toolchain/discovery/planning/verification: shared setup-skill topic-docs contract gaps (concern-file-ignore path, memory_dir root-rejection, headless-vs-forked ruling)

[kyle-sexton]

Lane: babysit. Triggering PR: #737 (fix/263-toolchain-topic-docs-relocate), head 7d3d88d1.

Worker verified the relocation's own completeness (fixed a dangling-reference gap, commit 7d3d88d1) and, while at it, surfaced 3 findings shared across the setup-skill family (/discovery:setup, /planning:setup, /verification:setup — verified verbatim-identical in all three, so not something this relocation created). Deferring per rule 3b: none of these are DEFER-FORBIDDEN classes on their own reading, but they touch the topic-docs contract's own guarantees, so fixing needs a cross-cutting pass (all setup-skill bindings, or the contract doc itself) rather than a single-plugin patch that would diverge the explicitly-mirrored family.

Category: bug (1, 2) / design-decision (3).

1. Concern-file-ignore guard checks the wrong path. The committed-tier guard probes <contract_dir> for gitignore status, never the actual .claude/topic-docs.yaml path it's meant to protect — so an ignored topic-docs.yaml is still reported as tracked. (PR refactor(toolchain): relocate setup topic-docs offering to the verification plugin that owns it #737 review comment 3616655423.)
2. Root-equivalent memory_dir isn't rejected up front. docs/conventions/topic-docs/README.md L259-262 documents memory_dir=. / empty / repo-root as invalid, but the skills only catch it via the downstream "never edit root .gitignore" backstop — not the mandated up-front stop the contract describes. (PR refactor(toolchain): relocate setup topic-docs offering to the verification plugin that owns it #737 review comment 3616882930.)
3. Headless persistence vs. forked-mode rule needs a decision, not just a fix. The contract's "a fork never writes .claude/topic-docs.yaml" (L240-245) is ambiguous on whether it governs an explicit /verification:setup apply invocation with full args (a deliberate CI/user configuration action) or only incidental placement-resolution during a fork's substantive work. Needs a ruling before any binding can be brought into compliance. (PR refactor(toolchain): relocate setup topic-docs offering to the verification plugin that owns it #737 review comment 3616882934.)

Root question for whoever picks this up: fix each binding individually (3 skills × up to 3 findings), or centralize the guard/validation logic once in the shared contract doc's reference implementation and have all three skills call it? The current pattern is copy-verbatim across three skills, which is exactly why one review surfaced the same 3 gaps in all of them.

[kyle-sexton]

Decision brief — setup-skill topic-docs contract gaps

For: human operator (this item is needs-human / wayfind: design). I am a brief-writer; I have decided nothing. Output below is one comment, no label or state change.

Anchors verified first-hand against docs/conventions/topic-docs/README.md on main and the three setup skills at PR #737 head 7d3d88d1 (plugins/{discovery,planning,verification}/skills/setup/SKILL.md). Line refs for the verification skill unless noted; discovery/verification share verbatim guard prose, planning reaches the same logic via a slightly different structure, so all three carry the same three gaps.

---

Problem (2 sentences)

Findings 1 and 2 are clear-cut bugs — a missing trackability guard on the concern file, and a missing up-front rejection of root-equivalent memory_dir — fixable as soon as the fix-scope is chosen. Finding 3 is a genuine design ruling that gates the others: the contract says "a fork never writes .claude/topic-docs.yaml," the skills explicitly let a full-arg headless apply write it, and underneath sits a structural question — patch the copy-verbatim prose in three places, or centralize the guards the way the contract already centralizes its other rules.

What is verified today

• Finding 1 — missing concern-file trackability guard (real). The committed-tier guard (check L46-50, re-run in apply L73) runs git check-ignore on a path inside the contract artifact dir (<contract_dir>/probe/PLAN.md) — which is its documented job (contract L249-254). Nothing ever runs git check-ignore on the .claude/topic-docs.yaml path the skill writes at L75-76 and then reports as persisted (L37, L80-81, Output L85). If a consumer ignores .claude/, the skill writes an ignored file and calls it tracked. Note: the guard is not misaimed (as the issue phrases it) — it correctly covers the artifact dir; the bug is the absence of any check on the concern file itself. (Review comment 3616655423.)
• Finding 2 — root-equivalent memory_dir not rejected up front (real). Contract L259-262 marks memory_dir = . / empty / repo-root invalid — stop and surface it before any self-ignore write. Skill apply L61-72 (resolve values) performs no such validation; the only protection is the downstream backstop at L79 ("Never edit the consumer's root .gitignore"). That is the backstop, not the mandated up-front stop. (Review comment 3616882930.)
• Finding 3 — fork-write rule vs explicit headless apply (genuine ambiguity). Contract L240-245: forked/headless mode "skip[s] the ask and persist[s] rungs… A fork never writes .claude/topic-docs.yaml. This rule is contract-owned; bindings cite it rather than redefining it." Skill L30-33 states a full-arg headless apply is "never prompted" and (L75-76) persists the file. The ambiguity: does the fork rule govern an explicit /verification:setup apply key=value … (a deliberate configuration act) or only incidental placement-resolution during a fork's substantive work? (Review comment 3616882934.)

---

Decision A — resolve the finding-3 ambiguity

A2 — fork rule governs ALL writes; no exemption (RECOMMENDED). Forked/headless apply becomes report-only: it resolves and surfaces what it would persist, writes nothing. Enforces the rule as written.

• Why: L244-245 is decisive — "bindings cite it rather than redefining it." Skill L30-33 is a binding redefining a contract-owned rule, which the contract forbids; so the skill is non-compliant regardless of which policy is nicer. This is the safer two-way door (start restrictive, loosen later if CI genuinely needs it; the reverse means the silent-mutation of team-shared tracked config has already happened). CI that must persist can write the concern file directly — it has a published schema — so no unique capability is lost. Matches reviewer 3616882934.
• Tradeoff / reversibility: reversible via a later contract amendment if a real headless-config need appears. Cost: removes the "headless apply persists" path the skill currently advertises.

A1 — fork rule governs ONLY incidental placement-resolution; explicit full-arg invocations exempt. Amend contract L243-244 to carve out deliberate apply invocations, then the skill's current behavior becomes compliant.

• Why it has a real case: the forked-mode paragraph (L240-243) reads as targeting incidental resolution during substantive work — an explicit configuration invocation is arguably a different act.
• Tradeoff / reversibility: note this is a contract edit, not a skill edit — you cannot reach A1 by leaving L30-33 as-is. Weaker on the safety axis (permits unattended writes to team-shared tracked config); reversible but the loosening direction is the riskier one.

Decision B — fix-scope (structural)

B1 — centralize the guards in the contract's reference implementation; the three skills cite them (RECOMMENDED).

• Why: the copy-verbatim family is the root cause this issue itself demonstrates — one review surfaced the same three gaps in all three skills. The fork rule is already contract-owned-and-cited (L244-245), while the two buggy guards live in the same "Runtime guards" section (L249-263) yet are copied into each skill's prose. B1 just extends to the guards the pattern the contract already models for one rule: fix once, no drift.
• Honest caveat: finding 3 proves a cited rule can still be contradicted by binding prose, so B1 curbs the copy-drift class (findings 1-2) but does not by itself cure compliance drift — bindings still need an audit pass. Larger up-front effort and a blast radius across the contract doc plus all three skills at once. Reversibility: medium (reverting re-introduces the drift risk).

B2 — fix each finding in place across all three skills (up to 3×3 edits).

• Why: smaller, localized, no new abstraction; each skill stays self-contained, matching the current family design.
• Tradeoff / reversibility: high reversibility, but perpetuates the drift-prone pattern — the next contract change risks re-opening the same 3× gap; up to nine edits to keep in sync.

---

Sources: PR #737 (refactor(toolchain): relocate setup topic-docs offering to the verification plugin that owns it); review comments 3616655423 (finding 1), 3616882930 (finding 2), 3616882934 (finding 3). Contract: docs/conventions/topic-docs/README.md L240-263.

No decision taken; no label or state changed by this comment.

[kyle-sexton]

Frontier disposition (drain session)

Ruling: Close as not planned.

Setup-skill topic-docs contract gaps are addressed incrementally per-plugin on touch; no fleet-wide ruling batch is staffed.

Re-open trigger: When a headless-vs-forked or memory_dir rejection causes a cross-plugin incident.