Compliance & Governance¶

Compliance & Governance for Hillstar Orchestrator.

Enforce workflow-driven development by gating git commits behind verified Hillstar workflow executions.

class governance.GovernanceEnforcer[source]¶

Bases: object

Enforce workflow-driven development before git commits.

__init__(hillstar_dir='.hillstar', policy=None)[source]¶

Parameters:

hillstar_dir (str)
policy (GovernancePolicy | None)

check(dev_mode=False)[source]¶

Check whether the current state is compliant for a git commit.

Parameters:: dev_mode (bool) – If True (or HILLSTAR_DEV_MODE=1 in env), skip governance check.
Returns:: compliant=True means commit is allowed.
Return type:: (compliant, reason)

write_marker(workflow_id, workflow_file, summary='')[source]¶

Write commit_ready marker after successful workflow execution.

Parameters:

workflow_id (str)
workflow_file (str)
summary (str)

Return type:

None

clear_marker()[source]¶

Clear the commit_ready marker (e.g. after commit completes).

Return type:: None

status()[source]¶

Return full status dictionary for display.

Return type:: dict

class governance.HookManager[source]¶

Bases: object

Manage git hooks for Hillstar governance enforcement.

__init__(project_dir='.')[source]¶

Parameters:: project_dir (str)

is_git_repo()[source]¶

Check if project_dir is a git repository.

Return type:: bool

is_installed()[source]¶

Check if the Hillstar pre-commit hook is installed.

Return type:: bool

install(force=False)[source]¶

Install the pre-commit hook.

Parameters:: force (bool) – Overwrite existing hook without prompting.
Returns:: (success, message)
Return type:: tuple[bool, str]

uninstall()[source]¶

Remove the Hillstar pre-commit hook.

Return type:: tuple[bool, str]

status()[source]¶

Return hook installation status.

Return type:: dict

class governance.GovernancePolicy[source]¶

Bases: object

Policy configuration for workflow enforcement.

max_age_seconds: int = 3600¶

allow_force_override: bool = True¶

require_workflow_id: bool = True¶

blocked_patterns: list[str]¶

exempt_patterns: list[str]¶

classmethod load(hillstar_dir)[source]¶

Load policy from .hillstar/governance_policy.json, or return defaults.

Parameters:: hillstar_dir (str)
Return type:: GovernancePolicy

save(hillstar_dir)[source]¶

Persist policy to .hillstar/governance_policy.json.

Parameters:: hillstar_dir (str)
Return type:: None

__init__(max_age_seconds=3600, allow_force_override=True, require_workflow_id=True, blocked_patterns=<factory>, exempt_patterns=<factory>)¶

Parameters:

max_age_seconds (int)
allow_force_override (bool)
require_workflow_id (bool)
blocked_patterns (list[str])
exempt_patterns (list[str])

Return type:

None

governance.verify_hillstar_compliance()[source]¶

Verify Hillstar compliance at import time.

Return type:: None

governance.enforcer¶

Script¶

enforcer.py

Path¶

python/hillstar/governance/enforcer.py

Purpose¶

Core governance enforcement: validate that a Hillstar workflow was executed before allowing a git commit to proceed.

Reads .hillstar/commit_ready.json written by runner.py on successful execution. Checks age, workflow ID, and policy compliance.

Inputs¶

hillstar_dir: path to .hillstar directory (default: .hillstar in cwd)
policy: GovernancePolicy instance

Outputs¶

(compliant: bool, reason: str)

Assumptions¶

runner.py writes commit_ready.json on successful workflow completion
.hillstar/ directory exists in the project root

Parameters¶

See GovernancePolicy

Failure Modes¶

commit_ready.json missing: non-compliant
commit_ready.json stale (age > max_age_seconds): non-compliant
HILLSTAR_FORCE_COMMIT=1 env var: override allowed if policy permits

Author: Julen Gamboa <julen.gamboa.ds@gmail.com>

Created¶

2026-02-08

Last Edited¶

2026-02-08

class governance.enforcer.GovernanceEnforcer[source]¶

Bases: object

Enforce workflow-driven development before git commits.

__init__(hillstar_dir='.hillstar', policy=None)[source]¶

Parameters:

hillstar_dir (str)
policy (GovernancePolicy | None)

check(dev_mode=False)[source]¶

Check whether the current state is compliant for a git commit.

Parameters:: dev_mode (bool) – If True (or HILLSTAR_DEV_MODE=1 in env), skip governance check.
Returns:: compliant=True means commit is allowed.
Return type:: (compliant, reason)

write_marker(workflow_id, workflow_file, summary='')[source]¶

Write commit_ready marker after successful workflow execution.

Parameters:

workflow_id (str)
workflow_file (str)
summary (str)

