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

.claude/settings.json

@@ -0,0 +1,5 @@
+{
+  "worktree": {
+    "baseRef": "head"
+  }
+}

.gitignore

@@ -12,6 +12,7 @@ Thumbs.db
 # Local-only Claude Code state
 .claude/settings.local.json
 .claude/observability/
+.claude/worktrees/
 CLAUDE.local.md
 
 # Test-result artifacts (Pester runner output)

.worktreeinclude

@@ -0,0 +1,10 @@
+# Memory-tier files worth carrying into new worktrees (one-way, creation-time
+# copy; gitignored-only). Never baselines or raw scratch — machine-bound.
+# The self-ignore file rides along so carried files stay ignored in the new
+# worktree from creation, not only after the first memory-tier write heals it.
+.work/.gitignore
+.work/*/EXPLORE.md
+.work/*/EXPLORE-*.md
+.work/*/RESEARCH.md
+.work/*/RESEARCH-*.md
+.work/*/*-checklist.md

docs/conventions/topic-docs/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog — topic-docs convention
 
+## 2.0.0 — 2026-07-17
+
+Visibility semantics are now normative contract guarantees. No tier moves, no
+`topic-docs.yaml` key changes, no slug-spec changes — the schema is untouched.
+The Versioning rule now counts a visibility-guarantee change as major; this
+release is the first such change, and the rule amendment is what makes the
+major label honest.
+
+- **Visibility across execution contexts** (new, normative): context × tier
+  visibility matrix; four native mechanisms — `worktree.baseRef: "head"` in
+  committed project settings (verified honored at project scope on CC 2.1.212,
+  including from linked worktrees), `.worktreeinclude` one-way creation-time
+  copy of gitignored memory files, by-value worker returns with the
+  orchestrator writing contract/durable tiers in the parent checkout, and the
+  work-item tracker as the cross-lane index (markdown-in-tickets as a primary
+  artifact store rejected: not diffable, no review gate, drifts from code).
+  Caveats documented: a `WorktreeCreate` hook makes `.worktreeinclude` inert;
+  a personal `.claude/settings.local.json` silently overrides the committed
+  `baseRef` machine-wide, so nothing may assume it universally in force.
+- **Pointer discipline on durable surfaces** (new, normative): tickets, PR
+  bodies, and promoted docs never cite prunable contract paths or gitignored
+  memory paths — cite the PR, the promoted location, or distilled values.
+- **Consumer adoption**: settings + `.worktreeinclude` templates; repository
+  files never travel with marketplace-installed plugins, so consuming repos
+  self-apply; rollout caveats (untracked-settings pull collision, Windows
+  worktree path limit).
+- **Implementers table reconciled with the fleet**: verification and toolchain
+  rows added; a Binding column distinguishes delta-doc implementers from
+  adopt-by-reference rows (knowledge, claude-ops, docs-hygiene) with the
+  reason each needs no delta doc; the verification manifest and baselines
+  moved from the implementation row to the new verification row, matching the
+  plugins' actual bindings.
+
+Mixed-fleet window: installed plugin caches and in-flight branches keep 1.x
+text until they update. Safe because no tier, key, or slug-spec changed —
+divergence is doctrinal, never layout-corrupting. In-flight branches sweep
+stale visibility text when they merge.
+
 ## 1.0.1 — 2026-07-15
 
 - Reserve `vault_backend: gitbook` without enabling writes: concern files preserve the key, skills

docs/conventions/topic-docs/README.md

@@ -55,6 +55,129 @@ Every fact has exactly one home. Any other surface — a handoff, a
 summary, a map, a PR body — may only *reference* it (path, URL, or
 context pointer), never restate it. An index is not a store.
 
+## Visibility across execution contexts
+
+Tier placement decides more than git hygiene: it decides **which
+execution contexts can see a document at all**. A linked worktree, a
+subagent worktree, a background session, and a cloud clone each
+materialize a different slice of the repository, so a document's tier is
+also its visibility guarantee. This section is normative — a change to
+what a context may rely on seeing is a **major** contract change (see
+Versioning).
+
+### Context × tier visibility matrix
+
+The worktree rows assume the consuming repo materializes both native
+mechanisms below (`worktree.baseRef: "head"` and `.worktreeinclude`);
+without them, every spawned worktree behaves as the default-base row.
+
+| Context | Memory `<memory_dir>/<slug>/` | Contract `<contract_dir>/<slug>/` (branch tier) | Durable (vault backend) | Machine state (`${CLAUDE_PLUGIN_DATA}`) |
+|---|---|---|---|---|
+| Writing checkout (same session or another session in it) | visible | visible, including uncommitted edits | visible | visible |
+| Worktree spawned from local HEAD (`worktree.baseRef: "head"`) | invisible, except `.worktreeinclude`-carried patterns (one-way copy at creation time) | committed state visible; uncommitted edits invisible | visible | visible (machine-global) |
+| Worktree spawned from the default base (`origin/HEAD`) | invisible, except `.worktreeinclude`-carried patterns | invisible — task-branch commits absent | merged state only | visible |
+| Sibling lane (worktree on another branch) | invisible | invisible | merged state only | visible |
+| Cloud clone / CI checkout | invisible | pushed commits only | pushed state only | invisible |
+
+Two consequences drive the rules below: a contract document is visible
+to an isolated context only as **committed** state (commit plan updates
+with their phase — the lifecycle already requires this), and a memory
+document is visible **only in the checkout that wrote it** unless a
+`.worktreeinclude` pattern carries it.
+
+### Native mechanisms
+
+Four native mechanisms, no custom machinery:
+
+- **`worktree.baseRef: "head"`** — committed project
+  `.claude/settings.json`. Spawned worktrees (including subagent
+  worktrees) branch from local `HEAD` instead of `origin/HEAD`, so they
+  carry the task branch's contract commits. Verified honored at
+  project-settings scope on CC 2.1.212, including from linked worktrees
+  (a linked-worktree session reads its *own* checkout's
+  `.claude/settings.json`, and `"head"` resolves to that worktree's
+  `HEAD`). Escape hatch: a personal `.claude/settings.local.json`
+  (resolved to the main checkout, covering every worktree) silently
+  overrides this machine-wide — no skill, gate, or audit may assume the
+  setting is universally in force.
+- **`.worktreeinclude`** — repository root, `.gitignore` syntax; only
+  files that match a pattern *and* are gitignored are copied. The copy
+  is **one-way at worktree-creation time**: later edits sync in neither
+  direction, so carried files are read-only context, never a channel.
+  Carry cross-checkout-useful memory files (stage ledgers,
+  `EXPLORE.md` / `RESEARCH.md`); never baselines or raw scratch
+  (machine-bound). Caveat: a `WorktreeCreate` hook replaces the default
+  worktree creation entirely and `.worktreeinclude` is **not
+  processed** — the hook script owns any copying.
+- **By-value returns** — a worker running in its **own checkout**
+  (subagent worktree, background session) returns its results **by
+  value**; the orchestrating session writes the contract and durable
+  tiers in the parent checkout. Workers never write those tiers from an
+  isolated checkout — commits and promotions land where the lifecycle
+  can see them. The boundary is the checkout, not the process: a forked
+  subagent running in the parent's checkout may write the memory slice
+  directly (its writes are already visible), and raw per-worker output
+  may land in the parent checkout's memory slice when the orchestrator
+  directs it there.
+- **Tracker as the cross-lane index** — the work-item tracker is the
+  awareness layer across lanes: branch files stay lane-local, and a
+  session in another lane discovers state through tickets, which point
+  (PR URLs, promoted-doc locations) per the single-home rule.
+  Markdown-in-tickets as a primary artifact store is rejected: ticket
+  bodies are not diffable, carry no review gate, and drift from code.
+
+### Pointer discipline on durable surfaces
+
+Durable surfaces — tickets, PR bodies, promoted docs — never point at
+prunable or gitignored paths. The contract slice is deleted before
+merge and the memory slice never leaves its checkout, so such pointers
+dangle by design. Cite the PR, the promoted location, or distilled
+values instead: a ticket sourced from a plan records the PR that
+carried the plan, and a plan records distilled baseline numbers, never
+the memory-slice path of the raw capture.
+
+### Consumer adoption
+
+Repository settings and root files never travel with
+marketplace-installed plugins (plugins run from an isolated cache), so
+each consuming repository materializes the two files itself:
+
+```json
+{
+  "worktree": {
+    "baseRef": "head"
+  }
+}
+```
+
+as committed `.claude/settings.json`, and a `.worktreeinclude` at the
+repository root (substitute a non-default resolved `memory_dir` for
+`.work`):
+
+```text
+.work/.gitignore
+.work/*/EXPLORE.md
+.work/*/EXPLORE-*.md
+.work/*/RESEARCH.md
+.work/*/RESEARCH-*.md
+.work/*/*-checklist.md
+```
+
+The first line carries the memory root's self-ignore file so the copied
+files are ignored in the new worktree from creation; without it they
+surface as untracked until the self-ignore guard heals on the first
+memory-tier write.
+
+Also gitignore `.claude/worktrees/` so worktree contents never appear
+as untracked files. Rollout caveats: pulling a commit that adds
+`.claude/settings.json` into a clone already holding an untracked file
+at that path fails with "untracked working tree file would be
+overwritten" — move the local file aside, pull, then merge its values
+back; on Windows, deep repository base paths can trip git's path limit
+inside nested worktrees (`'$GIT_DIR' too big`) — keep the repository
+base path short. Routing this materialization through a setup-skill
+apply action is a recorded follow-on, not built today.
+
 ## The tracked concern file — `.claude/topic-docs.yaml`
 
 The consumer-side single source of truth. Shape in
@@ -220,22 +343,30 @@ citations of retired paths as ghost refs.
 
 ## Implementers
 
-| Plugin | Writes | Tier(s) |
-|---|---|---|
-| discovery | `EXPLORE.md`, `RESEARCH.md` | memory |
-| planning | `PRD.md`, `PLAN.md` (Brief), `design/`, opt-in brainstorm persist | contract + memory |
-| implementation | `PLAN.md` (Plan/progress), `verification/` manifest, baselines, raw captures | contract + memory |
-| session-flow | handoffs | memory (`handoffs/`) |
-| review | review reports | memory (`reviews/`) |
-| work-items | per-topic action ledger; tracker projections | memory; ticket edge |
-| knowledge | ingest trees — **formal carve-out**: its work root resolves through its own `library_dir` seam, not `memory_dir`; slug conformance is form-only (charset/reserved names), and its nested `<epic>/<slug>/` sub-slices are sanctioned | memory (carved out) |
-| claude-ops | telemetry | machine state |
-| docs-hygiene | (reader) audit-noise detector recognizes these shapes | — |
+Plugins with their own placement deltas carry a deltas-only binding
+(`reference/topic-docs.md`); the rest adopt by reference — their
+relationship to the contract is fully stated by their table row.
+
+| Plugin | Writes | Tier(s) | Binding |
+|---|---|---|---|
+| discovery | `EXPLORE.md`, `RESEARCH.md` | memory | delta doc |
+| planning | `PRD.md`, `PLAN.md` (Brief), `design/`, opt-in brainstorm persist | contract + memory | delta doc |
+| implementation | `PLAN.md` (Plan/progress), `DEVIATIONS.md`, status summaries | contract + memory | delta doc |
+| verification | `verification/` manifest; baselines, raw captures | contract + memory | delta doc |
+| session-flow | handoffs | memory (`handoffs/`) | delta doc |
+| review | review reports | memory (`reviews/`) | delta doc |
+| work-items | per-topic action ledger; tracker projections | memory; ticket edge | delta doc |
+| toolchain | nothing of its own — its setup skill offers the concern file | — | delta doc |
+| knowledge | ingest trees — **formal carve-out**: its work root resolves through its own `library_dir` seam, not `memory_dir`; slug conformance is form-only (charset/reserved names), and its nested `<epic>/<slug>/` sub-slices are sanctioned | memory (carved out) | by reference — the carve-out above is its entire delta |
+| claude-ops | telemetry | machine state | by reference — machine state resolves no contract paths |
+| docs-hygiene | (reader) audit-noise detector recognizes these shapes | — | by reference — reads shapes, writes nothing |
 
 ## Versioning
 
 This contract is versioned in `CHANGELOG.md`. A change that moves a
-tier, renames a key in `topic-docs.yaml`, or alters the slug spec is a
-**major** contract change, and every implementer adopts it in the same
-release wave (clean break — this contract carries no compatibility
-machinery). Additive guidance is minor.
+tier, renames a key in `topic-docs.yaml`, alters the slug spec, or
+**changes a visibility guarantee** (what an execution context may rely
+on seeing, per the visibility matrix) is a **major** contract change,
+and every implementer adopts it in the same release wave (clean break —
+this contract carries no compatibility machinery). Additive guidance is
+minor.

plugins/discovery/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "discovery",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Structured discovery before changes: explore the local codebase (inline or in an isolated forked subagent) and run disciplined multi-source external research with source tiers, falsification, and recency gates — persisting EXPLORE.md / RESEARCH.md handoff artifacts.",
   "author": {
     "name": "Melodic Software",

plugins/discovery/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog — discovery plugin
 
+## 0.6.0 — 2026-07-17
+
+### Changed
+
+- Adopt topic-docs contract 2.0.0 (visibility semantics): `reference/topic-docs.md` states that
+  `EXPLORE.md` / `RESEARCH.md` are checkout-local and are the cross-checkout-useful kind the
+  contract's `.worktreeinclude` template carries into new worktrees. The by-value boundary is the
+  checkout, not the process: the `-deep` forks run in the parent's checkout and write the
+  artifacts there directly; only workers dispatched into their own checkout return findings by
+  value for the parent to write.
+
 ## 0.5.1 — 2026-07-15
 
 ### Fixed

plugins/discovery/reference/topic-docs.md

@@ -25,3 +25,13 @@ Discovery writes **memory tier only** — working documents nothing downstream e
 Discovery never writes the contract tier; the `contract_tier` setting does not change where its
 artifacts land. `/discovery:explore-deep` and a Tier-2 research subagent operate under the
 contract's **non-interactive / forked mode** rule.
+
+## Visibility (contract ≥ 2.0.0)
+
+These artifacts are memory-tier, so they exist only in the checkout that wrote them. They are
+exactly the cross-checkout-useful kind the contract's `.worktreeinclude` template carries into new
+worktrees (one-way, at creation time) where the consuming repo materializes it. The contract's
+by-value boundary is the checkout, not the process: the `-deep` forks run in the parent's checkout
+and write `EXPLORE.md` / `RESEARCH.md` there directly (already visible to the parent), returning a
+summary by value; a worker dispatched into its **own** checkout (worktree or background session)
+returns findings by value instead, and the parent writes the memory slice.

plugins/implementation/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "implementation",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "Disciplined implementation stage: execute approved plans inline (`/implementation:implement`) or via orchestrated worker subagents (`/implementation:implement-dispatch`) with incremental validation, TDD-by-default cadence, green-checkpoint commits, scope-fence drift detection, and divergence detection that routes back to planning. Build/test/lint, testing, and outcome verification live in the companion `toolchain`, `testing`, and `verification` plugins, invoked when installed.",
   "author": {
     "name": "Melodic Software",

plugins/implementation/CHANGELOG.md

@@ -3,6 +3,14 @@
 All notable changes to the `implementation` plugin are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning.
 
+## [0.7.0]
+
+### Changed
+
+- Adopt topic-docs contract 2.0.0 (visibility semantics): `reference/topic-docs.md` ties the
+  phase-commit rule to the contract's visibility guarantee — isolated contexts see the contract
+  slice as committed state only — and states the by-value return rule for dispatched workers.
+
 ## [0.6.2]
 
 ### Changed

plugins/implementation/reference/topic-docs.md

@@ -29,4 +29,8 @@ Verification manifests and baselines are the `verification` plugin's artifacts (
 their placement); this plugin does not write them.
 
 **Phase-commit rule:** each implementation phase's plan updates ride the same commit as that
-phase's source changes — one commit, one story; memory-tier files never enter the commit.
+phase's source changes — one commit, one story; memory-tier files never enter the commit. Per the
+contract's visibility rules (≥ 2.0.0) this is also what makes plan progress visible to isolated
+contexts: a spawned worktree or dispatched worker sees the contract slice only as **committed**
+state, so uncommitted plan marks are invisible outside the writing checkout. Dispatched workers
+return results by value; this session writes both tiers in its own checkout.

plugins/planning/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "planning",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "userConfig": {
     "use_ask_user_question": {
       "type": "boolean",

plugins/planning/CHANGELOG.md

@@ -3,6 +3,18 @@
 All notable changes to the `planning` plugin are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning.
 
+## [0.17.0]
+
+### Changed
+
+- Adopt topic-docs contract 2.0.0 (visibility semantics): `reference/topic-docs.md` records that
+  baselines are checkout-local and `PLAN.md` carries distilled values only;
+  `/planning:plan`'s baseline step no longer directs `PLAN.md` to reference the stored
+  memory-slice capture (pointer discipline — the path is invisible outside the writing checkout).
+- `/planning:wayfind` map-issue Notes carry durable pointers only (PRs, committed docs, prior
+  items, external links); memory-tier artifact content is distilled inline instead of pointed at —
+  tracker issues are durable surfaces under the contract's pointer discipline.
+
 ## [0.16.0]
 
 ### Added

plugins/planning/reference/topic-docs.md

@@ -27,6 +27,11 @@ behavior; this binding and topic-docs remain authoritative for their placement.
 the contract's solo/offline mode. Roots are configurable via the concern file's `contract_dir` /
 `memory_dir` keys.
 
+Baselines are machine-bound memory-tier captures, invisible outside the writing checkout: per the
+contract's pointer discipline (≥ 2.0.0), `PLAN.md` records **distilled baseline values only** and
+never cites a memory-slice capture path. Checklists are the stage-ledger kind the contract's
+`.worktreeinclude` template carries into new worktrees where the consuming repo materializes it.
+
 ## Close-out — the vault seam
 
 `/planning:plan` owns describing the contract-slice close-out. Its promotion step resolves