fix(docs-hygiene): close audit findings in audit-derivability, extract-ssot, write-for-agents and the changelog

[kyle-sexton]

Closes #4573

Refs #4142, #4713, #4700, #4701, #4027, #4657, #4661

Summary

Fixes the docs-hygiene findings from the audit of the unattended Cursor agent's 499 PRs. All changes are under plugins/docs-hygiene/; hooks/exec-bash.mjs is untouched. Version 0.23.14 becomes 0.23.15.

• audit-derivability (docs-hygiene: audit-derivability has no verdict for a routing-only agent doc, and keep-sample spot-tests have no defined outcome #4573): the rubric's routing-index row contradicted its own definition of "derivable"; the keep-sample and the git-log precondition were never delivered; the fresh-context spot-test could run on an agent that had already loaded the audited file. All five items in the issue are met on this branch, so it closes.
• extract-ssot (docs-hygiene:extract-ssot: exhaustive identify always dispatches the survey subagent, and step 8 always persists the roster #4713): identify.md Flags table and the Full form: line lacked --inline, and an all-refused survey had two names.
• write-for-agents (Apply the Claude Code 2.1.257 to 2.1.263 changelog decisions: 20 corrections, 1 native nomination, 7 adoptions, 3 declines #4027): the CLI append-flag facts were stated twice (table rows and a section) and carried a tracker tag.
• Plugin contract (docs-hygiene: agree the plugin's contract before it grows again #4142): the agent's decision is labelled proposed. No option is implemented.
• CHANGELOG: four released entries were copies of other entries or restated a change that shipped elsewhere.

Fix

• skills/audit-derivability/context/rubric.md: the routing-index row is a named exception to the derivable-from-primary-sources rule and never yields delete for a launch-loaded routing doc. New "Keep-sample protocol" section (size rule, diverged and converged outcomes, recording rule). git log runs before every delete and convert-to-pointer that recommends a change (convert-to-pointer (already satisfied) is exempt); a commit-recorded decision ships the verdict provisional as reverses a recorded decision. A launch-loaded audited file must be spot-tested by Explore or Plan, with a four-part verification record against the sub-agents doc.
• skills/audit-derivability/SKILL.md: matching sweep and spot-test text, sampled/overturned counts in the aggregate line and output schema.
• skills/audit-derivability/evals/: evals 14, 15, 16, all narration cases (routing-only root CLAUDE.md, converged keep-sample, deliberately created doc).
• skills/extract-ssot/: --inline row in identify.md, [--inline] in the Full form: line, "closed record" used in both files.
• skills/write-for-agents/reference/agent-doc-surfaces.md: three flag rows collapsed to one pointer row to "CLI prompt appends"; the section cites docs/specs/agent-doc-surfaces.md rows 26-28; the #4027 / 261-003 tag is removed.
• reference/plugin-contract.md, README.md: "Status: proposed" and pending the owner's decision; the Decision, Claim, Basis, As of and Recheck text is unchanged.
• CHANGELOG.md: bodies corrected in place, every heading kept. Edited entries: 0.23.8 (was a copy of 0.23.5), 0.23.9 (tracker item id dropped), 0.23.10 (now describes the section it shipped), 0.23.11 (was a copy of 0.23.10; no plugin file changed). New 0.23.15 entry names each.

Verification

• scripts/check-changelog-parity.sh --check --check-order: pass.
• scripts/validate-plugins.sh: all manifests and the catalog validated.
• plugins/skill-quality/scripts/check-evals-quality.sh on the audit-derivability evals.json: pass.
• **/*.test.sh under plugins/docs-hygiene: all pass.
• plugins/skill-quality/scripts/check-skill.sh plugins/docs-hygiene/skills: audit-derivability passes.
• CI: ci-status and both AI review lanes green on the merged head.

Related

Findings from .work/audit/REPORT.md: #4573 (3b partial delivery, 3c rubric.md:49), #4713 (findings 14-16), #4027 (findings 0 and 10), #4657 and #4661 (changelog findings 5, 8, 9), #4142 (3b and 3d decide fresh). #4700 and #4701 were already delivered in 0.23.4.

Owner decision pending on #4142: split, hold, or name-only listing for the file-name set; which budget rule governs; boundary 5 versus extract-ssot --yes and compress batch; ratify the charter; a shared audit entry point and a macOS runner. This PR does not choose.

🤖 Generated with Claude Code

https://claude.ai/code/session_01EugXnFddtpHcY5gTuyEirB

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-29T13:37:42.441878Z	e19ecee	Draft marked ready

ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[claude]

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

---

Security review complete

• Gather context (PR diff, changed files)
• Skip-gate check (security-relevant surface, instruction-surface deletions)
• Review changed files for vulnerabilities
• Post findings / no-findings summary

Scope reviewed: all 11 changed files (git diff origin/main...HEAD), all under plugins/docs-hygiene/: plugin manifest version bump, CHANGELOG.md, README.md, reference/plugin-contract.md, audit-derivability SKILL.md/rubric.md/evals + fixture, extract-ssot SKILL.md/identify.md, and write-for-agents/reference/agent-doc-surfaces.md.

No security issues found.

This PR is entirely prose/documentation and skill-body edits within a docs-hygiene plugin — no executable code, no input handling, no auth/access-control logic, no secrets, and no workflow-permission changes.

I applied the instruction-surface lens to the two edited skill bodies (audit-derivability/SKILL.md and context/rubric.md) since they're rules a Claude agent follows: every change there adds or tightens a guardrail rather than removing one —

• it now requires Explore/Plan (not just "e.g. Explore") for spot-testing launch-loaded files, since other subagent types already have CLAUDE.md/AGENTS.md pre-loaded and would self-grade (SKILL.md#L152-154, rubric.md#L266-272),
• it adds a mandatory git log check before every delete/convert-to-pointer verdict (rubric.md#L281-287),
• it adds a sampled spot-test for keep verdicts to bound false-keeps.

The write-for-agents/reference/agent-doc-surfaces.md table collapse (three CLI flag rows → one pointer row) doesn't drop any information — the version/combination/-p-only constraints remain fully stated in the "CLI prompt appends" section it now points to (agent-doc-surfaces.md#L478).

The new eval fixture (evals/fixtures/root-claude-md-routing.md) is inert test data used only by the eval harness, not a live loaded instruction file.

Per this lane's scope: GitHub Actions/workflow hardening is deferred to zizmor and out of scope here (no workflow files changed in this PR anyway).

[claude]

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

---

Claude finished the code review

• Gather context (PR diff, CLAUDE.md/AGENTS.md, REVIEW.md)
• Review changed files for correctness and maintainability
• Adversarially verify candidate findings
• Post inline comments for anchorable findings
• Post final summary

Summary

Reviewed all 11 changed files under plugins/docs-hygiene/ against origin/main per the /review:code-review criteria (correctness + CLAUDE.md/REVIEW.md alignment; security is out of scope here per REVIEW.md, and nothing security-relevant appears in this diff anyway).

No blocking or high-signal findings. No inline comments posted. Notable checks performed:

• Cross-referenced every place the rubric/SKILL.md restate the same facts (routing-index exception, git log precondition, keep-sample protocol, Explore/Plan spot-test requirement, output schema, aggregate line) — all consistent across SKILL.md and context/rubric.md.
• Verified the new ## Sources four-part verification record against the live docs page independently (not just author-claimed): fetched https://code.claude.com/docs/en/sub-agents.md and confirmed both the "Built-in subagents" and "What loads at startup" sections exist and say Explore/Plan skip the CLAUDE.md hierarchy and git-status snapshot, exactly as claimed — satisfies the skill-bodies-state-current-rules.md requirement.
• Verified docs/specs/agent-doc-surfaces.md rows 26-28 are in fact the three CLI append flags cited by the new pointer row/citation in write-for-agents/reference/agent-doc-surfaces.md — accurate.
• Confirmed the --inline flag documentation added to extract-ssot/actions/identify.md and SKILL.md's "Full form:" line is consistent with the flag's pre-existing behavior described elsewhere in SKILL.md's action-router row — this closes a real doc gap rather than introducing a new claim.
• Confirmed "closed record" terminology is now consistent across all three touched/adjacent surfaces (SKILL.md, identify.md, and the pre-existing extract-ssot/evals/evals.json, which already used that term).
• Spot-checked the new evals (14-16) and fixture against the rubric text they test; expectations line up with the rubric's stated behavior.
• CHANGELOG entries for 0.23.8/0.23.9/0.23.10/0.23.11 read consistently with the surrounding entries (0.23.5, 0.23.7) after the fix.

I did not independently re-run the verification commands listed in the PR description (check-changelog-parity.sh, validate-plugins.sh, check-skill.sh, etc.) — those are author-claimed and unverified by me; I only reviewed the resulting diffs directly.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e19eceea49

ℹ️ 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 finished @kyle-sexton's task in 1m 27s —— View job

---

Security review complete

• Gather context (PR diff, changed files)
• Invoke /review:security-review per custom instructions
• Skip-gate check (security-relevant surface, instruction-surface deletions)
• Review changed files for vulnerabilities
• Post findings / no-findings summary

Scope reviewed: all 10 changed files (gh pr diff 5296 against origin/main; local shallow clone had no merge-base for git diff), all under plugins/docs-hygiene/: .claude-plugin/plugin.json version bump, CHANGELOG.md, README.md, reference/plugin-contract.md, audit-derivability SKILL.md/rubric.md/evals/evals.json (+ new fixture referenced by the diff), extract-ssot SKILL.md/identify.md, and write-for-agents/reference/agent-doc-surfaces.md.

No security issues found.

This is a prose/documentation-only change set in a docs-hygiene plugin — no executable code, no input handling, no auth/access-control logic, no secrets, no CI workflow files touched.

Applied the instruction-surface lens (per docs/conventions/instruction-exception-register/README.md) to the two edited skill bodies, since they're rules a Claude agent follows:

• audit-derivability/SKILL.md and context/rubric.md — every behavioral change tightens a guardrail, none removes one: spot-tests of a launch-loaded audited file now must use Explore/Plan (was "e.g. Explore") since every other subagent type pre-loads CLAUDE.md/AGENTS.md and would self-grade (SKILL.md#L154, rubric.md#L266-273); a mandatory git log check now runs before every delete/convert-to-pointer verdict, not just empty files (rubric.md#L281-287); a new keep-sample spot-test bounds false-keeps. The pre-existing "Read-only with respect to the repository — no Edit/Write, no mutating Bash" line is untouched by this diff.
• reference/plugin-contract.md/README.md downgrade the charter from "recorded decision" to "Status: proposed … binds nothing until ratified" (plugin-contract.md#L3-8). Checked against the instruction-exception register's six Gate 0 classes (irreversible-action, secret-handling, data-integrity, external-publication, legal-compliance, agent-authority): this is a plugin-architecture/scope charter, not a control on any of those consequence classes, so it isn't a protected-class deletion.
• write-for-agents/reference/agent-doc-surfaces.md collapses three CLI-flag table rows into one pointer row — no fact is dropped; the version/-p-only/combination constraints remain fully stated in the "CLI prompt appends" section the new row cites (agent-doc-surfaces.md#L38).
• extract-ssot terminology changes (status: closed roster → "closed record") and the new --inline flag documentation are wording/completeness fixes with no behavior change to the resume-gate logic.
• The new eval fixture (evals/fixtures/root-claude-md-routing.md) is inert test data consumed only by the eval harness, never a live-loaded instruction file, so it carries no injection surface.

Per this lane's scope: GitHub Actions/workflow hardening is deferred to zizmor and out of scope here (no workflow files changed in this PR).
· Branch: fix/audit-docs-hygiene

[claude]

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

---

Code review complete

• Gather context (PR diff, CLAUDE.md/AGENTS.md, REVIEW.md)
• Review changed files for correctness and maintainability
• Adversarially verify candidate findings
• Post inline comments for anchorable findings
• Post final summary

Summary

Reviewed all 10 files changed vs origin/main (gh pr diff 5296) under the /review:code-review criteria (correctness + CLAUDE.md/repo conventions; security is out of scope for this lane and nothing security-relevant appears in this diff anyway).

1 finding posted inline — a genuine self-contradiction the PR's new text introduces in audit-derivability's rubric:

• rubric.md:231 (worked example, Case 2 — a routing-only CLAUDE.md with a deliberate-creation commit) says the verdict ships provisional, reverses a recorded decision. That clashes with the unconditional routing-index exception a few lines up (rubric.md:56-60, mirrored in SKILL.md:74), which says a launch-loaded routing-only doc's verdict is "never delete. It stays convert-to-pointer (already satisfied), not actionable" — with no carve-out for the new git-log/deliberate-state check. Both readings are supported by different parts of the same document, and no eval exercises this exact combination (eval 14 deliberately picks a routing doc with "only ordinary edits, no commit that records a decision," sidestepping it). Full detail in the inline comment.

Also verified (no issues):

• The two Codex findings on the prior head (e19eceea49) about eval 14 — a fixture referencing nonexistent anchors, and asserting a fabricated "no recorded decision" git history against a tracked fixture whose own commit contradicts that — are resolved by the latest commit (08f45e1): the fixture file is deleted, and eval 14 is now narration: true with files: [], stating the scenario (text, pointer targets, git-log outcome) directly in the prompt instead of pointing at a real tracked file. This matches the pattern already used by evals 3, 4, 15, and 16.
• Cross-checked the new --inline flag docs in extract-ssot/actions/identify.md (flags table) against step 2 of the exhaustive-mode steps — consistent.
• Cross-checked the write-for-agents collapsed CLI-flag table row against docs/specs/agent-doc-surfaces.md rows 26-28 — the citation is accurate, and the #cli-prompt-appends anchor it points to exists.
• Spot-checked CHANGELOG 0.23.8/0.23.9/0.23.10/0.23.11/0.23.15 entries against the diffs they describe — consistent with what actually shipped in each version.
• reference/plugin-contract.md/README.md "Status: proposed" wording is consistent between the two files and leaves the Decision/Claim/Basis text unchanged as described.

Did not independently re-run the PR description's listed verification commands (check-changelog-parity.sh, validate-plugins.sh, check-skill.sh, etc.) — those are author-claimed; I reviewed the resulting diffs directly instead.

[claude]

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

---

Code review complete

• Gather context (PR diff, CLAUDE.md/AGENTS.md, REVIEW.md)
• Review changed files for correctness and maintainability
• Adversarially verify candidate findings
• Post inline comments for anchorable findings
• Post final summary

Summary

Reviewed the full PR diff (gh pr diff 5296, base origin/main) at head 714a5e1, focused on correctness and consistency with CLAUDE.md/repo conventions (security is out of scope for this lane).

No blocking findings. No inline comments posted.

This head's only change since the prior review round is commit
714a5e1,
which resolves the contradiction the earlier claude review flagged between the routing-index
exception and the new deliberate-state precondition. Verified the fix is complete and consistent
across every surface that restates the rule:

• SKILL.md:154 and rubric.md:195-196 now both scope the git log precondition to verdicts
  "that recommend a change," with convert-to-pointer (already satisfied) explicitly exempted in
  matching language in both files.
• rubric.md:59-61 (Factor 1 routing row) cross-references the exemption explicitly: "The
  deliberate-state precondition below does not change this: that verdict recommends no change, so
  it reverses no recorded decision."
• The worked-examples table's Case 2 (rubric.md:233) was swapped from the ambiguous
  routing-only-CLAUDE.md scenario to an unambiguous docs/deploy-notes.md example, so the table no
  longer states two different verdicts for the same fact pattern.
• Eval 14 (evals.json) dropped its now-inapplicable "consults git log" expectation and its
  prompt/expected_output were updated to state the exemption directly — matches the rubric's
  current rule, and no eval asserts the old contradictory behavior.

No new issues introduced by this fix. Also re-checked the previously-flagged Codex finding on the
eval-14 fixture (nonexistent pointer targets / fabricated git history): still resolved as of the
prior round (fixture deleted, eval runs as narration with files: []), unaffected by this commit.

Spot-checked the remaining unchanged files from earlier rounds (extract-ssot's --inline flag
docs and "closed record" terminology, write-for-agents' collapsed CLI-flag table row, the
CHANGELOG/plugin-contract "proposed" status wording) for regressions from this push — none found;
they read the same as when previously reviewed.

Did not independently re-run the PR description's listed verification commands
(check-changelog-parity.sh, validate-plugins.sh, go-format.test.sh, etc.) — those are
author-claimed; I reviewed the resulting diffs directly.
· Branch: fix/audit-docs-hygiene

[claude]

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

---

Security review complete

• Gather context (PR diff, changed files)
• Invoke /review:security-review per custom instructions
• Skip-gate check (security-relevant surface, instruction-surface deletions)
• Review changed files for vulnerabilities
• Post findings / no-findings summary

Scope reviewed: all 10 files changed vs origin/main (gh pr diff 5296, shallow checkout had no merge-base for git diff), at head 714a5e1: plugin.json version bump, CHANGELOG.md, README.md, reference/plugin-contract.md, audit-derivability SKILL.md/context/rubric.md/evals/evals.json, extract-ssot SKILL.md/actions/identify.md, write-for-agents/reference/agent-doc-surfaces.md.

No security issues found.

This is a prose/documentation-only change set inside a docs-hygiene plugin — no executable code, no input handling, no auth/access-control logic, no secrets, no CI workflow files touched.

Applied the instruction-surface lens (per docs/conventions/instruction-exception-register/README.md) to the two edited skill bodies, since they are rules a Claude agent follows:

• audit-derivability/SKILL.md and context/rubric.md — every behavioral change tightens a guardrail, none removes one: a spot-test of a launch-loaded audited file now must use Explore/Plan (was "e.g. Explore"), since every other subagent type pre-loads CLAUDE.md/AGENTS.md and would self-grade; the git log deliberate-state check now runs before every delete/convert-to-pointer that recommends a change, not only empty files; a new keep-sample protocol bounds false-keeps. The pre-existing "Read-only with respect to the repository — no Edit/Write, no mutating Bash" line (SKILL.md#L146) is untouched by this diff.
• reference/plugin-contract.md/README.md downgrade the charter from "recorded decision" to "Status: proposed … binds nothing until ratified." Checked against the register's six Gate 0 classes (irreversible-action, secret-handling, data-integrity, external-publication, legal-compliance, agent-authority): this is a plugin-architecture/scope charter, not a control on any of those consequence classes, so it is not a protected-class deletion.
• write-for-agents/reference/agent-doc-surfaces.md collapses three CLI-flag table rows into one pointer row — no fact is dropped; the version/-p-only/combination constraints remain fully stated in the "CLI prompt appends" section the new row cites.
• extract-ssot terminology changes (status: closed roster → "closed record") and the new --inline flag documentation are wording/completeness fixes with no behavior change to the resume-gate logic.

Note: this latest commit (714a5e1) also adds an explicit exemption — convert-to-pointer (already satisfied) is excluded from the new git-log precondition — which resolves the rubric self-contradiction a prior code-review pass flagged on 08f45e1. That was a correctness finding, not a security one, and is out of scope for this lane.

Per this lane's scope: GitHub Actions/workflow hardening is deferred to zizmor and out of scope here (no workflow files changed in this PR).
· Branch: fix/audit-docs-hygiene