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

docs: deploy the ai-constitution with core so the governance pointer resolves

Browse Source 
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>
This commit is contained in:
Defame1297
2026-09-16 12:56:49 +00:00
parent a840f3fe04
commit adaa978d20
7 changed files with 11 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

238
core/ai-constitution.md Normal file
View File

@@ -0,0 +1,238 @@
# AI Constitution
**Version:** 1.1 (corrections from deep research pass applied May 2026)
**Scope:** All AI-assisted software development, deployment, and infrastructure management
**Audience:** Humans and AI agents operating in this context
**Inheritance:** Solo-authored; designed to be inherited by future collaborators and AI agents without requiring the author present
**Derivation:** Derived from sourced research across ten governance topics. Principles are evidence-based, not aspirational.
**Operative agent instructions:** See `core/instructions/governance.md` — the concise, agent-actionable distillation of this document for global context use.
---
## 1. Accountability
**Accountability is non-transferable.**
Every AI-generated output that enters a system, codebase, or production environment is owned by the human who accepted it. AI assistance does not reduce or distribute responsibility. "The model produced it" is not a defence — legally, ethically, or operationally.
**Ethics commitments must be concrete and auditable.**
Any principle in this document that cannot be tested or verified is not a principle — it is a claim. If compliance cannot be demonstrated, the commitment does not exist.
---
## 2. Security
**Secrets must never enter AI context.**
Credentials, API keys, tokens, passwords, and certificates must not appear in prompts, context files, RAG pipelines, or any input to an AI system. This is an architectural constraint, not a reminder. Scan context before it reaches a model.
**Never use AI-generated secrets, passwords, or cryptographic material.**
LLM-generated passwords have demonstrably insufficient entropy and exhibit predictable patterns. Use cryptographically secure random sources for all credential generation.
**AI-generated code is untrusted by default.**
Review AI-generated code with more scrutiny than human-written code — specifically for hardcoded credentials, insecure patterns, and licence-encumbered fragments — before any commit.
**Apply least-privilege to all AI agents.**
Agents receive only the permissions required for their specific, current task. Long-lived, broad-scope tokens for AI agents are prohibited. Scope credentials tightly; rotate frequently.
**Apply OWASP LLM Top 10 and Agentic AI Top 10 as baseline security requirements.**
Prompt injection, supply chain risks, excessive agency, sensitive information disclosure, and system prompt leakage require explicit controls. Traditional AppSec frameworks do not cover these attack surfaces.
**AI pipelines must surface uncertainty; never treat confident AI output as accurate output.**
Chaining AI subsystems without propagating confidence levels creates compounding, invisible error. Uncertain outputs require human review before consequential action.
---
## 3. Data Protection & Classification
**Sending personal data to an AI system is data processing under GDPR.**
It requires a lawful basis, a defined purpose, and appropriate safeguards. This applies to prompts, RAG pipelines, and fine-tuning data equally. There is no "just testing" exemption.
**The context window is a data store. Classify it accordingly.**
Everything that enters an AI prompt is subject to the same classification obligations as any other data store. Apply the classification framework below.
### Data Classification for AI Systems
| Tier | Label | Description | AI Rule |
| ------| ------------------| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ----------------------------------------------------------------------------------------------------------------------------|
| 1 | **Public** | Publicly available data | No restrictions |
| 2 | **Internal** | Operational data, non-personal system data, anonymised logs | Enterprise AI tools only; not consumer/free-tier products |
| 3 | **Confidential** | Proprietary source code, system architecture, IP, identifiable personal data | Enterprise AI with explicit data-not-used-for-training contractual commitment; GDPR legal basis required for personal data |
| 4 | **Restricted** | GDPR Article 9 special categories (health, biometrics, ethnicity, religion, sexual orientation, political views), credentials, regulated financial data, data under professional secrecy | Never enters any AI context. Hard architectural prohibition. |
**Consumer and free-tier AI products are incompatible with processing organisational or personal data.**
Enterprise contracts with explicit data-not-used-for-training commitments are the minimum bar. Verify per provider; do not assume.
**Data minimisation applies to AI prompts.**
Send only what is necessary for the task. Anonymise or pseudonymise personal data before AI input wherever feasible.
**Personal data must not enter AI fine-tuning or RAG pipelines without a GDPR legal basis and a completed DPIA.**
Right-to-erasure obligations under Article 17 cannot be fulfilled once data is encoded in model weights. This decision is irreversible.
---
## 4. Behaviour & Sycophancy
**Sycophancy is a first-class reliability and ethical risk.**
AI systems trained via RLHF systematically prioritise approval over accuracy. This is the most tractable cause of hallucination and must be explicitly designed against — through prompting standards, model selection, and evaluation criteria.
**Never interpret AI agreement as AI accuracy.**
Models change correct answers to wrong ones under user pressure in a majority of observed cases, then persist in the wrong answer. Challenge AI outputs before trusting them; agreement is not confirmation.
**In high-stakes contexts, never prompt for brevity at the expense of accuracy.**
Conciseness instructions demonstrably degrade factual reliability. Where accuracy matters, prompt for accuracy.
**Cross-validate consequential AI outputs.**
Any AI-generated output that informs a significant decision — architecture, security configuration, deployment, legal or financial — must be validated against an independent source or a second model before acting on it.
**Select models partly on sycophancy resistance.**
Model selection for professional use must include evaluation of sycophancy behaviour alongside capability benchmarks. Use a portfolio of benchmarks (MASK, SYCON-Bench, SycEval) — rankings flip across evaluations and no single benchmark is reliable. Run your own deployment-stage test for your specific task context; do not rely on vendor or single-study claims about which model family is most resistant.
**In domains where diverse perspectives matter, prompt explicitly for multiple viewpoints and dissenting positions.**
AI systems are trained in ways that systematically suppress annotator disagreements, producing outputs weighted toward dominant viewpoints at the expense of minority or dissenting positions (arxiv 2505.07772). A single AI output on a contested, values-laden, or socially complex question is not a neutral summary — it is a majority-weighted perspective. In architecture decisions, risk assessments, ethical questions, and any domain with genuine expert disagreement, prompt for counterarguments and dissenting views explicitly; do not treat the first output as balanced.
**In domains where diverse perspectives matter, prompt explicitly for dissent.**
AI systems trained to suppress annotator disagreement produce outputs that systematically underrepresent non-dominant viewpoints (arxiv 2505.07772). In architecture decisions, ethics reviews, risk assessments, and anything affecting underrepresented groups — explicitly prompt for minority positions, dissenting analysis, and counterarguments. Cross-validation against independent sources partially compensates for homogenisation; active prompting for dissent addresses it more directly.
---
## 5. Human Oversight & Automation Boundaries
**Human oversight must be genuine, not symbolic.**
Assigning a reviewer does not constitute oversight unless they have the information, time, agency, and intent to evaluate the output meaningfully. Review processes must make genuine evaluation possible.
**Production systems require a human checkpoint before any AI-initiated change.**
This is a hard rule. No architecture change, infrastructure modification, security configuration, or production deployment may be applied by an AI agent without explicit human review and approval of the specific change.
**Humans must own the code — not just approve it.**
The required comprehension standard (ACM/IEEE-CS Software Engineering Code of Ethics) is: intent-level understanding of what the code does and why; architectural understanding of how it fits the system; and verifiable behaviour via tests or traceable reasoning. Line-by-line comprehension of every implementation detail is not required and not the professional standard. What is required: a developer cannot commit AI-generated code they cannot explain, modify at the intent-and-architecture level, or verify against defined behaviour — with or without AI assistance for the verification step itself.
**Limit AI output volume to what reviewers can genuinely evaluate.**
When AI-generated change throughput exceeds human verification capacity, approvals become rubber-stamps. Output rates must be managed to preserve the possibility of genuine review.
**Distinguish HITL from HOTL deliberately.**
Human-in-the-loop (HITL) pauses before consequential action. Human-on-the-loop (HOTL) monitors after the fact. HITL is required for irreversible or high-stakes actions. HOTL is acceptable for low-stakes, bounded, reversible actions. The distinction must be explicit and documented.
**AI assistance must augment human capability, not replace it.**
Over-reliance on AI for tasks that require and develop critical skills is a governance risk, not just a quality risk. Kosmyna et al. (2025) found measurable neural disengagement in AI-assisted work; domain evidence shows skill atrophy when AI support is removed; ACM FAccT 2026 identifies cognitive offloading as a systematically overlooked safety risk. When AI takes over a capability entirely, the human's ability to catch AI errors in that domain is also lost. Governance must include periodic assessment of whether AI-assisted roles retain the baseline capability required to operate, audit, and override the AI without it.
**AI assistance must augment human capability, not replace it.**
Over-reliance on AI for tasks that require critical thinking, system comprehension, or skilled judgement creates cognitive dependency that degrades organisational resilience over time (Kosmyna et al. 2025; Chalkidis & Søgaard, ACM FAccT 2026). Governance must include mechanisms to detect skill atrophy in AI-assisted roles — periodic AI-free practice, comprehension checks, and capability baselines that do not depend on AI availability.
---
## 6. Sustainability & Societal Cost
**Governance is an obligation to those who bear the costs, not just those who use the tools.**
AI's primary costs — environmental, epistemic, and distributional — fall predominantly on people who are not its users: communities bearing grid and water stress from data centres, workers displaced faster than they can upskill, and societies absorbing the epistemic effects of large-scale AI-generated content at scale (IEA Energy and AI 2025; de Vries-Gao, ScienceDirect 2025; Chalkidis & Søgaard, ACM FAccT 2026). Those who benefit from AI use have an obligation to those who bear its costs — whether or not those costs are currently priced or legally required to be accounted for.
**Unmeasured AI usage is unjustifiable.**
Every AI integration must have defined success metrics before deployment. The environmental and societal costs are real and externally borne; they cannot be justified without evidence of value delivered. 42% of enterprises have abandoned most AI initiatives; only 5% of GenAI pilots show measurable P&L impact (S&P Global n=1,006; MIT NANDA lab). If value cannot be articulated, the costs on others cannot be defended.
**Match model capability to task complexity.**
Using frontier models for tasks a smaller model handles is not just economically wasteful — it imposes unnecessary environmental and infrastructure costs on others. Model selection is a governance decision with externalities.
**Token efficiency is a sustainability metric, not just a cost metric.**
Tokens per unit of value delivered simultaneously tracks cost, carbon intensity, and whether AI is doing genuine work. Per-task energy use is falling rapidly; aggregate consumption rises faster because adoption scale outpaces efficiency gains — the Jevons paradox applied to AI (IEA 2025/2026).
**Apply the J-Curve honestly.**
AI deployments not yet delivering measurable value must be time-bounded. DORA 2025 confirms the J-Curve pattern: short-term costs precede long-term gains, but the curve must actually turn. If a deployment has not reached value delivery within a defined review period, it must be redesigned or discontinued.
**Treat provider sustainability claims sceptically.**
Corporate environmental disclosure does not currently distinguish AI from non-AI workloads; independent verification of AI-specific footprint is not possible without regulatory mandates. Source claims only from independently verifiable data (IEA, peer-reviewed studies).
---
## 7. Transparency & Auditability
**Every AI agent action that produces an effect must generate a tamper-evident, human-readable trace.**
Minimum content: prompt input, model version, output, tool invocations, actor identity, timestamp. Isolated timestamps are not sufficient.
**Prompts are code and must be versioned accordingly.**
Every prompt used in a production AI system must be under version control with change logs recording what changed, why, and who approved the change. Unversioned prompts are unauditable prompts.
**AI involvement must be disclosed to anyone affected by its outputs.**
This is an ethical obligation regardless of jurisdiction. Under the EU AI Act (post-Omnibus May 2026 agreement): Article 50 transparency obligations apply from **December 2, 2026**, and only to providers of certain AI system types (chatbots, deepfake generators, high-risk systems) — not to deployers using coding assistants internally. Developers using tools like Copilot, Claude Code, or Cursor currently face only **Article 4 (AI literacy)** obligations, which have been live since February 2025. Consult legal counsel for jurisdiction-specific obligations.
**Logging must not create new data protection exposures.**
PII in logs must be redacted at ingestion. Log retention periods must align with data protection obligations — retain only what is necessary for the defined audit purpose.
---
## 8. Intellectual Property
**AI-generated code without meaningful human authorship is unprotectable and simultaneously liable.**
It may infringe third-party IP while being ineligible for copyright protection itself. Substantial human review, editing, and integration is required for both IP protection and licence compliance.
**Run licence-scanning on all AI-generated code before committing.**
Copyleft-licensed fragments can appear in AI output without licence headers. Manifest-based scanning tools do not catch AI-generated code. Dedicated licence scanning must cover AI-assisted contributions explicitly.
**Review AI provider terms of service specifically for IP provisions.**
Rights to AI-generated outputs vary significantly by provider and tier. Enterprise agreements must be reviewed for IP indemnification, output ownership clauses, and restrictions before using AI output in commercial software.
**Document human contributions to AI-assisted code.**
Version control history, code review records, and prompt logs together constitute evidence of human authorship. Where IP protection matters, the human contribution must be substantive and documentable.
---
## 9. Incident Response
**Extend existing IR frameworks for AI-specific failure modes; do not replace them.**
NIST SP 800-61 and ISO/IEC 27035 remain the required foundation. Extend with specific playbooks covering: prompt injection attacks, agentic scope violations, AI-caused data exposure, and auditability failures. Each requires a distinct detection and response procedure.
**Design for error containment, not error prevention.**
AI systems will produce erroneous outputs. The primary design obligation is to prevent errors from propagating to consequential, irreversible action — through permission envelopes, scope constraints, and HITL gates.
**AI may diagnose autonomously; production remediation requires human approval.**
AI-assisted detection and root cause analysis can run without human intervention. Applying remediation to production systems — rollback, configuration change, scaling decision — requires explicit human approval unless the action is pre-defined, bounded, and reversible.
**Post-mortems must cover AI and automation failures explicitly.**
Every AI-involved incident must be post-mortemed with the same rigour as service outages. The post-mortem must address: what instructions the agent operated under, what decision it made, what the failure mode was, and what governance change prevents recurrence.
**Regulatory notification obligations apply regardless of whether AI caused the incident.**
GDPR Article 33/34 and EU AI Act incident reporting obligations are not suspended because an AI system caused or contributed to the incident. The notification timeline and threshold are unchanged.
**Test incident response for AI-specific scenarios proactively.**
Standard chaos engineering and resilience drills must include AI-specific scenarios: prompt injection, agent scope violation, agentic hallucination triggering a downstream action. Untested playbooks do not work under pressure.
---
## 10. Deterministic Execution
**Prefer deterministic code over repeated AI inference for repeatable, well-specified tasks.**
If a task has a correct answer that does not depend on context or judgement, encode it as a script. Use AI once to generate and review the script; run the script in production. Repeated AI inference for a deterministic task adds cost, unreliability, and attack surface without benefit.
**Use AI inference at execution time only for tasks that are genuinely ambiguous or context-dependent.**
Applying probabilistic AI to deterministic problems is a documented anti-pattern. If you can draw a complete flowchart of the process with no "it depends" branches, the task does not need AI at execution time.
**AI-generated scripts are first drafts, not finished artefacts.**
Review AI-generated code for correctness, missing dependencies, and performance before production deployment. EffiBench (2024) found measurable execution overhead in unreviewed AI-generated code; human review substantially closes that gap. The review step is not optional.
**Deterministic enforcement must sit outside the AI, not inside it.**
Linters, CI gates, unit tests, and schema validation must run on AI-generated code as hard constraints. AI instructions alone are probabilistic and cannot serve as enforcement mechanisms.
**The script is the governed artefact; version and review it accordingly.**
When a repeatable task changes enough to invalidate the existing script, that is the trigger to re-engage AI — not a reason to revert to repeated inference. The script lives in version control, is human-reviewable, and is the authoritative record of how the task is performed.
---
## Governance
**This document is a living artifact.**
It must be reviewed after any significant AI incident, at each major addition of AI tooling, and at minimum annually. Research that contradicts current principles must be incorporated.
**Principles without enforcement are claims.**
Each principle above must map to at least one verifiable behaviour, automated check, or documented review process. Where that mapping does not exist, the principle is aspirational — label it as such and set a deadline for operationalisation. `core/instructions/governance.md` provides the agent-actionable distillation of this document; deterministic tooling (linters, CI gates, secret scanners, licence scanners) provides the enforcement layer that agent instructions alone cannot.
*Example mapping — Section 2, "Secrets must never enter AI context":*
- Agent instruction: `core/instructions/governance.md` hard prohibition with positive alternative (reference env var names, not values)
- Pre-commit gate: `git-secrets` or `trufflehog` scanning for credential patterns before any commit reaches version control
- CI gate: secret scanning step in pipeline rejects commits containing high-entropy strings
- Review checklist item: confirm no secrets in prompt logs before any session transcript is stored or shared
**This constitution does not replace legal advice.**
It operationalises current regulatory and research consensus for practitioners. For jurisdiction-specific obligations, regulatory filings, or IP disputes, consult qualified legal counsel.
---
*Derived from: AI Governance Research Session (May 2026).*
*Research documentation: `docs/research/governance_principles/ai-governance-research.md` | Open challenges: `docs/research/governance_principles/ai-governance-research-challenges.md`*
*Operative files: `core/instructions/governance.md` (agent instructions) | `docs/wiki/HUMANS.md` (human practitioner rules) | `docs/research/governance_principles/CONTROLS.md` (deterministic enforcement)*

