feat(conventions): topic-docs v3.0.0 — recursive slices with per-slice INDEX.md - #3557
Conversation
…archy) Nine threads for the v3 interface per the locked Brief (PR #3552, epic #3554): the INDEX.md frontmatter schema and the dispatch-gate candidate rule carry design-it-twice sketches; marker/regen contract, child-header mini-schema, size-cap behavior, seam wording, lanes' reserved home, the depth-proof worktree carry, and the read-first binding placement round out the set, with dependency order noted for the substrate PRs. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018zeKDi1TCmryAkU28BjQuD
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
|
Claude finished @kyle-sexton's task in 1m 51s —— View job Claude code review
This PR adds a single doc, Findings1 inline comment posted — the status-vocabulary legend at line 4 declares Non-blocking observation (not posted inline, low confidence)T3 (line 65) states a child slice's abstract lives in "its own INDEX.md frontmatter Everything else — dependency-order cross-references (T1→T3, T1→T5's |
|
Generated by Claude Code |
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
|
Claude has reviewed this PR 5 times. The lane skips further automatic reviews after 5; deleting this comment resets the count. |
![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: 793d3a74c2
ℹ️ 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".
Design threads T1-T9 locked to their recommended options under the session goal directive (fresh-context verifier validation dispatched; challenged threads will be fixed and re-verified before dependent phases). PLAN.md recreated with a Brief pointer (single-home: PR #3552 description) and the filled Plan: phased substrate-then-flip execution as one atomic PR on the designated branch, with the deviation from multi-PR staging noted and justified. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018zeKDi1TCmryAkU28BjQuD
|
Claude finished @kyle-sexton's task in 6m 12s —— View job Claude code review
This pass reviews the new commit ( Findings (2 inline comments posted)1. T1/T3 contradiction on where a child slice's abstract lives (line 66–70). T3 says a child slice's abstract comes from "its own INDEX.md frontmatter 2. T5's Both threads are marked Not re-flaggedTwo similar findings posted by Codex on the prior commit (missing Everything else checked out
|
Two convergent findings from the claude and Codex review lanes: Sketch A's frontmatter gains the abstract key (T3's single-home source for a child that is itself a slice), and T5's --check-children gains a deterministic content-derived child-slice predicate so parity never false-orphans sanctioned interior noun folders. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018zeKDi1TCmryAkU28BjQuD
Replace .worktreeinclude's depth-enumerated globs with reserved-name-keyed recursive patterns and add INDEX.md and INTENT family coverage the old set never matched. worktree-create.test.sh gains six cases proving zero-dir and depth-3 ** carry plus a non-reserved-name negative through the real ls-files/check-ignore path. Verified by a fresh-context agent: old and new sets produce byte-identical matches on the current tree plus the intended additions; suite 197 PASS / 0 FAIL. Refs #3554 (topic-docs v3 wave, thread T8). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018zeKDi1TCmryAkU28BjQuD
|
Claude finished @kyle-sexton's task in 1m 42s —— View job Claude security review
Ran the Skip gate: PR is open, and the diff has a small amount of security-adjacent surface (a Scope reviewed (files with actual logic/config changes in this diff — the remaining 46 changed files are pure doc deletions/additions with no executable or security-relevant content):
Result: no security issues found. Nothing here touches authentication, authorization, secrets handling, or introduces an injection/trust-boundary risk. |
|
Claude finished @kyle-sexton's task in 5m 27s —— View job Claude code review
1 inline comment posted on SummaryThe bulk of this PR's diff (11,583 of 11,594 net changed lines — 99.9%) is not the design-threads content the PR description describes. It's commit That deletion is plan-sanctioned ( Everything else checked out:
|
|
Last security-reviewed head: |
Fold the design verifier's challenged findings into the threads: markers reuse the repo's live BEGIN GENERATED convention; distinct exit codes per failure class; abstracts are one unwrapped line (the always-on formatter was shown to corrupt wrapped continuations); sole-artifact resolution by ordered reserved-name precedence with multi-family leaves requiring an index; index files gain frontmatter in discovery's artifact-shape spec; the explore collision escape moves parent-side in the same wave; parity moves out of the header-blind dispatch gate into the shared lib script with an explicit not-applicable verdict; cap-fail preserves any existing body and names the abstract-length lever; the native worktree-carry claim is softened to what was actually verified and corpus-carry guidance noted. Refs #3554. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018zeKDi1TCmryAkU28BjQuD
The changelog-parity gate correctly flagged the worktree-create.test.sh change riding a published version; add the release entry and manifest bump the wave's W1 workstream owed. Refs #3554. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018zeKDi1TCmryAkU28BjQuD
|
Claude finished @kyle-sexton's task in 1m 21s —— View job Claude security review
Ran the Skip gate: PR is open. A prior pass on this PR already reviewed everything through Files touched in that range (
None of these introduce or modify authentication, authorization, secrets handling, injection surfaces, or Actions trust-boundary behavior. The Result: no security issues found. |
…ointer The W4 verifier caught one live relative link into a slice the cleanup deleted; cite the pre-prune SHA per pointer discipline instead, matching the commit-convention README's form. Refs #3554. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018zeKDi1TCmryAkU28BjQuD
|
Claude finished @kyle-sexton's task in 3m 43s —— View job Claude code review
Ran the Findings (2 inline comments posted)1. Stale 2. Same staleness carried into Both stem from the same root cause: Everything else checked out
|
|
Claude finished @kyle-sexton's task in 3m 10s —— View job Claude code review
Ran the Skip gate: PR is open, not draft. The last code-review pass on this PR covered through Scope reviewed —
FindingsNo blocking findings. The two contradictions flagged in my prior review round on this PR are both resolved in this range:
Cross-checked the new exit-code scheme for internal consistency: T2 defines Non-blocking observation (not inline, low confidence)T3's "sole artifact" precedence for an index-less leaf lists Everything else checked out
|
…3 W3) Lane config and prompt defaults move to .work/lanes/ (lanes.json + prompts) with a default-only legacy fallback that warns and keeps prompt_dir coupled to the pre-move layout; $CLAUDE_OPS_LANES_CONFIG stays a verbatim escape hatch that never falls back. SKILL/config docs state the literal-.work carve-out (lanes does not resolve memory_dir) and keep the open durable cross-machine need honest. work-items triage's reference and eval follow, with its own 0.39.43 bump per the parity gate. claude-ops 0.40.0. Verified by a fresh-context agent: defaults, fallback coupling, and env escape hatch confirmed in code; 213+153+24 suite cases pass; shellcheck clean; the one blocking defect (missing work-items bump) fixed here. The reserved lanes/ roster row in the topic-docs README lands in this PR's flip commit, atomically with this change. Refs #3554 (thread T7). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018zeKDi1TCmryAkU28BjQuD
…S.md (v3 W2) Thirteen reference sites move the source-inventory/representation layer off the INDEX.md name (freed for the topic-docs v3 per-slice index) with semantics untouched: digest-unit parity, resume protocol, and pin-manifest hash-freeze read identically. Per the fresh-context verifier's one blocking finding, resume now accepts a pre-0.13.30 work root's INDEX.md as the Phase 2 artifact (rename-and-continue, never re-inventory) and a legacy pin-manifest re-pins under the new name instead of going BLOCKED. Released changelog history keeps the old name as immutable record. knowledge 0.13.30. Refs #3554 (thread T6). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018zeKDi1TCmryAkU28BjQuD
…th grading (W5+W6) W5 — lib/index-regen.sh regenerates the marker-delimited body of a slice INDEX.md from its children's frontmatter (slice/abstract/status/children mini-schema per design threads T1-T4) and checks declared-children parity in both directions via T5's child-slice predicate. Exit codes: 0 ok, 1 parity, 2 shape, 3 size cap (body preserved, two levers named). Guards: emphasis-span abstracts rejected (formatter-oscillation class), column-0 list-marker continuations rejected, duplicate declared children caught before the membership walks. 79-case test suite; registered copy at plugins/discovery/scripts/index-regen.sh kept byte-identical by scripts/sync-index-regen.sh and the new index-regen-sync CI job. Cross-plugin registry line stays commented until a second plugin consumes the script (single-copy drift is the sync job's to catch). W6 — check-dispatch-artifact.sh grades the exact assigned path only; the in-gate slice scan and worker-side collision escape are removed. The parent resolves one path before dispatch and the gate answers for that path alone. Collision handling moves parent-side: a worker finding its assigned root occupied reports through the persistence: by-value payload instead of picking a sub-slice, and the parent assigns the collision sub-slice, writes there, and re-runs the gate against its own choice, dropping --expect-index on that re-run since the payload pointer names the blocked root. Instruction surfaces updated across explore/research skills, the explorer agent definition, and both dispatch references; gate tests extended to pin the no-scan behavior. discovery 0.17.0 (minor: gate contract change + new registered script). Topic-docs v3 wave, Phase 1 workstreams W5+W6 (T1-T5); epic #3554.
…e INDEX.md (flip) The normative flip over the wave's committed substrate. The contract README moves to v3: recursive slices (a slice is a slice at every depth) with lazy level creation scoped to topic slices; INDEX.md reserved at every depth and required for slices with children or more than one artifact family; read-first binding; frontmatter as the single home for slice/abstract/status/children with the ordered children list as the curated order; marker-delimited generated body regenerated by lib/index-regen.sh with exit codes 0/1/2/3 and the ~25KB fail-with-hint; the T5 child-slice predicate and reserved-name precedence; interior freedom; the exact-assigned-path gate rule with parent-assigned collision sub-slices; corpus-seam relationship; lanes/ reserved concern row; the depth-proof .worktreeinclude consumer recipe with the carry claim softened to what W1 verified and the deliberate corpus-carry note. Coupled surfaces flip in the same commit: PLUGIN-ARTIFACT-PROTOCOL v3 (INDEX.md joins the memory-tier kinds) with its five registered copies re-synced byte-identically; the schema's memory_dir description names the recursive tree and the full reserved roster; the worked example gains the now-required index; discovery's artifact-shape spec carries the T3 abstract corollary for all three index families; map-corpus hard-binds corpus writes to the library_dir seam; docpage-digest's SOURCES.md prescription gains the abstract: frontmatter hook a parent regen mirrors (flip-verifier finding); the docs-hygiene ghost-ref exemption roster gains lanes and the long-missing exports. The ten per-plugin bindings and three setup skills were audited and need no delta change; the verifier confirmed the no-op. Contract CHANGELOG 3.0.0 major entry; bumps: discovery 0.18.0, knowledge 0.13.31, docs-hygiene 0.21.31, planning 0.34.16, implementation 0.15.9, verification 0.5.11, overengineering 0.3.5. Also restores discovery's 0.16.18 changelog heading the W5+W6 commit accidentally absorbed. Graded by a fresh-context verifier against the Brief and design threads: 9/10 criteria PASS, the one minor defect fixed here as prescribed; all suites green (79 regen checks, 201 docs-hygiene checks, 3068 contract files, 144 shell + 6 python suites). Refs #3554 (topic-docs v3 wave, Phase 2). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018zeKDi1TCmryAkU28BjQuD
…erarchy-rishvz # Conflicts: # plugins/claude-ops/.claude-plugin/plugin.json # plugins/claude-ops/CHANGELOG.md
|
Claude finished @kyle-sexton's task in 3m 2s —— View job Claude security review
Ran the Skip gate: PR is open. A prior pass already reviewed everything through This range carries real new logic (73 files, ~2,829 insertions), so I read every changed script and workflow file rather than skipping:
Result: no security issues found. Nothing in this range touches authentication, authorization, secrets handling, or introduces an injection/trust-boundary risk. |
…erge Final lifecycle step per the topic-docs convention (now v3, shipped on this same PR): the locked Brief stays durably recorded in PR #3552's description; the wave plan (PLAN.md) and the nine resolved design threads (design/design-threads.md) are retrievable at this branch's pre-prune commit ac7c0d3, named in PR #3557's body per pointer discipline. Net PR diff now carries no docs/topics/** path, so the contract-slice-prune-gate goes green. Refs #3554. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018zeKDi1TCmryAkU28BjQuD
kyle-sexton
changed the title
Accepts the topic-docs v3.0.0 adoption (#3557), which prunes contract slices from main, including docs/topics/context-engineering-claude-5/ and the corpus input note this branch had placed inside it. That note's actionable payloads already carry tracker receipts (#3565 the I15 boundary reopen, #3566 the unhobbling security caveats), and its settled upstream facts live in this branch's graduated knowledge docs, so the prune loses no content. The remaining payloads (the sibling plan's rerun-contract drift and its corroboration venue wording) are moot: main deleted both documents. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016uCQCPBraw7iVZ61F83EAJ
…instruction exception register (#3588) No related issue: this PR is the corpus absorption itself; the actionable follow-ups it produced were filed as their own issues (#3562-#3568, #3598) and are referenced below rather than closed here. ## Summary Absorbs the context-engineering corpus (the trq212 "New rules of context engineering for Claude 5 models" X article of 2026-07-24, the Anthropic "Effective context engineering for AI agents" engineering post of 2025-09-29, and the nine first-party pages they link) into this repository: five graduated knowledge documents, one new convention with its wiring, and three skill corrections. The upstream facts it rests on were verified against current official surfaces, and the answer set was validated by two independent fresh-context arms before sign-off. Per topic-docs v3.0.0, the decision contract is contract tier: it was committed on this branch as it locked and pruned before merge. It is pasted at the bottom of this body, and its durable outcomes graduated through the knowledge-vault seam into `docs/specs/`. ## Fix **Graduated knowledge**, `docs/specs/context-engineering-*.md`, moved out of the contract slice by history-preserving `git mv`: - `corpus-knowledge.md`, both primary sources by theme with byte-verified quotes, the figure-borne facts that exist in no text on either page (the approximately 9,100-character TodoWrite tool description, the six-layer context stack), the settled upstream facts, custody findings CF-1 to CF-7, and an appendix carrying the three system-prompt calibration prompts verbatim, transcribed from the figure image and re-verified by a second reader. - `critical-apparatus.md`, 142 of 318 swept assumption, omission and tension rows, the cross-source tensions (including the few-shot reversal between the two primaries), the unstated interface-versus-behavior thesis, and ten adoption guardrails. - `linked-sources.md`, the nine linked pages with citations, mechanisms and numbers, including the dynamic-workflows API surface and the multi-agent token economics that upstream publishes only inside figures. - `vertical-decisions.md`, verticals V2 to V7 resolved here rather than deferred, four of them to no change with the reason recorded, plus the one V1 answer (post-upgrade instruction re-testing) whose disposition had no other durable home once the contract was pruned. - `deletion-evidence-attribution.md`, the mechanism the consequential deletion tier needs, and why a per-rule bare experiment is not affordable. **New convention.** `docs/conventions/instruction-exception-register/` answers the "except in highly important areas" carve-out that subtractive instruction guidance leaves undefined. It adopts Gate 0's six consequence classes by reference rather than forking them, and adds the operation Gate 0 does not govern: deletion. Non-exhaustive and tighten-only, so omission never licenses a cut. **Wiring, in the same change**, because an unconsumed register changes no behavior — every consumer the register's table names now reads it: - `audit-instructions` criteria I1, I4 and I5 hold a protected candidate and propose compression instead of deletion. I1 carries the reason its own bar cannot see the problem: it asks whether removal would change behavior *today*, and a protected rail's removal changes behavior only on the occasion it was written for. - `unhobble` Phase 4 no longer ends at "everything the ledger did not defend stays deleted". A rule matching a protected class is restored whether or not the ledger logged against it, since a rail whose absence is unrecoverable will not usually announce itself inside one experiment window. The strip stays permitted — it is reversible and branch-local — and register holds are tallied separately so restoring one is not miscounted as a deletion the ledger defeated. - `instruction-placement`'s routing rubric names the register as the deletion counterpart, so one concern keeps one adjudication chain and the class list keeps one owner. **Skill corrections.** `session-flow:orchestrate` reconciles its 3-10x token-multiplier line against the upstream ~15x measurement it conflicted with, and carries the 1-2k condensed-return magnitude with its citation. **Upstream-drift near-miss.** `docs/conventions/upstream-drift/CHANGELOG.md` gains a 1.6.3 entry recording a silent-revision near-miss adjacent to its content-hashing deferral, with the trigger explicitly not fired and the deferral text untouched. ## Verification - `scripts/affected-tests.sh --run`: 30 selected suites on the final tree, all passed or skipped, zero failures. - Net PR diff contains no path under `docs/topics/**`, satisfying `contract-slice-prune-gate`. - `scripts/check-changelog-parity.sh` `--check`, `--check-bump`, `--check-order` and `--check-preserved` all pass against `origin/main` after the three plugin bumps. - Every relative markdown link in the changed files was resolved against the working tree; all 10 files, zero broken. - Upstream facts verified against current official surfaces and cross-checked by a second fresh-context arm with five spot-fetches, all reproducing verbatim: the `#` memory hotkey was removed in changelog v2.0.70; `/doctor`'s documented behavior per `commands.md` (v2.1.205 and v2.1.206) trims, dedupes and migrates CLAUDE.md guidance and finds unused skills by context cost, and no official surface describes skill-content "rightsizing"; the memory tool spans all Claude 4 and later models with no beta header while context editing remains beta, and Claude Code exposes neither natively. Recency anchor: Claude Code v2.1.252. - The 80% system-prompt reduction figure appears on no official documentation surface; it is recorded OPINION-tier with directional corroboration from changelog v2.1.154, citing both first-party carriers. - Corpus slices passed their standing byte-exactness gates through four correction rounds; the two verification arms per slice were same-vendor, and that degradation is recorded rather than hidden. - Answer set validated by two independent fresh-context arms with the recommendation rationale withheld: 14 of 14 confirmed, zero challenged, one premise correction absorbed. ## Related - Refs #3562, #3563, #3564, #3565, #3566, #3567, #3568 — the execution receipts this PR files work against: the exception register's follow-ups, the deletion-evidence attribution design, the orchestrate reconciliation, the I15 boundary reopen, the unhobbling security caveats, the content-hash designed issue, and the shared-surface governance decision. - Refs #3598, the `work-item-tracker` `create-item` version-guard defect found while filing those receipts (`gh >= 2.94` is required unconditionally, so a create needing none of the gated features is refused on `gh` 2.45). - Refs #3552 / #3557, the topic-docs v3 clean-break wave, which landed mid-effort and is the reason this PR's contract slice is pruned rather than committed. - Refs #3592, the Finding Your Unknowns corpus integration, which landed `docs/FINDING-YOUR-UNKNOWNS.md` mid-effort; this PR's field-guide reference points at it. ### Contract-slice pointers (topic-docs v3, prune with pointer) - Pre-prune commit (the last one that still held the slice): `1f7a11a4`. Under squash-merge this SHA form is best-effort; the graduation targets below are the load-bearing record. - Durable outcomes graduated to: `docs/specs/context-engineering-corpus-knowledge.md`, `docs/specs/context-engineering-critical-apparatus.md`, `docs/specs/context-engineering-linked-sources.md`, `docs/specs/context-engineering-vertical-decisions.md`, `docs/specs/context-engineering-deletion-evidence-attribution.md`, and the new convention at `docs/conventions/instruction-exception-register/`. - Actionable follow-ups graduated to the work-item tracker as the issues listed above. --- ## Approved decision contract (pruned `docs/topics/context-engineering-integration/PLAN.md`) Pasted verbatim per the prune-with-pointer lifecycle. GitHub's body sanitizer strips `<details>` here, so it is inline rather than collapsed. # Context-engineering corpus integration — decision contract ## Brief Status: **SIGNED OFF** — the operator confirmed the full sheet (Q1-Q16, all recommended dispositions as presented) on 2026-09-01 ("lets go with those"), satisfying the standing directive of 2026-08-31 ("I will confirm final answers for ALL questions... I want final sign off"). Q15 resolved: **finish** the prior plan (phases 8-11, with the corpus input note as a mandatory Phase 10 input). Q16 resolved: **topic-docs v3 wave first**; Q11/Q12/C1-class work executes against v3 shapes. Execution proceeds per the contract below. Grounded as of commit `335081c6` (origin/main, fetched 2026-09-01). Evidence artifacts live in the session's memory tier (`.work/context-engineering-integration/` and `.work/context-eng-corpus/`): two byte-verified docpage-digest slices (P1 = the trq212 "New rules of context engineering for Claude 5 models" X article; P2 = the Anthropic "Effective context engineering for AI agents" engineering post, published 2025-09-29), nine deep tier-2 page inventories, a fresh unbiased paragraph-grain sweep with four-lens critical apparatus, bidirectional reconciliation against the prior plan and field-guide audit, a master coverage ledger, verified EXPLORE/RESEARCH artifacts, blindspot cards B1-B10, brainstorm candidates C1-C12, and a fresh-context devils-advocate report (1 CRITICAL / 4 HIGH). The memory tier is never committed; this Brief is the durable record and inlines every decision-bearing fact. ### TLDR Absorb the two-article context-engineering corpus (plus its nine linked pages) into this marketplace's decision record, and integrate what earns its place: inputs to the in-flight `context-engineering-claude-5` plan, a small set of doc+wiring artifacts, two skill-vocabulary extensions, and recorded settled facts — under OPINION-tier/provenance discipline, with everything gated on the operator's final sign-off. ### Goal A signed-off answer set (Q1-Q14) that routes every corpus finding to a named, durable home — or an explicit deferral — without duplicating the prior plan's territory, silently expanding its locked Brief, or authoring against surfaces that have drifted. ### Constraints - Final sign-off gate: the operator confirms ALL answers; "go with recommended" assembles the sheet, never skips the gate. - The prior plan `docs/topics/context-engineering-claude-5/` owns the P1 instruction-audit lane; this effort never re-absorbs P1 or edits that plan's design docs unilaterally. - Memory-tier evidence is cited by content (inlined here) or by tracker item, never by bare `.work` path in anything meant to outlive the session. - Sequencing: the work-folder-hierarchy / topic-docs v3 clean-break wave (#3552, Brief locked 2026-09-01) restructures the `.work` substrate; Q12/C1/B9-dependent work orders against it (operator sequencing question on the sheet). ### Provisionally locked answers (rounds 1-2; refined by blindspot/devils-advocate; ALL pending sign-off) - **Q1 (deletion evidence threshold):** two-tier — editorial audit-instructions pass may delete trivial legacy guards; consequential rules need ledger evidence. Refinement (B5 + DA-MEDIUM): express the consequential tier in unhobble's existing two-rows-same-cause grammar, BUT that grammar currently defends re-adds after a full strip, not per-rule deletions — the deletion tier needs an attribution design (observation window, same-cause rule) before it becomes a skill edit. - **Q2 (exception register):** yes — a docs/conventions owner doc naming the "highly important areas" where hard constraints stay. Refinements (B2 + DA-MEDIUM): inert unless wired — same change names it in consuming skills' criteria text; register is NON-EXHAUSTIVE with a tighten-only clause; cross-referenced from instruction-placement's routing-rubric (Gate 0) so one concern keeps one adjudication chain; omission never licenses deletion. - **Q3 (conflict coverage):** superseded by evidence — audit-instructions I15 scopes conflicts to resident-surface pairs BY RECORDED DESIGN (its criteria file cites the article's user-request example as Source). The user-request-clash axis is a boundary REOPEN with a detectability answer, filed as an OPINION-tier detector candidate to the prior plan's catalog via tracker item (see Q8/C9), not a simple extension. - **Q4 (/doctor):** verification DONE by research — commands.md (v2.1.205/206): /doctor trims/dedupes/migrates CLAUDE.md guidance into skills and finds unused skills by context cost; no official surface says "rightsize" or skill-content simplification. The audit-native-overlap run is unnecessary (Q9); repo docs citing /doctor cite commands.md. - **Q5 (80% claim posture):** OPINION-tier WITH directional-corroboration annotation. Carriers (corrected 2026-09-01 by validator 2): the X article AND its claude.com/blog twin (the-new-rules-of-context-engineering-for-claude-5-generation-models) both carry the figure — under the repo's recorded precedent (audit-instructions criteria.md:153-158) a vendor blog corroborates rather than defines, so the tier stands; changelog v2.1.154 ("lean system prompt is now the default") corroborates direction only. Magnitude and "no measurable loss" stay vendor-voice (verifier's world-truth ruling); scope qualifier ("on our coding evaluations") always carried. Never phrase the annotation as "no official surface carries it" — falsifiable in one fetch. - **Q6 (model-upgrade re-test):** documented trigger only; the shipped `audit-pass` re-run contract (lease/epoch, suppression, three-scope inventory) is the ritual vehicle. Cite shipped reference files, not design/rerun-contract.md (drifted; flagged to plan owner). - **Q7 (prior-plan relationship):** fresh unbiased pass FIRST (executed 2026-08-31: 10 fresh sweeps, 4 reconciliation adjudications, coverage ledger); prior work is one reconciliation input. Residual decision → sign-off sheet: is the prior plan alive (resume / finish / absorb-and-close)? Routing without that answer is burial. ### Open questions for the sign-off sheet (recommended dispositions; operator decides) - **Q8:** split the gap-cluster routing — only execution-changing inputs (I15 reopen, rerun-contract drift, CF-7 wording, P2-never-engaged) go to the prior plan via the C2 note + phase-section references + tracker items; G-SEC (guardrail-deletion / memory- poisoning security) becomes its OWN work item now (security cost of burial); G-THESIS + G-PRECOND ride with the corpus critical apparatus (Q12); G-GOV is green-field with C10. - **Q9:** drop the audit-native-overlap /doctor run (evidence inlined at Q4); CF-7 filed as a wording fix, tier logic unaffected (venue characterization was litigated in #2036/#2057 — the note engages that history, headline softened from "authority-inflating"). - **Q10:** adopt the prior plan's OPINION-tier vocabulary corpus-wide + snapshot-dated citations. REVISED per devils-advocate: CF-1 does NOT fire upstream-drift's recorded content-hashing reopen trigger (no committed stale stamp caused a defect) — record CF-1 as adjacent near-miss evidence in a dated changelog entry per that convention's own v1.6.2 precedent, and file the hash store as its own designed issue via tracker; do not edit the deferral text. - **Q11:** cite-only now; graduation + custody policy deferred to V7, sequenced after the topic-docs v3 wave. - **Q12:** critical-apparatus home rides the corpus slices pending V7 + v3 sequencing; the durable pointer is this Brief + tracker items. - **Q13:** apply the P2-slice zero-cost merges as corrections round 4 (bakery transcriptions, compaction caveat C105, sub-agent economics) with re-pin + re-verify — noting the slice is memory-tier until Q11/V7 graduation decides otherwise. - **Q14:** the dated input note lands under the prior plan's `design/` per topic-docs, is referenced from PLAN.md AND from the phase sections it gates (Phase 8 criteria edits, Phase 10 reconcile) in the same commit, with tracker items for each actionable payload. ### Validation record Two independent fresh-context validators (rationale withheld, devils-advocate evidence discipline, 2026-09-01) each audited all seven locked decisions: 14/14 CONFIRMED, 0 CHALLENGED, 0 RECLASSIFIED. Standing findings carried to execution: (1) D3's tracker item must be written to survive an absorb-and-close outcome on Q15; (2) D1's consequential tier is deliberately unclearable until its attribution design exists — the ordering is enforced, not incidental; (3) Q5's annotation cites both first-party carriers (above); (4) D2's same-change wiring into shipped skills respects the repo/product "two hats" boundary unhobble records. ### Captured assumptions - Same operator owns this effort, the prior plan, and the topic-docs v3 wave; sequencing is theirs alone (sheet question). - Claude Code surfaces verified 2026-08-31/09-01 (v2.1.252 changelog recency gate); any execution re-verifies against then-current surfaces per the repo's upstream-drift discipline. - The `#` memory hotkey is REMOVED (changelog v2.0.70) — settled fact, recorded; the memory tool and context editing are platform-side (memory tool: all Claude 4+ models, no beta header; context editing: beta) and Claude Code exposes neither natively (analogues: auto-memory, compaction). ### Out of scope - Re-absorbing P1 into a second plan; editing the prior plan's design docs beyond the Q14 note; implementing C6-C12 before sign-off; graduating corpus slices before V7/v3 sequencing; referenced-external sources (Karpathy, context-rot study, arXiv, Willison) beyond cataloging. ### Acceptance criteria - The sign-off sheet presents ALL of Q1-Q14 in their refined forms with the operator's explicit confirmation recorded per answer; no answer executes unconfirmed. - Every accepted routing has a durable receipt (commit, tracker item, or phase-section reference) — nothing disposed by memory-tier note alone. - Post-sign-off execution follows the per-unit loop: one artifact at a time — apply, verify (the repo's own gates), close. ### Deferred questions All USER-RESERVED items were resolved by the operator's sign-off (2026-09-01, full sheet); none remain deferred. Resolutions and receipts: - Q8 — split routing ADOPTED: execution-changing inputs via the design note; G-SEC → #3566; G-THESIS/G-PRECOND ride the corpus; G-GOV → #3568. - Q9 — /doctor overlap run DROPPED; CF-7 wording fix carried in the note (payload 4). - Q10 — ADOPTED as revised: upstream-drift CHANGELOG 1.6.3 near-miss entry (deferral untouched, trigger not fired); hash store → #3567. - Q11 — cite-only now; graduation deferred to V7, after topic-docs v3. - Q12 — critical apparatus rides the corpus slices pending V7 + v3; this Brief + trackers are the durable pointers. - Q13 — EXECUTED: P2-slice corrections round 4 applied (figure transcriptions, compaction caveat, economics grounding), PNG re-verified, standing gates 12/12 PASS, re-pinned. - Q14 — EXECUTED: `design/corpus-input-2026-09-01.md` + header/Phase 8/Phase 10 references in the prior plan (one commit). - Q15 — FINISH the prior plan (phases 8-11; the note is a mandatory Phase 10 input). - Q16 — topic-docs v3 wave FIRST; v3-dependent work (Q11/Q12/C1-class) sequences after it. ### Execution receipts Tracker items: #3562 (C6 exception register), #3563 (C7 deletion-evidence attribution design), #3564 (C8 orchestrate reconciliation + annotation), #3565 (C9 I15 boundary reopen, written to survive any prior-plan outcome), #3566 (G-SEC security caveats), #3567 (hash store designed-issue placeholder), #3568 (G-GOV ownership decision). Commits: 6b7cd13 (contract), 48d851e (validator findings), 0c8bc33 (C2/C3/C5 batch), plus this one. Operational note: the work-item-tracker seam's `create-item` requires gh >= 2.94 and this cloud environment ships 2.45 (seam exit 3), so receipts were filed through the bound GitHub adapter's provider-mechanic path (repo-scoped REST) — coordination verbs (claim/lease) were not needed for solo-session creates. ## Plan (Empty — `/planning:plan` fills this after sign-off.) --- ### Post-sign-off amendments Two decisions above were overtaken by events after sign-off, and the amendment is recorded here rather than by editing the signed text: - **Q14** named the prior plan's `design/` as the input note's home. That slice was pruned from `main` by the topic-docs v3.0.0 adoption (#3557) while this work was in flight, so the note has no home. Its four payloads survive elsewhere: the I15 reopen as #3565, the P2-never-engaged finding in `context-engineering-critical-apparatus.md`, CF-7 in `context-engineering-corpus-knowledge.md` (recorded for the pattern, since the document it corrected no longer exists), and the rerun-contract drift moot for the same reason. - **Q11/Q12** deferred graduation and the critical-apparatus home to V7 "after the v3 wave". V7 resolved to graduate now rather than defer, because the memory tier does not survive a session; see `docs/specs/context-engineering-vertical-decisions.md`. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_016uCQCPBraw7iVZ61F83EAJ --------- Co-authored-by: Claude <noreply@anthropic.com>
2 participants
Closes #3554
Summary
The complete topic-docs v3 wave, executed per the locked Brief (durable record: PR #3552 description, pre-prune SHA
dd975248419d0d40083cebd9b9a009cd6a92ece4): design threads, staged plan, six substrate workstreams, the normative flip to contract v3.0.0, and the final contract-slice prune. Single atomic PR with commits ordered substrate → flip, per the plan's deviation note (the Brief's multi-PR staging exists so nothing partial reaches main; one PR is the strictest form of that atomicity).Contract-slice record (lifecycle: pruned before merge)
The slice
docs/topics/work-folder-hierarchy/rode this branch and is pruned in the final commit. Retrieval pointers (pre-prune commitac7c0d36ab, the last commit containing the slice):PLAN.md(phased wave plan)ac7c0d36ab:docs/topics/work-folder-hierarchy/PLAN.mddesign/design-threads.md(nine resolved threads, verifier-gated)ac7c0d36ab:docs/topics/work-folder-hierarchy/design/design-threads.mdFix
Contract v3.0.0 (
docs/conventions/topic-docs/README.md, clean-break major): recursive slices (a slice is a slice at every depth) with lazy level creation;INDEX.mdreserved at every depth, required for slices with children or more than one artifact family; read-INDEX-first binding; frontmatter (slice/abstract/status/children) as the single home for state with the orderedchildren:list as the curated order (no numeric prefixes ever); marker-delimited generated body; exact-assigned-path dispatch gate with parent-assigned collision sub-slices;lanes/reserved concern row; corpus-seam rule; depth-proof.worktreeincludeconsumer recipe.Substrate (Phase 1):
.worktreeincludecarry +worktree-create.test.shdepth coverage; source-control 0.55.35.INDEX.md→SOURCES.md(13 sites) with rename-and-continue legacy resume; knowledge 0.13.30..work/lanes/with loud legacy fallback; claude-ops 0.40.0, work-items 0.39.43.docs/topics/slices pruned (per-slug pre-prune SHAs in the table below);contract-slice-baseline.txtnow entry-less (topic-docs: graduate and prune the 17 contract slices already on main #1419 complete).lib/index-regen.shregenerates slice-index bodies from child frontmatter and checks declared-children parity both ways (79-case suite); synced discovery copy +index-regen-syncCI job.check-dispatch-artifact.shgrades the exact assigned path only; collision escape moved parent-side across discovery's instruction surfaces; discovery 0.17.0.Flip (Phase 2): README v3 +
PLUGIN-ARTIFACT-PROTOCOLv3 with its five registered copies re-synced byte-identically; schemamemory_dirdescription; worked example; T3 abstract corollary in discovery's artifact-shape spec; map-corpus hard-bound to thelibrary_dirseam; SOURCES.mdabstract:frontmatter hook; docs-hygiene ghost-ref roster gainslanes+ long-missingexports; contract CHANGELOG 3.0.0; bumps: discovery 0.18.0, knowledge 0.13.31, docs-hygiene 0.21.31, planning 0.34.16, implementation 0.15.9, verification 0.5.11, overengineering 0.3.5. The ten per-plugin bindings and three setup skills audited as deltas-only: no contradiction with v3, no edits needed (verifier-confirmed no-op).Merge with main resolved en route (claude-ops kept 0.40.0; main's 0.39.2 entry preserved). One commit-hygiene note: the W5+W6 commit initially absorbed discovery's
[0.16.18]changelog heading; the flip commit restores it with its original content (sanctioned by the parity script's #2388 note).W4 record — pruned pre-gate slices (pre-prune SHAs)
cd09b09cc97bb841f9570e4ba965bd9c4f24b343cd09b09cc97bb841f9570e4ba965bd9c4f24b34301c8c6f3aada6710014aa299c43c70c65d1d6f48cd09b09cc97bb841f9570e4ba965bd9c4f24b343cd09b09cc97bb841f9570e4ba965bd9c4f24b343cd09b09cc97bb841f9570e4ba965bd9c4f24b343b85544815b12feb986fc84777d2af01a1d2f09bbcd09b09cc97bb841f9570e4ba965bd9c4f24b343cd09b09cc97bb841f9570e4ba965bd9c4f24b343cd09b09cc97bb841f9570e4ba965bd9c4f24b343c70d8867ccd9f9921fdde25de70cb9a91e718c80Coverage audit (recorded on epic #3554): the eleven survived a wired gate because
--check-diffjudges only landed paths, never pre-existing slices; remaining narrow gaps noted there (links not policed,--checkverifies directory not content, slug-keyed exemptions).Verification
check-changelog-parity.sh --check-bump/--check-preserved(901 headings),validate-plugin-contracts.mjs(3068 files),sync-index-regen.sh --check,check-cross-plugin-source-drift.sh, actionlint,scripts/affected-tests.sh --run(144 shell suites) + the 6 Python suites.contract-slice-prune-gatered mid-flight by design (slice riding the branch); green after the final prune commit.Related