docs(topics): land the context-engineering rightsizing design record - #1323
Conversation
…g article Thirteen independent Opus 5 agents each digested one section of the source article, fenced from every prior interpretation of it in this repository so the read is independent. Each returns claims quoted verbatim, evidence status against freshly fetched official documentation, testable criteria with must-not-flag cases, repo targets measured by command, conflicts, and operator questions. All thirteen reported clean fences. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KcpjtTBgcSY2C7ALk6abSS
Four items are not clear: issue #1271 already owns this effort's highest-confidence finding and adds a mechanism no section agent found (when_to_use, used in 2 of 187 files); PR #1096 claims the check-21 slot section S4 proposed and edits the philosophy doc section S2 proposes to edit; PR #1261 is actively rewriting the fable-5 subtree the operator excluded from this pass. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KcpjtTBgcSY2C7ALk6abSS
…ister The first-hand scan covered only claude-code-plugins. A wider scan adds the collisions that matter most for the user-scope half: two dotfiles PRs are actively editing dot_claude/CLAUDE.md, and a nine-day-old branch touches it with no PR. Also records four further issues claiming parts of this subject matter, the runtime-vs-instruction-surface boundary, and that the parallel context-engineering branch is still being worked. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KcpjtTBgcSY2C7ALk6abSS
Thirteen decisions binding on every lane that follows: scope and posture, sequencing against four in-flight items, and the two machine-health fixes. Records the verified constraint that ~/.claude/settings.json is chezmoi-managed via dot_claude/modify_settings.json, so the plugin removals are a dotfiles change rather than an in-place edit. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KcpjtTBgcSY2C7ALk6abSS
Scope boundary, repo posture on arbitration vs deletion, fresh-docs mandate scoping, the auto-memory tier move and seeded value, the CLAUDE.md doc-table cut, and vendored-guidance precedence. These are the questions the section agents declined to answer; all six are now binding. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KcpjtTBgcSY2C7ALk6abSS
The machine-specific-paths gate rejected 48 absolute Windows paths across 14 digests; they become <repo-root>, <worktrees-root>/, and ~/. Two scratchpad script citations named a non-persisting temp path and are now described instead of cited. markdownlint's MD014/MD032/MD026/MD051/MD056 findings and four typos hits are fixed at the source, and the working tree is normalized to the LF the .gitattributes clean filter already committed. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KcpjtTBgcSY2C7ALk6abSS
The nineteen ratified decisions are preserved verbatim. This appends the outcome of the first execution pass to the contract itself, so the record lives in the source of truth rather than in a checkout-local working file. Three decisions did not survive first-hand verification. Each lane reported and stopped rather than re-deciding, as the contract requires. - D-12 errata: the cited 2 ms sibling-guard control never ran. Both disk-hygiene comparators failed at launch. The real root cause is worse than assumed - the guards are killed at their timeout and contribute no permission decision, so tool calls proceed unguarded. The directive is unaffected; only the citation is corrected. - D-13 deferred: the removal set is empty. All ten zero-invocation seeded plugins are hook plugins that leave no transcript trace when they succeed. The prescribed mechanism would also not have reclaimed a token on this machine. - D-17 deferred: diagnosis confirmed, prescription unexecutable. The move aborts chezmoi apply fleet-wide, proven by execution. Also records the D-6 exclusion outcome, D-9/D-10 including D-10's permanent content loss, a correction to the collision register's writer count, the per-lane execution table, and the blind spot that produced three independent false-negative incumbent searches. Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
…ed nothing L0, L2, L3 and L4 all terminated on a session usage limit rather than at a stopping point of their own. Their status previously rested on an unwritten assumption; each now carries an explicit deferral stating what is deferred, why, and the concrete trigger that unblocks it. Notes that matter for whoever resumes: - L2's in-progress work carries a known error - its no-incumbent claim comes from a search scoped to SKILL.md, which is exactly how C6 was missed three times. The search must be redone across plugins/** before the build resumes. - L4's uncommitted edits are worktree copies, not the installed plugins, so machine behavior is unchanged and the guards remain fail-open. They must not be applied without behavior-preservation testing and confirmation of the fail-open reading against official docs. - L2, L3 and L4's work exists nowhere else and was deliberately left uncommitted rather than sealed behind a fabricated checkpoint. Their worktrees must not be pruned. Also records the outstanding verification debt: only L10 received the fresh-context review D-5 requires. Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
…ncompleteness PR #319 was open and editing dot_claude/CLAUDE.md while the register presented three writers as the complete set. The missing row cost nothing; the false completeness is the finding. Re-derive from gh pr list at the moment of acting. Also drops two commit counts from the execution-status section that no longer matched the branch, rather than chasing a self-referential number. Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
Claude encountered an error after 1s —— View job I'll analyze this and get back to you. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 15e4f156af
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
Claude finished @kyle-sexton's task in 3m 29s —— View job PR Review
SummaryThis PR lands 17 documentation files (~5,700 lines) under Finding 1 — Convention violation: contract slice must be pruned or graduated before mergeSeverity: Substantive
This PR adds 17 files under
The PR description does not mention an operator exemption from this lifecycle step. The Recommended action: Either (a) graduate Finding 2 — Stale
|
| File | Line | Stale reference |
|---|---|---|
| S1-preamble.md:200 | 200 | re-anchor in plugin directory listing |
| S1-preamble.md:277 | 277 | plugins/re-anchor/skills/use-your-skills/SKILL.md:96 |
| S5-progressive-disclosure.md:135 | 135 | re-anchor:sweep-all-disciplines |
| S5-progressive-disclosure.md:290 | 290 | re-anchor plugin measurement row |
| S5-progressive-disclosure.md:310 | 310 | plugins/re-anchor/skills/script-the-deterministic-work/SKILL.md:1 |
| S6-tool-descriptions.md:240–243 | 240, 243 | plugins/re-anchor/README.md, plugins/re-anchor/.claude-plugin/plugin.json |
| S8-rich-references.md:223 | 223, 334 | plugins/re-anchor/skills/tighten-your-output/evals/evals.json |
| S11-skills.md:151 | 151, 190 | plugins/re-anchor/skills/sweep-all-disciplines/SKILL.md, plugins/re-anchor/skills/setup/SKILL.md |
| S13-try-simplifying.md:241 | 241 | plugins/re-anchor/skills/tighten-your-output/SKILL.md:3 |
These are measurement artifacts captured before the rename. The correct current paths are plugins/discipline/skills/<name>/SKILL.md with sweep-all replacing sweep-all-disciplines.
Important consequence for deferred lanes: The execution-status errata notes that L2, L3, and L4 are uncommitted and must resume. When they do, any incumbent search scoped to these recorded targets will silently miss the renamed skill — a concrete instance of the D-1 blind spot the errata itself documents.
Finding 3 — Stale .work/ source citation in S13 (validates Codex P3, partially)
Severity: Minor
S13-try-simplifying.md:3 cites its source as:
Source: `.work/context-engineering-rightsizing/source-article.md:116-118`
The article is now committed at docs/topics/context-engineering-rightsizing/source-article.md. The .work/ path is a checkout-local memory-tier path that does not exist in any clone of this repository. The convention's redaction bar (topic-docs README "Redaction bar" section) forbids machine-local paths in committed material.
The other 12 digests avoid this — they reference source-article.md without a leading path prefix, or omit the prefix entirely. Only S13 has this issue.
The corrected citation would be ../source-article.md:116-118.
Finding 4 — Dangling reference to uncommitted evidence file
Severity: Minor
decisions.md:96 states:
Full evidence:
guardrails-latency-diagnosis.md.
This file is not committed anywhere in this PR. It presumably lives only in .work/context-engineering-rightsizing/ (checkout-local, never committed). The single-home rule (topic-docs README) forbids committed documents from pointing at unreachable paths. A reviewer who needs to evaluate the D-12 errata cannot reach this evidence.
Recommended fix: Either commit guardrails-latency-diagnosis.md alongside the other design files, or replace the pointer with a self-contained summary of the key measurements (the errata section already captures the essentials — the reference to an external file may be superfluous).
Codex review findings assessment
| Codex finding | Assessment |
|---|---|
| P2: "Prune contract slice before merge" | Confirmed valid. See Finding 1 above. The convention is unambiguous. |
P2: "Retarget plugins/re-anchor paths" |
Confirmed valid. See Finding 2 above. plugins/re-anchor does not exist. |
| P2: "Point S13 at committed source" | Confirmed valid, scoped to S13:3 only. See Finding 3. The other digests use relative or unqualified paths. |
What's working well
- Errata discipline. Recording three deferred decisions (D-12, D-13, D-17) verbatim — with the original ratified text untouched and the correction alongside it — is exactly the right posture and will serve future lanes.
- Collision register self-correction. The
#319correction is appended below the original rows (preserved as the historical record), with the generalizable lesson explicit. The anti-pattern it names ("treat every verdict here as a pointer to re-check, never as the answer") is the right takeaway. - Blind-fence discipline. All 13 agents reported clean fence events. The structural convergences (description-bloat finding appearing in 4+ independent digests) are therefore genuine independent measurements, which is load-bearing for the decisions built on them.
- D-1 blind-spot disclosure. The "past-the-end" finding about C6 in
claude-memory:auditbeing invisible toSKILL.md-scoped searches is precise, reproducible, and directly actionable. This is the kind of meta-finding that saves lanes.
S13 cited the source article at its .work/ path, which no clone contains; it now points at the committed copy. The D-12 evidence pointer named a file that lives only in the memory slice and said nothing about that - it now states where the file is and that a clone cannot reach it, rather than dangling. Records the #1276 rename as an erratum instead of rewriting the digests. Every plugins/re-anchor path in them resolves nowhere now, but those are dated measurements taken before the rename; retargeting paths and line numbers that were never re-measured would fabricate precision. The lanes resuming against those targets are who this warning is for. Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
Claude finished @kyle-sexton's task in 3m 4s —— View job PR Review — Follow-up Pass (
|
| Finding | Prior status | This commit |
|---|---|---|
| 1 — Contract-slice prune-before-merge | Open | Still open — no operator exemption recorded |
2 — Stale plugins/re-anchor/** paths |
Open | Addressed via errata (S3 and S10 added to scope; stale paths retained by design) |
3 — .work/ citation in S13 |
Open | Resolved |
4 — Dangling guardrails-latency-diagnosis.md pointer |
Open | Resolved with disclosure |
|
Both reviews landed the same three P2s. Two are fixed in Fixed — S13's source citation. It pointed at Fixed — the D-12 evidence pointer. Deliberately not fixed — the Open, and not mine to decide — the contract-slice prune. The convention says what both reviews say it
So the rule is normative and unobserved, and this PR matches 15 precedents. Precedent is not an argument One note on the review infrastructure: the first |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 20e8a8bc1d
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
The nineteen ratified decisions and their execution errata are architectural decisions, not working material, so they graduate through the knowledge-vault seam rather than being pruned with the contract slice. Moved with history via git mv and reshaped to the ADR template: an active decision phrase, accepted status, and Context/Decision/Consequences around the ratified tables, which are preserved verbatim. Pointer discipline applied on the way out. The record no longer cites the memory slice that held the guardrails latency capture, nor the contract slice that is pruned in the following commit; the collision register and the section digests are cited by their surviving lessons rather than by path. Carries forward the one piece of the pass's working material a later lane cannot cheaply reconstruct: the five-gate conflict definition D-4 ships against, its four remediation sub-types, the must-not-flag false positives, and the C6 partial incumbent that bounds it. L2 already re-derived this once because it was unreachable. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The three deferral entries name files that are uncommitted in each lane's own worktree. A durable record must not present those as citations a reader can follow — the same pointer-discipline defect PR review raised against the pass's `.work/` source-article citation, surviving into the promoted record by a different route. States the unreachability explicitly and names what is durable in each entry: L2's known incumbent-search error, L3's verified-sound direction, and L4's unmet behavior-preservation precondition. A resumption that cannot find the worktree re-derives from those. Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
The contract tier is committed on the task branch only and pruned before merge (docs/conventions/topic-docs/README.md:33, :302-304). Its durable outcome graduated to docs/adr/0004 in an earlier commit on this branch; what remains here is the evidence base that produced it. Pruned: the thirteen blind section digests, the agent brief, the collision register, and the source-article capture. Each is dated measurement taken against a tree that has since moved — #1276 renamed the re-anchor plugin and the sweep-all-disciplines skill out from under every path they cite — so retargeting them would fabricate precision they never had, and keeping them would publish stale targets an incumbent search silently fails against. The rename mapping and the digests' surviving conclusions are recorded in the ADR. The evidence does not become unreachable. This commit's parent holds the full slice, and GitHub serves blobs at a pull request's head SHA after squash-merge and branch deletion (verified against merged #1365). The PR description carries that SHA and the retrieval command, which is the pointer this convention directs durable surfaces to leave (:135-141, :302-304). Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
Claude finished @kyle-sexton's task in 2m 55s —— View job PR Review — Follow-up Pass (
|
| Finding | Resolution |
|---|---|
| 1 — Contract-slice prune-before-merge | Resolved ✅ — Commit 4507676 graduated decisions to docs/adr/0004; commit 22744fd pruned the full slice. Net diff is now exclusively the ADR. |
2 — Stale plugins/re-anchor paths |
Resolved ✅ — All digests containing stale paths are pruned. The rename mapping (re-anchor → discipline, sweep-all-disciplines → sweep-all) and the deferred-lane warning survive in the ADR at lines 244–257. |
3 — .work/ citation in S13 |
Resolved ✅ — Fixed in 20e8a8bc; S13 is deleted in 22744fd. |
4 — Dangling guardrails-latency-diagnosis.md pointer |
Resolved ✅ — Fixed with disclosure in 20e8a8bc; measurements are restated in the ADR at lines 131–159. |
New Codex Findings (from 20e8a8bc) — Both Moot
| Codex finding | Assessment |
|---|---|
agent-brief.md source citations pointing to nonexistent design/source-article.md |
Moot — agent-brief.md is deleted in 22744fd. |
Deferral list still marks #319 correction as outstanding after it was already applied |
Moot — the decisions.md containing that list is deleted in 22744fd. The ADR's collision-register section (lines 231–241) records #319 as a historical narrative, not an outstanding deferral item. |
ADR Review (docs/adr/0004-...md)
The promoted record is structurally sound and follows ADR conventions. A few observations:
What's good:
- Standard format (
Status: accepted,Date: 2026-07-25, Context / Decision / Consequences). ✅ - Ratified decision text is verbatim; errata sit beside it rather than overwriting it — the right posture for a durable record. ✅
- Pointer discipline applied throughout: no
.work/citations, no checkout-local paths, no reference to the now-deleted digests by path. ✅ - Commit
5b29569corrected the deferral entries to state unreachability explicitly and name what's durable rather than presenting file paths as followable citations. ✅ - The five-gate conflict definition and the four sub-types (lines 356–408) are precise enough to be checker-implementable — this is exactly the content worth preserving from the working material. ✅
One soft issue — dangling forward reference to a sibling ADR:
Line 417 closes with:
The sibling ADR on the sweep boundary rules on where that work lands.
No sibling ADR exists in docs/adr/ (current entries: 0001, 0002, 0004). This is a forward reference to an ADR that has not yet been filed. It leaves the conflict detector's landing zone unspecified for anyone reading this record before the sibling arrives. Not a blocker, but the reference should either name the future ADR by its planned number/topic, or be softened to "a follow-on ADR will rule on where that work lands" so it reads as intent rather than a pointer.
Overall
The PR is in a clean state. Finding 1 — the only substantive open item from both prior review passes — is resolved. The net diff is a single, well-formed ADR. The soft finding above is advisory; it does not block merge.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 22744fd664
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
Claude finished @kyle-sexton's task in 1m 50s —— View job PR Review — Follow-up Pass (
|
| Finding | Status |
|---|---|
| 1 — Contract-slice prune-before-merge | Resolved ✅ (22744fd) |
2 — Stale plugins/re-anchor/** paths |
Resolved via errata ✅ (20e8a8b) |
3 — .work/ citation in S13 |
Resolved ✅ (20e8a8b) |
4 — Dangling guardrails-latency-diagnosis.md pointer |
Resolved with disclosure ✅ (20e8a8b) |
| Codex P2 — D-6 stale outstanding status | Resolved ✅ (38b8cab) |
| Codex P2 — sibling ADR forward reference | Advisory, open |
The PR is in a clean, mergeable state. The one open item is advisory.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 38b8cab113
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…home Type D was listed as a fourth conflict sub-type while the five-gate definition above it requires co-residency, which split-brain fails by construction: two files that are never simultaneously loaded cannot prescribe incompatible actions for one input. An implementation applying the gates faithfully would discard every Type D case, making the promised sub-type unreachable. It is now a separate check with its own observable — divergence between surfaces that are never co-resident, which is drift, not conflict — and its own criteria and severity. The C6 reuse boundary is restated as a coverage predicate rather than a layer predicate, matching what C6 operationally does: its discovery step is depth-limited and its CLAUDE.md-versus-CLAUDE.local.md comparison is redundancy-only, so three same-layer pairs a "cross-layer" framing drops are in fact uncovered. Both sweep-boundary references stated their destination by pointing at a companion record, which left this ADR unable to answer where the D-4 work lands on its own. The placement is now stated directly, with the companion cited for the option analysis rather than for the answer.
|
Claude finished @kyle-sexton's task in 2m 57s —— View job PR Review — Follow-up Pass (
|
| Finding | Prior status | fd1718c |
|---|---|---|
| 1 — Contract-slice prune-before-merge | Resolved ✅ (22744fd) |
Unchanged |
2 — Stale plugins/re-anchor/** paths |
Resolved via errata ✅ (20e8a8b) |
Unchanged |
3 — .work/ citation in S13 |
Resolved ✅ (20e8a8b) |
Unchanged |
4 — Dangling guardrails-latency-diagnosis.md pointer |
Resolved with disclosure ✅ (20e8a8b) |
Unchanged |
| Codex P2 — D-6 stale outstanding status | Resolved ✅ (38b8cab) |
Unchanged |
| Codex P2 — Split-brain / Type D reachability | Open 🔴 | Resolved ✅ |
| Codex P2 — D-16 fresh-docs rollout gating | Open |
Moot ✅ |
| Advisory — sibling ADR forward reference | Advisory |
Substantially addressed — L2 now actionable from this ADR alone; ADR 0005 reference is supplementary detail only |
The PR is clean and mergeable. No open blocking findings remain.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: fd1718c9c3
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
The execution record described lanes by what sat uncommitted in a worktree, which is unreachable from a clone and therefore not a citation. Every lane has since published, so each row now names the PR or issue that carries its result: L2 as #1343, L3 as #1349 with the UNBACKED-to-OPINION mapping stated so the claim set does not need to survive as a separate list, L4 as #1385 closed with recovery on #1403, L1 as #1286 closed with the fold on #1271 and gate defects on #1404. The source article is named with its URL rather than left as "a practitioner article", so a reader auditing this ADR's premises can reach the thing the digests measured. The digests themselves prune with the contract slice, which is why the pointer replaces them rather than supplementing them.
|
Claude finished @kyle-sexton's task in 1m 40s —— View job PR Review — Follow-up Pass (
|
| Finding | Prior status | f14ece0 |
|---|---|---|
| 1 — Contract-slice prune-before-merge | Resolved ✅ (22744fd) |
Unchanged |
2 — Stale plugins/re-anchor/** paths |
Resolved via errata ✅ (20e8a8b) |
Unchanged |
3 — .work/ citation in S13 |
Resolved ✅ (20e8a8b) |
Unchanged |
4 — Dangling guardrails-latency-diagnosis.md pointer |
Resolved with disclosure ✅ (20e8a8b) |
Unchanged |
| Codex P2 — D-6 stale outstanding status | Resolved ✅ (38b8cab) |
Unchanged |
| Codex P2 — Split-brain / Type D reachability | Resolved ✅ (fd1718c) |
Unchanged |
| Codex P2 — D-16 fresh-docs rollout gating | Moot ✅ (fd1718c) |
Unchanged |
| Codex P2 — L3 resume inputs not actionable from clone | Open 🔴 (fd1718c) |
Resolved ✅ |
| Advisory — ADR 0005 forward reference | Advisory fd1718c) |
Unchanged — not a blocker |
The PR is clean and mergeable. No open blocking findings remain.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: f14ece0e70
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| Two caveats: the fail-open behavior was read from the decompiled v2.1.219 binary and is **not yet | ||
| confirmed against official documentation**; and a second defect follows — **disk-hygiene's | ||
| destructive-operation guard has been silently unenforced for the entire measured window**, which | ||
| needs its own ticket and is not this effort's to fix. |
There was a problem hiding this comment.
When this ADR is the only durable artifact after the topic slice is pruned, the newly discovered disk-hygiene fail-open defect has no resolvable work item: this says it “needs its own ticket” but supplies none, and a repo-wide search of the reviewed tree finds no other durable reference. Because the guard is reported as silently unenforced for the entire measured window, leaving the follow-up only as prose risks losing a safety repair; file or link the issue here.
Useful? React with 👍 / 👎.
| | L3 | D-4, D-2 | **PR #1349** — checks I12–I14 folded into the incumbent catalog | | ||
| | L4 | D-12 | **PR #1385**, closed unmerged after fresh-context verification; timeout half landed as #1379, recovery tracked as #1403 | | ||
| | L5 | D-13, D-17 | **stopped by design**; both decisions refuted, nothing committed | | ||
| | L7 | D-9, D-10 | **dotfiles PR #321**, merged | |
There was a problem hiding this comment.
When this ADR is rendered on GitHub, bare #321 resolves against claude-code-plugins, not melodic-software/dotfiles, so a reader following this execution outcome is sent to the wrong PR. The same ambiguity affects dotfiles PRs #312 and #318 earlier in the record; use an explicit melodic-software/dotfiles#321 reference or URL.
Useful? React with 👍 / 👎.
(#1280) No linked issue ## What this PR lands One file: `docs/adr/0005-bound-instruction-surface-work-by-question-not-population.md`. This is the D-11 reconciliation — the ruling that decides where the context-engineering effort's two deliverables end and issue #1225 begins. ADR 0004 refers to it twice as "the sibling ADR on the sweep boundary"; this PR is what makes that pointer resolve. The analysis was written on the task branch under `docs/topics/context-engineering-rightsizing/design/`, which `docs/conventions/topic-docs/README.md:290-309` makes task-branch-only. It graduates here as a history-preserving `git mv` (`2e310bd9db`, 100% rename) followed by the rewrite (`d20bd40cf5`), so `git diff --name-only main...HEAD` returns exactly the one ADR path. ## What it decides - **The discriminator between #1225 and this effort is the question, not the population.** The file populations genuinely overlap — #1225 Part 2's "would this plugin benefit from a sub-agent" half reaches all 60 plugins. What separates them is the observable: existence qualification versus inter-surface contradiction versus content-against-model-capability. D-11's concern is routers, and orthogonal questions over shared files need no shared traversal. - **L2's novel scope is every contradiction pair `claude-memory:audit`'s C6 does not operationally cover** — not "cross-layer" contradiction. - **L2 lands as a new phase in `claude-config:audit-instructions` (Option A)**, with the plugin-source surface Phase A must gain first stated as part of A's cost. - **L3 folds into the incumbent criteria catalog**, and `UNBACKED` maps onto the existing `OPINION` tag with an `info` ceiling rather than becoming a fourth authority value. - **Deterministic findings follow #445's lane shape**, because both host plugins are report-only and nothing landing in them blocks a merge. - **The instruction plane is durable pre-session instruction text, not committed files**, which keeps user-global rules and `CLAUDE.local.md` inside the boundary. ## Rewrite, not a copy The graduated document was a working analysis that left two placement calls open. A durable record has to rule, so the rewrite states the decisions and carries only the evidence needed to audit them. It drops 400 lines and adds 238. Four review findings from this PR are applied in the rewrite: 1. **Same-layer C6 gaps stay inside L2's scope.** C6 operationally covers only root project `CLAUDE.md` versus project `.claude/rules/` — its discovery step is `find . -maxdepth 1` and its `CLAUDE.md`-versus-`CLAUDE.local.md` comparison is redundancy-only. The old "cross-layer" framing silently dropped three same-layer pairs it never reaches. The routing predicate is now *coverage*, not *layer*. 2. **Option C is no longer an independently valid whole-scope choice.** `claude-memory`'s own scope table routes settings, hooks, MCP, agents and skills to `claude-config` (`plugins/claude-memory/skills/audit/SKILL.md:34`), so taking C for L2's whole scope would place the check in a plugin that disclaims the surface. C survives as a memory-slice placement only. 3. **Option A's plugin-source surface enumerates the 181 shipped skills, not 187.** The recursive count includes six upstream `vendor/` materializations this repository never hand-edits. 4. **The boundary is durability and pre-session residency, not git status.** Several in-scope surfaces are deliberately user- or machine-local and are never committed. ## Verification Every `path:line` citation carried into the ADR was re-verified first-hand against current `main` rather than against the branch's older base — `audit-instructions/SKILL.md`, its `reference/criteria.md`, `claude-memory/skills/audit/SKILL.md`, its `reference/criteria.md` and `context/audit.md`, and `audit-automation-gaps`. One figure was corrected in the process: the "zero descriptions name conflict detection" claim is literally false — three of the 199 `description:` lines under `plugins/` contain the word in unrelated senses (merge-conflict resolution, glossary curation, a planning setup check) — so the ADR now states the precise claim, that none advertises instruction-contradiction detection. Gates run locally on the changed file: `markdownlint-cli2` 0 errors, `typos` clean, `editorconfig-checker` clean. ## Related Refs #1225 — reconciled per D-11; its owner gets one recommendation about the Part 1 existence qualifier. Refs #445 — its lane shape is where any deterministic slice of L2 or L3 goes. Refs #1219, the downstream consumer that a new router would have broken. #1323 depends on this PR for the sibling-ADR pointer ADR 0004 carries. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
…clude mechanical work (#1368) Closes #1324 ## Summary Runs the context-engineering rightsizing effort's criteria catalog over `plugins/playbooks/skills/fable-5/**` — the one subtree decision D-6 excluded from the original pass because PR #1261 was actively rewriting it. #1261 merged (2026-07-25T00:38:24Z) before this follow-up started; the catalog was applied against the post-#1261 tree. **Criteria source.** `docs/topics/context-engineering-rightsizing/design/decisions.md` and its 13 section digests (S1–S13), all still on the unmerged `feat/context-engineering-rightsizing` branch (PR #1323, open) — read directly from that ref per the item's own instruction, since the item names them as source of truth regardless of merge state. **The one concrete, evidenced finding.** S3's digest lists `playbooks/fable-5` among the files carrying the blanket verifier-subagent dispatch that locked decision D-5 targets: *"drop blanket dispatch on mechanical behavior-preserving work; keep it where the verdict is subjective or blast radius is wide."* fable-5 required a fresh-context verifier after **any** multi-file edit batch or before **any** multi-part completion claim, with no carve-out for a mechanical, behavior-preserving change (e.g. an exact, low-judgment rename). This PR adds that carve-out. The trigger turned out to live at **three** co-resident sites, not one — `SKILL.md`'s always-armed core-doctrine distillation, `context/verification.md`'s floor statement, and `context/orchestration.md`'s owning section. Narrowing only the owning section would have left `SKILL.md` stating the unnarrowed rule, reproducing the exact cross-surface split-brain the catalog's own S2 digest (CRIT-S2-1) flags as a defect class — caught in an advisor pass before this landed, and fixed by narrowing all three together. `orchestration.md` keeps the full reasoning (it owns the gate); the other two sites carry the shortest carve-out and point back to it. The carve-out reuses `context/planning.md`'s existing behavior-preserving/behavior-changing distinction per meta-rule 2 (one home per doctrine) rather than inventing a second one. **Declined: a blanket I1–I11 sweep.** No other digest (S2, S4, S5, S8, S11, S13) names a concrete `fable-5` finding. S13 explicitly rules out a blanket de-constraining sweep on high-absolute-density skills — fable-5 is a density leader (26.6 absolutes/100 lines, S3's own measurement) — absent an operator-run, report-only `claude-config:audit-instructions` pass; S5 and S11 both cite fable-5 as a *positive* progressive-disclosure exemplar (10.6x support:body ratio) rather than a target. `docs/topics/fable-field-guide-audit/` (PR #1261's own remediation record) shows the skill already cleared a Fable-5-specific admission bar (`SKILL.md:11`, "every line encodes something a strong model does NOT reliably do untold") stricter than this catalog's own I1–I11. A clean result on every other check is a valid outcome the catalog's `criteria.md` states explicitly, so no further edit was manufactured here. **Lane note.** Session-start bulk reclaim of unrelated stale-assigned items (Step 0 of the `work` skill) was blocked by the auto-mode classifier as out-of-scope for a session dispatched against one named item — correctly, since that hygiene is fleet-wide and orthogonal to #1324. Skipped without effect on this item, which was independently confirmed unassigned before claiming. ## Test plan - [x] `scripts/check-changed-skills.sh origin/main` — `fable-5: PASS — 0 errors, 1 warning` (the one warning, no Gotchas surface, pre-exists this change) - [x] `scripts/check-skill-portability.sh origin/main` — no unexcused coupling tokens in the 3 changed skill files - [x] `scripts/check-changelog-parity.sh --check-bump origin/main` — playbooks' version bump has a matching `## [0.5.1]` entry - [x] `markdownlint-cli2` on all 4 changed files — 0 issues - [x] `typos` on the changed skill directory and CHANGELOG — 0 issues - [x] `claude plugin validate plugins/playbooks` — passed - [x] `node scripts/validate-plugin-contracts.mjs` — 43 setup skills / 2055 plugin files checked, clean - [x] `node scripts/generate-catalog.mjs --check` — catalog in sync - [x] Read all 14 fable-5 files (`SKILL.md` + 13 `context/*.md`) and cross-checked against digests S1–S13 + `decisions.md`; no other digest names a concrete finding against this subtree - [x] Confirmed no open PR currently touches `plugins/playbooks/**` (re-derived via `gh pr list` per the item's own instruction, not trusted from `collision-register.md`) ## Related - #1324 (this PR closes it) - #1261 — the prior remediation record this PR does not revisit (`docs/topics/fable-field-guide-audit/`) - #1323 — the (unmerged) design-record PR whose branch this PR reads the criteria catalog from - D-5, D-6 in `docs/topics/context-engineering-rightsizing/design/decisions.md` (on `feat/context-engineering-rightsizing`, not yet on `main`) --- *This was generated by AI during work-loop execution.* --------- Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
1 participant
What this PR lands
One file:
docs/adr/0004-rightsize-instruction-surfaces-by-incumbent-first-arbitration.md.The branch carried the full contract slice for this effort while the work was in flight — 13 blind
section digests, the ratified decision set, the collision register, the agent brief, and the source
article, all under
docs/topics/context-engineering-rightsizing/. Perdocs/conventions/topic-docs/README.md:290-309that slice is task-branch-only: durable outcomesgraduate, follow-ups route to the tracker, and a final commit prunes the slice.
That lifecycle is now complete on this branch:
against, and the incumbent-gate blind spot are promoted into ADR 0004.
22744fd664removes the contract slice.git diff --name-only main...HEADreturns exactly the one ADR path, satisfying the enforcement ruleat
README.md:305-309.The digests were produced blind
Thirteen agents each read one section of the source article with no sight of the others' output and
no sight of this repository's prior conclusions. All thirteen reported clean fences. The
convergences between them are therefore independent measurements rather than echoes, which is what
makes the repeated findings load-bearing — and what the ADR's "Context" section rests on.
The digests themselves are working material, not durable knowledge, so they prune rather than
graduate. What survives is the arbitration posture they converged on (D-15) and the incumbent-first
gate (D-1) that the pass proved was worth paying for.
Three decisions were refuted by measurement — recorded, not executed
The ratified text of all nineteen decisions is preserved verbatim in the ADR. Where first-hand
measurement contradicted a decision's supporting evidence, the correction sits beside it as errata
and the lane stopped rather than re-deciding:
the root cause) stands and only the citation is corrected. The real defect is worse than the
decision assumed: the guards are substantially fail-open.
plugins are hook plugins, for which zero transcript invocations is the expected reading of a
correctly functioning one.
aborts
chezmoi applyfleet-wide with a hard template error.Both deferrals await operator re-decision. Nothing was committed on their behalf in any repository.
Deliberate, disclosed collision
Branch
docs/context-engineering-claude-5-topic(PR #1322) covers the same source article and isworked by a parallel session. The operator ruled that this pass runs independently and that the
collision is resolved at merge, not by folding. The ADR records this as a standing constraint rather
than as a register entry, because the register was working material and prunes with the slice.
What the pruned register taught, and why only the lesson survives
The collision register presented three writers on
dot_claude/CLAUDE.mdas the complete set whenthere were four (dotfiles PR #319, open and editing that file mid-pass). The missing row cost
nothing — it merged before colliding — but the false completeness is the finding, and two lanes were
dispatched trusting it. The register is not preserved; the generalizable lesson is, in the ADR:
re-derive collisions from
gh pr listat the moment of acting rather than trusting a snapshot.Verification
Gates run locally on the changed slice before pushing:
markdownlint-cli2,typos,editorconfig-checker,lychee,gitleaks, andscripts/check-docs-only.sh. All clean, nothingsuppressed. No machine-specific paths, no
.work/citations, and no shell or shebang files in thecommitted result.
Related
No linked issue — this PR closes nothing. It lands the durable design record; the execution
lanes it dispatched carry their own issues and PRs.
Refs #1324 — the D-6 follow-up covering
plugins/playbooks/skills/fable-5/**, excluded from thispass while PR #1261 rewrote it.
🤖 Generated with Claude Code