8
core/instructions/governance.md
View File

@@ -1,7 +1,7 @@
# Agent Instructions
Applies to: all AI agents and assistants in this context, at all times.
Full governance context: `docs/ai-constitution.md` — read it when making decisions not covered here.
Full governance context: `~/.claude/core/ai-constitution.md` — read it when making decisions not covered here.
This file is the operative subset: what you, as an agent, can act on in the moment.
---
@@ -70,13 +70,13 @@ When asked to perform a well-defined, repeatable task — file processing, deplo
## What This File Does Not Govern
Human process decisions are outside agent scope: oversight checkpoints, human approval gates, post-mortems, regulatory notifications, IP licence scanning, and sustainability measurement. These are defined in `docs/ai-constitution.md` and executed by humans following `docs/wiki/HUMANS.md`.
Human process decisions are outside agent scope: oversight checkpoints, human approval gates, post-mortems, regulatory notifications, IP licence scanning, and sustainability measurement. These are defined in `~/.claude/core/ai-constitution.md` and executed by humans following the holocron repo's `docs/wiki/HUMANS.md`.
The deterministic enforcement layer — pre-commit hooks, CI gates, scanner configuration, audit logging infrastructure, and AI agent permission scoping — is specified in `docs/research/governance_principles/CONTROLS.md` and implemented by humans. Agent instructions alone cannot enforce what deterministic tooling must enforce.
The deterministic enforcement layer — pre-commit hooks, CI gates, scanner configuration, audit logging infrastructure, and AI agent permission scoping — is specified in the holocron repo's `docs/research/governance_principles/CONTROLS.md` and implemented by humans. Agent instructions alone cannot enforce what deterministic tooling must enforce.
---
*Derived from AI Constitution v1.1 — May 2026. Update this file when the constitution is updated.*
*Compatible with: governance.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/rules/*.mdc*
*One source of truth. Do not copy-paste into tool-specific files — reference this file from thin adapters.*
*Counterparts: `docs/wiki/HUMANS.md` (human practitioner rules) | `docs/research/governance_principles/CONTROLS.md` (deterministic enforcement)*
*Counterparts, in the holocron repo: `docs/wiki/HUMANS.md` (human practitioner rules) | `docs/research/governance_principles/CONTROLS.md` (deterministic enforcement)*