Return type:

None

clear_marker()[source]¶

Clear the commit_ready marker (e.g. after commit completes).

Return type:: None

status()[source]¶

Return full status dictionary for display.

Return type:: dict

governance.compliance¶

Script¶

compliance.py

Path¶

python/hillstar/governance/compliance.py

Purpose¶

Compliance enforcement module for Hillstar.

Enforce Hillstar’s compliance architecture and prevent prohibited modifications. This module verifies that only API-based orchestration is used, preventing CLI/SDK access that would violate provider terms of service.

Providers Covered¶

Anthropic (Claude)
Mistral AI (Le Chat)
OpenAI (GPT, Codex)
Google (Vertex AI, Gemini)
Amazon (Bedrock)
Microsoft (Azure AI)
Meta (Llama)
Cohere
Ollama

Compliance Rules¶

API-only authentication for cloud providers
No CLI/SDK access methods
No mixing of access patterns
Proper provider attribution
User responsibility documentation

Author: Julen Gamboa <julen.gamboa.ds@gmail.com>

Created¶

2026-02-14

Last Edited¶

2026-02-17

exception governance.compliance.ComplianceError[source]¶

Bases: Exception

Raised when compliance violations are detected.

class governance.compliance.ComplianceEnforcer[source]¶

Bases: object

Enforce Hillstar’s compliance architecture.

PROTECTED_PROVIDERS = {'amazon': {'name': 'Amazon Bedrock', 'prohibited_attributes': ['console_session', 'cli_credentials', 'manual_client'], 'prohibited_methods': ['bedrock_cli', 'console_access', 'sdk_manual', 'pro_mode'], 'tos_violation': "Violates AWS's IAM requirements"}, 'anthropic': {'name': 'Anthropic', 'prohibited_attributes': ['cli_mode', 'pro_subscription', 'sdk_client'], 'prohibited_methods': ['use_cli', 'claude_pro', 'sdk_auth', 'manual_access'], 'tos_violation': "Violates Anthropic's automation restrictions"}, 'cohere': {'name': 'Cohere', 'prohibited_attributes': ['console_client', 'cli_credentials', 'pro_session'], 'prohibited_methods': ['cohere_cli', 'manual_access', 'sdk_pro', 'console_mode'], 'tos_violation': "Violates Cohere's API terms"}, 'google': {'name': 'Google', 'prohibited_attributes': ['console_client', 'pro_credentials', 'cli_mode'], 'prohibited_methods': ['vertex_cli', 'gemini_pro', 'sdk_console', 'manual_access'], 'tos_violation': "Violates Google Cloud's API requirements"}, 'meta': {'name': 'Meta Llama', 'prohibited_attributes': ['cli_session', 'direct_access', 'pro_credentials'], 'prohibited_methods': ['local_cli', 'manual_llama', 'sdk_direct', 'pro_access'], 'tos_violation': "Violates Llama's usage policies"}, 'microsoft': {'name': 'Microsoft Azure AI', 'prohibited_attributes': ['portal_session', 'cli_credentials', 'manual_mode'], 'prohibited_methods': ['azure_cli', 'portal_access', 'sdk_manual', 'pro_console'], 'tos_violation': "Violates Azure's enterprise requirements"}, 'mistral': {'name': 'Mistral AI', 'prohibited_attributes': ['le_chat_client', 'pro_credentials', 'cli_session'], 'prohibited_methods': ['use_le_chat', 'pro_access', 'chat_cli', 'manual_mode'], 'tos_violation': "Violates Mistral's Le Chat Pro terms"}, 'ollama': {'name': 'Ollama', 'prohibited_attributes': ['cli_mixed', 'pro_credentials'], 'prohibited_methods': ['ollama_cli_mix', 'pro_access', 'sdk_manual'], 'tos_violation': "Violates Ollama's local model terms"}, 'openai': {'name': 'OpenAI', 'prohibited_attributes': ['pro_session', 'codex_cli', 'plus_subscription'], 'prohibited_methods': ['use_codex_pro', 'chatgpt_plus', 'sdk_login', 'cli_access'], 'tos_violation': "Violates OpenAI's automation policies"}}¶

__init__()[source]¶

check_provider_class(provider_name, provider_class)[source]¶

Check a provider class for compliance violations.

Parameters:

provider_name (str)
provider_class (Any)

Return type:

bool

check_all_providers()[source]¶

Check all provider implementations for compliance.

Return type:: bool

check_model_selector()[source]¶

Check ModelSelector for compliance violations.

Return type:: bool

verify_compliance()[source]¶

Run all compliance checks.

Return type:: bool

get_violations()[source]¶

Get list of compliance violations.

Return type:: List[str]

print_compliance_report()[source]¶

Print compliance verification report.

