docs(topic-docs): ship contract 2.0.0 — visibility guarantees + seam fixes R1-R6

[kyle-sexton]

Topic-docs contract 2.0.0 — visibility guarantees + seam fixes R1–R6

Phase 5 of the plugin-philosophy program (PR B of the chain; PR A was #257). One-wave
contract-major adoption: owner doc, 8 implementer delta docs, 2 skill fixes, and the repo's own
materialization of the native mechanisms, landed atomically.

No linked issue.

Related

• docs: extend plugin doctrine — component stances, native-first, official-docs index #257 — PR A of the program: the doctrine wave this contract release implements.

What changed

• R6 owner doc (docs/conventions/topic-docs/README.md): new normative "Visibility across
  execution contexts" section — context × tier visibility matrix; four native mechanisms
  (worktree.baseRef: "head", .worktreeinclude, by-value worker returns with
  orchestrator-writes, tracker as the cross-lane index); WorktreeCreate-hook caveat;
  settings.local.json override escape hatch; pointer discipline on durable surfaces;
  consumer-adoption section. Versioning rule amended: a visibility-guarantee change is major
  (that amendment is what makes this release's 2.0.0 label honest — no tier/key/slug change).
  Implementers table reconciled with the fleet: verification + toolchain rows added, Binding
  column distinguishes delta-doc implementers from adopt-by-reference rows, and the verification
  manifest/baselines moved from the implementation row to the new verification row (matching the
  plugins' actual bindings).
• R1: committed .claude/settings.json with worktree.baseRef: "head" — verified honored at
  project-settings scope on CC 2.1.212, including from linked worktrees (control+treatment smoke
  tests; a linked-worktree session reads its own checkout's settings). .claude/worktrees/ added
  to .gitignore (the runtime .git/info/exclude entry is machine-local; fresh clones and CI
  checkouts lack it).
• R2: .worktreeinclude carrying stage ledgers and EXPLORE.md/RESEARCH.md into new
  worktrees (one-way, creation-time, gitignored-only); baselines and raw scratch deliberately
  excluded (machine-bound).
• R3: /work-items:decompose ticket provenance cites the PR carrying the plan, never the
  prunable contract-slice path; /planning:architect baseline step records distilled values only
  in PLAN.md, never memory-slice capture paths.
• R4/R5 (owner-doc text): isolated workers return results by value and the orchestrator
  writes contract/durable tiers in the parent checkout; the work-item tracker is the cross-lane
  awareness layer (markdown-in-tickets as primary artifact store rejected — not diffable, no
  review gate, drifts from code).
• Implementer wave: all 8 delta docs (plugins/*/reference/topic-docs.md) adopt 2.0.0; each
  touched plugin gets a minor version bump + CHANGELOG entry (discovery 0.6.0, implementation
  0.7.0, planning 0.17.0, review 0.11.0, session-flow 0.8.0, toolchain 0.3.0, verification 0.2.0,
  work-items 0.9.0, source-control 0.5.2 for the review-driven sync-check fixes — several
  re-bumped over releases that landed on main mid-flight).

Rollout notes

• Repo behavior change: every worktree Claude Code spawns in this repo (including subagent
  worktrees) now branches from local HEAD instead of origin/HEAD. A personal
  .claude/settings.local.json silently overrides this machine-wide — nothing may assume the
  setting universally in force.
• Pull collision: a clone already holding an untracked .claude/settings.json hits
  "untracked working tree file would be overwritten" on pull — move the file aside, pull, merge
  values back.
• Mixed-fleet window: installed plugin caches and in-flight branches keep 1.x text until they
  update — safe because no tier/key/slug-spec changed; divergence is doctrinal, never
  layout-corrupting. In-flight branches sweep stale visibility text when they merge.
• Windows: deep repository base paths can trip git's path limit inside nested worktrees
  ('$GIT_DIR' too big); this repo's base (~95 chars) is safe.

Verification

Drift check --check, validate-plugins.sh (incl. catalog --check), markdownlint (46 files, 0
errors), delta-doc/Implementers-table parity both directions, 8/8 version-bump coverage, gitleaks
clean on the new tracked files. Phase 4 empirical evidence (worktree semantics, CC 2.1.212) is in
the PLAN's verdict table below.

PLAN.md (contract slice — pruned before merge per its own lifecycle)

plugin-philosophy

Brief

TLDR

Extend the plugin doctrine to the full current component surface (13 component types, official docs
fetched 2026-07-17), lock a native-first principle with a maturity gate, fix the topic-docs two-tier
convention's visibility seams with native mechanisms, ship a complete official-doc link index, adopt
marketplace metadata maximally — then run a fanout conformance audit of all 47 plugins whose findings
graduate to tracker-managed remediation waves.

Goal

Every plugin measurably conforms to an extended, freshness-guarded doctrine; no custom mechanism
exists where a fitting native one does; every cross-plugin convention has exactly one registered
owner doc; the remediation program lives on the work-item tracker where any session or machine can
resume it.

Locked decisions

#	Decision
D1	Deliverable = doctrine revision + fleet-consistency audit, coupled in this one Brief. CI contract-gate automation deferred to follow-on (trigger: audit reveals automatable checks).
D2	Doc-link index is a first-class deliverable: every plugin-relevant official doc page linked (components mapped to their doc pages); no undocumented component types.
D3	Native-first principle: prefer built-in native mechanisms (userConfig, native component types, native lifecycle events) over custom extensibility points; custom only on genuine misfit, with the misfit documented.
D4	Native-adoption gate (qualifies D3): adopt a native mechanism when it (1) fills a real existing gap, (2) is stable and works cleanly — experimental/immature features wait for maturity, (3) meets repo standards. Never custom-build what a fitting native mechanism covers.
D5	Cross-plugin cooperation: hybrid. Native dependencies reserved for hard requires (plugin genuinely broken without collaborator) — none exist today; the {name}--v{version} git-tag release step lands with first use. Optional collaboration stays presence-gated with documented fallbacks; artifact protocol unchanged (data handoff, which dependencies don't cover).
D6	Component stance table: skills = primary surface (new frontmatter — paths, context: fork, arguments, skill-scoped hooks/once — adopted case-by-case); commands/ prohibited (officially legacy); agents, MCP, LSP, output styles, bin/ = adopt-on-need (bin/ requires collision-safe prefixed names; doctrine notes plugin agents ignore hooks/mcpServers/permissionMode); plugin settings.json agent (main-thread takeover) prohibited by default, exception needs documented justification; monitors, themes, channels = wait (experimental/immature), re-verified against current docs before each audit; dependencies per D5. Hooks addition: exec-form (args) mandatory wherever ${user_config.*} appears (v2.1.207), else the CLAUDE_PLUGIN_OPTION_<KEY> env mirror.
D7	Freshness rider on all doctrine artifacts: every stance/inventory row carries a verified-date + link to its official doc page and an explicit disclaimer that the platform changes constantly — always re-fetch current docs before acting; never trust the repo file alone.
D8	userConfig full-potential criterion: every personal/administrator scalar flowing through a custom channel (env-var toggle, gitignored personal file, documented hand-edit) migrates to userConfig using the full native schema — correct type, default preserving zero-config behavior, required only where truly blocking, sensitive: true for secrets, claude plugin install --config documented in each setup skill for headless use. Shell consumers read the native CLAUDE_PLUGIN_OPTION_<KEY> mirror; custom env vars retired. Ownership table otherwise unchanged. Guardrails HOOK_<NAME>_ENABLED toggles = flagship migration (userConfig booleans, default: true).
D9	Setup doctrine v2: setup skill required iff (a) consumer-project config surface, (b) external prerequisites (CLI, service, credential), or (c) non-trivial userConfig — criteria applied through the modular/configurable/repo-/machine-/user-agnostic lens, never blanket ceremony; zero-config zero-prereq plugins exempt. Uniform contract: skill named setup, disable-model-invocation: true, check (read-only inspect/verify) + apply (idempotent configure) actions, complete-args non-interactive path. Formatter/linter plugins gain thin check-centric setups. Native Setup hook event = sanctioned headless/CI init surface; SessionStart + ${CLAUDE_PLUGIN_DATA} manifest-diff = sanctioned runtime-dependency idiom.
D10	Runtime-prerequisite visibility: anything with a runtime prereq (e.g. jq on PATH) degrades gracefully — never a hard crash; absence is surfaced to BOTH the agent and the user, with OTel as a candidate visibility channel; no black boxes. Extends the philosophy doc's "Prerequisites and failure behavior" section.
D11	Convention registry: pointer-only section in PLUGIN-PHILOSOPHY.md — one owner doc per shared concern (topic-docs binding, skill layout + evals schema, lib/hook-utils.sh sync, report vocabularies, artifact protocol, seam phrasing); registry names and points, never restates; audit rule = per-row conformance; a new convention lands in an owner doc before a second plugin adopts it.
D12	Topic-docs tiers: keep the nature-based two-tier split and the docs/topics/ name (contents are transient topic-scoped contract docs; docs/specs/ is already the durable vault target — renaming would conflate tiers).
D13	Two-tier seam fix package (all native): R1 worktree.baseRef: "head" in committed repo settings so worktree-isolated spawns carry task-branch state; R2 .worktreeinclude with targeted memory-tier patterns (stage ledgers, EXPLORE/RESEARCH — not baselines/raw scratch; one-way creation-time copy documented); R3 pointer discipline — durable surfaces (tickets, committed PLAN) never point at prunable or gitignored paths (decompose cites the PR, not the contract path; PLAN records distilled baseline values only); R4 isolated workers return results by value, the orchestrator writes both tiers in the parent checkout; R5 the work-item tracker is the cross-lane awareness/index layer (branch files stay lane-local; markdown-in-tickets as primary artifact store rejected — not diffable, drifts from code); R6 topic-docs convention doc corrected (worktree-visibility rationale, context×tier visibility matrix, mechanisms named) — a major contract version adopted by all implementers in one wave.
D14	Doc-link index: dedicated docs/OFFICIAL-DOCS.md — complete categorized map of plugin-relevant official pages with a component→doc-page table, per-row verified-dates, the D7 staleness disclaimer, and https://code.claude.com/docs/llms.txt named as the authoritative self-updating master list. CLAUDE.md keeps its lean canonical table plus one pointer row to the index.
D15	Marketplace metadata maximalism (machine-, user-, org-agnostic posture): populate every helpful-signal field — relevance signals wherever meaningful (audit criterion per plugin), defaultEnabled: false for personal/niche-category plugins, displayName where it genuinely clarifies, complete descriptive metadata. Consumer-facing doc section on org enablement of suggestions (pluginSuggestionMarketplaces + source declaration in managed settings). Hard rule: version lives in plugin.json only, never in marketplace entries (silent-precedence trap).
D16	Audit execution: doctrine docs land first; then per-plugin subagent fanout scores all 47 plugins against a doctrine-derived checklist (~15 dimensions: setup criteria, userConfig migration, exec-form hooks, metadata completeness, component stances, registry conformance, prereq degradation, pointer discipline); findings distill into a plugin×dimension conformance matrix graduating to GitHub issues — one epic + per-wave issues (setup, userConfig, metadata, hooks, convention-seam waves) via the work-items seam; raw per-plugin detail stays memory-tier; automatable checks become the deferred CI gate's backlog.

Constraints

• Fresh-docs mandate applies at execution time: re-fetch the relevant official pages before each edit
  wave; this Brief's doc facts were verified 2026-07-17.
• Work isolated in worktree, branch docs/plugin-philosophy; PRs required, squash merge, PR title
  per Conventional Commits.
• Topic-docs convention change (D13/R6) is a major contract version; every implementer plugin adopts
  in the same release wave (the contract carries no compatibility machinery).
• userConfig migrations preserve existing behavior via default values (guardrails toggles default
  true).
• Every plugin change clears the migration playbook's gate + plugin-acceptance security review.

Acceptance criteria

• PLUGIN-PHILOSOPHY.md revised: component stance table (D6) with D7 freshness riders, native-first +
  adoption gate (D3/D4), convention registry (D11), config ownership updated (D8 criterion, exec-form
  rule, version-placement rule), setup criteria (D9), prerequisite-visibility rule (D10).
• MIGRATION-PLAYBOOK.md updated consistently (setup contract, userConfig criterion, security review
  touchpoints).
• docs/OFFICIAL-DOCS.md exists: complete categorized page map, component→doc table, verified-dates,
  staleness disclaimer, llms.txt master pointer; CLAUDE.md carries the pointer row and stays lean.
• Topic-docs convention doc corrected per R6 with visibility matrix; R1 settings entry, R2
  .worktreeinclude, and R3 skill pointer fixes (decompose ticket provenance, architect baseline
  recording) landed; the three flagged execution-time verifications resolved empirically and
  recorded.
• marketplace.json metadata complete per D15; claude plugin validate . passes.
• Audit epic + wave issues filed on GitHub with the conformance matrix distilled into the epic; every
  47-plugin row scored; raw details in the memory slice.
• Existing CI (plugin contract tests, markdownlint) green on every PR.

Captured assumptions

• Consumers run CC ≥ 2.1.207 (userConfig shell-form ban semantics, pluginConfigs scoping); older
  clients degrade per official behavior, not worked around.
• Marketplace remains the melodic-software catalog but every decision holds machine-, user-, and
  org-agnostic (no solo-consumer scoping).

Out-of-scope (deferred with triggers)

• CI contract gate — trigger: audit identifies automatable checks (D16 backlog).
• Bundle plugin (name + dependencies curated set) — trigger: one-command curated install need beyond
  the fleet-sync skill.
• Monitors, themes, channels adoption — trigger: feature exits experimental/immature status at a
  future doc re-verification (D6 wait rows).
• music → creative, deployment category, and other plugin-organization deferrals remain owned by
  that Brief.

Deferred questions

• Windows sensitive userConfig storage behavior (docs silent on Windows keychain) — empirical
  verification during audit, before any secret migrates. Arbiter: /architect (execution evidence).
• Worktree-sweep treatment of ignored files; --bg session worktree base semantics;
  worktree.baseRef honored at project-settings scope — empirical smoke tests during D13 execution.
  Arbiter: /architect.
• Per-plugin relevance signal quality (which signals are genuinely helpful vs noise) — decided
  per-plugin during the metadata wave. Arbiter: /architect.

Plan

Program log. 2026-07-17: PR A (#257, Phases 1–3 + P4 evidence) squash-merged to main; all
review findings (2 Codex inline + 2 follow-ups + 6 Claude-review) classified, fixed, and
verified; contract slice pruned on that branch and re-committed here on docs/topic-docs-2.0.0
(the PR B branch, cut from post-squash main). Phase 5 wave executed on this branch (fresh-fetched
worktrees + settings pages; all sanity checks green: drift --check, validate-plugins incl.
catalog --check, markdownlint, delta-doc/table parity, 8-plugin bump coverage). Implementers
table also corrected: verification manifest/baselines moved off the implementation row to a new
verification row. Next: PR B.

Seven phases. Doctrine docs land first (D16 ordering), the topic-docs contract major version ships as
one wave, marketplace metadata follows, and the fleet audit runs last against the landed doctrine.
The fresh-docs mandate is embedded as the first work item of every phase that states platform
facts — never a standalone phase, never skipped.

The three flagged empirical verifications resolve at their Brief-assigned execution points:
worktree-semantics smoke tests → Phase 4 (gates Phase 5 R1/R2); per-plugin relevance quality →
Phase 6 (per-plugin, during the metadata wave); Windows sensitive userConfig storage → Phase 7
(before any userConfig-wave issue touching secrets is filed).

Phase 1: PLUGIN-PHILOSOPHY.md doctrine revision [DONE]

Covers D3, D4, D6, D7, D8, D9, D10, D11.

Work items:

1. Fresh-fetch: plugins, plugins-reference, skills, hooks, settings, plugin-dependencies
   pages; re-verify the 13 component types and the D6 stance facts (skill frontmatter additions,
   commands/ legacy status, bin/ rules, agent field limitations, monitors/themes/channels
   maturity, v2.1.207 exec-form rule). Any drift from the Brief's 2026-07-17 facts is recorded in
   the memory slice and the stance table reflects current reality. The verified component-type
   count (N, expected 13) is written to .work/plugin-philosophy/component-count.txt — Phases 1
   and 3 sanity checks assert against N, not a hard-coded 13.
2. Add Native-first principle + adoption gate section (D3/D4).
3. Add Component stance table (D6): 13 rows, each with stance, rationale, verified-date +
   official-doc link (D7 rider), and the D7 staleness disclaimer heading the table.
4. Extend Configuration ownership and scope: D8 userConfig full-potential criterion (native
   schema fields, CLAUDE_PLUGIN_OPTION_<KEY> mirror, retirement of custom env channels), exec-form
   hooks rule, version-placement rule (version in plugin.json only).
5. Rewrite Setup is explicit and repeatable to the D9 v2 criteria (required-iff conditions,
   uniform setup skill contract, Setup hook event and SessionStart manifest-diff idioms).
6. Extend Prerequisites and failure behavior with D10 (graceful degradation, dual agent+user
   visibility, OTel as candidate channel, no black boxes).
7. Add Convention registry section (D11): pointer-only table — one owner doc per shared concern
   (topic-docs binding, skill layout + evals schema, lib/hook-utils.sh sync, report vocabularies,
   artifact protocol, seam phrasing); registry names and points, never restates.

Sanity Check:

• grep -c "Verified 2026" docs/PLUGIN-PHILOSOPHY.md ≥ N (one rider per stance row; N from
  component-count.txt).
• grep -n "Convention registry\|Native-first" docs/PLUGIN-PHILOSOPHY.md returns both sections.
• Component stance table row count = N; Read confirms every verified component type named.
• npx markdownlint-cli2 --config .markdownlint-cli2.jsonc docs/PLUGIN-PHILOSOPHY.md exit 0 (CI's
  pinned action is authoritative; local run uses the repo config).

Phase 2: MIGRATION-PLAYBOOK.md consistency pass [DONE]

Depends on Phase 1 (doctrine wording is SSOT; playbook points, never restates).

Work items:

1. Update the per-plugin migration gate: setup-contract check (D9), userConfig criterion (D8),
   exec-form hook rule — each as a pointer to the philosophy doc section plus playbook-specific
   procedure only.
2. Extend the plugin-acceptance security review touchpoints: sensitive userConfig handling,
   bin/ collision-safe naming, plugin settings.json agent prohibition check.
3. Remove or redirect any playbook text that now duplicates Phase 1 doctrine (no restated stance
   tables).

Sanity Check:

• grep -n "PLUGIN-PHILOSOPHY" docs/MIGRATION-PLAYBOOK.md shows pointer citations in the gate and
  security-review sections.
• No restated stance table: no markdown table in MIGRATION-PLAYBOOK.md whose header row contains
  both Component and Stance columns (Read assertion — pointers naming the section are fine).
• npx markdownlint-cli2 --config .markdownlint-cli2.jsonc docs/MIGRATION-PLAYBOOK.md exit 0.

Phase 3: docs/OFFICIAL-DOCS.md index + CLAUDE.md pointer [DONE]

Covers D14. Parallel-safe with Phase 2 (disjoint files); component list comes from the Brief/Phase 1
stance table.

Work items:

1. Fresh-fetch https://code.claude.com/docs/llms.txt; enumerate every plugin-relevant page.
2. Create docs/OFFICIAL-DOCS.md: categorized page map, component→doc-page table, per-row
   verified-dates, D7 staleness disclaimer, llms.txt named as the authoritative self-updating
   master list.
3. Add one pointer row to CLAUDE.md's canonical table; CLAUDE.md stays lean (no other growth).
4. Wave A join step (main session): reconcile the component→doc table against Phase 1's
   verified component list (component-count.txt + stance table) before PR A — parallel work off
   the Brief snapshot must converge on Phase 1's fresh-fetched reality.

Sanity Check:

• test -f docs/OFFICIAL-DOCS.md && component table has N rows (N from component-count.txt).
• grep -n "llms.txt" docs/OFFICIAL-DOCS.md and grep -n "OFFICIAL-DOCS" CLAUDE.md both hit.
• CLAUDE.md diff = exactly one added table row: git diff origin/main...HEAD --stat -- CLAUDE.md
  shows a 1-2 line delta.
• npx markdownlint-cli2 --config .markdownlint-cli2.jsonc docs/OFFICIAL-DOCS.md exit 0; the
  repo's offline link-integrity check passes on the new file (external-URL lychee lane is advisory
  weekly — spot-check a sample of new URLs via WebFetch instead).

Phase 4: Worktree-semantics empirical verification (throwaway spike) [DONE]

Feasibility spike (might change Phase 5's shape) — results are evidence, no kept code. Parallel-safe
with Phases 1–3 (touches scratchpad + throwaway worktrees only).

All tests run in a throwaway git init repo in the scratchpad with a synthetic origin —
never in this repo (its ~30 live worktrees, runtime-written .git/info/exclude, and main checkout
on a feature branch confound every measurement). Use claude -p --worktree exclusively (skips the
trust dialog; interactive mode errors in a fresh repo). Unique worktree names per run (name reuse
resets clean worktrees to base since v2.1.208); the spike removes its own worktrees
(-p-created worktrees are never auto-cleaned; Windows: expect NTFS lock retries,
git worktree remove --force).

Work items:

1. Fresh-fetch the worktrees doc (the doc anchor for baseRef/.worktreeinclude — not the
   settings page) plus settings; record cited behavior, including the documented fallback
   "when origin/HEAD isn't resolvable, worktrees fall back to current local HEAD".
2. Smoke test A — worktree.baseRef: "head" at project-settings scope, two arms: control
   (baseRef unset or "fresh") asserts marker ABSENT; treatment (baseRef: "head" in
   committed .claude/settings.json) asserts marker PRESENT. Verdict HONORED only if BOTH arms
   behave — a marker-present-only test is defeated by the documented origin/HEAD fallback (false
   positive). Variant A2: spawn from within an existing linked worktree (docs state head resolves
   to that worktree's HEAD — test against that expected value). Variant A3: settings.json present
   only in the worktree checkout vs only in the main checkout — pins which copy a linked-worktree
   session reads (undocumented; only settings.local.json is documented as main-checkout-resolved).
3. Smoke test B — .worktreeinclude one-way creation-time copy: use real nested-gitignore paths
   (.work/<slug>/… ignored via a nested * .gitignore, mirroring this repo) — not a toy
   root-level pattern; assert copy at creation; modify original, assert no sync-back.
4. Smoke test C — worktree-sweep treatment of ignored files (genuinely undocumented — this test is
   the only source of truth; capture git status --ignored snapshots in the raw transcript) +
   --bg session worktree base semantics.
5. The sub-agent records raw transcripts in .work/plugin-philosophy/verifications/, stamps every
   VERDICT file with claude --version, and returns the VERDICT lines by value; the main
   session fills the pending rows in this PLAN's "Empirical verification results" table (PLAN.md
   edits stay main-session-only) and feeds them into Phase 5's R1/R2 design. If the CC version has
   moved by the Phase 5 gate, re-run the cheap test-A control/treatment pair.

Sanity Check:

• .work/plugin-philosophy/verifications/ contains ≥ 3 result files, one per smoke test, each
  ending in a one-line VERDICT (HONORED / NOT-HONORED / behavior description) and a
  claude --version stamp line.
• Test A result file contains BOTH control: and treatment: lines with opposite marker outcomes
  (else verdict is invalid by construction).
• This PLAN's "Empirical verification results" table row 1 is filled (no (pending)).

Phase 5: Topic-docs contract 2.0.0 + seam fixes R1–R6 (one wave) [DONE]

Covers D13. Contract-major change: every implementer adopts in the same wave (no compatibility
machinery). Gated by Phase 4 verdicts.

Work items:

1. Pre-flight consumer check (first item): Grep/Glob for every consumer parsing the
   convention surface — .claude/topic-docs.yaml keys, slug spec, tier paths, runtime guards, the
   scripts/check-cross-plugin-source-drift.sh registry, hooks reading docs/topics/ or .work/.
   Document parse paths in the memory slice before editing anything.
2. R6 — rewrite docs/conventions/topic-docs/README.md: worktree-visibility rationale, context ×
   tier visibility matrix, native mechanisms named (worktree.baseRef, .worktreeinclude, by-value
   returns, tracker index); CHANGELOG entry 2.0.0; schema untouched unless a key changes (KEEP
   expected). Reconcile the Implementers table with reality: toolchain and verification
   carry reference/topic-docs.md but are absent from the table; knowledge, claude-ops,
   docs-hygiene are listed without delta docs — the 2.0.0 table must match the actual fleet
   (add/annotate rows or document why a row is delta-doc-free). The CHANGELOG 2.0.0 entry states
   the mixed-fleet window and why it is safe (no tier/key/slug-spec change — installed cache
   copies and in-flight branches keep 1.x text until they update; divergence is doctrinal, not
   layout-corrupting), and notes a post-PR-B stale-text sweep obligation for in-flight branches at
   their merge time.
3. R1 — committed .claude/settings.json with worktree.baseRef: "head" (shape per Phase 4 smoke
   test A verdict; if NOT-HONORED at project scope, execute the tagged fallback below). Rollout
   note in the PR B description + convention doc: a clone with an existing untracked
   .claude/settings.json hits "untracked working tree file would be overwritten" on pull —
   document the remedy; state the repo-wide worktree-spawn behavior change; gitignore
   .claude/worktrees/ in the same change (mandatory — the runtime .git/info/exclude entry is
   machine-local; CI checkouts and fresh clones lack it, and partial tracking of .claude/
   otherwise turns nested worktrees into git add -A hazards); run the hygiene CI lanes
   (machine-specific-paths, gitleaks, editorconfig) locally on the new tracked file. Document the
   escape hatch: a personal .claude/settings.local.json (main-checkout-resolved, covers every
   worktree) silently overrides R1 machine-wide — the convention doc states this; no audit
   dimension may assume R1 is universally in force.
   Consumer-adoption path (mandatory): repo settings never travel with marketplace-installed
   plugins (isolated cache) — R1/R2 as files fix only this repo. The 2.0.0 doc ships a
   consumer-adoption section: the settings snippet + a .worktreeinclude template, scoped as
   "authoring-repo materialization; consumer repos self-apply" (routing it through a D9 setup-skill
   apply action is recorded as a follow-on trigger, not built now). The visibility matrix gains a
   caveat row: a WorktreeCreate hook makes .worktreeinclude inert (documented) — hook script
   owns the copy.
4. R2 — .worktreeinclude with targeted memory-tier patterns (stage ledgers, EXPLORE/RESEARCH; not
   baselines/raw scratch); one-way creation-time copy documented in the convention doc.
5. R3 — pointer-discipline fixes: plugins/work-items/skills/decompose cites the PR (not contract
   paths) in ticket provenance; plugins/planning/skills/architect records distilled baseline
   values in PLAN (raw captures stay memory-tier). Sweep both skill bodies for prunable-path
   citations.
6. R4/R5 — convention doc text: isolated workers return results by value with the orchestrator
   writing both tiers in the parent checkout (R4); the work-item tracker named as the cross-lane
   awareness/index layer, markdown-in-tickets rejected with rationale (R5).
7. Implementer wave: update all 8 plugins/*/reference/topic-docs.md delta docs against the 2.0.0
   owner doc; bump each touched plugin's plugin.json semver + CHANGELOG; docs-hygiene declutter
   detector references checked (reader row).

File inventory (checkbox discipline — tick as processed):

File	Action	Rationale
[x] docs/conventions/topic-docs/README.md	MODIFY	R6 rewrite, visibility matrix, R4/R5 text
[x] docs/conventions/topic-docs/CHANGELOG.md	MODIFY	2.0.0 entry
[x] docs/conventions/topic-docs/topic-docs.schema.json	KEEP (audit)	no key changes — untouched
[x] docs/conventions/topic-docs/examples/*	AUDIT	layout unaffected by matrix/mechanisms — untouched
[x] .claude/settings.json	CREATE	R1 worktree.baseRef
[x] .worktreeinclude	CREATE	R2 patterns (+ .claude/worktrees/ gitignored)
[x] plugins/discovery/reference/topic-docs.md	MODIFY	2.0.0 adoption
[x] plugins/implementation/reference/topic-docs.md	MODIFY	2.0.0 adoption
[x] plugins/planning/reference/topic-docs.md	MODIFY	2.0.0 adoption
[x] plugins/review/reference/topic-docs.md	MODIFY	2.0.0 adoption
[x] plugins/session-flow/reference/topic-docs.md	MODIFY	2.0.0 adoption
[x] plugins/toolchain/reference/topic-docs.md	MODIFY	2.0.0 adoption
[x] plugins/verification/reference/topic-docs.md	MODIFY	2.0.0 adoption
[x] plugins/work-items/reference/topic-docs.md	MODIFY	2.0.0 adoption
[x] plugins/work-items/skills/decompose/SKILL.md	MODIFY	R3 ticket provenance
[x] plugins/planning/skills/architect/SKILL.md	MODIFY	R3 baseline recording
[x] 8 × plugins/*/plugin.json + CHANGELOG.md	MODIFY	minor bump per touched plugin
[x] plugins/knowledge/…, plugins/claude-ops/…, plugins/docs-hygiene/…	AUDIT	no stale convention text found — untouched; table annotates by-reference rationale

Sanity Check:

• bash scripts/check-cross-plugin-source-drift.sh --check exit 0 (the flag CI runs; flagless mode
  is informational only).
• grep -n "2.0.0" docs/conventions/topic-docs/CHANGELOG.md hits; grep -rn "visibility matrix" -i docs/conventions/topic-docs/README.md hits.
• Implementers-table parity: every plugins/*/reference/topic-docs.md path has a matching table
  row and vice versa (Read assertion against the glob result).
• Pre-flight consumer list exists: .work/plugin-philosophy/consumers-topic-docs.md non-empty.
• Every plugin with a modified file has a plugin.json version bump:
  git diff origin/main...HEAD --name-only | grep '^plugins/' | cut -d/ -f2 | sort -u each has a
  matching plugins/<name>/plugin.json in the diff.
• bash scripts/validate-plugins.sh exit 0 (includes generate-catalog.mjs --check — regenerate
  the catalog if any plugin.json description changed).
• npx markdownlint-cli2 --config .markdownlint-cli2.jsonc on touched .md files exit 0.

Phase 6: Marketplace metadata wave [TODO]

Covers D15 + per-plugin relevance quality verification (deferred question c).

Work items:

1. Fresh-fetch plugin-marketplaces + discover-plugins + plugins-reference
   (default-enablement section) + the dedicated plugin-relevance page; re-verify entry schema
   (relevance, defaultEnabled, displayName, description precedence, version
   silent-precedence trap). defaultEnabled flip semantics for already-installed consumers are
   undocumented — if the fetched pages stay silent, run a 2-minute empirical flip on one plugin
   before the wave (does a marketplace refresh disable an existing install?). Never touch a
   plugin's name (breaks existing installs without a renames map); displayName is safe.
2. Per-plugin pass over all 47 entries: add relevance only where the signal is genuinely helpful
   (judged per-plugin — noise rejected), defaultEnabled: false for personal/niche categories,
   displayName where it clarifies, complete descriptions; assert no version field in any
   entry.
3. Consumer-facing doc section on org enablement of suggestions (pluginSuggestionMarketplaces +
   managed-settings source declaration) — lands in the discover/consumer section of README or
   OFFICIAL-DOCS per where consumer docs live (decided at execution against the fetched page).
4. Record per-plugin relevance decisions (adopted vs rejected-as-noise) in
   .work/plugin-philosophy/relevance-decisions.md.
5. Regenerate the README catalog: node scripts/generate-catalog.mjs (CI runs --check; metadata
   edits drift the generated block otherwise).

Sanity Check:

• claude plugin validate . exit 0.
• node scripts/generate-catalog.mjs --check exit 0.
• node -e assertion: 47 entries; every entry resolves a description (entry or plugin.json);
  version absent from all entries — exit 0.
• .work/plugin-philosophy/relevance-decisions.md has 47 rows.

Phase 7: Fleet conformance audit fanout + tracker graduation [TODO]

Covers D16. Runs against merged doctrine (Phases 1–6 landed).

Work items:

1. Search-before-create (first item): gh issue list --search for an existing
   plugin-conformance epic / wave issues. Match found → pivot to updating the existing items
   (record the match + pivot in the memory slice); no match → proceed to create. Verify required
   labels exist (gh label list) and create missing ones before any gh issue create --label
   call (missing labels fail the create).
2. Derive the audit checklist (~15 dimensions) from the landed doctrine docs: setup criteria (D9),
   userConfig migration (D8), exec-form hooks, metadata completeness (D15), component stances (D6),
   registry conformance (D11), prereq degradation (D10), pointer discipline (R3), freshness riders
   (D7), plus dimensions the doctrine text yields. Freeze a rubric file with per-dimension
   anchored PASS/FAIL criteria + one worked example, injected verbatim into every worker prompt
   (uncalibrated independent scoring across batches encodes rubric drift, not conformance).
   Authority rule: plugins are scored against landed doctrine only; where a fresh-fetched
   doc disagrees with doctrine, that is a doctrine-update finding (its own wave), never plugin
   nonconformance. Dimensions may not assume R1 is universally in force (local-settings override
   exists). Checklist + rubric → memory slice.
3. Fresh-fetch the component doc pages the checklist cites (to detect doctrine-vs-platform drift
   per the authority rule above).
4. Windows sensitive userConfig empirical verification (deferred question a): configure a
   throwaway sensitive userConfig value on this Windows machine; locate where it persists
   (Credential Manager vs plaintext file); VERDICT recorded before any userConfig wave issue
   involving secrets is filed. Secrets excluded from that wave if storage is plaintext (tagged
   fallback below).
5. Fanout: pilot batch of 3–5 plugins first, reviewed by the main session against the rubric
   before full fanout; then per-plugin subagents score the remainder in batches of 8–10; each
   worker writes its own raw report to .work/plugin-philosophy/audit/<plugin>.md (memory-tier
   raw output is carved out of R4 — R4's orchestrator-writes rule governs contract/durable tiers)
   and returns only its scored dimension row by value; the orchestrator (main session) appends
   matrix rows incrementally per batch, so a compaction mid-run loses nothing. Double-score a
   random 3-plugin sample with independent workers and reconcile disagreements before graduating
   the matrix.
6. File the GitHub epic (conformance matrix distilled inline — single-token score cells only,
   prose lives in per-wave issues; GitHub bodies cap near 64 KB) + per-wave issues (setup,
   userConfig, metadata, hooks, convention-seam) via the work-items seam; issues cite the epic + PR
   permalinks, never contract/memory paths (R3). Automatable checks list → epic section = deferred
   CI gate backlog (D1 trigger).

Sanity Check:

• Search outcome recorded: .work/plugin-philosophy/audit/tracker-search.md states the query + hit
  count + create-vs-update decision.
• ls .work/plugin-philosophy/audit/*.md | wc -l ≥ 47 (one report per plugin) + matrix file with
  47 scored rows.
• gh issue list --label epic --search "plugin conformance" (or equivalent) returns the epic;
  epic body contains the matrix; ≥ 5 wave issues reference the epic.
• grep -c "docs/topics/\|\.work/" <epic and wave issue bodies> = 0 (pointer discipline).
• Windows sensitive VERDICT file exists in .work/plugin-philosophy/verifications/.

Empirical verification results

#	Question	Phase	VERDICT
1	worktree.baseRef at project scope; sweep of ignored files; --bg base	4	HONORED (CC 2.1.212, control+treatment): committed project .claude/settings.json worktree.baseRef: "head" honored, incl. from linked worktrees (A2: resolves to the worktree's own HEAD; A3: a linked-worktree session reads its OWN checkout's settings.json). .worktreeinclude: nested-gitignored files qualify, copy is one-way creation-time. Sweep: --worktree worktrees never auto-swept (empirical); subagent/bg sweep would remove ignored-only worktrees (INFERRED — ignored ≠ untracked). --bg base = origin/HEAD by default, so R1 moves it to local HEAD. Windows caveat: deep worktree base paths can trip git PATH_MAX ('$GIT_DIR' too big); this repo's base (~95 chars) is safe.
2	Per-plugin relevance signal quality	6	(pending — per-plugin ledger)
3	Windows sensitive userConfig storage	7	(pending)

Blast radius

HIGH. Matches stress-test triggers: new conventions constraining all future work (doctrine +
contract-major), architecture decisions across 47 plugins + 8 implementer materializations, shared
committed settings (.claude/settings.json) affecting every session, and undocumented behavior
(worktree semantics, Windows sensitive storage — mitigated by the empirical phases). Reversible via
git revert (docs/metadata only, no runtime code), and existing CI (contract tests, markdownlint,
drift check) gates every PR — hence HIGH, not CRITICAL.

Stress-test summary

Two fresh-context adversarial passes ran; all findings verified against the repo before adoption.

Plan-reviewer (Step 3): 9 IMPORTANT + 5 SUGGESTION, 0 CRITICAL — all applied: implementer-roster
reconciliation + parity check (Phase 5), CI-parity sanity commands (drift --check, catalog
--check, markdownlint config, node -e over Python), pointer-vs-restate check made structural
(Phase 2), Phase 4 by-value/fence contradiction resolved, component-count made variable with a
Wave A join step, PR-chain PLAN lifecycle defined, Phase 7 batching + label verify-or-create,
worktree-variant smoke tests, R1 rollout notes.

Devils-advocate (Step 4): 16 assumptions attacked; 4 mandatory changes, all applied:
(1) Phase 4 redesigned — isolated scratch repo with synthetic origin, control+treatment arms
(defeats the documented origin/HEAD-fallback false positive), settings-scope variant A3,
CC-version-stamped verdicts with re-run at the Phase 5 gate; (2) PLAN lifecycle switched to
branch-local prune-per-PR (the program must not self-violate the contract it ships); (3) 2.0.0 doc
gains a consumer-adoption path — repo settings provably never reach marketplace-installed
consumers; (4) Phase 7 calibration — frozen anchored rubric, pilot batch, double-scored sample.
Also adopted: mandatory .claude/worktrees/ gitignore in PR B, WorktreeCreate-hook caveat for
.worktreeinclude, mixed-fleet window statement in the CHANGELOG, doctrine-wins authority rule for
audit scoring, defaultEnabled-flip empirical check, matrix cell budget (64 KB body cap), name
immutability during the metadata wave. One finding escalated to a user gate: R6 major-vs-minor
contradiction with the contract's own versioning rule (see User-approval gates).

Execution shape

Two parallel-safe waves inside an otherwise sequential PR chain; fanout inside Phase 7.

Phase	Surface	Basis
1	Main session	Judgment-heavy doctrine writing; SSOT wording others depend on
2	Main session	Depends on Phase 1 wording; pointer discipline needs judgment
3	Sub-agent worker (parallel with 1–2)	Mechanical index build from llms.txt; disjoint files (OFFICIAL-DOCS.md, one CLAUDE.md row)
4	Sub-agent worker (parallel with 1–3)	Scripted smoke tests; touches scratch/throwaway worktrees only
5	Main session (implementer sweep may fan out mechanically)	Contract-major judgment; 25-file wave needs single editorial voice
6	Main session	Single file; 47 per-plugin relevance judgments
7	Workflow/sub-agent fanout, orchestrated by main session	D16-locked fanout; R4 by-value returns

Wave A (parallel): Phase 1 (main) ∥ Phase 3 (sub-agent) ∥ Phase 4 (sub-agent). Zero file overlap:
P1 = docs/PLUGIN-PHILOSOPHY.md; P3 = docs/OFFICIAL-DOCS.md + CLAUDE.md; P4 = .work/ + scratch.
Wave B (sequential): Phase 2 → Phase 5 → Phase 6 → Phase 7.

Scope fences (Wave A): P3 agent ALLOWED docs/OFFICIAL-DOCS.md, CLAUDE.md (one row);
FORBIDDEN everything else incl. PLAN.md. P4 agent ALLOWED .work/plugin-philosophy/verifications/
and throwaway git init repos under the scratchpad (its own branches/worktrees live there);
FORBIDDEN every file and branch of THIS repo (note: claude -p --worktree <name> creates branches
named worktree-<name> — another reason the spike never runs in this repo).
Sequential fallback: any fence violation or agent failure → that phase re-runs inline main-session
in Wave B order. PLAN.md edits are main-session-only.

Cost note: Wave A = 2 extra agents vs sequential (~saves one serial doc-build + smoke-test round);
Phase 7 = ~47 scoring agents (D16-locked, run regardless of shape).

Open questions

None blocking — the three empirical questions are scheduled inside phases with tagged fallbacks.

Handoff to implementation

User-approval gates

• [BRIEF CONTRADICTION — user decision required] D13 locks R6 as a major contract version
  ("2.0.0, one wave"), but the contract's own Versioning rule says major = "moves a tier, renames a
  key, or alters the slug spec" — R6 does none (schema KEEP; the change is visibility semantics +
  doctrine text). Options: (a) keep 2.0.0 and amend the Versioning rule so visibility-semantics
  guarantees also count as major (the doctrine repo then applies its own rule consistently);
  (b) downgrade to a 1.x minor, dissolving the one-wave coordination burden and most of Phase 5's
  mixed-fleet risk. RECOMMENDED: (a) — the Brief locked the one-wave clean break deliberately, and
  a visibility-guarantee change does alter what implementers may rely on; the rule amendment makes
  the label honest. The plan as written assumes (a).
• [FALLBACK — confirm or override] Smoke test A fails (project-scope worktree.baseRef not
  honored): R1 degrades to documenting the limitation + the strongest honored scope in the
  convention doc, and an upstream issue is filed; R2/R6 proceed unchanged.
• [FALLBACK — confirm or override] Windows sensitive storage is plaintext: secret-bearing
  userConfig migrations are excluded from the userConfig wave issue and recorded as blocked-upstream
  in the epic; non-secret migrations proceed.
• Scope-expansion of any kind (new convention, new component adoption) mid-flight → stop and ask.

Execution shape ([EXEC-SHAPE] tagged)

• [EXEC-SHAPE] PR slicing: PR A = Phases 1–3 (doctrine + index, current branch
  docs/plugin-philosophy); PR B = Phases 4–5 (contract 2.0.0 wave; Phase 4 evidence rides the
  memory tier, distilled results in PLAN); PR C = Phase 6 (metadata); PR D = close-out (Phase 7's
  PLAN/verdict updates + prune-with-pointer). Rationale: reviewability + distinct concerns
  (doctrine vs contract-major vs metadata); each PR independently green on existing CI.
• [EXEC-SHAPE] PLAN.md lifecycle across the PR chain — branch-local, prune-per-PR: the
  topic-docs contract says contract slices are pruned before merge, and this program (which ships
  that very contract's 2.0.0) must not self-violate by parking a slice on main for weeks. Each PR
  branch commits the current PLAN, pastes it into its PR description, and prunes the slice in a
  final commit before merge; the next PR branch (cut from post-squash main) re-commits the
  updated PLAN from the local working tree. Cross-PR continuity = the PR-description pastes + (from
  Phase 7) the epic. Close-out at PR D: Phase 7's verdict rows and final status tags commit there,
  durable outcomes graduate, final prune-with-pointer. The Windows sensitive VERDICT is recorded
  durably (PLAN verdict table → PR D description + epic), not only in gitignored .work/.
  (Alternative rejected: adding a multi-PR-program exception clause to the 2.0.0 lifecycle text —
  viable, but it lands only in PR B while PR A would already need it; override at approval if the
  exception clause is preferred.)
• [EXEC-SHAPE] Wave A parallelism + fences as tabled above.
• [EXEC-SHAPE] Phase 7 fanout surface: per-plugin subagents (Workflow engine if available, plain
  sub-agent fanout otherwise) — D16 locks the fanout itself.
• [EXEC-SHAPE] Empirical verifications embedded at Brief-assigned execution points (P4/P6/P7)
  rather than a standalone verification phase.

Mechanical work

• Commit boundaries: one commit per phase minimum; Phase 5 = one wave commit for the contract bump +
  implementer adoption (clean break lands atomically); PLAN.md status-tag updates ride each phase's
  commit. Each PR branch is cut from post-squash main, never from the previous PR branch
  (stacking would replay the prior PR's squashed commits in the diff).
• Verification checkpoints: run each phase's Sanity Check before its commit; existing CI
  (contract tests, markdownlint, drift check) green before each PR merge.
• Sequential fallback: documented under Execution shape; orchestrator-writes rule (R4) applies to
  all fanout output.
• Close-out: /architect close-out at PR time — PLAN.md into PR description <details>, durable
  outcomes graduate (vault_backend docs), contract slice pruned with pointer.

🤖 Generated with Claude Code

https://claude.ai/code/session_01M1owJj9ZzkV36V3C1CyX4a

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fc5f14653a

ℹ️ 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".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ca05dcfbc3

ℹ️ 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]

PR Review: topic-docs contract 2.0.0

• Gather context from PR metadata and changed files list
• Read key changed files (.worktreeinclude, README.md, .claude/settings.json, skill files, sample delta docs)
• Verify Codex inline findings independently
• Review for correctness, security, CLAUDE.md alignment
• Post findings

View job run

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5d3da2c0f1

ℹ️ 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]

Claude finished @kyle-sexton's task in 3m 39s —— View job

---

PR Review: topic-docs contract 2.0.0

• Gather context from PR metadata and changed files list
• Read key changed files (.worktreeinclude, README.md, .claude/settings.json, skill files, sample delta docs)
• Verify Codex inline findings are fully resolved in latest commits
• Review for correctness, security, CLAUDE.md alignment
• Post findings

---

Summary

This is a docs/config-only contract-major release. All 6 Codex findings across two rounds were addressed in 5d3da2c and 6502ccb. The mechanics are correct, the 36-file wave is internally consistent, and no security or CLAUDE.md issues remain. One advisory observation below.

---

Codex findings — verified resolved

Finding	Commit	Status
.work/.gitignore not carried (Codex R1, round 1)	5d3da2c	Resolved — .work/.gitignore is first pattern in .worktreeinclude and in the consumer template
Phantom CHANGED on unmatched globs in create.md (Codex R2, round 1)	5d3da2c	Resolved — [[ -f "$f" ]] || continue correctly skips literal unmatched globs; both the no-match and multi-match cases are sound
Discovery binding claiming by-value for parent-checkout workers (Codex R3, round 1)	5d3da2c	Resolved — boundary is now "checkout, not process"; -deep forks write directly since they run in the parent checkout
Decompose tickets losing plan provenance after slice prune (Codex R4, round 2)	6502ccb	Resolved — template now records PLAN Phase N, topic <slug> pre-PR and instructs backfilling the PR URL as a comment once it opens
Wayfind map Notes pointing at memory-tier paths (Codex R5, round 2)	6502ccb	Resolved — both SKILL.md:85 and map-anatomy.md template now read "durable pointers only; distill memory-tier content inline"
R6 owner-doc correctness	This PR	Resolved by design

---

Spot-checked for this review

.claude/settings.json — confirmed via SHA 75384642: correct four-key JSON with worktree.baseRef: "head". The D status in the CI working tree is a checkout environment artifact, not a code issue.

.gitignore — .claude/worktrees/ added alongside pre-existing .claude/settings.local.json and .claude/observability/. Necessary companion to the committed settings file so worktree checkouts don't surface as untracked. ✓

.worktreeinclude — six patterns, all at the correct depth (.work/.gitignore, EXPLORE.md, EXPLORE-*.md, RESEARCH.md, RESEARCH-*.md, *-checklist.md). Matches the consumer template in README.md exactly. Baselines and raw scratch deliberately absent. ✓

README.md visibility matrix — context × tier matrix is logically consistent: the worktree rows accurately describe the worktree.baseRef and .worktreeinclude behaviour, the escape-hatch caveat (settings.local.json override) is documented, and the WorktreeCreate-hook caveat correctly notes that .worktreeinclude is inert when a hook owns worktree creation. ✓

Versioning rule amendment — the CHANGELOG 2.0.0 entry explains the logic (amendment makes the major label honest; no tier/key/slug change), and the README Versioning section now correctly lists a visibility-guarantee change as major. Self-consistent. ✓

Implementers table parity — 8 delta-doc rows match the 8 modified reference/topic-docs.md files; 3 adopt-by-reference rows (knowledge, claude-ops, docs-hygiene) have no delta doc in the diff, which is correct. ✓

Version bumps — all 9 touched plugins have a matching plugin.json bump and CHANGELOG entry: discovery 0.6.0, implementation 0.7.0, planning 0.14.0, review 0.10.0, session-flow 0.8.0, source-control 0.5.2 (nullglob fix), toolchain 0.3.0, verification 0.2.0, work-items 0.9.0. ✓

Security — no code execution surfaces introduced. The create.md shell snippet was already reviewed; the [[ -f "$f" ]] || continue addition is purely additive and safe. No PII, no secrets, no MCP egress, no hooks with new execution. ✓

---

One advisory observation

Decompose backfill is advisory-only (decompose/SKILL.md:135-139):

The backfill instruction ("when the PR opens, backfill it as a comment on each published item") is embedded in an HTML comment inside the body template, so it's guidance to the agent that reads the skill — not a step in the process flow. There is no enforcement gate. Tickets published before a PR exists will dangle until someone remembers to run the backfill. This is an acceptable trade-off for a docs-only fix (adding a process step here would widen scope), but it would benefit from a follow-on that either promotes the backfill to an explicit numbered step in the publish flow or adds it to the /work-items:decompose close-out checklist. Not a blocker.

---

CLAUDE.md alignment

Rule	Status
Repo-agnostic (no hardcoded paths)	✓ Consumer adoption section explicitly scopes R1/R2 as "self-apply"
Configurable without editing the plugin	✓ settings.local.json escape hatch documented
Plugin-form-safe	✓ No ../ reach-outs in delta docs
No PII / secrets	✓
Versioned	✓ 9 version bumps covering all touched plugins
Security-reviewed	✓ Config/docs only; shell snippet is injection-safe

This PR is ready to merge.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6502ccbf53

ℹ️ 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".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c6fbb542b5

ℹ️ 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".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6693d68e34

ℹ️ 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]

PR Review: topic-docs contract 2.0.0 (Codex rounds 4–5)

• Gather context — new commits since prior review: rounds 4 (6693d68) and 5 (c924b09)
• Read create.md at HEAD to verify round 4 and 5 fixes
• Review for correctness and any remaining issues
• Post findings

View job run

[claude]

Claude finished @kyle-sexton's task in 2m 47s —— View job

---

PR Review: topic-docs contract 2.0.0 (Codex rounds 4–6)

• Gather context — new commits: rounds 4 (c6fbb54), 5 (6693d68), 6 (c924b09), and merge from main (9d8e3a5)
• Read create.md at HEAD to verify all fixes
• Verify decompose + wayfind fixes from prior rounds still intact
• Review for correctness and any remaining issues
• Post findings

---

Codex rounds 4–6 — all verified resolved

Codex finding	Commit	Status
Detect deletions of carried worktree files (create.md)	c6fbb54	Resolved — MAIN_ROOT glob expansion (lines 39–43) now surfaces files present in main but absent in the worktree as ABSENT here (deleted, or never carried): $f
Create parent dirs before syncing new memory files (create.md)	c6fbb54	Resolved — mkdir -p "$(dirname "$MAIN_ROOT/$f")" before cp (line 57); new-file diff against /dev/null
Read .worktreeinclude from the worktree root (create.md)	6693d68	Resolved — `cd "$(git rev-parse --show-toplevel)"
Avoid treating never-copied files as deletions (create.md)	c924b09	Resolved — ABSENT label is now "deleted, or never carried" (line 42); Remove-from-main option requires explicit user confirmation of a deliberate same-session deletion; default is Skip (line 56)

---

Spot-checks

create.md detection block — all six fixes across rounds 1–6 are coherent together. The worktree-side loop (for f in $pattern) correctly skips unmatched globs via [[ -f "$f" ]] || continue; the main-side loop (for m in "$MAIN_ROOT"/$pattern) correctly detects carried files deleted from the worktree; mkdir -p before copy and /dev/null for new-file diffs are consistent; and the ABSENT ambiguity is surfaced clearly without auto-removing main's copy.

.worktreeinclude — .work/.gitignore is first (so the self-ignore guard is active from worktree creation); six patterns covering stage ledgers and checklists. Matches the consumer template in README.md exactly. ✓

Decompose provenance — still intact: pre-PR publishes record PLAN Phase N, topic <slug> (a label, not a path); HTML comment instructs backfilling the PR URL as a comment once the PR opens. ✓

Wayfind Notes — still intact: "durable pointers only — PRs, committed docs, prior items, external links; memory-tier artifacts are checkout-local, so distill their relevant content inline." ✓

Merge commit (9d8e3a5) — absorbed planning 0.16.0 from main over the wave's 0.14.0, plus patches to implementation/session-flow/work-items. No regression: the .worktreeinclude and create.md changes from rounds 3–5 are all post-merge and unaffected.

---

No new findings

All six Codex rounds are fully addressed. The detection block is internally consistent, edge cases (unmatched globs, new slugs requiring mkdir -p, never-carried files that look like deletions, subdirectory invocations) are all handled correctly in the agent-instruction pseudocode. No security, CLAUDE.md alignment, or correctness issues remain.

This PR is ready to merge.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9e5f52b2cd

ℹ️ 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".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 323eb8c11b

ℹ️ 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".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c26f7006cb

ℹ️ 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]

Claude finished @kyle-sexton's task in 1m 50s —— View job

---

PR Review: topic-docs contract 2.0.0 (Codex rounds 7–8)

• Gather context — new commits: round 7 (c26f700) and round 8 (a87f75c)
• Read cleanup.md (round 7) and map-anatomy.md + wayfind SKILL.md (round 8) at HEAD
• Verify fixes are correct and internally consistent
• Post findings

---

Codex rounds 7–8 — both verified resolved

Codex finding	Commit	Status
Check absent carried files before cleanup (cleanup.md)	c26f700	Resolved — guard now expands each pattern from MAIN_ROOT in addition to the worktree toplevel; main-side files absent from the worktree are surfaced with removal gated on explicit deliberate-deletion confirmation (default keep)
Exempt memory distillation from the no-recaps rule (map-anatomy.md)	a87f75c	Resolved — "Links, not recaps" is now qualified to "for anything durably linkable"; the memory-tier distillation is named as the one sanctioned exception with clear rationale

---

Spot-checks

cleanup.md carried-ignored-file guard — the updated guard now fully mirrors the PR pre-flight: AND from MAIN_ROOT expansion added, absent-in-worktree case surfaces with a default-keep confirmation gate (so files that were never carried, e.g. from pre-.worktreeinclude or manual worktrees, cannot trigger accidental erasure of main's copies). Internally consistent with the PR pre-flight wording from rounds 4–6. ✓

map-anatomy.md Notes section — the three-bullet Notes block is now self-consistent: bullet 2 requires memory-tier distillation; bullet 3 ("Links, not recaps — for anything durably linkable") carves out that distillation as its one sanctioned exception with rationale. An agent following all three bullets can now correctly inline memory-tier content without violating the no-recaps invariant. ✓

SKILL.md Notes description — the inline description in the chart-mode step still correctly describes the Notes section ("memory-tier <memory_dir>/ artifacts are checkout-local, so distill their relevant content inline"), consistent with the updated template. ✓

---

No new findings

All eight Codex rounds are fully addressed. Both round 7 and round 8 changes are minimal, targeted one-to-three-line edits that close the identified gaps without widening scope. The full carried-file guard is now symmetric between the PR pre-flight and the cleanup path, and the wayfind Notes template is internally self-consistent.

This PR is ready to merge.