diff --git a/SIMPLIFICATION-AUDIT.md b/SIMPLIFICATION-AUDIT.md index cb7ac1f..40cd506 100644 --- a/SIMPLIFICATION-AUDIT.md +++ b/SIMPLIFICATION-AUDIT.md @@ -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. diff --git a/core/instructions/governance.md b/core/instructions/governance.md index 721e297..0d21bc8 100644 --- a/core/instructions/governance.md +++ b/core/instructions/governance.md @@ -79,4 +79,4 @@ The deterministic enforcement layer — pre-commit hooks, CI gates, scanner conf *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/HUMANS.md` (human practitioner rules) | `docs/research/governance_principles/CONTROLS.md` (deterministic enforcement)* +*Counterparts: `docs/wiki/HUMANS.md` (human practitioner rules) | `docs/research/governance_principles/CONTROLS.md` (deterministic enforcement)* diff --git a/docs/ai-constitution.md b/docs/ai-constitution.md index b236f69..3066a89 100644 --- a/docs/ai-constitution.md +++ b/docs/ai-constitution.md @@ -235,4 +235,4 @@ It operationalises current regulatory and research consensus for practitioners. *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/HUMANS.md` (human practitioner rules) | `docs/research/governance_principles/CONTROLS.md` (deterministic enforcement)* +*Operative files: `core/instructions/governance.md` (agent instructions) | `docs/wiki/HUMANS.md` (human practitioner rules) | `docs/research/governance_principles/CONTROLS.md` (deterministic enforcement)* diff --git a/docs/research/governance_principles/CONTROLS.md b/docs/research/governance_principles/CONTROLS.md index a5c14ec..8e5265c 100644 --- a/docs/research/governance_principles/CONTROLS.md +++ b/docs/research/governance_principles/CONTROLS.md @@ -2,7 +2,7 @@ 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`*