AGENTS.md

@@ -45,7 +45,7 @@ Read these on demand:
 - `docs/spec/gates.md` — what each pre-commit and pre-push hook enforces and why; read when a gate fails or before changing hook config
 - `docs/spec/architecture.md` — directory structure, install pipeline, provider model
 - `docs/adr/` — architectural decisions; read before answering design questions or proposing structural changes
-- `docs/ai-constitution.md` — full governance evidence base; read when a governance decision needs justification
+- `core/ai-constitution.md` — full governance evidence base; read when a governance decision needs justification
 - `docs/research/ai-coding-factory/ai-coding-factory-principles.md` — factory design rationale; read when implementing, auditing, or reviewing skills or factory structure
 - `docs/notes/factory-integration-decisions.md` — decisions from the factory integration grill; read when making skill authoring or factory design decisions
 - Governance rules are always in effect — `core/instructions/governance.md` (agent rules); `docs/research/governance_principles/CONTROLS.md`

SIMPLIFICATION-AUDIT.md

@@ -345,6 +345,8 @@ The shared pattern: per-skill `README.md` files no model reads, a `docs/research
     >
     > **Two defects the finding missed, both worth fixing independently of it.** (1) **A live bug: `docs/HUMANS.md` does not exist** — the file is `docs/wiki/HUMANS.md`. The wrong path appears **five times across three files**, including the **deployed** `core/instructions/governance.md:82`, which is self-inconsistent (line 73 correct, line 82 broken); the other four are `CONTROLS.md:5,101,106` and `ai-constitution.md:238`. (An earlier revision said "four times" while enumerating all five.) **Fixed (2026-09-15):** all five corrected to `docs/wiki/HUMANS.md`; the deployed copy under `~/.claude/` ~~is now stale until `scripts/install.sh` re-runs~~ → was redeployed on 2026-09-16 (see §10). (2) The deployed always-on file carries **repo-relative pointers that dangle in every project but this one** — an agent told to "read it when making decisions not covered here" cannot. That is the substantive question this finding should have asked. The footer is additionally self-referential: `governance.md:80` lists the file as compatible with itself.
     >
+    > **Decided and done (2026-09-16, grill).** The constitution moved from `docs/ai-constitution.md` to `core/ai-constitution.md`, so the existing `core` deploy step ships it to `~/.claude/core/ai-constitution.md`, and `governance.md`'s "read it when making decisions not covered here" pointer now names that deployed path. The three informational pointers (`HUMANS.md`, `CONTROLS.md`, and the footer) now say they live in the holocron repo rather than reading as local paths. Path-qualified citations were updated in `AGENTS.md`, `docs/spec/architecture.md`, `docs/notes/skill-implementation-workflow.md`, `CONTROLS.md` and the wiki's `HUMANS.md`; the vendored `write-skill` example under `plugins/kyberforge/docs/research/examples/` and this audit's historical notes were left as records. The wiki commit is local until its push is approved, and the `docs/wiki` gitlink is bumped only after that.
+    >
     > **Decision (2026-09-16):** Not proceeding — the human declined this finding, including the 168-word cross-reference trim. `core/instructions/governance.md` and the other three governance documents stay as they are. The `docs/HUMANS.md` path defect was fixed separately (see §10).
 
 28. [x] **ADRs: 2,740 lines, 72% in eight ADRs over 150 lines.** ADR-0020 is 513 lines with a 71-line measurement log as Context; ADR-0017 has 173 lines of amendments against 45 of decision. ADR-0001 is superseded and ADR-0006 moot, both keeping full text below the banner. ADR-0002 is three lines. Truncate superseded ones to the banner, fold amendments into the decision, cap Context at 20 lines, add a 25-line `docs/adr/README.md` index with status. The rules already live in `gates.md`; the ADRs need only decision and consequences. Effort M.

core/instructions/governance.md

@@ -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)*

docs/notes/skill-implementation-workflow.md

@@ -58,7 +58,7 @@ Return: extracted content per source, commit SHAs, licence notes, security flags
 
 Spawn an agent to cross-check the extracted upstream content against:
 - `core/instructions/governance.md` — hard prohibitions, data classification, HITL requirements
-- `docs/ai-constitution.md` — scope discipline, deterministic execution preference, licence obligations, output volume constraint, transparency requirements
+- `core/ai-constitution.md` — scope discipline, deterministic execution preference, licence obligations, output volume constraint, transparency requirements
 
 The agent flags conflicts and tensions as numbered items for the synthesis grill. It does **not** resolve them — that is the grill's job.
 

docs/research/governance_principles/CONTROLS.md

@@ -1,7 +1,7 @@
 # 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.
+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.
 
@@ -103,4 +103,4 @@ Human judgment decisions — which AI model to use, whether a specific output is
 ---
 
 *Derived from AI Constitution v1.1 — May 2026.*
-*Counterpart to: `docs/wiki/HUMANS.md` | `core/instructions/governance.md` | Full context: `docs/ai-constitution.md`*
+*Counterpart to: `docs/wiki/HUMANS.md` | `core/instructions/governance.md` | Full context: `core/ai-constitution.md`*

docs/spec/architecture.md

@@ -61,7 +61,7 @@ Plugin-root documentation belongs in `docs/`. That convention is older than the
 Those on-demand files are plain markdown — no frontmatter, no schema. The agent decides when to read each one from task context and the content index label alone. Frontmatter is deferred until there is evidence that agents are loading the wrong files in practice; it is a deliberate deferral, not an oversight to close.
 
 The governance layer has two phases:
-- **Phase 1** (complete): instruction and documentation layer — `governance.md` loaded via `@import`; `docs/ai-constitution.md` and `docs/wiki/HUMANS.md` as human-facing reference; `CONTEXT.md` extended with governance domain language.
+- **Phase 1** (complete): instruction and documentation layer — `governance.md` loaded via `@import`; `core/ai-constitution.md` and `docs/wiki/HUMANS.md` as human-facing reference; `CONTEXT.md` extended with governance domain language.
 - **Phase 2** (planned): deterministic enforcement layer — pre-commit hooks, CI gates, secret scanning, licence scanning. Specified in `docs/research/governance_principles/CONTROLS.md`.
 
 ## AGENTS.md pattern