diff --git a/docs/conventions/commit-convention/README.md b/docs/conventions/commit-convention/README.md index 677a27450..bf76d67c6 100644 --- a/docs/conventions/commit-convention/README.md +++ b/docs/conventions/commit-convention/README.md @@ -101,7 +101,7 @@ Contract points: fail-closed broken-file contract applies; a key it omits still falls back per key to the markdown H2. **Both V1 reasons for shipping no well-known search are engaged, not overridden by fiat** (#163434 - is the demanding consumer; design: `docs/topics/commit-convention-well-known-path/`, PR #1185). V1 recorded + is the demanding consumer; design recorded under PR #1185 — see Sources). V1 recorded (i) "no consumer demanding it yet" — now void. And (ii) a search list "adds probe order and shadowing questions" and "keeps every path choice in the consuming repo's hands." V2 answers (ii) narrowly: it is a single fixed default path, **not** a search list, so probe order is the bounded @@ -170,3 +170,7 @@ purposes without it. Naming coincidence recorded per the seam rules: the convention file is `.claude/source-control.md` after the concern (delivery workflow), not the plugin. The plugin-name collision is incidental; the file is not renamed. + +## Sources + +- Design topic for the well-known-path decision: [`docs/topics/commit-convention-well-known-path/`](../../topics/commit-convention-well-known-path/), carrying PR #1185. diff --git a/plugins/docs-hygiene/.claude-plugin/plugin.json b/plugins/docs-hygiene/.claude-plugin/plugin.json index b3e9246c7..699eae384 100644 --- a/plugins/docs-hygiene/.claude-plugin/plugin.json +++ b/plugins/docs-hygiene/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "docs-hygiene", - "version": "0.14.6", + "version": "0.14.7", "description": "Documentation-hygiene toolkit: compress (flavor-trim markdown with a semantic-diff safety net), audit-noise (classify markdown noise), extract-ssot (deduplicate repeated content into a single source of truth), audit-encapsulation (detect citations into skill-private surfaces), rename-references (sweep stale references after renames), and audit-derivability (classify whether a whole document earns its existence \u2014 could a fresh agent re-derive it from the code?).", "author": { "name": "Melodic Software", diff --git a/plugins/docs-hygiene/CHANGELOG.md b/plugins/docs-hygiene/CHANGELOG.md index 824d2c86b..19da5eca3 100644 --- a/plugins/docs-hygiene/CHANGELOG.md +++ b/plugins/docs-hygiene/CHANGELOG.md @@ -1,5 +1,16 @@ # Changelog — docs-hygiene plugin +## [0.14.7] + +### Added + +- **audit-derivability route follow-ups:** in-tree status board + (`context/derivability-route-followups.md`) for the 174 route-to-sibling + annotations from the 2026-08-15 repo-wide sweep — noise routes closed after + re-scan + one Sources relocation; extract-ssot routes triaged + (synced-cluster / functional-scaffold / changelog-parity / pending) without + opening new issues (#2735). + ## [0.14.6] ### Added diff --git a/plugins/docs-hygiene/context/derivability-route-followups.md b/plugins/docs-hygiene/context/derivability-route-followups.md new file mode 100644 index 000000000..b3590233f --- /dev/null +++ b/plugins/docs-hygiene/context/derivability-route-followups.md @@ -0,0 +1,122 @@ +# Derivability route-to-sibling follow-ups (2026-08-15 sweep) + +Durable tracking for the 174 route-to-sibling annotations from the repo-wide +`/docs-hygiene:audit-derivability` sweep (issue #2735 / session ledger +`derivability-ledger.json`, ephemeral). This file is the in-tree status board — +no new GitHub issues are opened from it. + +## Batch record + +| Pass | Date | Scope | Outcome | +|---|---|---|---| +| audit-noise re-scan | 2026-08-16 | all 38 noise-routed paths | 32 files scanner-clean under detect 0.14.5+ exemptions; 6 `CHANGELOG.md` basename-exempt; 1 Tier-2 ghost-ref remediated (commit-convention README → Sources) | +| extract-ssot triage | 2026-08-16 | all 136 ssot-routed paths | dispositions below; exact byte-identical `reference/artifact-protocol.md` cluster already registered in `scripts/cross-plugin-source-registry.txt` (keep-as-synced-copies, not pointer-extract) | +| false-keep sampling | deferred | 1089 `keep-owns-facts` from the original sweep | original session ledger ephemeral; future sweeps sample keeps per the post-#2695 contract — do not invent a one-off sample without the ledger | + +## Route: audit-noise (38) + +Disposition after the 2026-08-16 pass: **closed for scanner follow-up**. Line-level +noise the original sweep saw was largely false-positive under the pre-exemption +scanner; remaining real cite relocated. + +| Path | Status | +|---|---| +| `CLAUDE.md` | clean | +| `docs/conventions/commit-convention/README.md` | remediated — design-topic ghost-ref moved to `## Sources` | +| `docs/conventions/config-cascade/README.md` | clean | +| `docs/conventions/ecosystem-commands/README.md` | clean | +| `docs/conventions/hook-observability/README.md` | clean | +| `docs/conventions/hook-telemetry/README.md` | clean | +| `docs/topics/context-engineering-claude-5/design/skill-inventory.md` | clean | +| `plugins/ai-briefing/skills/generate/references/build-pipeline.md` | clean | +| `plugins/ai-briefing/skills/generate/references/slide-generation.md` | clean | +| `plugins/architecture/CHANGELOG.md` | basename-exempt | +| `plugins/claude-ops/skills/known-issues/context/registry-schema.md` | clean (pointer-converted in #2695 — re-verified present) | +| `plugins/disk-hygiene/CHANGELOG.md` | basename-exempt | +| `plugins/domain-driven-design/README.md` | clean | +| `plugins/dometrain/README.md` | clean | +| `plugins/education/CHANGELOG.md` | basename-exempt | +| `plugins/education/README.md` | clean | +| `plugins/eol-normalizer/CHANGELOG.md` | basename-exempt | +| `plugins/eol-normalizer/README.md` | clean | +| `plugins/evals/CHANGELOG.md` | basename-exempt | +| `plugins/firecrawl/CHANGELOG.md` | basename-exempt | +| `plugins/knowledge/skills/youtube-digest/templates/sources.md` | clean | +| `plugins/knowledge/vendor/repo-analysis/README.md` | clean | +| `plugins/knowledge/vendor/video-digestion/TUNING.md` | clean | +| `plugins/machine-health/skills/audit/references/windows/check-catalog.md` | clean | +| `plugins/machine-health/skills/audit/references/windows/elevation-matrix.md` | clean | +| `plugins/mcp-tools/skills/audit/reference/server-discovery.md` | clean | +| `plugins/planning/reference/topic-docs.md` | clean | +| `plugins/planning/skills/draft-goal-condition/SKILL.md` | clean | +| `plugins/planning/skills/interview/context/session-config.md` | clean | +| `plugins/playbooks/skills/boris/SKILL.md` | clean | +| `plugins/songwriting/context/pat-pattison/research/ai-tools.md` | clean | +| `plugins/testing/README.md` | clean | +| `plugins/toolchain/skills/check/context/bash.md` | clean | +| `plugins/toolchain/skills/check/context/dotnet.md` | clean | +| `plugins/toolchain/skills/check/context/go.md` | clean | +| `plugins/toolchain/skills/check/context/python.md` | clean | +| `plugins/toolchain/skills/check/context/typescript.md` | clean | +| `plugins/typos-format/README.md` | clean | + +## Route: extract-ssot (136) + +Pragmatic triage (not a full Rule-of-Three extract pass). Categories: + +### A — Keep as synced byte-identical cluster (registered) + +Already enforced by `scripts/cross-plugin-source-registry.txt` + +`validate-plugin-contracts.mjs`. Pointer-extraction would break per-plugin +install copies. + +- `plugins/{discovery,implementation,planning,verification}/reference/artifact-protocol.md` + +### B — Functional artifacts / scaffolds (out of scope for dedup-into-prose-SSOT) + +Per post-#2695 rubric: runtime checklists and similar scaffolds may duplicate +*shape* without being extract-ssot candidates into a shared prose SSOT. +Re-open only if two checklists are byte-identical and meant to stay that way +(then register like artifact-protocol). + +- `plugins/**/templates/checklist.md` (planning, interview, session-flow, + debugging, codebase-health, code-tidying, claude-config, source-control, + work-items, …) +- `plugins/machine-health/skills/audit/scripts/{linux,macos}/NOT_IMPLEMENTED.md` + (near-dup scaffolding; OS-specific on purpose) +- `plugins/claude-config/skills/audit/templates/checklist.md` and siblings + +### C — CHANGELOG routes (changelog-parity before any dedup) + +Do not collapse changelogs across concerns. Judge each against the +changelog-parity convention if a future pass revisits them. + +- `docs/conventions/*/CHANGELOG.md` (finding-suppression, hook-telemetry, + liveness-assertion, plugin-data-report-keying, standards) +- `plugins/mutation-testing/CHANGELOG.md` + +### D — Pending extract-ssot candidates (not processed this batch) + +Everything else on the original 136 list remains a **candidate** for a future +`/docs-hygiene:extract-ssot` identify pass (path/glob-scoped, not bare +whole-repo). Highest-leverage next slices when resumed: + +1. Plugin README boilerplate clusters (format plugins, hygiene plugins) — + similarity ~0.5–0.7, needs Rule-of-Three evidence before extract. +2. `plugins/docs-hygiene/skills/rename-references/context/{apply,audit,triage}.md` + — same skill, likely progressive-disclosure not duplication. +3. Songwriting research/template prompt cluster — large; defer to a dedicated + extract-ssot wave. +4. Autonomy setup templates — likely intentional variants. + +Full original path list: GitHub issue #2735 (durable copy of the ephemeral +ledger). This file owns **status**, not a second full roster, so the two stay +aligned via the issue link rather than a duplicated 136-row table. + +## False-keep sampling backlog + +The completed sweep's 1089 `keep-owns-facts` verdicts were never sampled. The +contract now requires sampling keeps on future sweeps. A one-off 20-keep +fresh-context probe is blocked here because the session ledger is gone; do not +fabricate sample membership. Next full `audit-derivability` sweep must sample +keeps and record the sample set beside its ledger. diff --git a/plugins/docs-hygiene/skills/audit-derivability/SKILL.md b/plugins/docs-hygiene/skills/audit-derivability/SKILL.md index e21e7a12f..cd209a2cf 100644 --- a/plugins/docs-hygiene/skills/audit-derivability/SKILL.md +++ b/plugins/docs-hygiene/skills/audit-derivability/SKILL.md @@ -119,7 +119,7 @@ Batch / sweep aggregate at the end: Audited document(s): delete,

convert-to-pointer, keep-as-cache, keep-owns-facts, out-of-scope functional artifacts; of the verdicts also carry a route-to-sibling annotation. ``` -Route-to-sibling is an ANNOTATION on a verdict, never a fifth verdict class: a document whose verdict stands (usually a keep) but whose rationale routes material to a sibling — doc-to-doc duplication to `/docs-hygiene:extract-ssot`, line-level noise to `/docs-hygiene:audit-noise` — records that route in its rationale, and `` counts the documents carrying one, so routed work is visible in the aggregate instead of vanishing into the keep bucket. +Route-to-sibling is an ANNOTATION on a verdict, never a fifth verdict class: a document whose verdict stands (usually a keep) but whose rationale routes material to a sibling — doc-to-doc duplication to `/docs-hygiene:extract-ssot`, line-level noise to `/docs-hygiene:audit-noise` — records that route in its rationale, and `` counts the documents carrying one, so routed work is visible in the aggregate instead of vanishing into the keep bucket. In-tree follow-up status for the 2026-08-15 repo-wide routed set: [`../../context/derivability-route-followups.md`](../../context/derivability-route-followups.md). Corpus-scale sweeps (more documents than one reply can carry): the per-document blocks live in the batch ledger files; the reply carries the aggregate line, the confirmed-actionable (`delete` / `convert-to-pointer`) subset, the provisional (cap-deferred) verdicts reported separately for visibility — never as part of the actionable subset — and the ledger file locations.