refactor(toolchain): relocate setup topic-docs offering to the verification plugin that owns it

plugins/implementation/README.md

@@ -33,7 +33,8 @@ gracefully when absent — no hard dependencies:
   `<contract_dir>/<slug>/` (default `docs/topics/`), committed on the task branch and
   pruned before merge; working memory in the self-ignoring `<memory_dir>/` (default
   `.work/`). The tracked `.claude/topic-docs.yaml` concern file is the consumer-side
-  source of truth — the `toolchain` plugin's `/toolchain:setup` offers to write it.
+  source of truth — each lifecycle plugin's own setup (`/discovery:setup`,
+  `/planning:setup`, `/verification:setup`) offers to write it.
 - **Reads your conventions, assumes none.** Testing structure, commit conventions,
   branch policy, and project invariants come from your own `CLAUDE.md` and rules.
 - **Cross-plugin refs degrade gracefully.** Companion plugins (`toolchain`, `testing`,
@@ -72,8 +73,9 @@ self-verification — but installing the companion plugins restores the full for
 ## Configuration
 
 Artifact placement is governed by the tracked `.claude/topic-docs.yaml` concern file
-(see the topic-docs seam above); the `toolchain` plugin's `/toolchain:setup` interviews
-for and persists it. This plugin declares no userConfig options.
+(see the topic-docs seam above); each lifecycle plugin's own setup (`/discovery:setup`,
+`/planning:setup`, `/verification:setup`) interviews for and persists it. This plugin
+declares no userConfig options.
 
 ## License
 

