Defame1297/holocron
0
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

chore: migrate legacy pre-commit hook to .pre-commit-config.yaml

Browse Source 
Replaces shell script (.git/hooks/pre-commit.legacy) with ecosystem-managed pre-commit framework:
- gitleaks/gitleaks: secret scanning
- jumanjihouse/pre-commit-hooks: shellcheck wrapper
- pre-commit/pre-commit-hooks: JSON/YAML validation, end-of-file-fixer, trailing-whitespace
- local hooks: SKILL.md frontmatter validation

Uses pinned versions for reproducibility across environments. Includes auto-fixes from hook runs (formatting, trailing whitespace, JSON beautification).

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
This commit is contained in:
Defame1297
2026-06-27 18:54:37 +00:00
parent 3e52636da6
commit d98d0dae18
39 changed files with 1077 additions and 235 deletions
Download Patch File Download Diff File Expand all files Collapse all files

62
docs/research/governance_principles/CONTROLS.md
View File

@@ -1,8 +1,8 @@
# Deterministic Controls
Applies to: any environment, repository, or pipeline where AI tools are used.
Full governance context: `docs/ai-constitution.md` — principles these controls enforce.
Human practitioner rules: `docs/HUMANS.md` | Agent instructions: `core/instructions/governance.md`
Applies to: any environment, repository, or pipeline where AI tools are used.
Full governance context: `docs/ai-constitution.md` — principles these controls enforce.
Human practitioner rules: `docs/HUMANS.md` | Agent instructions: `core/instructions/governance.md`
This file specifies the enforcement layer: controls that run mechanically, regardless of human or agent intention.
**Why this file exists:** Agent instructions and human practitioner rules are probabilistic — they depend on attention and intent. This layer removes that dependency. A control that runs automatically in CI enforces a principle more reliably than any instruction in any file. Where a principle can be enforced deterministically, it must be.
@@ -15,16 +15,16 @@ Controls configured once per development environment. Any machine or environment
---
**Secret scanning in pre-commit**
A pre-commit hook that detects secrets, credentials, API keys, and high-entropy strings must be active in every development environment. It must run before any commit reaches version control — not as a best-effort scan, but as a blocking gate.
**Secret scanning in pre-commit**
A pre-commit hook that detects secrets, credentials, API keys, and high-entropy strings must be active in every development environment. It must run before any commit reaches version control — not as a best-effort scan, but as a blocking gate.
*Enforces: Constitution §2 — secrets never enter AI context or version control.*
**AI tool data tier verification**
AI tools used for Internal, Confidential, or Restricted data must be configured to use enterprise-tier endpoints. Verify contractual data-not-trained commitments are in place before connecting any non-Public data source to an AI tool. This is a one-time verification per tool, repeated when tools or plans change.
**AI tool data tier verification**
AI tools used for Internal, Confidential, or Restricted data must be configured to use enterprise-tier endpoints. Verify contractual data-not-trained commitments are in place before connecting any non-Public data source to an AI tool. This is a one-time verification per tool, repeated when tools or plans change.
*Enforces: Constitution §3 — consumer and free-tier products handle Public data only.*
**Governance instruction file present and adapter files configured**
Every repository or project context in active use must have an agent governance instruction file present and accessible (in this repo: `core/instructions/governance.md`, deployed globally via `@import`), with tool-specific adapter files (CLAUDE.md, copilot-instructions.md, etc.) referencing it. Verify this is in place before starting AI-assisted work in any new repo.
**Governance instruction file present and adapter files configured**
Every repository or project context in active use must have an agent governance instruction file present and accessible (in this repo: `core/instructions/governance.md`, deployed globally via `@import`), with tool-specific adapter files (CLAUDE.md, copilot-instructions.md, etc.) referencing it. Verify this is in place before starting AI-assisted work in any new repo.
*Enforces: Constitution §1 — governance rules must reach the agents operating in context.*
---
@@ -35,32 +35,32 @@ Controls configured for each repository. Apply these when creating a new repo or
---
**Secret scanning in CI**
Every repository CI pipeline must include a secret scanning step that fails the build on detected credentials, tokens, or high-entropy strings. Pre-commit hooks can be bypassed; CI cannot. Both layers are required.
**Secret scanning in CI**
Every repository CI pipeline must include a secret scanning step that fails the build on detected credentials, tokens, or high-entropy strings. Pre-commit hooks can be bypassed; CI cannot. Both layers are required.
*Enforces: Constitution §2 — architectural constraint, not a reminder.*
**Dependency and security scanning**
Every repository CI pipeline must include dependency vulnerability scanning covering known CVEs and supply chain risks. For repositories using AI-generated code, the scan must be configured to cover AI-assisted contributions — not just declared dependencies.
**Dependency and security scanning**
Every repository CI pipeline must include dependency vulnerability scanning covering known CVEs and supply chain risks. For repositories using AI-generated code, the scan must be configured to cover AI-assisted contributions — not just declared dependencies.
*Enforces: Constitution §2 — AI-generated code is untrusted by default; OWASP LLM supply chain risks.*
**Licence scanning**
Every repository CI pipeline must include a licence scanning step that detects copyleft-licensed fragments (GPL, AGPL, LGPL) in committed code. Manifest-based scanners alone are insufficient for AI-assisted contributions — the scan must cover code content, not just declared dependencies.
**Licence scanning**
Every repository CI pipeline must include a licence scanning step that detects copyleft-licensed fragments (GPL, AGPL, LGPL) in committed code. Manifest-based scanners alone are insufficient for AI-assisted contributions — the scan must cover code content, not just declared dependencies.
*Enforces: Constitution §8 — copyleft fragments can appear in AI output without headers.*
**AI agent permission scoping**
Any AI agent granted access to this repository must be configured with the minimum permissions required for its specific task. Broad-scope tokens granting read/write access to the full repository or infrastructure are prohibited for AI agents. Token scope must be documented and reviewed when the agent's task scope changes.
**AI agent permission scoping**
Any AI agent granted access to this repository must be configured with the minimum permissions required for its specific task. Broad-scope tokens granting read/write access to the full repository or infrastructure are prohibited for AI agents. Token scope must be documented and reviewed when the agent's task scope changes.
*Enforces: Constitution §2 — least-privilege for all AI agents.*
**Prompt version control**
Any prompt used in an automated or recurring AI pipeline — not ad-hoc sessions — must be committed to version control with a change history. Prompts not under version control are not auditable. A prompt that runs in production without version control is uncontrolled code.
**Prompt version control**
Any prompt used in an automated or recurring AI pipeline — not ad-hoc sessions — must be committed to version control with a change history. Prompts not under version control are not auditable. A prompt that runs in production without version control is uncontrolled code.
*Enforces: Constitution §7 — prompts are code; unversioned prompts are unauditable.*
**Audit logging for agentic workflows**
Any agentic workflow that modifies state — files, infrastructure, configuration, deployments — must produce a log capturing: prompt input (or reference to versioned prompt), model version, action taken, outcome, timestamp. The log must be tamper-evident and human-readable. Isolated timestamps without action context are not sufficient.
**Audit logging for agentic workflows**
Any agentic workflow that modifies state — files, infrastructure, configuration, deployments — must produce a log capturing: prompt input (or reference to versioned prompt), model version, action taken, outcome, timestamp. The log must be tamper-evident and human-readable. Isolated timestamps without action context are not sufficient.
*Enforces: Constitution §7 — every agent action producing an effect must generate a trace.*
**Human approval gate for production changes**
Any CI/CD pipeline that applies changes to production systems, security configuration, or infrastructure must include an explicit human approval step before the change is applied. Automated merge-and-deploy pipelines for AI-generated changes are prohibited without this gate. The gate must be implemented in the pipeline, not left to individual judgment.
**Human approval gate for production changes**
Any CI/CD pipeline that applies changes to production systems, security configuration, or infrastructure must include an explicit human approval step before the change is applied. Automated merge-and-deploy pipelines for AI-generated changes are prohibited without this gate. The gate must be implemented in the pipeline, not left to individual judgment.
*Enforces: Constitution §5 — production requires a human checkpoint; this is a hard rule.*
---
@@ -71,25 +71,25 @@ Controls that must be verified periodically. These cannot be configured once and
---
**Pre-commit hook integrity** *(per developer, monthly)*
**Pre-commit hook integrity** *(per developer, monthly)*
Verify pre-commit hooks are installed, active, and current in every active development environment. Hooks can be bypassed, uninstalled by tooling updates, or silently disabled. A hook that is not tested is not a control.
**CI scan results review** *(per repository, per release or sprint)*
**CI scan results review** *(per repository, per release or sprint)*
Review secret, licence, and dependency scan outputs — not just pass/fail status. A scan that passes because exceptions have accumulated is not a clean scan. Review exception lists and remove expired or unjustified exceptions.
**AI agent permission audit** *(per repository, quarterly)*
**AI agent permission audit** *(per repository, quarterly)*
Verify that AI agent tokens and permissions remain scoped to current task requirements. Agent permissions granted for a specific task tend to persist after the task ends. Revoke and re-scope on a defined cadence.
**Audit log review** *(per agentic workflow, per sprint or monthly)*
**Audit log review** *(per agentic workflow, per sprint or monthly)*
Review AI agent action logs for unexpected scope, anomalous patterns, or actions that should have triggered a human approval gate but did not. Logging without review is record-keeping, not oversight.
**AI deployment value review** *(per deployment, time-bounded)*
**AI deployment value review** *(per deployment, time-bounded)*
Every AI integration must be reviewed against the success criteria defined before deployment. Integrations that have not delivered measurable value within the defined review period must be redesigned or discontinued. Schedule this review at deployment time, not retrospectively.
**Provider terms and data handling review** *(annually, or when providers update terms)*
**Provider terms and data handling review** *(annually, or when providers update terms)*
Verify that AI provider terms of service, data handling commitments, and IP provisions remain consistent with what was agreed at onboarding. Provider terms change. An enterprise commitment made in 2024 may not have the same scope in 2026. Re-verify; do not assume continuity.
**Constitution and controls alignment review** *(annually, or after any significant AI incident)*
**Constitution and controls alignment review** *(annually, or after any significant AI incident)*
Verify that the controls specified here remain aligned with the current version of the AI Constitution. When the constitution is updated, this file must be reviewed and updated to match. A control specification that drifts from the constitution it enforces is not a control.
---
@@ -102,5 +102,5 @@ Human judgment decisions — which AI model to use, whether a specific output is
---
*Derived from AI Constitution v1.1 — May 2026.*
*Derived from AI Constitution v1.1 — May 2026.*
*Counterpart to: `docs/HUMANS.md` | `core/instructions/governance.md` | Full context: `docs/ai-constitution.md`*