docs(encapsulation): remediate audit-encapsulation sweep findings + add no-scope confirmation to the skill

[kyle-sexton]

Closes #2701
Closes #2702

Summary

A repo-wide /docs-hygiene:audit-encapsulation run classified 85 candidate cites (fresh-context adjudication on the 8 borderline ones) and confirmed 16 violations. This PR remediates all 16: the 9 unblocked violations plus one same-shape prose cite the detector's grep cannot see, and the 7 formerly facade-blocked hits, resolved by building the scripts/ entry surfaces #2701/#2702 called for. It also gives the skill the no-scope confirmation fallback + sweep action so a bare invocation confirms scope before running repo-wide.

Fix

Remediation (commit 1):

• Path B re-points: docs/conventions/loop-lane (3 cites incl. two SKILL.md# heading anchors), docs/conventions/pr-body-convention, machine-health's Windows check catalog, and code-tidying's tidy SKILL.md (§2.4.1 parenthetical + a §2.6 prose cite) now reference owning skills by slash invocation instead of private paths/anchors.
• Path A promotion: the <state-key> scheme's canonical definition moved to docs/conventions/plugin-data-report-keying/ after all six extract-ssot verify gates passed; audit-pass's reference §3 now defers to it (no dual-maintenance).
• Path A refused honestly for the untrusted-content fence (Rule of Three: only two consumers): work-items/reference/item-content-trust.md now states its constraint self-contained, with the babysit-prs alignment named in prose per the contract's intentional-duplication technique — the main-pinned raw-GitHub deep link is gone.

Skill update (commit 2): audit-encapsulation gains the no-scope confirmation — a bare invocation with no inherited working set asks ONE confirmation presenting prescribed defaults (repo-wide scope, detect-only, fan-out off; 2–3 concurrent workers when fan-out is opted into and no rate-limit telemetry is readable, resolving pacing from rate-limit-guard's reader contract when it is); new sweep action skips the confirmation; eval cases 7–8 pin both behaviors.

Verifier fixes (commits 3–6): changelog-parity repairs, the Codex-flagged cross-plugin link removed from run-state-and-resumability.md, and six fresh-context-verifier findings applied — including re-syncing both lib/state-key.sh headers (claude-memory 0.9.1) so attribution follows the promoted convention. The four sites that cited §3 by relative path are all re-pointed; only legal intra-skill self-cites remain.

Facades (commit 7 — closes #2701, #2702): conform rather than carve out. knowledge (youtube-digest + course-digest scripts/run-tests.sh facades over their private extraction/ packages), ai-briefing 0.7.2 (generate facade over output/build/), machine-health (audit scripts/run-tests.ps1 wrapper over the private Pester runner). The three ci.yml npm lanes and CLOUD-SESSIONS.md invoke the facades; the remaining cache-dependency-path lines are KIND-2 data references, commented as such. All TODO(audit-encapsulation) markers removed; the authoring-repo CI carve-out question is moot.

Post-merge reconciliation (final commits): main released its own docs-hygiene 0.12.0 and knowledge 0.12.2 mid-review, which both conflicted and silently suppressed the pull_request workflows (no test-merge commit); the merge from main renumbers this PR's releases to docs-hygiene 0.12.1 and knowledge 0.12.3, takes main's newer plugin description, and carves exactly run-tests.sh out of validate-plugin-contracts.mjs's ai-briefing scripts tombstone (the collector-token content scan still covers the carved-out file). Plus a grammar fix and a conflict-marker cleanup.

Verification

• detect.sh regression suite: all 36 checks pass; allowed-tools-pairing.test.sh passes; state-key.test.sh all 23 checks pass; validate-plugin-contracts.mjs, catalog, and cheatsheet checks pass post-carve-out.
• shellcheck + shfmt clean on the three bash facades; facade usage error path exercised.
• markdownlint-cli2 clean on every touched markdown file; actionlint clean on ci.yml; plugin.json validates; evals.json parses with sequential ids 1–8; changelog parity --check-bump green for all eight bumped plugins (ai-briefing 0.7.2, claude-config 0.38.2, claude-memory 0.9.1, code-tidying 0.10.2, docs-hygiene 0.12.1, knowledge 0.12.3, machine-health 0.10.3, work-items 0.35.23).
• Post-remediation detect re-run: contract-adjudicated illegal count is 0 (raw detector count 78 → 74; the residue is detector over-flagging of adjudicated-legal cites — tracked with reproductions in docs-hygiene/audit-encapsulation: detect.sh cannot serve as the gate the contract invites — adjudication divergence, no terminal state for blocked hits, filter/scope gaps (plugin-quality audit) #2728).
• A fresh-context verification pass over the full diff ran twice (after commit 2 and after commit 6); all findings applied.

Related

Every thread this work opened is either fixed in this PR or tracked: #2697 (cloud rate-limit telemetry gap the skill's fixed concurrency default works around), #2716 (detector misses relative-path cites), #2728 (plugin-quality audit of the skill itself: detector/adjudication divergence, no terminal state for acknowledged hits, filter/scope gaps), #2729 (audit-pass's non-git refusal narrative cites a state-key limitation the shared executable no longer has — surfaced by this PR's promotion).

🤖 Generated with Claude Code

https://claude.ai/code/session_01FDxmoBKkwCsHPgsu93mw2m

---

Generated by Claude Code

[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.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c14a4e220d

ℹ️ 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 1s —— View job

---

I'll analyze this and get back to you.

[claude]

Claude encountered an error after 1s —— View job

---

I'll analyze this and get back to you.

[claude]

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

---

Security Review — /review:security-review

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

Skip gate: change has no security-relevant surface.

This PR is a documentation/encapsulation-hygiene sweep: markdown cross-references reworded to cite skills by slash-invocation instead of private file paths, one convention doc promoted as canonical source for the <state-key> scheme, plugin version bumps + CHANGELOG entries, and TODO(audit-encapsulation) comment markers added to .github/workflows/ci.yml and a couple of markdown/shell files. I reviewed the full diff (gh pr diff 2703, 29 files, +185/-76):

• .github/workflows/ci.yml — only # TODO(...) comment lines added ahead of existing cache-path steps; no trigger, permissions, secrets, or step logic changed.
• plugins/{claude-config,claude-memory}/lib/state-key.sh — only the header comment block changed (attribution of where the scheme is canonically defined); the executable logic, including the existing path-traversal defense that hashes any non-plain-segment repo identity before it becomes a directory component, is untouched.
• plugins/work-items/reference/item-content-trust.md — the untrusted-content fence's wording/behavior is unchanged; this drops an external main-pinned raw-GitHub link in favor of stating the fence self-contained in-doc, which if anything reduces trust-boundary risk (no fetch of remote content to resolve the fence definition).
• All other changes are markdown link/prose rewrites, plugin.json version bumps, and CHANGELOG.md additions.

No authorization/access-control logic, injection surfaces, credential handling, or GitHub Actions trigger/permission changes are present in this diff. Per the skip gate in /review:security-review, no findings are reported.

(Note: the one substantive review thread on this PR — Codex's flag about the run-state-and-resumability.md cross-plugin link breaking on installed copies — is an encapsulation/maintainability concern, not a security one, and the author's reply indicates it was already addressed in 22c4db2.)

[claude]

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

---

Claude's review — /review:code-review

• Gather context (PR diff, origin/main...HEAD, changed files)
• Read the touched files at HEAD (not just diff hunks) for prose/logic coherence
• Verify the Codex-flagged installed-plugin link-resolution issue was actually fixed
• Verify JSON/YAML structural validity of touched non-prose files (evals.json, ci.yml comment placement)
• Cross-check the item-content-trust.md reused fence against babysit-prs/reference/orchestration.md's actual text
• Post summary

Scope

This PR is almost entirely documentation/prose (re-pointing citations that reached into other skills' private surfaces, two plugin.json/CHANGELOG.md version bumps per touched plugin, and comment-only edits to lib/state-key.sh and ci.yml). The only behavior-affecting change is plugins/docs-hygiene/skills/audit-encapsulation/SKILL.md's new no-scope confirmation + sweep action, which is prompt-level routing logic (markdown), not code.

Findings

No blocking correctness or maintainability issues found.

Specifically checked and confirmed clean:

• The Codex review comment's finding is resolved. run-state-and-resumability.md no longer links across the plugin/repo boundary — it names the plugin-data-report-keying convention in prose and keeps the one-line grammar as a marked intentional duplicate, with the in-plugin lib/state-key.sh as the operational pointer. docs/MIGRATION-PLAYBOOK.md:611 ("installed plugins are copied to ~/.claude/plugins/cache... any reference to files [outside]...") confirms the reasoning for why a repo-level docs/ link would have been unresolvable from an installed copy — the fix is sound.
• Promoted content matches at both ends. docs/conventions/plugin-data-report-keying/README.md's repo-identity/worktree-discriminator derivation is identical in substance to what audit-pass's reference used to state inline, and to lib/state-key.sh's header comment (comment-only diff there — the executable logic is untouched).
• The item-content-trust.md fence is reused verbatim, as claimed. The BEGIN QUOTED PR DATA / END QUOTED PR DATA markers now embedded directly in item-content-trust.md match plugins/source-control/skills/babysit-prs/reference/orchestration.md's "Worker Prompt Template" section byte-for-byte — no drift introduced by dropping the fragile main-pinned raw-GitHub fetch.
• evals.json is valid JSON with sequential ids 1–8; cases 7–8 do pin the new confirm/sweep behaviors described in the SKILL.md and CHANGELOG.
• ci.yml's three new TODO(audit-encapsulation) comment lines sit at the correct mapping indentation inside each actions/setup-node with: block — no YAML structure risk.
• Spot-checked several of the re-pointed citations (loop-lane/README.md, audit-instructions/conflict-criteria.md, check-catalog.md) for dangling pronouns/broken sentence flow after the link removal — all read coherently, no information silently lost.

One thing outside this review's scope but worth noting for the author: the PR description's TODO-marker count ("7 facade-blocked hits") doesn't obviously reconcile 1:1 with the number of TODO(audit-encapsulation) comments actually added (5 comment blocks, some covering multiple cited lines) — likely just a raw-hit-vs-comment-block counting nuance in the PR narrative, not a code defect, so not filed as a finding.

[github-actions]

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

[claude]

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

---

Security Review — /review:security-review

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

Skip gate: change has no security-relevant surface.

Reviewed the full current PR diff (git diff origin/main...HEAD, 37 files, +293/-100 at head 813420e), including the two commits pushed since the prior security review of this branch (head 90e22fc): ea6fedb (facade scripts + CI wiring, closes #2701/#2702) and the subsequent merge/grammar/conflict-marker-cleanup commits (61360b1, 8ed5b6f, 813420e).

• New facade scripts (plugins/ai-briefing/skills/generate/scripts/run-tests.sh, plugins/knowledge/skills/{youtube-digest,course-digest}/scripts/run-tests.sh, plugins/machine-health/skills/audit/scripts/run-tests.ps1) — all use fixed case/positional-arg dispatch (install|build|test|all) or direct passthrough to a private test runner (Invoke-MachineHealthTests.ps1 @args). No eval, no unsanitized interpolation into a shell/command string, no new untrusted-input path.
• .github/workflows/ci.yml — the three touched npm steps now call bash .../scripts/run-tests.sh <verb> instead of inline npm ci/npm test with working-directory:. No trigger, permissions:, secrets, or job-level changes; still gated by the existing docs_only scope check.
• plugins/{claude-config,claude-memory}/lib/state-key.sh — comment-only header changes (attribution of the canonical <state-key> scheme definition); executable logic, including the existing path-traversal defense, is untouched.
• plugins/work-items/reference/item-content-trust.md — prose-only strengthening of the untrusted-content fence documentation (drops an external main-pinned fetch in favor of self-contained wording); the fence markers and never-follow instruction are unchanged.
• plugins/docs-hygiene/skills/audit-encapsulation/SKILL.md — the new no-scope confirmation + sweep action is prompt-level routing logic (markdown), not executable code; no injection surface.
• All remaining changes are plugin.json version bumps, CHANGELOG.md entries, and cross-reference prose rewrites (docs/CLOUD-SESSIONS.md, docs/conventions/*, machine-health check catalog, claude-config skill docs).

No authorization/access-control logic, injection surfaces, credential handling, or GitHub Actions trigger/permission changes are present anywhere in this diff, including the commits added since the last review. Per the skip gate in /review:security-review, no findings are reported.
— branch claude/docs-hygiene-audit-encapsulation-h8oh20

[claude]

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

---

Claude's review — /review:code-review

• Gather context (PR diff, changed files, prior review coverage)
• Identify what's new since the last code-review pass on this lane
• Review the new commits against the skip-gate / high-signal bar
• Post findings

Scope of this pass

This lane already posted a full review on commit 90e22fc (11:09 UTC). Three commits landed after that: ea6fedb (facades, closes #2701/#2702), 61360b1 (grammar fix), and the merge + conflict-marker cleanup (8ed5b6f, 813420e) that brings this branch even with origin/main. This pass reviews only what's new in that range — the remediation/prose content from the earlier commits was already covered and is unchanged since.

New content reviewed:

• .github/workflows/ci.yml — three npm lanes re-wired from raw npm ci/working-directory to the new scripts/run-tests.sh <verb> facades; TODO(audit-encapsulation) comments replaced with KIND-2 data-reference notes.
• New facade scripts: plugins/ai-briefing/skills/generate/scripts/run-tests.sh, plugins/knowledge/skills/{course,youtube}-digest/scripts/run-tests.sh, plugins/machine-health/skills/audit/scripts/run-tests.ps1.
• docs/CLOUD-SESSIONS.md re-pointed to the facade invocations.
• plugins/knowledge/CHANGELOG.md — stray >>>>>>> origin/main conflict marker left by the merge, removed in 813420e.

Findings

No blocking correctness or maintainability issues.

Verified:

• Each facade's case verbs (install/build/test/all) match exactly what ci.yml now invokes per step — no verb mismatch, no now-orphaned working-directory: clause (the scripts cd internally, so removing it was correct).
• All three facades' target paths resolve (extraction/package.json, output/build/package.json, tests/Invoke-MachineHealthTests.ps1 all present at HEAD) and the two new run-tests.sh scripts carry the executable bit (100755) needed for bash …/run-tests.sh to work the same way a checked-out script normally would (moot for bash, but consistent with the pwsh -File and README's direct-invocation examples).
• plugins/machine-health/README.md's test-invocation snippet matches the new run-tests.ps1 facade path.
• No other leftover <<<<<<</=======/>>>>>>> conflict markers anywhere under plugins/**/CHANGELOG.md or elsewhere in the diff — 813420e caught the only one.
• Version/changelog consistency holds post-merge: knowledge is now 0.12.3 (plugin.json matches CHANGELOG heading; the PR description's "0.12.2" is stale text from before the merge renumbered it alongside the already-merged map-corpus 0.12.2 entry — a description nit, not a code defect) — same pattern for docs-hygiene (0.12.1 vs. the description's 0.12.0).
• Remediation/prose files from the earlier commits (loop-lane, pr-body-convention, plugin-data-report-keying, audit-instructions, audit-pass's run-state-and-resumability.md, item-content-trust.md, state-key.sh headers, check-catalog.md, code-tidying's tidy SKILL.md) are byte-identical to what was already reviewed on 90e22fc — confirmed via git diff 90e22fc..HEAD scoped to each path, so not re-relitigated here.

Nothing to flag as an inline comment — no changed line in the new range has a defect.
· branch claude/docs-hygiene-audit-encapsulation-h8oh20

[claude]

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

---

Security Review — /review:security-review

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

Skip gate: change has no security-relevant surface.

Reviewed the full current PR diff (git diff origin/main...HEAD, 38 files, +313/-109 at head a6815c8). The only commit added since the last full security review of this branch (head 813420e, posted above) is a6815c8, which touches a single file: scripts/validate-plugin-contracts.mjs (+20/-9).

That change is a CI contract-validation script edit only — it refines the ai-briefing legacy-scripts tombstone check from "ban the whole skills/generate/scripts directory" to "ban everything in it except a named run-tests.sh carve-out," and keeps the seed/ ban unchanged. It:

• Reads the local filesystem only (filesUnder/join/relative), no exec/eval/subprocess, no network I/O.
• Operates over paths already scoped to the repo's own plugins/ tree — no user-controlled or externally-sourced input.
• Doesn't touch permissions, secrets, workflow triggers, or authorization logic.
• Is defensive in intent: it narrows what's allowed to reappear under a previously-tombstoned path, and the PR description confirms the existing automatedXTokens content scan still covers the carved-out file, so a banned collector can't sneak back in under the allowed filename.

All other files in the diff (facade scripts, ci.yml, state-key.sh headers, item-content-trust.md, the audit-encapsulation SKILL.md confirmation logic, and the various markdown/CHANGELOG/plugin.json changes) were already reviewed and found to have no security-relevant surface in the prior pass on this branch — no changes to any of those files have occurred since.

No authorization/access-control logic, injection surfaces, credential handling, or GitHub Actions trigger/permission changes are present anywhere in this diff, including the commit added since the last review. Per the skip gate in /review:security-review, no findings are reported.
— branch claude/docs-hygiene-audit-encapsulation-h8oh20

[claude]

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

---

Claude's review — /review:code-review

• Gather context (PR diff, origin/main...HEAD, changed files)
• Invoke /review:code-review per custom instructions
• Post findings

Scope

Reviewed the full current diff (git diff origin/main...HEAD, 38 files, +313/-109 at head a6815c8), focused on the commits added since the prior code-review-lane pass on this PR (ea6fedb facades + CI wiring, 61360b1 grammar fix, 8ed5b6f merge, 813420e conflict-marker cleanup, a6815c8 contracts carve-out), plus a spot re-check of the earlier commits' doc re-points.

Findings

No blocking correctness or maintainability issues found. No inline comments filed.

Specifically checked and confirmed clean on this pass:

• scripts/validate-plugin-contracts.mjs (lines 136–160) — the tombstone carve-out for ai-briefing/skills/generate/scripts/ correctly uses relative() (already imported) to exempt only run-tests.sh from the legacy-collector check, and the file still passes through the separate automatedXTokens content scan (matches \.sh$), so a collector can't smuggle itself back in under the allowed filename. The seed/ tombstone check is preserved unchanged.
• Facade scripts are consistent with their CI callers. ai-briefing/skills/generate/scripts/run-tests.sh's case statement (install|test|all) matches the two CI steps that call it; youtube-digest/course-digest's run-tests.sh (install|build|test|all) matches their three-step (install/typecheck/test) CI lanes. No verb CI calls is missing from a script's case, and no case branch is dead.
• plugins/claude-config/lib/state-key.sh / plugins/claude-memory/lib/state-key.sh — both headers now carry the full repo-identity/worktree-discriminator derivation (not just the one-line grammar), which is what run-state-and-resumability.md's new §3 text claims ("whose header states the full derivation"); the claim checks out against the actual file content, and the two plugin copies stay byte-identical to each other.
• No dangling links to the demoted content. Grepped for remaining run-state-and-resumability.md ... §3 and create.md ... §2.4 references outside audit-pass/pull-request's own files — the only hits left are legal intra-skill self-cites (a skill's own docs citing its own section), matching the PR's claim that "only legal intra-skill self-cites remain."
• No leftover git conflict markers anywhere in plugins/, docs/, scripts/, .github/ (checked after the 813420e cleanup commit).
• evals.json is still valid JSON with sequential ids 1–8 after the merge.

One pre-existing, non-blocking observation for the author (not filed as a finding): the PR description's version numbers (docs-hygiene 0.12.0, knowledge 0.12.2) are stale relative to the actual current bumps (0.12.1, 0.12.3) — a mismatch introduced by the later commits doing a second bump, not a code defect.
— branch claude/docs-hygiene-audit-encapsulation-h8oh20