Defame1297
adaa978d20
Why: the always-on governance.md told agents to read docs/ai-constitution.md when a decision is not covered, a path that exists only in this repo, so the fallback failed in every other project. (Simplification audit finding 27, second defect.) Implementation Notes: - Move docs/ai-constitution.md to core/ai-constitution.md; the existing core deploy step now ships it to ~/.claude/core/. - governance.md line 4 and line 73 name ~/.claude/core/ai-constitution.md; the HUMANS.md and CONTROLS.md pointers now say they live in the holocron repo. - Repoint path-qualified citations in AGENTS.md, architecture.md, skill-implementation-workflow.md and CONTROLS.md. The vendored write-skill example and the audit's historical notes are left as records. - The docs/wiki gitlink is not bumped here; the wiki commit awaits push. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
107 lines
8.4 KiB
Markdown
107 lines
8.4 KiB
Markdown
# Deterministic Controls
|
|
|
|
Applies to: any environment, repository, or pipeline where AI tools are used.
|
|
Full governance context: `core/ai-constitution.md` — principles these controls enforce.
|
|
Human practitioner rules: `docs/wiki/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.
|
|
|
|
---
|
|
|
|
## Day-One: Environment Setup
|
|
|
|
Controls configured once per development environment. Any machine or environment used for AI-assisted work must have these in place before work begins.
|
|
|
|
---
|
|
|
|
**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.
|
|
*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.
|
|
*Enforces: Constitution §1 — governance rules must reach the agents operating in context.*
|
|
|
|
---
|
|
|
|
## Per-Repo: Repository Controls
|
|
|
|
Controls configured for each repository. Apply these when creating a new repo or when adding AI-assisted workflows to an existing one.
|
|
|
|
---
|
|
|
|
**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.
|
|
*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.
|
|
*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.
|
|
*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.
|
|
*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.
|
|
*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.
|
|
*Enforces: Constitution §5 — production requires a human checkpoint; this is a hard rule.*
|
|
|
|
---
|
|
|
|
## Ongoing: Verification and Review
|
|
|
|
Controls that must be verified periodically. These cannot be configured once and forgotten — they degrade, drift, and become stale. Assign a cadence and an owner.
|
|
|
|
---
|
|
|
|
**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)*
|
|
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)*
|
|
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)*
|
|
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)*
|
|
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)*
|
|
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)*
|
|
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.
|
|
|
|
---
|
|
|
|
## What This File Does Not Govern
|
|
|
|
The specific tooling used to implement each control is the implementer's choice — tool selection is out of scope here. What is in scope is the requirement: what the control must detect, gate, or produce. Select tools that meet the requirement; replace them when better options exist without needing to update this file.
|
|
|
|
Human judgment decisions — which AI model to use, whether a specific output is acceptable, how to classify ambiguous data — are governed by `docs/wiki/HUMANS.md`. Agent judgment decisions are governed by `core/instructions/governance.md`. This file governs only what can be enforced without judgment.
|
|
|
|
---
|
|
|
|
*Derived from AI Constitution v1.1 — May 2026.*
|
|
*Counterpart to: `docs/wiki/HUMANS.md` | `core/instructions/governance.md` | Full context: `core/ai-constitution.md`*
|