From f0dbab1fc541660deb7da152c30c2fdea67ec7c9 Mon Sep 17 00:00:00 2001 From: Aaron Stainback Date: Mon, 27 Apr 2026 22:45:32 -0400 Subject: [PATCH 1/2] copilot-instructions: add inverse-direction rule for the Otto-279 carve-out + surface-category quick reference MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Aaron 2026-04-28 surfaced a same-substrate-verifier failure this session: a Claude Code plugin agent (pr-review-toolkit:silent-failure-hunter) PASSED an over-scrubbed de-naming on docs/research/** as "consistent with Otto-279 history-surface attribution carve-out — non-history-surface prose drops the named-attribution form." The verifier inverted the carve-out the same direction the actor did. When actor and verifier share the same rule-misreading, single-CLI verify is insufficient. The existing copilot-instructions.md "Reviewer note" tells Copilot not to FLAG first-name attribution on history surfaces. What was missing: the inverse direction — don't SUGGEST removing attribution from history surfaces either. The carve-out is bidirectional. Two additions to the "No name attribution" rule: (1) Inverse-direction rule (explicit): When proposing a de-naming edit (Aaron → "the human maintainer," Otto → "the architect," etc.), check the surface path FIRST. If the path is in the closed-list history surfaces, the existing names are correct as-is and a de-naming suggestion is the bug, not the fix. (2) Surface-category quick reference (so the path-check is actually doable in-line during review): - History surfaces (preserve as-is): memory/**, docs/research/**, docs/ROUND-HISTORY.md, docs/DECISIONS/**, docs/aurora/**, docs/pr-preservation/**, docs/hygiene-history/**, docs/WINS.md, docs/BACKLOG.md, docs/backlog/**, commit messages, PR titles + bodies. - Roster-mapping carve-out (governance / instructions files): .github/copilot-instructions.md, AGENTS.md, GOVERNANCE.md, docs/CONFLICT-RESOLUTION.md. - Current-state surfaces (role-refs only): code, .claude/skills/**, .claude/agents/**, openspec/specs/**, docs/*.tla, docs/AGENT-BEST-PRACTICES.md, docs/GLOSSARY.md, docs/WONT-DO.md, threat models, READMEs, trajectory files (docs/trajectories/**). Composes with the loop-quality trajectory just landed at docs/trajectories/loop-quality.md (LFG #659 branch). When that trajectory ships to AceHack main + cross-references this file, the discipline is fully landed. Plugin disclosure: this commit was authored under Claude Code (harness-built-in tools only; no plugin agents invoked for the edit itself, though the failure-mode this addresses surfaced when invoking pr-review-toolkit:silent-failure-hunter for a prior verify in this session). Co-Authored-By: Claude Opus 4.7 --- .github/copilot-instructions.md | 44 +++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 822c646df..fa8504145 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -360,6 +360,50 @@ Per [docs/CONFLICT-RESOLUTION.md](../docs/CONFLICT-RESOLUTION.md) preserve who-said-what for the record. On any other path, DO flag name attribution — names should not bleed into reusable code/docs/skills. + + **Inverse-direction rule (added 2026-04-28 after a + same-substrate-verifier failure):** the carve-out is + bidirectional — applies to both *flagging existing + attribution* AND *suggesting attribution removal*. When + proposing a de-naming edit (replacing "Aaron" with "the + human maintainer," or "Otto" with "the architect," or + similar), check the surface path FIRST. If the path is in + the closed-list history surfaces above, the existing names + are correct as-is and a de-naming suggestion is the bug, + not the fix. The 2026-04-28 surfacing: a same-substrate + reviewer (the `pr-review-toolkit:silent-failure-hunter` + plugin agent in Claude Code) passed an over-scrubbed + de-naming on `docs/research/**` as *"consistent with + Otto-279 history-surface attribution carve-out — + non-history-surface prose drops the named-attribution + form"* — i.e., the verifier inverted the carve-out the + same direction the actor did. When the actor and the + verifier share the same rule-misreading, single-CLI + verify is insufficient. **Surface-path-first** is the + corrective: identify the surface category before + suggesting any name-related edit. + + **Surface-category quick reference** (use this BEFORE + flagging or suggesting a name-related edit): + - **History surfaces** (preserve attribution as-is): + `memory/**`, `docs/research/**`, `docs/ROUND-HISTORY.md`, + `docs/DECISIONS/**`, `docs/aurora/**`, + `docs/pr-preservation/**`, `docs/hygiene-history/**`, + `docs/WINS.md`, `docs/BACKLOG.md`, `docs/backlog/**`, + commit messages, PR titles + bodies. + - **Roster-mapping carve-out** (governance / instructions + files with one-time persona-to-role mapping permitted): + `.github/copilot-instructions.md`, `AGENTS.md`, + `GOVERNANCE.md`, `docs/CONFLICT-RESOLUTION.md`. Body-prose + attribution still forbidden on these. + - **Current-state surfaces** (use role-refs only): code + (F#/C#/TS/shell), skill bodies under `.claude/skills/**`, + persona definitions under `.claude/agents/**`, spec docs + (`openspec/specs/**`, `docs/*.tla`), behavioural docs + (`docs/AGENT-BEST-PRACTICES.md`, `docs/GLOSSARY.md`, + `docs/WONT-DO.md`), threat models, READMEs, + public-facing prose, trajectory files + (`docs/trajectories/**`). - **Analyzer findings: right-long-term-fix OR documented suppression, never the third path of "quick appeasement."** For every `Sxxxx` (Sonar) / `MAxxxx` (Meziantou) / From a7e7fddc23c9ba4539bdbc0316cbe451043590fa Mon Sep 17 00:00:00 2001 From: Aaron Stainback Date: Mon, 27 Apr 2026 23:52:03 -0400 Subject: [PATCH 2/2] copilot-instructions: tighten carve-out example + classification per PR #74 review threads MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PR #74 review-thread fixes: P1 (Copilot, line 369): the example de-naming edit used "Otto" → "the architect", but the architect persona in the roster mapping is Kenji, not Otto. Reframed the example to refer generically to "the architect persona's first-name" without hardcoding which name maps to which role — that decoupling makes the rule survive future persona-roster changes too. P1 (Copilot, line 377): the same example used "Aaron" as a persona-roster-mapping example, but Aaron is the human maintainer (not part of the agent-persona roster). Reframed to "human-maintainer first-name" + "agent-persona first-name" — same de-coupling discipline as above. P2 (Copilot, line 398): the carve-out classification of AGENTS.md / GOVERNANCE.md / CONFLICT-RESOLUTION.md was ambiguous — these files contain BOTH a roster mapping section (carve-out applies) AND body-prose elsewhere (must use role-refs). Clarified that the carve-out covers the explicit roster section ONLY; elsewhere in these same files, role-refs remain mandatory. P2 (codex, line 404): added CLAUDE.md to the current-state surface list (it was missing — it's the wake-time floor for agents and clearly a current-state surface). P1 (Copilot, line 406): `docs/trajectories/**` doesn't exist on this branch (lives on the trajectory-pattern branch). Reframed the listing to "when present" and noted the cross- branch reality so the surface-category check stays sound. --- .github/copilot-instructions.md | 29 ++++++++++++++++++++--------- 1 file changed, 20 insertions(+), 9 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index fa8504145..d0ec4e0ef 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -365,9 +365,12 @@ Per [docs/CONFLICT-RESOLUTION.md](../docs/CONFLICT-RESOLUTION.md) same-substrate-verifier failure):** the carve-out is bidirectional — applies to both *flagging existing attribution* AND *suggesting attribution removal*. When - proposing a de-naming edit (replacing "Aaron" with "the - human maintainer," or "Otto" with "the architect," or - similar), check the surface path FIRST. If the path is in + proposing a de-naming edit (replacing a human-maintainer + first-name with "the human maintainer," or replacing an + agent-persona first-name with the role-ref defined in the + roster mapping above — e.g., the architect persona's + first-name with "the architect" — or similar), check the + surface path FIRST. If the path is in the closed-list history surfaces above, the existing names are correct as-is and a de-naming suggestion is the bug, not the fix. The 2026-04-28 surfacing: a same-substrate @@ -392,18 +395,26 @@ Per [docs/CONFLICT-RESOLUTION.md](../docs/CONFLICT-RESOLUTION.md) `docs/WINS.md`, `docs/BACKLOG.md`, `docs/backlog/**`, commit messages, PR titles + bodies. - **Roster-mapping carve-out** (governance / instructions - files with one-time persona-to-role mapping permitted): + files where a one-time persona-to-role mapping section + is permitted because the file's job requires resolving + role-refs to persona-names): the *roster sections* of `.github/copilot-instructions.md`, `AGENTS.md`, - `GOVERNANCE.md`, `docs/CONFLICT-RESOLUTION.md`. Body-prose - attribution still forbidden on these. + `GOVERNANCE.md`, `docs/CONFLICT-RESOLUTION.md`. The + carve-out covers the explicit roster mapping ONLY; + body-prose attribution outside the roster section + remains forbidden on these files (i.e., elsewhere in + these files use role-refs, not persona-names). - **Current-state surfaces** (use role-refs only): code (F#/C#/TS/shell), skill bodies under `.claude/skills/**`, persona definitions under `.claude/agents/**`, spec docs (`openspec/specs/**`, `docs/*.tla`), behavioural docs (`docs/AGENT-BEST-PRACTICES.md`, `docs/GLOSSARY.md`, - `docs/WONT-DO.md`), threat models, READMEs, - public-facing prose, trajectory files - (`docs/trajectories/**`). + `docs/WONT-DO.md`), `CLAUDE.md`, threat models, READMEs, + public-facing prose, trajectory files (when present + under `docs/trajectories/**`; the directory is part + of the planned trajectory-pattern but lives on a + separate branch on this branch's tip — treat as + "current-state when present"). - **Analyzer findings: right-long-term-fix OR documented suppression, never the third path of "quick appeasement."** For every `Sxxxx` (Sonar) / `MAxxxx` (Meziantou) /