Why: three governance documents cited `docs/HUMANS.md`, which has never existed -- the human
practitioner rules live at `docs/wiki/HUMANS.md`. One of the three is
`core/instructions/governance.md`, which is `@`-imported into every session in every project,
so an agent following its "read it when making decisions not covered here" pointer hit a dead
path. That file was self-inconsistent: line 73 already cited the correct path while line 82 did
not.
Implementation notes: five occurrences corrected across three files --
`core/instructions/governance.md:82`, `docs/research/governance_principles/CONTROLS.md:5,101,106`,
and `docs/ai-constitution.md:238`. Text is otherwise untouched; this is a path correction only,
not a change to any governance rule. Marked the defect fixed in SIMPLIFICATION-AUDIT.md, which
recorded it in two places as outstanding.
Impact: no rule, gate or behaviour changes. The deployed copy at
`~/.claude/core/instructions/governance.md` no longer matches the repo and stays stale until
`scripts/install.sh` re-runs; it was byte-identical before this commit.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
@@ -290,7 +290,7 @@ The shared pattern: per-skill `README.md` files no model reads, a `docs/research
>
> **Honest ceiling: 168 words / 17.7%** of the file's 949 — the cross-reference scaffolding only: preamble **43** (lines 3–5), non-governance block **77** (71–76), footer **48** (79–82), landing at ~67 lines with no rule loss. (An earlier revision said 47 for the preamble, which is only reachable by counting lines 1–7 — that sweeps in the `#` glyph and a `---` rule as words.) Plus 133 words from the constitution. Not 50 lines, not 20%.
>
> **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.) (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.
> **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. (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.
28.**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.
> **Moved backwards (measured 2026-09-14 over `afa7187^`..`a6434e0`):** today's ADR-0024 work did the opposite of this finding on every axis, and that is recorded here so it is a known trade rather than a surprise. `docs/adr/` went from **23 files / 2,748 lines** to **24 / 3,084** — one new ADR (0024, 259 lines) plus amendment and banner text across **eleven existing ADRs** (0001, 0006, 0011, 0013, 0014, 0015, 0017, 0018, 0019, 0020, 0021 — 87 lines added, 10 removed, net **+77**), for a total of net **+336 lines (+12%)**. The two ADRs this finding names for truncation both grew *below* their banners instead: **ADR-0001 26 → 27** lines and **ADR-0006 22 → 27**, each gaining a fresh "as of ADR-0024" paragraph rather than losing the historical body beneath it. ADR-0017 gained a supersession banner while keeping its four amendments in full — the exact shape this finding proposes to fold.
@@ -491,5 +491,5 @@ The recurring failure mode is worth naming, because it has now produced six wron
### Two defects to fix independently of any finding
- **A live bug in always-on context.** The deployed `core/instructions/governance.md` cites`docs/HUMANS.md`, which does not exist — the file is `docs/wiki/HUMANS.md`. **Five occurrences across three files**;`governance.md` is self-inconsistent (line 73 correct, line 82 broken), and it is `@`-imported into every session in every project. Also `CONTROLS.md:5,101,106` and `ai-constitution.md:238`.
- **~~A live bug in always-on context.~~ Fixed (2026-09-15).** The deployed `core/instructions/governance.md` cited`docs/HUMANS.md`, which does not exist — the file is `docs/wiki/HUMANS.md`. Five occurrences across three files (`governance.md:82`, which was self-inconsistent against its own correct line 73; `CONTROLS.md:5,101,106`; `ai-constitution.md:238`), in a file `@`-imported into every session in every project. All five now point at `docs/wiki/HUMANS.md`. Note the deployed copy under `~/.claude/` no longer matches the repo until `scripts/install.sh` re-runs.
- **This checkout's install is stale and there is a branch hazard.** At the time of the wave `apm outdated` reported 6 outdated dependencies, 9 commits behind `main`, with a clean tree and nothing reporting it. **Do not run `apm update` on this branch** — it resolves against `main` and restores the obsidian MCP server that commit `c96ca9c` removed here. Reproduced. The mechanism is worse than "reinstalls `plugins/bin/.mcp.json`": apm never writes into `plugins/`, it re-materialises the file under `apm_modules/` and regenerates the repo-root `/.mcp.json` — which `c96ca9c` gitignored, so the restoration would not appear in `git status` at all. This belongs in ADR-0019's Consequences; see finding 34.
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`
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.
@@ -98,9 +98,9 @@ Verify that the controls specified here remain aligned with the current version
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/HUMANS.md`. Agent judgment decisions are governed by `core/instructions/governance.md`. This file governs only what can be enforced without judgment.
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/HUMANS.md` | `core/instructions/governance.md` | Full context: `docs/ai-constitution.md`*
*Counterpart to: `docs/wiki/HUMANS.md` | `core/instructions/governance.md` | Full context: `docs/ai-constitution.md`*
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
