docs(knowledge): make map-corpus self-contained instead of citing a pruned Brief

[kyle-sexton]

Summary

map-corpus shipped with references to the planning document that produced it — the Q19 label in
SKILL.md, discovery/link-map-format.md, discovery/check_linkmap.py and the eval set, plus
"Brief criterion 2", "Brief criterion 6", "Brief acceptance criterion 4", "the rule the Brief owed
step 2", and "the Brief's captured content-hash assumption" across the spoke files.

That document was docs/topics/docsite-digest/PLAN.md, and it exists in no git ref:

$ git log --all --oneline -- docs/topics/docsite-digest
(no output)

That fact decides the shape of the fix. The topic-docs lifecycle allows a pruned slice to be cited
by pointer, but only a followable one — docs/conventions/topic-docs/README.md:429, "a pointer
without a followable ref is not a preservation" — which is exactly the pattern #2686 used
(git show 5341117c:docs/topics/boris-routines-adoption/PLAN.md). Here there is no commit to point
at, so no pointer form the convention accepts can be constructed. The alternative — committing
the slice instead — is affirmatively blocked: docsite-digest appears nowhere in
scripts/contract-slice-baseline.txt, so check-contract-slice-prune.sh --check-diff red-lines a
new slice by design. Making each site self-contained is therefore the only conforming outcome, not
a stylistic preference.

So each site now states what it needs, in consumer terms:

• The deferred rung-3 decision (SKILL.md, discovery/link-map-format.md) states its own fork —
  a presence-gated /firecrawl:firecrawl map seam versus a recorded reason to reimplement in-page
  extraction — its user-reserved arbiter, and its trigger (the first corpus whose seeds resolve
  neither llms.txt nor a sitemap).
• The deferred repo-tree enumeration rung states its trigger (the first corpus whose repository
  half is too large to enumerate by hand).
• The gate contract in discovery/link-map-format.md states classification coverage and the bound
  breach as the gate's own reasons to exist, rather than as external criterion numbers.
