toolshed: Instructions file for Claude Code

CLAUDE.md

This repo is a Claude Code plugin marketplace, not an application. It is almost entirely Markdown; the executable code published is the engine package (plugins/doc-lifecycle/engine/doclifecycle/, stdlib-only — the single owner the #57 re-architecture absorbed the helper scripts into; see its README.md) plus thirteen skill helper scripts (plugins/doc-lifecycle/skills/detecting-doc-drift/scripts/validate-drift-output.py, plugins/doc-lifecycle/skills/detecting-doc-bloat/scripts/validate-bloat-output.py and .../detecting-doc-bloat/scripts/plan-chunks.py, plus scheduling-doc-sync's scripts/upgrade-gate.py (the upgrade lane's semver comparison, plus the strict X.Y.Z shape-check a dispatched upgrade target passes before it names a git ref), scripts/stage-upgrade.py (that lane's path authority, #127 — it derives what a regeneration wrote by comparing the scratch tree against the install, refuses the run whole if any difference lies outside what apply-upgrade.py owns, and is vendored precisely because both upgrade jobs must run it from a copy of the install's own tooling taken before the regeneration wrote the release's copy of it), scripts/render-report.py (the upgrade lane's run surface — its only consumer; detecting-doc-bloat now summarizes its report by hand rather than through a subcommand here), scripts/render-audit-summary.py (the audit lanes' run-surface rendering — #71/#144), scripts/render-apply-summary.py (the apply lane's run surface — its refusals, its staged path list, and the PR title, body, and commit message that carry the approval set's digest and summary — #72; plus that lane's recovery half, #198 — it reads what the remote holds at the derived branch and which pull request is already open on it, and renders each terminal recovery state: branch created, branch reused, pull request already open, or a typed conflict), scripts/probe-evidence-tool.py (the audit lane's declared-tool probe — it renders drift-audit --evidence-command from evidence-tools.json and runs each declared tool only as a --help/--version read, under the model step's existing Bash(python3 *) grant rather than a wider one, #118), scripts/verify-apply-bytes.py (both apply lanes' byte verification at the two git boundaries the engine cannot see, #191 — it takes the applier's certified postimage manifest and compares the staged index and then the commit tree against it, refusing when git holds anything else and naming the commit the push carries so the pushed tree is the verified one; and at a third boundary, #198 — the same certification asked of an existing derived branch a re-run found on the remote, which is reusable only if it carries this approval's trailer, sits on the same base, and is still what the branch holds when the lane fetches it, since a branch that advanced in between would keep the read commit alive as an ancestor and pass every other check), and scripts/bloat-cadence.py (the scheduled bloat lane's trusted prompt renderer and schema-bound action-output collector — it validates chunk returns, selects one retry, and runs from the release-pinned marketplace rather than being vendored), and scripts/check-repo-integrity.py (the repository-integrity gate both read-only audit lanes run between the model step and any assembly — HEAD, staged, tracked, and untracked surfaces, with an --allow list holding exactly the artifacts a lane declared it would write into the work tree; un-vendored because it judges the checkout and so must not live in it, #185), and scripts/apply-upgrade.py (the deterministic upgrade engine — the target release's own copy is what the upgrade lane runs, in the one job holding no credential, and it stays deliberately un-vendored) — all under scheduling-doc-sync/scripts/, not the skill's base directory, which holds only the templates; all python3, no deps) plus the five GitHub Actions templates the scheduling skill installs (plugins/doc-lifecycle/skills/scheduling-doc-sync/doc-audit.yml — the read-only scheduled drift audit, #71; doc-bloat-audit.yml — the weekly read-only, budgeted Task fan-out whose typed completion gaps come from the report, #144; doc-apply.yml — the manual apply dispatch, the human-selected apply lane, #72; doc-policy-apply.yml — the successful-scheduled-audit-chained policy lane whose three jobs keep the model repository-credential-free and open a real review PR for the mechanical subset selected by the standing consumer policy, #143; and doc-sync-upgrade.yml — the model-free upgrade lane, whose weekly schedule only detects a newer release and files a notice issue, while a human dispatch naming the target is what regenerates the wiring and opens the version-bump PR, #127). #77 removed the legacy doc-sync.yml / doc-bloat.yml write lanes and their gate/path-authority/distill-planner scripts, so an install is exactly those five templates; apply-upgrade.py installs the four engine lanes only into a repo holding .doc-lifecycle/registry.json, and the upgrade lane everywhere. The sample repos under tests/fixtures/ are the other runnable code that matters, alongside the dogfooded install under .doc-lifecycle/ (#133 centralized it there out of .github/doc-sync/; three tiers by owner — consumer judgment at the root, plugin-regenerated wiring under wiring/, machine-written state under state/): wiring/upgrade-gate.py, wiring/stage-upgrade.py, wiring/render-report.py, wiring/render-audit-summary.py, wiring/render-apply-summary.py, wiring/probe-evidence-tool.py, wiring/verify-apply-bytes.py — the chunk planner and the two output validators are NOT vendored here; both detecting skills always dispatch their own copy via ${CLAUDE_PLUGIN_ROOT}, so a copy under wiring/ would have no reader (aj604/toolshed#77 follow-up), and check-repo-integrity.py is not vendored either — both audit lanes run it from the release-pinned marketplace clone, because a gate that judges the checkout must not be a file inside the checkout it judges (#185), wiring/engine/ (the doclifecycle package vendored wholesale from plugins/doc-lifecycle/engine/, byte-identical to it — the only copy the lanes run, never edited in place), registry.json (the classification registry — five roots, closed-world), audit-scope.json (bloat-audit scope config, and one of Migration mode's inference inputs), drift-waivers.json (accepted-UNVERIFIABLE claims — drift-audit --waivers annotates against it, and Migration mode re-keys it; no installed lane passes that flag today), evidence-tools.json (the local tools the audit lane may cite — gh here), auto-apply-policy.json (this consumer's standing authorization for mechanical stale-passage and narrative-anchor refresh records; upgrades preserve it and never seed one), installed-version (the plugin-version lockfile the upgrade workflow reads), and state/sync-marker, which survives as legacy state no lane reads — carried across the relocation byte-for-byte because whose state it is decides that. The five lane workflows stay in .github/workflows/ (doc-audit.yml, doc-bloat-audit.yml, doc-apply.yml, doc-policy-apply.yml, doc-sync-upgrade.yml) because GitHub reads workflows only from there, and are the only doc-lifecycle content left under .github/. Also runnable: the ci+release workflow (.github/workflows/release.yml), that workflow's own test-suite runner (.github/scripts/run-script-suites.py, #99 — discovery-driven, so a new tests/scripts/*_test.py suite needs no hand-wiring), the release manifest guard (.github/scripts/release-manifest.py, #77 — it reads release.yml for the discovery steps CI actually runs, computes the suites those steps really execute, and fails when a suite in the tree is not among them: a tests/engine subdirectory missing __init__.py, a name the pattern misses, a directory nothing discovers, or a glob narrowed in release.yml. It also carries the release manifest mapping each release criterion to the suites that discharge it — #77's original criteria, #158's primary human lifecycle transaction, and #203's issue #168 sign-off regressions, which names the suites carrying each reproduced sign-off failure's regression so deleting one is a reported failure rather than a quietly smaller gate — and declares tests/baselines/ and tests/fixtures/ non-gate roots — the RED/GREEN skill baselines are retained methodology, demonstrably outside the release gate), and the shadow-mode parity gate's second-cycle worker orchestrator (tests/baselines/shadow-parity-gate-rerun/fanout.py, #117 — kept because it carries the worker prompt the verdict makes claims about). The rest of the tree's Python is one-off tooling wired into no lane and no CI step: assets/demo/make_cast.py (the README demo's generator), tests/docs-ab/ (the A/B harness), tests/baselines/fixing-docs-merge-red/build_report.py.