Return type:: None

governance.compliance.verify_hillstar_compliance()[source]¶

Verify Hillstar compliance at import time.

Return type:: None

governance.policy¶

Script¶

policy.py

Path¶

python/hillstar/governance/policy.py

Purpose¶

Governance policy definitions: what constitutes a valid workflow execution for the purpose of gating git commits.

Inputs¶

None (configuration constants)

Outputs¶

GovernancePolicy dataclass

Assumptions¶

Policy is loaded from .hillstar/governance_policy.json if present, otherwise defaults apply.

Parameters¶

max_age_seconds: Maximum age of a commit_ready marker (default 3600 = 1 hour)
allow_force_override: Whether HILLSTAR_FORCE_COMMIT env var is respected
require_workflow_id: Whether a workflow ID must be present in the marker
blocked_patterns: File patterns that always require a workflow (e.g. *.py, *.json)
exempt_patterns: File patterns exempt from enforcement (e.g. *.md docs, logs)

Failure Modes¶

policy.json malformed: falls back to defaults with a warning

Author: Julen Gamboa <julen.gamboa.ds@gmail.com>

Created¶

2026-02-08

Last Edited¶

2026-02-08

class governance.policy.GovernancePolicy[source]¶

Bases: object

Policy configuration for workflow enforcement.

max_age_seconds: int = 3600¶

allow_force_override: bool = True¶

require_workflow_id: bool = True¶

blocked_patterns: list[str]¶

exempt_patterns: list[str]¶

classmethod load(hillstar_dir)[source]¶

Load policy from .hillstar/governance_policy.json, or return defaults.

Parameters:: hillstar_dir (str)
Return type:: GovernancePolicy

save(hillstar_dir)[source]¶

Persist policy to .hillstar/governance_policy.json.

Parameters:: hillstar_dir (str)
Return type:: None

__init__(max_age_seconds=3600, allow_force_override=True, require_workflow_id=True, blocked_patterns=<factory>, exempt_patterns=<factory>)¶

Parameters:

max_age_seconds (int)
allow_force_override (bool)
require_workflow_id (bool)
blocked_patterns (list[str])
exempt_patterns (list[str])

Return type:

None

governance.hooks¶

Script¶

hooks.py

Path¶

python/hillstar/governance/hooks.py

Purpose¶

Git hook management: install, remove, and verify pre-commit hooks that enforce Hillstar workflow execution before allowing commits.

Inputs¶

project_dir: path to the git repository root

Outputs¶

.git/hooks/pre-commit script that calls hillstar enforce check

Assumptions¶

Git repository exists at project_dir
hillstar CLI is on PATH

Parameters¶

project_dir: str

Failure Modes¶

.git/hooks/ does not exist: not a git repo
pre-commit hook already exists: prompts before overwriting

Author: Julen Gamboa <julen.gamboa.ds@gmail.com>

Created¶

2026-02-08

Last Edited¶

2026-02-08

class governance.hooks.HookManager[source]¶

Bases: object

Manage git hooks for Hillstar governance enforcement.

__init__(project_dir='.')[source]¶

Parameters:: project_dir (str)

is_git_repo()[source]¶

Check if project_dir is a git repository.

Return type:: bool

is_installed()[source]¶

Check if the Hillstar pre-commit hook is installed.

Return type:: bool

install(force=False)[source]¶

Install the pre-commit hook.

Parameters:: force (bool) – Overwrite existing hook without prompting.
Returns:: (success, message)
Return type:: tuple[bool, str]

uninstall()[source]¶

Remove the Hillstar pre-commit hook.

Return type:: tuple[bool, str]

status()[source]¶

Return hook installation status.

Return type:: dict

governance.project_init¶

Script¶

project_init.py

Path¶

python/hillstar/governance/project_init.py

Purpose¶

Initialize Hillstar project structure with recommended directory layout.

Inputs¶

project_path (str): Root directory of project to initialize

Outputs¶

Created .hillstar/ and workflows/ directories with subdirectories

Assumptions¶

Project directory exists and is writable

Parameters¶

project_path: Project root (defaults to current directory)

Failure Modes¶

No write permissions PermissionError
Invalid path FileNotFoundError

Author: Julen Gamboa <julen.gamboa.ds@gmail.com>

Created¶

2026-02-09

Last Edited¶

2026-02-17

governance.project_init.initialize_project_structure(project_path=None)[source]¶

Initialize recommended directory structure for Hillstar projects.

Creates: - .hillstar/ with subdirectories (traces, logs, audit, checkpoints, data_stores) - workflows/ with subdirectories (core, infrastructure)

Parameters:: project_path (str | None) – Project root directory (defaults to current directory)
Returns:: Dictionary with created directories and initialization status
Return type:: dict