docs(skills): Contents blocks on long reference spokes (check 26) (#4071)

[kyle-sexton]

Closes #4071

Summary

Ten long reference spokes (over 300 lines) open with a ## Contents block of section anchors, so
skill-quality check 26 (long spoke files carry a table of contents) passes on them.

Fix

• claude-config: audit-pass/reference/determinism-tiers.md, audit-pass/reference/run-state-and-resumability.md (adds the lease sub-anchor to its existing block), audit/context/validation-categories.md
• claude-memory: audit/reference/official-guidance.md
• claude-ops: audit-performance/reference/known-performance-issues.md, observability/context/data-sources.md
• discovery: research/context/dispatch.md
• overengineering: audit/context/surface-walk.md
• source-control: setup/reference/apply-convention.md gains two headings (target layer and non-interactive writes; the interactive interview) so its Contents block has anchors to link; no step text changed
• writing: be-concise/reference/sources.md

Each of the seven plugins is bumped one patch above main with a dated CHANGELOG entry. No other file changes.

Verification

• scripts/check-changed-skills.sh origin/main: every touched skill PASS, no check 26 warning on any of the ten spokes
• scripts/validate-plugins.sh: all manifests and the catalog validate
• scripts/check-changelog-parity.sh --check --check-order: pass
• Every anchor matches a heading on the current file

Related

• docs: add Contents blocks to the seven reference spokes over 300 lines that check 26 flags #4071 carries needs-human with an open question about C3 ratification; this PR adds navigation only and records no decision on that question.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WejvGhkHUSWPRim2caW2Wh

[github-actions]

PR body contract — issue linkage

This PR body conforms to the issue-linkage contract. Nothing to do.

[claude]

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

---

Security review complete — no issues found

• Gather context (PR diff, changed files, /review:security-review skill)
• Apply skip gate
• Review changed files for security-relevant surface
• Report findings (or confirm none)

I read the full diff (git diff origin/main...HEAD, 66 files, +285/-76) against the /review:security-review criteria. This PR:

• Adds ## Contents anchor-link blocks to the top of ten long reference/context spokes across claude-config, claude-memory, claude-ops, discovery, overengineering, source-control, and writing (docs-only, no content moved).
• Restructures two existing prose blocks into headings in plugins/source-control/skills/setup/reference/apply-convention.md so a Contents block can link them (no content moved).
• Does a fleet-wide token rename, resolves in your session → resolves in this session, across skill-description frontmatter, SKILL.md bodies, and reference docs (per docs/conventions/native-references), plus the matching update to the GATE_TOKEN constant and its usages/tests in plugins/claude-ops/skills/audit-native-overlap/scripts/overlap.py and scripts/test_overlap.py.
• Bumps plugin versions and appends CHANGELOG.md entries accordingly.

None of this touches code paths that process untrusted input, authentication/authorization, secrets/credentials, injection surfaces (command/SQL/path/template), or GitHub Actions workflow configuration. The overlap.py/test_overlap.py changes are a literal string-constant rename used by a docs-linting parity check, not a change in logic or trust boundaries.

Skip gate applied: no security-relevant surface in this diff. No findings to report.
· branch cursor/4071-spoke-contents-37e9

[claude]

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

---

Code review complete

• Gather context (diff, CLAUDE.md/REVIEW.md conventions)
• Run skip gate (draft/closed/trivial/already-reviewed) — PR is open, not draft; reviewed
• Review changed files against code-review lane criteria
• Adversarially verify candidate findings
• Report findings (inline comment + summary)

Ran /review:code-review per the pinned instructions. Reviewed the diff against origin/main (66 files, +285/-76): ten ## Contents blocks added to long reference spokes, the apply-convention.md H2 restructuring, and the version/changelog bumps that go with them. This branch is stacked on #4112, so the diff also carries that branch's resolves in your session → resolves in this session token rename fleet-wide; I did not re-review that rename's own logic since it isn't new to this PR, but I did check it for completeness.

Verification method: for each of the ten Contents blocks and the two new headings in apply-convention.md, I diffed against origin/main, listed the file's actual ##/### headings, and hand-checked every anchor against GitHub's slug algorithm (colon/ampersand/parens stripped, spaces → hyphens, & leaves a double hyphen). All ten check out — order, nesting, and anchors all match the real headings. I could not execute scripts/check-shell-portability.sh or markdownlint in this sandbox (Bash execution beyond read-only git/grep required approval that wasn't available), so I did not independently re-run the checks the PR description claims (check 26, MD051, changelog parity) — those are author-claimed and unverified by me.

Finding (posted inline on docs/conventions/native-references/README.md:69): the token rename left a self-referential sentence — "The gate: resolves in this session (or resolves in this session)" — duplicating the same string in a place that used to document two accepted spellings. The CHANGELOG's own 3.0.0 entry says the old spelling is no longer accepted, so the parenthetical should be dropped rather than left duplicated.

Not flagged, but worth a human glance: plugins/claude-ops/skills/audit-performance/reference/known-performance-issues.md picks up two `` suppression comments mid-sentence, unrelated to the Contents-block work and not mentioned in the PR's own Verification section. They're inert HTML comments (harmless either way), so I didn't treat this as a blocking finding, but the author may want to confirm they were actually needed (i.e., that check-shell-portability.sh genuinely flagged these lines) rather than added defensively.

One informational note: the PR body's listed patch-bump versions (e.g. "claude-config 0.50.3") no longer match the diff (claude-config is actually 0.51.21 → 0.51.23) — expected drift from stacking on #4112/main, not a code issue.
· Branch

[claude]

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

---

Security review complete — no issues found

• Gather context (PR diff, changed files, /review:security-review skill)
• Apply skip gate
• Review changed files for security-relevant surface
• Report findings (or confirm none)

I read the full diff (gh pr diff 4781, 66 files, +285/-76) against the /review:security-review criteria. This PR:

• Adds ## Contents anchor-link blocks to the top of ten long reference/context spokes across claude-config, claude-memory, claude-ops, discovery, overengineering, source-control, and writing (docs-only, no content moved).
• Restructures two prose blocks into H2 headings in plugins/source-control/skills/setup/reference/apply-convention.md so a Contents block can link all three sections (no content moved).
• Fleet-wide token rename, resolves in your session → resolves in this session, across skill-description frontmatter, SKILL.md bodies, and reference docs, plus the matching update to the GATE_TOKEN constant and its usages/tests in plugins/claude-ops/skills/audit-native-overlap/scripts/overlap.py and scripts/test_overlap.py.
• Bumps plugin versions and appends CHANGELOG.md entries accordingly.

Skip gate applied: no security-relevant surface in this diff — no untrusted input handling, auth/authorization, secrets/credentials, injection surfaces (command/SQL/path/template), or GitHub Actions workflow changes. The overlap.py/test_overlap.py changes are a literal string-constant rename used by a docs-linting parity check, not a change in logic or trust boundaries. No findings to report.
· branch cursor/4071-spoke-contents-37e9

[claude]

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

---

Security review complete — no issues found

• Gather context (PR diff, changed files, /review:security-review skill)
• Apply skip gate
• Review changed files for security-relevant surface
• Report findings (or confirm none)

Reviewed the current PR head (3c5c0b9) via git diff origin/main...HEAD — 24 files, +186/-22, matching the PR's stated diffstat. (Note: earlier security-review comments on this thread were run against a different, larger diff of this branch, 66 files/+285/-76, that included a since-merged fleet-wide token rename; that content is no longer part of this PR's diff and is not re-reviewed here.)

This PR's actual content:

• Adds ## Contents anchor-link blocks to ten long reference/context spokes across claude-config, claude-memory, claude-ops, discovery, overengineering, and writing — pure additive navigation, no prose content moved or changed.
• Restructures plugins/source-control/skills/setup/reference/apply-convention.md: converts a flat bullet list at the top into two new ## headings ("Target layer and non-interactive writes", "The interactive interview") so the new Contents block has anchors to link. No step text, ordering, or instructions changed — checked the diff line-by-line against the instruction-exception register lens (this skill's guidance on deletions/narrowing of standing instructions): nothing is deleted or softened here, only re-anchored.
• Bumps each of the seven plugins' plugin.json version by one patch and appends a matching CHANGELOG.md entry.

None of this touches untrusted-input handling, authentication/authorization, secrets/credentials, injection surfaces (command/SQL/path/template), or GitHub Actions workflow files. No .github/workflows files are in this diff.

Skip gate applied: no security-relevant surface in this diff. No findings to report.
· branch cursor/4071-spoke-contents-37e9

[claude]

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

---

Code review complete

• Gather context (diff against origin/main, AGENTS.md/CLAUDE.md conventions)
• Run skip gate — PR is open, not draft, not trivial-automated (reviewable content change); no prior review on this head applies (this head's diff is 24 files/+186/-22, distinct from the earlier reviews on this branch, which covered a since-resolved stacked-branch diff of 66 files that no longer applies now that Retoken the native-surface presence gate so descriptions carry no second person #4112 merged into main)
• Review changed files against code-review lane criteria
• Adversarially verify candidate findings
• Report findings

Scope: ten ## Contents anchor-link blocks added to long reference/context spokes across claude-config, claude-memory, claude-ops, discovery, overengineering, source-control, and writing, plus the matching per-plugin patch bump and CHANGELOG.md entry (7 plugins × plugin.json + CHANGELOG.md = 14 files, + 10 spoke files = 24, matching the diff).

Verification method: for each of the ten Contents blocks (and the two new H2s in plugins/source-control/skills/setup/reference/apply-convention.md), I extracted every actual ##/### heading in the file and hand-checked each Contents anchor against GitHub's heading-slug algorithm (lowercase, strip punctuation/backticks/markdown, collapse to hyphens — including the double-hyphen cases from &, +, and stripped colons, e.g. Category A: Schema & Structure → #category-a-schema--structure, 7. Git + GH activity (context for severity) → #7-git--gh-activity-context-for-severity). All ten files' anchors match their real headings exactly, in the right order.

For apply-convention.md specifically, I confirmed the two new H2s (## Target layer and non-interactive writes, ## The interactive interview) only wrap existing prose — no step text changed, matching the PR description and the CHANGELOG entry's claim.

Version bumps and CHANGELOG entries are consistent: each of the 7 touched plugins bumps exactly one patch version above its current main value, with a changelog entry naming the specific spoke(s) touched.

No findings. This is a mechanical, low-risk change (docs navigation only, no content moved or altered) and it's internally consistent. I could not execute scripts/check-changed-skills.sh or scripts/validate-plugins.sh myself in this sandbox, so the check-26/manifest-validation claims in the PR description are author-claimed and unverified by me — my own verification above was a manual anchor-by-anchor check against the actual heading text, which is why I'm confident despite not running the scripts.
· branch cursor/4071-spoke-contents-37e9

[claude]

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

---

Security review complete — no issues found

• Gather context (PR diff via gh pr diff 4781, 24 files, +190/-24)
• Apply skip gate
• Review changed files for security-relevant surface
• Report findings (or confirm none)

Reviewed the current PR head (4ea75e7) diff against origin/main, 24 files, matching the diffstat in the PR description. Content:

• Adds ## Contents anchor-link blocks to ten long reference/context spokes across claude-config, claude-memory, claude-ops, discovery, overengineering, and writing — pure additive navigation, no prose content moved or changed.
• Restructures plugins/source-control/skills/setup/reference/apply-convention.md: converts a flat bullet list into two new ## headings ("Target layer and non-interactive writes", "The interactive interview") so the new Contents block has anchors to link. Checked line-by-line under the instruction-surface lens (this is exactly the pattern that lens exists to catch — a restructure that looks prose-only can quietly drop a rule): every bullet, step, and the layer=/subject_pattern=/branch_issue_pattern= prose carries over unchanged, nothing is deleted, narrowed, or softened. No standing instruction is affected.
• Bumps each of the 7 touched plugins' plugin.json version by one patch and appends a matching CHANGELOG.md entry (no code changes accompany the bumps).

None of this touches untrusted-input handling, authentication/authorization, secrets/credentials, injection surfaces (command/SQL/path/template), or GitHub Actions workflow files — no .github/workflows files are in this diff, and no scripts changed.

Skip gate applied: no security-relevant surface in this diff. No findings to report.
· branch cursor/4071-spoke-contents-37e9

[claude]

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

---

Code review complete

• Gather context (gh pr diff 4781, AGENTS.md/CLAUDE.md conventions, /review:code-review skill instructions)
• Run skip gate — PR is open, not draft; head 4ea75e7 is new since the last review on this branch (a Merge remote-tracking branch 'origin/main' commit landed after the prior review), so this is a fresh pass rather than a skip
• Review changed files against code-review lane criteria
• Adversarially verify candidate findings
• Report findings

Scope: gh pr diff 4781 — 24 files, +190/-24, matching the PR's stated diffstat: ten ## Contents anchor-link blocks added to long reference/context spokes across claude-config, claude-memory, claude-ops, discovery, overengineering, source-control, and writing, the two new H2 headings in apply-convention.md that the Contents block links, plus the matching per-plugin patch-version bump and CHANGELOG.md entry (7 × plugin.json + CHANGELOG.md = 14 files, + 10 spoke files = 24).

Verification method: I read each of the ten touched files in full at the current head (not just the diff hunks) and, for every entry in its new ## Contents block, hand-checked the anchor against GitHub's actual heading-slug algorithm against the real heading text in that file — including the punctuation-stripping edge cases (& and + leaving a double hyphen, ` backticks and parens stripped, 4.5 losing its dot, --resume inside a heading keeping its literal double hyphen). All ten files' Contents entries resolve to a heading that actually exists, in the right order and nesting. For apply-convention.md specifically, the two new headings (## Target layer and non-interactive writes, ## The interactive interview) wrap only pre-existing prose — no step text, ordering, or instructions changed, matching the PR description and CHANGELOG entry.

Version bumps and CHANGELOG entries are internally consistent: each of the 7 touched plugins bumps exactly one patch version above its pre-PR value, with a changelog entry naming the specific spoke(s) touched.

On the earlier review threads on this branch: the two prior code-review comments here were against an older head (3c5c0b9, and before that a 66-file head carrying a since-merged fleet-wide token rename). That rename and its associated README.md finding are no longer part of this PR's diff — docs/conventions/native-references/README.md is not among the 24 files changed at the current head — so that finding does not apply here and I did not re-flag it.

No findings. This is a mechanical, low-risk, docs-only navigation change with no content moved or altered, and it holds up under a full anchor-by-anchor check rather than a sampled one.

Not independently verified: scripts/check-changed-skills.sh, scripts/validate-plugins.sh, and scripts/check-changelog-parity.sh, which the PR description cites as passing — I did not have shell access to run them in this session, so those results are author-claimed, not confirmed by me. My own verification above is the manual per-anchor check described.
· Branch