• The whole-snapshot hash in extraction/node-manifest-format.md now points at
  ${CLAUDE_PLUGIN_ROOT}/reference/citation-shape.md, which actually owns that fact
  (citation-shape.md:24 defines the hash; :41-42 ties it to map-corpus's snapshot_sha256).
• verification/inventory-format.md and verification/test_check_inventory.py keep the substantive
  rationale (two prior gates in this codebase shipped fail-open and were caught by verifiers) and
  drop only the criterion-number citation.

No behavior, schema, gate, exit code, or argument change. Only prose, one Python docstring, one
Python error-message string, and the eval set's wording of an existing expectation.

Test plan

Every command run locally against this branch.

Check	Result
python verification/test_check_inventory.py	Ran 29 tests — OK
python discovery/test_discovery.py	Ran 30 tests — OK (incl. test_no_discovery_inputs_rejected, which covers the edited branch)
check_linkmap.py no-discovery path (the edited string)	exit 2, message reworded, code unchanged
check_linkmap.py --help	argument surface unchanged (--linkmap, repeatable --discovery)
scripts/check-changed-skills.sh origin/main	CHECK-SKILL map-corpus: PASS — 0 errors, 1 warning(s) (warning is the pre-existing 204/200-line soft target)
npx markdownlint-cli2 over the changed markdown	Summary: 0 error(s) across 5 files
evals schema (ajv vs the skill-quality bundled schema)	evals.json valid
check-evals-quality.sh	PASS (0 warning(s))
scripts/check-contract-slice-prune.sh --check-diff origin/main	exit 0 — "leaves no path under docs/topics/"
scripts/check-contract-slice-prune.sh --check	exit 0 — 11 grandfathered, none stale
scripts/check-changelog-parity.sh --check / --check-bump / --check-preserved	exit 0 each

Ghost-ref sweep across the repo (excluding .git/ and the gitignored memory tier): no surviving
Q19 or docsite-digest reference in any shipped surface, and no surviving Brief / criterion
back-reference anywhere under plugins/knowledge/skills/map-corpus/. The two remaining Q19 hits
are a different topic's own question numbering in docs/topics/ladder-climb-roadmap/.

An independent fresh-context verifier re-derived the prune decision, read the gate script, re-swept
for ghost refs, and re-ran the tests with the authoring rationale withheld. It returned
PASS-WITH-FINDINGS, all findings advisory. Two are worth recording here:

• The edited fail(2, …) branch is covered for its exit code, not its message.
  discovery/test_discovery.py:354 (test_no_discovery_inputs_rejected) runs the gate with no
  --discovery and asserts exit 2; its assertion substring (at least one --discovery) sits
  before the reworded text, so the test pins the contract that matters and is indifferent to the
  wording — which is why it passes unchanged.
• The new ${CLAUDE_PLUGIN_ROOT} pointer sits outside the skill gate's scope. check-skill.sh
  check 5 walks SKILL.md only (:529-530), so the ref in extraction/node-manifest-format.md is
  not machine-checked. The identical form on SKILL.md:204 is in scope and passes, and the target
  was verified by hand. Flagged as the one line here CI would not catch if it rotted.

Anchor check, since renaming ## Evidence-token byte mapping (the rule the Brief owed step 2) to
## Evidence-token byte mapping changes its slug: repo-wide grep for inventory-format.md#,
the-rule-the-brief-owed, and evidence-token-byte-mapping returns zero hits. No dangling anchor.

The two new normative claims added to SKILL.md (a bare unguarded cross-plugin reference is barred;
dependencies are reserved for hard requires) were checked against their owner,
docs/PLUGIN-PHILOSOPHY.md:25-26,33, and are accurate.

Related

Follows the contract-slice prune pattern established by #2686, and pays down the last reference debt
left by the working slice that produced map-corpus.

No related issue: routine hygiene on a shipped skill, found while pruning the working slice that
produced it.

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[claude]

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

---

CI code review — complete

• Gather context (PR body, changed files, diff)
• Apply skip gate checks
• Review changed files for correctness / maintainability per /review:code-review
• Adversarial validation of any candidate findings
• Post inline comments (if any) and final summary

Skip gate: none apply — PR is open, not a draft, and the change (9 files, +44/-25) has a real review surface even though it's docs/prose-only.

Findings

No high-signal correctness or maintainability issues found. This is a clean, self-consistent prose/doc-string/error-string edit with no behavior, schema, gate, exit-code, or argument changes, matching what the PR body claims.

Checks I ran myself (not just restating the author's Test plan):

• git diff origin/main...HEAD review of all 9 changed files.
• Ghost-reference sweep: confirmed no Q19, Brief, docsite-digest string survives anywhere under plugins/knowledge/skills/map-corpus/ after the edit (grep -rn result was empty).
• Verified the new pointer in extraction/node-manifest-format.md:17-18 against the target — reference/citation-shape.md:24 does define the content-hash rule and :41-42 does tie it to snapshot_sha256 in map-corpus inventories/queues — the claim checks out.
• Verified evals/evals.json is still valid JSON and the reworded expected_output/expectations for eval 3 stay behaviorally equivalent to the old Q19 wording.
• Verified .claude-plugin/plugin.json version bump (0.12.1 → 0.12.2) has a matching CHANGELOG.md ## [0.12.2] entry, consistent in style with the prior 0.12.1 entry that established the same "pay down Brief-referenced debt" pattern.
• Checked discovery/check_linkmap.py's edited fail(2, ...) message — string-only change, exit code and control flow untouched.

One thing I could not independently verify (blocked by sandbox approval on running arbitrary python3/pytest invocations in this lane): the author-claimed local test runs (test_check_inventory.py, test_discovery.py, check-changed-skills.sh, markdownlint-cli2, check-contract-slice-prune.sh, check-changelog-parity.sh). I read the diffs to those test/gate files directly instead and they are string/docstring-only changes with no logic touched, which is consistent with the author's claimed results — but I'm labeling that as author-claimed and unverified by me, not independently confirmed.

No inline comments posted — no findings met the bar.

[claude]

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

---

Security review — /review:security-review

Task list

• Gather context (PR diff, files, CLAUDE.md)
• Run /review:security-review per custom instructions
• Post findings

Result: no security-relevant surface — skip gate applied

I reviewed the full diff (git diff origin/main...HEAD, 9 files, +44/-25) against this skill's skip
gate ("stop early when the change has no security-relevant surface after reading the diff").

Every change in this PR is prose or wording:

• plugins/knowledge/.claude-plugin/plugin.json — version bump 0.12.1 → 0.12.2 only.
• plugins/knowledge/CHANGELOG.md — new changelog entry (text only).
• plugins/knowledge/skills/map-corpus/SKILL.md, discovery/link-map-format.md,
  extraction/node-manifest-format.md, verification/inventory-format.md — replace an
  unfollowable planning-doc citation (Q19, "Brief criterion N") with self-contained prose stating
  the same fork, trigger, and arbiter in-line. No schema, gate logic, or control-flow change.
• discovery/check_linkmap.py — one fail(2, "...") error-message string reworded
  ("rung 3 is deferred by Q19" → "rung 3 is deferred, user-reserved"); exit code and branch
  logic unchanged.
• verification/test_check_inventory.py — module docstring reworded only; test bodies/assertions
  unchanged.
• evals/evals.json — expected_output / expectations wording updated to match; no schema or
  behavior change.

There is no touched authentication, authorization, data handling, injection surface (command/SQL/
path/template), token/secret/credential handling, or GitHub Actions workflow/permissions content in
this diff. This is a pure documentation-debt cleanup (removing references to a planning doc that
was never committed) with no runtime-behavior change, per the PR's own description and test plan.

No security findings to report.

[github-actions]

Last security-reviewed head: 5ec2e143e549c113cc02dee96bcd5f07b15628b5. On the next push, the relevance gate compares only the commits since this SHA; delete this comment to force a full re-review.

[github-actions]

Claude has reviewed this PR 1 time. The lane skips further automatic reviews after 5; deleting this comment resets the count.