plugins/toolchain/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "toolchain",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "description": "Repo-agnostic polyglot verification toolchain: build + test + lint for changed files across .NET, Python, TypeScript, Bash, PowerShell, Markdown, YAML, and cross-cutting surfaces (`/toolchain:check`, `/toolchain:lint`), plus a re-runnable `/toolchain:setup` with check (report the configured ecosystems and their command surface) and apply (interview, infer, and write the tracked per-ecosystem command config those skills resolve first).",
   "author": {
     "name": "Melodic Software",

plugins/toolchain/CHANGELOG.md

@@ -3,6 +3,20 @@
 All notable changes to the `toolchain` plugin are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning.
 
+## [0.5.0]
+
+### Removed
+
+- **`/toolchain:setup` no longer offers the topic-docs concern file — relocated to the lifecycle
+  plugins that own it.** Setup step 6 wrote `.claude/topic-docs.yaml`, a consumer config resolved by
+  the `implementation` and `verification` plugins for artifact placement; no `/toolchain:*` skill reads
+  it, so this build/test/lint plugin was writing another plugin's consumer config. Setup is now scoped
+  solely to the ecosystem command surface it owns (the tracked `.claude/ecosystems/*.yaml` files):
+  `check` no longer reports the topic-docs concern and `apply` no longer offers it, and the orphaned
+  `reference/topic-docs.md` binding that only step 6 read is removed. The shared concern file is offered
+  by each lifecycle plugin's own setup — `/discovery:setup`, `/planning:setup`, and the new
+  `/verification:setup` — independent of whether the others are installed. Closes #263.
+
 ## [0.4.3]
 
 ### Changed

plugins/toolchain/README.md

@@ -9,7 +9,7 @@ defaults. Three skills, one concern: mechanical verification of changed code.
 |---|---|
 | `/toolchain:check` | Build + test + lint for changed files, auto-detecting affected ecosystems (.NET, Python, TypeScript, Bash, PowerShell, Markdown) from git status; resolves each ecosystem's commands through the shared four-rung ladder. Also the reference skill other plugins compose for ecosystem detection and command resolution. |
 | `/toolchain:lint` | Lint + format checks only — faster than a build cycle, honors each tool's config-file opt-in, `--fix` mode where linters support it; also owns the `yaml` and `cross-cutting` lint surfaces. |
-| `/toolchain:setup` | Configure the plugin for a repo. `check` (read-only, default) reports which ecosystems are configured, each one's resolved command surface, and the topic-docs concern file, validating the tracked files against the contract schema; `apply` interviews + infers + writes the tracked `.claude/ecosystems/<ecosystem>.yaml` files that `/toolchain:check` and `/toolchain:lint` resolve first, and offers the tracked `.claude/topic-docs.yaml` concern file. Re-runnable. |
+| `/toolchain:setup` | Configure the plugin for a repo. `check` (read-only, default) reports which ecosystems are configured and each one's resolved command surface, validating the tracked files against the contract schema; `apply` interviews + infers + writes the tracked `.claude/ecosystems/<ecosystem>.yaml` files that `/toolchain:check` and `/toolchain:lint` resolve first. Re-runnable. |
 
 ## Works in any repo
 
@@ -24,10 +24,6 @@ defaults. Three skills, one concern: mechanical verification of changed code.
   `docs/conventions/ecosystem-commands/README.md` (schema: `ecosystem.schema.json`);
   testing structure and commit conventions still come from your own `CLAUDE.md` and
   rules.
-- **Companion lifecycle plugins degrade gracefully.** `/toolchain:setup` offers the
-  `.claude/topic-docs.yaml` concern file that the `implementation` and `verification`
-  plugins resolve for artifact placement — offered independent of whether those
-  plugins are installed today.
 - **Self-contained.** All command tables, the resolution ladder, and per-ecosystem
   context ship inside the plugin and are referenced via `${CLAUDE_PLUGIN_ROOT}`; state
   and artifacts go to your project's own tree.
@@ -41,9 +37,8 @@ defaults. Three skills, one concern: mechanical verification of changed code.
 
 ## Configuration
 
-Ecosystem command surfaces live in tracked `.claude/ecosystems/*.yaml` files, and
-artifact placement is governed by the tracked `.claude/topic-docs.yaml` concern file;
-`/toolchain:setup apply` interviews for and persists both (`/toolchain:setup check`
+Ecosystem command surfaces live in tracked `.claude/ecosystems/*.yaml` files;
+`/toolchain:setup apply` interviews for and persists them (`/toolchain:setup check`
 reports the effective configuration). This plugin declares no userConfig options.
 
 ## License

plugins/toolchain/skills/setup/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: setup
-description: "Configure the toolchain plugin for this repository. check (read-only): report which ecosystems are configured, each one's resolved build/test/lint command surface, and the topic-docs concern file, validating the tracked files against the contract schema. apply: interview the user, infer per-ecosystem commands from the repo layout, and write the tracked .claude/ecosystems/<ecosystem>.yaml files that /toolchain:check and /toolchain:lint resolve first, plus the offered .claude/topic-docs.yaml concern file. Use when: 'set up toolchain', 'configure build/lint commands', 'toolchain setup', /toolchain:check or /toolchain:lint reports it is falling back to bundled defaults, a toolchain change needs recording, or a skill asks where topic documents should land. Actions: check (read-only verification, default) | apply (write the ecosystem command config and topic-docs concern file). Re-runnable and safe."
+description: "Configure the toolchain plugin for this repository. check (read-only): report which ecosystems are configured and each one's resolved build/test/lint command surface, validating the tracked files against the contract schema. apply: interview the user, infer per-ecosystem commands from the repo layout, and write the tracked .claude/ecosystems/<ecosystem>.yaml files that /toolchain:check and /toolchain:lint resolve first. Use when: 'set up toolchain', 'configure build/lint commands', 'toolchain setup', /toolchain:check or /toolchain:lint reports it is falling back to bundled defaults, or a toolchain change needs recording. Actions: check (read-only verification, default) | apply (write the ecosystem command config). Re-runnable and safe."
 argument-hint: "check | apply [<ecosystem>]"
 user-invocable: true
 disable-model-invocation: true
@@ -51,17 +51,11 @@ first**, then report a PASS/FAIL/INFO table; modify nothing.
    configured (see the inference signals under `apply`), and note that `/toolchain:check` /
    `/toolchain:lint` resolve those through inference then the bundled portable defaults. The
    remediation is `apply` to persist a command surface.
-3. **Topic-docs concern file** (`$REPO_ROOT/.claude/topic-docs.yaml`). Report present/absent and, when
-   present, the effective `contract_tier` and `vault_backend`. INFO when absent (companion plugins use
-   the documented defaults). When `vault_backend` is `gitbook`, note it is deferred and non-writable
-   (see `docs/adr/0001-defer-gitbook-as-knowledge-vault-backend.md`) — the writable promotion target
-   remains `docs`.
 
 ## `apply` (idempotent)
 
-Run `check` first. Then write the accepted ecosystem files and, when accepted, the topic-docs concern
-file. After each write, confirm the file is tracked (not gitignored) — re-run the `check` probe for
-that path rather than trusting the write.
+Run `check` first. Then write the accepted ecosystem files. After each write, confirm the file is
+tracked (not gitignored) — re-run the `check` probe for that path rather than trusting the write.
 
 ### 1. Read existing config first
 
@@ -119,38 +113,11 @@ Personal per-key overrides go in `.claude/ecosystems/<ecosystem>.local.yaml`; a
 user-global → team → local overlay, additively per key. Recommend the consumer add
 `.claude/ecosystems/*.local.*` to `.gitignore` if not already covered.
 
-### 6. Offer the topic-docs concern file
-
-Companion lifecycle plugins — `implementation` (`/implementation:implement`) and `verification`
-(`/verification:confirm`, `/verification:measure`) — place plan progress, verification manifests, and
-baselines per the topic-docs convention
-([`${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md`](${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md)). This
-skill offers the shared consumer-side concern file those plugins resolve, independent of whether they
-are installed today.
-When `$REPO_ROOT/.claude/topic-docs.yaml` is absent, offer to write it — one question, recommended
-option first (`contract_tier: branch`, the default; `local` for solo/offline work) — and materialize
-only the keys that differ from the documented defaults (always at least one explicit key, e.g.
-`contract_tier: branch` — a comment-only YAML document parses as null and fails the contract
-schema's `type: object`), offering every schema key (`contract_dir`,
-`memory_dir`, `contract_tier`, `vault_backend`). When it exists, leave it alone unless the user asks
-to reconfigure — and preserve every schema key it carries; a re-run never drops one. Before writing, run the conflict check — only when the chosen
-tier is `branch` (local mode has no committed tier to guard): `git check-ignore -v` on a
-representative file path inside the chosen contract root (e.g. `<contract_dir>/probe/PLAN.md` — a
-bare directory misses `**` patterns) — a matching ignore rule is surfaced to
-the user with the exact rule, never worked around. Never edit the consumer's root `.gitignore`; the
-resolved memory root self-ignores through its own `.gitignore`. Whenever the effective
-`vault_backend` is (or becomes) `gitbook` — preserved from an existing file or chosen by the user
-during this interview — report that GitBook is deferred and non-writable (see
-`docs/adr/0001-defer-gitbook-as-knowledge-vault-backend.md`): the effective writable promotion
-target remains `docs` until a later reviewed decision enables the backend. Do not configure or test a
-GitBook API, MCP, or Git Sync writer; offer to replace the key with `docs` only if the user chooses
-that change.
-
 ## Output
 
-Tracked `.claude/ecosystems/*.yaml` files in the consuming repo — plus `.claude/topic-docs.yaml`
-when accepted — and a one-paragraph summary of what was written and how to re-run this setup to
-reconfigure. `check` alone reports the effective configuration and changes nothing.
+Tracked `.claude/ecosystems/*.yaml` files in the consuming repo, and a one-paragraph summary of what
+was written and how to re-run this setup to reconfigure. `check` alone reports the effective
+configuration and changes nothing.
 
 ## What this skill does NOT do
 

plugins/verification/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "verification",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "Outcome-verification stage: prove a change achieved its intended outcome (`/verification:confirm` \u2014 a mechanical build/test/lint prerequisite gate, then intent-match + evidence + verdict with the criterion auto-detected by change type), and verify measurable-improvement claims against a planning-time baseline (`/verification:measure`), never fabricating numbers.",
   "author": {
     "name": "Melodic Software",

plugins/verification/CHANGELOG.md

@@ -3,6 +3,20 @@
 All notable changes to the `verification` plugin are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning.
 
+## [0.3.0]
+
+### Added
+
+- **`/verification:setup` — settles the topic-docs seam for the consuming repo.** Offers the tracked
+  `.claude/topic-docs.yaml` concern file that governs where `/verification:confirm` lands its manifests
+  (contract tier) and `/verification:measure` lands its baselines and raw captures (memory tier). `check`
+  (default) reports the effective concern read-only; `apply` persists it — non-interactively from
+  complete `<key>=<value>` arguments or via a one-question, recommendation-first interview — running the
+  committed-tier `git check-ignore` guard before writing and never editing the consumer's root
+  `.gitignore`. Mirrors the `/discovery:setup` and `/planning:setup` pattern, offering the shared file
+  independent of whether the sibling lifecycle plugins are installed. This concern was previously offered
+  by `/toolchain:setup`, a build/test/lint plugin that owns no lifecycle artifacts. Part of #263.
+
 ## [0.2.4]
 
 ### Changed

plugins/verification/README.md

@@ -9,6 +9,7 @@ green build into confirmed outcomes.
 |---|---|
 | `/verification:confirm` | Outcome verification — a mechanical prerequisite gate (delegated to build/lint) followed by intent-match + evidence + verdict, with the criterion auto-detected by change-type (feature / fix / refactor). |
 | `/verification:measure` | Measurable-improvement verification — capture a baseline at planning time, re-measure after the change under the same conditions; no baseline → honest "cannot quantify", never fabricated numbers. |
+| `/verification:setup` | Configure where verification artifacts land. `check` (read-only, default) reports the effective topic-docs concern; `apply` persists the tracked `.claude/topic-docs.yaml`. Re-runnable. |
 
 ## Works in any repo
 
@@ -42,8 +43,8 @@ green build into confirmed outcomes.
 ## Configuration
 
 Artifact placement is governed by the tracked `.claude/topic-docs.yaml` concern file
-(the `toolchain` plugin's `/toolchain:setup` interviews for and persists it). This
-plugin declares no userConfig options.
+(`/verification:setup` interviews for and persists it — `check` reports the effective
+concern read-only, `apply` writes it). This plugin declares no userConfig options.
 
 ## License