feat(docs-hygiene): repo-wide sweep escalation for audit-derivability + apply the sweep's confirmed verdicts

[kyle-sexton]

No linked issue

Summary

Three phases in one branch. First, /docs-hygiene:audit-derivability's empty-target no-op became a confirmation-gated repo-wide sweep escalation, with the sweep contract scaled to large corpora. Second, that sweep ran against this repo (1131 tracked .md, 68 batched read-only subagents, fresh-context spot-tests) and its confirmed verdicts were applied. Third, a /plugin-quality:audit of the five components this session exercised fed back fixes to the sweep skill itself and to four sibling plugins.

Fix

Skill change (docs-hygiene 0.12.0): offer-only repo-wide escalation with prescribed defaults; large-corpus batching with bounded ledger output; the spot-test cap defers (provisional verdicts excluded from actionable routing), never waives; tracked-only sweep scope with single-combined-pathspec enumeration (git ls-files -- '<dir>/*.md' — the earlier two-pathspec form OR'd and silently swept the whole repo); eval 10 added.

Applied sweep verdicts (four plugins): claude-ops 0.32.3, machine-health 0.10.3, repo-hygiene 0.10.4 pointer conversions; toolchain 0.13.1 README de-duplication. Deliberate holds recorded: five checklist runtime scaffolds, the Linux NOT_IMPLEMENTED.md placeholder, the empty unhobble-baseline root CLAUDE.md (#2188).

Plugin-quality audit remediations:

• docs-hygiene (audit-derivability): functional-artifact out-of-scope disposition (source of 5 wrong verdicts); git-log deliberate-state check before deleting empty files; pointer verdicts verify their anchors; sweep reports scope+count pre-fan-out, reconciles near-identical cross-batch siblings, samples keep verdicts, defers exclusions to extract-ssot's list; repo-scoped read-only rule; 3 regression evals.
• guardrails 0.28.27: staged-write (producer > tmp && mv) named as a residual in the scope note + README with the secret-guard consequence stated; harness-timeout fail-open edge documented. Test suite 426/426. Follow-ups recorded (narrow same-command detector, repo-layer content invariants), deliberately not rushed.
• markdown-format 0.11.17: skip notice states real semantics + hook environment inheritance (root cause: hooks inherit Claude Code's process env, not the shell profile, so nvm-provisioned tools are invisible to hooks); markdownlint-cli2 added as exact repo devDependency so the filesystem probe resolves in cloud sessions.
• session-flow 0.23.5 (orchestrate): fork claim narrowed to the documented sentence; workflow/teammate runtime caps added to the cap inventory (the CPU-dependent cap that bound the evidence run at 2 concurrent); ${CLAUDE_EFFORT} self-detects direct-read fallback; sources re-verified 2026-08-15.
• discipline 0.12.8: manifest enumeration opened; third declared delta counted; reciprocal sibling-boundary pointers.

Verification

• Sweep coverage script-verified (68/68 batches, 1131 entries, 0 dup/missing); 10/10 flagged verdicts spot-tested (4 confirmed, 6 overturned).
• Audit findings grounded per finding in session evidence + current official docs (hooks/sub-agents/workflows/skills pages fetched 2026-08-15); pathspec fix empirically reproduced by the PR's review lane (1133 → 4 files, recursion preserved).
• guardrails block-hook-bypass tests: 426/426 pass; bash -n clean on all edited hooks.
• generate-catalog regenerated + generate-cheatsheet --check in sync; validate-plugins.sh passed; markdownlint 0 issues on 13 changed files; typos clean; all JSON validated.

Related

Refs #2188 (unhobble bare baseline — reason the empty root CLAUDE.md is kept)

🤖 Generated with Claude Code

https://claude.ai/code/session_01NfA3WGc3me6akomM3iQNZo

[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 encountered an error after 0s —— View job

---

I'll analyze this and get back to you.

[claude]

Claude encountered an error after 0s —— View job

---

I'll analyze this and get back to you.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a76cbb0398

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[claude]

Claude encountered an error after 0s —— View job

---

I'll analyze this and get back to you.

[claude]

Claude encountered an error after 0s —— View job

---

I'll analyze this and get back to you.

[claude]

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

---

Code review — /review:code-review

Reviewed the diff at 60fc8e0 against origin/main (17 files, mostly a version-bump wave plus doc-to-pointer conversions dogfooding this very skill). Focused on the substantive logic change: plugins/docs-hygiene/skills/audit-derivability/SKILL.md.

Codex's two prior findings on this PR (P1 ledger-bounding, P2 spot-test-cap/hard-rule conflict) both look resolved by commit fc0dc5f — the reply now carries only the aggregate + actionable subset + ledger pointers (not full per-document detail), and past-cap verdicts are explicitly demoted to "provisional" rather than silently skipping the spot-test.

However, reconciling P2 introduced a new internal contradiction, and the escalation's new default scope doesn't fully line up with the action it delegates to. Two inline findings posted:

1. 🔴 Important — SKILL.md:116: the corpus-scale output line says the reply's "actionable … subset" is "split into confirmed vs provisional" — i.e. provisional verdicts are part of the actionable subset. That contradicts the prescribed-defaults bullet (line 88) and the Hard Rules addition (line 125) two sections later, both of which say a provisional (cap-deferred) verdict is excluded from actionable routing. As written, an agent following the output-schema line alone could still offer to route an un-spot-tested delete to the work-item tracker — the exact failure this PR's second commit was meant to close.
2. 🟡 Suggestion — SKILL.md:84: the escalation's default scope is git ls-files '*.md' (tracked-only), but the sweep <dir> action it says it runs as is contractually just "a directory to walk recursively" with no tracked-vs-untracked filtering stated anywhere (router row or context/rubric.md). Sibling skills in this plugin (extract-ssot/actions/identify.md, extract-ssot/context/lessons.md) already codify a "git ls-files only, exclude gitignored/vendored" convention explicitly — worth doing the same here so the escalation's promised scope actually matches what sweep does when driven by it.

Everything else checked out:

• The pointer-conversion files (claude-ops, machine-health, repo-hygiene, toolchain READMEs/TODOs) all point at real, existing files/symbols — spot-checked registry_manager.py's REQUIRED_FIELDS / VALID_CATEGORIES / VALID_STATUSES / validate_issue() / resolve_data_dir(), machine-health's references/shared/approvals.md and references/windows/remediation-policy.md, and repo-hygiene's cleanup-config.md + clean-*.sh/git-*.sh scripts — all present.
• Version bumps and CHANGELOG entries are consistent with the corresponding file changes in each plugin.
• New eval 10 covers the offer-only escalation behavior as described (it's inserted out of numeric order relative to eval 8/9 in the file, but IDs are unique and this is not functionally significant — not reported as a finding).
• No security-lane concerns — this PR is documentation/skill-instruction only, no code paths, no auth/data-access changes. (This repo has a dedicated claude-security-review lane, so security scope is intentionally out of this lane regardless.)

Both findings are about the newly-added text reconciling with itself/the existing action contract, not implementation bugs — this is a documentation-only PR, so "fixing" them means further wordsmithing this section for internal consistency.

[claude]

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

---

Security Review

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

Skip gate met — no security-relevant surface. Reviewed the full diff (gh pr diff against origin/main) across all 17 changed files. Every change is one of:

• plugin.json version bumps (patch/minor)
• CHANGELOG.md additions documenting the rationale for each doc change
• Markdown documentation restructured into pointers to their authoritative source (registry-schema.md, machine-health TODO.md, ecosystems.md, toolchain README.md)
• SKILL.md prose changes to audit-derivability describing an offer-only, confirmation-gated escalation path, plus a batching contract for large corpus sweeps
• A new eval entry (evals.json) covering the offer-only behavior

No code, scripts, or GitHub Actions workflow files are touched. The new audit-derivability behavior is read-only by explicit hard rule (no Edit/Write/mutating Bash), requires explicit user confirmation before any repo-wide scan runs, and never auto-files or auto-edits — there's no injection surface, no credential/token handling, no authorization logic, and no trust-boundary crossing introduced by this diff.

Per /review:security-review's skip gate ("change has no security-relevant surface after reading the diff"), stopping here with no findings.

[github-actions]

Last security-reviewed head: 156a718586b0a963d39bd838a7555593b7ef73aa. 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 5 times. The lane skips further automatic reviews after 5; deleting this comment resets the count.

[claude]

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

---

Claude finished @kyle-sexton's task in 3m

• Gather context (PR diff, custom instructions)
• Run /review:code-review per custom instructions
• Post findings

Code review — /review:code-review

Reviewed the diff at 5206b56 (17 files). This head commit was pushed specifically to address the two prior findings on this PR, so I focused on verifying that fix plus a fresh pass over the rest of the diff.

Both prior findings are now resolved, exactly as suggested:

1. Codex P2 / earlier Claude finding (provisional-verdict contradiction) — SKILL.md:116 now reads "the confirmed-actionable (delete / convert-to-pointer) subset, the provisional (cap-deferred) verdicts reported separately for visibility — never as part of the actionable subset." This now agrees with the prescribed-defaults bullet (line 88) and the Hard Rules addition (line 125) — all three now consistently exclude provisional verdicts from actionable routing.
2. Earlier Claude finding (scope/action-contract mismatch) — the sweep <dir> router row (SKILL.md:68) now states the tracked-only scope explicitly ("Corpus audit of the directory's tracked markdown (enumerate via git ls-files '*.md' -- <dir>; gitignored, untracked, and vendored/ephemeral files are out of scope...)"), matching the escalation's default scope at line 84 and the extract-ssot convention it cites.

Rest of the diff — no new issues found:

• The four pointer-conversion docs (claude-ops, machine-health, repo-hygiene, toolchain) all resolve to real files/symbols. Re-verified: registry_manager.py's REQUIRED_FIELDS/VALID_CATEGORIES/VALID_STATUSES/validate_issue()/resolve_data_dir(), machine-health's references/shared/approvals.md + references/windows/remediation-policy.md, repo-hygiene's cleanup-config.md + all five referenced scripts, and toolchain's docs/conventions/ecosystem-commands/README.md + ecosystem.schema.json — all present.
• plugin.json version bumps match the CHANGELOG entries and PR description (claude-ops 0.32.3, docs-hygiene 0.12.0, machine-health 0.10.3, repo-hygiene 0.10.4, toolchain 0.13.1).
• context/rubric.md has no residual "directory to walk recursively" language that would conflict with the new tracked-only sweep contract.
• New eval 10 is present and matches the offer-only escalation behavior; it's inserted out of numeric order relative to evals 8/9 (non-functional, IDs still unique — not a finding).
• No security-relevant surface (doc/skill-instruction only, read-only hard rules unchanged) — consistent with the separate security-review lane's skip verdict on this PR.

No inline comments needed this pass — everything flagged previously is fixed, and no new findings surfaced.

[claude]

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

---

Security Review

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

Skip gate met — no security-relevant surface. This lane's relevance gate compares only the commits since the last-reviewed head (60fc8e0, reviewed 2026-08-15T10:29:08Z). The only change since then is commit 5206b56, which touches a single file:

• plugins/docs-hygiene/skills/audit-derivability/SKILL.md — 2 prose edits reconciling the sweep <dir> action's scope (now explicitly git ls-files '*.md', tracked-only) and the output-schema line (provisional cap-deferred verdicts now explicitly excluded from the actionable subset) with the rest of the document. This is exactly the fix for the two review findings raised earlier on this PR (Codex P2 and my own inline finding on the actionable-subset wording).

No code, scripts, or GitHub Actions workflow files are touched by this commit. The change is prose-only within an agent-instruction Markdown file — no auth/access-control logic, no injection surface, no secrets/token handling, no trust-boundary crossing. Reviewing the full cumulative diff (origin/main...HEAD, 17 files) confirms the same holds repo-wide: version bumps, CHANGELOG entries, and doc-to-pointer conversions, none of which introduce security-relevant surface.

Per the skip gate ("change has no security-relevant surface after reading the diff"), stopping here with no findings.

[claude]

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

---

Security Review

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

Skip gate met — no security-relevant surface. This lane's relevance gate compares only the commits since the last-reviewed head (5206b56, reviewed 2026-08-15T10:34:06Z). The only change since then is commit c66ce34, which touches a single file:

• plugins/docs-hygiene/skills/audit-derivability/SKILL.md — one-line prose fix to the sweep <dir> row's git ls-files example: replaces two OR'd pathspecs ('*.md' -- <dir>, which silently escalates a directory-scoped sweep to the whole repo) with a single combined pathspec (-- '<dir>/*.md').

No code, scripts, or GitHub Actions workflow files are touched by this commit. The change is prose-only within an agent-instruction Markdown file, correcting a scope-widening documentation bug in an example command — no auth/access-control logic, no injection surface, no secrets/token handling, no trust-boundary crossing. Reviewing the full cumulative diff (origin/main...HEAD, 17 files) confirms the same holds repo-wide: version bumps, CHANGELOG entries, and doc-to-pointer conversions, none of which introduce security-relevant surface — consistent with this lane's prior passes on 60fc8e0 and 5206b56.

Per the skip gate ("change has no security-relevant surface after reading the diff"), stopping here with no findings.

[claude]

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

---

Code review — /review:code-review

• Gather context (PR diff, custom instructions)
• Invoke /review:code-review skill and follow its procedure
• Post findings

Reviewed the diff since the last review on this lane (last-reviewed head 5206b56; current head c66ce34). The only change is a single-line fix in plugins/docs-hygiene/skills/audit-derivability/SKILL.md:68.

What it fixes: the sweep <dir> action's enumeration command was git ls-files '*.md' -- <dir> — two pathspecs, which git ls-files ORs together rather than intersecting. Since '*.md' alone already matches every tracked markdown file repo-wide, the second pathspec (<dir>) added nothing, and a directory-scoped sweep silently widened to the whole repo. The fix switches to a single combined pathspec, git ls-files -- '<dir>/*.md'.

Verified empirically (not just read) against this repo's actual tree, using plugins/docs-hygiene/skills/audit-derivability as the test directory (chosen because it has a .md file two levels deep, evals/fixtures/derivable-with-source/runtime-settings.md, to confirm recursion isn't lost by the fix):

• Old buggy form — git ls-files '*.md' -- plugins/docs-hygiene/skills/audit-derivability → 1133 files (essentially the whole repo, confirming the escalation bug as described).
• New form — git ls-files -- 'plugins/docs-hygiene/skills/audit-derivability/*.md' → 4 files, correctly scoped to the directory and still recursive (it picks up the nested fixture file two levels down, so the sweep <dir> row's "walk recursively" contract still holds under the fix).

Also checked for residual references to the old two-pathspec form elsewhere in the skill (context/rubric.md, the repo-wide-escalation defaults at line 84, evals.json) — none found. Line 84's git ls-files '*.md' is the correct, unrelated repo-wide-default case (no directory to combine with), and the user-narrows-to-a-directory path there correctly routes through the now-fixed sweep <dir> row.

No findings. This commit is a small, well-verified, self-contained bug fix with no loose ends.

[claude]

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

---

Code review — /review:code-review

• Gather context (PR diff, custom instructions)
• Invoke /review:code-review skill and follow its procedure
• Post findings

Reviewed the diff since the last review on this lane (last-reviewed head c66ce34, "no findings"; current head 0051b32). The only new commit is 0051b32, "apply plugin-quality audit findings across five exercised components" — a large prose/instruction diff across docs-hygiene, guardrails, markdown-format, session-flow, and discipline (24 files, all Markdown/JSON/shell-comment changes, no executable logic changed beyond string literals).

One finding posted inline — plugins/docs-hygiene/skills/audit-derivability/SKILL.md:117: the new aggregate-output line adds a <r> routed-to-sibling bucket, but no verdict class, output-schema enum, or hard rule anywhere in the file (or in context/rubric.md) ever defines when a whole document earns that disposition — the Verdict classes table still lists only the original four verdicts, and the closest existing concept (line 61's per-claim "duplication → /docs-hygiene:extract-ssot" routing) feeds a provisional verdict among the four, not a fifth document-level outcome. Its sibling addition in the same edit, <f> out-of-scope functional artifacts, is properly defined (line 51 + rubric.md); routed-to-sibling isn't. This is the same class of contract-inconsistency this PR's earlier commits (fc0dc5f, 5206b56) were written to close.

Rest of the diff — no issues found:

• docs-hygiene (SKILL.md, context/rubric.md, evals/evals.json): the functional-artifact out-of-scope disposition, git-log deliberate-state check, convert-to-pointer anchor-verification rule, and sweep same-basename/keep-sampling additions are internally consistent with the rest of the file (aside from the one finding above). evals.json is valid JSON with unique eval IDs (13 entries; non-sequential order is cosmetic, not functional, consistent with the prior review pass's note on eval 10).
• guardrails (block-hook-bypass.sh, block-noncanonical-commit.sh, README.md): all changes are comment/message string edits (staged-write residual naming, harness-timeout residual note) — no control-flow changes; quoting/escaping in the edited string literals is balanced.
• markdown-format (markdown-format.sh, package.json): skip-notice string reworded for accuracy; markdownlint-cli2 pinned as an exact-version devDependency, consistent with the stated cloud-session PATH-inheritance root cause.
• session-flow (orchestrate/SKILL.md, context/sources.md): new caveats (workflow/teammate limits are CPU-dependent and separate from the Agent-tool env vars; the fork-is-a-leaf claim narrowed to what the docs actually state) read as accurate refinements, not contradictions of existing text.
• discipline (three SKILL.md files + manifest description): reciprocal sibling-boundary pointers between reason-dont-recite, pick-for-the-problem, and reuse-or-replace are consistent both directions; scrutinize-dont-coast's "two deltas" → "three deltas" edit correctly cross-references its own existing "adversarial pass runs in a fresh context" section.
• All five touched plugin.json manifests are valid JSON with version bumps matching their CHANGELOG.md entries.

Not independently verified (author-claimed only): the PR body's "68/68 batches, 1131 unique ledger entries" sweep-coverage script check, block-hook-bypass "426/426 pass" test-suite claim, and the markdownlint/typos/catalog-check commands — this session's Bash access is scoped to read-only git/gh (per this lane's allowed-tools), so node scripts/generate-catalog.mjs --check, markdownlint-cli2, and the plugin's own test runner could not be executed here to confirm.
— branch: claude/docs-hygiene-audit-derivability-o12zbc

[claude]

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

---

Security Review

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

Skip gate met — no security-relevant surface. This lane's relevance gate compares only the commits since the last-reviewed head (c66ce34, reviewed 2026-08-15T17:10:51Z). The only change since then is commit 0051b32, "fix: apply plugin-quality audit findings across five exercised components" (24 files), which is:

• plugin.json version bumps + CHANGELOG.md entries (discipline 0.12.8, guardrails 0.28.26, markdown-format 0.11.17, session-flow 0.23.5, docs-hygiene), and one docs/CATALOG.md description sync.
• Prose-only edits across skill/context Markdown (discipline's pick-for-the-problem, reason-dont-recite, scrutinize-dont-coast; session-flow's orchestrate/SKILL.md + context/sources.md; docs-hygiene's audit-derivability/SKILL.md + context/rubric.md) — cross-referencing sibling skills, replacing an external issue-tracker citation with an internal one, adding scope/out-of-scope rules and worked examples to the audit-derivability rubric. No behavior with security surface (still read-only, no Edit/Write/mutating Bash).
• guardrails/hooks/block-hook-bypass.sh and block-noncanonical-commit.sh — comment-only additions (no code/logic changed): documenting an already-known "staged write moved into place" residual and a hook-timeout edge case. markdown-format/hooks/markdown-format.sh — a PostToolUse notice string reworded, no logic change.
• package.json / package-lock.json — adds markdownlint-cli2@0.23.1 as a pinned devDependency; checked the lockfile diff, every new entry resolves to https://registry.npmjs.org (no non-standard registries or unpinned refs introduced).
• evals/evals.json — new/renumbered eval fixtures for the audit-derivability skill (prompts + expected agent behavior), no executable content.

No code, scripts (beyond the comment-only hook edits), or GitHub Actions workflow files carry logic changes. Nothing here touches auth/access-control, introduces an injection surface, handles secrets/tokens, or crosses a trust boundary. Consistent with this lane's prior passes on 60fc8e0, 5206b56, and c66ce34.

Per the skip gate ("change has no security-relevant surface after reading the diff"), stopping here with no findings.

[claude]

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

---

Security Review

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

Skip gate met — no security-relevant surface. This lane's relevance gate compares only the commits since the last-reviewed head (0051b32, reviewed 2026-08-15T17:20:30Z). The only change since then is commit 566e5e1, "fix(docs-hygiene): cross-skill citation form and injection fallback for the skill-quality gate," which touches a single file:

• plugins/docs-hygiene/skills/audit-derivability/SKILL.md — two prose/script tweaks:
  • Line 15: appends || echo "(status unavailable)" to the pre-computed-context git status --porcelain pipeline. This is a resilience fallback for a pre-existing read-only command (no new subprocess, no new input, no privilege change) — it only changes what prints when git status fails, not what it can do.
  • Line 72: rewrites a cross-skill citation from prose ("its actions/identify.md") to an explicit path (${CLAUDE_PLUGIN_ROOT}/skills/extract-ssot/actions/identify.md). This is a documentation pointer inside agent-instruction Markdown, not executable code — it doesn't introduce a new read/write surface or change the skill's hard rules (still read-only, no Edit/Write/mutating Bash).

No code, scripts, or GitHub Actions workflow files are touched by this commit. No auth/access-control logic, no injection surface, no secrets/token handling, no trust-boundary crossing. Consistent with this lane's prior passes on 60fc8e0, 5206b56, c66ce34, and 0051b32.

Per the skip gate ("change has no security-relevant surface after reading the diff"), stopping here with no findings.

[claude]

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

---

Code review — /review:code-review

• Gather context (PR diff, custom instructions)
• Invoke /review:code-review skill and follow its procedure
• Post findings

Reviewed the diff since the last code-review-lane pass on this PR (last-reviewed head c66ce34; current head 566e5e1) — commits 0051b32 and 566e5e1, 24 files.

One finding posted inline — the pre-compute fallback that 566e5e1 re-added is itself dead, for the same reason its predecessor was removed as dead two commits earlier in 0051b32. See SKILL.md:15 for the detail — inline comment posted there.

Rest of the diff — no further findings:

• docs-hygiene rubric/evals additions (functional-artifact out-of-scope disposition, git-log deliberate-state check, pointer-anchor verification, sweep batching/reconciliation/scope-exclusion changes) are internally consistent; new evals 8/11/12/13 have unique IDs and match their stated behavior; no residual references to the old two-pathspec git ls-files form.
• session-flow/orchestrate SKILL.md + context/sources.md: fork-is-a-leaf claim narrowed to what the cited docs actually state, workflow/teammate caps and the CPU-dependent concurrency clause added, all citations dated/sourced.
• discipline sibling-boundary cross-references (pick-for-the-problem, reason-dont-recite, scrutinize-dont-coast) are reciprocal and consistent with each other.
• guardrails (block-hook-bypass.sh, block-noncanonical-commit.sh) and markdown-format (markdown-format.sh) changes are comment/message-text only, no logic touched — matches the security lane's read on 0051b32.
• plugin.json version bumps match their CHANGELOG.md heads for all five touched plugins (discipline 0.12.8, docs-hygiene 0.12.0, guardrails 0.28.26, markdown-format 0.11.17, session-flow 0.23.5).
• package.json/package-lock.json: markdownlint-cli2@0.23.1 pinned as an exact devDependency, consistent with the stated purpose (cloud-session PATH resolution for the markdown-format hook's filesystem probe).
  · branch claude/docs-hygiene-audit-derivability-o12zbc

[claude]

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

---

Security Review

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

Skip gate met — no security-relevant surface. This lane's relevance gate compares only the commits since the last-reviewed head (566e5e1, reviewed 2026-08-15T17:23:15Z). The only change since then is commit aaca6ad, "fix(docs-hygiene): define route-to-sibling as a verdict annotation, not an undefined bucket," which touches a single file:

• plugins/docs-hygiene/skills/audit-derivability/SKILL.md — resolves the outstanding review finding on <r> routed-to-sibling by redefining it as an annotation on an existing verdict (not a fifth, previously-undefined verdict class): the aggregate line now reads <d> delete, <p> convert-to-pointer, <c> keep-as-cache, <k> keep-owns-facts, <f> out-of-scope functional artifacts; <r> of the verdicts also carry a route-to-sibling annotation, plus a new paragraph defining when a verdict carries that annotation (doc-to-doc duplication → /docs-hygiene:extract-ssot, line-level noise → /docs-hygiene:audit-noise).

This is a prose-only edit to an agent-instruction Markdown file. No code, scripts, or GitHub Actions workflow files are touched. No auth/access-control logic, no injection surface, no secrets/token handling, no trust-boundary crossing. Consistent with this lane's prior passes on 60fc8e0, 5206b56, c66ce34, 0051b32, and 566e5e1.

Per the skip gate ("change has no security-relevant surface after reading the diff"), stopping here with no findings.
— branch: claude/docs-hygiene-audit-derivability-o12zbc

[claude]

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

---

Security Review

• Gather context (PR diff since last-reviewed head, custom instructions)
• Invoke /review:security-review and follow its procedure
• Post findings

Skip gate met — no security-relevant surface. This lane's relevance gate compares only the commits since the last-reviewed head (aaca6ad, reviewed 2026-08-15T17:25:29Z). The only change since then is commit a9a18d4, "fix(docs-hygiene): make the pre-compute fallback actually fire on git failure," which touches a single line:

• plugins/docs-hygiene/skills/audit-derivability/SKILL.md:15 — restructures the pre-computed-context line's shell pipeline from git status --porcelain 2>/dev/null | awk '...' | head -20 || echo "(status unavailable)" to s=$(git status --porcelain 2>/dev/null) && printf '%s\n' "$s" | awk '...' | head -20 || echo "(status unavailable)". This addresses the correctness finding raised on the prior commit (566e5e1): without pipefail, a trailing || on a three-stage pipe binds to head's exit status, not git status's, so the fallback could never fire. Capturing git status's exit status into the s=$(...) assignment first, gated with &&, makes the || fallback correctly trigger only when git status itself fails.

This is a read-only shell-command restructuring inside an agent-instruction Markdown file's pre-computed-context block (same git status/awk/head primitives as before, no new command, no write). No code, scripts, or GitHub Actions workflow files are touched. No auth/access-control logic, no injection surface introduced, no secrets/token handling, no trust-boundary crossing. Consistent with this lane's prior passes on 60fc8e0, 5206b56, c66ce34, 0051b32, 566e5e1, and aaca6ad.

Per the skip gate ("change has no security-relevant surface after reading the diff"), stopping here with no findings.
— branch: claude/docs-hygiene-audit-derivability-o12zbc

[claude]

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

---

Security Review

• Gather context (PR diff since last-reviewed head, custom instructions)
• Invoke /review:security-review and follow its procedure
• Post findings

Skip gate met — no security-relevant surface. This lane's relevance gate compares only the commits since the last-reviewed head (a9a18d4, reviewed 2026-08-15T17:30:16Z). The only change since then is commit 8bdbf14, "fix: update markdown-format test assertion for the reworded notice; name method-doc steps in discipline citations," which touches 11 files:

• Nine discipline skill SKILL.md files (do-your-research, pick-for-the-problem, point-dont-copy, reason-dont-recite, reuse-or-replace, script-the-deterministic-work, scrutinize-dont-coast, tighten-your-output, use-your-skills) — each gets a one-word/phrase annotation appended to an existing "method doc's step 2" or "step 3" citation (e.g. "step 2, self-audit", "step 3 (correct forward)"), so the citation stays valid if the method doc's steps are renumbered later. Pure prose, no behavior change.
• plugins/discipline/CHANGELOG.md — documents the above.
• plugins/markdown-format/hooks/markdown-format.test.sh:886 — updates a jq assertion's expected substring to match the notice text reworded in an earlier commit (0051b32) on this same PR. Test-only, no hook logic changed.

No code, scripts (beyond the one test-assertion string), or GitHub Actions workflow files carry logic changes. Nothing here touches auth/access-control, introduces an injection surface, handles secrets/tokens, or crosses a trust boundary. Consistent with this lane's prior passes on 60fc8e0, 5206b56, c66ce34, 0051b32, 566e5e1, aaca6ad, and a9a18d4.

Per the skip gate ("change has no security-relevant surface after reading the diff"), stopping here with no findings.
— branch: claude/docs-hygiene-audit-derivability-o12zbc

[claude]

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

---

Security Review

• Gather context (PR diff since last-reviewed head, custom instructions)
• Invoke /review:security-review and follow its procedure
• Post findings

Skip gate met — no security-relevant surface. This lane's relevance gate compares only the commits since the last-reviewed head (8bdbf14, reviewed 2026-08-15T17:39:39Z). The only change since then is commit 3eb0832, a merge of origin/main into this branch (bringing in unrelated already-merged main history, including the audit-encapsulation/audit-noise sweep from PR #2703).

Verified the actual PR diff is unaffected by this merge: git merge-base origin/main HEAD now resolves to origin/main's own tip, so gh pr diff / git diff origin/main...HEAD returns the same 45 files as before, and every file in that true PR diff is byte-identical to the pre-merge state except for four conflict-resolution reconciliations, all version/changelog bookkeeping only:

• plugins/docs-hygiene/.claude-plugin/plugin.json / CHANGELOG.md — version bumped 0.12.0 → 0.13.0 so this PR's changelog entry sits correctly above main's already-released 0.12.1 entry.
• plugins/machine-health/CHANGELOG.md — 0.10.3 → 0.10.4, same reconciliation.
• plugins/session-flow/CHANGELOG.md — 0.23.5 → 0.23.6, same reconciliation.

No code, scripts, or GitHub Actions workflow files carry any logic change from this commit. Nothing here touches auth/access-control, introduces an injection surface, handles secrets/tokens, or crosses a trust boundary — consistent with this lane's prior passes on 60fc8e0, 5206b56, c66ce34, 0051b32, 566e5e1, aaca6ad, a9a18d4, and 8bdbf14.

Per the skip gate ("change has no security-relevant surface after reading the diff"), stopping here with no findings.
— branch: claude/docs-hygiene-audit-derivability-o12zbc

[claude]

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

---

Security Review

• Gather context (PR diff since last-reviewed head, custom instructions)
• Invoke /review:security-review and follow its procedure
• Post findings

Skip gate met — no security-relevant surface. This lane's relevance gate compares only the commits since the last-reviewed head (3eb0832, reviewed 2026-08-15T18:37:45Z, "no findings"). The only change since then is commit 11aa0b8, a merge of origin/main into this branch (bringing in unrelated already-merged main history from PR #2700, "repo-wide interview fallback for /compress").

Verified the merge doesn't touch this PR's actual diff: git merge-base origin/main HEAD now resolves to origin/main's new tip (32216ca), and git diff origin/main...HEAD returns the same 45 files as before, byte-identical in content to what was reviewed at 3eb0832. The only content difference between 3eb0832 and 11aa0b8 (git diff 3eb0832 11aa0b8 --stat) is in files that are not part of this PR's diff — docs-hygiene/skills/compress/*, source-control/* — because those landed on main via #2700 and are excluded once the merge-base advances past them.

No code, scripts, or GitHub Actions workflow files carry any new logic. Nothing in the true PR diff touches auth/access-control, introduces an injection surface, handles secrets/tokens, or crosses a trust boundary — consistent with this lane's prior passes on 60fc8e0, 5206b56, c66ce34, 0051b32, 566e5e1, aaca6ad, a9a18d4, 8bdbf14, and 3eb0832.

Per the skip gate ("this head already has a successful security review that still applies"), stopping here with no findings.
— branch: claude/docs-hygiene-audit-derivability-o12zbc

[claude]

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

---

Security Review

• Gather context (PR diff since last-reviewed head, custom instructions)
• Invoke /review:security-review and follow its procedure
• Post findings

Skip gate met — no security-relevant surface. This lane's relevance gate compares only the commits since the last-reviewed head (11aa0b8, reviewed 2026-08-15T19:34:48Z, "no findings"). Since then, two merge commits landed (c1b2033 merging origin/main, then 156a718 merging origin/main again) — both bring in unrelated already-merged main history (PR #2720's guardrails security fix, PR #2715's mutation-testing findings-persistence feature, and other main-only doc/script changes).

Verified the actual PR diff is unaffected in substance: git diff origin/main...HEAD still returns the same 45 files reviewed previously, and diffing 11aa0b8..156a718 restricted to those 45 paths shows only two touched:

• plugins/guardrails/.claude-plugin/plugin.json — version 0.28.26 → 0.28.27.
• plugins/guardrails/CHANGELOG.md — the [0.28.26] header for this PR's own entry (staged-write named residual / harness-timeout fail-open note, reviewed and cleared on 0051b32/8bdbf14) is renumbered to [0.28.27], with main's PR fix(guardrails): classify destructive git subcommands as mutating #2720 security-fix entry now occupying [0.28.26] above it.

This is a pure merge-conflict renumbering: c1b2033's message states it explicitly ("Resolve guardrails CHANGELOG conflict: keep main's 0.28.26 SECURITY fix (#2720) and renumber this PR's residual-docs changes to 0.28.27"). The prose content of this PR's own changelog entry is byte-identical to what was already reviewed under the old 0.28.26 label — only the semver header moved to avoid colliding with the unrelated fix now merged into main at that version. No hook logic, script, or workflow file changed; block-hook-bypass.sh and block-noncanonical-commit.sh are untouched by this diff.

No code, scripts, or GitHub Actions workflow files carry new logic. Nothing in the true PR diff touches auth/access-control, introduces an injection surface, handles secrets/tokens, or crosses a trust boundary — consistent with this lane's prior passes on 60fc8e0, 5206b56, c66ce34, 0051b32, 566e5e1, aaca6ad, a9a18d4, 8bdbf14, 3eb0832, and 11aa0b8.

Per the skip gate ("this head already has a successful security review that still applies"), stopping here with no findings.
— branch: claude/docs-hygiene-audit-derivability-o12zbc