diff --git a/.claude/cloud-bootstrap.sh b/.claude/cloud-bootstrap.sh index d03c42416b..7322f159a2 100755 --- a/.claude/cloud-bootstrap.sh +++ b/.claude/cloud-bootstrap.sh @@ -137,7 +137,7 @@ fi # exists for: a session exercises the plugin code on the current branch, not # published main. # -# Timing limit (docs/CLOUD-SESSIONS.md, "Plugins in sessions on this repo"): +# Timing limit (docs/cloud-sessions.md, "Plugins in sessions on this repo"): # the plugin/command registry is read at process start, BEFORE a SessionStart # hook runs, and is not re-read, so a hook run's installs are invisible to the # session performing them. They serve the next process start — which on an @@ -261,7 +261,7 @@ if [[ -x "$claude_bin" ]] && command -v jq >/dev/null 2>&1; then # A directory-source install cache is keyed by the semver in plugin.json, not # by commit, so a later commit under the same version never replaces the # snapshot and `plugin update` false-greens on the version compare — see - # "Same-version commit drift" in docs/MIGRATION-PLAYBOOK.md and #2061. On a + # "Same-version commit drift" in docs/migration-playbook.md and #2061. On a # resume after the checkout advanced, a presence check alone would therefore # keep serving the skills and hooks of whatever commit installed first, which # defeats the reason this repo uses a directory source at all. Compare the SHA diff --git a/.claude/rules/ruff-pin.md b/.claude/rules/ruff-pin.md index 7b9b283d1d..b0ce708af4 100644 --- a/.claude/rules/ruff-pin.md +++ b/.claude/rules/ruff-pin.md @@ -10,4 +10,4 @@ Lint Python in this repo through `scripts/run-ruff.sh check ` (the wrappe ruff arguments through and resolves the CI-pinned ruff version); a bare `ruff` on PATH can disagree with CI in both directions, so never use it for verification here. Do not adopt a newer ruff's new rules in an unrelated change; bumping the pin is a deliberate Dependabot change. Full rationale: -[`docs/CI-RUNNER-ROUTING.md`, "Local / workstation ruff"](../../docs/CI-RUNNER-ROUTING.md#local--workstation-ruff). +[`docs/ci-runner-routing.md`, "Local / workstation ruff"](../../docs/ci-runner-routing.md#local--workstation-ruff). diff --git a/.github/recurring-schedule.json b/.github/recurring-schedule.json index 4a1106d59b..e15e982634 100644 --- a/.github/recurring-schedule.json +++ b/.github/recurring-schedule.json @@ -14,7 +14,7 @@ }, "last_checked": "2026-08-08", "next_due": "2026-11-06", - "notes": "On each frontier model release (primary trigger), run /claude-config:audit-instructions and /claude-config:unhobble over this repository's session surfaces to re-test which standing instructions the new model still needs. No automation observes the release event: the trigger's consumer is the standing OPEN [Maintenance] issue (#2019) — kept open continuously so /work-items:work can select it the moment an operator or agent notices a release, ahead of next_due. The quarterly cadence is a backstop only, guaranteeing the pass happens even when a release goes unnoticed (docs/PLUGIN-PHILOSOPHY.md, Instruction economy). Tier-4 caveat (known limitation, unenforced): last-resort selection can pick the open issue when no release has occurred, and neither the work skill's tier-4 step nor recheck's close step consults any precondition — the issue body instructs the claimant (no frontier release since last_checked: unclaim, leave open, never recheck-close), but honoring that depends on the claimant reading the body and deviating from the unconditional close step. If a premature close drains the item before a real release, re-open or re-create it from this row. Session surfaces only, never the shipped plugin components.", + "notes": "On each frontier model release (primary trigger), run /claude-config:audit-instructions and /claude-config:unhobble over this repository's session surfaces to re-test which standing instructions the new model still needs. No automation observes the release event: the trigger's consumer is the standing OPEN [Maintenance] issue (#2019) — kept open continuously so /work-items:work can select it the moment an operator or agent notices a release, ahead of next_due. The quarterly cadence is a backstop only, guaranteeing the pass happens even when a release goes unnoticed (docs/plugin-philosophy.md, Instruction economy). Tier-4 caveat (known limitation, unenforced): last-resort selection can pick the open issue when no release has occurred, and neither the work skill's tier-4 step nor recheck's close step consults any precondition — the issue body instructs the claimant (no frontier release since last_checked: unclaim, leave open, never recheck-close), but honoring that depends on the claimant reading the body and deviating from the unconditional close step. If a premature close drains the item before a real release, re-open or re-create it from this row. Session surfaces only, never the shipped plugin components.", "close_previous": true }, { @@ -38,7 +38,7 @@ "triggers": [], "last_checked": "2026-08-08", "next_due": "2026-11-06", - "notes": "Report-only self-maintenance routine (digest menu #9 pilot). Sweep docs/ and top-level repo docs for references to files/checks/skills that no longer exist, stale version claims, and moved OFFICIAL-DOCS.md pages (review:doc-drift-detector or docs-hygiene audits); verify generated CATALOG/SKILL-CHEAT-SHEET freshness on a scratch branch. File one issue per confirmed drift cluster or comment no-drift on the open [Maintenance] issue (#2024 is the first instance). Never edits docs directly from the routine.", + "notes": "Report-only self-maintenance routine (digest menu #9 pilot). Sweep docs/ and top-level repo docs for references to files/checks/skills that no longer exist, stale version claims, and moved official-docs.md pages (review:doc-drift-detector or docs-hygiene audits); verify generated CATALOG/skill-cheat-sheet freshness on a scratch branch. File one issue per confirmed drift cluster or comment no-drift on the open [Maintenance] issue (#2024 is the first instance). Never edits docs directly from the routine.", "close_previous": true } ] diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 8fb10f1150..e2b68d5ed0 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -604,6 +604,15 @@ jobs: continue-on-error: true run: scripts/check-skill-leaf-names.sh --check + # Self-test first, so a broken checker cannot mask a regression. + - name: Run docs-naming tests + if: needs.changes.outputs.run_shell == 'true' + run: bash scripts/check-docs-naming.test.sh + - name: Check docs/ filenames are lower-kebab + id: docs_naming + continue-on-error: true + run: scripts/check-docs-naming.sh --check + # A plugin's prose counts its own skills by hand ("bundling fourteen # skills", "the other thirteen skills are zero-config") and nothing # recomputes those numbers when a skill lands, so adding one silently @@ -758,7 +767,7 @@ jobs: continue-on-error: true run: scripts/check-plugin-manifest-presence.sh - # docs/CLOUD-SESSIONS.md promises `enabledPlugins` "turns on the whole + # docs/cloud-sessions.md promises `enabledPlugins` "turns on the whole # catalog, so this repo dogfoods everything it publishes"; nothing # enforced it, and ai-slop (#2892), context-budget (#2932) and # improvement (#2985) each reached main catalogued but never enabled. The @@ -1135,7 +1144,7 @@ jobs: # a month after the 750k consumers had already overflowed, and a tripwire # that fires after the failure it exists to predict is worse than none. # (Neither basis speaks for a 200k-window consumer, who is over the - # 40,000-char budget today; docs/CLOUD-SESSIONS.md records that.) + # 40,000-char budget today; docs/cloud-sessions.md records that.) # Report-only for the same reason its sibling is. The fix for the # aggregate is the per-skill description trim, which #3526 owns. - name: Report the skill-listing budget at this repo's configured fraction @@ -1268,6 +1277,7 @@ jobs: loop-lane-floor-drift=${{ steps.loop_lane_floor_drift.outcome }} detector-findings-crosswalk=${{ steps.detector_findings_crosswalk.outcome }} skill-leaf-names=${{ steps.skill_leaf_names.outcome }} + docs-naming=${{ steps.docs_naming.outcome }} skill-count-claims=${{ steps.skill_count_claims.outcome }} userconfig-argv=${{ steps.userconfig_argv.outcome }} hook-exec-form=${{ steps.hook_exec_form.outcome }} diff --git a/README.md b/README.md index 21a91fd4c0..09280acf26 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ Browse and manage with `/plugin`. To refresh after updates: `/plugin marketplace When you consume this repo from a local `directory` source, the install cache keys on semver `version`, not commit, so several commits under one version leave early installs on a stale snapshot and `plugin update` can report "already at the latest version" while SHA lags. See -[`docs/MIGRATION-PLAYBOOK.md`](docs/MIGRATION-PLAYBOOK.md) ("Same-version commit drift") and +[`docs/migration-playbook.md`](docs/migration-playbook.md) ("Same-version commit drift") and [#2061](https://github.com/melodic-software/claude-code-plugins/issues/2061). ### Enable plugin suggestions for an organization @@ -51,12 +51,12 @@ user opts in with `/plugin enable`; an existing install is never flipped by cata ## Finding your way -- Not sure which skill to invoke? Start at the [skill cheat sheet](docs/SKILL-CHEAT-SHEET.md). A +- Not sure which skill to invoke? Start at the [skill cheat sheet](docs/skill-cheat-sheet.md). A scan-and-go map from what you are doing to the skill that does it. -- [Plugin catalog](docs/CATALOG.md). Every plugin by category, generated from the manifests and +- [Plugin catalog](docs/catalog.md). Every plugin by category, generated from the manifests and kept in sync by CI. New plugins clear the per-plugin migration gate in - [`docs/MIGRATION-PLAYBOOK.md`](docs/MIGRATION-PLAYBOOK.md). -- [Catalog taxonomy](docs/CATALOG-TAXONOMY.md). The category vocabulary the catalog is grouped by. + [`docs/migration-playbook.md`](docs/migration-playbook.md). +- [Catalog taxonomy](docs/catalog-taxonomy.md). The category vocabulary the catalog is grouped by. ## What's here @@ -73,13 +73,13 @@ user opts in with `/plugin enable`; an existing install is never flipped by cata source-control convention). It governs work done here and ships to no one. - `.github/`, workflows plus the policy files they read (runner policy, security paths, recurring schedule, PR template). -- `docs/MIGRATION-PLAYBOOK.md`, design charter, extensibility model, the per-plugin migration +- `docs/migration-playbook.md`, design charter, extensibility model, the per-plugin migration gate, and the local development loop. - `docs/`, further design records and audits (CI runner routing, extensibility-contract smoke tests, migration audits). - `CLAUDE.md`, operating rules for AI agents working in this repo (fresh-docs mandate + plugin design rules). -- `docs/OFFICIAL-DOCS.md`, canonical index of the official Claude Code doc pages the mandate +- `docs/official-docs.md`, canonical index of the official Claude Code doc pages the mandate sends you to. ## Validate a change diff --git a/docs/adr/0003-verification-guards-earn-default-on-by-measured-precision.md b/docs/adr/0003-verification-guards-earn-default-on-by-measured-precision.md index 891cdbb051..f7073c7942 100644 --- a/docs/adr/0003-verification-guards-earn-default-on-by-measured-precision.md +++ b/docs/adr/0003-verification-guards-earn-default-on-by-measured-precision.md @@ -117,7 +117,7 @@ sufficient one. Specifically: duplicating `check-changelog-parity --check-bump` would fire correctly; it would simply add no signal the required gate does not already produce, while adding a second place the rule can drift. That is the **one mechanism per concern** principle - (`PLUGIN-PHILOSOPHY.md`'s validation section, owned upstream in `standards`) — redundancy, + (`plugin-philosophy.md`'s validation section, owned upstream in `standards`) — redundancy, not a silent skip. The deletion criterion for a future guard author is "supplies no additional signal," which is a coverage test, not a correctness one. @@ -144,6 +144,6 @@ sufficient one. Specifically: - #1270 (scoping, amended twice), #1284 (the two-guard PR, closed), #1319 (the shipped guard), #1314 (the withdrawn guard's measurement and rescope) - `docs/conventions/hook-precision/README.md` — over-fire discipline -- `docs/PLUGIN-PHILOSOPHY.md` — one mechanism per concern (validation section) +- `docs/plugin-philosophy.md` — one mechanism per concern (validation section) - `melodic-software/standards`, `conventions/engineering/enforceability-tiers.md` — classify the tier first, justify automation second diff --git a/docs/adr/0004-rightsize-instruction-surfaces-by-incumbent-first-arbitration.md b/docs/adr/0004-rightsize-instruction-surfaces-by-incumbent-first-arbitration.md index e8b7cb1785..17bfed721f 100644 --- a/docs/adr/0004-rightsize-instruction-surfaces-by-incumbent-first-arbitration.md +++ b/docs/adr/0004-rightsize-instruction-surfaces-by-incumbent-first-arbitration.md @@ -59,7 +59,7 @@ re-decide. | # | Decision | Consequence | |---|---|---| | D-7 | **Fold the listing-budget material into issue #1271**, and adopt its `when_to_use` lever | #1271 already measured the defect and found the field this effort's agents missed. No second ticket | -| D-8 | **Sequence behind PR #1096** for anything touching `check-skill.sh` or `docs/PLUGIN-PHILOSOPHY.md` | Check 21 is taken. New criteria pick a free number against the post-merge file | +| D-8 | **Sequence behind PR #1096** for anything touching `check-skill.sh` or `docs/plugin-philosophy.md` | Check 21 is taken. New criteria pick a free number against the post-merge file | | D-9 | **Sequence the user-scope work behind dotfiles PRs #318 and #312**, and read #312's Opus 5 re-derivation as an input before measuring | Measuring `dot_claude/CLAUDE.md` while two PRs edit it produces a diff that reverts newer rules | | D-10 | **Drop the stale dotfiles branch** `docs/claude-md-github-conventions` (+13 lines to `CLAUDE.md`, last commit 2026-07-15, no PR) | One fewer writer on the contested file | | D-11 | **Reconcile with issue #1225 before building anything sweep-shaped** | Two repo-wide sweeps become two routers | @@ -81,7 +81,7 @@ These are the questions the section agents explicitly declined to answer, plus t | D-15 | **Arbitration stays the repo's default posture.** Deletion is adopted only where a constraint has no current safety rationale | Overrides the article's blanket delete-constraints posture. A lane proposing a deletion must state the constraint's rationale and why it no longer holds | | D-16 | **The fresh-docs mandate narrows in scope, not in substance** — it binds changes touching a plugin manifest, marketplace schema, hook contract, or documented harness behavior | Prose and mechanical edits are out. The mandate stays non-negotiable within its scope | | D-17 | **Auto-memory: move `autoMemoryEnabled` from `claudeSettings.force` to `claudeSettings.seed`, seeded `false`** | Two decisions, both taken. The tier move ends the silent-revert trap; `seed` writes only when absent, so this machine keeps its current value and every fresh machine starts off. Overrides the S7 agent's `true` recommendation on tracked-drift grounds — the capability unlock is available per machine by toggle | -| D-18 | **Cut `CLAUDE.md:13-30`** (the doc-URL table) to a pointer at `docs/OFFICIAL-DOCS.md` | Verified strict subset; 29.6% of the file; line 30 already points at the superset. Accepted risk: the mandate's force must come from the rule, not from the URLs being pre-loaded | +| D-18 | **Cut `CLAUDE.md:13-30`** (the doc-URL table) to a pointer at `docs/official-docs.md` | Verified strict subset; 29.6% of the file; line 30 already points at the superset. Accepted risk: the mandate's force must come from the rule, not from the URLs being pre-loaded | | D-19 | **Vendored `skill-authoring` guidance governs authoring mechanics; this effort's carve-out governs what stays constrained** | Different axes. Where they genuinely collide, upstream wins and the divergence is recorded — a vendored file is never hand-edited | ### Standing constraints these decisions inherit diff --git a/docs/adr/0005-bound-instruction-surface-work-by-question-not-population.md b/docs/adr/0005-bound-instruction-surface-work-by-question-not-population.md index 4229e816c0..7700162457 100644 --- a/docs/adr/0005-bound-instruction-surface-work-by-question-not-population.md +++ b/docs/adr/0005-bound-instruction-surface-work-by-question-not-population.md @@ -334,7 +334,7 @@ re-run the sweep rather than treating the row set as complete. | **#1268** false `context: fork` rationale | No / No — **title-filter false positive** | Matched only on the literal `audit` inside another topic's slice path (`docs/topics/plugin-audit-port/`, PR #1241). It corrects one rationale inside that topic's design record, explicitly says "Do not change the decision", and has since closed. Recorded so a reader can see it was assessed rather than silently dropped | Per D-8, anything touching `plugins/skill-quality/scripts/check-skill.sh` or -`docs/PLUGIN-PHILOSOPHY.md` sequences behind PR #1096, which claims **check 21**. The next free check +`docs/plugin-philosophy.md` sequences behind PR #1096, which claims **check 21**. The next free check number is **22**. Neither L2 nor L3 needs a `check-skill.sh` slot — L2 lands in `claude-config`, L3 is a catalog edit — so #1096 is a constraint to respect, not a blocker either lane waits on. diff --git a/docs/adr/0016-source-skill-recommendation-from-the-catalog-not-the-listing.md b/docs/adr/0016-source-skill-recommendation-from-the-catalog-not-the-listing.md index 1cad962ce5..7eee8ed1dd 100644 --- a/docs/adr/0016-source-skill-recommendation-from-the-catalog-not-the-listing.md +++ b/docs/adr/0016-source-skill-recommendation-from-the-catalog-not-the-listing.md @@ -128,7 +128,7 @@ boundary events if that graduation is ever taken — never `UserPromptSubmit`, w > description-matched, not hook-driven, so no `Stop`/`TaskCompleted` hook is implied by this > revision. -**Placement.** `docs/CATALOG-TAXONOMY.md`'s assignment principle says subject wins when the subject +**Placement.** `docs/catalog-taxonomy.md`'s assignment principle says subject wins when the subject is the salient reason a plugin exists, which argues for filing this under `claude-code`/`claude-ops` beside `inventory`. It lands in `session-flow` instead: the skill's subject is the **session** — what to do next given where this session stands — and its inputs are session state (durable artifacts, diff --git a/docs/adr/0018-treat-the-plugin-as-the-encapsulation-boundary-for-skill-citation.md b/docs/adr/0018-treat-the-plugin-as-the-encapsulation-boundary-for-skill-citation.md index de9db25644..4970d65993 100644 --- a/docs/adr/0018-treat-the-plugin-as-the-encapsulation-boundary-for-skill-citation.md +++ b/docs/adr/0018-treat-the-plugin-as-the-encapsulation-boundary-for-skill-citation.md @@ -8,7 +8,7 @@ Two documents in this repository gave skill authors opposite instructions about citing a path inside another skill, and both were being followed. -`docs/PLUGIN-PHILOSOPHY.md:337-342` prescribes the citation and regulates only its path form: +`docs/plugin-philosophy.md:337-342` prescribes the citation and regulates only its path form: ```text Apply the same anchoring rule to bundled assets: one skill citing another skill's supporting file @@ -84,7 +84,7 @@ sees only the conclusion will re-make them. The draft ruling kept 49 findings alive on the grounds that a bare relative cross-skill path "stays a defect on the philosophy doc's own reasoning". It does not. The doctrine condemns one specific -shape, at `docs/PLUGIN-PHILOSOPHY.md:341-342`: +shape, at `docs/plugin-philosophy.md:341-342`: ```text A bare `context/…`-style path is reserved for a skill's OWN supporting files; it resolves against @@ -167,7 +167,7 @@ Same plugin, same targets, one anchored and correct, one bare and unresolvable. is binding rather than advisory: legalising the intra-plugin case without also requiring a resolvable form produces drift inside a single plugin, and already has. -Two of the ten sit in the doctrine document itself, at `docs/PLUGIN-PHILOSOPHY.md:596` and `:1071`, +Two of the ten sit in the doctrine document itself, at `docs/plugin-philosophy.md:596` and `:1071`, writing a path with no resolvable base in the same file whose lines 341-342 forbid exactly that. The first is a live Convention-registry row other plugins consult: @@ -189,7 +189,7 @@ everyone who installs `docs-hygiene`. That recommendation was **not** taken literally, and the departure is recorded here so it is chosen rather than inherited. The relaxation was written into both documents instead: -- `docs/PLUGIN-PHILOSOPHY.md` states the cross-plugin limit it previously omitted, which is how 30 +- `docs/plugin-philosophy.md` states the cross-plugin limit it previously omitted, which is how 30 call sites came to read blanket permission into it, and states the anchor limit. - `public-surface-contract.md` gained a conditional carve-out rather than a relaxation. It is gated on the consuming repo actually being built that way (one manifest and one version per plugin, no diff --git a/docs/adr/0021-reject-the-three-unused-official-plugin-components.md b/docs/adr/0021-reject-the-three-unused-official-plugin-components.md index 9085f90d93..027be738bd 100644 --- a/docs/adr/0021-reject-the-three-unused-official-plugin-components.md +++ b/docs/adr/0021-reject-the-three-unused-official-plugin-components.md @@ -8,7 +8,7 @@ The three unused official plugin components raised as adoption candidates on this date, evaluated against the enforcement hierarchy (default **REJECT** unless the value is concrete and not already covered by an existing mechanism). This is that evaluation, not an index of every component the -marketplace does not use — the [component-stances table](../PLUGIN-PHILOSOPHY.md#component-stances) is +marketplace does not use — the [component-stances table](../plugin-philosophy.md#component-stances) is that index, and it carries a stance for components never raised here. Facts verified fresh 2026-07-12 per `CLAUDE.md` "Fresh-docs mandate". Verdict for all three: **REJECT now**, each with an explicit recheck trigger — no implementation issues emitted (zero accepted). diff --git a/docs/adr/0025-adopt-the-unknowns-corpus-as-judgment-preserving-contract-deltas.md b/docs/adr/0025-adopt-the-unknowns-corpus-as-judgment-preserving-contract-deltas.md index 58a3b4c4bd..bc66c84ccb 100644 --- a/docs/adr/0025-adopt-the-unknowns-corpus-as-judgment-preserving-contract-deltas.md +++ b/docs/adr/0025-adopt-the-unknowns-corpus-as-judgment-preserving-contract-deltas.md @@ -32,9 +32,9 @@ anti-premature-codification warning treated as a binding constraint: sign-off, as additive lines in the owning skills' bodies with same-commit eval expectations, never as generator skills. - BEHAVIORAL rows never land as standing instructions: they ship as doc lines in - `docs/FINDING-YOUR-UNKNOWNS.md` plus tracked eval candidates (#3589), awaiting + `docs/finding-your-unknowns.md` plus tracked eval candidates (#3589), awaiting observed-stumble evidence. -- `docs/FINDING-YOUR-UNKNOWNS.md` is the graduated reference and the owner doc for the +- `docs/finding-your-unknowns.md` is the graduated reference and the owner doc for the reply-affordance and export-button conventions (registry rows point at it, owner-doc-first); it quotes the warning byte-faithfully under a stated fair-quotation basis. diff --git a/docs/adr/0028-classify-a-plugin-s-hooks-by-packaging-before-proposing-a-split.md b/docs/adr/0028-classify-a-plugin-s-hooks-by-packaging-before-proposing-a-split.md index 1a976142e8..71a7d15af8 100644 --- a/docs/adr/0028-classify-a-plugin-s-hooks-by-packaging-before-proposing-a-split.md +++ b/docs/adr/0028-classify-a-plugin-s-hooks-by-packaging-before-proposing-a-split.md @@ -81,7 +81,7 @@ Class C split is urgent, and they remain the only such lever for Class A and B. FIRES by default. - [ADR 0019](0019-share-code-across-plugins-by-vendoring-with-a-sync-gate.md) — the packaging analogue: how code is shared across plugins once they are separate. -- [`docs/PLUGIN-PHILOSOPHY.md` § Classifying a hook](../PLUGIN-PHILOSOPHY.md#classifying-a-hook) — +- [`docs/plugin-philosophy.md` § Classifying a hook](../plugin-philosophy.md#classifying-a-hook) — the complementary axes. That rubric asks what a hook DOES (mechanism) and why it EXISTS (class); this one asks where it belongs. A hook can be pure policy by that rubric and still sit in a Class C plugin. diff --git a/docs/adr/0029-admit-a-second-findings-producer-behind-a-targeted-run-clause.md b/docs/adr/0029-admit-a-second-findings-producer-behind-a-targeted-run-clause.md index 30d2d1ae8a..0ff0421153 100644 --- a/docs/adr/0029-admit-a-second-findings-producer-behind-a-targeted-run-clause.md +++ b/docs/adr/0029-admit-a-second-findings-producer-behind-a-targeted-run-clause.md @@ -96,7 +96,7 @@ over a corpus, so it was measured once on this repository before shipping: The one is `docs/hook-migration-audit.md`, which no file in the repository references under any form. Both rejections are more instructive than the survivor. `docs/adr/0006-...` is cited twice, but under the `ADR 0006` form rather than the filename form, caught by this lane's own query-form-variation -rule. `docs/ai-briefing-design.md` is cited by `docs/MIGRATION-PLAYBOOK.md`, and was missed because +rule. `docs/ai-briefing-design.md` is cited by `docs/migration-playbook.md`, and was missed because the measurement filtered to paths "cited nowhere outside their own directory" while both files sit in `docs/`. Two of three apparent orphans were citation-search artifacts, in two different ways. diff --git a/docs/adr/0031-name-the-worktree-root-git-config-key-as-a-capability-section.md b/docs/adr/0031-name-the-worktree-root-git-config-key-as-a-capability-section.md index 1e86f51b2a..33c591b9bf 100644 --- a/docs/adr/0031-name-the-worktree-root-git-config-key-as-a-capability-section.md +++ b/docs/adr/0031-name-the-worktree-root-git-config-key-as-a-capability-section.md @@ -104,7 +104,7 @@ adopt. ## Consequences -- `docs/PLUGIN-PHILOSOPHY.md` Design boundary states the collision-free +- `docs/plugin-philosophy.md` Design boundary states the collision-free capability-section rule and names `worktreeroot.path`. Convention registry gains a row pointing at `plugins/source-control/reference/worktree-root-convention.md`. diff --git a/docs/adr/0034-name-docs-files-lower-kebab-case-with-conventional-exceptions.md b/docs/adr/0034-name-docs-files-lower-kebab-case-with-conventional-exceptions.md new file mode 100644 index 0000000000..fa878bc9b3 --- /dev/null +++ b/docs/adr/0034-name-docs-files-lower-kebab-case-with-conventional-exceptions.md @@ -0,0 +1,117 @@ +# Name docs/ files in lower-kebab-case, with conventional exceptions + +- Status: accepted +- Date: 2026-09-11 + +## Context + +`docs/` carried three naming forms at once: UPPER-KEBAB (`PLUGIN-PHILOSOPHY.md`, +`MIGRATION-PLAYBOOK.md`, `CATALOG.md`, eleven more at the root), lower-kebab (every +`docs/conventions/*/README.md` neighbour, every ADR, every spec), and the conventional uppercase +names (`README.md`, `CHANGELOG.md`). Every citation had to remember which spelling one file used, +and the thirteen uppercase root files were the most cited: six absolute GitHub URLs in plugin +bodies, fifty-four plugin `setup` skills, two `.claude/rules` files, the top-level `README.md`, +three generators and one validator, and hundreds of relative links. + +Two of the thirteen were a URL interface. ADR 0018 has every plugin cite `docs/` doctrine by +absolute raw URL, so `docs/PLUGIN-PHILOSOPHY.md` and `docs/MIGRATION-PLAYBOOK.md` were addresses +that installed plugin copies fetch at run time, and renaming them is a breaking change for any copy +that has not been updated. + +No rule stated which form a new file should take, and nothing checked. + +## Decision + +**Every file under `docs/` is named in lower-kebab-case.** A basename matches +`^[a-z0-9]+([.-][a-z0-9]+)*\.[a-z0-9]+$`: lowercase letters, digits, single hyphens, a +non-empty lowercase extension, dotted stems and multi-part extensions allowed +(`v1.2.schema.json`), and never an empty or trailing segment (`foo..md`, `foo.md.`). + +**Three exemptions, and only these.** `README.md`, `CHANGELOG.md`, and `INDEX.md` anywhere under +`docs/`, the conventional uppercase names forges and tooling look for by exact spelling (`INDEX.md` +is the topic-docs convention's reserved index name). Everything under `docs/topics/`, the +branch-only contract slice whose file names belong to the topic-docs convention and are pruned +before merge. Code files by extension (`py`, `sh`, `mjs`, `js`, `ps1`), whose casing is the +language's convention. + +**The thirteen root files are renamed in one hard cutover, with no tombstones.** No file is left +at an old uppercase path. Every current-surface citation is repointed in the same pull request, +and every plugin whose body cites a renamed file takes a patch bump with a release entry, so +installed copies receive the corrected citations through the normal update path. + +**The historical record is left as written, by tier.** Current surfaces (skills, rules, READMEs, +conventions, generators, the six URL sites) change in every form, bare stems included. ADRs, specs, +and upstream notes change only in markdown links and backtick paths, so the links resolve while the +narrative stays what it was. Plugin `CHANGELOG.md` released entries do not change, except one real +markdown link, corrected under the plugin's own new release entry, which names the correction. + +**Enforcement is a checker with a co-located test.** `scripts/check-docs-naming.sh --check` +walks `git ls-files docs/`, applies the rule and the exemptions, and independently fails any two +tracked paths under `docs/` that differ only by case. It runs in the `lint` job as an advisory +step fed to the `ci-status` aggregate, beside the sibling gates. This record is the owner +document a reader consults; a path-scoped `.claude/rules/` file that restates it for `docs/**` +is not added while `main` carries the unhobble bare baseline recorded under `.claude/unhobble/`, +whose method strips pointer rules that have an owner document and a deterministic oracle and +restores a rule only when the stumble ledger defends it. The readd phase recreates such a rule +from this record if the ledger earns it. + +**Duplicate ADR numbers stay.** `0018`, `0025`, and `0028` each name two records. This record takes +the next free number and renumbers nothing; a uniqueness gate is a separate change. + +## Evidence + +**Three published style guides mandate lowercase-hyphenated file names and none prefers +uppercase.** The Google developer documentation style guide's filenames page requires lowercase +letters with hyphens between words. The GitLab documentation style guide requires lowercase +filenames with dashes. Microsoft Learn's contributor guide requires lowercase, hyphen-separated +names for markdown and media. Every naming rule this repository already writes down for its own +files (skill directories, convention directories, ADR filenames, script names) is kebab-case; the +thirteen uppercase files were the outliers, not the rule. + +**Tombstones cannot coexist with their lowercase twins.** Microsoft Learn's Azure Repos page on +case sensitivity states that when a repository holds two files whose names differ only by case, +checking out both on a case-insensitive file system results in the second overwriting the first. +Two of this repository's CI jobs check out the tree on `windows-2025`, and contributors work on +macOS. A compatibility file at `docs/PLUGIN-PHILOSOPHY.md` beside `docs/plugin-philosophy.md` +would therefore corrupt every such checkout, and a raw-URL tombstone has to sit at exactly the old +path to serve its purpose. Hard cutover was the only shape that keeps the tree valid everywhere. + +**The repository's own posture for a breaking body change is a version bump.** Twelve of the +twelve most recent commits that edited a plugin body bumped that plugin and wrote a changelog +entry, and the plugin cache is version-keyed, so an unbumped edit never reaches an installed copy. +The changelog-parity discipline sanctions a released-entry edit only when the pull request body +and the plugin's new release entry both name it, which is why the one released-entry link +correction is declared in both places. + +**`git mv` handles the case-only rename on every platform.** Git's `builtin/mv.c` renames through +the index, so a rename that differs only by case commits correctly from a case-insensitive +checkout as well; no two-step rename through a temporary name was needed. + +**A path-scoped rule cannot enforce a naming rule alone.** Rules under `.claude/rules/` with a +`paths:` frontmatter load when a covered file is read, never when one is created, so a new +`docs/NEW-FILE.md` is written without the rule ever entering context. The checker is the gate; the +rule is the explanation a reader finds when they open a covered file. + +## Consequences + +**A 404 window for stale installed copies.** An installed plugin whose body still cites +`docs/PLUGIN-PHILOSOPHY.md` or `docs/MIGRATION-PLAYBOOK.md` by absolute URL fetches a path that +no longer exists until that plugin is updated to the bumped version. The window closes per plugin +on update and there is no redirect; the raw content host serves none, and a tombstone is ruled out +above. + +**Future edits that cite a retired path get an advisory notice.** The `guardrails` plugin's +`stale-path-verify` hook flags a write that names a path no longer in the tree, so a body edit +pasted from an old copy surfaces the uppercase path at write time rather than at review. + +**Every future `docs/` file is named without a lookup.** The rule has one form and three listed +exemptions, and the checker reports the offending path and the rule in one line. + +**Historical records read slightly differently from the tree.** An ADR or spec that names a +doctrine file by bare stem in its narrative still says `PLUGIN-PHILOSOPHY`; the link beside it +resolves. A reader following the narrative alone resolves the name by case-folding, which is the +cost accepted for leaving accepted records unedited. + +**The reference sweep is not reusable as written.** The sed maps and the tier boundary were +specific to these thirteen files. A reusable naming-consistency skill is a separate change with its +own evals and listing budget. diff --git a/docs/architecture/landscape.json b/docs/architecture/landscape.json index 48e472ea46..a44eeb7c6c 100644 --- a/docs/architecture/landscape.json +++ b/docs/architecture/landscape.json @@ -15,7 +15,7 @@ {"from":"claude-code-plugins","to":"JuliusBrussee/caveman","type":"cites","relation":"external","count":1,"files":["plugins/adhd/README.md"]}, {"from":"claude-code-plugins","to":"Satsuoni/DeDRM_tools","type":"cites","relation":"external","count":5,"files":["plugins/kindle-dedrm/skills/manage/SKILL.md","plugins/kindle-dedrm/skills/manage/reference/sources.md","plugins/kindle-dedrm/skills/manage/reference/versions.md","plugins/kindle-dedrm/skills/manage/reference/workflow.md"]}, {"from":"claude-code-plugins","to":"SonarSource/eslint-plugin-sonarjs","type":"cites","relation":"external","count":2,"files":["plugins/code-metrics/reference/collectors.md","plugins/code-metrics/scripts/collectors/sonarjs.py"]}, - {"from":"claude-code-plugins","to":"anthropics/claude-code","type":"cites","relation":"external","count":37,"files":["docs/MIGRATION-PLAYBOOK.md","docs/PLUGIN-PHILOSOPHY.md","docs/conventions/hook-config-delivery/README.md","docs/conventions/permission-rule-hygiene/README.md","docs/conventions/topic-docs/README.md"]}, + {"from":"claude-code-plugins","to":"anthropics/claude-code","type":"cites","relation":"external","count":37,"files":["docs/conventions/hook-config-delivery/README.md","docs/conventions/permission-rule-hygiene/README.md","docs/conventions/topic-docs/README.md","docs/migration-playbook.md","docs/plugin-philosophy.md"]}, {"from":"claude-code-plugins","to":"anthropics/claude-code-action","type":"cites","relation":"external","count":1,"files":["plugins/improvement/README.md"]}, {"from":"claude-code-plugins","to":"anthropics/claude-plugins-official","type":"cites","relation":"external","count":1,"files":["plugins/playgrounds/README.md"]}, {"from":"claude-code-plugins","to":"anthropics/skills","type":"cites","relation":"external","count":3,"files":["plugins/docs-hygiene/skills/audit-progressive-disclosure/SKILL.md","plugins/playbooks/skills/skill-authoring/reference/authoring-guidance.md","plugins/skill-quality/scripts/check-skill.sh"]}, @@ -24,7 +24,7 @@ {"from":"claude-code-plugins","to":"bitinn/node-fetch","type":"cites","relation":"external","count":1,"files":["plugins/miro/dist/index.min.js"]}, {"from":"claude-code-plugins","to":"bnjbvr/cargo-machete","type":"cites","relation":"external","count":2,"files":["docs/specs/dead-code-detector-landscape.md"]}, {"from":"claude-code-plugins","to":"boyter/scc","type":"cites","relation":"external","count":6,"files":["plugins/code-metrics/README.md","plugins/code-metrics/reference/collectors.md","plugins/code-metrics/scripts/collectors/scc.py","plugins/code-tidying/skills/dissolve-comments/reference/tooling.md"]}, - {"from":"claude-code-plugins","to":"cli/cli","type":"cites","relation":"external","count":1,"files":["docs/CLOUD-FLEET-SETUP.md"]}, + {"from":"claude-code-plugins","to":"cli/cli","type":"cites","relation":"external","count":1,"files":["docs/cloud-fleet-setup.md"]}, {"from":"claude-code-plugins","to":"crate-ci/typos","type":"cites","relation":"external","count":9,"files":[".claude/cloud-bootstrap.sh","_typos.toml","plugins/typos-format/README.md","plugins/typos-format/hooks/typos-format.sh","plugins/typos-format/skills/setup/SKILL.md"]}, {"from":"claude-code-plugins","to":"cursor/plugins","type":"cites","relation":"external","count":5,"files":["docs/upstream/cursor-pstack.md","plugins/ai-slop/CHANGELOG.md","plugins/ai-slop/README.md","plugins/ai-slop/skills/audit/reference/catalog.md","plugins/ai-slop/skills/audit/reference/rewrite-guide.md"]}, {"from":"claude-code-plugins","to":"dandavison/delta","type":"cites","relation":"external","count":1,"files":["docs/adr/0031-name-the-worktree-root-git-config-key-as-a-capability-section.md"]}, @@ -49,14 +49,14 @@ {"from":"claude-code-plugins","to":"mattpocock/skills","type":"cites","relation":"external","count":5,"files":["docs/upstream/aihero-course.md","docs/upstream/aihero-shipping-course.md","docs/upstream/mattpocock-skills.md","plugins/wizard/CHANGELOG.md"]}, {"from":"claude-code-plugins","to":"melodic-software/ci-workflows","type":"cites","relation":"internal","count":145,"files":[".claude/source-control.md",".github/actionlint.yaml",".github/dependabot.yml",".github/standards/runner-policy/policy.json",".github/standards/runner-policy/runner-policy.mjs"]}, {"from":"claude-code-plugins","to":"melodic-software/claude-code-plugins-ci","type":"cites","relation":"internal","count":1,"files":["package.json"]}, - {"from":"claude-code-plugins","to":"melodic-software/dotfiles","type":"cites","relation":"internal","count":4,"files":["docs/CI-RUNNER-ROUTING.md","docs/adr/0004-rightsize-instruction-surfaces-by-incumbent-first-arbitration.md","plugins/machine-health/CHANGELOG.md","plugins/source-control/CHANGELOG.md"]}, - {"from":"claude-code-plugins","to":"melodic-software/github-iac","type":"cites","relation":"internal","count":18,"files":[".github/actionlint.yaml",".github/dependabot.yml",".github/workflows/ci.yml",".github/workflows/silent-revert-canary.yml","docs/CI-RUNNER-ROUTING.md"]}, + {"from":"claude-code-plugins","to":"melodic-software/dotfiles","type":"cites","relation":"internal","count":4,"files":["docs/adr/0004-rightsize-instruction-surfaces-by-incumbent-first-arbitration.md","docs/ci-runner-routing.md","plugins/machine-health/CHANGELOG.md","plugins/source-control/CHANGELOG.md"]}, + {"from":"claude-code-plugins","to":"melodic-software/github-iac","type":"cites","relation":"internal","count":18,"files":[".github/actionlint.yaml",".github/dependabot.yml",".github/workflows/ci.yml",".github/workflows/silent-revert-canary.yml","docs/adr/0002-default-on-ai-review-advisory-with-earned-promotion.md"]}, {"from":"claude-code-plugins","to":"melodic-software/knowledge-corpus","type":"cites","relation":"internal","count":2,"files":["docs/adr/0022-consume-the-knowledge-corpus-from-a-separate-repository.md","docs/knowledge-integration-design.md"]}, - {"from":"claude-code-plugins","to":"melodic-software/medley","type":"cites","relation":"internal","count":17,"files":["docs/MIGRATION-PLAYBOOK.md","docs/adr/0020-defer-three-medley-surfaces-with-explicit-recheck-triggers.md","docs/ai-briefing-design.md","docs/conventions/ecosystem-commands/CHANGELOG.md","docs/hook-migration-audit.md"]}, + {"from":"claude-code-plugins","to":"melodic-software/medley","type":"cites","relation":"internal","count":17,"files":["docs/adr/0020-defer-three-medley-surfaces-with-explicit-recheck-triggers.md","docs/ai-briefing-design.md","docs/conventions/ecosystem-commands/CHANGELOG.md","docs/hook-migration-audit.md","docs/migration-playbook.md"]}, {"from":"claude-code-plugins","to":"melodic-software/miro-mcp","type":"cites","relation":"internal","count":1,"files":["plugins/miro/package.json"]}, {"from":"claude-code-plugins","to":"melodic-software/provisioning","type":"cites","relation":"internal","count":5,"files":["plugins/claude-ops/skills/observability/context/operator-setup-collector-daemon.md","plugins/claude-ops/skills/observability/context/operator-setup.md","plugins/claude-ops/skills/observability/context/otel-pipeline.md"]}, {"from":"claude-code-plugins","to":"melodic-software/runner-policy-runtime","type":"cites","relation":"internal","count":1,"files":[".github/standards/runner-policy/package.json"]}, - {"from":"claude-code-plugins","to":"melodic-software/standards","type":"cites","relation":"internal","count":53,"files":[".claude/rules/pr-body-contract.md",".github/workflows/managed-files-guard.yml",".markdownlint-cli2.jsonc","docs/CI-RUNNER-ROUTING.md","docs/CLOUD-FLEET-SETUP.md"]}, + {"from":"claude-code-plugins","to":"melodic-software/standards","type":"cites","relation":"internal","count":53,"files":[".claude/rules/pr-body-contract.md",".github/workflows/managed-files-guard.yml",".markdownlint-cli2.jsonc","docs/adr/0003-verification-guards-earn-default-on-by-measured-precision.md","docs/adr/0005-bound-instruction-surface-work-by-question-not-population.md"]}, {"from":"claude-code-plugins","to":"mibk/dupl","type":"cites","relation":"external","count":4,"files":["plugins/code-metrics/README.md","plugins/code-metrics/reference/collectors.md","plugins/code-metrics/scripts/collectors/dupl.py"]}, {"from":"claude-code-plugins","to":"microsoft/TypeScript","type":"cites","relation":"external","count":2,"files":["docs/specs/dead-code-lsp-viability.md"]}, {"from":"claude-code-plugins","to":"microsoft/mcp","type":"cites","relation":"external","count":1,"files":["plugins/claude-ops/skills/known-issues/context/action-scan.md"]}, diff --git a/docs/CATALOG-TAXONOMY.md b/docs/catalog-taxonomy.md similarity index 97% rename from docs/CATALOG-TAXONOMY.md rename to docs/catalog-taxonomy.md index 8d94e21287..3e1ef803e6 100644 --- a/docs/CATALOG-TAXONOMY.md +++ b/docs/catalog-taxonomy.md @@ -4,7 +4,7 @@ This document is the single owner of the marketplace's category vocabulary. Each `.claude-plugin/marketplace.json` carries one `category` value drawn from the controlled set below, and the generated catalog groups plugins by it. Three consumers of this vocabulary conform to this document and cite it, never restating its definitions: the marketplace file, the catalog generator, and -`docs/CATALOG.md`. +`docs/catalog.md`. Category is display-and-grouping metadata only. It never appears in an install identifier (`plugin-name@marketplace`) or a skill invocation (`/plugin-name:skill`). Physical layout stays flat @@ -97,7 +97,7 @@ Plugin-scoped (owned by the named plugin's README): The human-browsable catalog is generated, not hand-maintained. `marketplace.json` is the single source of truth for each plugin's `category` and the ordering key; `plugin.json` owns each description. The generator -emits the grouped catalog section between markers in `docs/CATALOG.md`, and a CI check fails when the committed +emits the grouped catalog section between markers in `docs/catalog.md`, and a CI check fails when the committed section drifts from what the manifests would produce. This retires hand-maintained catalog duplication and keeps the grouped view and the manifests from diverging. diff --git a/docs/CATALOG.md b/docs/catalog.md similarity index 99% rename from docs/CATALOG.md rename to docs/catalog.md index 8328e60d8d..2cd990c0dd 100644 --- a/docs/CATALOG.md +++ b/docs/catalog.md @@ -2,7 +2,7 @@ The generated per-category plugin catalog: the block between the markers below is generated from the plugin manifests and kept in sync by CI. Never hand-edit it; the category vocabulary is owned by -[`docs/CATALOG-TAXONOMY.md`](CATALOG-TAXONOMY.md). +[`docs/catalog-taxonomy.md`](catalog-taxonomy.md). diff --git a/docs/CI-RUNNER-ROUTING.md b/docs/ci-runner-routing.md similarity index 100% rename from docs/CI-RUNNER-ROUTING.md rename to docs/ci-runner-routing.md diff --git a/docs/CLOUD-FLEET-SETUP.md b/docs/cloud-fleet-setup.md similarity index 98% rename from docs/CLOUD-FLEET-SETUP.md rename to docs/cloud-fleet-setup.md index e33fb8f3b3..fe2de1f1e5 100644 --- a/docs/CLOUD-FLEET-SETUP.md +++ b/docs/cloud-fleet-setup.md @@ -1,6 +1,6 @@ # Cloud fleet setup: one shared environment for every melodic-software repo -The goal-oriented companion to [CLOUD-SESSIONS.md](CLOUD-SESSIONS.md): that doc explains the +The goal-oriented companion to [cloud-sessions.md](cloud-sessions.md): that doc explains the mechanics and this repo's own setup; this one gets **the whole fleet** runnable in Claude Code cloud sessions (web, `claude --cloud`, mobile, desktop, and routines) with warm-boot startup. Account context this plan is built for: a personal (Max) claude.ai account. Organization-shared @@ -10,7 +10,7 @@ Basis and freshness: the toolchain inventory below was derived from shallow clon fleet repo's default branch on 2026-08-13; bootstrap adoption was re-verified on 2026-08-16 by reading each repo's `.claude/` contents and `settings.json` at `origin/main` (`gh api repos/melodic-software//contents/.claude`); platform claims rest on the rung-1 doc fetches -recorded in [CLOUD-SESSIONS.md](CLOUD-SESSIONS.md); the environment itself was verified live on +recorded in [cloud-sessions.md](cloud-sessions.md); the environment itself was verified live on 2026-08-14 from a cloud session inside it. Results are in [#2654](https://github.com/melodic-software/claude-code-plugins/issues/2654), folded in below. Recheck trigger, per the [upstream-drift convention](conventions/upstream-drift/README.md): a @@ -92,7 +92,7 @@ from a session started on a `kyle-sexton` repo if they ever matter). > (`.claude/cloud-bootstrap.sh`) and two callers: the environment's cache build pre-launch, and > the SessionStart hook per session. The standards `cloud-environment` component invokes only > that path, with no legacy fallback by decision, and pre-launch execution is what makes -> marketplace plugins load at turn one (see [CLOUD-SESSIONS.md](CLOUD-SESSIONS.md)). +> marketplace plugins load at turn one (see [cloud-sessions.md](cloud-sessions.md)). Environments are created only from the environment selector at [claude.ai/code](https://claude.ai/code) (cloud icon above the message box). There is no API. @@ -235,7 +235,7 @@ webhooks). Create via `/schedule` in a local CLI session or at Starters matched to this fleet, cheapest first: 1. **Weekly upstream-drift re-verification** (this repo; schedule, weekly): re-fetch the pages - behind `docs/OFFICIAL-DOCS.md` and `docs/CLOUD-SESSIONS.md` per the upstream-drift + behind `docs/official-docs.md` and `docs/cloud-sessions.md` per the upstream-drift convention's fetch route, and open a PR when a stamp no longer matches. Connectors: none. 2. **Nightly backlog groom** (this repo; schedule, weeknights): triage new issues, label, link PRs per the repo's conventions. Connectors: none (built-in GitHub tools suffice). @@ -284,7 +284,7 @@ session on this repo in the new environment and ask Claude to verify: medley): make the session's *first* message a plugin slash command and confirm it resolves. `/plugin` is not available in cloud sessions, and a Bash-side `claude plugin list` proves only disk state, not that the session loaded anything (see the - same-session limit in [CLOUD-SESSIONS.md](CLOUD-SESSIONS.md)). + same-session limit in [cloud-sessions.md](cloud-sessions.md)). 5. If the .NET setup-script step failed (`dotnet` missing), confirm the environment's network access is **All** per [Step 1](#step-1-the-shared-environment-claudeai-ui-one-time), since a narrower level can `403`-block the installer's redirect chain (#2654 Blocker 1), which All @@ -308,7 +308,7 @@ session on this repo in the new environment and ask Claude to verify: failed deterministically; verified against PyPI's published digests, a coverage gap rather than tampering). A 2026-08-15 session then confirmed the wiring end to end, with the hook running at startup and installing all 65 plugins, and established the follow-on limit now recorded in - `docs/CLOUD-SESSIONS.md` §"Plugins in sessions on this repo": hook-time installs land on disk + `docs/cloud-sessions.md` §"Plugins in sessions on this repo": hook-time installs land on disk but are never loaded by the session that ran them (the registry is read before the hook), so plugins go live at turn one only when the cache build runs the bootstrap pre-launch, which the standards `cloud-environment` component does. Remaining #2654 actions are environment-side, diff --git a/docs/CLOUD-SESSIONS.md b/docs/cloud-sessions.md similarity index 99% rename from docs/CLOUD-SESSIONS.md rename to docs/cloud-sessions.md index 0d6aaae941..7fd085c807 100644 --- a/docs/CLOUD-SESSIONS.md +++ b/docs/cloud-sessions.md @@ -145,7 +145,7 @@ plus the cost model of Start with one Default. Environments are account-scoped and repo-agnostic, so a single environment serves every repository. This fleet runs its Default at **All** network access (operator decision 2026-08-22; rationale in -[CLOUD-FLEET-SETUP.md](CLOUD-FLEET-SETUP.md#step-1-the-shared-environment-claudeai-ui-one-time)). +[cloud-fleet-setup.md](cloud-fleet-setup.md#step-1-the-shared-environment-claudeai-ui-one-time)). Add a second, named environment only when a class of work needs something incompatible or heavy enough to isolate: a big SDK whose cache churn you want contained, or an account that handles sensitive material and therefore has to run narrower than All, on a @@ -298,7 +298,7 @@ catalog on, and the cloud bootstrap installs from the two together (see guarded one-liner in the [setup-script lever above](#setup-script-vs-sessionstart-hook-decision-criteria), implemented fleet-wide by the standards `cloud-environment` component that - [CLOUD-FLEET-SETUP.md](CLOUD-FLEET-SETUP.md)'s step-1 stub fetches. Whether the cached + [cloud-fleet-setup.md](cloud-fleet-setup.md)'s step-1 stub fetches. Whether the cached snapshot's `~/.claude` actually reaches sessions is undocumented. After adding the line, rebuild the cache (edit saves the script) and verify with a fresh session whose *first* message is a plugin slash command. @@ -323,7 +323,7 @@ catalog on, and the cloud bootstrap installs from the two together (see explicitly, for the benefit of the *next* process start, per the timing bullet above. It never calls `claude plugin marketplace remove`, which deletes the marketplace's entry from `.claude/settings.json` and would have the script mutate tracked config. -- On resume it also repairs [same-version commit drift](MIGRATION-PLAYBOOK.md): because a +- On resume it also repairs [same-version commit drift](migration-playbook.md): because a directory-source cache is keyed by the semver in `plugin.json` rather than the commit, a presence check alone would keep serving whichever commit installed first. The script compares the `gitCommitSha` recorded at install time against `HEAD` and forces the documented diff --git a/docs/conventions/authoring-formats/CHANGELOG.md b/docs/conventions/authoring-formats/CHANGELOG.md index d22fc61b3f..d263daa5c9 100644 --- a/docs/conventions/authoring-formats/CHANGELOG.md +++ b/docs/conventions/authoring-formats/CHANGELOG.md @@ -48,11 +48,11 @@ consuming skills restate. - **Consumer surface in convention-doc expression**: `/authoring-formats/README.md`, one layer (team, via the pointer line), no overlay channel, unknown keys inert. Neither key is a plugin-manifest option: a team-shared format choice has no per-operator axis, per - `docs/PLUGIN-PHILOSOPHY.md` § Configuration ownership and scope. + `docs/plugin-philosophy.md` § Configuration ownership and scope. - **Resolution ladder** stated in a copyable block: anchor, home resolution, read, layer order, defaults, soft degrade, provenance reporting. A consuming skill restates it rather than citing this file, because an installed plugin never sees this repository's `docs/conventions/`. -- **Registered** in the convention registry in `docs/PLUGIN-PHILOSOPHY.md` and in the +- **Registered** in the convention registry in `docs/plugin-philosophy.md` and in the [config-cascade](../config-cascade/README.md) Implementers table. No skill reads either key on `main` at this release. The consuming changes are separate slices, diff --git a/docs/conventions/commit-convention/README.md b/docs/conventions/commit-convention/README.md index 687792f87d..f282a2cb4d 100644 --- a/docs/conventions/commit-convention/README.md +++ b/docs/conventions/commit-convention/README.md @@ -4,7 +4,7 @@ Owner doc for the machine-readable **enforcement** read of a consumer's commit-s PR-title convention. This concern is consumed by **more than one plugin**: `source-control` authors and drafts against the convention, and `guardrails` gates against it. Its ownership lives here at marketplace level, not inside either plugin, per -[`docs/MIGRATION-PLAYBOOK.md`](../../MIGRATION-PLAYBOOK.md) "concern-named config consumed by >1 +[`docs/migration-playbook.md`](../../migration-playbook.md) "concern-named config consumed by >1 plugin". A guardrails hook cites **this** doc, never `plugins/source-control/reference/`. ## Two reads of one file @@ -151,7 +151,7 @@ purposes without it. - **Unresolved = no enforcement.** No team-tracked pattern (or a non-enforceable one) → the gate does nothing. A gate never blocks against the bundled Conventional Commits default: CC is not a - lane-1-eligible default (see [`docs/PLUGIN-PHILOSOPHY.md`](../../PLUGIN-PHILOSOPHY.md) "Two-lane + lane-1-eligible default (see [`docs/plugin-philosophy.md`](../../plugin-philosophy.md) "Two-lane convention posture"), so gating an un-opted-in repo against it would impose a convention the consumer never chose. **Enforcement strength = strength of explicit team config.** - **Policy-floor via team-only reads.** Enforcement reads the **tracked** team layer only; the diff --git a/docs/conventions/config-cascade/CHANGELOG.md b/docs/conventions/config-cascade/CHANGELOG.md index 65cf46976d..7f927926ef 100644 --- a/docs/conventions/config-cascade/CHANGELOG.md +++ b/docs/conventions/config-cascade/CHANGELOG.md @@ -111,7 +111,7 @@ every surface; the change carves out one surface class that may invert precedenc ## [1.0] - 2026-07-20 -Initial published contract, extracted from the tracked-rich-config section in `docs/MIGRATION-PLAYBOOK.md` +Initial published contract, extracted from the tracked-rich-config section in `docs/migration-playbook.md` so fleet audits have a Convention registry row to check. No rule changed in the extraction. - Layer set and precedence: user-global → team → local overlay, resolved in that order. diff --git a/docs/conventions/config-cascade/README.md b/docs/conventions/config-cascade/README.md index b69e4ee2e0..3db65468c2 100644 --- a/docs/conventions/config-cascade/README.md +++ b/docs/conventions/config-cascade/README.md @@ -181,7 +181,7 @@ once setup has discovered which file carries the region. **Dual-read deprecation window.** A migrated skill that finds the retired dedicated file present treats it as WARN **and** reads it as authority (at minimum as inference evidence) until the -consumer cleans it through the retirement mechanism (`docs/MIGRATION-PLAYBOOK.md` +consumer cleans it through the retirement mechanism (`docs/migration-playbook.md` § Retired conventions). This covers a consumer who updated the plugin without re-running setup, and is the one sanctioned dual-read: declared per surface by its retirement record, WARN-visible on every run, never silent. The window closes for a consumer when that record's cleanup runs, and for diff --git a/docs/conventions/detector-findings/CHANGELOG.md b/docs/conventions/detector-findings/CHANGELOG.md index 1cde6d577f..b87a265984 100644 --- a/docs/conventions/detector-findings/CHANGELOG.md +++ b/docs/conventions/detector-findings/CHANGELOG.md @@ -482,7 +482,7 @@ what a reader could not yet rely on. Initial published contract, a deliberate stub, per [#2679](https://github.com/melodic-software/claude-code-plugins/issues/2679). It lands before the -first detector pilot because `PLUGIN-PHILOSOPHY.md`'s registry rule sets a deadline ("before a second +first detector pilot because `plugin-philosophy.md`'s registry rule sets a deadline ("before a second plugin adopts it"), and the pilot is that second adopter. Depth trails the pilot, which is what produces the evidence to harden against. @@ -517,5 +517,5 @@ produces the evidence to harden against. - Enforceability classified; all mechanical enforcement deferred with event triggers (first detector on `main`; pilot completion or a second adopter). Adopters table ships **empty**: `review:fanout` is the reference writer, not an adopter, and sits on the other side of this doc's boundary. -- Convention registry row added in `PLUGIN-PHILOSOPHY.md`; `review:fanout`'s writer contract gains a +- Convention registry row added in `plugin-philosophy.md`; `review:fanout`'s writer contract gains a pointer to this doc. diff --git a/docs/conventions/detector-findings/README.md b/docs/conventions/detector-findings/README.md index 14f08da2d2..a984a178d3 100644 --- a/docs/conventions/detector-findings/README.md +++ b/docs/conventions/detector-findings/README.md @@ -33,8 +33,8 @@ The shape is owned by What this doc owns is everything the shape alone does not settle: which fields a non-fanout producer must compute for itself, what coexistence between producers means, and where the boundary sits. -It was published as a stub ahead of its depth, on `PLUGIN-PHILOSOPHY.md` -[Convention registry](../../PLUGIN-PHILOSOPHY.md#convention-registry): "A new cross-plugin +It was published as a stub ahead of its depth, on `plugin-philosophy.md` +[Convention registry](../../plugin-philosophy.md#convention-registry): "A new cross-plugin convention lands in an owner doc **before a second plugin adopts it**". That is a deadline rather than a licence to author late. The depth below is the first detector pilot's evidence, and the crosswalk is written from it: a rule whose tier cannot be argued from `severity.md`'s test is not @@ -661,4 +661,4 @@ adopter row is a minor bump; docs-only clarification is a patch. - [`scripts/check-cross-plugin-source-drift.sh`](../../../scripts/check-cross-plugin-source-drift.sh): the shared-source cluster mechanism the emitter decision is measured against, and the gate its revisit trigger fires at. - `melodic-software/standards` `conventions/engineering/enforceability-tiers.md`: tier vocabulary and routing rule. - [`liveness-assertion`](../liveness-assertion/README.md): the fail-loud-or-agent-readable contract a detector satisfies by persisting. -- [`PLUGIN-PHILOSOPHY` Convention registry](../../PLUGIN-PHILOSOPHY.md#convention-registry): one owner doc per shared concern, and the before-a-second-adopter deadline this stub answers. +- [`plugin-philosophy` Convention registry](../../plugin-philosophy.md#convention-registry): one owner doc per shared concern, and the before-a-second-adopter deadline this stub answers. diff --git a/docs/conventions/ecosystem-commands/README.md b/docs/conventions/ecosystem-commands/README.md index a15d0d6603..1ebce3e0f7 100644 --- a/docs/conventions/ecosystem-commands/README.md +++ b/docs/conventions/ecosystem-commands/README.md @@ -74,7 +74,7 @@ or `.claude//**`). This contract intentionally names the folder by **con General rule this instance establishes: **when a tracked-config concern is consumed by more than one plugin, name the folder by concern and record the contract in `docs/conventions/`**, per -`docs/MIGRATION-PLAYBOOK.md` "Extensibility contract v2.1". +`docs/migration-playbook.md` "Extensibility contract v2.1". The directory is `.claude/`-scoped but not Claude-walled: it is ordinary tracked YAML any agent or script can read. Agent-agnostic discovery is satisfied by the consuming repo citing the path from its @@ -84,7 +84,7 @@ by reference. ## Resolution ladder (plugin behavior) Plugins resolve the command surface per the convention-resolution ladder -(`docs/MIGRATION-PLAYBOOK.md` "Convention-resolution ladder"): +(`docs/migration-playbook.md` "Convention-resolution ladder"): 1. `.claude/ecosystems/.yaml` present → use it. It is authoritative. 2. Absent → infer from the repo's build files (solution files, `pyproject.toml`, `package.json`, …) @@ -171,4 +171,4 @@ change. The demotion path is designed in. The schema carries the contract version (`CHANGELOG.md`). Additive schema changes bump minor; breaking changes bump major, get a changelog entry with a migration note, and re-trigger the consuming plugins' version bumps (the plugin `version` is the only update-delivery vehicle, per -`docs/MIGRATION-PLAYBOOK.md` "Version pinning and update delivery"). +`docs/migration-playbook.md` "Version pinning and update delivery"). diff --git a/docs/conventions/hook-config-delivery/README.md b/docs/conventions/hook-config-delivery/README.md index a26056b274..12f76b57fe 100644 --- a/docs/conventions/hook-config-delivery/README.md +++ b/docs/conventions/hook-config-delivery/README.md @@ -20,7 +20,7 @@ of **harness-prompted `userConfig` values**, the options a plugin declares in `p Claude Code prompts for at enable time. They are different inputs with different trust properties: a cascade layer is repo- or user-authored file content; a `userConfig` value is harness-mediated and stored in scopes a repo cannot write. Whether a given knob should be `userConfig` or a tracked -cascade surface is a design call owned by the [plugin philosophy](../../PLUGIN-PHILOSOPHY.md); once +cascade surface is a design call owned by the [plugin philosophy](../../plugin-philosophy.md); once it is `userConfig`, this doc owns its route to hook logic. Which keys exist and what they mean stay with each plugin's own docs. @@ -141,7 +141,7 @@ unproven. A ratified D adoption (after the Open-gaps probe) is recorded in ## Adopters Conformance is tracked as it exists on `main`, per the -[convention registry](../../PLUGIN-PHILOSOPHY.md#convention-registry) discipline. +[convention registry](../../plugin-philosophy.md#convention-registry) discipline. | Surface | Channel | Status | |---|---|---| diff --git a/docs/conventions/hook-input-rewriting/README.md b/docs/conventions/hook-input-rewriting/README.md index ba9696b767..21e4236817 100644 --- a/docs/conventions/hook-input-rewriting/README.md +++ b/docs/conventions/hook-input-rewriting/README.md @@ -1,7 +1,7 @@ # Hook input rewriting: deny or ask, never a silent rewrite Owner doc for what a `PreToolUse` hook may do to a tool call it disagrees with. The -[plugin philosophy](../../PLUGIN-PHILOSOPHY.md) owns the posture rule: an advisory hook is a nudge, +[plugin philosophy](../../plugin-philosophy.md) owns the posture rule: an advisory hook is a nudge, a guard must not block legitimate work. [Hook precision](../hook-precision/README.md) owns what a hook matches. This doc owns the one question those two leave open: when a hook can see both that a call is wrong and what the right call would be, is it allowed to substitute the right one? diff --git a/docs/conventions/hook-observability/README.md b/docs/conventions/hook-observability/README.md index 118e80f2e7..ca0367f549 100644 --- a/docs/conventions/hook-observability/README.md +++ b/docs/conventions/hook-observability/README.md @@ -2,7 +2,7 @@ Owner doc for the three observability surfaces every fleet hook declares or emits: a during-run status label, a user-visible notice when a runtime prerequisite is missing, and the fleet's -telemetry envelope. The [plugin philosophy](../../PLUGIN-PHILOSOPHY.md) owns the posture rule: +telemetry envelope. The [plugin philosophy](../../plugin-philosophy.md) owns the posture rule: advisory-versus-blocking, fail-open-versus-closed. This doc owns which of the three surfaces a given situation uses and how each is shaped. diff --git a/docs/conventions/hook-precision/README.md b/docs/conventions/hook-precision/README.md index 0b2c638c1e..306bbf39d6 100644 --- a/docs/conventions/hook-precision/README.md +++ b/docs/conventions/hook-precision/README.md @@ -1,7 +1,7 @@ # Hook precision: false-positive discipline for plugin hooks Owner doc for the precision discipline every plugin hook follows so it fires on what it targets and stays -quiet on everything else. The [plugin philosophy](../../PLUGIN-PHILOSOPHY.md) owns the posture rule: an +quiet on everything else. The [plugin philosophy](../../plugin-philosophy.md) owns the posture rule: an advisory hook is a nudge, a guard must not block legitimate work. This doc owns the *precision shape* that keeps both true: the recurring ways a hook over-fires, and the discipline that turns each production false positive into a regression test instead of a re-filed issue. diff --git a/docs/conventions/invocation-mode/README.md b/docs/conventions/invocation-mode/README.md index 10d77a421f..74298dc214 100644 --- a/docs/conventions/invocation-mode/README.md +++ b/docs/conventions/invocation-mode/README.md @@ -5,7 +5,7 @@ Owner doc for choosing a skill's **invocation mode**: whether the model may invo (`disable-model-invocation: true`). Consumed by skill authors at design time (`playbooks:skill-authoring`), by the fleet gate (`skill-quality:check`), and by audits grading existing skills. One home per the convention registry -([`docs/PLUGIN-PHILOSOPHY.md`](../../PLUGIN-PHILOSOPHY.md) "Convention registry"); this doc decides, +([`docs/plugin-philosophy.md`](../../plugin-philosophy.md) "Convention registry"); this doc decides, other surfaces point here. Provenance: AI Hero course steering lane 8 @@ -55,7 +55,7 @@ of its cited page no longer matching the bullet re-derives it here): triggering signal is private to the human (e.g. `discipline:wait-what`, where only the human knows comprehension broke), or it enters a persistent session-consuming mode the human should choose deliberately (e.g. `education:teach`). -2. **(ii) Setup skills.** Per the PLUGIN-PHILOSOPHY setup contract ("Setup is explicit and +2. **(ii) Setup skills.** Per the plugin-philosophy setup contract ("Setup is explicit and repeatable"): `setup` skills are named `setup` and carry `disable-model-invocation: true`. 3. **(iii) Maintainer-only skills.** Operate on this marketplace's working tree (vendored-content sync, drift checks); meaningless or harmful for consumers to reach via the model. @@ -160,7 +160,7 @@ Upstream's router pattern, a model-invoked skill whose job is routing the agent skills, is rejected for this fleet: under the model-invoked default, the always-in-context listing already does that job, and this fleet's `true` set is *deliberately* model-invisible, so a router reaching into it would defeat the exception classes. The human-side cognitive-load -problem is answered by `docs/SKILL-CHEAT-SHEET.md` and `claude-ops:inventory`. +problem is answered by `docs/skill-cheat-sheet.md` and `claude-ops:inventory`. **Carve-out:** domain-scoped *composition* routers (`discipline:sweep-all`, whose membership is derived from corrector metadata) are a distinct, admitted pattern; they compose model-invoked skills rather than recovering discoverability for hidden ones. @@ -222,7 +222,7 @@ listing omitting every `true` skill and dropping ~82% of descriptions least-invo the whole reason this skill resolves from the installed catalog instead. The second turns on *naming* versus *reaching*: `show-options` renders a menu and explicitly does not execute what the human picks, and both surfaces the router verdict itself blesses as the answer to the human-side -problem, `docs/SKILL-CHEAT-SHEET.md` and `claude-ops:inventory` (itself `false`), already name the +problem, `docs/skill-cheat-sheet.md` and `claude-ops:inventory` (itself `false`), already name the `true` set to a human from a model-reachable surface. Naming hidden skills to a human is settled practice in this fleet; only the agent invoking them is what the exception classes forbid. Nor is it the composition-router carve-out, which composes model-invoked skills rather than surfacing hidden @@ -287,7 +287,7 @@ in the table above**, and the table's two flips are the only entries that are no ## Cross-references -- PLUGIN-PHILOSOPHY: setup contract (class ii source), Instruction economy (listing-cost +- plugin-philosophy: setup contract (class ii source), Instruction economy (listing-cost doctrine), Convention registry (this doc's row). - `skill-quality:check`: `listing-budget` (measurement) and check 24, the explicit-key criterion (enforcement: FAIL for a marketplace plugin skill, WARN elsewhere; class attribution is diff --git a/docs/conventions/liveness-assertion/CHANGELOG.md b/docs/conventions/liveness-assertion/CHANGELOG.md index 7eaca687fa..64672fdf49 100644 --- a/docs/conventions/liveness-assertion/CHANGELOG.md +++ b/docs/conventions/liveness-assertion/CHANGELOG.md @@ -37,4 +37,4 @@ stays open for enforcement peels). conforming references; #510, #385/#376, #465/#499, #509 as tracked instances. - Enforceability classified; peel 1 defers CI meta-check and engine self-test gates with event triggers. -- Convention registry row added in `PLUGIN-PHILOSOPHY.md`; Prerequisites section gains a pointer. +- Convention registry row added in `plugin-philosophy.md`; Prerequisites section gains a pointer. diff --git a/docs/conventions/liveness-assertion/README.md b/docs/conventions/liveness-assertion/README.md index bf5ef3e6d0..627cb2ea9d 100644 --- a/docs/conventions/liveness-assertion/README.md +++ b/docs/conventions/liveness-assertion/README.md @@ -5,12 +5,12 @@ capability behind it is dead or its findings are invisible**. One contract: a co **fails loud** or **routes its findings into an agent-readable channel**, never both green and silent. "Green-with-hidden-findings" and "healthy-while-dead" are contract violations. -The fleet already states slices of this doctrine in prose, in [`PLUGIN-PHILOSOPHY`](../../PLUGIN-PHILOSOPHY.md) -[Prerequisites and failure behavior](../../PLUGIN-PHILOSOPHY.md#prerequisites-and-failure-behavior) +The fleet already states slices of this doctrine in prose, in [`plugin-philosophy`](../../plugin-philosophy.md) +[Prerequisites and failure behavior](../../plugin-philosophy.md#prerequisites-and-failure-behavior) ("No black boxes: a silently skipped feature is a defect"; "Do not swallow errors or claim success when the promised result was not produced"), and enforces one mechanical slice in CI (`silent-skip-gate` over `plugins/*/hooks/*.sh`). Under the -[convention registry](../../PLUGIN-PHILOSOPHY.md#convention-registry)'s one-owner-per-concern rule, +[convention registry](../../plugin-philosophy.md#convention-registry)'s one-owner-per-concern rule, this doc closes the gap: a cross-surface contract for the **false-green** class that the hook-only gate cannot reach ([melodic-software/claude-code-plugins#532](https://github.com/melodic-software/claude-code-plugins/issues/532)). @@ -93,7 +93,7 @@ this peel publishes the contract only. | Existing surface | How it relates | |---|---| -| [`PLUGIN-PHILOSOPHY` Prerequisites and failure behavior](../../PLUGIN-PHILOSOPHY.md#prerequisites-and-failure-behavior) | Prose doctrine this convention specializes for health/status/advisory/gate surfaces. Prerequisites section remains the entry point for runtime-absence classification; this doc adds the false-green class and surface taxonomy. | +| [`plugin-philosophy` Prerequisites and failure behavior](../../plugin-philosophy.md#prerequisites-and-failure-behavior) | Prose doctrine this convention specializes for health/status/advisory/gate surfaces. Prerequisites section remains the entry point for runtime-absence classification; this doc adds the false-green class and surface taxonomy. | | [`hook-observability`](../hook-observability/README.md) | Owns the three hook output surfaces (`statusMessage`, `systemMessage`, telemetry). Prerequisite-skip visibility is one *hook-shaped* instance of the core contract. | | `silent-skip-gate` (`scripts/check-silent-skips.sh`) | Mechanical enforcement of the hook slice only. Not a stand-in for this convention. | | Hygiene lane aggregator `--self-test` | Conforming counter-example for engine health-check: self-test before trust. | @@ -146,6 +146,6 @@ instance rows is a minor bump; docs-only clarification is a patch. ## External authority -- [`PLUGIN-PHILOSOPHY` Prerequisites and failure behavior](../../PLUGIN-PHILOSOPHY.md#prerequisites-and-failure-behavior): prose doctrine this convention specializes. +- [`plugin-philosophy` Prerequisites and failure behavior](../../plugin-philosophy.md#prerequisites-and-failure-behavior): prose doctrine this convention specializes. - [`hook-observability`](../hook-observability/README.md): hook-shaped visibility surfaces and the `silent-skip-gate` slice. - `melodic-software/standards` `conventions/engineering/enforceability-tiers.md`: tier vocabulary and routing rule. diff --git a/docs/conventions/loop-lane/README.md b/docs/conventions/loop-lane/README.md index 0ab65a5f7a..430f27f73b 100644 --- a/docs/conventions/loop-lane/README.md +++ b/docs/conventions/loop-lane/README.md @@ -16,9 +16,9 @@ mechanic in a self-paced drain loop over a repository's backlog. Three lanes ado Because those live in two different plugins, the topology, escalation contract, capability-tier vocabulary, and loop-layer invariants they share cannot live inside either plugin. A sibling-plugin file import is a defect -([`PLUGIN-PHILOSOPHY.md`](../../PLUGIN-PHILOSOPHY.md#design-boundary)), and a cross-plugin convention +([`plugin-philosophy.md`](../../plugin-philosophy.md#design-boundary)), and a cross-plugin convention lands in an owner doc before the second plugin adopts it -([convention registry](../../PLUGIN-PHILOSOPHY.md#convention-registry)). This is that owner doc. +([convention registry](../../plugin-philosophy.md#convention-registry)). This is that owner doc. **Pointer-not-copy.** Each mechanic below is owned by a plugin or a sibling convention; this doc fixes the *contract* every lane holds to and points at the owner for the *mechanism*. It never diff --git a/docs/conventions/native-references/README.md b/docs/conventions/native-references/README.md index f47d9b7737..14366e46d8 100644 --- a/docs/conventions/native-references/README.md +++ b/docs/conventions/native-references/README.md @@ -19,12 +19,12 @@ This doc owns the phrasing of references **to native surfaces**. It does not own Its three elements are the template this doc specializes; a native surface is not a plugin, which is why the specialization needs its own owner rather than a clause in that doc. - **Whether a reference should exist at all.** That is a verdict, and verdicts live in the - committed overlap store rendered into [`docs/NATIVE-SURFACES.md`](../../NATIVE-SURFACES.md). + committed overlap store rendered into [`docs/native-surfaces.md`](../../native-surfaces.md). This doc governs the words once a verdict says a reference is warranted. - **The stamp discipline on any upstream fact a reference restates.** [`upstream-drift`](../upstream-drift/README.md) owns the four-part record (claim, basis, as-of date, recheck trigger) and the observability bar its triggers must clear. -- **Instruction economy.** [`PLUGIN-PHILOSOPHY`](../../PLUGIN-PHILOSOPHY.md) owns the rule that +- **Instruction economy.** [`plugin-philosophy`](../../plugin-philosophy.md) owns the rule that every always-loaded description is a per-session tax. This doc keeps the phrase to one clause because of that rule; it does not restate it. @@ -173,7 +173,7 @@ Six properties the section keeps: ## Self-containment: shipped plugins never cite the registry -The overlap store and [`docs/NATIVE-SURFACES.md`](../../NATIVE-SURFACES.md) live in this +The overlap store and [`docs/native-surfaces.md`](../../native-surfaces.md) live in this repository. A plugin installed from the marketplace does **not** have them: a citation would be a broken reference at install time, and the reader would be routed to a file that does not exist. diff --git a/docs/conventions/plugin-data-report-keying/CHANGELOG.md b/docs/conventions/plugin-data-report-keying/CHANGELOG.md index 172275af4f..6395e61f03 100644 --- a/docs/conventions/plugin-data-report-keying/CHANGELOG.md +++ b/docs/conventions/plugin-data-report-keying/CHANGELOG.md @@ -46,7 +46,7 @@ added, and no worked example is added or removed. Initial published contract. Written because the hazard was already understood inside the fleet and applied inconsistently *within one plugin*, the signature of a missing rule rather than a per-skill oversight. `docs/conventions/` carried eighteen entries and none governed how a plugin names what it -writes under `${CLAUDE_PLUGIN_DATA}`; the nearest governing text (`docs/MIGRATION-PLAYBOOK.md` seam 4) +writes under `${CLAUDE_PLUGIN_DATA}`; the nearest governing text (`docs/migration-playbook.md` seam 4) scopes *what may live there*, not how it is named. - **Rule 1 [SPEC]**: every write is keyed `//`, with `` = diff --git a/docs/conventions/plugin-data-report-keying/README.md b/docs/conventions/plugin-data-report-keying/README.md index 60d10e3e08..31f06ef607 100644 --- a/docs/conventions/plugin-data-report-keying/README.md +++ b/docs/conventions/plugin-data-report-keying/README.md @@ -5,7 +5,7 @@ Last updated: 2026-09-07 A marketplace-wide contract for **how a plugin names what it writes under `${CLAUDE_PLUGIN_DATA}`**: the key, the retention shape, and whether a write may overwrite. It does not govern *what* may live -there; that is `docs/MIGRATION-PLAYBOOK.md`'s seam 4 (`${CLAUDE_PLUGIN_DATA}` for machine state +there; that is `docs/migration-playbook.md`'s seam 4 (`${CLAUDE_PLUGIN_DATA}` for machine state only), and this convention sits underneath it. ## The harness fact this exists for @@ -178,7 +178,7 @@ holds every project's artifact under the same deletable root. ## Related -- `docs/MIGRATION-PLAYBOOK.md` seam 4: what may live under `${CLAUDE_PLUGIN_DATA}` at all. This +- `docs/migration-playbook.md` seam 4: what may live under `${CLAUDE_PLUGIN_DATA}` at all. This convention governs naming beneath that. - `docs/conventions/topic-docs/`: tier placement, including the `${CLAUDE_PLUGIN_DATA}` machine-state tier. diff --git a/docs/conventions/plugin-reconfiguration/README.md b/docs/conventions/plugin-reconfiguration/README.md index bf14816c02..131354402c 100644 --- a/docs/conventions/plugin-reconfiguration/README.md +++ b/docs/conventions/plugin-reconfiguration/README.md @@ -10,7 +10,7 @@ a re-verification against a newer Claude Code release is a one-file edit. This doc owns the **reconfiguration routes and their caveats** for options stored in Claude Code's native plugin-configuration surface (`pluginConfigs`). Which options a plugin has, and what they mean, belong to that plugin's own README Options reference. The rule that no setup skill ever -writes `pluginConfigs`, user settings, or the plugin cache is PLUGIN-PHILOSOPHY's (Setup is +writes `pluginConfigs`, user settings, or the plugin cache is plugin-philosophy's (Setup is explicit and repeatable); this doc restates it only as the reason both routes below are consumer-run. diff --git a/docs/conventions/pr-body-convention/README.md b/docs/conventions/pr-body-convention/README.md index 3346aaa67e..642b1807b3 100644 --- a/docs/conventions/pr-body-convention/README.md +++ b/docs/conventions/pr-body-convention/README.md @@ -5,7 +5,7 @@ sections a pull-request body must carry. This concern is designed for **more tha `source-control` drafts and pre-checks against it today, and a future CI or `guardrails`-style enforcement consumer validates an already-created PR body against the same key later. Its ownership lives here at marketplace level, not inside `source-control`, per -[`docs/MIGRATION-PLAYBOOK.md`](../../MIGRATION-PLAYBOOK.md) "concern-named config consumed by >1 +[`docs/migration-playbook.md`](../../migration-playbook.md) "concern-named config consumed by >1 plugin". An owner doc lands before the second consumer adopts the key, not after. ## The key, and where it lives @@ -39,7 +39,7 @@ the per-key (whole-list) override semantics. This doc never restates them. It ow When no layer sets `pr_body_required_sections`, the plugin's built-in scaffold requires exactly two sections: `Summary` and `Test plan`. This is a deliberate **lane-1 default** -([`docs/PLUGIN-PHILOSOPHY.md`](../../PLUGIN-PHILOSOPHY.md) "Two-lane convention posture"), a +([`docs/plugin-philosophy.md`](../../plugin-philosophy.md) "Two-lane convention posture"), a good-practice value that cannot conflict in any repo the plugin drops into, because it presumes nothing about the consumer. diff --git a/docs/conventions/retired-conventions/README.md b/docs/conventions/retired-conventions/README.md index c87885e794..c48755629b 100644 --- a/docs/conventions/retired-conventions/README.md +++ b/docs/conventions/retired-conventions/README.md @@ -10,8 +10,8 @@ one shared deterministic helper, so every setup skill detects and cleans the sam This directory is the source of truth: `README.md` (the contract), `CHANGELOG.md` (version history). The decision record is [ADR 0018](../../adr/0018-express-team-shared-conventions-as-consumer-convention-docs.md); -the migration playbook has a section for it (`docs/MIGRATION-PLAYBOOK.md` § Retired conventions) and the -plugin philosophy makes the declaration mandatory (`docs/PLUGIN-PHILOSOPHY.md`, "Retirement +the migration playbook has a section for it (`docs/migration-playbook.md` § Retired conventions) and the +plugin philosophy makes the declaration mandatory (`docs/plugin-philosophy.md`, "Retirement declaration is mandatory"). ## Boundary: this contract owns the mechanism, never the decision to retire diff --git a/docs/conventions/shell-test-helpers/README.md b/docs/conventions/shell-test-helpers/README.md index b7d425039b..8cf5a699dd 100644 --- a/docs/conventions/shell-test-helpers/README.md +++ b/docs/conventions/shell-test-helpers/README.md @@ -3,7 +3,7 @@ Owner doc for one fork this marketplace has already decided: a plugin's shell `*.test.sh` assertion primitives and a plugin script's exit-code taxonomy are **not** consolidated into a shared, cross-plugin mechanism. Both stay duplicated or divergent per plugin, on purpose. The -[plugin philosophy](../../PLUGIN-PHILOSOPHY.md) owns the portability boundary this rests on: a plugin +[plugin philosophy](../../plugin-philosophy.md) owns the portability boundary this rests on: a plugin never imports files from a sibling plugin, and cooperation crosses that boundary only through a documented public seam. A shared shell assertion library is neither. diff --git a/docs/conventions/topic-docs/README.md b/docs/conventions/topic-docs/README.md index 047cbab7ac..d6aabb060b 100644 --- a/docs/conventions/topic-docs/README.md +++ b/docs/conventions/topic-docs/README.md @@ -157,7 +157,7 @@ Five rules hold at this row: can observe. This constrains the FORM of an override, and does not oblige any plugin to offer one. No implementer declares one today, so the ambient temp root is currently the only root in play. Per the - configuration ownership table in `docs/PLUGIN-PHILOSOPHY.md`. + configuration ownership table in `docs/plugin-philosophy.md`. **Keep the footprint small.** Nothing reclaims this tree on a schedule: verified 2026-07-26 against the full Claude Code docs corpus, no diff --git a/docs/conventions/upstream-drift/CHANGELOG.md b/docs/conventions/upstream-drift/CHANGELOG.md index f7122e86ed..321064e31d 100644 --- a/docs/conventions/upstream-drift/CHANGELOG.md +++ b/docs/conventions/upstream-drift/CHANGELOG.md @@ -187,13 +187,13 @@ surface owned. ## [1.1.0] - 2026-08-10 Adopters registry gains a row for -[`PLUGIN-PHILOSOPHY` recorded gate runs](../../PLUGIN-PHILOSOPHY.md#recorded-gate-runs) +[`plugin-philosophy` recorded gate runs](../../plugin-philosophy.md#recorded-gate-runs) ([#2175](https://github.com/melodic-software/claude-code-plugins/issues/2175)). No required part, canonical name, or enforceability verdict changed. - The new table is the registry's first entry of the **recorded-decision** kind that also carries a per-row trigger: each row states the observable event for its own verdict, rather than the - divergence-at-fetch trigger the component-stances and `OFFICIAL-DOCS` rows share. The row says so, + divergence-at-fetch trigger the component-stances and `official-docs` rows share. The row says so, so a reader does not carry the wrong firing rule across from the sibling table. ## [1.0.0] - 2026-07-26 @@ -220,6 +220,6 @@ from upstream-owned sources. - Enforceability classified per `enforceability-tiers.md`; the stamp-carries-trigger presence check named as the one deterministic candidate, deferred per the routing rule. - Migrated citing surfaces: hook-config-delivery, ecosystem-commands, loop-lane, topic-docs, - PLUGIN-PHILOSOPHY (component stances + registry row), OFFICIAL-DOCS, MIGRATION-PLAYBOOK. The + plugin-philosophy (component stances + registry row), official-docs, migration-playbook. The adopter table states per row what the surface carries: conforming four-part records, named triggers on an in-repo decision, or deliberately trigger-less terminal exclusions. diff --git a/docs/conventions/upstream-drift/README.md b/docs/conventions/upstream-drift/README.md index 02e0c5a9c0..cf72e3a265 100644 --- a/docs/conventions/upstream-drift/README.md +++ b/docs/conventions/upstream-drift/README.md @@ -23,12 +23,12 @@ with a **recheck trigger**, the stated observable event that obliges re-deriving The fleet previously practiced this in five-plus places under four names: "recheck triggers" ([hook-config-delivery](../hook-config-delivery/README.md)), "revisit triggers" ([ecosystem-commands](../ecosystem-commands/README.md), the -[migration playbook](../../MIGRATION-PLAYBOOK.md)), "re-trigger" (the migration playbook again, on a +[migration playbook](../../migration-playbook.md)), "re-trigger" (the migration playbook again, on a plugin-acceptance review record), "re-derivation triggers" ([loop-lane](../loop-lane/README.md)), plus the unlabeled "What would reopen it" ([topic-docs](../topic-docs/README.md)), with no shared definition of what a trigger must contain and no statement of what makes one checkable. Under the -[convention registry](../../PLUGIN-PHILOSOPHY.md#convention-registry)'s one-owner-per-concern rule +[convention registry](../../plugin-philosophy.md#convention-registry)'s one-owner-per-concern rule that is the fragmentation this doc closes ([melodic-software/claude-code-plugins#1638](https://github.com/melodic-software/claude-code-plugins/issues/1638)). @@ -169,7 +169,7 @@ binding any absence-establishing fetch to the raw `.md` channel with `curl` plus on the asymmetry that "a truncated fetch cannot fabricate a PRESENCE, only an ABSENCE", after two of its runs asserted a false absence exactly this way. Two independent derivations of one rule is the signal that it wants an owner. Per the -[convention registry](../../PLUGIN-PHILOSOPHY.md#convention-registry)'s one-owner-per-concern rule, +[convention registry](../../plugin-philosophy.md#convention-registry)'s one-owner-per-concern rule, the general form belongs in this doc and those surfaces keep their page-specific detail. **The `.md` channel is per-page, not universal.** `docpage-digest`'s profile records that a @@ -348,10 +348,10 @@ contract to fit its exceptions. |---|---|---| | [hook-config-delivery](../hook-config-delivery/README.md) §Recheck triggers | already the canonical name | Conforming records: version-pinned facts table with per-fact basis, table-wide as-of dates, and fact-scoped event triggers. | | [loop-lane](../loop-lane/README.md) §Versioning | "Re-derivation triggers" | Conforming records: dated upstream-claim stamps; drift outcomes recorded in its changelog. | -| [PLUGIN-PHILOSOPHY](../../PLUGIN-PHILOSOPHY.md) component-stances staleness disclaimer | unlabeled discipline | Conforming records: per-row claim, linked page, and verified date; the re-fetch-before-acting rule is [read-time validation](#read-time-validation-is-not-a-firing), and every row's stated trigger is a fetch diverging from the row. | -| [PLUGIN-PHILOSOPHY](../../PLUGIN-PHILOSOPHY.md#recorded-gate-runs) recorded gate runs | new with this table | Conforming records of the second kind: **recorded decisions**, one per platform surface the Native-first adoption gate has been run against, carrying an adopt/defer/decline verdict, the quoted upstream basis it rests on, and a trigger written per row rather than the generic divergence-at-fetch. A verdict is re-derived when its own trigger fires, not on any fetch that differs. | -| [OFFICIAL-DOCS](../../OFFICIAL-DOCS.md) staleness warning and per-row verified dates | unlabeled discipline | Conforming records: same shape as the component-stances table: link + date, divergence-at-fetch as the stated trigger. | -| [MIGRATION-PLAYBOOK](../../MIGRATION-PLAYBOOK.md) decision records | "Revisit trigger", and "Re-trigger" on the plugin-acceptance review record | Mixed: the dated component-decision records cite upstream bases and conform; the org-internal records (e.g. the ratification and plugin-acceptance review records) are named triggers; the skill-quality retrofit record is a third kind, terminal exclusions that state "no recheck trigger" by design, decided out, so nothing fires. | +| [plugin-philosophy](../../plugin-philosophy.md) component-stances staleness disclaimer | unlabeled discipline | Conforming records: per-row claim, linked page, and verified date; the re-fetch-before-acting rule is [read-time validation](#read-time-validation-is-not-a-firing), and every row's stated trigger is a fetch diverging from the row. | +| [plugin-philosophy](../../plugin-philosophy.md#recorded-gate-runs) recorded gate runs | new with this table | Conforming records of the second kind: **recorded decisions**, one per platform surface the Native-first adoption gate has been run against, carrying an adopt/defer/decline verdict, the quoted upstream basis it rests on, and a trigger written per row rather than the generic divergence-at-fetch. A verdict is re-derived when its own trigger fires, not on any fetch that differs. | +| [official-docs](../../official-docs.md) staleness warning and per-row verified dates | unlabeled discipline | Conforming records: same shape as the component-stances table: link + date, divergence-at-fetch as the stated trigger. | +| [migration-playbook](../../migration-playbook.md) decision records | "Revisit trigger", and "Re-trigger" on the plugin-acceptance review record | Mixed: the dated component-decision records cite upstream bases and conform; the org-internal records (e.g. the ratification and plugin-acceptance review records) are named triggers; the skill-quality retrofit record is a third kind, terminal exclusions that state "no recheck trigger" by design, decided out, so nothing fires. | | [ecosystem-commands](../ecosystem-commands/README.md) task-runner deferral | "Revisit triggers" | Named triggers only: an undated in-repo deferral; not a four-part record. | | [topic-docs](../topic-docs/README.md) §Implementers restate the rules | "What would reopen it" | Named trigger only: an in-repo source-hoisting decision; not a four-part record. | | `/ai-slop:audit`, the tell catalog it loads, §Upstream-drift record | new with 1.5.0 | Conforming record: revision-pinned four-part record over the Wikipedia source page (claim, `oldid` basis, as-of date, recurring recheck trigger: each `ai-slop` release and each fleet audit, chosen over per-revision after measuring the page at 50+ edits/week), plus a recorded fetch-gap note for two source sections the same trigger covers. | diff --git a/docs/conventions/windows-path-emit/README.md b/docs/conventions/windows-path-emit/README.md index 06071a35cd..96f9ac98b2 100644 --- a/docs/conventions/windows-path-emit/README.md +++ b/docs/conventions/windows-path-emit/README.md @@ -2,8 +2,8 @@ Owner doc for one rule that has already cost this repo real test validity: **a path that originates in Git Bash and is handed to PowerShell, `cmd`, or a Windows-native interpreter must be converted to -Windows form first.** The [plugin philosophy](../../PLUGIN-PHILOSOPHY.md) owns the -[cross-platform contract](../../PLUGIN-PHILOSOPHY.md#cross-platform-contract) this rests on, "build +Windows form first.** The [plugin philosophy](../../plugin-philosophy.md) owns the +[cross-platform contract](../../plugin-philosophy.md#cross-platform-contract) this rests on, "build paths from documented anchors with platform path APIs"; this doc owns the *emit shape* that keeps it true at the one boundary where the failure is silent, and names the helper and the detector that back it. diff --git a/docs/extensibility-contract-smoke-tests.md b/docs/extensibility-contract-smoke-tests.md index e5c03da483..b216409e26 100644 --- a/docs/extensibility-contract-smoke-tests.md +++ b/docs/extensibility-contract-smoke-tests.md @@ -2,7 +2,7 @@ These tests resolve behavior the official docs leave unspecified for the extensibility contract v2.1 (the "Extensibility contract v2.1: the four seams" section of the [migration -playbook](MIGRATION-PLAYBOOK.md)). Each records the commands used and the observed result, so the +playbook](migration-playbook.md)). Each records the commands used and the observed result, so the contract rests on verified behavior rather than inference. Run 2026-07-12 against Claude Code 2.1.207 on Windows. Re-verify fresh before relying on a result. diff --git a/docs/FINDING-YOUR-UNKNOWNS.md b/docs/finding-your-unknowns.md similarity index 98% rename from docs/FINDING-YOUR-UNKNOWNS.md rename to docs/finding-your-unknowns.md index b5eb72d09b..3b5d8d7914 100644 --- a/docs/FINDING-YOUR-UNKNOWNS.md +++ b/docs/finding-your-unknowns.md @@ -7,8 +7,8 @@ what you don't yet know while it is still cheap to find out. This doc owns the h conventions the methodology graduated into this marketplace: the reply-affordance convention, the export-button rule, and the opt-in deviation-log convention. It also owns the pattern catalog and the boundaries (when HTML, when not; what deliberately stays -un-codified). Sibling docs: `PLUGIN-PHILOSOPHY.md` (governance), -`GLOSSARY.md` (vocabulary), `MIGRATION-PLAYBOOK.md` (delivery). +un-codified). Sibling docs: `plugin-philosophy.md` (governance), +`glossary.md` (vocabulary), `migration-playbook.md` (delivery). **Sources and permission basis.** The material derives from public posts by their named author (see [Sources](#sources-and-citation-shape)). This doc quotes short attributed @@ -75,7 +75,7 @@ Two diagnostics ride the taxonomy: The lifecycle is a loop: what an artifact teaches you becomes the starting map for the next round. The author frames this as matching the map to the territory (S1, "Matching map and territory"), cited here as his metaphor, not adopted as house vocabulary (see -`GLOSSARY.md` rejected terms). +`glossary.md` rejected terms). ## The five-pass pre-implementation workflow @@ -169,7 +169,7 @@ where a skill's own contract says so. **Recorded trigger.** The moment a second plugin reads `DEVIATIONS.md` (rather than writing its own), the convention-registry rule fires and this section graduates to a -registry row per `PLUGIN-PHILOSOPHY.md` "Convention registry". +registry row per `plugin-philosophy.md` "Convention registry". ## When HTML, and when not @@ -240,7 +240,7 @@ Two companions to the warning: ## Heuristics awaiting evidence The following corpus heuristics are recorded here as doc lines and candidate eval cases, -not as standing skill instructions. Per `PLUGIN-PHILOSOPHY.md` "Instruction economy", +not as standing skill instructions. Per `plugin-philosophy.md` "Instruction economy", they graduate into a skill body only on observed, repeated stumble evidence: - **Observed-fact evidence bar** (brainstorming): each candidate option cites an observed, diff --git a/docs/GLOSSARY.md b/docs/glossary.md similarity index 96% rename from docs/GLOSSARY.md rename to docs/glossary.md index 9144667994..f0ee1aaec2 100644 --- a/docs/GLOSSARY.md +++ b/docs/glossary.md @@ -76,7 +76,7 @@ per consumer. The four-way pre-prompt breakdown used to decide which unknown-finding pass a task needs: known knowns, known unknowns, unknown knowns, unknown unknowns. Owned by -[`FINDING-YOUR-UNKNOWNS.md`](FINDING-YOUR-UNKNOWNS.md); entries cite it rather than restating the +[`finding-your-unknowns.md`](finding-your-unknowns.md); entries cite it rather than restating the quadrants. **blindspot finding types** @@ -85,7 +85,7 @@ The typed taxonomy a blindspot pass reports its findings in: Landmine (breaks so non-obvious), History (a constraint the code no longer shows), Convention (an unwritten team rule), Missing concept (a domain idea the prompt never named). The output contract lives in `discovery:blindspot`; the taxonomy's rationale in -[`FINDING-YOUR-UNKNOWNS.md`](FINDING-YOUR-UNKNOWNS.md). +[`finding-your-unknowns.md`](finding-your-unknowns.md). ## Rejected terms @@ -101,7 +101,7 @@ Each maps to the term or doctrine that owns the concept. | cache *(the doc-restating-environment sense)* | `docs-hygiene:audit-derivability`'s derivable-from-environment doctrine; the word is overloaded here (plugin cache, prompt cache) | | sediment | the `docs-hygiene` audit family's pruning doctrine; collides with the code-sense use in `playbooks:fable-5` | | sycophancy | nothing. It is a generic LLM-behavior term with no distinct project meaning. Free-prose use is unaffected; it is simply not project vocabulary | -| map / territory | the source author's metaphor, cited where it appears in [`FINDING-YOUR-UNKNOWNS.md`](FINDING-YOUR-UNKNOWNS.md) "The unknowns taxonomy"; never house vocabulary (metaphor-jargon risk) | +| map / territory | the source author's metaphor, cited where it appears in [`finding-your-unknowns.md`](finding-your-unknowns.md) "The unknowns taxonomy"; never house vocabulary (metaphor-jargon risk) | ## Provenance diff --git a/docs/hook-migration-audit.md b/docs/hook-migration-audit.md index 13f910bc5d..20529450a8 100644 --- a/docs/hook-migration-audit.md +++ b/docs/hook-migration-audit.md @@ -2,16 +2,16 @@ Point-in-time audit of the **general-purpose** subset of `melodic-software/medley`'s in-repo hooks for extraction into this marketplace's hook plugins (`guardrails`, `claude-ops`). This is an **audit -snapshot**, not durable policy. The [migration playbook](MIGRATION-PLAYBOOK.md) is the policy; this +snapshot**, not durable policy. The [migration playbook](migration-playbook.md) is the policy; this table records each candidate's gate compliance on the audit date and which follow-up issue owns each accepted migration. Empirical claims decay: a row is only true as of the stamp below. Audited 2026-07-12 (`melodic-software/medley#1391`, under wave-2 map `melodic-software/medley#1369`). Facts are Tier-0, read from each hook's `.sh`, its `.test.sh`, and medley's `.claude/settings.json` registration this session. The shipped-standard column is measured against the published hook-plugin -conventions: the [four-seam extensibility contract](MIGRATION-PLAYBOOK.md), the +conventions: the [four-seam extensibility contract](migration-playbook.md), the [hook-telemetry envelope contract](conventions/hook-telemetry/README.md), and the -[shared-`hook-utils.sh` decision record](MIGRATION-PLAYBOOK.md). +[shared-`hook-utils.sh` decision record](migration-playbook.md). ## Scope @@ -112,7 +112,7 @@ parameterized tool or are consumer-owned by design. **Revisit trigger:** a second repo adopts the `.work/`-prep-evidence-before-PR convention → extract a generic prep-gate whose slug derivation, artifact glob, and freshness field are declared config. - **`hook-telemetry-sink`**: the consumer sink the [envelope contract](conventions/hook-telemetry/README.md) - "Mediator boundary" and the playbook's [Reintegration](MIGRATION-PLAYBOOK.md) step, which keeps the + "Mediator boundary" and the playbook's [Reintegration](migration-playbook.md) step, which keeps the sink script as the bridge, both say stays consumer-owned. It maps the envelope into medley's own store; it is not a producer to migrate. **Revisit trigger:** see the generic-sink gap below. - **`cc-telemetry-ensure`**: medley OTEL-pipeline enablement, bound to `tools/observability/*` diff --git a/docs/knowledge-integration-design.md b/docs/knowledge-integration-design.md index 7a1a9940ca..0a5b1c4852 100644 --- a/docs/knowledge-integration-design.md +++ b/docs/knowledge-integration-design.md @@ -3,7 +3,7 @@ Spec for the `knowledge` plugin's first-class value step: a session opens against the consolidated `knowledge-corpus` corpus and fits relevant findings into **any** target repo. Capability and shape (a skill, not a manual workflow) are already locked by the decision record for the knowledge-corpus -consuming repo and integration flow (2026-07-13), listed under `MIGRATION-PLAYBOOK.md` +consuming repo and integration flow (2026-07-13), listed under `migration-playbook.md` "Decision records". This record specs the skill; it does not re-open the mechanism. **No build here**. The implement follow-up is emitted below. diff --git a/docs/MIGRATION-PLAYBOOK.md b/docs/migration-playbook.md similarity index 99% rename from docs/MIGRATION-PLAYBOOK.md rename to docs/migration-playbook.md index 4246152f62..cc93f637ff 100644 --- a/docs/MIGRATION-PLAYBOOK.md +++ b/docs/migration-playbook.md @@ -29,7 +29,7 @@ How skills, hooks, and agents become reusable plugins in this marketplace. One p time: lift it out, make it work in plugin form and in any repo, build in configuration and extensibility, vet it against best practices, then publish. -The durable design policy is [Plugin philosophy](PLUGIN-PHILOSOPHY.md). This playbook applies that +The durable design policy is [Plugin philosophy](plugin-philosophy.md). This playbook applies that policy to migration, validation, cutover, and release; it does not redefine the policy. All schema and behavior claims below were verified against the official docs on 2026-06-22 (the @@ -325,7 +325,7 @@ two fixed setup lines; this playbook only names the mechanism. Schema is reposit machine-scope files under `~/.claude/` stay outside it (ADR 0018). This ladder is the runtime application of the durable convention posture owned by -[PLUGIN-PHILOSOPHY.md § Two-lane convention posture](PLUGIN-PHILOSOPHY.md): a pre-prescribed +[plugin-philosophy.md § Two-lane convention posture](plugin-philosophy.md): a pre-prescribed convention is a hardcoded dependency, so a plugin ships a default only in lane 1 (a good-practice value that cannot conflict in any consuming repo) and otherwise takes lane 2, where its setup discovers the consumer's convention and externalizes it as an extensibility point the ladder then resolves. @@ -334,7 +334,7 @@ the consumer's convention and externalizes it as an extensibility point the ladd Whether a plugin needs a `setup` skill, and the uniform contract it follows (`setup` name, `disable-model-invocation: true`, `check` + `apply` actions, non-interactive completion), is owned -by [PLUGIN-PHILOSOPHY.md § Setup is explicit and repeatable](PLUGIN-PHILOSOPHY.md). Migration work +by [plugin-philosophy.md § Setup is explicit and repeatable](plugin-philosophy.md). Migration work applies it as-is. Playbook-specific additions: the Thariq `config.json` first-run pattern is **rejected** for plugins: it is not an official mechanism, and it writes into `${CLAUDE_PLUGIN_ROOT}`, which is replaced on every update (the plugins-reference caching note), so @@ -388,7 +388,7 @@ cover trigger/routing, the happy path, at least one refusal/guardrail, and one a must not do. **Method source.** The methodology behind this policy is Anthropic's "Define success criteria and -build evaluations" ([indexed in OFFICIAL-DOCS.md](OFFICIAL-DOCS.md#evaluation-guidance-platform-docs); +build evaluations" ([indexed in official-docs.md](official-docs.md#evaluation-guidance-platform-docs); the `evals` plugin distills it). The rich form is that guidance's eval anatomy with the golden answer in its rubric-instructions form (`expected_output` + `expectations` are what a grader is told to look for), and every case must carry one. The schema rejects a case with no @@ -749,7 +749,7 @@ Catalog these per migration; they are the usual failures when an in-repo skill b the path [resolves against the repository checkout](https://code.claude.com/docs/en/plugin-marketplaces#relative-paths), including cloud sessions that install from the clone at session start, with no separate `marketplace add` step. Local collaborators still see the interactive trust prompt once they - trust the folder. See [`docs/CLOUD-SESSIONS.md`](CLOUD-SESSIONS.md) "Plugins in sessions on this repo". + trust the folder. See [`docs/cloud-sessions.md`](cloud-sessions.md) "Plugins in sessions on this repo". ## Per-plugin migration gate @@ -763,11 +763,11 @@ For each skill/hook/agent being migrated: 4. **Bundle + isolate.** Move required assets inside the plugin; reference via `${CLAUDE_PLUGIN_ROOT}`. 5. **Expose extensibility.** Declare `userConfig` for consumer choices; document each option. Apply the userConfig full-potential criterion and the exec-form hook rule from - [PLUGIN-PHILOSOPHY.md § Configuration ownership and scope](PLUGIN-PHILOSOPHY.md): no custom + [plugin-philosophy.md § Configuration ownership and scope](plugin-philosophy.md): no custom config channel where the native schema fits, and no `${user_config.*}` in shell-form hooks. 6. **Strip PII / secrets.** Hard gate, before the first commit. 7. **Check component stances.** Every component the plugin ships conforms to the component stance - table in [PLUGIN-PHILOSOPHY.md](PLUGIN-PHILOSOPHY.md): no `commands/`, no unjustified + table in [plugin-philosophy.md](plugin-philosophy.md): no `commands/`, no unjustified `settings.json` `agent`, wait-listed components absent; setup criteria applied per its setup section; runtime prerequisites degrade per its failure-behavior rules. 8. **Idempotent, modular, extensible.** Re-running is safe; pieces compose; variability is declared. @@ -781,7 +781,7 @@ For each skill/hook/agent being migrated: even with `metadata.pluginRoot` set, despite the marketplaces-doc example to the contrary (verified 2026-06-23). Then run `claude plugin validate --strict ` to validate the **catalog manifest itself**: a bad entry surfaces only there, not in per-plugin validation. The catalog page - (`docs/CATALOG.md`) regenerates from the manifests, so run `node scripts/generate-catalog.mjs`. + (`docs/catalog.md`) regenerates from the manifests, so run `node scripts/generate-catalog.mjs`. ## Migration order, PRs & parallelization @@ -798,7 +798,7 @@ conflicts. Group units into one PR only when they are hard-coupled, or when the mechanical bulk edit. **Expect one shared-file conflict, resolved at merge.** The two files parallel PRs all touch are the -catalog manifest (`.claude-plugin/marketplace.json`) and the generated catalog page (`docs/CATALOG.md`). Those conflicts are +catalog manifest (`.claude-plugin/marketplace.json`) and the generated catalog page (`docs/catalog.md`). Those conflicts are expected: resolve them by **serializing the final merges**, not by serializing authorship. **Gate every unit before publish.** Each unit clears its parity / acceptance gate, the per-plugin @@ -907,7 +907,7 @@ plugins-reference, and hooks pages 2026-07-17; re-verify per the `CLAUDE.md` fre does. 7. **Main-thread and PATH surfaces.** A plugin `settings.json` `agent` entry takes over the consumer's main thread, and is prohibited by default per the component stance table in - [PLUGIN-PHILOSOPHY.md](PLUGIN-PHILOSOPHY.md); an exception requires the documented justification + [plugin-philosophy.md](plugin-philosophy.md); an exception requires the documented justification the stance demands, reviewed here. `bin/` executables join the Bash tool's `PATH` while the plugin is enabled: names must be collision-safe (plugin-prefixed), and each binary's provenance is reviewed like any hook script. @@ -1484,7 +1484,7 @@ surface to a published plugin for a single consumer's low-value nicety. `sensitive` value is absent from settings entirely (smoke-test A) and cannot be verified this way. **Exception:** a `directory`/`file` relative-path entry in checked-in project settings resolves against the repo checkout (cloud sessions included). See - [`docs/CLOUD-SESSIONS.md`](CLOUD-SESSIONS.md). Otherwise the marketplace is known but the plugin is absent, and step 3's + [`docs/cloud-sessions.md`](cloud-sessions.md). Otherwise the marketplace is known but the plugin is absent, and step 3's verify edit would run with no plugin hook. 2. Interactively, `/plugin configure` adjusts `userConfig` toggles at any time; keep the `HOOK_TELEMETRY_SINK` wiring and the sink script (the bridge), adapting the sink for any diff --git a/docs/NATIVE-SURFACES.md b/docs/native-surfaces.md similarity index 100% rename from docs/NATIVE-SURFACES.md rename to docs/native-surfaces.md diff --git a/docs/native-surfaces/records.json b/docs/native-surfaces/records.json index 38ef7e27ec..c5bf364768 100644 --- a/docs/native-surfaces/records.json +++ b/docs/native-surfaces/records.json @@ -1,6 +1,6 @@ { "schema": 1, - "note": "SSOT for native-surface overlap verdicts. Hand-editable and human-gated: every verdict here was written by a person, never by a run. docs/NATIVE-SURFACES.md is generated from this file and is never the source. Seeded candidates come from the canonical-pair seed bundled with /claude-ops:audit-native-overlap; a candidate becomes a row only when someone rules on it. Phrasing rules for anything baked out of these rows: docs/conventions/native-references/README.md.", + "note": "SSOT for native-surface overlap verdicts. Hand-editable and human-gated: every verdict here was written by a person, never by a run. docs/native-surfaces.md is generated from this file and is never the source. Seeded candidates come from the canonical-pair seed bundled with /claude-ops:audit-native-overlap; a candidate becomes a row only when someone rules on it. Phrasing rules for anything baked out of these rows: docs/conventions/native-references/README.md.", "rows": [ { "native": { "name": "code-review", "class": "bundled-skill", "markers": [] }, diff --git a/docs/OFFICIAL-DOCS.md b/docs/official-docs.md similarity index 100% rename from docs/OFFICIAL-DOCS.md rename to docs/official-docs.md diff --git a/docs/PLUGIN-ARTIFACT-PROTOCOL.md b/docs/plugin-artifact-protocol.md similarity index 100% rename from docs/PLUGIN-ARTIFACT-PROTOCOL.md rename to docs/plugin-artifact-protocol.md diff --git a/docs/PLUGIN-PHILOSOPHY.md b/docs/plugin-philosophy.md similarity index 99% rename from docs/PLUGIN-PHILOSOPHY.md rename to docs/plugin-philosophy.md index 2a47d8611d..26a1558348 100644 --- a/docs/PLUGIN-PHILOSOPHY.md +++ b/docs/plugin-philosophy.md @@ -19,8 +19,8 @@ - [Authoritative references](#authoritative-references) This is the durable design policy for plugins in this marketplace. The -[migration playbook](MIGRATION-PLAYBOOK.md) applies it to migration and release work; the -[plugin artifact protocol](PLUGIN-ARTIFACT-PROTOCOL.md) defines the shared artifact contract used by +[migration playbook](migration-playbook.md) applies it to migration and release work; the +[plugin artifact protocol](plugin-artifact-protocol.md) defines the shared artifact contract used by lifecycle plugins. ## Design boundary @@ -653,7 +653,7 @@ doc before a second plugin adopts it. Fleet audits check conformance per row. | Shared concern | Owner | |---|---| | Topic-docs two-tier binding | [`docs/conventions/topic-docs/`](conventions/topic-docs/README.md) | -| Lifecycle artifact protocol | [`docs/PLUGIN-ARTIFACT-PROTOCOL.md`](PLUGIN-ARTIFACT-PROTOCOL.md) | +| Lifecycle artifact protocol | [`docs/plugin-artifact-protocol.md`](plugin-artifact-protocol.md) | | Shared hook utility library | `lib/hook-utils.sh`, synced by `scripts/sync-hook-utils.sh` | | Cross-plugin shared-source clusters | `scripts/cross-plugin-source-registry.txt` | | Config cascade: consumer-config layering, precedence, overlay naming, and expression form | [`docs/conventions/config-cascade/`](conventions/config-cascade/README.md) | @@ -688,8 +688,8 @@ doc before a second plugin adopts it. Fleet audits check conformance per row. | Always-on hook cost ceiling | [`docs/conventions/hook-budget/`](conventions/hook-budget/README.md) | | Tracker reference form inside a code comment | [`docs/conventions/tracker-reference-form/`](conventions/tracker-reference-form/README.md) | | Untrusted-content framing contract | [`docs/conventions/untrusted-content/`](conventions/untrusted-content/README.md) | -| Reply affordance on decision-collecting artifacts | [`docs/FINDING-YOUR-UNKNOWNS.md`](FINDING-YOUR-UNKNOWNS.md#reply-affordance-convention) | -| Export button on interactive HTML artifacts | [`docs/FINDING-YOUR-UNKNOWNS.md`](FINDING-YOUR-UNKNOWNS.md#export-button-rule) | +| Reply affordance on decision-collecting artifacts | [`docs/finding-your-unknowns.md`](finding-your-unknowns.md#reply-affordance-convention) | +| Export button on interactive HTML artifacts | [`docs/finding-your-unknowns.md`](finding-your-unknowns.md#export-button-rule) | | Retired-convention detection and cleanup (manifest + shared helper) | [`docs/conventions/retired-conventions/`](conventions/retired-conventions/README.md) | | Authoring formats: acceptance-criteria format and diagram dialect by artifact kind, read by `/planning:interview`, `/planning:prd`, and `/planning:design` | [`docs/conventions/authoring-formats/`](conventions/authoring-formats/README.md) | @@ -1193,7 +1193,7 @@ cannot assume a plugin layout. ## Authoritative references The complete categorized index of plugin-relevant official pages is -[`docs/OFFICIAL-DOCS.md`](OFFICIAL-DOCS.md); `https://code.claude.com/docs/llms.txt` is the +[`docs/official-docs.md`](official-docs.md); `https://code.claude.com/docs/llms.txt` is the authoritative self-updating master list. The Claude Code pages this document rests on, each re-fetched 2026-08-10 and confirmed to still carry the topics named beside it (the `melodic-software/standards` entry below is not a Claude Code page and was not re-checked on that diff --git a/docs/SKILL-CHEAT-SHEET.md b/docs/skill-cheat-sheet.md similarity index 99% rename from docs/SKILL-CHEAT-SHEET.md rename to docs/skill-cheat-sheet.md index 15e9c06c82..492637732b 100644 --- a/docs/SKILL-CHEAT-SHEET.md +++ b/docs/skill-cheat-sheet.md @@ -6,7 +6,7 @@ Do not hand-edit the generated block below. Edit the source frontmatter and rege Grouping axis: this page groups skills by **sequence of use**, the session-flow workflow stages you move through while working. The separate what-kind-of-plugin taxonomy axis is -owned by [docs/CATALOG-TAXONOMY.md](CATALOG-TAXONOMY.md). +owned by [docs/catalog-taxonomy.md](catalog-taxonomy.md). diff --git a/docs/specs/context-engineering-corpus-knowledge.md b/docs/specs/context-engineering-corpus-knowledge.md index 3a781a5537..b08989b651 100644 --- a/docs/specs/context-engineering-corpus-knowledge.md +++ b/docs/specs/context-engineering-corpus-knowledge.md @@ -16,7 +16,7 @@ Companion documents: the signed-off decision contract this corpus fed, which was slice and is therefore pruned before merge under the topic-docs convention, so it survives as the `
` paste in its pull request; and the earlier `context-engineering-claude-5` plan, built on P1 alone and never engaging P2, whose slice main pruned in the topic-docs v3.0.0 adoption. -Sibling durable outputs of the same corpus family: `docs/FINDING-YOUR-UNKNOWNS.md` and the +Sibling durable outputs of the same corpus family: `docs/finding-your-unknowns.md` and the neighboring `context-engineering-*.md` specs listed at the end of this section. ## Contents diff --git a/docs/specs/context-engineering-linked-sources.md b/docs/specs/context-engineering-linked-sources.md index 87e529f2c1..2643610339 100644 --- a/docs/specs/context-engineering-linked-sources.md +++ b/docs/specs/context-engineering-linked-sources.md @@ -139,7 +139,7 @@ are the named upstream of interview-style and blindspot planning skills in this **Where the deep apparatus lives** `context-engineering-critical-apparatus.md`. Note additionally that this page has a dedicated repo -integration whose durable output is `docs/FINDING-YOUR-UNKNOWNS.md`, landed separately, which +integration whose durable output is `docs/finding-your-unknowns.md`, landed separately, which carries the article's claims into this marketplace's own contract deltas; the audit slice that produced it was contract tier and has been pruned. That integration and the critical apparatus are complementary: the audit is repo-facing, the apparatus is diff --git a/docs/specs/dead-code-lsp-viability.md b/docs/specs/dead-code-lsp-viability.md index 9fb07108e4..af82dd6b78 100644 --- a/docs/specs/dead-code-lsp-viability.md +++ b/docs/specs/dead-code-lsp-viability.md @@ -250,8 +250,8 @@ already correct: - `scripts/validate-plugin-contracts.mjs:271` declares `lspServers: [".lsp.json"]` - `plugins/claude-ops/skills/inventory/scripts/inventory.py:88` inventories `lsp-servers` -- `docs/OFFICIAL-DOCS.md:44` tracks the LSP servers doc page -- `docs/PLUGIN-PHILOSOPHY.md:180` says "*Adopt on need. Consumer must have the language-server binary; +- `docs/official-docs.md:44` tracks the LSP servers doc page +- `docs/plugin-philosophy.md:180` says "*Adopt on need. Consumer must have the language-server binary; declare the prerequisite per the failure-behavior rules.*" That last line is the governing house policy and it points the same way as this research. diff --git a/docs/specs/docs-hygiene-sweep-unapplied-remediations.md b/docs/specs/docs-hygiene-sweep-unapplied-remediations.md index d39eec6d3f..c75d09d5ea 100644 --- a/docs/specs/docs-hygiene-sweep-unapplied-remediations.md +++ b/docs/specs/docs-hygiene-sweep-unapplied-remediations.md @@ -141,14 +141,14 @@ a description of what moved rather than as coordinates. | 18 | `plugins/planning/skills/interview/SKILL.md` | T2 | 302 L / 6,346 w | 37 | `tier-mismatch`, not a new spoke: lines 233 to 274 collapse into the existing `context/session-config.md`, which already declares itself the reference layer for that exact section | | 19 | `plugins/work-items/skills/triage/SKILL.md` | T2 | 198 L / 4,070 w | 56 | `context/apply-outcome.md` | | 20 | `prompts/loops/loop-lane-prompts.md` | T3 | 1,961 L | 775 | `prompts/loops/loop-lane-profile-claude-code-plugins.md` (1,187 to 1,961). The file declares itself repository-agnostic and 40% of it is one repository's filled instance | -| 21 | `docs/MIGRATION-PLAYBOOK.md` | T3 | 1,738 L | 266 | Six dated decision records (1,473 to 1,738) move to `docs/adr/`. **Renumber:** the spec was written for 0018 through 0023, and 0018 is now taken, so they land at 0019 through 0024 | +| 21 | `docs/migration-playbook.md` | T3 | 1,738 L | 266 | Six dated decision records (1,473 to 1,738) move to `docs/adr/`. **Renumber:** the spec was written for 0018 through 0023, and 0018 is now taken, so they land at 0019 through 0024 | `plugins/implementation/skills/implement-dispatch/SKILL.md` was measured and is **not** a finding: 118 lines but 3,420 words, roughly 29 words per line. It is recorded because a future addition crosses the ceiling without the line count moving. -The `MIGRATION-PLAYBOOK.md` split is the only one with heavy inbound citation. It is cited from many -plugin changelogs and from `docs/PLUGIN-PHILOSOPHY.md`. No citation found in the audit targets a +The `migration-playbook.md` split is the only one with heavy inbound citation. It is cited from many +plugin changelogs and from `docs/plugin-philosophy.md`. No citation found in the audit targets a moved section by anchor, but re-check anchors before cutting. ## L2 structure: 167 findings @@ -180,7 +180,7 @@ Concentration by group, as measured, for scoping: | Group | Files | Largest | |---|---:|---| | `I-songwriting` | 40 | `plugins/songwriting/context/pat-pattison/research/meter.md`, 1,922 L | -| `K-repo-docs` | 15 | `docs/MIGRATION-PLAYBOOK.md`, 1,738 L | +| `K-repo-docs` | 15 | `docs/migration-playbook.md`, 1,738 L | | `C-vcs-repo` | 11 | `plugins/source-control/skills/babysit-prs/reference/orchestration.md`, 962 L | | `B-cc-config-ops` | 9 | `plugins/claude-config/skills/audit-instructions/reference/criteria.md`, 1,742 L | | `E-session-behavior` | 9 | `plugins/session-flow/reference/save-point.md`, 566 L | @@ -293,12 +293,12 @@ applied. | Cluster | Instances | Existing owner | Remedy | |---|---:|---|---| | `lane-telemetry-upsert` | 3 | `plugins/claude-ops/skills/lanes/SKILL.md`, "Never pass a body as an `@path` string" | `name-an-owner` plus `normalize-wording`. Highest value in the lane: drifted, unowned, unguarded | -| `dynamic-context-git-preamble` | 44, 26 edited | none; proposes a `docs/PLUGIN-PHILOSOPHY.md` "Inline-template conventions" home | `normalize-wording` plus `edit-existing-rule`. One canonical fallback string corrects a live mislabel (`echo "clean"` on a failed `git status`) at 15 sites | -| `setup-probe-dont-recite` | 17 | `docs/PLUGIN-PHILOSOPHY.md` "Setup is explicit and repeatable" (clause absent) | `edit-existing-rule`. All 17 already cite that contract at document scope | -| `setup-headless-reconfigure-recipe` | 22, 6 edited | `docs/PLUGIN-PHILOSOPHY.md` "Configuration ownership and scope" | `normalize-wording` | +| `dynamic-context-git-preamble` | 44, 26 edited | none; proposes a `docs/plugin-philosophy.md` "Inline-template conventions" home | `normalize-wording` plus `edit-existing-rule`. One canonical fallback string corrects a live mislabel (`echo "clean"` on a failed `git status`) at 15 sites | +| `setup-probe-dont-recite` | 17 | `docs/plugin-philosophy.md` "Setup is explicit and repeatable" (clause absent) | `edit-existing-rule`. All 17 already cite that contract at document scope | +| `setup-headless-reconfigure-recipe` | 22, 6 edited | `docs/plugin-philosophy.md` "Configuration ownership and scope" | `normalize-wording` | | `detector-findings-producer-preamble` | 4 | `docs/conventions/detector-findings/README.md` | `normalize-wording`. Removes two em dashes in `plugins/mutation-testing/skills/audit/context/persist-findings.md:1` and `:5` as a side effect | | `songwriting-persistence-block` | 9 | `plugins/songwriting/context/pat-pattison/research/artifact-persistence.md` | `trim-to-citation`, the lane's only one, because it is the only cluster whose owner sits inside the same plugin as its call sites | -| `setup-never-writes-boundary` | 41, 34 edited | `docs/PLUGIN-PHILOSOPHY.md` "Configuration ownership and scope" | `normalize-wording` | +| `setup-never-writes-boundary` | 41, 34 edited | `docs/plugin-philosophy.md` "Configuration ownership and scope" | `normalize-wording` | ### Remediated, N equal to 2 and N equal to 1 @@ -332,7 +332,7 @@ Recorded so nobody re-opens them. | `songwriting-author-seam` | 9 | 9 of 9 already cite by exact heading | **Sequencing.** Roughly 45 `plugins/*/skills/setup/SKILL.md` files are touched by four sub-clusters -at once and must be worked one pass per file, not in parallel. `docs/PLUGIN-PHILOSOPHY.md` carries +at once and must be worked one pass per file, not in parallel. `docs/plugin-philosophy.md` carries three clusters' owner additions and must go first, because every later cluster cites it. ## L4 encapsulation: 34 violations @@ -398,8 +398,8 @@ directory and are legal cite targets. | `V-slop-02` | `docs/conventions/upstream-drift/README.md:342` | `ai-slop/skills/audit/reference/catalog.md` | | `V-dhg-01` | `docs/conventions/upstream-drift/README.md:343` | `docs-hygiene/skills/write-for-humans/reference/sources.md` | | `V-sf-01` | `docs/conventions/pre-pr-ordering/README.md:5` | `session-flow/skills/workflow/context/pre-pr.md` | -| `V-sq-01` | `docs/PLUGIN-PHILOSOPHY.md:596` | `skill-quality/skills/check/reference/fresh-eyes-declarations.md`, also unresolvable | -| `V-sq-02` | `docs/PLUGIN-PHILOSOPHY.md:1071` | same target, also unresolvable | +| `V-sq-01` | `docs/plugin-philosophy.md:596` | `skill-quality/skills/check/reference/fresh-eyes-declarations.md`, also unresolvable | +| `V-sq-02` | `docs/plugin-philosophy.md:1071` | same target, also unresolvable | | `V-sc-15` | `plugins/work-items/skills/setup/reference/overlay-ignore-probes.md:18` | `source-control/skills/setup/reference/apply-convention.md` | | `V-ops-01` | `plugins/claude-config/skills/audit-pass/reference/run-state-and-resumability.md:70` | `claude-ops/skills/lanes/context/restart-consumer.md` | | `V-auto-01` | `plugins/source-control/skills/babysit-loop/reference/promotion-evidence-resolution.md:8` | `autonomy/skills/setup/schemas/guardrails-security-binding.schema.json` | @@ -470,7 +470,7 @@ constraint survives the rewrite. Line numbers below are **re-verified against th ### `negation`, 6 -**1. `docs/PLUGIN-PHILOSOPHY.md:561`** (the audit recorded `:546`; the file gained 15 lines above it) +**1. `docs/plugin-philosophy.md:561`** (the audit recorded `:546`; the file gained 15 lines above it) ```text Do not swallow errors or claim success when the promised result was not produced. @@ -984,13 +984,13 @@ README), `## Tests` (`machine-health`), `## Revisit triggers` (`instruction-plac | J4 | `plugins/desktop-notification/README.md:85` | `M3` | S2 | | J5 | `plugins/wizard/README.md:35` | `L1` | S2 | | J6 | `plugins/plugin-quality/README.md:9` | `L1` | S2 | -| K1 | `docs/MIGRATION-PLAYBOOK.md:1728` | `Am3` | S3 | +| K1 | `docs/migration-playbook.md:1728` | `Am3` | S3 | | K2 | `docs/conventions/standards/README.md:80` | `Am3` | S3 | | K3 | `docs/upstream/mattpocock-skills.md:14` | `Am2` | S3 | | M1 | `README.md:54` | `Am4` | S3 | | M2 | `SECURITY.md:9` | `A1` | S3 (no edit recommended) | -`K4` is `docs/PLUGIN-PHILOSOPHY.md`, filed as an `M1` mode finding with **no edit proposed**: it is +`K4` is `docs/plugin-philosophy.md`, filed as an `M1` mode finding with **no edit proposed**: it is four documents (policy reference, argument, procedure, measured findings) in over a thousand lines, and splitting it belongs to L2. The finding exists so L2 has the mode boundaries when it decides where the split lines go. @@ -1024,7 +1024,7 @@ a quarter of the slice, from authoring-doctrine scope, and account for at least | R1 | 57 | `HUMAN` | out of scope, working artifact | `docs/topics/**`. Contract-tier documents whose reader is the task's own agents | | R2 | 9 | `HUMAN` | `AGENT` | The `docs/conventions/*/README.md` files that declare themselves synced verbatim into agent-loaded plugin binding copies | | R3 | 2 | `HUMAN` | `AGENT` | `prompts/**`. Launch-prompt templates filled in by a person and read by a model | -| R4 | 2 | `HUMAN` | out of scope, generated | `docs/CATALOG.md` and `docs/SKILL-CHEAT-SHEET.md` | +| R4 | 2 | `HUMAN` | out of scope, generated | `docs/catalog.md` and `docs/skill-cheat-sheet.md` | | R5 | 4 | `HUMAN` | out of scope, functional artifact | Test-fixture READMEs under `tests/fixtures/`, `skills/worktree/fixtures/`, `scripts/fixtures/` | | R6 | 5 | `HUMAN` | no change, no findings filed | `docs/upstream/**` drift ledgers. A person does read them, but their table rows record what a source said and rewriting one changes the record | diff --git a/docs/specs/extract-ssot-sweep-2026-08-28.md b/docs/specs/extract-ssot-sweep-2026-08-28.md index a9462d9a79..baf724120f 100644 --- a/docs/specs/extract-ssot-sweep-2026-08-28.md +++ b/docs/specs/extract-ssot-sweep-2026-08-28.md @@ -62,11 +62,11 @@ findings came from. Four of its results are factual defects rather than style dr Ordered as the predecessor's sequencing note requires: the owner doc first, then the call sites, one editing pass per file. -### Owner edits, `docs/PLUGIN-PHILOSOPHY.md` +### Owner edits, `docs/plugin-philosophy.md` - **A `runtime-grounded` clause** in "Setup is explicit and repeatable". The recorded cluster `setup-probe-dont-recite` named this owner and recorded the clause as absent; it was, and - `grep -n "recite" docs/PLUGIN-PHILOSOPHY.md` returned nothing. Twenty setup skills asserted the + `grep -n "recite" docs/plugin-philosophy.md` returned nothing. Twenty setup skills asserted the rule with no owner to point at. - **Three missing Convention registry rows.** `hook-budget`, `tracker-reference-form` and `untrusted-content` each open by declaring themselves owner docs and each was absent from the @@ -74,7 +74,7 @@ editing pass per file. check conformance per row." A convention with no row gets no conformance check, and `untrusted-content` is fleet-adopted and anchors a standing refusal. - **A registry row for the dynamic-context precompute convention**, owned by the `playbooks` plugin. - The recorded cluster proposed a new `docs/PLUGIN-PHILOSOPHY.md` section named "Inline-template + The recorded cluster proposed a new `docs/plugin-philosophy.md` section named "Inline-template conventions"; that heading already exists under "Delegation mechanics" and owns a different subject (what a dispatch prompt must contain), so a second one would have duplicated an anchor and merged two unrelated concerns. @@ -256,13 +256,13 @@ on disk. One is fixed in this change set; the second, a table cell in the same f | Cluster | Sites | Proposed owner | |---|---|---| -| `read-only-artifact-write-reconciliation` | 7 audit skills | `docs/PLUGIN-PHILOSOPHY.md` "Naming". Seven skills reason from one unowned premise to two opposite bare-invocation defaults, and the repo has already shipped a detector that "quietly violated its own skill's stated hard rule" on it | -| `destructive-consent-floor` | 5 skills | `docs/PLUGIN-PHILOSOPHY.md` "Naming", which already uses "explicit user override" and "never under a blanket approval" without defining either. The fleet holds two live rules on whether a flag is consent, for the same operation | -| `worker-return-is-synthesis` | 13 files, 8 plugins | `docs/PLUGIN-PHILOSOPHY.md` "Delegation mechanics". The re-verification scope has already forked: four sites require every finding re-verified, one requires only the claims a conclusion rests on | +| `read-only-artifact-write-reconciliation` | 7 audit skills | `docs/plugin-philosophy.md` "Naming". Seven skills reason from one unowned premise to two opposite bare-invocation defaults, and the repo has already shipped a detector that "quietly violated its own skill's stated hard rule" on it | +| `destructive-consent-floor` | 5 skills | `docs/plugin-philosophy.md` "Naming", which already uses "explicit user override" and "never under a blanket approval" without defining either. The fleet holds two live rules on whether a flag is consent, for the same operation | +| `worker-return-is-synthesis` | 13 files, 8 plugins | `docs/plugin-philosophy.md` "Delegation mechanics". The re-verification scope has already forked: four sites require every finding re-verified, one requires only the claims a conclusion rests on | | `dispatch-prompt-part-contract` | 6 files | The same section, which carries a four-part list that matches no consumer's. Four, five and six-part contracts are all in force | | `fanout-concurrency-cap` | 9 numeric sites | The same section, which has no concurrency content at all. Nine caps from 1 to a dozen with five grounds and no owner, while a fleet audit already treats "a numeric concurrency cap" as satisfying a required posture | | `config-cascade-unreadable-layer` | 5 setup skills | `docs/conventions/config-cascade/`, whose resolution algorithm covers a malformed layer and not an unreadable one. Five skills invented a variant; one file states it twice, differently | -| `settings-scope-write-posture` | 3 audit skills | `docs/PLUGIN-PHILOSOPHY.md` "Configuration ownership and scope". Two owner docs exist and each is scoped so it binds none of the three sites | +| `settings-scope-write-posture` | 3 audit skills | `docs/plugin-philosophy.md` "Configuration ownership and scope". Two owner docs exist and each is scoped so it binds none of the three sites | ### In-plugin consolidations @@ -437,7 +437,7 @@ available: the alternative is a changelog entry that does not say what it change ### Three trees the sweep excluded by fiat The sweep's encapsulation floor scoped itself to `docs/**` and then dropped five subtrees. Two of the -exclusions are defensible and stated as such: `docs/SKILL-CHEAT-SHEET.md` (162 citations, generated +exclusions are defensible and stated as such: `docs/skill-cheat-sheet.md` (162 citations, generated and CI drift-checked, so an edit is reverted by its generator) and `docs/upstream/` (vendored, not this repo's prose to style). **The other three rest on nothing.** `docs/specs/` (roughly 265 sites), `docs/topics/` (roughly 43) and `docs/adr/` (25) were excluded on the assertion that "the dated @@ -457,7 +457,7 @@ expression, and per this file's own recall-limits discipline none of these numbe ### A stale record found in passing, not an ADR matter -`docs/MIGRATION-PLAYBOOK.md`'s "Review record: `dometrain` (ACCEPT, 2026-07-22)" carries the +`docs/migration-playbook.md`'s "Review record: `dometrain` (ACCEPT, 2026-07-22)" carries the clause "Reviewed at `0.1.0`; a version bump adding a new trust surface re-triggers this review." **The plugin's manifest reads `0.2.7`** (`plugins/dometrain/.claude-plugin/plugin.json`, read from the working tree, not from the roster). Eleven releases landed in between and the review was never @@ -491,12 +491,12 @@ the accurate statement and needs no edit. Recorded rather than left, because a s reading stronger in the log than in the artifact is the direction that misleads. **The `:943` re-anchoring was good practice for a reason that was not true.** `dd6c11fe`'s message -says the spec's `dometrain` entry pinned `MIGRATION-PLAYBOOK.md:943`, "a line this change's own edit +says the spec's `dometrain` entry pinned `migration-playbook.md:943`, "a line this change's own edit would have invalidated", and claims the decay rule was for the first time "caught before landing". The insertion lands below that line: ```console -$ git show dd6c11fe --unified=0 --format='' -- docs/MIGRATION-PLAYBOOK.md | grep '^@@' +$ git show dd6c11fe --unified=0 --format='' -- docs/migration-playbook.md | grep '^@@' @@ -944,0 +945,7 @@ ### Review record — `dometrain` (ACCEPT, 2026-07-22) ``` @@ -513,7 +513,7 @@ established. **"Every one of #3468's ADR-0018 citation fixes wrote a CHANGELOG entry" is false, in the harmless direction.** `c66f26ce` also fixed two sites that produced no changelog entry: the -Convention registry row in `docs/PLUGIN-PHILOSOPHY.md`, and a `skills/confirm/SKILL.md` parenthetical +Convention registry row in `docs/plugin-philosophy.md`, and a `skills/confirm/SKILL.md` parenthetical in `docs/conventions/pre-pr-ordering/README.md`, a convention that ships no `CHANGELOG.md` at all (`ls docs/conventions/pre-pr-ordering/` returns `README.md` alone). Both were resolved by deleting the path rather than by quoting it, so neither manufactured a new citation. The twelve-row count and @@ -576,7 +576,7 @@ actually supports is the near-inverse: > summary an update.** Cross-file staleness is the default outcome, not the exception: the fix and > the record live in different files, nothing in the toolchain links them, and the commit has no > reason of its own to open the record. #3380 closed 32 of 34 rows spread across a `.claude/rules/` -> file, `docs/PLUGIN-PHILOSOPHY.md`, four convention READMEs and several plugins' trees, and left a +> file, `docs/plugin-philosophy.md`, four convention READMEs and several plugins' trees, and left a > two-hour-old roster in `docs/specs/` asserting the opposite, and four later passes paid for it. > > An earlier version of this paragraph said "three plugins' files", which `git show --stat 6c7a1032` @@ -813,7 +813,7 @@ figures to differ. trusting the roster. That pass resolved **16 citations at 12 sites in 8 files**, every one rewritten to the `/plugin:skill` public invocation on the [`loop-lane` 9.0.1](../conventions/loop-lane/CHANGELOG.md) form. Beyond the five named above it - reached `docs/PLUGIN-PHILOSOPHY.md`'s Convention registry (the dynamic-context precompute row + reached `docs/plugin-philosophy.md`'s Convention registry (the dynamic-context precompute row this very change set added, written in the bare plugin-relative form ADR 0018 names as its real defect class), two conformance rows in `docs/conventions/config-cascade/README.md`, one in `docs/conventions/pre-pr-ordering/README.md`, three in @@ -829,16 +829,16 @@ figures to differ. this checkout rather than an address for an obligation. They are the three worked examples in `docs/conventions/plugin-data-report-keying/README.md`, the four location cites in `docs/conventions/shell-test-helpers/README.md` (whose subject *is* where the duplicate copies - sit), the four `scripts/` entry-surface pointers in `docs/NATIVE-SURFACES.md` and - `docs/CLOUD-SESSIONS.md` that the public-surface contract's own carve-out permits, two observation + sit), the four `scripts/` entry-surface pointers in `docs/native-surfaces.md` and + `docs/cloud-sessions.md` that the public-surface contract's own carve-out permits, two observation rows in the `NATIVE-SURFACES` generated region (authored in `docs/native-surfaces/records.json`, so a hand-edit of the rendered view would be overwritten and the store's copy is the same citation, not a second one), that store's own note on where the - overlap seed file lives, the boris-baseline evidence row in `docs/PLUGIN-PHILOSOPHY.md`, the five - file-and-frontmatter cites inside `docs/MIGRATION-PLAYBOOK.md`'s dated `dometrain` security-review + overlap seed file lives, the boris-baseline evidence row in `docs/plugin-philosophy.md`, the five + file-and-frontmatter cites inside `docs/migration-playbook.md`'s dated `dometrain` security-review record (each asserting what a named file contains, under a record that re-triggers on a version bump), and three dated changelog entries that quote a citation as it stood. - `docs/SKILL-CHEAT-SHEET.md` is + `docs/skill-cheat-sheet.md` is generated too, and the dated records under `docs/specs/`, `docs/adr/` and `docs/topics/` are out of scope by the same test. - **A fifth filtered probe exists and is not in the four-site table above.** diff --git a/docs/specs/invocation-mode-doctrine-brief.md b/docs/specs/invocation-mode-doctrine-brief.md index a31a772948..21dfeea909 100644 --- a/docs/specs/invocation-mode-doctrine-brief.md +++ b/docs/specs/invocation-mode-doctrine-brief.md @@ -42,7 +42,7 @@ question-bounded per ADR 0005. - [x] Rubric doc exists at `docs/conventions/invocation-mode/README.md`: default posture, exception classes, evidence axes, router verdict, 10-row grade table. -- [x] Convention-registry row added in `docs/PLUGIN-PHILOSOPHY.md`; one-line cross-references +- [x] Convention-registry row added in `docs/plugin-philosophy.md`; one-line cross-references from its setup contract and Instruction economy sections. - [x] Lane 8 decision rows (8 rows, lessons 3/4/5) recorded in STEERING.md with lane status. - [x] SSOT (`docs/upstream/mattpocock-skills.md`) gap-3 verdict cells dispositioned; the @@ -78,7 +78,7 @@ question-bounded per ADR 0005. cross-skill-reach axis. - **Q6, router pattern:** REJECT the model-side router with reason (under the model-invoked default the always-present listing is the router; the `true` set is deliberately - model-invisible). Human-side answer: `docs/SKILL-CHEAT-SHEET.md` + `claude-ops:inventory`. + model-invisible). Human-side answer: `docs/skill-cheat-sheet.md` + `claude-ops:inventory`. Domain-scoped composition routers (`discipline:sweep-all` precedent) remain an admitted, distinct pattern. - **Q7, re-grade bounding:** one question. Do the 10 non-setup `true` skills fall into a diff --git a/docs/specs/write-for-agents-brief.md b/docs/specs/write-for-agents-brief.md index d877bd0436..f1dd7ddbc6 100644 --- a/docs/specs/write-for-agents-brief.md +++ b/docs/specs/write-for-agents-brief.md @@ -55,7 +55,7 @@ them. extraction. Settled by: the shipped `evals/evals.json` suite, where every positive case fires the skill, every negative control (audit phrasing, "create a skill", human-README writing) does not. This criterion was drafted naming `claude plugin eval`; the skill shipped in #3003 with - this marketplace's own eval format, which `MIGRATION-PLAYBOOK.md` "Evals" explains is + this marketplace's own eval format, which `migration-playbook.md` "Evals" explains is `skill-creator`'s and not that command's, and which nothing executes, so the suite is a written specification checked by `check-evals-quality.sh`, exercised by hand per that section's recipe, rather than a pass/fail gate on the implementation PR. diff --git a/docs/upstream/aihero-course.md b/docs/upstream/aihero-course.md index f9a15c3ec3..b63b349c47 100644 --- a/docs/upstream/aihero-course.md +++ b/docs/upstream/aihero-course.md @@ -333,7 +333,7 @@ Interview-first per contract; register gate clean (8/8); user confirmed. Contrac | Invocation choice needs a decision rubric (L3, L4) | ADOPT (adapted — inverted default) | Rubric adopted with model-invoked default + three exception classes (side-effect/manual-timing, setup, maintainer-only) — the inverse of upstream's user-invoked default. Home: `docs/conventions/invocation-mode/README.md` + convention-registry row; cross-linked from PLUGIN-PHILOSOPHY (setup contract, Instruction economy); `playbooks:skill-authoring` pointer filed | | Upstream's user-invoked default (L4) | REJECT | Solo-operator posture; materially weakened by mattpocock/skills#693 (desktop/web drop user-invoked skills from the listing) and by this marketplace's multi-repo discoverability need | | Splitting by invocation (L4) | ADOPT (routed) | The rubric owns the split axis; `docs-hygiene:write-for-agents` (#2962) when-to-split doctrine points at it (lane 7 decision honored) | -| Router-skill pattern (L4 / MECHANICS) | REJECT (with reason) | Under the model-invoked default the always-present listing IS the router; `disable-model-invocation: true` skills are deliberately model-invisible. Human-side answer: `docs/SKILL-CHEAT-SHEET.md` + `claude-ops:inventory`. Domain-scoped composition routers (`discipline:sweep-all` precedent) remain an admitted distinct pattern | +| Router-skill pattern (L4 / MECHANICS) | REJECT (with reason) | Under the model-invoked default the always-present listing IS the router; `disable-model-invocation: true` skills are deliberately model-invisible. Human-side answer: `docs/skill-cheat-sheet.md` + `claude-ops:inventory`. Domain-scoped composition routers (`discipline:sweep-all` precedent) remain an admitted distinct pattern | | Explicit `disable-model-invocation` on every skill (L4) | ADOPT | 17 missing-key skills normalized to explicit `false` + new `skill-quality:check` criterion requiring the key — filed implementation follow-on | | Setup-skill convention (L3/L4) | PARITY — no work | Already documented: PLUGIN-PHILOSOPHY "Setup is explicit and repeatable" (landed `967db56c`, pre-dating #2910's "documented nowhere" premise) | | User vs project scope + cloud caveat (L5) | ADOPT | Remote/cloud sessions never load `~/.claude` user scope — project/marketplace skills are the only steering that reaches them; recorded as the rubric's surface-coverage/cloud-scope evidence axis | @@ -425,7 +425,7 @@ convention-resolution ladder found no existing project glossary and more than on home, so creation was deferred to a filed follow-on rather than invented in-lane ([#3000](https://github.com/melodic-software/claude-code-plugins/issues/3000)). That is now **done**: the maintainer confirmed the placement and the ADOPTED terms live in -[`docs/GLOSSARY.md`](../GLOSSARY.md), which also records the REJECT rows below as rejected +[`docs/glossary.md`](../glossary.md), which also records the REJECT rows below as rejected synonyms mapped to the terms that own their concepts. The rows here remain the decision record — the glossary carries the vocabulary, this table carries why. diff --git a/docs/upstream/aihero-shipping-course.md b/docs/upstream/aihero-shipping-course.md index d4ed092e99..bb996eb223 100644 --- a/docs/upstream/aihero-shipping-course.md +++ b/docs/upstream/aihero-shipping-course.md @@ -63,7 +63,7 @@ PARTIAL / REJECTED / OPEN. | F | /goal vs tickets posture | — | planning:draft-goal-condition | ADOPTED (sixth route-away row: multi-window work routes to spec + decomposed items; advisory, no folklore token figures) | #2938 | | W | Wayfinder deltas | C18–C20 | planning:wayfind | PARTIAL (C18+C19 adopted; C20 already-present) | #2939 | | X | Invocation doctrine (skills-repo delta PRs #878/#880; C23 from #848) | C21–C23 | playbooks:skill-authoring, skill-quality:check | PARTIAL (C21+C22 adopted; C23 already-present — corrected 2026-08-21 from a flat ADOPTED, which disagreed with C23's own disposition and with how every other lane holding an already-present candidate is graded) | #2940 | -| Y | Macro/micro lifecycle orchestrator (interview Q18) | — | work-items:ship | ADOPTED (thin router; PR topology per-container via the `Execution shape:` line, not repo config; item/checkpoint/phase-boundary canonized in `work-items/reference/execution-shape.md`; the glossary deferral has since ENDED — `docs/GLOSSARY.md` landed 2026-08-20 (#3062) and `phase boundary` is promoted there, while `item` and `checkpoint` stay reference-local as seam-specific terms) | #2948 | +| Y | Macro/micro lifecycle orchestrator (interview Q18) | — | work-items:ship | ADOPTED (thin router; PR topology per-container via the `Execution shape:` line, not repo config; item/checkpoint/phase-boundary canonized in `work-items/reference/execution-shape.md`; the glossary deferral has since ENDED — `docs/glossary.md` landed 2026-08-20 (#3062) and `phase boundary` is promoted there, while `item` and `checkpoint` stay reference-local as seam-specific terms) | #2948 | Seam-scrutiny follow-ons (not course-derived, surfaced by the same audit): binding config (#2941), contract hygiene (#2942), lease hardening (#2943), local-markdown docs (#2944), @@ -201,7 +201,7 @@ given, and one disposal venue does not exist. phase boundary* (a loop) while confirm → quality-gate → pull-request fires *once at completion*, and that verifier is dispatched by `implementation:implement-dispatch`, not `implement` — writing it down canonically would have laundered the error into an SSOT. Also: READMEs are - human-facing and graded on a different bar by docs hygiene; `PLUGIN-PHILOSOPHY.md:474-476` + human-facing and graded on a different bar by docs hygiene; `plugin-philosophy.md:474-476` routes a cross-plugin concern to a `docs/conventions/` owner doc rather than a plugin README; converting the inline mentions to citations would **strip the presence gates from the invocation sites** (a seam-phrasing violation — the gate belongs where the invocation is instructed); and @@ -218,7 +218,7 @@ given, and one disposal venue does not exist. "review gate passes" → suggest `confirm`, then PR after CONFIRMED. The skill that renders the verdict, the skill that lists the sequence, and the plugin that opens the PR all agreed; `implement`'s handoff step was the lone dissenter. Landed: a new owner doc - `docs/conventions/pre-pr-ordering/` with a registry row in `PLUGIN-PHILOSOPHY.md` (the registry's + `docs/conventions/pre-pr-ordering/` with a registry row in `plugin-philosophy.md` (the registry's own trigger — "a new cross-plugin convention lands in an owner doc before a second plugin adopts it" — had already fired); `pre-pr.md` cites the owner for the order and keeps ownership of what each step does; its override-boundary paragraph corrected from "fixed plugin identity" to fleet @@ -293,7 +293,7 @@ withheld; three of five initial answers revised on evidence). number would read a same-numbered issue in the *current* repo; (3) the contract-slice rung keys on the **topic slug**, not the branch slug — the branch axis is deliberately lossy. **Design correction found in PR review:** the item is read through a documented public seam or the provider - mechanic, never by invoking the sibling plugin's seam CLI — `PLUGIN-PHILOSOPHY.md` forbids + mechanic, never by invoking the sibling plugin's seam CLI — `plugin-philosophy.md` forbids discovering another plugin's installation directory, and no namespaced item-fetch action exists today. So this is *not* the marketplace's first cross-plugin seam call; the provider-mechanic read is the operative path, the rung works with no tracker plugin installed, and parent linkage (whose diff --git a/docs/upstream/cursor-pstack.md b/docs/upstream/cursor-pstack.md index 1aa4ac80b4..e5b9d48bf3 100644 --- a/docs/upstream/cursor-pstack.md +++ b/docs/upstream/cursor-pstack.md @@ -34,7 +34,7 @@ directory Cursor exposes"), and Cursor transcript paths under `~/.cursor/`. | `tdd` | Two rules: [`testing:write`'s decline list](../../plugins/testing/skills/write/context/write.md) and [`debugging:debug` phase 5](../../plugins/debugging/skills/debug/SKILL.md) — see [below](#tdd--absorbed-as-two-rules-in-two-different-plugins) | Absorbed (skill omitted) | **Taken:** the cost branch — six impracticality triggers (broad harness setup, brittle mocks, slow end-to-end infrastructure, production-only state, an unstatable reproduction, large fixture churn) plus "prefer no new test to a bad one" and the requirement to name the substitute check; and "confirm it fails for the intended reason", the one part of the seven-step workflow with no counterpart. **Re-homed on audit:** the plan put both in `debug`; `testing:write`'s "When NOT to write tests" is the incumbent for the cost concern and a second decline list there would split it. **Rejected — the skill:** its own description says to "use only when the user explicitly asks", which cannot earn an always-listed line. **Rejected — the five-item bad-test definition:** `tdd:principles` sources this from Khorikov and `testing:audit` enforces it deterministically. **Rejected — the anti-test-gaming guardrails:** already verbatim in `implementation:implement`. **Rejected — "do not silently skip the regression step":** `debug` phases 5 and 6 already say it. **Rejected — the evidence-shaped report:** marginal; phase 6 already requires the hypothesis and an independent verdict. | | `reflect` | One routing fix in [`running-retro`](../../plugins/session-flow/skills/running-retro/SKILL.md) and [`retro`](../../plugins/session-flow/skills/retro/context/session.md) — see [below](#reflect--omitted-one-routing-gap-closed) | Absorbed (skill omitted) | **Taken:** routing an accepted learning by edit size, narrowed to the one part that was missing — an accepted new-skill candidate now goes to `/playbooks:skill-authoring` gated on `/skill-quality:check`, presence-gated with a stated fallback, in BOTH retro skills. **Widened on audit:** the plan scoped it to `running-retro` because "`retro`'s five dimensions are closed", a non-sequitur — `retro` closes its scoring dimensions, not the analysis that produces candidates. **Rejected — the skill:** `retro` and `running-retro` own the axis and `reflect` claims no unclaimed trigger. **Rejected — the structural-enforcement check:** `claude-config:audit-automation-gaps` owns it with a default-REJECT posture. **Rejected — the Accepted/Rejected/Backlog gate:** stated twice already, and upstream's version auto-files backlog items where `running-retro` forbids it. **Rejected — "the skill didn't trigger" as a finding class:** owned by `discipline:use-your-skills`. **Rejected — the three orthogonal lenses:** the strongest dissent in this port, recorded below rather than smoothed over. | | `arena` | No skill. Four ideas folded into [`architecture:improve` Design-It-Twice](../../plugins/architecture/skills/improve/research/deepening/interface-design.md), [`prototype`'s shared discipline](../../plugins/prototype/context/discipline.md), and [`naming:name-it-better tournament`](../../plugins/naming/skills/name-it-better/SKILL.md) | Absorbed (skill omitted — see [below](#why-arena-ships-no-skill)) | **Taken:** the rejected-alternatives return field, which becomes a sixth part of the Design-It-Twice result schema and reuses the `rejected-reason` field name the candidate artifact already carries; the graft ledger — a hybrid must name what came from which design *and* what was left behind with its reason — landing both in Design-It-Twice's recommendation step and in prototype's when-done capture, whose rule 6 previously read "the answer is the only thing worth keeping" and whose step 6 deletes losing variants; the read-the-spread discipline, adapted rather than copied, because that fan-out assigns *orthogonal* constraints so shape-divergence is the designed null result and only convergence-anyway or assumption-divergence carries signal; and criterion pre-commitment in naming's tournament, restricted to *when* the rubric is fixed since *which* criteria apply is already owned by the consuming project. **Rejected — the skill itself.** See below. **Rejected — the secret rubric.** Naming's rubric is deliberately the consuming project's own declared standards, which are public by construction; withholding them would fight that design rather than improve it, and pre-commitment gets the same anti-retrofit property without the secrecy. **Adaptation notes, corrected on verification.** An earlier draft of this row overstated both, and the corrections are recorded rather than quietly swapped. (1) Upstream does **not** set a subagent `isolation:` — the word never appears in its file. It assigns each candidate an output path, "a git worktree where possible, otherwise `/tmp/arena-/candidate-/`", to avoid N candidates writing to one path. That is a different mechanism from the `isolation: worktree` frontmatter this fleet has declined three times (`sweep-all:451`, `discovery/agents/explorer.md:103`, `researcher.md:99` — "isolation and a disk-graded handoff are incompatible by construction"), so those rejections are not actually in conflict with it. (2) Its judge instruction is "**Prefer** a different model family from the parent's" — a preference, not the unconditional demand the earlier draft claimed; `must` appears zero times in the upstream file. That is compatible with this fleet's presence-gated-with-a-named-fallback posture rather than opposed to it. The unconditional version belongs to `show-me-your-work`, below, and the two lanes should not be conflated. Neither note bears on the omission, which rests on the Rule of Three alone. | -| `technical-writing` | [`docs-hygiene:write-for-humans`](../../plugins/docs-hygiene/skills/write-for-humans/SKILL.md) | Derived, re-posture | **Taken:** the four-layer model and the question each layer answers (mode / address / load / ambiguity); the Diátaxis mode picker with all four modes, the compass, "use it on one sentence too", and the don't-mix-split-and-link rule; upstream's three above-the-layers rules (cut every word that does no work; use the short everyday word; when a rule makes a sentence worse, fix the sentence another way or leave it alone) — our third always-rule, write the real name and do not invent jargon, is drawn from upstream's separate word-list and anti-jargon paragraphs rather than from that trio; the "vary the rhythm" section, which is the sharpest thing in the upstream file — a document can obey every layer and still read machine-written, and *be specific over sterile* names the failure exactly; the address, load and ambiguity rule sets; the STE fidelity caveat, kept because it is why this ships a paraphrase rather than a claim of conformance; and the review checklist, minus two items. **Re-postured — the whole point of the port.** Upstream ships the four standards as house rules. Here they are a **named, replaceable default set**, applied only after a search for the consuming project's own declared guide comes back empty, with the fallback stated out loud. `PLUGIN-PHILOSOPHY.md:198-202` admits a shipped default "only when it is a good-practice value that cannot conflict in *any* repo the plugin drops into", and names Conventional Commits as the archetype of what fails that test; Google style, ASD-STE100 and Global English are that class. The draft plan carried its own disproof — a decision existed solely to delete two Global English punctuation rules because they already conflicted with this repository's measured em-dash ruling. Those rules are therefore **kept**, where a consumer's own guide disables them, rather than deleted for every consumer because one repository disagreed; `ai-slop`'s own charter states the principle ("a deliberate house style is config in the consuming repo, never a shipped-default change"). **Rejected — the commit-message and PR-body scope.** Upstream applies every layer except Diátaxis to them. Here `ai-slop:audit` already excludes commit messages and PR bodies from the markdown-prose regime, shape is owned by `source-control:commit`'s subject-convention ladder and the PR-body-sections convention, and both `write-for-*` skills scope to markdown *files*, which a commit message is not. **Rejected — review-checklist items 1 and 8.** Item 1 is scoped "only to document sets" (a cross-document audit) and item 8 demands verifying counts and regeneration commands (a verification action); either would smuggle an audit into a write-time skill. The count rule survives in the body as a writing rule. **Rejected — "add new offenders to unslop's abstract-metaphor rule".** That rule lives in `ai-slop`'s `skills/audit/reference/catalog.md`, which is a private surface under the encapsulation contract *and* CC BY-SA 4.0 material derived from a pinned Wikipedia revision; instructing a consumer to edit another plugin's internals fails on both counts. For the same reason the audit's counter-proposal to absorb the three sentence layers into that catalog was declined: it would contaminate an attributed corpus and falsify its drift claim. **Rejected — "indent code snippets with tabs".** A hard formatting convention that collides with a consuming repo's own linter config, by the same test that re-postured the rest. **Rejected — the worked example.** Upstream's is about its own `budget.mjs`; a substitute path from this repository would be the identical defect with a different string, and a consumer reading a path that does not exist in their tree is what `audit-noise` classifies as a ghost ref. Rewritten fully generic, labelled as placeholders. **Renamed:** `write-for-humans`, not `technical-writing` — the latter is a noun phrase and the grammar takes an imperative verb phrase. Bare `write` both collides (the leaf-name registry records `write bug-report,testing`) and under-specifies the reader, which is exactly when `PLUGIN-PHILOSOPHY.md:67` prescribes a hyphenated qualifier, so this is grammar-conformant rather than a new exception. **Upgraded:** upstream's four source stamps carry a fetch date and no recheck trigger; the drift convention bars a bare date, so each now carries a full four-part stamp. | +| `technical-writing` | [`docs-hygiene:write-for-humans`](../../plugins/docs-hygiene/skills/write-for-humans/SKILL.md) | Derived, re-posture | **Taken:** the four-layer model and the question each layer answers (mode / address / load / ambiguity); the Diátaxis mode picker with all four modes, the compass, "use it on one sentence too", and the don't-mix-split-and-link rule; upstream's three above-the-layers rules (cut every word that does no work; use the short everyday word; when a rule makes a sentence worse, fix the sentence another way or leave it alone) — our third always-rule, write the real name and do not invent jargon, is drawn from upstream's separate word-list and anti-jargon paragraphs rather than from that trio; the "vary the rhythm" section, which is the sharpest thing in the upstream file — a document can obey every layer and still read machine-written, and *be specific over sterile* names the failure exactly; the address, load and ambiguity rule sets; the STE fidelity caveat, kept because it is why this ships a paraphrase rather than a claim of conformance; and the review checklist, minus two items. **Re-postured — the whole point of the port.** Upstream ships the four standards as house rules. Here they are a **named, replaceable default set**, applied only after a search for the consuming project's own declared guide comes back empty, with the fallback stated out loud. `plugin-philosophy.md:198-202` admits a shipped default "only when it is a good-practice value that cannot conflict in *any* repo the plugin drops into", and names Conventional Commits as the archetype of what fails that test; Google style, ASD-STE100 and Global English are that class. The draft plan carried its own disproof — a decision existed solely to delete two Global English punctuation rules because they already conflicted with this repository's measured em-dash ruling. Those rules are therefore **kept**, where a consumer's own guide disables them, rather than deleted for every consumer because one repository disagreed; `ai-slop`'s own charter states the principle ("a deliberate house style is config in the consuming repo, never a shipped-default change"). **Rejected — the commit-message and PR-body scope.** Upstream applies every layer except Diátaxis to them. Here `ai-slop:audit` already excludes commit messages and PR bodies from the markdown-prose regime, shape is owned by `source-control:commit`'s subject-convention ladder and the PR-body-sections convention, and both `write-for-*` skills scope to markdown *files*, which a commit message is not. **Rejected — review-checklist items 1 and 8.** Item 1 is scoped "only to document sets" (a cross-document audit) and item 8 demands verifying counts and regeneration commands (a verification action); either would smuggle an audit into a write-time skill. The count rule survives in the body as a writing rule. **Rejected — "add new offenders to unslop's abstract-metaphor rule".** That rule lives in `ai-slop`'s `skills/audit/reference/catalog.md`, which is a private surface under the encapsulation contract *and* CC BY-SA 4.0 material derived from a pinned Wikipedia revision; instructing a consumer to edit another plugin's internals fails on both counts. For the same reason the audit's counter-proposal to absorb the three sentence layers into that catalog was declined: it would contaminate an attributed corpus and falsify its drift claim. **Rejected — "indent code snippets with tabs".** A hard formatting convention that collides with a consuming repo's own linter config, by the same test that re-postured the rest. **Rejected — the worked example.** Upstream's is about its own `budget.mjs`; a substitute path from this repository would be the identical defect with a different string, and a consumer reading a path that does not exist in their tree is what `audit-noise` classifies as a ghost ref. Rewritten fully generic, labelled as placeholders. **Renamed:** `write-for-humans`, not `technical-writing` — the latter is a noun phrase and the grammar takes an imperative verb phrase. Bare `write` both collides (the leaf-name registry records `write bug-report,testing`) and under-specifies the reader, which is exactly when `plugin-philosophy.md:67` prescribes a hyphenated qualifier, so this is grammar-conformant rather than a new exception. **Upgraded:** upstream's four source stamps carry a fetch date and no recheck trigger; the drift convention bars a bare date, so each now carries a full four-part stamp. | | `blast-radius` | [`review:quality-gate downstream`](../../plugins/review/skills/quality-gate/context/downstream.md) | Partial (scope adopted, mechanics rejected) | **Taken:** the scope, which is the only part that was genuinely missing — the whole review lane is diff-scoped and nothing in it looks outward (verified by reading: `architecture-guardian` stops at mapping changed files to layers, `code-reviewer` and `doc-drift-detector` carry no caller item, `fanout` fans across surfaces all diffing one merge-base, `mutation-testing:audit` is `git diff`-scoped by construction). Also taken: "listing the callers is not the job"; the where-grep-stops surfaces (library source and pinned version, serialization boundaries, timing and lifecycle, flag reach, cross-language readers); the confirmed-vs-cleared split as two deliverables; "a search that finds nothing is still an answer"; and the cheapest-test handback, strengthened into a presence-gated handoff to `/testing:write` + `/mutation-testing:audit`. **Rejected — the five-rung proof ladder.** It would be this fleet's *ninth* evidence ladder (severity's confidence axis, `improvement:find`'s evidence ladder, research source tiers, `codebase-health`'s verified/likely/needs-review, `repo-fleet-hygiene`'s confidence model, `trace-intent`'s intent-evidence tiers, fable-5's calibration grades and inference-distance rungs, mutation-testing's productive/equivalent/arid/unclassified). `discipline:reuse-or-replace` names that exactly: "leaving the established way in place and quietly adding a divergent way alongside it". The unverified-claim floor it encodes is kept, citing fable-5's verification chapter as owner. And this port's own departure argument condemns its bottom rung specifically — a rung that is cheapest to fill when the evidence is worst is a rung that will be filled. **Rejected — "the one fact it's safe because of" as the report's spine**, demoted to a first probe. As an organizing structure it makes secondary risks structurally invisible on any change with several independent ones, and this marketplace models change risk as multi-dimensional (`autonomy`'s work-classes names four risk properties; `devils-advocate` Round 4 sweeps ten operational categories precisely because assumption-driven rounds miss traps). **Rejected — a third axis in `review/context/severity.md`**, which its own Vocabulary section closes at two and which `review/skills/quality-gate/context/spec.md` had already declined to widen; it is also a cross-plugin convention surface with a CI gate. **Rejected — the `arena` routing**, no such skill existing here. **Renamed:** `downstream`, not `impact` (generic, and already prose-loaded in six always-listed descriptions (`ai-slop:audit`, `architecture:improve`, `claude-ops:changelog`, `docs-hygiene:rename-references`, `improvement:find`, `work-items:work`)) and not `blast-radius` (a three-way collision), while the "blast radius" trigger phrases are carried deliberately rather than suppressed. | | `unslop` | [`ai-slop:audit`'s tell catalog, "Cursor unslop additions"](../../plugins/ai-slop/skills/audit/reference/catalog.md) and [`reference/rewrite-guide.md`](../../plugins/ai-slop/skills/audit/reference/rewrite-guide.md), in [`ai-slop` 0.2.0](../../plugins/ai-slop/CHANGELOG.md) | Absorbed (skill omitted) | **Landed before this record** — derived at `ai-slop` 0.2.0 on 2026-08-19 (`reference/catalog.md`, "Second pass"), so this file's git history dates the *row*, not the derivation — and so it is not one of the ten lanes decided below; the row exists because the collection's attribution is incomplete without it, and because the recheck trigger above reaches only the rows this table names. **No skill:** `ai-slop:audit` already owned the axis over a Wikipedia-derived tell inventory and already shipped the detect-then-guarded-fix flow upstream's four-step process describes, so the port lands as entries in an existing catalog rather than as a skill; the `unslop this` trigger phrase is carried in that skill's description rather than suppressed. **Taken:** the seven patterns the Wikipedia inventory did not already carry — three script rules (`rule-chatbot-artifacts`, which merges upstream's separate chatbot-phrase and sycophantic-tone patterns and argues IMPORTANT in the [detector-findings crosswalk](../conventions/detector-findings/README.md); `rule-filler-phrases` and `rule-stacked-hedging`, both SUGGESTION) and four rubric tells (`rule-false-ranges`, `rule-colon-crutch`, `rule-abstract-metaphor-jargon`, `rule-mechanism-free-claims`); the plain-word trio `utilize` / `leverage` / `facilitate` into the shipped AI-vocabulary default, density-gated and measured quiet on the calibration corpus, so the shipped default stays neutral while saturated files still flag; and the upstream file's fix-time half, which a catalog that only decides *what flags* had nowhere to put — it becomes `reference/rewrite-guide.md`, carrying the plain-speech rewrites, the substitution guardrail (an em dash becomes a period or a comma, never a parenthesis, an en dash, or a spaced hyphen, because swapping one tell for another is not a fix), and the closing self-audit pass. **Deduplicated rather than absorbed:** every remaining upstream pattern already had a Wikipedia-derived entry, and the catalog records that in an overlap map accounting for all of them. The map says **catalogued by**, deliberately weaker than "covered by": a row pointing at a `recorded-only` entry says so, and `rule-bold-overuse`, `rule-inline-header-lists` and `rule-title-case` are each catalogued and dormant, so nothing runs them in either layer — and upstream's own carve-out for a bold lead-in that ends in a period and introduces genuinely new detail is recorded on `rule-inline-header-lists` as calibration pre-work, not as a live boundary. **Rejected — Name-dropping**, deliberately out of scope for general prose: the Wikipedia-specific form is `rule-canned-notability`, whose entry says there is no general-prose analogue worth a rule. **Rejected — the general half of Generic conclusions.** Only the formulaic closer that `rule-challenges-conclusion`'s pattern actually matches is detected; a bare optimism line matches no shipped rule, and the overlap map records that rather than papering over it. **Rejected as a script rule — abstract metaphor nouns.** Upstream ships a word list; calibrated against this marketplace's corpus, "substrate" alone measured 114 legitimate technical uses, so the tell stays rubric, where the literal-versus-metaphor call has a reader. **Rejected — "let some mess in".** Five of the six adding-soul bullets survive as the rewrite guide's Adding voice section; that one does not, and the section is bounded twice over — by document register (never API reference tables) and by the fix flow's meaning-preservation guard, so voice changes how a kept claim is phrased and never invents one. **Adaptation note:** upstream's description ends "Must always apply"; the additions inherited the incumbent's posture instead — triggered, read-only by default, rewriting only when `fix` is passed as an explicit argument. **Not audited at the pin above.** This verdict was formed at integration time against upstream `main` with no revision recorded — the catalog and the rewrite guide both cite an unpinned blob URL, and the catalog's own four-part drift record covers the Wikipedia source page only — so `main@60c641e4` is this row's baseline for the next diff, not the state it was audited at. | | `show-me-your-work` | Four rules in [`implement-dispatch`'s deviation log](../../plugins/implementation/skills/implement-dispatch/SKILL.md), in [`implementation` 0.15.0](../../plugins/implementation/CHANGELOG.md); the formula-injection guard in [`claude-ops:audit-install-state`'s `install_state.py`](../../plugins/claude-ops/skills/audit-install-state/scripts/install_state.py), in [`claude-ops` 0.35.1](../../plugins/claude-ops/CHANGELOG.md) — see [below](#why-show-me-your-work-ships-neither-a-skill-nor-a-convention) | Absorbed (skill omitted) | **One of the ten lanes decided below** — unlike the `unslop` row above, which is not — and it gains a row because the recheck trigger reaches only the rows this table names, while this lane ships derived surfaces in two plugins. The omission argument, the eight-surface classification table it rests on, and the shape mismatch that killed the `session-flow:running-retro` premise are below and are not restated here; this row records what crossed over. **Taken — four rules into `implement-dispatch`'s `DEVIATIONS.md`:** append and supersede rather than edit or delete, the new entry naming what it supersedes, because rewriting history hides the reversal a PR reviewer most needs to see; evidence is a pointer (a SHA, a `file:line`, a test name, an artifact path) and preferably one a committed script produced, so the reviewer can re-run it rather than believe it — upstream splits that across its `evidence` column definition and a separate rule, merged here into one; an entry carries its outcome and says `unverified` rather than reading as settled; and one entry is one decision, since an entry that does not fit on a line or two is a decision that is not crisp yet. **Taken separately — the formula-injection guard from `scripts/log.sh`,** which prefixes any cell opening with `=`, `+`, `-`, or `@` with a single quote so a spreadsheet cannot execute it. It was absent fleet-wide, and looking for a landing site found a live exposure rather than a hypothetical one: `audit-install-state`'s `write_csv` already passed six walk-derived cells (`relpath`, `surface`, `number_meaning`, `liveness`, `liveness_reason`, `evidence`) straight through `csv.writer` into the artifact whose whole point is that a reader opens it row by row. It is now `csv_safe`, with `TestCsvFormulaInjection` confirmed discriminating against the guard disabled in memory. **Adapted — the guard is stricter here than upstream's.** Upstream's `clean()` rewrites tab, CR, and LF to spaces and only then tests the four leaders; `csv_safe` quotes rather than strips and treats a leading tab, CR, or LF as a formula leader in its own right, because a spreadsheet strips them before deciding, so `\t=cmd()` evaluates exactly as `=cmd()` does. Non-string cells — the integer byte counts, the boolean deny flag — pass through untouched. **Adapted — the trail's substance, not its artifact.** The four rules land as prose in an existing markdown log that a PR review reads, not as upstream's six-column TSV plus a shell appender; `DEVIATIONS.md` carries no `ts` or `phase` axis and gains none. **Adapted — the `unverified` rule cites rather than restates,** naming the identical grounding discipline `work-items:work-loop` and `source-control:babysit-loop` already apply to their cycle reports. **Rejected — the skill, and with it the marketplace convention it proposes.** Upstream's "Composing this skill" section tells other skills to route their audit trail here and let it own the format; that is a convention, and the classification below finds one genuine adopter — two if `session-flow:handoff` counts, and those two disagree about the one thing a shared format would have to fix. Upstream's own frontmatter sets `disable-model-invocation: true`, so even there the skill is reachable only by a typed invocation and its working value is the format other skills borrow, which is what was borrowed. **Rejected — the mandatory cross-model review of the trail.** Upstream is unconditional ("you **must** spawn a subagent on a different model family"), and it is this lane, not `arena`, that the `arena` row points at when separating a preference from a demand; it loses against the ~15 presence-gated-with-a-named-fallback sites counted below. **Rejected — the standing "Attention" section on every reply,** a session-wide output posture, which is a declared species here with exactly one member (`adhd:shape`). **Rejected as a duplicate — the log-versus-transcript self-audit,** whose discipline already ships verbatim in the two loop lanes named above. **Audited at the pin above.** Unlike the `unslop` row, this verdict was formed against `main@60c641e4`: the change that set that pin (`228a2b19`, 2026-08-21) is the same one that landed both absorbs and this file, so git history dates the derivation correctly and no date correction applies. Re-verified while adding this row — `pstack/skills/show-me-your-work/` is byte-identical between the pin and upstream `main@46125561` (read 2026-08-21), so the row lands with no drift outstanding. | @@ -85,13 +85,13 @@ elimination rounds versus a single parent-side comparison. A skill extracted acr have to make all of it configurable, which is the architecture plugin's own deletion test failing: deleting the shared shell would not concentrate complexity, it would only move it, since each caller would still supply its own generators, its own rubric, and its own convergence rule. That is the -definition of a shallow module, and `MIGRATION-PLAYBOOK.md:1630-1636` names extraction without a +definition of a shallow module, and `migration-playbook.md:1630-1636` names extraction without a second consumer speculative generality outright. **Every trigger it would claim is already taken.** A user asking for competing names reaches `naming`; competing interfaces, `architecture:improve`; competing UI layouts, `prototype:explore-directions`. A skill splits on distinct trigger vocabulary -(`MIGRATION-PLAYBOOK.md:27-33`), and `arena` has none of its own — it would sit in the always-listed +(`migration-playbook.md:27-33`), and `arena` has none of its own — it would sit in the always-listed description budget as a permanently-paid context line competing with the three skills that would actually run. @@ -140,7 +140,7 @@ three of its proposed **absorbs** also failed, each to a different rule: `session-flow:show-options` ("a design that ranks-then-truncates reintroduces the same gatekeeping through the cutoff"), which routes to `orient`. - **"Never quietly turn 'all' into 'recent N'"** is genuinely novel — `orient` has no scope-lock - step — and was still declined. `PLUGIN-PHILOSOPHY.md:574-578` admits a new standing instruction + step — and was still declined. `plugin-philosophy.md:574-578` admits a new standing instruction only on observed, repeated stumble evidence against the current model, named where the instruction is added. The only evidence available was that upstream says so. diff --git a/docs/upstream/mattpocock-skills.md b/docs/upstream/mattpocock-skills.md index a269d4d678..574322bd26 100644 --- a/docs/upstream/mattpocock-skills.md +++ b/docs/upstream/mattpocock-skills.md @@ -112,7 +112,7 @@ flip as [#2969](https://github.com/melodic-software/claude-code-plugins/issues/2 | Pruning: no-ops (model-relative, run-the-document test) | `claude-config:unhobble` (empirical — operationalizes his remove-and-observe test) + `audit-instructions` (judgment) | PARITY+ | | MECHANICS: invocation choice | rubric at `docs/conventions/invocation-mode/` (model-invoked default + exception classes; the setup convention was already documented in PLUGIN-PHILOSOPHY, contra this row's earlier "undocumented" reading); `skill-quality:check listing-budget` instrument | ADOPTED (adapted — inverted default; lane 8, 2026-08-17; enforcement → #2968) | | MECHANICS: splitting by invocation | rubric § Splitting by invocation; #2962's when-to-split doctrine points there | ADOPTED (routed; lane 8, 2026-08-17) | -| MECHANICS: router skills | rubric § Router-skill verdict; human-side answer = `docs/SKILL-CHEAT-SHEET.md` + `claude-ops:inventory`; composition-router carve-out (`discipline:sweep-all`) | REJECTED with reason (lane 8, 2026-08-17 — the always-present listing is the router under a model-invoked default) | +| MECHANICS: router skills | rubric § Router-skill verdict; human-side answer = `docs/skill-cheat-sheet.md` + `claude-ops:inventory`; composition-router carve-out (`discipline:sweep-all`) | REJECTED with reason (lane 8, 2026-08-17 — the always-present listing is the router under a model-invoked default) | | Invocation-reach invariant | tracked strand (below) | CONFIRMED (docs-verified 2026-08-17; lane 8 disposition below) | ## Tracked (event-triggered re-evaluation) diff --git a/plugins/actionlint/.claude-plugin/plugin.json b/plugins/actionlint/.claude-plugin/plugin.json index aa2a842048..534d86df9a 100644 --- a/plugins/actionlint/.claude-plugin/plugin.json +++ b/plugins/actionlint/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "actionlint", - "version": "0.8.46", + "version": "0.8.47", "description": "Lint GitHub Actions workflow files on edit via actionlint, surfacing findings as advisory context.", "author": { "name": "Melodic Software", diff --git a/plugins/actionlint/CHANGELOG.md b/plugins/actionlint/CHANGELOG.md index 48abb41f3e..5b9497a8ff 100644 --- a/plugins/actionlint/CHANGELOG.md +++ b/plugins/actionlint/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `actionlint` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.8.47] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.8.46] ### Changed diff --git a/plugins/actionlint/skills/setup/SKILL.md b/plugins/actionlint/skills/setup/SKILL.md index caf194d1e4..b4796e27e8 100644 --- a/plugins/actionlint/skills/setup/SKILL.md +++ b/plugins/actionlint/skills/setup/SKILL.md @@ -7,7 +7,7 @@ disable-model-invocation: true ## Purpose -Thin check-centric setup per the uniform setup contract (`docs/PLUGIN-PHILOSOPHY.md` +Thin check-centric setup per the uniform setup contract (`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in the marketplace repository): `check` inspects and reports, `apply` resolves. This plugin owns no consumer-project configuration. actionlint auto-discovers its own optional config from the repository, and the tunables are the native diff --git a/plugins/ai-briefing/.claude-plugin/plugin.json b/plugins/ai-briefing/.claude-plugin/plugin.json index 1e9457dfe9..e759cd430c 100644 --- a/plugins/ai-briefing/.claude-plugin/plugin.json +++ b/plugins/ai-briefing/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "ai-briefing", - "version": "0.7.28", + "version": "0.7.29", "description": "Build source-backed AI-industry briefings from official vendor publications, configured RSS/Atom feeds, GitHub releases, reputable secondary reporting, and user-supplied URLs. Deduplicate, rank, and present results as markdown or optional HTML/PPTX decks, with repository-owned profile, audience, and brand configuration. Automated X/Twitter collection is disabled; Playwright is used only for deterministic local rendering.", "author": { "name": "Melodic Software", diff --git a/plugins/ai-briefing/CHANGELOG.md b/plugins/ai-briefing/CHANGELOG.md index b7b114ac57..4321252ba5 100644 --- a/plugins/ai-briefing/CHANGELOG.md +++ b/plugins/ai-briefing/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `ai-briefing` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.7.29] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.7.28] ### Changed diff --git a/plugins/ai-briefing/skills/setup/SKILL.md b/plugins/ai-briefing/skills/setup/SKILL.md index f87282a6f7..ee190798dc 100644 --- a/plugins/ai-briefing/skills/setup/SKILL.md +++ b/plugins/ai-briefing/skills/setup/SKILL.md @@ -17,7 +17,7 @@ requested, install the optional deterministic presentation build toolchain. The repository- and organization-agnostic; consumers supply their own authorized sources, audience lens, and branding. -Check-centric per the uniform setup contract (`docs/PLUGIN-PHILOSOPHY.md` +Check-centric per the uniform setup contract (`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in the marketplace repository): `check` inspects and reports, `apply` scaffolds the profile, and the build-toolchain install is a distinct opt-in subaction rather than fused behind a flag. Tracked profile configuration belongs in diff --git a/plugins/autonomy/.claude-plugin/plugin.json b/plugins/autonomy/.claude-plugin/plugin.json index ca3792cb0c..69a2000402 100644 --- a/plugins/autonomy/.claude-plugin/plugin.json +++ b/plugins/autonomy/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "autonomy", - "version": "0.23.7", + "version": "0.23.8", "description": "Governed autonomous agent operation: role-topology, binding-seam, wiring-vs-advisor, telemetry, return-accounting, trigger-dispatch, per-work-class guardrail-matrix, standing-routine-catalog, and design-only runner-charter contracts for climbing the AI-adoption ladder, plus a guided-setup skill that discovers an adopting org's state, writes its schema-versioned binding, wires standards-pinned OTLP emission with a zero-cost file-artifact default, wires human-attested return capture at the task boundary, wires signal adapters with one governed dispatch entrypoint, binds the five-class guardrail matrix to an org's isolation substrates with an in-boundary live-validation probe before recording each fail-closed binding, and stands up standing-routine-catalog classes as scheduled temporal signal adapters behind the one governed queue with free scheduling defaults wired as reviewable changes and each routine's work-class mapping homed on the security surface.", "author": { "name": "Melodic Software", diff --git a/plugins/autonomy/CHANGELOG.md b/plugins/autonomy/CHANGELOG.md index aef2a009fb..31a2597dfc 100644 --- a/plugins/autonomy/CHANGELOG.md +++ b/plugins/autonomy/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `autonomy` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.23.8] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.23.7] ### Changed diff --git a/plugins/autonomy/skills/setup/SKILL.md b/plugins/autonomy/skills/setup/SKILL.md index 584ffea5a5..841d092eaa 100644 --- a/plugins/autonomy/skills/setup/SKILL.md +++ b/plugins/autonomy/skills/setup/SKILL.md @@ -314,7 +314,7 @@ scheduling surface recorded in two `surfaces` maps resolving as ambiguous, are c extends this skill. - Estimate, impute, or backfill the two human-attested return fields. Ever. - Write the plugin cache, Claude Code user settings, or `pluginConfigs`, per the uniform setup - contract (`docs/PLUGIN-PHILOSOPHY.md` "Setup is explicit and repeatable" in the marketplace + contract (`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in the marketplace repository). Nor platform settings. - Assume the shape of any particular org or fleet, a run against an unknown repo asks or defaults; it never guesses silently. diff --git a/plugins/bash-format/.claude-plugin/plugin.json b/plugins/bash-format/.claude-plugin/plugin.json index 776a8157d2..b23ab23adf 100644 --- a/plugins/bash-format/.claude-plugin/plugin.json +++ b/plugins/bash-format/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "bash-format", - "version": "0.7.47", + "version": "0.7.48", "description": "Auto-format and lint shell scripts on edit via shfmt + ShellCheck, using the consuming repo's own .editorconfig and .shellcheckrc.", "author": { "name": "Melodic Software", diff --git a/plugins/bash-format/CHANGELOG.md b/plugins/bash-format/CHANGELOG.md index 585c7cffd9..ab3b53b119 100644 --- a/plugins/bash-format/CHANGELOG.md +++ b/plugins/bash-format/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `bash-format` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.7.48] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.7.47] ### Changed diff --git a/plugins/bash-format/skills/setup/SKILL.md b/plugins/bash-format/skills/setup/SKILL.md index c1ffdc5c2e..81bdb9480e 100644 --- a/plugins/bash-format/skills/setup/SKILL.md +++ b/plugins/bash-format/skills/setup/SKILL.md @@ -7,7 +7,7 @@ disable-model-invocation: true ## Purpose -Thin check-centric setup per the uniform setup contract (`docs/PLUGIN-PHILOSOPHY.md` +Thin check-centric setup per the uniform setup contract (`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in the marketplace repository): `check` inspects and reports, `apply` resolves. This plugin owns no consumer-project configuration. Linting rules come from the repository's own `.shellcheckrc`, formatting from its `.editorconfig`, diff --git a/plugins/biome-format/.claude-plugin/plugin.json b/plugins/biome-format/.claude-plugin/plugin.json index 67054eb671..c6f612bffa 100644 --- a/plugins/biome-format/.claude-plugin/plugin.json +++ b/plugins/biome-format/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "biome-format", - "version": "0.6.45", + "version": "0.6.46", "description": "Auto-format and lint JS/TS/JSX/JSON on edit via Biome, only when a biome.json governs the repo, using the consuming repo's own Biome config.", "author": { "name": "Melodic Software", diff --git a/plugins/biome-format/CHANGELOG.md b/plugins/biome-format/CHANGELOG.md index 369a9b8727..1abcbda1b5 100644 --- a/plugins/biome-format/CHANGELOG.md +++ b/plugins/biome-format/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `biome-format` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.6.46] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.6.45] ### Changed diff --git a/plugins/biome-format/skills/setup/SKILL.md b/plugins/biome-format/skills/setup/SKILL.md index 109826b049..0323f44a5c 100644 --- a/plugins/biome-format/skills/setup/SKILL.md +++ b/plugins/biome-format/skills/setup/SKILL.md @@ -7,7 +7,7 @@ disable-model-invocation: true ## Purpose -Thin check-centric setup per the uniform setup contract (`docs/PLUGIN-PHILOSOPHY.md` +Thin check-centric setup per the uniform setup contract (`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in the marketplace repository): `check` inspects and reports, `apply` resolves. This plugin owns no consumer-project configuration. Rules come from the repository's own Biome config, and the only tunable is the native `userConfig` diff --git a/plugins/bugs/.claude-plugin/plugin.json b/plugins/bugs/.claude-plugin/plugin.json index ab701b6157..2a491a4ab4 100644 --- a/plugins/bugs/.claude-plugin/plugin.json +++ b/plugins/bugs/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "bugs", - "version": "0.10.2", + "version": "0.10.3", "description": "Produces from an informal defect description a structured five-field bug report: title, steps to reproduce, expected vs actual, severity with justification, and suggested fix location. Read-only by default: it emits the report and never edits code, opens a PR, or files an issue on its own.", "author": { "name": "Melodic Software", diff --git a/plugins/bugs/CHANGELOG.md b/plugins/bugs/CHANGELOG.md index abbf159c33..a17bc297e4 100644 --- a/plugins/bugs/CHANGELOG.md +++ b/plugins/bugs/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `bugs` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.10.3] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.10.2] ### Changed diff --git a/plugins/bugs/skills/setup/SKILL.md b/plugins/bugs/skills/setup/SKILL.md index 6cc00ace8c..69e116767e 100644 --- a/plugins/bugs/skills/setup/SKILL.md +++ b/plugins/bugs/skills/setup/SKILL.md @@ -139,7 +139,7 @@ a fresh session. - Do not produce or file a bug report; invoke `/bugs:write` via the Skill tool. - Do not run a hunt; that is `/bugs:scan`. This skill only verifies and writes its config. - Do not write the plugin cache, Claude Code user settings, or `pluginConfigs`, per the uniform - setup contract (`docs/PLUGIN-PHILOSOPHY.md` "Setup is explicit and repeatable" in the + setup contract (`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in the marketplace repository). - Do not delete the tracked config: `apply` converges to the configured state and never removes. - Do not invent an organization, repository, marketplace, or environment-variable prefix. diff --git a/plugins/claude-config/.claude-plugin/plugin.json b/plugins/claude-config/.claude-plugin/plugin.json index 78c0bd3154..024c000168 100644 --- a/plugins/claude-config/.claude-plugin/plugin.json +++ b/plugins/claude-config/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "claude-config", - "version": "0.42.4", + "version": "0.42.5", "description": "Nine configuration-health skills (plus setup) for a repo's Claude Code configuration: audit (settings.json / .mcp.json / hooks / plugins / permissions drift), audit-automation-gaps (evidence-gated verdicts on automation gaps), audit-permission-grants (allow-rule / allowed-tools grants for auto-mode durability and portability), audit-permission-state (the permission rules actually in effect: every settings scope merged with per-rule provenance, what auto mode drops on entry, config written where nothing reads it, and which managed intents are enforced versus loosenable), draft-auto-mode-rules (interview and draft a paste-ready autoMode classifier block; prints only, never writes), audit-instructions (locally-owned instruction surfaces vs current model capability, proposing removals/rewrites of instructions the model no longer needs, and detecting cross-surface instruction conflicts), audit-prompting-postures (the additive lane: posture guidance the prompting guide says a component's purpose needs but the component does not carry), audit-pass (one coordinated, ordered, resumable pass over a named target: three-scope inventory, run-time-derived exclusion set, stable finding identity, suppression memory, resume, one human gate, delegating every check to the plugin that owns it), and unhobble (the empirical bare-baseline experiment: reversibly strip a repo's standing instructions, log real stumbles against the current model, re-add only what evidence earns).", "author": { "name": "Melodic Software", diff --git a/plugins/claude-config/CHANGELOG.md b/plugins/claude-config/CHANGELOG.md index 8bb5aed5f2..380ddf0d79 100644 --- a/plugins/claude-config/CHANGELOG.md +++ b/plugins/claude-config/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `claude-config` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.42.5] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.42.4] ### Changed diff --git a/plugins/claude-config/README.md b/plugins/claude-config/README.md index c161fb43e4..ea2992f0e7 100644 --- a/plugins/claude-config/README.md +++ b/plugins/claude-config/README.md @@ -226,7 +226,7 @@ The marketplace's `renames` map still carries a historical `claude-config-audit` session. No action is needed for `audit`, `audit-automation-gaps`, and `audit-permission-grants`. That entry is a migration aid for consumers who predate the rename, not the marketplace's go-forward mechanism: the map is frozen-historical and later renames ship as clean breaking -changes (see the [migration playbook](../../docs/MIGRATION-PLAYBOOK.md#version-pinning-and-update-delivery)). +changes (see the [migration playbook](../../docs/migration-playbook.md#version-pinning-and-update-delivery)). The `memory-health` skill did **not** move to `claude-config`. It was extracted into the new, separate `claude-memory` plugin (now its `audit` skill). The rename only rewrites the `claude-config-audit` diff --git a/plugins/claude-config/skills/audit-instructions/SKILL.md b/plugins/claude-config/skills/audit-instructions/SKILL.md index fb22b42da3..e0170f47e0 100644 --- a/plugins/claude-config/skills/audit-instructions/SKILL.md +++ b/plugins/claude-config/skills/audit-instructions/SKILL.md @@ -257,7 +257,7 @@ high-stakes and correlated blind spots are the risk, prefer a cross-vendor advis installed and set up**, e.g. the OpenAI Codex plugin, when its documented surface can take this artifact, invoked per its own docs, with the fresh-context same-vendor subagent as the stated fallback, never a route to a command that may not resolve -(per `docs/PLUGIN-PHILOSOPHY.md` "Fresh-eyes checkpoints" in the marketplace repository). +(per `docs/plugin-philosophy.md` "Fresh-eyes checkpoints" in the marketplace repository). Batch one verifier per surface (not one per finding), counted under the same ~20-dispatch gate. A proposal the verifier defends is demoted to `info` or dropped, never surfaced as a confident removal. diff --git a/plugins/claude-config/skills/setup/SKILL.md b/plugins/claude-config/skills/setup/SKILL.md index ef5efb173b..55ed243634 100644 --- a/plugins/claude-config/skills/setup/SKILL.md +++ b/plugins/claude-config/skills/setup/SKILL.md @@ -7,7 +7,7 @@ disable-model-invocation: true ## Purpose -Setup per the uniform setup contract (`docs/PLUGIN-PHILOSOPHY.md` "Setup is explicit and repeatable" in +Setup per the uniform setup contract (`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in the marketplace repository): `check` inspects and reports, `apply` resolves. This plugin declares no `userConfig`, and has two setup concerns: diff --git a/plugins/claude-config/skills/unhobble/SKILL.md b/plugins/claude-config/skills/unhobble/SKILL.md index 529a630ccc..8dc9303123 100644 --- a/plugins/claude-config/skills/unhobble/SKILL.md +++ b/plugins/claude-config/skills/unhobble/SKILL.md @@ -85,8 +85,8 @@ means passing its phase commands from inside the same checkout its manifest name operator's call, default kept per the official carve-out). For hook entries specifically, the classification rubric, covering mechanism vs class, the hybrid trim-not-delete rule, and the ground-truth-oracle carve-out (behavioral purpose with a non-derivable machine oracle is a - keep), is owned by the marketplace's PLUGIN-PHILOSOPHY "Classifying a hook" section - (); + keep), is owned by the marketplace's plugin-philosophy "Classifying a hook" section + (); read it there and apply it to hooks, never re-derive it. Non-hook surfaces (rules, instruction files, skills, agents, plugins) classify by the class definitions above; `hybrid` applies to any unit whose behavioral and policy surfaces can be split in place. Classification is per unit that diff --git a/plugins/claude-ops/.claude-plugin/plugin.json b/plugins/claude-ops/.claude-plugin/plugin.json index 573175cda9..d557d69003 100644 --- a/plugins/claude-ops/.claude-plugin/plugin.json +++ b/plugins/claude-ops/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "claude-ops", - "version": "0.54.1", + "version": "0.54.2", "description": "Claude Code operations toolkit. Twelve skills: audit-skill-visibility (audit whether each installed skill is actually VISIBLE to the model, and diagnose why most of a fleet never gets used: a skill is invisible when its description is dropped by Claude Code's skill-listing context budget, which sheds descriptions lowest-score-first so an unused skill loses the keywords that would let it be matched, from skills genuinely not wanted, from skills the run cannot observe at all; computes whether the listing overflows from documented settings, and withholds every cold verdict the data cannot support rather than reporting absence of data as absence of use), inventory (read-only enumeration of the complete invocable surface: every built-in CLI command with aliases and hidden/gated status, every bundled skill, and every component of every installed plugin across all marketplaces; reads the shipped binary because upstream publishes no built-in command list, and carries an integrity verdict so a drifted build reports counts as floors rather than silently short totals), audit-install-state (read-only audit of the machine-scope ~/.claude installation directory and ~/.claude.json: full inventory split into an authored surface and rolled-up bulk trees, product-managed retention vs genuinely unmanaged state, filename-scheme resolution before any process-liveness check, and deliberate/mid-experiment detection; reports, never deletes), audit-performance (read-only slowness-diagnostic capture run at the moment the machine or a session feels slow: CLI version, retention-sweep health including the silent unparsable-settings pause, a timed census walk of the install tree as a sweep-cost proxy, active-session and plugin-fleet counts, a process census, and the fan-out layer, which covers a load-labelled no-op spawn baseline, every hook that will fire bucketed per-tool-call versus per-turn with its invocation shape, the configured statusline, subagent concurrency and spawn-depth ceilings against documented defaults, whether running sessions predate the settings file they are judged by, and orphan attribution by parent liveness rather than age, plus on Windows a kernel-object census (Token objects against uptime, paged pool) that names a host-level leak beneath all four suspects; read against a bundled known-performance-issues reference that also records the causes tested and cleared; separates the four documented suspects of accumulated state, version regression, component bloat, and per-spawn fan-out cost, and routes remediation out; reports, never mutates, and never executes a discovered hook or statusline command), audit-native-overlap (map native Claude Code surfaces, namely built-in CLI commands, bundled skills, plugin-backed built-ins, and session-provided skills, against the current repo's plugin skills and agents, so a custom component never silently duplicates what Claude Code itself ships; bare invocation is a read-only overlap report carrying the extraction's integrity floors and a shared-listing-budget exposure section, verdicts are human-gated in a committed store rendered into a generated registry whose every row carries an observable recheck trigger, and only an explicit apply step bakes presence-gated native references into descriptions and Boundary sections), observability (read locally captured telemetry from the OTEL store, the collector, the per-session hook event log and hook-event JSONL, and ccusage, with trend reports, a per-session report of what fired, what was blocked and the event timeline, and store pruning), known-issues (search known Claude product GitHub bugs, check service health, maintain a persistent tracked-issue registry), changelog (ingest Claude Code changelog entries and integrate them into the current repo), plugins (bring a machine's plugin fleet current on demand: marketplace refresh, effective-scope updates including in-repo project/local installs, new-plugin install per policy, scope-divergence detection and explicit convergence), morning-brief (read-only gh-based operator morning view: queue-label counts, merge-ready PRs, parked decisions with their RECOMMENDED lines, and loop-lane telemetry freshness), lanes (start/restart/stop/status loop lanes as named background Claude Code sessions seeded from canonical prompt files, with per-lane model/effort, a repo-pull + marketplace-refresh launch step, and a consume-restarts action, an OS-schedulable reader that relaunches stopped lanes whose telemetry carries a restart_request), and a re-runnable setup action that settles where the known-issues registry, the skill-usage log and the hook log root live, places the root's self-ignoring guard, and detects retired conventions. Plus an opt-in, default-off per-session hook event log (one JSON line per hook event on every event the generated registry marks observable, written to /sessions/.jsonl, with SessionEnd retention by session count or age and an optional detached pre-prune command), a family of eight advisory *-audit hooks (API errors, config changes, instruction loads, permission denials, pre-compaction, skill usage, tool failures, and unsurfaced hook failures. The last also warns the user via systemMessage, since a hook that fails to launch enforces nothing and Claude Code surfaces the failure to nobody) that emit the shared hook-telemetry envelope, and a reference sink that routes envelopes under the same root: per session when the envelope carries a session id, else into the shared hook-events.jsonl the observability skill reads.", "author": { "name": "Melodic Software", diff --git a/plugins/claude-ops/CHANGELOG.md b/plugins/claude-ops/CHANGELOG.md index dc061d580b..14169e7ee3 100644 --- a/plugins/claude-ops/CHANGELOG.md +++ b/plugins/claude-ops/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `claude-ops` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.54.2] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.54.1] ### Changed diff --git a/plugins/claude-ops/README.md b/plugins/claude-ops/README.md index 7be816465a..6c62cedd6d 100644 --- a/plugins/claude-ops/README.md +++ b/plugins/claude-ops/README.md @@ -35,7 +35,7 @@ Claude Code's native OTEL cannot see. |---|---| | `/claude-ops:audit-skill-visibility` | Audits whether the model can actually **see** each installed skill, the question behind "why does most of my fleet never get used?", since a skill the model cannot see can never be chosen. Reports three independent things per skill: **reachability** (visible, `user-only` by design, hidden by an override or disabled plugin, or invisibly misconfigured), **observation** (what usage was actually recorded, always horizon-qualified), and **starvation** (whether it is losing the description-budget contest: Claude Code drops descriptions starting with the skills you invoke least, so an unused skill loses the keywords a request would match and stays unused). Whether the listing overflows is computed from documented settings; which particular skills lose their descriptions is a labelled likelihood band, never an exact cutoff. Withholds every cold verdict the data cannot support instead of reporting absence of data as absence of use. Read-only. | | `/claude-ops:audit-install-state` | Read-only audit of the machine-scope Claude Code installation directory, the `~/.claude` tree plus the home-root `~/.claude.json`. Inventories every file (entries labelled as an authored surface or a rolled-up bulk tree, with the complete per-file rows in a CSV artifact), separates what Claude Code's own `cleanupPeriodDays` sweep already manages from what nothing manages, resolves what each number in a filename actually *is* before attempting any process-liveness lookup, and deny-lists any subtree holding a revert ledger before classifying anything as stale. Never deletes; hands off to `claude project purge` and `/disk-hygiene:clean`. | -| `/claude-ops:audit-native-overlap` | Maps native Claude Code surfaces, built-in CLI commands, bundled skills, plugin-backed built-ins, session-provided skills, against the current repo's plugin skills and agents. Bare invocation is a read-only overlap report (candidates with evidence, detection integrity floors carried through, and a shared-listing-budget exposure section); verdicts (`prefer-native` / `prefer-ours` / `complementary` / `superseded` / `defer`) are human-gated in a committed store (`docs/native-surfaces/records.json`) rendered into a generated registry (`docs/NATIVE-SURFACES.md`) whose every row carries an observable recheck trigger; only an explicit `apply` step bakes presence-gated native references into component descriptions and Boundary sections. | +| `/claude-ops:audit-native-overlap` | Maps native Claude Code surfaces, built-in CLI commands, bundled skills, plugin-backed built-ins, session-provided skills, against the current repo's plugin skills and agents. Bare invocation is a read-only overlap report (candidates with evidence, detection integrity floors carried through, and a shared-listing-budget exposure section); verdicts (`prefer-native` / `prefer-ours` / `complementary` / `superseded` / `defer`) are human-gated in a committed store (`docs/native-surfaces/records.json`) rendered into a generated registry (`docs/native-surfaces.md`) whose every row carries an observable recheck trigger; only an explicit `apply` step bakes presence-gated native references into component descriptions and Boundary sections. | | `/claude-ops:audit-performance` | Read-only slowness-diagnostic capture, run at the moment the machine or a session feels slow, before restarting or deleting anything. One timed engine pass separates four documented suspects: accumulated install-tree state, version regression, component bloat, and the fan-out layer, plus on Windows a kernel-object census that names the host-level Token-object leak beneath all four. Each suspect's evidence and verdict routing is documented in the skill. Phase timings are first-class evidence; content reads are allowlisted to four non-secret config files (`settings.json`, `.last-cleanup`, `hooks.json`, `installed_plugins.json`), so `~/.claude.json` and `history.jsonl` stay stat-only. Reports and routes; never mutates, never elevates, and never executes a discovered hook or statusline command. | | `/claude-ops:observability` | Reads locally captured Claude Code telemetry, OTEL DuckDB store, machine-owned collector, optional Aspire dashboard, hook-event JSONL, ccusage, and renders cross-session trend reports (`session`/`day`/`week`/`month`/`since:`/`all` scopes). Read-only except the explicit `clean` action, which prunes the JSONL log and OTEL store by age. | | `/claude-ops:known-issues` | Searches known Claude product GitHub bugs before you build on a feature, checks service health and model quality, and maintains a persistent registry of tracked issues (what they block, workarounds, follow-ups when fixed). Actions: `status` (default), `search`, `check-all`, `scan`, `list`, `quality`, `create`. | diff --git a/plugins/claude-ops/skills/audit-native-overlap/SKILL.md b/plugins/claude-ops/skills/audit-native-overlap/SKILL.md index ada2844129..ed0e8989c9 100644 --- a/plugins/claude-ops/skills/audit-native-overlap/SKILL.md +++ b/plugins/claude-ops/skills/audit-native-overlap/SKILL.md @@ -188,7 +188,7 @@ Three artifacts, one direction of flow: provenance class and hidden/gated markers, our component, the verdict and its reason, evidence, a class-tagged observation record, a recheck trigger with its verified date, `baked` flags, and the budget caveat. -2. **The generated view**. `docs/NATIVE-SURFACES.md`, rendered from the store between HTML +2. **The generated view**. `docs/native-surfaces.md`, rendered from the store between HTML markers, per provenance lane. Never hand-edited; a `--check` mode regenerates and diffs. 3. **The self-check**, a deterministic script over what is locally decidable: store parses and declares its schema, every row carries a trigger, records are well-formed including their diff --git a/plugins/claude-ops/skills/audit-native-overlap/scripts/overlap.py b/plugins/claude-ops/skills/audit-native-overlap/scripts/overlap.py index 4d74013c4c..aad2eac415 100755 --- a/plugins/claude-ops/skills/audit-native-overlap/scripts/overlap.py +++ b/plugins/claude-ops/skills/audit-native-overlap/scripts/overlap.py @@ -1325,7 +1325,7 @@ def add_paths(sub: argparse.ArgumentParser) -> None: sub.add_argument( "--view", default=None, - help="generated registry view (default: /docs/NATIVE-SURFACES.md)", + help="generated registry view (default: /docs/native-surfaces.md)", ) detect = subparsers.add_parser( @@ -1394,7 +1394,7 @@ def main(argv: list[str] | None = None) -> int: if args.store is None: args.store = str(repo / "docs" / "native-surfaces" / "records.json") if args.view is None: - args.view = str(repo / "docs" / "NATIVE-SURFACES.md") + args.view = str(repo / "docs" / "native-surfaces.md") if args.command == "detect": return cmd_detect(args) diff --git a/plugins/claude-ops/skills/audit-native-overlap/scripts/test_overlap.py b/plugins/claude-ops/skills/audit-native-overlap/scripts/test_overlap.py index fbf8f66393..a5adede544 100755 --- a/plugins/claude-ops/skills/audit-native-overlap/scripts/test_overlap.py +++ b/plugins/claude-ops/skills/audit-native-overlap/scripts/test_overlap.py @@ -88,7 +88,7 @@ def __init__(self, rows=None): self._tmp = tempfile.TemporaryDirectory() self.root = Path(self._tmp.name) self.store_path = self.root / "docs" / "native-surfaces" / "records.json" - self.view_path = self.root / "docs" / "NATIVE-SURFACES.md" + self.view_path = self.root / "docs" / "native-surfaces.md" self.store_path.parent.mkdir(parents=True, exist_ok=True) self.write_store(make_store(rows if rows is not None else [BASE_ROW])) # BASE_ROW claims a Boundary section, so the component it names exists diff --git a/plugins/claude-ops/skills/setup/SKILL.md b/plugins/claude-ops/skills/setup/SKILL.md index 7dade4f25b..515164566d 100644 --- a/plugins/claude-ops/skills/setup/SKILL.md +++ b/plugins/claude-ops/skills/setup/SKILL.md @@ -7,7 +7,7 @@ disable-model-invocation: true ## Purpose -Setup under the uniform setup contract (`docs/PLUGIN-PHILOSOPHY.md` "Setup is explicit and +Setup under the uniform setup contract (`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in the marketplace repository). This plugin's configuration surface is native `userConfig` scalars that Claude Code owns (`registry_dir`, `skill_usage_dir`, `skill_usage_scope`, and the six `session_*` hook-logging options): Claude Code prompts for them when the plugin is diff --git a/plugins/code-tidying/.claude-plugin/plugin.json b/plugins/code-tidying/.claude-plugin/plugin.json index ff07c8e73c..e1af01e28b 100644 --- a/plugins/code-tidying/.claude-plugin/plugin.json +++ b/plugins/code-tidying/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "code-tidying", - "version": "0.19.1", + "version": "0.19.2", "description": "Code tidying and comment hygiene: /code-tidying:tidy proactively hunts a rotated, glob-scoped lane for Beck-style tidyings under a research-backed scope budget and ships one tight PR; /code-tidying:batch-simplify sweeps a time window, a branch, or an entire repository through grouped, dependency-ordered simplification waves with a fix-first deferral contract that resolves deferrals in the same run instead of filing issues; /code-tidying:dissolve-comments enforces self-describing expressive code over a diff or target, widening to the branch diff and then the whole repository when the tree is clean: it deletes zero-information comments, dissolves code-expressible ones into names and structure behind a tests gate (safe mode restricts applied edits to removals), and keeps only terse load-bearing comments code cannot express; /code-tidying:audit-comment-residue is a read-only classifier that flags history, plan, conversational, and ticket/PR residue in code comments for author-applied deletion; /code-tidying:audit-dead-code is a read-only whole-repo dead-code hunter running four labelled lanes of unequal confidence (knip for TS/JS, vulture for Python, gopls for Go, and a portable grep lane for shell and other symbol languages), adjudicating every candidate against dynamic-usage evidence into a dead, uncertain, or alive verdict. Project-specific tidy lanes are scaffolded into a tracked .claude/tidy-lanes/ config folder by a re-runnable setup skill.", "author": { "name": "Melodic Software", diff --git a/plugins/code-tidying/CHANGELOG.md b/plugins/code-tidying/CHANGELOG.md index 814d1a413c..3d6364a184 100644 --- a/plugins/code-tidying/CHANGELOG.md +++ b/plugins/code-tidying/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `code-tidying` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.19.2] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.19.1] ### Changed diff --git a/plugins/code-tidying/skills/setup/SKILL.md b/plugins/code-tidying/skills/setup/SKILL.md index 01ecc7b41b..f43f740f53 100644 --- a/plugins/code-tidying/skills/setup/SKILL.md +++ b/plugins/code-tidying/skills/setup/SKILL.md @@ -16,7 +16,7 @@ per-section with the bundled lane; a lane without it resolves project-only. Project lanes are optional: with none, `/code-tidying:tidy` uses the bundled lanes, so their absence is a reported INFO, never a FAIL. Check-centric per the uniform setup contract -(`docs/PLUGIN-PHILOSOPHY.md` "Setup is explicit and repeatable" in the marketplace repository): +(`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in the marketplace repository): `check` inspects read-only; `apply` scaffolds or retunes lanes, then re-runs `check`. No argument or `check` runs the check; `apply` runs the check first, then the scaffold flow. `apply ` targets a single lane. Idempotent: re-running reads the existing lane files and proposes additions or edits diff --git a/plugins/code-tidying/skills/tidy/reference/exclusions.md b/plugins/code-tidying/skills/tidy/reference/exclusions.md index 7491331bbb..b20a958f34 100644 --- a/plugins/code-tidying/skills/tidy/reference/exclusions.md +++ b/plugins/code-tidying/skills/tidy/reference/exclusions.md @@ -96,7 +96,7 @@ If during a self-update run you find drift in any of the following, **clean exit Everything **path-based** in section 1 is overridable. A path exclusion is a default, not a law: it exists because an autonomous hunt has no reason to be in that file, which is a different claim from "the user may not ask for it". `/code-tidying:dissolve-comments override ruff.toml` is a legitimate request, and a list that cannot express it forces the user to edit by hand what the skill exists to do. -Three channels lift it, each owning one row of the config-ownership table in `docs/PLUGIN-PHILOSOPHY.md` "Configuration ownership and scope". +Three channels lift it, each owning one row of the config-ownership table in `docs/plugin-philosophy.md` "Configuration ownership and scope". | Channel | Table row | Form | Reach | |---|---|---|---| diff --git a/plugins/codebase-health/.claude-plugin/plugin.json b/plugins/codebase-health/.claude-plugin/plugin.json index 7720f4477d..70538f3171 100644 --- a/plugins/codebase-health/.claude-plugin/plugin.json +++ b/plugins/codebase-health/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "codebase-health", - "version": "0.9.3", + "version": "0.9.4", "description": "Repo-wide drift audit between docs, config, code, and architecture: verifies every factual claim against reality via parallel subagent fan-out, severity-rates findings, and reports read-only, delegating remediation to the implementation/verification lanes. Audit dimensions are configurable through a tracked .claude/codebase-health.md config file written by the setup skill.", "author": { "name": "Melodic Software", diff --git a/plugins/codebase-health/CHANGELOG.md b/plugins/codebase-health/CHANGELOG.md index afc8694c2e..cedbe525e7 100644 --- a/plugins/codebase-health/CHANGELOG.md +++ b/plugins/codebase-health/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `codebase-health` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.9.4] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.9.3] ### Changed diff --git a/plugins/codebase-health/skills/audit/SKILL.md b/plugins/codebase-health/skills/audit/SKILL.md index af6356e27c..cdfdd5c439 100644 --- a/plugins/codebase-health/skills/audit/SKILL.md +++ b/plugins/codebase-health/skills/audit/SKILL.md @@ -216,7 +216,7 @@ rubber-stamps it; an independent agent re-reading the doc claim AND the actual c false positives and miscategorized-but-correct claims. Where the finding set is high-stakes and correlated blind spots are the risk, prefer a cross-vendor advisor **when one is installed and set up**, e.g. the OpenAI Codex plugin, when its documented surface can take this artifact, invoked per its own docs, with the fresh-context same-vendor subagent as the stated fallback, never a route to a command that may not resolve -(per `docs/PLUGIN-PHILOSOPHY.md` "Fresh-eyes checkpoints" in the marketplace repository). +(per `docs/plugin-philosophy.md` "Fresh-eyes checkpoints" in the marketplace repository). Fence each validator to read-only (its findings' files + verification-sources). diff --git a/plugins/context-budget/.claude-plugin/plugin.json b/plugins/context-budget/.claude-plugin/plugin.json index 05977d48c9..611fe4a255 100644 --- a/plugins/context-budget/.claude-plugin/plugin.json +++ b/plugins/context-budget/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "context-budget", - "version": "0.6.27", + "version": "0.6.28", "description": "Measure a Claude Code session's fixed startup context payload per item, on the consumer's machine at a pinned, version-stamped binary, including per-tool attribution of the built-in tool pools that /context reports only as lump sums, derived live by A/B bare-name-deny differencing with enforced comparability rules (skill-listing signature, one mode, one binary), an SDK-primary exact meter degrading to a version-aware headless /context parser and then to an honest structured error (never a wrong number), and a per-project measure-toggle-remeasure ledger under the plugin data directory recording every lever's real before/after delta. Report-only: prints exact config, applies nothing.", "author": { "name": "Melodic Software", diff --git a/plugins/context-budget/CHANGELOG.md b/plugins/context-budget/CHANGELOG.md index 97021048bd..d848365c16 100644 --- a/plugins/context-budget/CHANGELOG.md +++ b/plugins/context-budget/CHANGELOG.md @@ -5,6 +5,12 @@ All notable changes to the `context-budget` plugin. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [0.6.28] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.6.27] ### Changed diff --git a/plugins/context-budget/skills/setup/SKILL.md b/plugins/context-budget/skills/setup/SKILL.md index d4f6f575a8..4e5bf7667f 100644 --- a/plugins/context-budget/skills/setup/SKILL.md +++ b/plugins/context-budget/skills/setup/SKILL.md @@ -7,7 +7,7 @@ disable-model-invocation: true ## Purpose -Check-only setup under the Check-only carve-out (`docs/PLUGIN-PHILOSOPHY.md` "Setup is explicit +Check-only setup under the Check-only carve-out (`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in the marketplace repository): this plugin's configuration surface contains no writable artifact, so `check` inspects, reports, and points at each remediation, and no `apply` is offered because there is nothing it could conformingly write. The warrant is the carve-out's diff --git a/plugins/context-guard/.claude-plugin/plugin.json b/plugins/context-guard/.claude-plugin/plugin.json index 737b0e71ab..61f07f3dce 100644 --- a/plugins/context-guard/.claude-plugin/plugin.json +++ b/plugins/context-guard/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "context-guard", - "version": "0.7.56", + "version": "0.7.57", "description": "Per-session context-window observability plus the first shipped consumer: a statusline wrapper tees each session's context_window fields to a per-session snapshot file, a zone resolver classifies usage into smart/acceptable/dumb bands (percentage bands plus window-class token bands, conservative-min combination, zones.json SSOT with shipped defaults), a reader contract fixes how consuming sessions interpret the snapshots, and zone-crossing hooks report once per transition into a worse zone across two channels: the continuation menu to the operator, who owns that choice, and to the model only the zone determination plus the counter-steer that a zone word is not a decay signal (advisory by default; an optional blocking mode gates new mutating work on a fresh dumb-zone snapshot with handoff-writing exempt), with a PostCompact hook persisting an evidence-degraded marker.", "author": { "name": "Melodic Software", diff --git a/plugins/context-guard/CHANGELOG.md b/plugins/context-guard/CHANGELOG.md index ad96d7d412..d9205f972a 100644 --- a/plugins/context-guard/CHANGELOG.md +++ b/plugins/context-guard/CHANGELOG.md @@ -5,6 +5,12 @@ All notable changes to the `context-guard` plugin. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [0.7.57] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.7.56] ### Changed diff --git a/plugins/context-guard/skills/setup/SKILL.md b/plugins/context-guard/skills/setup/SKILL.md index b8022f6d48..7b06766292 100644 --- a/plugins/context-guard/skills/setup/SKILL.md +++ b/plugins/context-guard/skills/setup/SKILL.md @@ -283,7 +283,7 @@ fallback lives in the file that was just deleted. ## What this skill does not do - Write the plugin cache, Claude Code user settings, or `pluginConfigs`, per the uniform setup - contract (`docs/PLUGIN-PHILOSOPHY.md` "Setup is explicit and repeatable" in the marketplace + contract (`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in the marketplace repository). Nor `settings.json` (user or project) or any other Claude Code settings surface; the printed edit is the operator's to apply. - Install `jq` or any system package. - Write to the snapshot directory `~/.claude/context-guard/context/`, the tee owns those files. diff --git a/plugins/context7/.claude-plugin/plugin.json b/plugins/context7/.claude-plugin/plugin.json index c5a0dae5c1..7ee1d49c27 100644 --- a/plugins/context7/.claude-plugin/plugin.json +++ b/plugins/context7/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "context7", - "version": "0.5.5", + "version": "0.5.6", "description": "Looks up current library documentation, API references, and code examples via Context7 (ctx7 CLI or the Context7 MCP server) with a two-step resolve-then-query workflow: a lookup skill (default lookup plus an upstream drift-check action) and a setup skill for CLI install, auth, and MCP configuration.", "author": { "name": "Melodic Software", diff --git a/plugins/context7/CHANGELOG.md b/plugins/context7/CHANGELOG.md index 9440eb058f..5611d239d0 100644 --- a/plugins/context7/CHANGELOG.md +++ b/plugins/context7/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `context7` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.5.6] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.5.5] ### Changed diff --git a/plugins/context7/skills/setup/SKILL.md b/plugins/context7/skills/setup/SKILL.md index 4d1bc34f15..a7dfb71782 100644 --- a/plugins/context7/skills/setup/SKILL.md +++ b/plugins/context7/skills/setup/SKILL.md @@ -23,7 +23,7 @@ Bring the local environment to a working state for `/context7:lookup`. Two indep either alone sufficient: the **CLI** (`ctx7` via npm) and the **Context7 MCP server** (configured by the consuming project). An optional `CONTEXT7_API_KEY` raises rate limits for both. -Check-centric per the uniform setup contract (`docs/PLUGIN-PHILOSOPHY.md` +Check-centric per the uniform setup contract (`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in the marketplace repository): `check` inspects and reports, `apply` resolves what `check` found, and the CLI install is a distinct opt-in subaction. Idempotent and transparent: safe to rerun. diff --git a/plugins/desktop-notification/.claude-plugin/plugin.json b/plugins/desktop-notification/.claude-plugin/plugin.json index b96df22c40..9c81933860 100644 --- a/plugins/desktop-notification/.claude-plugin/plugin.json +++ b/plugins/desktop-notification/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "desktop-notification", - "version": "0.6.39", + "version": "0.6.40", "description": "Alert you when Claude Code needs input: an audible terminal bell, an OSC 9 terminal notification, and an OS-native toast (macOS/Linux) on permission and idle prompts.", "author": { "name": "Melodic Software", diff --git a/plugins/desktop-notification/CHANGELOG.md b/plugins/desktop-notification/CHANGELOG.md index 2324967bbf..5562ee2f04 100644 --- a/plugins/desktop-notification/CHANGELOG.md +++ b/plugins/desktop-notification/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `desktop-notification` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.6.40] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.6.39] ### Changed diff --git a/plugins/desktop-notification/skills/setup/SKILL.md b/plugins/desktop-notification/skills/setup/SKILL.md index 87efa27a62..7460bf97e8 100644 --- a/plugins/desktop-notification/skills/setup/SKILL.md +++ b/plugins/desktop-notification/skills/setup/SKILL.md @@ -7,7 +7,7 @@ disable-model-invocation: true ## Purpose -Thin check-centric setup per the uniform setup contract (`docs/PLUGIN-PHILOSOPHY.md` +Thin check-centric setup per the uniform setup contract (`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in the marketplace repository): `check` inspects and reports, `apply` resolves. This plugin owns no consumer-project configuration. The only tunables are the four native `userConfig` toggles (master + one per channel), and every diff --git a/plugins/discipline/.claude-plugin/plugin.json b/plugins/discipline/.claude-plugin/plugin.json index 8469abba56..42a36dc9c8 100644 --- a/plugins/discipline/.claude-plugin/plugin.json +++ b/plugins/discipline/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "discipline", - "version": "0.14.4", + "version": "0.14.5", "description": "Discipline correctors that re-anchor a standing rule mid-session, then audit both the work in flight and the pre-existing state and choices it trusts, and correct what has drifted: do-your-research (research and no-assumptions discipline; sibling do-your-research-deep escalates to a typed full inventory of the session's claims, namely assumptions, asserted facts, concrete specifics, and load-bearing premises, verified at a configurable depth and reported as a per-item ledger), follow-our-standards (alignment to the consuming org's engineering conventions), point-dont-copy (pointer-over-copy discipline: no copied content, internal-name coupling, or closed capability lists), reason-dont-recite (interrogate inherited content, since precedent is evidence of what is, never self-justifying authority), tighten-your-output (terseness discipline: fewer words or lines with no loss of meaning or correctness), recheck-against-upstream (existing state is not evidence of its own correctness, so audit config, code, and infra against current official upstream docs; sibling recheck-against-upstream-deep fans subagents doc-by-doc over a whole subsystem), pick-for-the-problem (tool, library, framework, and approach selection fitted to the problem, not reached for out of habit, availability, incumbency, or preconception), mind-your-maxims (cooperative-communication discipline per Grice plus the AI-augmented transparency maxim), script-the-deterministic-work (offload the deterministic sub-work of counts, diffs, sorts, transforms, and scaffolds to a script that runs, reserving model output for judgment over its real output; the audit runs both ways, also catching an existing script that over-reaches into judgement), use-your-skills (actually use the skills already in context: scan the listing, map the task, invoke the fitting skill instead of reinventing it, and name skills when delegating to a subagent), and reuse-or-replace (anti-fragmentation: new work reuses an established way of doing something or openly replaces it (migrate the old uses, record the decision), never silently stands up a second parallel way; divergence is allowed but owes a recorded reason proportional to blast radius), and scrutinize-dont-coast (adversarial self-scrutiny: stop coasting on your own recent output and re-examine whether it is sound, not merely confidently produced, through a fresh-context pass blind to the reasoning that made it, then remediate with the user; it stops the trajectory first and remediates collaboratively rather than autonomously). Plus further species that are not correctors (examples, not a fixed list, since each skill's own description is authoritative), including setup, sweep-all, a posture-batch runbook that composes them by fanning out an audit-only subagent per in-scope corrector, then applying the corrections on the main thread in a fixed order, with batch membership and order set by each corrector's own colocated tier metadata and an optional userConfig overlay, and wait-what, a one-shot user-invoked-only communication repair: type /discipline:wait-what when the last message did not land and the model re-pitches it, backing up as far as needed, adding the missing context, in ASD-STE100 Simplified Technical English, using the project's ubiquitous language; never model-invoked and never in the batch, and hold-my-hand, a standing session posture (neither a corrector nor a one-shot): it partitions the remaining work into phases and presents only the current one, never the phases after it beyond a one-line count, each phase naming where to be, numbered steps with exact commands, the expected output, the common failure, who performs each step, and the exact reply that advances; it stays out of the batch because a sweep must never impose a delivery posture the user did not ask for. Firing a corrector is a re-anchor, not an accusation; the audit may return clean.", "author": { "name": "Melodic Software", diff --git a/plugins/discipline/CHANGELOG.md b/plugins/discipline/CHANGELOG.md index 99999dadc3..5830b9c217 100644 --- a/plugins/discipline/CHANGELOG.md +++ b/plugins/discipline/CHANGELOG.md @@ -5,6 +5,12 @@ All notable changes to the `discipline` plugin are documented here. Format follo Entries below `0.9.0` were released under the plugin's former name, `re-anchor`. +## [0.14.5] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.14.4] ### Changed diff --git a/plugins/discipline/context/re-anchor-audit-correct.md b/plugins/discipline/context/re-anchor-audit-correct.md index 1579b6fa13..1f542052bb 100644 --- a/plugins/discipline/context/re-anchor-audit-correct.md +++ b/plugins/discipline/context/re-anchor-audit-correct.md @@ -53,7 +53,7 @@ Run these in order. Skip a step only when its input is genuinely absent One example is the OpenAI Codex plugin, when its documented surface can take this artifact, invoked per its own docs. Keep the fresh-context same-vendor subagent as the stated fallback, never a route to a command that may not resolve - (per `docs/PLUGIN-PHILOSOPHY.md` "Fresh-eyes checkpoints" in the marketplace repository). + (per `docs/plugin-philosophy.md` "Fresh-eyes checkpoints" in the marketplace repository). Surface anything that cannot be corrected here rather than papering over it. **Outward artifacts are the one carve-out:** correcting forward never *files* an diff --git a/plugins/discipline/skills/setup/SKILL.md b/plugins/discipline/skills/setup/SKILL.md index e64b86590c..681f32bd2c 100644 --- a/plugins/discipline/skills/setup/SKILL.md +++ b/plugins/discipline/skills/setup/SKILL.md @@ -92,7 +92,7 @@ Official contract: (the page -`docs/OFFICIAL-DOCS.md` indexes for subagents), quoting it: +`docs/official-docs.md` indexes for subagents), quoting it: - The parent has the identifier it needs: "When a subagent completes, Claude receives its agent ID." - The mechanism: "Claude uses the `SendMessage` tool with the agent's ID or name as the `to` field diff --git a/plugins/disk-hygiene/.claude-plugin/plugin.json b/plugins/disk-hygiene/.claude-plugin/plugin.json index eddeb3bd5e..d8e613c604 100644 --- a/plugins/disk-hygiene/.claude-plugin/plugin.json +++ b/plugins/disk-hygiene/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "disk-hygiene", - "version": "0.23.6", + "version": "0.23.7", "description": "Context-aware disk hygiene for arbitrary directory trees: inventories orphaned and temporary artifacts, classifies evidence into review tiers, and offers exact-path cleanup only after a fresh safety preview and explicit per-tier approval. The target is read-only by default; OS-managed paths, links and mount points, VCS-tracked content without the complete checkout evidence bundle, changed entries, and live-handle uncertainty fail closed.", "author": { "name": "Melodic Software", diff --git a/plugins/disk-hygiene/CHANGELOG.md b/plugins/disk-hygiene/CHANGELOG.md index 28870d2565..74d5148983 100644 --- a/plugins/disk-hygiene/CHANGELOG.md +++ b/plugins/disk-hygiene/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `disk-hygiene` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.23.7] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.23.6] ### Changed diff --git a/plugins/disk-hygiene/skills/setup/SKILL.md b/plugins/disk-hygiene/skills/setup/SKILL.md index 6e4258b502..c7408ba95a 100644 --- a/plugins/disk-hygiene/skills/setup/SKILL.md +++ b/plugins/disk-hygiene/skills/setup/SKILL.md @@ -7,7 +7,7 @@ disable-model-invocation: true ## Purpose -Thin check-centric setup per the uniform setup contract (`docs/PLUGIN-PHILOSOPHY.md` +Thin check-centric setup per the uniform setup contract (`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in the marketplace repository): `check` inspects and reports, `apply` resolves. This plugin owns no consumer-project configuration, targets and modes arrive as `/disk-hygiene:clean` arguments, and the only tunable is the native diff --git a/plugins/docs-hygiene/.claude-plugin/plugin.json b/plugins/docs-hygiene/.claude-plugin/plugin.json index 5496af3f4e..a8af42f0a6 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.21.46", + "version": "0.21.47", "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), audit-derivability (classify whether a whole document earns its existence: could a fresh agent re-derive it from the code?), audit-progressive-disclosure (grade instruction files against a load-tier model for split opportunities and hub/spoke disclosure defects), write-for-agents (authoring-time doctrine that fires while agent-consumed markdown is being written), and write-for-humans (the same moment for the other reader, covering end-user READMEs, RFCs, release notes and guides, and resolving the consuming project's own style guide first).", "author": { "name": "Melodic Software", diff --git a/plugins/docs-hygiene/CHANGELOG.md b/plugins/docs-hygiene/CHANGELOG.md index 6d177051a6..fa7e63eab2 100644 --- a/plugins/docs-hygiene/CHANGELOG.md +++ b/plugins/docs-hygiene/CHANGELOG.md @@ -1,5 +1,11 @@ # Changelog: docs-hygiene plugin +## [0.21.47] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.21.46] ### Changed diff --git a/plugins/docs-hygiene/skills/audit-derivability/SKILL.md b/plugins/docs-hygiene/skills/audit-derivability/SKILL.md index e22632e551..d114524419 100644 --- a/plugins/docs-hygiene/skills/audit-derivability/SKILL.md +++ b/plugins/docs-hygiene/skills/audit-derivability/SKILL.md @@ -72,7 +72,7 @@ Re-derivation cost is paid by the reader, and agent-facing and human-facing read Do NOT guess derivability from a skim. Two passes, escalating only where the stakes justify it: 1. **Heuristic claim-source classification (every document).** Classify each load-bearing claim by where its truth lives. *code/config/structure* (derivable), *another tracked doc* (duplication → `/docs-hygiene:extract-ssot`), or *nowhere else* (owned, non-derivable), and let the mix drive a provisional verdict. Before an actionable verdict on an empty or near-empty file, check `git log` for evidence the state is deliberate: a deliberately emptied or reset file is a recorded decision (Factor 4) → `keep-owns-facts`. -2. **Empirical spot-test (load-bearing or contested deletions only).** Once this context has read the document it knows the answers and will overestimate how derivable they were, a self-grade. Confirm a `delete`/`convert-to-pointer` by delegating to a **fresh-context, non-fork subagent** (e.g. `Explore`) that has NOT seen the document: it reproduces the document's conclusions from native exploration only, then compare. Prefer a cross-vendor advisor for that spot-test **when one is installed and set up**, e.g. the OpenAI Codex plugin, when its documented surface can take this artifact, invoked per its own docs, with the fresh-context same-vendor subagent as the stated fallback, never a route to a command that may not resolve (per `docs/PLUGIN-PHILOSOPHY.md` "Fresh-eyes checkpoints" in the marketplace repository). Convergence confirms derivable; divergence means the document owns something exploration could not recover. Keep it. Never the Agent tool's `fork` subagent type: a fork inherits the parent conversation, so it carries the contamination the spot-test exists to avoid. A skill's own `context: fork` frontmatter is a different thing and starts blank. Full protocol: `context/rubric.md`. +2. **Empirical spot-test (load-bearing or contested deletions only).** Once this context has read the document it knows the answers and will overestimate how derivable they were, a self-grade. Confirm a `delete`/`convert-to-pointer` by delegating to a **fresh-context, non-fork subagent** (e.g. `Explore`) that has NOT seen the document: it reproduces the document's conclusions from native exploration only, then compare. Prefer a cross-vendor advisor for that spot-test **when one is installed and set up**, e.g. the OpenAI Codex plugin, when its documented surface can take this artifact, invoked per its own docs, with the fresh-context same-vendor subagent as the stated fallback, never a route to a command that may not resolve (per `docs/plugin-philosophy.md` "Fresh-eyes checkpoints" in the marketplace repository). Convergence confirms derivable; divergence means the document owns something exploration could not recover. Keep it. Never the Agent tool's `fork` subagent type: a fork inherits the parent conversation, so it carries the contamination the spot-test exists to avoid. A skill's own `context: fork` frontmatter is a different thing and starts blank. Full protocol: `context/rubric.md`. Gate the spot-test by stakes: skip it for an obviously trivial derivable file (an auto-generated index, a verbatim config restatement); run it whenever being wrong about the deletion costs a reader something real. diff --git a/plugins/docs-hygiene/skills/audit-encapsulation/context/public-surface-contract.md b/plugins/docs-hygiene/skills/audit-encapsulation/context/public-surface-contract.md index 60982f9439..6c0e6c8fe9 100644 --- a/plugins/docs-hygiene/skills/audit-encapsulation/context/public-surface-contract.md +++ b/plugins/docs-hygiene/skills/audit-encapsulation/context/public-surface-contract.md @@ -42,7 +42,7 @@ The relaxation is intra-plugin only. Cross-plugin path citation stays a violatio install independently and the cited path can be genuinely absent. Heading anchors stay private in both cases, because a heading is body structure whatever ships alongside it. -This repository layers exactly that convention; `docs/PLUGIN-PHILOSOPHY.md` states it and bounds it. +This repository layers exactly that convention; `docs/plugin-philosophy.md` states it and bounds it. A repo that has not declared such a convention gets the unrelaxed contract above. A skill MAY expose a `scripts/.sh` entry as a declared public facade (delegating to a private backend directory) that hooks/CI invoke directly. That is the encapsulation-respecting alternative to vendoring a copy of the logic. A meta-tooling consumer that only READS a skill-internal path as data, such as a version-drift gate reading a pinned-version file or a path-scoped trigger naming the file it watches, cites that path under the KIND-2 forced-cite exemption (see the filter taxonomy in SKILL.md): it names a path structurally, it does not invoke skill logic. Logic invocation goes through the facade; data/path reference is KIND-2. diff --git a/plugins/docs-hygiene/skills/compress/SKILL.md b/plugins/docs-hygiene/skills/compress/SKILL.md index d02428ba61..7ed2292832 100644 --- a/plugins/docs-hygiene/skills/compress/SKILL.md +++ b/plugins/docs-hygiene/skills/compress/SKILL.md @@ -129,7 +129,7 @@ Audit action output: table with `target`, `expected_yield_pct`, `classify` (SKIP ## Gotchas -- **Self-audit drifts toward EXPANSION.** The semantic-diff dispatch must run as a SEPARATE fresh-context audit, never a self-audit by the model that produced the edits. Self-audit re-adds words just removed ("preserve clarity"; an observed failure, see ## Sources). Prefer a cross-vendor advisor for that audit **when one is installed and set up**, e.g. the OpenAI Codex plugin, when its documented surface can take this artifact, invoked per its own docs, with the fresh-context same-vendor subagent as the stated fallback, never a route to a command that may not resolve (per `docs/PLUGIN-PHILOSOPHY.md` "Fresh-eyes checkpoints" in the marketplace repository). Subagents cannot reliably spawn the verifier themselves (nested subagent support is version-dependent, and a fresh-context verifier beats self-critique regardless), so for batch fan-out follow `context/fan-out-orchestration.md`: the main session dispatches separate compress + audit subagents, reconciling per finding. +- **Self-audit drifts toward EXPANSION.** The semantic-diff dispatch must run as a SEPARATE fresh-context audit, never a self-audit by the model that produced the edits. Self-audit re-adds words just removed ("preserve clarity"; an observed failure, see ## Sources). Prefer a cross-vendor advisor for that audit **when one is installed and set up**, e.g. the OpenAI Codex plugin, when its documented surface can take this artifact, invoked per its own docs, with the fresh-context same-vendor subagent as the stated fallback, never a route to a command that may not resolve (per `docs/plugin-philosophy.md` "Fresh-eyes checkpoints" in the marketplace repository). Subagents cannot reliably spawn the verifier themselves (nested subagent support is version-dependent, and a fresh-context verifier beats self-critique regardless), so for batch fan-out follow `context/fan-out-orchestration.md`: the main session dispatches separate compress + audit subagents, reconciling per finding. - **Sub-3% diffs auto-revert unless `--force`.** Default `<3% AND 0 semantic-loss → REVERT`; always-loaded instruction files bound at 2-3% yield (see ## Sources). Pass `--force` only when a targeted sub-3% diff is intentional, the user owns the result. - **Caveman writes a `.original.md` backup beside the target.** The caveman backend hardcodes this backup path; running it against the real file litters the repo. Backend Step B wraps caveman in a `mktemp -d` tempdir so the backup lands there and Bash call 2 removes it explicitly; a gitignore entry for `**/*.original.md` in the consuming repo is optional belt-and-suspenders. diff --git a/plugins/docs-hygiene/skills/write-for-agents/SKILL.md b/plugins/docs-hygiene/skills/write-for-agents/SKILL.md index d708bfb515..4d3e739323 100644 --- a/plugins/docs-hygiene/skills/write-for-agents/SKILL.md +++ b/plugins/docs-hygiene/skills/write-for-agents/SKILL.md @@ -26,7 +26,7 @@ an always-loaded surface than for an on-demand one. Every line you write spends two budgets, and cutting one can overspend the other: - **Context load**. Tokens the agent pays, every session for always-loaded surfaces. Governed - marketplace-wide by PLUGIN-PHILOSOPHY's Instruction economy: an instruction earns its place + marketplace-wide by plugin-philosophy's Instruction economy: an instruction earns its place with observed-stumble evidence, or it goes. - **Cognitive load**. Attention the human maintainer pays. The human is the index of the doc set: they must be able to hold where things live. Ten tiny fragment files can be cheaper for diff --git a/plugins/dometrain/.claude-plugin/plugin.json b/plugins/dometrain/.claude-plugin/plugin.json index 837328c8d6..b88e7010cc 100644 --- a/plugins/dometrain/.claude-plugin/plugin.json +++ b/plugins/dometrain/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "dometrain", - "version": "0.2.12", + "version": "0.2.13", "description": "Dometrain course-content grounding over a third-party remote MCP server (Dometrain-hosted, Bearer auth): search lessons, pull curated lesson documents with on-screen code, and cite timestamped deep links. Requires an active Dometrain Pro subscription. Credential entered once through Claude Code's native masked userConfig prompt and stored in secure credential storage. Ships with a grounding usage skill kept in sync with Dometrain's own official Claude Code plugin.", "author": { "name": "Melodic Software", diff --git a/plugins/dometrain/CHANGELOG.md b/plugins/dometrain/CHANGELOG.md index 6d79fc6a35..407d21ddd3 100644 --- a/plugins/dometrain/CHANGELOG.md +++ b/plugins/dometrain/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `dometrain` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.2.13] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.2.12] ### Changed diff --git a/plugins/dometrain/skills/setup/SKILL.md b/plugins/dometrain/skills/setup/SKILL.md index 9721d79ece..cebe00bbcd 100644 --- a/plugins/dometrain/skills/setup/SKILL.md +++ b/plugins/dometrain/skills/setup/SKILL.md @@ -122,7 +122,7 @@ to detect the collision by comparing MCP tool-name prefixes. A true collision pr - Do not read, echo, log, copy, or persist the API key. - Do not write the plugin cache, Claude Code user settings, or `pluginConfigs`, per the uniform - setup contract (`docs/PLUGIN-PHILOSOPHY.md` "Setup is explicit and repeatable" in the + setup contract (`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in the marketplace repository). - Do not call a Dometrain tool during setup. Resolution via tool inventory / `ToolSearch` is sufficient and spends no quota. diff --git a/plugins/education/.claude-plugin/plugin.json b/plugins/education/.claude-plugin/plugin.json index 3778aa2fc4..bfadfb56d2 100644 --- a/plugins/education/.claude-plugin/plugin.json +++ b/plugins/education/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "education", - "version": "0.10.7", + "version": "0.10.8", "description": "Interactive multi-session learning coach: teaches a general subject or a concept grounded in the consuming repo through the Knowledge-Skills-Wisdom progression, with persistent per-topic learning state. Also a single-session domain primer, a one-shot plain-language explainer that drops anything to genuinely plain words, a picture explainer that answers the same question as a diagram-led HTML artifact for someone who knows nothing about the topic, and a post-work comprehension check that quizzes the human on a completed change.", "author": { "name": "Melodic Software", diff --git a/plugins/education/CHANGELOG.md b/plugins/education/CHANGELOG.md index 3b6f72a964..5a8c68f0cf 100644 --- a/plugins/education/CHANGELOG.md +++ b/plugins/education/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `education` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.10.8] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.10.7] ### Changed diff --git a/plugins/education/skills/setup/SKILL.md b/plugins/education/skills/setup/SKILL.md index f3e7fef973..2543576e20 100644 --- a/plugins/education/skills/setup/SKILL.md +++ b/plugins/education/skills/setup/SKILL.md @@ -78,6 +78,6 @@ Claude Code. Do not claim a configuration change until a rerun observes the new - Do not start a teach, explain, or quiz session; use `/education:teach`, `/education:explain`, or `/education:quiz-me`. - Do not write the plugin cache, Claude Code user settings, or `pluginConfigs`, per the uniform - setup contract (`docs/PLUGIN-PHILOSOPHY.md` "Setup is explicit and repeatable" in the + setup contract (`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in the marketplace repository). - Do not invent an organization, repository, marketplace, or environment-variable prefix. diff --git a/plugins/eol-normalizer/.claude-plugin/plugin.json b/plugins/eol-normalizer/.claude-plugin/plugin.json index bd8d761d95..183a215652 100644 --- a/plugins/eol-normalizer/.claude-plugin/plugin.json +++ b/plugins/eol-normalizer/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "eol-normalizer", - "version": "0.6.45", + "version": "0.6.46", "description": "Normalize a written file's working-tree line endings to its .gitattributes eol value on edit: symmetric CRLF/LF driven by git check-attr, advisory and never blocking.", "author": { "name": "Melodic Software", diff --git a/plugins/eol-normalizer/CHANGELOG.md b/plugins/eol-normalizer/CHANGELOG.md index fedcb001d0..66f972e7dd 100644 --- a/plugins/eol-normalizer/CHANGELOG.md +++ b/plugins/eol-normalizer/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `eol-normalizer` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.6.46] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.6.45] ### Changed diff --git a/plugins/eol-normalizer/skills/setup/SKILL.md b/plugins/eol-normalizer/skills/setup/SKILL.md index e5c7f5de3a..8d37fcb3fb 100644 --- a/plugins/eol-normalizer/skills/setup/SKILL.md +++ b/plugins/eol-normalizer/skills/setup/SKILL.md @@ -7,7 +7,7 @@ disable-model-invocation: true ## Purpose -Thin check-centric setup per the uniform setup contract (`docs/PLUGIN-PHILOSOPHY.md` +Thin check-centric setup per the uniform setup contract (`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in the marketplace repository): `check` inspects and reports, `apply` resolves. This plugin owns no consumer-project configuration. The normalization policy is the repository's own `.gitattributes`, and the only tunable is the diff --git a/plugins/event-storming/.claude-plugin/plugin.json b/plugins/event-storming/.claude-plugin/plugin.json index 48f9dbf841..9e8512906e 100644 --- a/plugins/event-storming/.claude-plugin/plugin.json +++ b/plugins/event-storming/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "event-storming", - "version": "0.6.10", + "version": "0.6.11", "description": "EventStorming for domain discovery: a methodology skill (Big Picture / Process Modeling / Design-Level facilitation reference, notation, patterns) and a simulation skill (agentic multi-persona workshops that produce a structured-markdown model by default; a live Miro-board rendering path is available when the first-party miro plugin is enabled).", "author": { "name": "Melodic Software", diff --git a/plugins/event-storming/CHANGELOG.md b/plugins/event-storming/CHANGELOG.md index 5f9c4c807b..33f47ae923 100644 --- a/plugins/event-storming/CHANGELOG.md +++ b/plugins/event-storming/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `event-storming` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.6.11] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.6.10] ### Changed diff --git a/plugins/event-storming/README.md b/plugins/event-storming/README.md index b88985547b..65c66bff22 100644 --- a/plugins/event-storming/README.md +++ b/plugins/event-storming/README.md @@ -49,7 +49,7 @@ Both optional surfaces degrade gracefully: tools unavailable), `simulation` detects it at preflight and runs in structured-markdown mode instead of failing. Miro's official hosted server (`mcp.miro.com`) was evaluated and **rejected** as the target (no board-delete tool for teardown; third-party remote egress). Trust record in the - marketplace repo's MCP decision table (`docs/MIGRATION-PLAYBOOK.md`). + marketplace repo's MCP decision table (`docs/migration-playbook.md`). - **Web research absent.** The skills use the Perplexity MCP tools if present, otherwise Claude Code's built-in `WebSearch` / `WebFetch`; with no research surface at all they ask you for the domain context rather than guessing. diff --git a/plugins/event-storming/skills/simulation/reference/miro-integration.md b/plugins/event-storming/skills/simulation/reference/miro-integration.md index 74056c6f94..93b6a93477 100644 --- a/plugins/event-storming/skills/simulation/reference/miro-integration.md +++ b/plugins/event-storming/skills/simulation/reference/miro-integration.md @@ -15,7 +15,7 @@ Miro MCP server. > **Why the bundled server and not Miro's hosted one.** The live-board path targets the first-party > bundled server so that board teardown is expressible (the hosted server exposes no board-delete > tool) and so board and workshop content never leaves for a third-party remote MCP. The decision -> record lives in the marketplace repo's MCP decision table in `docs/MIGRATION-PLAYBOOK.md`. +> record lives in the marketplace repo's MCP decision table in `docs/migration-playbook.md`. ### Tool namespace diff --git a/plugins/firecrawl/.claude-plugin/plugin.json b/plugins/firecrawl/.claude-plugin/plugin.json index 986f3b6460..4375fb999d 100644 --- a/plugins/firecrawl/.claude-plugin/plugin.json +++ b/plugins/firecrawl/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "firecrawl", - "version": "0.5.11", + "version": "0.5.12", "description": "Web scraping, search, crawling, and file parsing through the firecrawl-cli binary with a write-to-disk-then-Read pattern that keeps large results out of context: a user-facing wrapper skill, a lazy-install setup skill, and a separate gated maintainer update skill tracking the upstream CLI and skill source.", "author": { "name": "Melodic Software", diff --git a/plugins/firecrawl/CHANGELOG.md b/plugins/firecrawl/CHANGELOG.md index 12b01afe51..8013677477 100644 --- a/plugins/firecrawl/CHANGELOG.md +++ b/plugins/firecrawl/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `firecrawl` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.5.12] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.5.11] ### Changed diff --git a/plugins/firecrawl/skills/setup/SKILL.md b/plugins/firecrawl/skills/setup/SKILL.md index b07a29b28f..265401e39b 100644 --- a/plugins/firecrawl/skills/setup/SKILL.md +++ b/plugins/firecrawl/skills/setup/SKILL.md @@ -7,7 +7,7 @@ disable-model-invocation: true ## Purpose -Thin check-centric setup per the uniform setup contract (`docs/PLUGIN-PHILOSOPHY.md` +Thin check-centric setup per the uniform setup contract (`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in the marketplace repository): `check` inspects and reports, `apply` resolves. This plugin is **lazy-install by design**, the main skill treats `firecrawl-cli` as an escalation option installed when first needed and flags its own diff --git a/plugins/go-format/.claude-plugin/plugin.json b/plugins/go-format/.claude-plugin/plugin.json index d1040316bb..f743ad864e 100644 --- a/plugins/go-format/.claude-plugin/plugin.json +++ b/plugins/go-format/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "go-format", - "version": "0.3.49", + "version": "0.3.50", "description": "Auto-fix Go formatting and import management on edit via goimports. Runs unconditionally (no consumer-config gate), skipping generated files.", "author": { "name": "Melodic Software", diff --git a/plugins/go-format/CHANGELOG.md b/plugins/go-format/CHANGELOG.md index 37cb709230..43eb025696 100644 --- a/plugins/go-format/CHANGELOG.md +++ b/plugins/go-format/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `go-format` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.3.50] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.3.49] ### Changed diff --git a/plugins/go-format/skills/setup/SKILL.md b/plugins/go-format/skills/setup/SKILL.md index ba772a9500..21b4251fc9 100644 --- a/plugins/go-format/skills/setup/SKILL.md +++ b/plugins/go-format/skills/setup/SKILL.md @@ -7,7 +7,7 @@ disable-model-invocation: true ## Purpose -Thin check-centric setup per the uniform setup contract (`docs/PLUGIN-PHILOSOPHY.md` +Thin check-centric setup per the uniform setup contract (`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in the marketplace repository): `check` inspects and reports, `apply` resolves. This plugin owns no consumer-project configuration. It runs unconditionally (no consumer-config opt-in gate, unlike sibling formatter plugins Ruff/typos), diff --git a/plugins/guardrails/.claude-plugin/plugin.json b/plugins/guardrails/.claude-plugin/plugin.json index 5c6467cce5..f391100eb1 100644 --- a/plugins/guardrails/.claude-plugin/plugin.json +++ b/plugins/guardrails/.claude-plugin/plugin.json @@ -147,5 +147,5 @@ "min": 1 } }, - "version": "0.33.3" + "version": "0.33.4" } diff --git a/plugins/guardrails/CHANGELOG.md b/plugins/guardrails/CHANGELOG.md index a05678a1d3..8d209ce994 100644 --- a/plugins/guardrails/CHANGELOG.md +++ b/plugins/guardrails/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `guardrails` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.33.4] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.33.3] ### Changed diff --git a/plugins/guardrails/hooks/flag-commit-pr-skill-bypass.sh b/plugins/guardrails/hooks/flag-commit-pr-skill-bypass.sh index 3592ad7f44..d64fc9621b 100755 --- a/plugins/guardrails/hooks/flag-commit-pr-skill-bypass.sh +++ b/plugins/guardrails/hooks/flag-commit-pr-skill-bypass.sh @@ -45,7 +45,7 @@ # Opt-in switch: flag_commit_pr_skill_bypass_enabled userConfig option. # DEFAULT OFF since 0.20.0: the #2021 hook-surface classification found this # is a behavioral-class context injector — a fixed prose nudge that consults no -# external ground truth — and PLUGIN-PHILOSOPHY.md's instruction-economy +# external ground truth — and plugin-philosophy.md's instruction-economy # evidence gate ablates that class config-off first (the script stays; a # consumer opts back in by setting the option to true). diff --git a/plugins/guardrails/hooks/stale-path-verify.sh b/plugins/guardrails/hooks/stale-path-verify.sh index 1e4074b746..4c98a3c28c 100755 --- a/plugins/guardrails/hooks/stale-path-verify.sh +++ b/plugins/guardrails/hooks/stale-path-verify.sh @@ -201,7 +201,7 @@ normalize_candidate() { [[ "$t" =~ [[:space:]] ]] && return 0 # Strip a trailing line/range citation suffix — this repo cites - # `docs/MIGRATION-PLAYBOOK.md:576-580` and `SKILL.md:24` pervasively. + # `docs/migration-playbook.md:576-580` and `SKILL.md:24` pervasively. t="${t%%:[0-9]*}" # Strip a trailing markdown-anchor fragment. diff --git a/plugins/guardrails/hooks/workflow-resilience-check.sh b/plugins/guardrails/hooks/workflow-resilience-check.sh index 5b31293ca8..37c7bc789a 100755 --- a/plugins/guardrails/hooks/workflow-resilience-check.sh +++ b/plugins/guardrails/hooks/workflow-resilience-check.sh @@ -12,7 +12,7 @@ # Opt-in switch: workflow_resilience_check_enabled userConfig option. # DEFAULT OFF since 0.20.0: the #2021 hook-surface classification found this # is a behavioral-class context injector — two greps and a fixed checklist that -# asserts nothing the model cannot derive — and PLUGIN-PHILOSOPHY.md's +# asserts nothing the model cannot derive — and plugin-philosophy.md's # instruction-economy evidence gate ablates that class config-off first (the # script stays; a consumer opts back in by setting the option to true). diff --git a/plugins/guardrails/skills/setup/SKILL.md b/plugins/guardrails/skills/setup/SKILL.md index f2cff5c498..8ac18b08ce 100644 --- a/plugins/guardrails/skills/setup/SKILL.md +++ b/plugins/guardrails/skills/setup/SKILL.md @@ -7,7 +7,7 @@ disable-model-invocation: true ## Purpose -Thin check-centric setup per the uniform setup contract (`docs/PLUGIN-PHILOSOPHY.md` +Thin check-centric setup per the uniform setup contract (`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in the marketplace repository): `check` inspects and reports, `apply` resolves. This plugin owns no consumer-project configuration. Every tunable is a native `userConfig` option (one enable toggle per guard plus the diff --git a/plugins/implementation/.claude-plugin/plugin.json b/plugins/implementation/.claude-plugin/plugin.json index 279383d7c7..751f1bbc45 100644 --- a/plugins/implementation/.claude-plugin/plugin.json +++ b/plugins/implementation/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "implementation", - "version": "0.16.6", + "version": "0.16.7", "description": "Disciplined implementation stage: execute approved plans inline (`/implementation:implement`) or via orchestrated worker subagents (`/implementation:implement-dispatch`) with incremental validation, TDD-by-default cadence, green-checkpoint commits, scope-fence drift detection, and divergence detection that routes back to planning. Build/test/lint, testing, and outcome verification live in the companion `toolchain`, `testing`, and `verification` plugins, invoked when installed.", "author": { "name": "Melodic Software", diff --git a/plugins/implementation/CHANGELOG.md b/plugins/implementation/CHANGELOG.md index 3d96be9307..2855e1e8c4 100644 --- a/plugins/implementation/CHANGELOG.md +++ b/plugins/implementation/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `implementation` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.16.7] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.16.6] ### Fixed diff --git a/plugins/implementation/agents/phase-verifier.md b/plugins/implementation/agents/phase-verifier.md index 1517484a33..e77de1a260 100644 --- a/plugins/implementation/agents/phase-verifier.md +++ b/plugins/implementation/agents/phase-verifier.md @@ -36,7 +36,7 @@ on any new model release. Tier *definitions* stay abstract; only this seam binds Frontmatter binds a floor-shaped default; it cannot express session-relative raising. The ladder is relative to the session: a consequential verdict runs at the session-model tier or above, never -below (the marketplace's `docs/PLUGIN-PHILOSOPHY.md` "Model tiers"). So when the dispatching +below (the marketplace's `docs/plugin-philosophy.md` "Model tiers"). So when the dispatching session's model resolves above this binding, the orchestrator passes a per-invocation `model` at or above the session tier; that override routes upward only. diff --git a/plugins/implementation/skills/implement-dispatch/SKILL.md b/plugins/implementation/skills/implement-dispatch/SKILL.md index 2417af8f54..6f7e565426 100644 --- a/plugins/implementation/skills/implement-dispatch/SKILL.md +++ b/plugins/implementation/skills/implement-dispatch/SKILL.md @@ -75,7 +75,7 @@ In a session with no human to escalate to, stop-and-escalate on Moderate diverge - **One entry is one decision.** If it does not fit on a line or two, the decision is not crisp yet, split it, or say plainly that it is still open. - **Entries are typed, and a deviation carries four fields.** Type each entry as one of: plan-confirmed (a load-bearing plan assumption checked out), discovery (something learned the plan never spoke to), deviation (the plan said X, the run did Y), or human-decision (a call only a person can make, marked blocking or non-blocking). A deviation entry answers: plan said / found / chose / revisit. This taxonomy is this plugin's own output contract for its own log file, never a format imposed on consumer repos. -Interactive sessions may opt into this same log rather than leaving Moderate adjustments in scrollback (see `/implementation:implement` "Step 3: Divergence Detection"); the house posture and rationale live in `docs/FINDING-YOUR-UNKNOWNS.md` in the marketplace repository. +Interactive sessions may opt into this same log rather than leaving Moderate adjustments in scrollback (see `/implementation:implement` "Step 3: Divergence Detection"); the house posture and rationale live in `docs/finding-your-unknowns.md` in the marketplace repository. An entry whose evidence does not resolve, or whose result was never verified, is the PR review catching a gap. That is the log working. Major divergence (fundamental assumption wrong) still STOPS even autonomously. Park the run with a handoff note rather than improvising a new design. Interactive sessions keep the `/implementation:implement` "Step 3: Divergence Detection" escalation ladder unchanged. @@ -83,7 +83,7 @@ An entry whose evidence does not resolve, or whose result was never verified, is **Ritual unchanged, except the phase-boundary commit's contents.** Every phase boundary runs `/implementation:implement`'s "Step 4: Task Tracking and Phase-Boundary Handoff" ritual, plan marks, handoff entry, status summary, mark-then-commit, resume prompt, with one scoped exception: Step 4 item 4 normally combines a phase's source changes and its plan-mark in one commit, but a dispatched worker already committed and pushed its source early (per the push-early clause above) before the orchestrator's acceptance-criteria verdict exists to mark the phase `[DONE]`. In that case the phase-boundary commit is plan-marks-only, the worker's earlier commit already carries the source, rather than the combined single commit inline mode produces. Under worker-side provisioning this plan-mark commit lands on the worker's branch, committed in the returned worktree via `git -C ` **and pushed**, never in the orchestrator's default checkout (which would put it on the local default branch, off the PR branch. See the Prerequisites exception). Pushing it is not optional: it keeps the worktree tip in sync with the remote, which `/source-control:pull-request create --pushed`'s HEAD-equals-remote precondition requires, and it keeps tracked plan progress on the PR branch. Orchestration changes who edits and when the source lands, not whether progress gets recorded. -**Fresh-context verifier before marking a phase `[DONE]`:** the Step 4 ritual's acceptance-criteria verdict (item 1) is, in orchestrated runs, *dispatched* rather than rendered inline. Dispatch this plugin's `phase-verifier` agent (subagent type `implementation:phase-verifier`; its `model` frontmatter structurally binds the verifier at least as capable as the implementer it checks) to check the phase's acceptance criteria against the actual diff, handed binary criteria and the diff with your rationale withheld. Frontmatter binds a floor, not a session-relative value: a consequential verdict runs at the session-model tier or above, never below (the marketplace's `docs/PLUGIN-PHILOSOPHY.md` "Model tiers"), so when the orchestrating session's model resolves above the binding, pass a per-invocation `model` at or above the session tier. Upward only. Where the phase's outcome is high-stakes and correlated blind spots are the risk, prefer a cross-vendor advisor for that verifier **when one is installed and set up**. E.g. the OpenAI Codex plugin, when its documented surface can take this artifact, invoked per its own docs. With the fresh-context same-vendor verifier sub-agent as the stated fallback, never a route to a command that may not resolve (per `docs/PLUGIN-PHILOSOPHY.md` "Fresh-eyes checkpoints" in the marketplace repository). It applies in every mode: autonomous runs always dispatch it; interactive runs dispatch it for any phase beyond a mechanical, behavior-preserving change. **An `INCONCLUSIVE` return, the `phase-verifier` contract's answer when it could not decide every criterion, is not a verdict:** the phase stays unmarked, and the orchestrator re-dispatches a *fresh* verifier against the gap the return named (narrower criteria, or the specific files it could not reach), never accepting the partial coverage and never marking `[DONE]` on it; a second inconclusive return on the same criteria is an escalation, handled like a divergence report (step 5 above). Surface subagent results in the response before ending the turn. +**Fresh-context verifier before marking a phase `[DONE]`:** the Step 4 ritual's acceptance-criteria verdict (item 1) is, in orchestrated runs, *dispatched* rather than rendered inline. Dispatch this plugin's `phase-verifier` agent (subagent type `implementation:phase-verifier`; its `model` frontmatter structurally binds the verifier at least as capable as the implementer it checks) to check the phase's acceptance criteria against the actual diff, handed binary criteria and the diff with your rationale withheld. Frontmatter binds a floor, not a session-relative value: a consequential verdict runs at the session-model tier or above, never below (the marketplace's `docs/plugin-philosophy.md` "Model tiers"), so when the orchestrating session's model resolves above the binding, pass a per-invocation `model` at or above the session tier. Upward only. Where the phase's outcome is high-stakes and correlated blind spots are the risk, prefer a cross-vendor advisor for that verifier **when one is installed and set up**. E.g. the OpenAI Codex plugin, when its documented surface can take this artifact, invoked per its own docs. With the fresh-context same-vendor verifier sub-agent as the stated fallback, never a route to a command that may not resolve (per `docs/plugin-philosophy.md` "Fresh-eyes checkpoints" in the marketplace repository). It applies in every mode: autonomous runs always dispatch it; interactive runs dispatch it for any phase beyond a mechanical, behavior-preserving change. **An `INCONCLUSIVE` return, the `phase-verifier` contract's answer when it could not decide every criterion, is not a verdict:** the phase stays unmarked, and the orchestrator re-dispatches a *fresh* verifier against the gap the return named (narrower criteria, or the specific files it could not reach), never accepting the partial coverage and never marking `[DONE]` on it; a second inconclusive return on the same criteria is an escalation, handled like a divergence report (step 5 above). Surface subagent results in the response before ending the turn. ### Resident-vs-clear at phase boundaries diff --git a/plugins/improvement/.claude-plugin/plugin.json b/plugins/improvement/.claude-plugin/plugin.json index c53b9de52d..4c31266661 100644 --- a/plugins/improvement/.claude-plugin/plugin.json +++ b/plugins/improvement/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "improvement", - "version": "0.1.13", + "version": "0.1.14", "description": "Evidence-first, cross-dimension improvement finder. Point it at a repo, feature, concept, or process surface and it produces a ranked, evidence-cited list of improvement candidates led by value-to-effort, interviews on the pick, and hands off to the planning pipeline; runnable unattended as a tech-debt-sweep routine.", "author": { "name": "Melodic Software", diff --git a/plugins/improvement/CHANGELOG.md b/plugins/improvement/CHANGELOG.md index b856a9a858..666dbcf5e0 100644 --- a/plugins/improvement/CHANGELOG.md +++ b/plugins/improvement/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `improvement` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.1.14] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.1.13] ### Changed diff --git a/plugins/improvement/README.md b/plugins/improvement/README.md index b7278c589d..c5badf1588 100644 --- a/plugins/improvement/README.md +++ b/plugins/improvement/README.md @@ -42,7 +42,7 @@ capabilities and limits rather than relying on numbers written here. A routine fires a fresh cloud session, and this skill exists there only when the `improvement` plugin is installed in that session's environment. Per this marketplace's -[docs/CLOUD-SESSIONS.md](../../docs/CLOUD-SESSIONS.md), a SessionStart-hook install is never +[docs/cloud-sessions.md](../../docs/cloud-sessions.md), a SessionStart-hook install is never visible to the session that ran it. So the plugin must be pre-installed by the cloud environment's setup script (or otherwise present before the session process starts). That is why the template below opens with a hard guard: if `/improvement:find` is unavailable, stop and report. A run diff --git a/plugins/instruction-placement/.claude-plugin/plugin.json b/plugins/instruction-placement/.claude-plugin/plugin.json index 62c0e50b19..aa680879a1 100644 --- a/plugins/instruction-placement/.claude-plugin/plugin.json +++ b/plugins/instruction-placement/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "instruction-placement", - "version": "0.13.3", + "version": "0.13.4", "description": "Routes agent-instruction content to the surface that loads it at the right moment. The audit skill sweeps a repository's instruction layer and its ordinary markdown for content whose scope is narrower than the surface carrying it, meaning conventions keyed to one file type or one subtree sitting in an always-loaded CLAUDE.md or AGENTS.md, and for normative conventions stranded in documentation Claude never loads at all, then classifies each against a routing rubric and proposes a destination whose `paths:` glob is machine-validated before it is ever offered. Safety-class content (irreversible actions, secrets, data integrity, external publication, compliance, agent authority) is hard-denied from demotion and reported as held back rather than proposed, because demotion trades guaranteed presence for conditional presence and deferred surfaces are invisible inside subagents and absent after compaction until re-triggered. Every accepted move regenerates an always-loaded index of deferred surfaces, which is what keeps a demoted rule reachable from a subagent that never receives its injection. The audit is read-only and emits a diffable findings artifact; realignment is a separate skill gated per item with no blanket-approve path; a deterministic check skill gates that every rule glob still resolves and the index is current; and a setup skill verifies the one thing no other gate can see: that the index target is a file Claude Code will actually read, since it reads CLAUDE.md and not AGENTS.md.", "author": { "name": "Melodic Software", diff --git a/plugins/instruction-placement/CHANGELOG.md b/plugins/instruction-placement/CHANGELOG.md index d7d8a57656..665f46b67b 100644 --- a/plugins/instruction-placement/CHANGELOG.md +++ b/plugins/instruction-placement/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `instruction-placement` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.13.4] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.13.3] ### Changed diff --git a/plugins/instruction-placement/skills/setup/SKILL.md b/plugins/instruction-placement/skills/setup/SKILL.md index 4eaf2ea653..85b507d817 100644 --- a/plugins/instruction-placement/skills/setup/SKILL.md +++ b/plugins/instruction-placement/skills/setup/SKILL.md @@ -12,7 +12,7 @@ shell: bash ## Purpose -Thin check-centric setup per the uniform setup contract (`docs/PLUGIN-PHILOSOPHY.md`, "Setup is +Thin check-centric setup per the uniform setup contract (`docs/plugin-philosophy.md`, "Setup is explicit and repeatable"): `check` inspects and reports, `apply` points at what it found. The warrant is all three criteria, but one carries the weight. **The index target is an external diff --git a/plugins/kindle-dedrm/.claude-plugin/plugin.json b/plugins/kindle-dedrm/.claude-plugin/plugin.json index 34a5d60c0d..a34d0e421d 100644 --- a/plugins/kindle-dedrm/.claude-plugin/plugin.json +++ b/plugins/kindle-dedrm/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "kindle-dedrm", - "version": "0.7.17", + "version": "0.7.18", "description": "Manage the Kindle for PC 2.8.0 + Calibre DeDRM workflow for personal-use ebook DRM removal on books the user owns (Windows only). Action router with setup, sync, update, cleanup, and status, each state mutation paired with a documented compensating reversal.", "author": { "name": "Melodic Software", diff --git a/plugins/kindle-dedrm/CHANGELOG.md b/plugins/kindle-dedrm/CHANGELOG.md index 75b0697550..f064f7b868 100644 --- a/plugins/kindle-dedrm/CHANGELOG.md +++ b/plugins/kindle-dedrm/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `kindle-dedrm` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.7.18] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.7.17] ### Changed diff --git a/plugins/kindle-dedrm/skills/setup/SKILL.md b/plugins/kindle-dedrm/skills/setup/SKILL.md index 84b2335b7b..5a7677d574 100644 --- a/plugins/kindle-dedrm/skills/setup/SKILL.md +++ b/plugins/kindle-dedrm/skills/setup/SKILL.md @@ -8,7 +8,7 @@ disable-model-invocation: true ## Purpose Verify and provision the first-time DeDRM setup, per the uniform setup contract -(`docs/PLUGIN-PHILOSOPHY.md` "Setup is explicit and repeatable" in the marketplace repository). +(`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in the marketplace repository). `check` inspects prerequisites and current state read-only; `apply` runs the provisioning walkthrough (the router skill's workflow reference), then re-runs `check`. No argument or `check` runs the check; `apply` runs the check first, then provisioning; `apply download` runs only the gated diff --git a/plugins/knowledge/.claude-plugin/plugin.json b/plugins/knowledge/.claude-plugin/plugin.json index 34c6036595..c541fc0e87 100644 --- a/plugins/knowledge/.claude-plugin/plugin.json +++ b/plugins/knowledge/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "knowledge", - "version": "0.13.50", + "version": "0.13.51", "description": "Ingest external knowledge into durable, synthesized artifacts. Ships a book-distillation pipeline (PDF/EPUB into concept-organized, author-attributed skill reference files), a video-digest pipeline (watch a single public video from YouTube or X, formerly Twitter: transcript, link harvest, and repo-applicability synthesis), a course-digest pipeline (extract and synthesize online video courses from Dometrain and Teachable into repo-applicable recommendations), a docpage-digest pipeline (single online documentation page into a verified knowledge slice with dual verification including one cross-vendor verifier, and an interview handoff), and a map-corpus pipeline (multi-resource corpus into a classified link map, deterministic node manifests, gate-verified relevance inventory, and an approved queue of docpage-digest runs), plus a re-runnable setup action; a configurable library directory governs where synthesized artifacts land in the consuming repo.", "author": { "name": "Melodic Software", diff --git a/plugins/knowledge/CHANGELOG.md b/plugins/knowledge/CHANGELOG.md index 1e7fc97098..794c65df6b 100644 --- a/plugins/knowledge/CHANGELOG.md +++ b/plugins/knowledge/CHANGELOG.md @@ -4,6 +4,12 @@ All notable changes to the `knowledge` plugin are recorded here. The `version` i `.claude-plugin/plugin.json` is the delivery vehicle. A consumer receives a change only after that version increases. +## [0.13.51] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.13.50] ### Changed diff --git a/plugins/knowledge/reference/ingest-deferred-decisions.md b/plugins/knowledge/reference/ingest-deferred-decisions.md index 45e21185ed..91053fb487 100644 --- a/plugins/knowledge/reference/ingest-deferred-decisions.md +++ b/plugins/knowledge/reference/ingest-deferred-decisions.md @@ -48,7 +48,7 @@ skill's collision check then permanently refuses to resume them. **Trigger:** an orchestrator that justifies the cost. **Cost measured at the time of deferral** (2026-08, re-measure before acting): 48 occurrences across 14 tracked files; a two-plugin change with two CHANGELOG entries and two version -bumps; a regenerated `docs/CATALOG.md`; 24 CHANGELOG occurrences that must +bumps; a regenerated `docs/catalog.md`; 24 CHANGELOG occurrences that must **not** be rewritten; an unresolved question about ADRs 0006 and 0007 citing the live path; and an explicit migration of 14 live work slices. diff --git a/plugins/knowledge/skills/setup/SKILL.md b/plugins/knowledge/skills/setup/SKILL.md index 36c3b418a7..4bab8e43f8 100644 --- a/plugins/knowledge/skills/setup/SKILL.md +++ b/plugins/knowledge/skills/setup/SKILL.md @@ -15,7 +15,7 @@ the plugin is enabled, stores non-sensitive options in user settings, and ignore Official contract: . -Check-centric per the uniform setup contract (`docs/PLUGIN-PHILOSOPHY.md` +Check-centric per the uniform setup contract (`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in the marketplace repository): `check` inspects and reports, `apply` resolves what `check` found, and the extraction-dependency provisioning is a distinct opt-in subaction. The `library_dir` option is Claude-Code-owned; this skill never diff --git a/plugins/machine-health/.claude-plugin/plugin.json b/plugins/machine-health/.claude-plugin/plugin.json index b6c1ea3cf1..52fe35a2f3 100644 --- a/plugins/machine-health/.claude-plugin/plugin.json +++ b/plugins/machine-health/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "machine-health", - "version": "0.12.15", + "version": "0.12.16", "description": "Workstation health audit: OS-specific checks (disk, OS updates, security posture, CISA KEV correlation) run from a versioned catalog with trend-aware severity, approval-gated remediations, and dated markdown reports. Windows fully implemented; macOS/Linux scaffolded (report UNKNOWN and stop). Machine state persists in the plugin data directory; the report directory and check catalog are configurable.", "author": { "name": "Melodic Software", diff --git a/plugins/machine-health/CHANGELOG.md b/plugins/machine-health/CHANGELOG.md index aec67480a0..a2174a2e4b 100644 --- a/plugins/machine-health/CHANGELOG.md +++ b/plugins/machine-health/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `machine-health` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.12.16] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.12.15] ### Changed diff --git a/plugins/machine-health/skills/audit/scripts/windows/checks/Test-ClaudeTempRoot.ps1 b/plugins/machine-health/skills/audit/scripts/windows/checks/Test-ClaudeTempRoot.ps1 index 620f207500..c66380ba2a 100644 --- a/plugins/machine-health/skills/audit/scripts/windows/checks/Test-ClaudeTempRoot.ps1 +++ b/plugins/machine-health/skills/audit/scripts/windows/checks/Test-ClaudeTempRoot.ps1 @@ -153,7 +153,7 @@ try { $root = Resolve-ClaudeTempRoot if (-not $root.Exists) { - # Not applicable exits quietly and successfully (docs/PLUGIN-PHILOSOPHY.md + # Not applicable exits quietly and successfully (docs/plugin-philosophy.md # "Prerequisites and failure behavior"). Same shape as the battery check on a # desktop: OK with a negative detail flag, never UNKNOWN. $result = New-HealthResult -Id $id -Category $category -Os 'windows' ` diff --git a/plugins/machine-health/skills/setup/SKILL.md b/plugins/machine-health/skills/setup/SKILL.md index 75df1032c0..a6de3cac28 100644 --- a/plugins/machine-health/skills/setup/SKILL.md +++ b/plugins/machine-health/skills/setup/SKILL.md @@ -8,7 +8,7 @@ disable-model-invocation: true ## Purpose Inspect and customize `/machine-health:audit` on this host per the uniform setup contract -(`docs/PLUGIN-PHILOSOPHY.md` "Setup is explicit and repeatable" in the marketplace repository): +(`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in the marketplace repository): `check` reads the effective configuration and reports, `apply` writes it. The machine-local surface is the catalog overlay at `/catalog/checks.local.jsonc` and the remediation approvals at `/state/approvals.json`. Configuration here is machine-local by design. diff --git a/plugins/markdown-format/.claude-plugin/plugin.json b/plugins/markdown-format/.claude-plugin/plugin.json index 6b167e79b2..e0ebe1591b 100644 --- a/plugins/markdown-format/.claude-plugin/plugin.json +++ b/plugins/markdown-format/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "markdown-format", - "version": "0.11.54", + "version": "0.11.55", "description": "Auto-format and lint Markdown on edit via markdownlint-cli2, only in repos that carry their own markdownlint config.", "author": { "name": "Melodic Software", diff --git a/plugins/markdown-format/CHANGELOG.md b/plugins/markdown-format/CHANGELOG.md index c666681c9e..0d30efaace 100644 --- a/plugins/markdown-format/CHANGELOG.md +++ b/plugins/markdown-format/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `markdown-format` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.11.55] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.11.54] ### Changed diff --git a/plugins/markdown-format/skills/setup/SKILL.md b/plugins/markdown-format/skills/setup/SKILL.md index 681ef4d598..63a9e29fc0 100644 --- a/plugins/markdown-format/skills/setup/SKILL.md +++ b/plugins/markdown-format/skills/setup/SKILL.md @@ -7,7 +7,7 @@ disable-model-invocation: true ## Purpose -Thin check-centric setup per the uniform setup contract (`docs/PLUGIN-PHILOSOPHY.md` +Thin check-centric setup per the uniform setup contract (`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in the marketplace repository): `check` inspects and reports, `apply` resolves. This plugin owns no consumer-project configuration. Rules come from the repository's own markdownlint config, and the only tunable is the native diff --git a/plugins/miro/.claude-plugin/plugin.json b/plugins/miro/.claude-plugin/plugin.json index fbf9687762..2fc0315bf1 100644 --- a/plugins/miro/.claude-plugin/plugin.json +++ b/plugins/miro/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "miro", - "version": "0.4.0", + "version": "0.4.1", "description": "Miro board management over the Model Context Protocol: create and manage boards, sticky notes, shapes, frames, connectors, and tags for EventStorming, brainstorming, and diagramming. Bundles a local stdio MCP server (single self-contained Node artifact); installs disabled, so opt in and supply a Miro API token.", "author": { "name": "Melodic Software", diff --git a/plugins/miro/CHANGELOG.md b/plugins/miro/CHANGELOG.md index 59fc34e5cc..2defb88760 100644 --- a/plugins/miro/CHANGELOG.md +++ b/plugins/miro/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `miro` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.4.1] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.4.0] ### Changed diff --git a/plugins/miro/skills/setup/SKILL.md b/plugins/miro/skills/setup/SKILL.md index 7205e4ee82..8e11376b87 100644 --- a/plugins/miro/skills/setup/SKILL.md +++ b/plugins/miro/skills/setup/SKILL.md @@ -106,7 +106,7 @@ supported keychain is available. Never read or reveal either location's contents - Do not read, echo, log, copy, or persist the token. - Do not write the plugin cache, Claude Code user settings, or `pluginConfigs`, per the uniform - setup contract (`docs/PLUGIN-PHILOSOPHY.md` "Setup is explicit and repeatable" in the + setup contract (`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in the marketplace repository). - Do not make a Miro API request without explicit confirmation. - Do not invoke a mutating Miro tool during setup. diff --git a/plugins/mutation-testing/.claude-plugin/plugin.json b/plugins/mutation-testing/.claude-plugin/plugin.json index 3b5168b48b..3041217f9a 100644 --- a/plugins/mutation-testing/.claude-plugin/plugin.json +++ b/plugins/mutation-testing/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "mutation-testing", - "version": "0.3.23", + "version": "0.3.24", "description": "Measures whether a test suite can actually detect faults, not merely execute code: `/mutation-testing:principles` answers operator, mutant-state, and metric questions from the primary literature; `/mutation-testing:setup` verifies the ecosystem's mutation tool and writes the tracked config; `/mutation-testing:audit` runs diff-scoped mutation analysis and reports surviving mutants, verifying that tracked source was restored and failing the run when it cannot, delegating the productive-versus-arid judgment to a fresh-context reviewer and test authoring to the test lane, and optionally persisting survivors as a findings file the review fix pass consumes.", "author": { "name": "Melodic Software", diff --git a/plugins/mutation-testing/CHANGELOG.md b/plugins/mutation-testing/CHANGELOG.md index caa0659b2b..990c00f38e 100644 --- a/plugins/mutation-testing/CHANGELOG.md +++ b/plugins/mutation-testing/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `mutation-testing` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.3.24] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.3.23] ### Changed diff --git a/plugins/mutation-testing/skills/audit/SKILL.md b/plugins/mutation-testing/skills/audit/SKILL.md index 9fb2a1c6a6..50b1c73807 100644 --- a/plugins/mutation-testing/skills/audit/SKILL.md +++ b/plugins/mutation-testing/skills/audit/SKILL.md @@ -75,7 +75,7 @@ Three properties, stated first because everything below depends on them: later phase runs and nothing is persisted ([Phase 3](#phase-3-execute)). Per the naming doctrine's verb contract, `audit` reports and stops, and bare invocation does exactly that. `--persist-findings` is the explicit user override that verb contract sanctions - (the marketplace's `docs/PLUGIN-PHILOSOPHY.md` verb table). Its writes, the findings file and + (the marketplace's `docs/plugin-philosophy.md` verb table). Its writes, the findings file and the self-ignore guard's own `.gitignore` when a governing checkout was found and the guard heals that root, are each **proven outside tracked space before that write is made**, never in tracked source and never in a file another producer owns. diff --git a/plugins/mutation-testing/skills/setup/SKILL.md b/plugins/mutation-testing/skills/setup/SKILL.md index 3d39c65381..1537f1f286 100644 --- a/plugins/mutation-testing/skills/setup/SKILL.md +++ b/plugins/mutation-testing/skills/setup/SKILL.md @@ -13,7 +13,7 @@ Establish the four things `/mutation-testing:audit` cannot infer safely at run t Configuration is required rather than optional here, which differs from a plugin whose config merely speeds up inference. A mutation run drives the project's own test runner against deliberately broken source; guessing the tool or the diff target either does nothing or does something expensive. -Check-centric per the uniform setup contract (`docs/PLUGIN-PHILOSOPHY.md` +Check-centric per the uniform setup contract (`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in the marketplace repository): `check` inspects read-only; `apply` interviews and writes, then re-runs `check`. No argument or `check` runs the check; `apply` runs the check first, then the write flow. diff --git a/plugins/overengineering/.claude-plugin/plugin.json b/plugins/overengineering/.claude-plugin/plugin.json index 46d1b9e14d..273edfed1f 100644 --- a/plugins/overengineering/.claude-plugin/plugin.json +++ b/plugins/overengineering/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "overengineering", - "version": "0.4.10", + "version": "0.4.11", "description": "Evidence-earned-keep audit of an existing enforcement surface, covering agent hooks and standing instructions, repository and version-control hooks, CI lanes and gate scripts, branch protections, forge apps, and declared external integrations. It treats every incumbent mechanism as a retirement candidate until empirical evidence earns its keep, argues every verdict in cost of carry, caps retirement-direction verdicts on security-class artifacts at FLAG-FOR-HUMAN, and realigns to the simplest adequate solution behind an explicit per-item human gate. The audit is read-only and emits a diffable findings artifact; realignment is a separate, explicitly invoked skill; and a third read-only lane re-runs the audit on whatever cadence the consumer wires and reports only what moved since the last run, above a configurable noise budget. A justification lane applies the same method to whatever single artifact you point at, a decision record, a document, a component, a dependency, or a code construct, asking whether a reason existed for it and whether that reason still holds, and reporting how much evidence each verdict actually rests on.", "author": { "name": "Melodic Software", diff --git a/plugins/overengineering/CHANGELOG.md b/plugins/overengineering/CHANGELOG.md index 33ffb6372d..6c9b270272 100644 --- a/plugins/overengineering/CHANGELOG.md +++ b/plugins/overengineering/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `overengineering` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.4.11] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.4.10] ### Changed diff --git a/plugins/overengineering/context/findings-artifact.md b/plugins/overengineering/context/findings-artifact.md index bd0401577a..c6ef9af4e3 100644 --- a/plugins/overengineering/context/findings-artifact.md +++ b/plugins/overengineering/context/findings-artifact.md @@ -679,7 +679,7 @@ therefore belongs to that mechanic, and the artifact's own writes stay in `audit ## External authority -- `docs/PLUGIN-ARTIFACT-PROTOCOL.md`: the lifecycle profile this artifact conforms to, covering +- `docs/plugin-artifact-protocol.md`: the lifecycle profile this artifact conforms to, covering memory-tier placement, resolution through the current plugin's `reference/topic-docs.md` binding, and the missing-prerequisite stop. - `docs/conventions/finding-suppression/`: the `finding_id` derivation, the required entry keys, diff --git a/plugins/planning/.claude-plugin/plugin.json b/plugins/planning/.claude-plugin/plugin.json index c40084cb0b..77890e266d 100644 --- a/plugins/planning/.claude-plugin/plugin.json +++ b/plugins/planning/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "planning", - "version": "0.39.7", + "version": "0.39.8", "userConfig": { "use_ask_user_question": { "type": "boolean", diff --git a/plugins/planning/CHANGELOG.md b/plugins/planning/CHANGELOG.md index b2b0bee172..2f09a2d141 100644 --- a/plugins/planning/CHANGELOG.md +++ b/plugins/planning/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `planning` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.39.8] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.39.7] ### Changed diff --git a/plugins/planning/skills/audit-answers/SKILL.md b/plugins/planning/skills/audit-answers/SKILL.md index 0017595703..edb58112ee 100644 --- a/plugins/planning/skills/audit-answers/SKILL.md +++ b/plugins/planning/skills/audit-answers/SKILL.md @@ -57,7 +57,7 @@ Everything else enters the provisional set as an accepted answer for validation. ### Step 2. Dispatch fresh-context validators -Dispatch **1–3 fresh-context (non-fork) adversarial validator subagents**, **each reviewing the whole answer set**. The count scales independent redundancy (more validators = more independent cross-checks on *every* answer), never a sharding of the work. Every validator sees every answer, so the Step 4 merge can require agreement across all of them; splitting coverage would make "confirmed by all" indistinguishable from "unseen by some" and is not done. A fork inherits this session's reasoning and would carry its bias forward, so a validator MUST be a fresh-context (non-fork) subagent that never saw the interview happen. This is the self-grade fresh-eyes rule the marketplace mandates for any step that judges its own context's work. Where the verdict is high-stakes and correlated blind spots are the risk, prefer a cross-vendor advisor for a validator **when one is installed and set up**. E.g. the OpenAI Codex plugin, when its documented surface can take this artifact, invoked per its own docs. With the fresh-context same-vendor subagent as the stated fallback, never a route to a command that may not resolve (per `docs/PLUGIN-PHILOSOPHY.md` "Fresh-eyes checkpoints" in the marketplace repository). +Dispatch **1–3 fresh-context (non-fork) adversarial validator subagents**, **each reviewing the whole answer set**. The count scales independent redundancy (more validators = more independent cross-checks on *every* answer), never a sharding of the work. Every validator sees every answer, so the Step 4 merge can require agreement across all of them; splitting coverage would make "confirmed by all" indistinguishable from "unseen by some" and is not done. A fork inherits this session's reasoning and would carry its bias forward, so a validator MUST be a fresh-context (non-fork) subagent that never saw the interview happen. This is the self-grade fresh-eyes rule the marketplace mandates for any step that judges its own context's work. Where the verdict is high-stakes and correlated blind spots are the risk, prefer a cross-vendor advisor for a validator **when one is installed and set up**. E.g. the OpenAI Codex plugin, when its documented surface can take this artifact, invoked per its own docs. With the fresh-context same-vendor subagent as the stated fallback, never a route to a command that may not resolve (per `docs/plugin-philosophy.md` "Fresh-eyes checkpoints" in the marketplace repository). Each validator receives the whole provisional answer set and the interview's persisted context (Brief or general summary), **with the recommendation's persuasive rationale WITHHELD**. It audits the decision, not the story that sold it. Hand it *what* was decided, never *why the orchestrator liked it*: a validator handed the pitch inherits the pitch's blind spot. diff --git a/plugins/planning/skills/brainstorm/SKILL.md b/plugins/planning/skills/brainstorm/SKILL.md index beb37f4945..a452a83b6b 100644 --- a/plugins/planning/skills/brainstorm/SKILL.md +++ b/plugins/planning/skills/brainstorm/SKILL.md @@ -12,7 +12,7 @@ metadata: The divergence step before any scoping: unknown-knowns (criteria the user only recognizes when seen) surface cheapest at candidate-list time. Finding one mid-implementation costs a re-plan. A brainstorm round also calibrates scope: reacting to a cheapest→most-ambitious spread prevents locking a scope that is too narrow (missed the high-value approach) or too wide (ambition the problem doesn't need). -Opening a fresh session on a rough problem with a brainstorm is a citable practice, not a detour: the cheapest→ambitious spread is the cheapest artifact that surfaces criteria the user only recognizes when seen (rationale and sources: `docs/FINDING-YOUR-UNKNOWNS.md` in the marketplace repository). +Opening a fresh session on a rough problem with a brainstorm is a citable practice, not a detour: the cheapest→ambitious spread is the cheapest artifact that surfaces criteria the user only recognizes when seen (rationale and sources: `docs/finding-your-unknowns.md` in the marketplace repository). Distinct neighbors: `/planning:design` Phase 1 decomposes the problem space WITHIN a design task already chosen; a proactive architecture-friction scan (e.g. `/architecture:improve`, if installed) hunts on its own lanes; a UI-variation prototyper (e.g. `/prototype:explore-directions`, if installed) builds visual variations of a chosen direction. This skill is the general, problem-shaped entry upstream of all three. Creative-domain ideation owned by a domain skill (e.g. songwriting brainstorms → `/songwriting:workflow`, if installed) stays with that skill. diff --git a/plugins/planning/skills/devils-advocate/SKILL.md b/plugins/planning/skills/devils-advocate/SKILL.md index bb43babbf9..4b4dfaa976 100644 --- a/plugins/planning/skills/devils-advocate/SKILL.md +++ b/plugins/planning/skills/devils-advocate/SKILL.md @@ -42,7 +42,7 @@ This stress-test runs from a fresh pair of eyes, and dispatches to a fresh-conte - **Plan-review mode**. If the plan under review was produced in THIS context/session, the producing context shares the assumptions that created the plan's blind spots and drifts toward approving its own work; dispatch the stress-test to a fresh-context sub-agent. When you were invoked on an artifact this context did not author (a file, a plan from another session, a diff), you are already the fresh pair of eyes. Proceed directly. - **`incumbent` mode**. Always dispatch. The incumbent lives in the current codebase, so any read of it you already hold is a digest; a first-hand exploration is what forms an independent view. The sub-agent invokes `/discovery:explore` via the Skill tool (if installed, else explores directly) on the incumbent itself (Alternatives Sweep, Step 1). -In both cases the dispatch prompt carries only WHAT to investigate: the plan artifact, or the incumbent's identity and where it lives, never your conclusions about it. "Here is the target; go look yourself," not "here is what I found; confirm it." A sub-agent handed the parent's verdict inherits the parent's blind spot. Where the verdict is high-stakes and correlated blind spots are the risk, prefer a cross-vendor advisor for that fresh pair of eyes **when one is installed and set up**, for example the OpenAI Codex plugin, when its documented surface can take this artifact, invoked per its own docs, with the fresh-context same-vendor sub-agent as the stated fallback, never a route to a command that may not resolve (per `docs/PLUGIN-PHILOSOPHY.md` "Fresh-eyes checkpoints" in the marketplace repository). +In both cases the dispatch prompt carries only WHAT to investigate: the plan artifact, or the incumbent's identity and where it lives, never your conclusions about it. "Here is the target; go look yourself," not "here is what I found; confirm it." A sub-agent handed the parent's verdict inherits the parent's blind spot. Where the verdict is high-stakes and correlated blind spots are the risk, prefer a cross-vendor advisor for that fresh pair of eyes **when one is installed and set up**, for example the OpenAI Codex plugin, when its documented surface can take this artifact, invoked per its own docs, with the fresh-context same-vendor sub-agent as the stated fallback, never a route to a command that may not resolve (per `docs/plugin-philosophy.md` "Fresh-eyes checkpoints" in the marketplace repository). ## When to Use diff --git a/plugins/planning/skills/plan/SKILL.md b/plugins/planning/skills/plan/SKILL.md index b61fa518a3..57433899f8 100644 --- a/plugins/planning/skills/plan/SKILL.md +++ b/plugins/planning/skills/plan/SKILL.md @@ -143,7 +143,7 @@ Per-scale calibration examples live in [context/plan-template.md](context/plan-t ### Step 3: Plan Stress-Test (MANDATORY. Never skip) -**Before assessing blast radius or presenting ANY plan, dispatch a fresh-context plan-reviewer sub-agent.** The producing main thread MUST NOT self-attack the plan inline. Fresh-context verifiers outperform self-critique; the model that just wrote the plan rubber-stamps it. Where the plan is high-stakes and correlated blind spots are the risk, prefer a cross-vendor advisor **when one is installed and set up**. E.g. the OpenAI Codex plugin, when its documented surface can take this artifact, invoked per its own docs. With the fresh-context plan-reviewer sub-agent as the stated fallback, never a route to a command that may not resolve (per `docs/PLUGIN-PHILOSOPHY.md` "Fresh-eyes checkpoints" in the marketplace repository). +**Before assessing blast radius or presenting ANY plan, dispatch a fresh-context plan-reviewer sub-agent.** The producing main thread MUST NOT self-attack the plan inline. Fresh-context verifiers outperform self-critique; the model that just wrote the plan rubber-stamps it. Where the plan is high-stakes and correlated blind spots are the risk, prefer a cross-vendor advisor **when one is installed and set up**. E.g. the OpenAI Codex plugin, when its documented surface can take this artifact, invoked per its own docs. With the fresh-context plan-reviewer sub-agent as the stated fallback, never a route to a command that may not resolve (per `docs/plugin-philosophy.md` "Fresh-eyes checkpoints" in the marketplace repository). 1. Gather the plan draft + design artifacts (or `design-resolution.md`) + the Brief 2. Dispatch a read-only general sub-agent with the prompt from [context/plan-reviewer.md](context/plan-reviewer.md) diff --git a/plugins/planning/skills/wayfind/SKILL.md b/plugins/planning/skills/wayfind/SKILL.md index 3ad78b1fde..65a6a53074 100644 --- a/plugins/planning/skills/wayfind/SKILL.md +++ b/plugins/planning/skills/wayfind/SKILL.md @@ -183,7 +183,7 @@ owns the trigger's meaning (too-big + fog, both, not either alone). For pre-implementation efforts, the routed items above compose into a known five-pass order (blindspot → brainstorm/prototype → interview → reference port → plan); the workflow section of -`docs/FINDING-YOUR-UNKNOWNS.md` in the marketplace repository states it with rationale. +`docs/finding-your-unknowns.md` in the marketplace repository states it with rationale. ## What this skill does NOT do diff --git a/plugins/planning/tests/interview-defenses.test.sh b/plugins/planning/tests/interview-defenses.test.sh index f2eda78f90..966aae2604 100755 --- a/plugins/planning/tests/interview-defenses.test.sh +++ b/plugins/planning/tests/interview-defenses.test.sh @@ -12,7 +12,7 @@ # `blocked` with arbiter USER-RESERVED. It is never captured as an assumption. # # The lane-4 audit graded both defenses as holding. They are prose rules with no runner -# behind them: the marketplace has no model-graded eval runner (docs/MIGRATION-PLAYBOOK.md, +# behind them: the marketplace has no model-graded eval runner (docs/migration-playbook.md, # "Method source" — grading is a human judgment pass until the deferred runner lands), so # the eval cases in skills/interview/evals/evals.json are a rubric, not a gate. This suite # is the gate: it pins the eval cases that grade each defense AND the load-bearing rule text @@ -96,7 +96,7 @@ # ones read as bearing on them today, not a closed set. # - Anything semantic. This gate proves the RULE TEXT and the CASE INPUTS are intact. It # cannot prove the skill OBEYS them — only a model-graded runner could, and the -# marketplace has none (docs/MIGRATION-PLAYBOOK.md, "Method source"). +# marketplace has none (docs/migration-playbook.md, "Method source"). # Read this suite as raising the cost of a silent weakening, never as proving one # impossible. # diff --git a/plugins/playbooks/.claude-plugin/plugin.json b/plugins/playbooks/.claude-plugin/plugin.json index 73ec7608ae..52d3444daf 100644 --- a/plugins/playbooks/.claude-plugin/plugin.json +++ b/plugins/playbooks/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "playbooks", - "version": "0.11.2", + "version": "0.11.3", "description": "Doctrine and knowledge playbooks as on-demand skills, plus a maintainer-facing update skill. boris carries Boris Cherny's Claude Code workflow tips (howborisusesclaudecode.com), skill-authoring carries Anthropic's internal skill-authoring playbook, and fable-5 carries Claude Fable 5's operating doctrine (self-authored, no upstream). The boris and skill-authoring packs vendor a verbatim upstream baseline; /playbooks:update drift-checks and syncs those baselines centrally (maintainers).", "author": { "name": "Melodic Software", diff --git a/plugins/playbooks/CHANGELOG.md b/plugins/playbooks/CHANGELOG.md index 4d2d3d2255..f84dbe24fc 100644 --- a/plugins/playbooks/CHANGELOG.md +++ b/plugins/playbooks/CHANGELOG.md @@ -4,6 +4,12 @@ All notable changes to the `playbooks` plugin are recorded here. The `version` i `.claude-plugin/plugin.json` is the delivery vehicle. A consumer receives a change only after that version increases. +## [0.11.3] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.11.2] ### Changed diff --git a/plugins/playbooks/reference/prompt-caching.md b/plugins/playbooks/reference/prompt-caching.md index 44e80fb0d1..57c626f488 100644 --- a/plugins/playbooks/reference/prompt-caching.md +++ b/plugins/playbooks/reference/prompt-caching.md @@ -101,7 +101,7 @@ check or a docs page settles it. ## Session-side counterparts Claude Code owns request assembly in a session, so the session-side versions of these rows live -elsewhere: effort-change cache cost and per-message steering in `docs/PLUGIN-PHILOSOPHY.md` +elsewhere: effort-change cache cost and per-message steering in `docs/plugin-philosophy.md` under Effort tiers, subagent cache TTL mechanics in the fable-5 pack's `context/orchestration.md`, session cache-health observability in the `claude-ops` observability skill, and the byte-identical-prefix rule as it reaches shared-prefix fleets in the diff --git a/plugins/playbooks/skills/fable-5/context/orchestration.md b/plugins/playbooks/skills/fable-5/context/orchestration.md index 7a7deb3036..5dc9c2aeb5 100644 --- a/plugins/playbooks/skills/fable-5/context/orchestration.md +++ b/plugins/playbooks/skills/fable-5/context/orchestration.md @@ -68,7 +68,7 @@ A worker's return is recall-grade knowledge per the calibration chapter, section In-context adversarial self-review, per the verification chapter, section "Adversarial self-review", is the floor at every effort level; wherever the trigger below fires, self-review is never the final gate, because the context that produced the changes contains the exact assumptions that produced the error and converges on approval rather than detection. -The independence gradient runs further than fresh context alone: self-review (floor) < a fresh **same-vendor** context (strips the producer's rationale) < a **different-vendor** model (strips the producer's training priors too, and its errors are uncorrelated with yours, so it catches failure classes a same-family reviewer shares). Reach for the strongest independent critic the work warrants. A high-blast-radius verification is the natural place to prefer a cross-vendor advisor such as the OpenAI Codex plugin, **when one is installed and set up** and its documented surface can take this artifact, invoked per its own docs. The fresh-context same-vendor subagent is the stated fallback, never a route to a command that may not resolve (per `docs/PLUGIN-PHILOSOPHY.md` "Fresh-eyes checkpoints" in the marketplace repository). +The independence gradient runs further than fresh context alone: self-review (floor) < a fresh **same-vendor** context (strips the producer's rationale) < a **different-vendor** model (strips the producer's training priors too, and its errors are uncorrelated with yours, so it catches failure classes a same-family reviewer shares). Reach for the strongest independent critic the work warrants. A high-blast-radius verification is the natural place to prefer a cross-vendor advisor such as the OpenAI Codex plugin, **when one is installed and set up** and its documented surface can take this artifact, invoked per its own docs. The fresh-context same-vendor subagent is the stated fallback, never a route to a command that may not resolve (per `docs/plugin-philosophy.md` "Fresh-eyes checkpoints" in the marketplace repository). TRIGGER: a fresh-context verifier is required in addition to the floor: after any multi-file edit batch, and before declaring any multi-part task complete. Each trigger is exempt only when *every* batch it covers is mechanical, meaning a transform with no judgment call, so a second author given the same rule would produce the same edit, *and* behavior-preserving (the planning chapter's distinction) *and* narrow in blast radius; a hand-designed refactor fails the first condition however well it preserves behavior. All three are required, because only a judgment-free transform carries none of the producer-blind-spot risk an independent reader exists to catch, so the post-batch trigger weighs that one batch, while the completion trigger weighs every batch in the task and one behavior-changing batch anywhere in it keeps the gate, however mechanical the last batch was. A subjective verdict, or a wide blast radius, defeats the exemption inside a trigger that already fired; neither creates a trigger on its own, so a subjective single-file, single-part change still takes only the floor. Outside these two triggers, the in-context floor suffices. diff --git a/plugins/playwright/.claude-plugin/plugin.json b/plugins/playwright/.claude-plugin/plugin.json index aec1511f3d..346a1ce0dc 100644 --- a/plugins/playwright/.claude-plugin/plugin.json +++ b/plugins/playwright/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "playwright", - "version": "0.6.10", + "version": "0.6.11", "description": "Live E2E browser automation via Microsoft's @playwright/cli: named sessions, accessibility-ref snapshots, click/fill by ref, screenshots, console and network capture, mocking, tracing, video, and auth state, with artifacts written to disk so only paths enter context, plus a vendored upstream baseline and maintainer drift-check update flow.", "author": { "name": "Melodic Software", diff --git a/plugins/playwright/CHANGELOG.md b/plugins/playwright/CHANGELOG.md index c5253a70cf..5c64bce25b 100644 --- a/plugins/playwright/CHANGELOG.md +++ b/plugins/playwright/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `playwright` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.6.11] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.6.10] ### Changed diff --git a/plugins/playwright/skills/setup/SKILL.md b/plugins/playwright/skills/setup/SKILL.md index edf65ba3b7..35dfc8a071 100644 --- a/plugins/playwright/skills/setup/SKILL.md +++ b/plugins/playwright/skills/setup/SKILL.md @@ -7,7 +7,7 @@ disable-model-invocation: true ## Purpose -Thin check-centric setup per the uniform setup contract (`docs/PLUGIN-PHILOSOPHY.md` +Thin check-centric setup per the uniform setup contract (`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in the marketplace repository): `check` inspects and reports, `apply` resolves. This plugin owns no consumer-project configuration and no `userConfig`. It recommends `@playwright/cli`'s own defaults, so the only tunable diff --git a/plugins/plugin-quality/.claude-plugin/plugin.json b/plugins/plugin-quality/.claude-plugin/plugin.json index 69b6794185..5da19628dc 100644 --- a/plugins/plugin-quality/.claude-plugin/plugin.json +++ b/plugins/plugin-quality/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "plugin-quality", - "version": "0.7.14", + "version": "0.7.15", "description": "Post-use behavioral audit of Claude Code plugin components: a six-step audit workflow (evidence capture, grounded mapping in a fresh subagent, blindspot pass, interactive contract lock, presence-gated review seams, work-item emit with draft+confirm) over any skill, agent, hook, command, or config you have actually used, zone-informed by context-guard snapshots when present, conservative when not.", "author": { "name": "Melodic Software", diff --git a/plugins/plugin-quality/CHANGELOG.md b/plugins/plugin-quality/CHANGELOG.md index 64e6b606c6..0e39f3e48b 100644 --- a/plugins/plugin-quality/CHANGELOG.md +++ b/plugins/plugin-quality/CHANGELOG.md @@ -5,6 +5,12 @@ All notable changes to the `plugin-quality` plugin. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [0.7.15] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.7.14] ### Changed diff --git a/plugins/plugin-quality/skills/audit/reference/component-types/hook.md b/plugins/plugin-quality/skills/audit/reference/component-types/hook.md index 1beeb14198..ef933d6cac 100644 --- a/plugins/plugin-quality/skills/audit/reference/component-types/hook.md +++ b/plugins/plugin-quality/skills/audit/reference/component-types/hook.md @@ -17,7 +17,7 @@ PreToolUse / PostToolUse / lifecycle hook scripts. against the current hooks reference, not memory. Verified 2026-08-21 against [Hooks reference: Exit code output](https://code.claude.com/docs/en/hooks#exit-code-output). Recheck when the hooks reference changelog or the `hooks` doc page changes in a Claude Code release - this repo's `OFFICIAL-DOCS.md` index records. + this repo's `official-docs.md` index records. - **Fail-open vs fail-closed** on missing deps (jq), empty/timed-out stdin, parse errors. - **Enablement/scope probe**: if it self-disables based on plugin enablement or settings, does it read the *merged effective* scopes (user-global + project + local), not just one? diff --git a/plugins/powershell-format/.claude-plugin/plugin.json b/plugins/powershell-format/.claude-plugin/plugin.json index f4b3888760..e10736066b 100644 --- a/plugins/powershell-format/.claude-plugin/plugin.json +++ b/plugins/powershell-format/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "powershell-format", - "version": "0.7.48", + "version": "0.7.49", "description": "Auto-format and lint PowerShell on edit via PSScriptAnalyzer, only when a PSScriptAnalyzerSettings.psd1 governs the repo, using the consuming repo's own analyzer settings.", "author": { "name": "Melodic Software", diff --git a/plugins/powershell-format/CHANGELOG.md b/plugins/powershell-format/CHANGELOG.md index 5b1181e765..78c0f73d5c 100644 --- a/plugins/powershell-format/CHANGELOG.md +++ b/plugins/powershell-format/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `powershell-format` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.7.49] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.7.48] ### Changed diff --git a/plugins/powershell-format/skills/setup/SKILL.md b/plugins/powershell-format/skills/setup/SKILL.md index 2ce13de1bb..5ea0845903 100644 --- a/plugins/powershell-format/skills/setup/SKILL.md +++ b/plugins/powershell-format/skills/setup/SKILL.md @@ -7,7 +7,7 @@ disable-model-invocation: true ## Purpose -Thin check-centric setup per the uniform setup contract (`docs/PLUGIN-PHILOSOPHY.md` +Thin check-centric setup per the uniform setup contract (`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in the marketplace repository): `check` inspects and reports, `apply` resolves. This plugin owns no consumer-project configuration. Formatting and linting rules come from the repository's own `PSScriptAnalyzerSettings.psd1`, and the diff --git a/plugins/provenance/.claude-plugin/plugin.json b/plugins/provenance/.claude-plugin/plugin.json index 9a40e91160..22d3528576 100644 --- a/plugins/provenance/.claude-plugin/plugin.json +++ b/plugins/provenance/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "provenance", - "version": "0.5.10", + "version": "0.5.11", "description": "Finds prose in tracked markdown that restates content an external source owns (vendor docs, blogs, articles) without adequate attribution, confirms the source, and refactors the copy into a pointer, a citation, or a dated stamped record. Documentation provenance, not software supply chain. Nomination and judgment are LLM work; the scripts do only reasoning-free work (corpus scoping, breadcrumb extraction, stamp expiry, fingerprint compare of two concrete texts). Read-only audit by default; explicit fix and sweep actions apply dispositions behind a semantic-diff guard and live pointer verification. Findings conform to the detector-findings convention.", "author": { "name": "Melodic Software", diff --git a/plugins/provenance/CHANGELOG.md b/plugins/provenance/CHANGELOG.md index 0a1f4d95e2..d03898e2b8 100644 --- a/plugins/provenance/CHANGELOG.md +++ b/plugins/provenance/CHANGELOG.md @@ -1,5 +1,11 @@ # Changelog +## [0.5.11] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.5.10] ### Changed diff --git a/plugins/provenance/skills/audit/scripts/extract-breadcrumbs.sh b/plugins/provenance/skills/audit/scripts/extract-breadcrumbs.sh index ddf07af6bd..608e5f1599 100755 --- a/plugins/provenance/skills/audit/scripts/extract-breadcrumbs.sh +++ b/plugins/provenance/skills/audit/scripts/extract-breadcrumbs.sh @@ -240,7 +240,7 @@ function is_stamp(line, low, pos, rest, rest_orig, off, kw, wlen) { # (the 10-character ISO date; the "may" rule is unbounded and can outrun the # slack, as check-stamps.sh notes at the same rule), and require # each match to BEGIN at or before wlen. Slicing at exactly wlen dropped - # docs/CLOUD-SESSIONS.md:320 from this inventory while check-stamps.sh + # docs/cloud-sessions.md:320 from this inventory while check-stamps.sh # counted it a candidate: its date starts at offset 60 of 60, so the cut # left a bare "2" and no form matched. These two scripts promise the same # candidate definition, so the boundary has to be the same in both. diff --git a/plugins/provenance/skills/audit/scripts/extract-breadcrumbs.test.sh b/plugins/provenance/skills/audit/scripts/extract-breadcrumbs.test.sh index d02ac91436..35b30c7c36 100755 --- a/plugins/provenance/skills/audit/scripts/extract-breadcrumbs.test.sh +++ b/plugins/provenance/skills/audit/scripts/extract-breadcrumbs.test.sh @@ -188,7 +188,7 @@ STRADDLE_DIR="$TEST_TMPDIR/straddle" mkdir -p "$STRADDLE_DIR" { printf '# Straddle\n\n' - # Taken from docs/CLOUD-SESSIONS.md:320, which check-stamps.sh counts as a + # Taken from docs/cloud-sessions.md:320, which check-stamps.sh counts as a # candidate and this extractor did not. One keyword, and the date sits far # enough from it that the 60-character slice cut the year in half. Note the # line must carry no SECOND keyword: "as-of" beside the date would restart diff --git a/plugins/rate-limit-guard/.claude-plugin/plugin.json b/plugins/rate-limit-guard/.claude-plugin/plugin.json index 47ce5456f2..4924146d94 100644 --- a/plugins/rate-limit-guard/.claude-plugin/plugin.json +++ b/plugins/rate-limit-guard/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "rate-limit-guard", - "version": "0.8.11", + "version": "0.8.12", "description": "Shared rate-limit guard for loop lanes: a statusline wrapper tees the subscription rate-limit windows to a fixed machine-scope file, a StopFailure hook records rate-limit stops reactively, and a reader contract fixes how consuming sessions pause and resume.", "author": { "name": "Melodic Software", diff --git a/plugins/rate-limit-guard/CHANGELOG.md b/plugins/rate-limit-guard/CHANGELOG.md index 538bb18731..f1746092b7 100644 --- a/plugins/rate-limit-guard/CHANGELOG.md +++ b/plugins/rate-limit-guard/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `rate-limit-guard` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.8.12] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.8.11] ### Changed diff --git a/plugins/rate-limit-guard/skills/setup/SKILL.md b/plugins/rate-limit-guard/skills/setup/SKILL.md index 460f992409..f8c9b51237 100644 --- a/plugins/rate-limit-guard/skills/setup/SKILL.md +++ b/plugins/rate-limit-guard/skills/setup/SKILL.md @@ -261,7 +261,7 @@ fallback lives in the file that was just deleted. ## What this skill does NOT do - Write the plugin cache, Claude Code user settings, or `pluginConfigs`, per the uniform setup - contract (`docs/PLUGIN-PHILOSOPHY.md` "Setup is explicit and repeatable" in the marketplace + contract (`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in the marketplace repository). Nor `settings.json` (user or project) or any other Claude Code settings surface; the printed edit is the operator's to apply. - Install `jq` or any system package. diff --git a/plugins/repo-fleet-hygiene/.claude-plugin/plugin.json b/plugins/repo-fleet-hygiene/.claude-plugin/plugin.json index f237609a91..3c83a8fe92 100644 --- a/plugins/repo-fleet-hygiene/.claude-plugin/plugin.json +++ b/plugins/repo-fleet-hygiene/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "repo-fleet-hygiene", - "version": "0.23.24", + "version": "0.23.25", "description": "Cross-repository Git/GitHub fleet discovery, evidence rollup, and a gated apply verb that executes a prior fleet action plan behind one confirmation. Audit stays read-only and confidence-tiered; apply mutates only with --apply plus interactive confirmation or --yes.", "author": { "name": "Melodic Software", diff --git a/plugins/repo-fleet-hygiene/CHANGELOG.md b/plugins/repo-fleet-hygiene/CHANGELOG.md index d4914623c1..d009ea9828 100644 --- a/plugins/repo-fleet-hygiene/CHANGELOG.md +++ b/plugins/repo-fleet-hygiene/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to `repo-fleet-hygiene` are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.23.25] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.23.24] ### Changed diff --git a/plugins/repo-fleet-hygiene/skills/setup/SKILL.md b/plugins/repo-fleet-hygiene/skills/setup/SKILL.md index e20675029b..fea1f4935e 100644 --- a/plugins/repo-fleet-hygiene/skills/setup/SKILL.md +++ b/plugins/repo-fleet-hygiene/skills/setup/SKILL.md @@ -15,7 +15,7 @@ requires scope from somewhere: CLI bare path / `--root` / `--repo`, or `fleet.ro entries in a consumed config. Absence of every config on the ladder is therefore INFO for `check` (nothing to validate yet) and a hard failure for a subsequent no-argument audit, not a silent default to the current project. Check-centric per the uniform setup contract -(`docs/PLUGIN-PHILOSOPHY.md` "Setup is explicit and repeatable" in the marketplace repository): +(`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in the marketplace repository): `check` inspects read-only; `apply` creates or updates the file, then re-runs `check`. No argument or `check` runs the check; `apply` runs the check first, then the write. All non-interactive: when the arguments fully specify the change, `apply` proceeds without prompting. diff --git a/plugins/repo-hygiene/.claude-plugin/plugin.json b/plugins/repo-hygiene/.claude-plugin/plugin.json index c8d82862e2..891dcf041c 100644 --- a/plugins/repo-hygiene/.claude-plugin/plugin.json +++ b/plugins/repo-hygiene/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "repo-hygiene", - "version": "0.10.40", + "version": "0.10.41", "description": "Repo hygiene action-router: /repo-hygiene:clean sweeps reclaimable caches, build artifacts, and stale git metadata, and can realign the working tree to a fresh-pull state, dry-run-first, with destructive tiers gated behind explicit confirmation and a session-scoped destructive-command guard. Ecosystem targets are detected at runtime; secrets, runtime dependencies, and skill data are preserved by default.", "author": { "name": "Melodic Software", diff --git a/plugins/repo-hygiene/CHANGELOG.md b/plugins/repo-hygiene/CHANGELOG.md index 5928dba3e9..f17da3528e 100644 --- a/plugins/repo-hygiene/CHANGELOG.md +++ b/plugins/repo-hygiene/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `repo-hygiene` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.10.41] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.10.40] ### Changed diff --git a/plugins/repo-hygiene/skills/setup/SKILL.md b/plugins/repo-hygiene/skills/setup/SKILL.md index 6bb8efb161..c1e7702f9c 100644 --- a/plugins/repo-hygiene/skills/setup/SKILL.md +++ b/plugins/repo-hygiene/skills/setup/SKILL.md @@ -7,7 +7,7 @@ disable-model-invocation: true ## Purpose -Check-only setup under the Check-only carve-out (`docs/PLUGIN-PHILOSOPHY.md` "Setup is explicit +Check-only setup under the Check-only carve-out (`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in the marketplace repository): this plugin's configuration surface contains no writable artifact, so `check` inspects, reports, and points at each remediation, and no `apply` is offered because there is nothing it could conformingly write. The warrant is the carve-out's diff --git a/plugins/review/.claude-plugin/plugin.json b/plugins/review/.claude-plugin/plugin.json index 89866fd764..52d1389742 100644 --- a/plugins/review/.claude-plugin/plugin.json +++ b/plugins/review/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "review", - "version": "0.28.1", + "version": "0.28.2", "description": "Code-review toolkit: six read-only reviewer agents (code, security, architecture, doc drift, build/test/lint, CI-log audit), plus orchestration skills for the quality gate, fan-out, and enforceability audit (/review:audit-enforceability), and CI lane commands (/review:code-review, /review:security-review) for org reusable workflows.", "author": { "name": "Melodic Software", diff --git a/plugins/review/CHANGELOG.md b/plugins/review/CHANGELOG.md index 03633f8f07..2eb0c719ac 100644 --- a/plugins/review/CHANGELOG.md +++ b/plugins/review/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `review` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.28.2] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.28.1] ### Changed diff --git a/plugins/review/skills/quality-gate/context/downstream.md b/plugins/review/skills/quality-gate/context/downstream.md index ca3e60f6d8..3289481433 100644 --- a/plugins/review/skills/quality-gate/context/downstream.md +++ b/plugins/review/skills/quality-gate/context/downstream.md @@ -24,7 +24,7 @@ blind spots are the risk, prefer a cross-vendor advisor **when one is installed example the OpenAI Codex plugin, when its documented surface can take this artifact, invoked per its own docs, with the fresh-context same-vendor subagent as the stated fallback, never a route to a command that may not resolve -(per [`docs/PLUGIN-PHILOSOPHY.md`](https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/docs/PLUGIN-PHILOSOPHY.md) +(per [`docs/plugin-philosophy.md`](https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/docs/plugin-philosophy.md) "Fresh-eyes checkpoints"). ## Orchestrator sequence (main thread) diff --git a/plugins/review/skills/quality-gate/context/self.md b/plugins/review/skills/quality-gate/context/self.md index a03362b696..f1848f57b7 100644 --- a/plugins/review/skills/quality-gate/context/self.md +++ b/plugins/review/skills/quality-gate/context/self.md @@ -2,7 +2,7 @@ Design judgment and completeness check after implementation, before verification or PR. **Not a build check.** -**Dispatch policy:** the producing main thread MUST NOT run the checklist inline. The thread that wrote the code rubber-stamps its own recap. Orchestrate a fresh-context read-only subagent; the main thread gathers inputs, dispatches, verifies findings, and presents the verdict. Where the verdict is high-stakes and correlated blind spots are the risk, prefer a cross-vendor advisor **when one is installed and set up**, for example the OpenAI Codex plugin when its documented surface can take this artifact, invoked per its own docs, with the fresh-context same-vendor subagent as the stated fallback, never a route to a command that may not resolve (per [`docs/PLUGIN-PHILOSOPHY.md`](https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/docs/PLUGIN-PHILOSOPHY.md) "Fresh-eyes checkpoints"). +**Dispatch policy:** the producing main thread MUST NOT run the checklist inline. The thread that wrote the code rubber-stamps its own recap. Orchestrate a fresh-context read-only subagent; the main thread gathers inputs, dispatches, verifies findings, and presents the verdict. Where the verdict is high-stakes and correlated blind spots are the risk, prefer a cross-vendor advisor **when one is installed and set up**, for example the OpenAI Codex plugin when its documented surface can take this artifact, invoked per its own docs, with the fresh-context same-vendor subagent as the stated fallback, never a route to a command that may not resolve (per [`docs/plugin-philosophy.md`](https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/docs/plugin-philosophy.md) "Fresh-eyes checkpoints"). ## Orchestrator sequence (main thread) diff --git a/plugins/review/skills/quality-gate/context/spec.md b/plugins/review/skills/quality-gate/context/spec.md index 2ff255434d..5ea83681e7 100644 --- a/plugins/review/skills/quality-gate/context/spec.md +++ b/plugins/review/skills/quality-gate/context/spec.md @@ -69,7 +69,7 @@ guess a provider; drop to rung 3 and say so. plugin.** A plugin "never imports files from a sibling plugin or discovers another plugin's installation directory," and cooperation goes through "a documented public seam: an artifact contract, an explicit invocation argument, or an optional namespaced skill invocation" -([`docs/PLUGIN-PHILOSOPHY.md`](https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/docs/PLUGIN-PHILOSOPHY.md)). +([`docs/plugin-philosophy.md`](https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/docs/plugin-philosophy.md)). The `work-items` tracker seam's CLI is that plugin's internal surface, so this skill does not invoke it directly. In priority order: diff --git a/plugins/review/skills/setup/SKILL.md b/plugins/review/skills/setup/SKILL.md index 18140a095d..0f83d73dec 100644 --- a/plugins/review/skills/setup/SKILL.md +++ b/plugins/review/skills/setup/SKILL.md @@ -19,7 +19,7 @@ Idempotent: re-running reads the current state and offers an update rather than a re-run against a conforming, current-version index proposes no changes. Action routing per the uniform setup contract -([`docs/PLUGIN-PHILOSOPHY.md`](https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/docs/PLUGIN-PHILOSOPHY.md) +([`docs/plugin-philosophy.md`](https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/docs/plugin-philosophy.md) "Setup is explicit and repeatable"): no argument or `check` runs the binding's state-reading procedure read-only and reports index presence and resolved standards root, per-row path validation, and the DIRECTIONAL version delta as a PASS/FAIL/INFO diff --git a/plugins/ruff-format/.claude-plugin/plugin.json b/plugins/ruff-format/.claude-plugin/plugin.json index 2ae488759b..f0063f9c13 100644 --- a/plugins/ruff-format/.claude-plugin/plugin.json +++ b/plugins/ruff-format/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "ruff-format", - "version": "0.6.46", + "version": "0.6.47", "description": "Auto-format and lint Python on edit via Ruff, only when a Ruff config governs the repo, using the consuming repo's own Ruff config.", "author": { "name": "Melodic Software", diff --git a/plugins/ruff-format/CHANGELOG.md b/plugins/ruff-format/CHANGELOG.md index e0f6816ecc..6d91e1aac7 100644 --- a/plugins/ruff-format/CHANGELOG.md +++ b/plugins/ruff-format/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `ruff-format` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.6.47] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.6.46] ### Changed diff --git a/plugins/ruff-format/skills/setup/SKILL.md b/plugins/ruff-format/skills/setup/SKILL.md index e6e38fd9dc..dceb22e113 100644 --- a/plugins/ruff-format/skills/setup/SKILL.md +++ b/plugins/ruff-format/skills/setup/SKILL.md @@ -7,7 +7,7 @@ disable-model-invocation: true ## Purpose -Thin check-centric setup per the uniform setup contract (`docs/PLUGIN-PHILOSOPHY.md` +Thin check-centric setup per the uniform setup contract (`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in the marketplace repository): `check` inspects and reports, `apply` resolves. This plugin owns no consumer-project configuration. Rules come from the repository's own Ruff config, and the only tunable is the native `userConfig` diff --git a/plugins/session-flow/.claude-plugin/plugin.json b/plugins/session-flow/.claude-plugin/plugin.json index 050f9d94d2..c8520fb77c 100644 --- a/plugins/session-flow/.claude-plugin/plugin.json +++ b/plugins/session-flow/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "session-flow", - "version": "0.35.9", + "version": "0.35.10", "description": "Session-lifecycle toolkit of fourteen skills: workflow (navigate a staged dev workflow and suggest the next stage), handoff (write a save-point and resume prompt for /clear-and-resume), continue-in-background (delegate the task to a fresh background agent that continues it now, using the same save-point engine as handoff, delivered by launching a detached claude --bg session seeded with the resume prompt; launches only on explicit user request), keep-going (recover and continue after any interruption OR when live off-thread work looks stalled: inventory off-thread work, inspect its real output, act only on evidence, then continue; after a usage limit lifts it continues rather than summarizing-and-stalling), find-handoff (recover a lost handoff after /clear, when the resume prompt was written but never copied, via a read-only detection ladder: known-location glob of the handoffs dir, then a bounded, recency-ranked transcript scan for the handoff directive and dashed-rail markers, then a confirm-before-resume gate; surfaces only the resume prompt + metadata, never raw transcript content), clean-stop (get to a durable, linked stopping point before the machine may go away: sweep every repo/worktree for uncommitted, unpushed, or PR-less work, push it durable, put breadcrumbs in PR/issue bodies, then give a free-and-clear verdict), retro (structured end-of-session retrospective with transcript metrics and learning codification), running-retro (in-flight retrospective checkpoints that spawn a subagent to analyze the transcript so far and append classified findings to a cumulative running ledger, which captures and routes only, the live counterpart to retro; also owns a detached-observer substrate that can watch a session out-of-band and run the checkpoint autonomously after the session ends), orient (read-only session orientation: synthesize where the session stands, what it is doing, and why, from durable + off-thread state the built-in /recap never sees: ledgers, handoffs, workflow checklists, running-retro ledgers, open PRs and work-items, and git), orchestrate (arm a session or worker with proactive-orchestration imperatives), reanchor (verify a session's working assumptions are still true against live reality, checking referenced PRs/issues/branches, base-branch drift, renamed/version-drifted surfaces, stale memory-tier files, and the goal a handoff records, compared across the chain so a re-derived goal reports as drift, before building on them), reconcile (retire finished off-thread work and reconcile this session's task ledger with reality, the prune-and-reconcile counterpart to keep-going's resume: inventory the work this session spawned, inspect its real state, retire the finished and close proven-done tasks, auto-settling the finished and gating any kill of still-running work; sibling sessions in the project are reported read-only), setup (check-centric verification of the observer's runtime prerequisites and configuration), and show-options (lay out which skills fit this moment as a ranked, nothing-hidden menu: a shortlist per bucket plus the complete remainder by name, resolved from the full installed catalog rather than the truncated in-context listing, so the human decides and no option is withheld for looking already-done).", "author": { "name": "Melodic Software", diff --git a/plugins/session-flow/CHANGELOG.md b/plugins/session-flow/CHANGELOG.md index c7b6b00b5f..20668d5467 100644 --- a/plugins/session-flow/CHANGELOG.md +++ b/plugins/session-flow/CHANGELOG.md @@ -1,5 +1,11 @@ # Changelog: session-flow plugin +## [0.35.10] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.35.9] ### Changed diff --git a/plugins/session-flow/skills/setup/SKILL.md b/plugins/session-flow/skills/setup/SKILL.md index 328bf02590..e25ad3f130 100644 --- a/plugins/session-flow/skills/setup/SKILL.md +++ b/plugins/session-flow/skills/setup/SKILL.md @@ -7,7 +7,7 @@ disable-model-invocation: true ## Purpose -Check-only setup under the Check-only carve-out (`docs/PLUGIN-PHILOSOPHY.md` "Setup is explicit +Check-only setup under the Check-only carve-out (`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in the marketplace repository): this plugin's configuration surface contains no writable artifact, so `check` inspects, reports, and offers each remediation, and no `apply` is offered because there is nothing it could conformingly write. Only the **detached observer** (see diff --git a/plugins/session-flow/skills/show-options/context/candidate-ladder.md b/plugins/session-flow/skills/show-options/context/candidate-ladder.md index 156ebbf7b4..05e14abe09 100644 --- a/plugins/session-flow/skills/show-options/context/candidate-ladder.md +++ b/plugins/session-flow/skills/show-options/context/candidate-ladder.md @@ -58,7 +58,7 @@ silently listed as runnable and never silently dropped, the same annotate-don't- **Rung 2's shape.** The consuming project publishes a catalog at a documented path it declares; a marketplace that generates one already has the right artifact shape. In the source marketplace here, -`docs/SKILL-CHEAT-SHEET.md` is generated from skill frontmatter by `scripts/generate-cheatsheet.mjs` +`docs/skill-cheat-sheet.md` is generated from skill frontmatter by `scripts/generate-cheatsheet.mjs` and CI-enforced against drift. That is the shape to accept, since it already carries per-skill stage grouping and a one-line summary. Do **not** hardcode that path: the file lives outside any plugin directory, so a plugin copied into a cache cannot reach it, and a consuming repo will not diff --git a/plugins/session-flow/skills/workflow/SKILL.md b/plugins/session-flow/skills/workflow/SKILL.md index 306de1f709..e1b35861ed 100644 --- a/plugins/session-flow/skills/workflow/SKILL.md +++ b/plugins/session-flow/skills/workflow/SKILL.md @@ -81,7 +81,7 @@ PR lifecycle: prep → create → monitor CI → merge (runs after step 7) Stages 0-3 expand, for unfamiliar territory, into a known five-pass pre-implementation order (blindspot → brainstorm/prototype → interview → reference port → plan); the workflow section of -`docs/FINDING-YOUR-UNKNOWNS.md` in the marketplace repository states it with rationale. +`docs/finding-your-unknowns.md` in the marketplace repository states it with rationale. ### 2. Detect current position diff --git a/plugins/session-flow/skills/workflow/context/steps.md b/plugins/session-flow/skills/workflow/context/steps.md index 6b93193eed..ec7bd028e1 100644 --- a/plugins/session-flow/skills/workflow/context/steps.md +++ b/plugins/session-flow/skills/workflow/context/steps.md @@ -73,7 +73,7 @@ and review criteria, or delegate to a fresh-context reviewer. reasoning that produced the change; prefer that over pure self-audit for non-trivial diffs - For a high-stakes diff, prefer a cross-vendor advisor **when one is installed and set up**, for example the OpenAI Codex plugin, when its documented surface can take this artifact, invoked per its own docs, with the fresh-context same-vendor subagent as the stated fallback, never a route to a command that may not resolve - (per `docs/PLUGIN-PHILOSOPHY.md` "Fresh-eyes checkpoints" in the marketplace repository) + (per `docs/plugin-philosophy.md` "Fresh-eyes checkpoints" in the marketplace repository) ## 7. Verify outcome diff --git a/plugins/skill-quality/.claude-plugin/plugin.json b/plugins/skill-quality/.claude-plugin/plugin.json index 7be1c13426..c8c5c37752 100644 --- a/plugins/skill-quality/.claude-plugin/plugin.json +++ b/plugins/skill-quality/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "skill-quality", - "version": "0.22.3", + "version": "0.22.4", "description": "Skill-authoring QA tooling: a static contract checker that runs twenty-seven deterministic checks over a Claude Code skill (frontmatter, explicit invocation mode, description/verb-contract polarity, per-skill listing-entry cap, trigger-keyword preservation, line caps, broken internal refs, markdownlint, gotchas surface, evals presence, precompute opportunity, completion-criteria signal, injection shell-declaration, fresh-eyes declaration conformance), a shared skill-listing budget reporter across a set of skills, and a bundled evals.json schema plus a deterministic eval-quality lint (duplicate case identities, missing fixtures, empty or vague grading criteria, set-coverage warnings). Runs against any repo's skills directory via the convention-resolution ladder, with no baked layout.", "author": { "name": "Melodic Software", diff --git a/plugins/skill-quality/CHANGELOG.md b/plugins/skill-quality/CHANGELOG.md index 774e4123c2..6cb22c4cdb 100644 --- a/plugins/skill-quality/CHANGELOG.md +++ b/plugins/skill-quality/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `skill-quality` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.22.4] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.22.3] ### Added diff --git a/plugins/skill-quality/reference/evals.schema.json b/plugins/skill-quality/reference/evals.schema.json index f583232a7f..4df992a6ca 100644 --- a/plugins/skill-quality/reference/evals.schema.json +++ b/plugins/skill-quality/reference/evals.schema.json @@ -2,7 +2,7 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://melodic-software.github.io/claude-code-plugins/skill-quality/evals.schema.json", "title": "Skill evaluations", - "description": "Schema for a skill's evals/evals.json. Supports both rich and minimal forms, but every case must carry a grading criterion: at least one of `expected_output`, `expectations`, or `assertions` (a case that cannot be graded is not an eval — per the eval anatomy in Anthropic's evaluation guidance, indexed in docs/OFFICIAL-DOCS.md). Rich form adds per-case `name` (kebab-case) and `expectations` (or the upstream-named `assertions`; skill-creator upstream uses `assertions`, rich-form skills here use `expectations`).", + "description": "Schema for a skill's evals/evals.json. Supports both rich and minimal forms, but every case must carry a grading criterion: at least one of `expected_output`, `expectations`, or `assertions` (a case that cannot be graded is not an eval — per the eval anatomy in Anthropic's evaluation guidance, indexed in docs/official-docs.md). Rich form adds per-case `name` (kebab-case) and `expectations` (or the upstream-named `assertions`; skill-creator upstream uses `assertions`, rich-form skills here use `expectations`).", "type": "object", "additionalProperties": false, "required": ["skill_name", "evals"], diff --git a/plugins/skill-quality/scripts/check-skill.sh b/plugins/skill-quality/scripts/check-skill.sh index a30d196625..4d0ac2aa90 100755 --- a/plugins/skill-quality/scripts/check-skill.sh +++ b/plugins/skill-quality/scripts/check-skill.sh @@ -1682,7 +1682,7 @@ fi # # The exception class a `true` claims is NOT machine-checkable: a static scan # cannot tell class (i) manual-timing from an unjustified hide. Only class (ii) -# is deterministic — the PLUGIN-PHILOSOPHY setup contract names `setup` skills — +# is deterministic — the plugin-philosophy setup contract names `setup` skills — # so every other `true` emits a note for hand-verification against the rubric # rather than a warning nothing can clear. @@ -1721,7 +1721,7 @@ else fi # --- Check 25: description/verb-contract polarity (WARN; advisory) ---------- -# PLUGIN-PHILOSOPHY Naming fixes verb meanings: audit/scan are read-only +# plugin-philosophy Naming fixes verb meanings: audit/scan are read-only # findings reports (mutation only behind an explicit override such as --fix); # clean/tidy/fix mutate the target. This check flags a description that tells # a different story than that verb contract, or than the body — the two @@ -1815,10 +1815,10 @@ VC_ALL_LC="$(printf '%s %s' "$CUR_DESC" "$CUR_WTU" | tr '[:upper:]' '[:lower:]') VC_HIT="" if [[ "$VC_LEAF" == "audit" || "$VC_LEAF" == "scan" ]] && vc_lead_mutate "$VC_LEAD_LC" && ! vc_has_override "$VC_ALL_LC"; then - VC_HIT="leaf verb '$VC_LEAF' is a read-only findings report (PLUGIN-PHILOSOPHY Naming) but the description lead advertises mutation without an explicit override" + VC_HIT="leaf verb '$VC_LEAF' is a read-only findings report (plugin-philosophy Naming) but the description lead advertises mutation without an explicit override" elif [[ "$VC_LEAF" == "clean" || "$VC_LEAF" == "tidy" || "$VC_LEAF" == "fix" ]] && vc_lead_readonly "$VC_LEAD_LC"; then - VC_HIT="leaf verb '$VC_LEAF' mutates the target (PLUGIN-PHILOSOPHY Naming) but the description lead claims the skill is read-only/report-only" + VC_HIT="leaf verb '$VC_LEAF' mutates the target (plugin-philosophy Naming) but the description lead claims the skill is read-only/report-only" elif vc_lead_readonly "$VC_LEAD_LC" && vc_body_bare_mutate "$VC_BODY"; then VC_HIT="description lead claims read-only but the body mutates on bare invocation (or hides an unadvertised mutation path)" elif vc_lead_mutate "$VC_LEAD_LC" && ! vc_has_override "$VC_ALL_LC" && diff --git a/plugins/skill-quality/skills/check/SKILL.md b/plugins/skill-quality/skills/check/SKILL.md index 920727897a..d51121590e 100644 --- a/plugins/skill-quality/skills/check/SKILL.md +++ b/plugins/skill-quality/skills/check/SKILL.md @@ -253,7 +253,7 @@ tool. This gate does not automate that reachability check; author and review aga model-invoked default and the only three exception classes a `true` may claim, is [`docs/conventions/invocation-mode/README.md`](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/conventions/invocation-mode/README.md). Class attribution is NOT machine-checkable: only a `setup` skill's `true` is deterministic (class - (ii), the PLUGIN-PHILOSOPHY setup contract), so every other `true` emits a note to hand-verify + (ii), the plugin-philosophy setup contract), so every other `true` emits a note to hand-verify rather than a warning no scan could clear. - Check 25 (description/verb-contract polarity) is an advisory heuristic, never a FAIL. It flags a listing-surface mismatch between the description lead (before `Use when:`) and the diff --git a/plugins/skill-quality/skills/check/evals/evals.json b/plugins/skill-quality/skills/check/evals/evals.json index ee99059017..bb49718f7e 100644 --- a/plugins/skill-quality/skills/check/evals/evals.json +++ b/plugins/skill-quality/skills/check/evals/evals.json @@ -101,7 +101,7 @@ { "id": 9, "name": "verb-contract-mismatch-warn-is-advisory", - "prompt": "The skill-quality check on skill audit returned: `WARN: description/verb-contract mismatch: leaf verb 'audit' is a read-only findings report (PLUGIN-PHILOSOPHY Naming) but the description lead advertises mutation without an explicit override`. What does it mean and what should I do?", + "prompt": "The skill-quality check on skill audit returned: `WARN: description/verb-contract mismatch: leaf verb 'audit' is a read-only findings report (plugin-philosophy Naming) but the description lead advertises mutation without an explicit override`. What does it mean and what should I do?", "expected_output": "It is check 25, an advisory WARN, not a FAIL — the skill did not fail. It flags a factual-consistency defect in the listing surface: the description lead (or the leaf verb) tells a read-only story while the skill advertises or performs mutation, or the reverse. Hand-verify the lead against the Naming verb contract and the body. --fix in the description is the compliant override shape (claude-config:audit [--fix]). Do not treat the WARN as a mandate to add a --fix path or rename the skill — both are out of scope for this check. It does not block shipping.", "files": [], "expectations": [ diff --git a/plugins/skill-quality/skills/setup/SKILL.md b/plugins/skill-quality/skills/setup/SKILL.md index b80da8b291..b8b1206a7f 100644 --- a/plugins/skill-quality/skills/setup/SKILL.md +++ b/plugins/skill-quality/skills/setup/SKILL.md @@ -7,7 +7,7 @@ disable-model-invocation: true ## Purpose -Check-only setup under the Check-only carve-out (`docs/PLUGIN-PHILOSOPHY.md` "Setup is explicit +Check-only setup under the Check-only carve-out (`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in the marketplace repository): this plugin's configuration surface contains no writable artifact, so `check` resolves and verifies the skills root and prints the reconfiguration guidance below, and no `apply` is offered because there is nothing it could conformingly write. diff --git a/plugins/songwriting/.claude-plugin/plugin.json b/plugins/songwriting/.claude-plugin/plugin.json index 135c41dfc3..38081fa8fd 100644 --- a/plugins/songwriting/.claude-plugin/plugin.json +++ b/plugins/songwriting/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "songwriting", - "version": "1.4.25", + "version": "1.4.26", "description": "Songwriting craft companion: nine concern-scoped lyric-craft skills (workflow router, rhyme, object-writing, metaphor, meter-prosody, song-form, co-write, diagnose, practice) applying Pat Pattison's methods, with an object-writing agent that performs the sensory exercise itself and per-skill emission boundaries that route generation to the skill that owns it, plus Suno v5.5 prompt engineering (style prompts, tagged lyrics, genre templates, troubleshooting).", "author": { "name": "Melodic Software", diff --git a/plugins/songwriting/CHANGELOG.md b/plugins/songwriting/CHANGELOG.md index 974c44b606..bd2e04efde 100644 --- a/plugins/songwriting/CHANGELOG.md +++ b/plugins/songwriting/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `songwriting` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [1.4.26] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [1.4.25] ### Changed diff --git a/plugins/songwriting/skills/setup/SKILL.md b/plugins/songwriting/skills/setup/SKILL.md index 516d624e78..85a1b2a754 100644 --- a/plugins/songwriting/skills/setup/SKILL.md +++ b/plugins/songwriting/skills/setup/SKILL.md @@ -7,7 +7,7 @@ disable-model-invocation: true ## Purpose -Thin check-centric setup per the uniform setup contract (`docs/PLUGIN-PHILOSOPHY.md` +Thin check-centric setup per the uniform setup contract (`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in the marketplace repository): `check` inventories the consuming repo's tracked prompt-template overrides and reports the effective artifact layout; `apply` scaffolds an override from a bundled default (or removes a byte-identical one). The override seam and the output diff --git a/plugins/source-control/.claude-plugin/plugin.json b/plugins/source-control/.claude-plugin/plugin.json index 026793bab2..7cbaba9edb 100644 --- a/plugins/source-control/.claude-plugin/plugin.json +++ b/plugins/source-control/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "source-control", - "version": "0.55.76", + "version": "0.55.77", "description": "Git and GitHub delivery workflow: /commit (Conventional Commits + Co-authored-by trailer via safe heredoc mechanics), /pull-request (prep, create, CI monitoring, review-comment triage, merge, CI-log fetch), /babysit-prs (self-pacing fleet loop, safe by default; opt-in worker/autopilot tiers add gate-checked merge and thread resolution behind a deterministic Python engine), /babysit-loop (the loop-lane merge lane: a standing or drain loop that invokes babysit-prs per cycle, configured through repo-scoped babysit_loop_* keys on the layered source-control.md seam, with merge authority human-only until the target repo's tracked config adopts the lane, a gate-proven C2-mechanical baseline once adopted, and standing merge-rung raises binding from the team-tracked layer only, with one named exception, where an invocation line explicitly typing both the autopilot tier keyword and the dedicated raise argument --merge c3-this-run widens that single invocation's merge authority up to C3 behind a fresh independent frontier-tier resolver, while C4-structural and C5-untrusted-provenance stay unconditionally human-merge), /worktree (create, status, cleanup, audit for parallel-session isolation), /setup (check the effective commit-subject / PR-title convention merged across its config layers and the babysit-prs config, or apply, which interviews the repo and writes the convention config to a chosen layer), and /resolve-conflicts (intent-first merge/rebase conflict resolution with a semantic-conflict sweep, never --abort). The commit-subject / PR-title convention is configurable via a source-control.md config written by a re-runnable setup skill, layered across a ~/.claude user-global file, the tracked team file, and a gitignored .claude/source-control.local.md personal overlay merged per key; Conventional Commits is the default when no convention is declared.", "author": { "name": "Melodic Software", diff --git a/plugins/source-control/CHANGELOG.md b/plugins/source-control/CHANGELOG.md index 4311a48558..ba8d85e414 100644 --- a/plugins/source-control/CHANGELOG.md +++ b/plugins/source-control/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `source-control` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.55.77] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.55.76] ### Changed diff --git a/plugins/source-control/reference/config-resolution.md b/plugins/source-control/reference/config-resolution.md index 3bd437fe01..2b1c4e81e3 100644 --- a/plugins/source-control/reference/config-resolution.md +++ b/plugins/source-control/reference/config-resolution.md @@ -17,7 +17,7 @@ loop-lane keys, read by `/source-control:babysit-loop`. Every consumer reads thi bakes its own layering rules, and the three layers and per-key merge below govern both families. Implements the tracked-rich-config extensibility contract in -[`docs/MIGRATION-PLAYBOOK.md`](https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/docs/MIGRATION-PLAYBOOK.md). +[`docs/migration-playbook.md`](https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/docs/migration-playbook.md). ## The config surface diff --git a/plugins/source-control/skills/setup/SKILL.md b/plugins/source-control/skills/setup/SKILL.md index 90c21cf381..65319af762 100644 --- a/plugins/source-control/skills/setup/SKILL.md +++ b/plugins/source-control/skills/setup/SKILL.md @@ -8,7 +8,7 @@ disable-model-invocation: true ## Purpose Inspect and configure the source-control plugin per the uniform setup contract -(`docs/PLUGIN-PHILOSOPHY.md` "Setup is explicit and repeatable" in the marketplace repository): +(`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in the marketplace repository): `check` reports the effective configuration, `apply` writes it. Two configuration surfaces: 1. The commit-subject / PR-title convention config, layered across a user-global file, the tracked diff --git a/plugins/toolchain/.claude-plugin/plugin.json b/plugins/toolchain/.claude-plugin/plugin.json index d4bbbd37ce..0388d25891 100644 --- a/plugins/toolchain/.claude-plugin/plugin.json +++ b/plugins/toolchain/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "toolchain", - "version": "0.13.15", + "version": "0.13.16", "description": "Repo-agnostic polyglot verification toolchain: build + test + lint for changed files across .NET, Python, TypeScript, Bash, PowerShell, Markdown, Go, YAML, and cross-cutting surfaces (`/toolchain:check`, `/toolchain:lint` with format-only `--fix` and gated `--code-fix`), plus a re-runnable `/toolchain:setup` with check (report the configured ecosystems and their command surface) and apply (interview, infer, and write the tracked per-ecosystem command config those skills resolve first).", "author": { "name": "Melodic Software", diff --git a/plugins/toolchain/CHANGELOG.md b/plugins/toolchain/CHANGELOG.md index d0eee8d9a2..9427187610 100644 --- a/plugins/toolchain/CHANGELOG.md +++ b/plugins/toolchain/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `toolchain` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.13.16] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.13.15] ### Changed diff --git a/plugins/toolchain/skills/setup/SKILL.md b/plugins/toolchain/skills/setup/SKILL.md index 6a51e2e5f6..d5a3416714 100644 --- a/plugins/toolchain/skills/setup/SKILL.md +++ b/plugins/toolchain/skills/setup/SKILL.md @@ -8,7 +8,7 @@ disable-model-invocation: true ## Purpose Inspect and configure the consuming repo's tracked ecosystem command surface per the uniform setup -contract (`docs/PLUGIN-PHILOSOPHY.md` "Setup is explicit and repeatable" in the marketplace +contract (`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in the marketplace repository): `check` reports what is configured, `apply` writes it. The tracked files at `.claude/ecosystems/.yaml` let `/toolchain:check` and `/toolchain:lint` resolve commands deterministically from rung 1 of the ladder diff --git a/plugins/typos-format/.claude-plugin/plugin.json b/plugins/typos-format/.claude-plugin/plugin.json index 0bcb669689..0c09a297a1 100644 --- a/plugins/typos-format/.claude-plugin/plugin.json +++ b/plugins/typos-format/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "typos-format", - "version": "0.6.51", + "version": "0.6.52", "description": "Spell-check on edit via typos-cli, unconditionally. Report-only by default, honoring the consuming repo's own typos configuration when one is present.", "author": { "name": "Melodic Software", diff --git a/plugins/typos-format/CHANGELOG.md b/plugins/typos-format/CHANGELOG.md index f2c2eaa41a..f3c79778e3 100644 --- a/plugins/typos-format/CHANGELOG.md +++ b/plugins/typos-format/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `typos-format` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.6.52] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.6.51] ### Changed diff --git a/plugins/typos-format/skills/setup/SKILL.md b/plugins/typos-format/skills/setup/SKILL.md index 3873a186c2..a0bc681183 100644 --- a/plugins/typos-format/skills/setup/SKILL.md +++ b/plugins/typos-format/skills/setup/SKILL.md @@ -7,7 +7,7 @@ disable-model-invocation: true ## Purpose -Thin check-centric setup per the uniform setup contract (`docs/PLUGIN-PHILOSOPHY.md` +Thin check-centric setup per the uniform setup contract (`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in the marketplace repository): `check` inspects and reports, `apply` resolves. This plugin owns no consumer-project configuration. Rules come from the repository's own typos config, and the only tunables are the native `userConfig` diff --git a/plugins/verification/.claude-plugin/plugin.json b/plugins/verification/.claude-plugin/plugin.json index cd038b80bd..43e0bb592f 100644 --- a/plugins/verification/.claude-plugin/plugin.json +++ b/plugins/verification/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "verification", - "version": "0.6.7", + "version": "0.6.8", "description": "Outcome-verification stage: prove a change achieved its intended outcome (`/verification:confirm`: a mechanical build/test/lint prerequisite gate, then intent-match + evidence + verdict with the criterion auto-detected by change type), and verify measurable-improvement claims against a planning-time baseline (`/verification:measure`), never fabricating numbers.", "author": { "name": "Melodic Software", diff --git a/plugins/verification/CHANGELOG.md b/plugins/verification/CHANGELOG.md index 0bfd116ccd..be2a4479be 100644 --- a/plugins/verification/CHANGELOG.md +++ b/plugins/verification/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `verification` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.6.8] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.6.7] ### Changed diff --git a/plugins/verification/skills/confirm/SKILL.md b/plugins/verification/skills/confirm/SKILL.md index edc2c7d627..daedb8ac1e 100644 --- a/plugins/verification/skills/confirm/SKILL.md +++ b/plugins/verification/skills/confirm/SKILL.md @@ -106,7 +106,7 @@ Read the criterion context file for the dispatched mode, then run the flow below 5. **Evidence collection**. Stage-1 results, E2E results, test names + assertions proving the claimed behavior. For UI changes: the UI evidence artifacts per [context/outcome.md](context/outcome.md) (pre/action/post snapshot, console, network, behavior assertion. "screenshot looks fine" is NOT an assertion). When the plan states a measurable goal: the `/verification:measure` comparison table. 6. **Report + verdict**. Emit the outcome report (intent-match table, mechanical results, E2E + UI-evidence tables when triggered, evidence table, measurements when applicable) and a `CONFIRMED` / `NEEDS WORK` verdict. Report template and verdict criteria in [context/outcome.md](context/outcome.md). -**Independence of the verdict.** This skill usually runs in the context that produced the changes, and that context carries the assumptions that produced any defect, converging on approval rather than detection. Stage 1's mechanical pass/fail is objective and needs no escalation, but for the Stage 2 outcome verdict on anything beyond a mechanical, behavior-preserving change, render `CONFIRMED` / `NEEDS WORK` from an agent that did NOT produce the artifact: dispatch a fresh-context verifier with the acceptance criteria and the diff, withholding your rationale so it audits the artifact and not your story. Where the outcome is high-stakes and correlated blind spots are the risk, prefer a cross-vendor advisor **when one is installed and set up**, e.g. the OpenAI Codex plugin, when its documented surface can take this artifact, invoked per its own docs, with the fresh-context same-vendor verifier above as the stated fallback, never a route to a command that may not resolve (per `docs/PLUGIN-PHILOSOPHY.md` "Fresh-eyes checkpoints" in the marketplace repository). +**Independence of the verdict.** This skill usually runs in the context that produced the changes, and that context carries the assumptions that produced any defect, converging on approval rather than detection. Stage 1's mechanical pass/fail is objective and needs no escalation, but for the Stage 2 outcome verdict on anything beyond a mechanical, behavior-preserving change, render `CONFIRMED` / `NEEDS WORK` from an agent that did NOT produce the artifact: dispatch a fresh-context verifier with the acceptance criteria and the diff, withholding your rationale so it audits the artifact and not your story. Where the outcome is high-stakes and correlated blind spots are the risk, prefer a cross-vendor advisor **when one is installed and set up**, e.g. the OpenAI Codex plugin, when its documented surface can take this artifact, invoked per its own docs, with the fresh-context same-vendor verifier above as the stated fallback, never a route to a command that may not resolve (per `docs/plugin-philosophy.md` "Fresh-eyes checkpoints" in the marketplace repository). When `/testing:run-e2e` ran, persist an assertion-only evidence manifest (what was asserted, at which commit. Record `verified_at_sha`) to the topic's contract slice at `//verification/` (default `docs/topics/`; the memory slice under `contract_tier: local`), resolved per the topic-docs binding ([`${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md`](${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md)). Under `contract_tier: branch` the manifest is committed on the task branch; under `local` it stays in the self-ignored memory slice (the PR-description paste is its publication surface). Either way it meets the contract's redaction bar: distilled assertions only. No raw command captures, no machine-local paths, no usernames or credentials; cite a `## Reproduction` block instead. Raw captures stay in the memory tier at `//scratch/` (default `.work/`), never committed. diff --git a/plugins/visualization/.claude-plugin/plugin.json b/plugins/visualization/.claude-plugin/plugin.json index 345008b105..565a03e174 100644 --- a/plugins/visualization/.claude-plugin/plugin.json +++ b/plugins/visualization/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "visualization", - "version": "0.6.1", + "version": "0.6.2", "description": "On-demand visualization router: infers what in the current conversation should be shown visually, then decides the best FORM (a mermaid diagram, a markdown table, a hand-authored SVG/CSS chart, ASCII/Unicode art, a rich rendered page, or, where the bundled design skill is available, a hand-editable design canvas) and the best MEDIUM (inline terminal, a local HTML file, or a published Artifact) via a decision matrix over content shape, complexity, and a configurable medium preference. Renders good defaults and asks only when the target is genuinely ambiguous and no form was named. A form-and-medium decision layer in front of the craft capabilities. It routes chart craft and artifact-design fundamentals to those capabilities when installed and never restates them.", "author": { "name": "Melodic Software", diff --git a/plugins/visualization/CHANGELOG.md b/plugins/visualization/CHANGELOG.md index fb427ecf17..9e4c2fcc63 100644 --- a/plugins/visualization/CHANGELOG.md +++ b/plugins/visualization/CHANGELOG.md @@ -3,6 +3,15 @@ All notable changes to the `visualization` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.6.2] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. +- **Released-entry correction, declared here per the changelog-parity discipline:** the + `plugin-philosophy` link inside the 0.3.2 entry now points at `docs/plugin-philosophy.md`; the + old uppercase path no longer exists. + ## [0.6.1] ### Changed @@ -233,7 +242,7 @@ All notable changes to the `visualization` plugin are documented here. Format fo ### Unchanged, deliberately - **No `setup` skill.** One was written and then dropped: `medium` is **trivial** by - [PLUGINPHILOSOPHY](../../docs/PLUGIN-PHILOSOPHY.md)'s own test, a self-contained scalar with + [PLUGINPHILOSOPHY](../../docs/plugin-philosophy.md)'s own test, a self-contained scalar with a default preserving zero-config behavior, whose out-of-set values are documented as falling back to that default. This plugin also has no external prerequisite and no consumer-project configuration surface. None of the three criteria that require a `setup` skill holds, so diff --git a/plugins/work-items/.claude-plugin/plugin.json b/plugins/work-items/.claude-plugin/plugin.json index a28a205d20..eeddcc7d42 100644 --- a/plugins/work-items/.claude-plugin/plugin.json +++ b/plugins/work-items/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "work-items", - "version": "0.40.7", + "version": "0.40.8", "description": "Manages development work items through a provider-neutral tracker seam that ships with the plugin (bundled dispatcher plus github, local-markdown, jira, gitea, and linear adapters; seam plugin-dir canonical, adapters consumer-local-first): dashboard, taxonomy-labeled creation, a race-safe assignee-plus-lease claim protocol, recurring-schedule checks, TODO scanning, stale-lease auditing, plan decomposition into vertical-slice items, a macro-journey router over spec containers (rollup, per-container execution shape, next-step routing), raw-intake triage (issues and unsolicited PRs through raw, verified, briefed, autonomous-eligible states), plus the two work-items loop lanes of the loop-lane convention: a self-paced autonomous work-loop drain (work-class admission gate, adaptive item cap, PR-only) and an attended attend-queue escalation lane. The re-runnable setup skill binds the provider (.work-item-tracker.json), seeds the recurring-schedule seam (.github/recurring-schedule.json), and remaps canonical role labels.", "author": { "name": "Melodic Software", diff --git a/plugins/work-items/CHANGELOG.md b/plugins/work-items/CHANGELOG.md index 99abf44678..171975f4b9 100644 --- a/plugins/work-items/CHANGELOG.md +++ b/plugins/work-items/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `work-items` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.40.8] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.40.7] ### Changed diff --git a/plugins/work-items/reference/execution-shape.md b/plugins/work-items/reference/execution-shape.md index 9eb4215655..cf742ab938 100644 --- a/plugins/work-items/reference/execution-shape.md +++ b/plugins/work-items/reference/execution-shape.md @@ -111,7 +111,7 @@ Sequential checkpoints on one shared branch; the journey ships as one PR at the ## Vocabulary Canonical journey terms (resolved 2026-08-17). The marketplace-wide glossary write is **no longer -deferred**. `docs/GLOSSARY.md` landed 2026-08-20 (#3062) and declares itself repo-wide. Of the +deferred**. `docs/glossary.md` landed 2026-08-20 (#3062) and declares itself repo-wide. Of the three terms below, **`phase boundary` has been promoted there and this file no longer defines it**; `work item` and `checkpoint` stay reference-local, because both are specific to this plugin's execution shapes rather than repo-wide vocabulary. @@ -128,7 +128,7 @@ An item closed within a shared-branch (`integration branch → single PR`) flow: recorded on the branch and in the tracker, safe to clear context and resume, from any machine. An item is always a graph node; it is a checkpoint only in a shared-branch flow. -**Phase boundary** is defined repo-wide in [`docs/GLOSSARY.md`](../../../docs/GLOSSARY.md), not here. +**Phase boundary** is defined repo-wide in [`docs/glossary.md`](../../../docs/glossary.md), not here. This file used to carry its own definition ("the session-level decision moment between phases of work"), which diverged from the glossary's once that landed. Two definitions of one term, one of diff --git a/plugins/work-items/reference/pipeline-shape.md b/plugins/work-items/reference/pipeline-shape.md index dd57783188..2053423283 100644 --- a/plugins/work-items/reference/pipeline-shape.md +++ b/plugins/work-items/reference/pipeline-shape.md @@ -48,7 +48,7 @@ that stage (the Step 5 anchor) rather than dead-end. For the Verify lane specifically, where the result is high-stakes and correlated blind spots are the risk, prefer a cross-vendor advisor **when one is installed and set up**, e.g. the OpenAI Codex plugin, when its documented surface can take this artifact, invoked per its own docs. The fresh-context same-vendor verifier is the stated fallback, never a route to a command that may not resolve -(per `docs/PLUGIN-PHILOSOPHY.md` "Fresh-eyes checkpoints" in the marketplace repository). +(per `docs/plugin-philosophy.md` "Fresh-eyes checkpoints" in the marketplace repository). The **discipline slot** (`discipline:*`) is reserved: the discipline set is a periodic anchor across lane execution rather than a human-invoked extra. Its placement in the sequence is left for a later `#513` diff --git a/plugins/work-items/skills/setup/SKILL.md b/plugins/work-items/skills/setup/SKILL.md index ffe94cc27c..87397fab89 100644 --- a/plugins/work-items/skills/setup/SKILL.md +++ b/plugins/work-items/skills/setup/SKILL.md @@ -20,7 +20,7 @@ empty skeleton and stops there, because that bind is usually reached as a detour reporting "no binding", the operator came to do something else, and should not be walked through a per-item interview to get there. -Check-centric per the uniform setup contract (`docs/PLUGIN-PHILOSOPHY.md` +Check-centric per the uniform setup contract (`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in the marketplace repository): `check` inspects read-only and reports a PASS/FAIL/INFO table; `apply` binds the provider, writes or reshapes the schedule, and offers the role remap, then re-runs `check`. No argument or `check` runs the check; `apply` runs the diff --git a/plugins/x/.claude-plugin/plugin.json b/plugins/x/.claude-plugin/plugin.json index 3ff89b3fdf..06069144fe 100644 --- a/plugins/x/.claude-plugin/plugin.json +++ b/plugins/x/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "x", - "version": "0.2.4", + "version": "0.2.5", "description": "Read X (formerly Twitter) posts, note tweets, and X Articles as Markdown without an X API key, via a documented fallback ladder over third-party converters: xtomd.com for single posts and articles, Thread Reader App for unrolled reply chains. A pasted X link becomes readable content instead of a login wall.", "author": { "name": "Melodic Software", diff --git a/plugins/x/CHANGELOG.md b/plugins/x/CHANGELOG.md index 3f1f4f66ce..a212ff2728 100644 --- a/plugins/x/CHANGELOG.md +++ b/plugins/x/CHANGELOG.md @@ -5,6 +5,12 @@ All notable changes to the `x` plugin. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [0.2.5] + +### Changed + +- Cite the marketplace `docs/` doctrine files by their lower-kebab names (`docs/plugin-philosophy.md`, `docs/migration-playbook.md`, and siblings); the files were renamed and the old uppercase paths no longer resolve. + ## [0.2.4] ### Changed diff --git a/plugins/x/README.md b/plugins/x/README.md index ba2d274b20..40093168e8 100644 --- a/plugins/x/README.md +++ b/plugins/x/README.md @@ -116,7 +116,7 @@ Neither vendor identifies its operating entity or publishes a retention policy, submitted URL is logged indefinitely. A consumer who does not accept that egress disables the plugin. The recorded trust decision, including the retracted claims from the first review draft, lives in the marketplace's -[plugin-acceptance security review](../../docs/MIGRATION-PLAYBOOK.md). +[plugin-acceptance security review](../../docs/migration-playbook.md). ## Known limits diff --git a/prompts/cloud-bootstrap-rollout.md b/prompts/cloud-bootstrap-rollout.md index dffdf6b082..e7edc70734 100644 --- a/prompts/cloud-bootstrap-rollout.md +++ b/prompts/cloud-bootstrap-rollout.md @@ -5,9 +5,9 @@ setup-script stub pasted once per claude.ai account, shared provisioning in the `melodic-software/standards` repo's [`cloud-environment` component](https://github.com/melodic-software/standards/blob/main/components/cloud-environment/setup.sh), and a mechanical per-repo migration prompt. Mechanics and evidence live in -[docs/CLOUD-SESSIONS.md](../docs/CLOUD-SESSIONS.md) §"Plugins in sessions on this repo"; the +[docs/cloud-sessions.md](../docs/cloud-sessions.md) §"Plugins in sessions on this repo"; the fleet inventory and the canonical stub's home live in -[docs/CLOUD-FLEET-SETUP.md](../docs/CLOUD-FLEET-SETUP.md). +[docs/cloud-fleet-setup.md](../docs/cloud-fleet-setup.md). ## Why this layout (verified 2026-08-15) @@ -35,7 +35,7 @@ restated in the Part 1 and Part 3 paste blocks below, if any of these happen: Cl re-reading the plugin/command/skill registry after a SessionStart hook runs (closing the same-session gap this rollout exists to route around, tracked as #2733); the `cloud-environments` docs' Setup scripts vs SessionStart hooks or Environment caching sections change; or -`docs/CLOUD-SESSIONS.md`'s "Plugins in sessions on this repo" section, which this file cites as +`docs/cloud-sessions.md`'s "Plugins in sessions on this repo" section, which this file cites as ground truth, changes its verified date or verdict. ## Part 1: standards repo, once (paste into a session on `melodic-software/standards`) @@ -46,8 +46,8 @@ Update the existing Claude Code cloud-environment component in this repo bootstrap-rename rollout. Context (verified 2026-08-15 in melodic-software/claude-code-plugins, in its -docs/CLOUD-SESSIONS.md §"Plugins in sessions on this repo" and -docs/CLOUD-FLEET-SETUP.md): Claude Code builds its plugin/command/skill +docs/cloud-sessions.md §"Plugins in sessions on this repo" and +docs/cloud-fleet-setup.md): Claude Code builds its plugin/command/skill registry at process start and never re-reads it, so plugin installs must land before the session process launches, meaning in this component at environment cache build, to be loaded at turn one. Fleet repos are renaming their @@ -94,7 +94,7 @@ edit **Default** (one environment per account; see the rationale at the end): 2. **Environment variables**: none (values are readable by every session; there is no secrets store). 3. **Setup script**: paste the canonical stub below (same as - [CLOUD-FLEET-SETUP.md](../docs/CLOUD-FLEET-SETUP.md) step 1), save. Saving rebuilds the + [cloud-fleet-setup.md](../docs/cloud-fleet-setup.md) step 1), save. Saving rebuilds the environment cache, which is also how a later standards component change is picked up early: any trivial edit-and-save forces a rebuild. @@ -114,7 +114,7 @@ edit **Default** (one environment per account; see the rationale at the end): `~/.claude` did not reach the session, a platform limitation to report upstream (resume is the standing workaround). If SessionStart alone just installed plugins and the first slash returns `Unknown command`, that is the harness residual documented in - [CLOUD-SESSIONS.md](../docs/CLOUD-SESSIONS.md) (#2733): resume, or read the skill's + [cloud-sessions.md](../docs/cloud-sessions.md) (#2733): resume, or read the skill's `SKILL.md` from the working tree. Do not expect a plugin-side fix. ## Part 3: every repo (the copy-paste migration prompt) @@ -124,7 +124,7 @@ Migrate this repository's Claude Code cloud bootstrap from the SessionStart-hook layout to the split cloud-bootstrap layout. Context (verified 2026-08-15 in melodic-software/claude-code-plugins, see its -docs/CLOUD-SESSIONS.md §"Plugins in sessions on this repo"): Claude Code builds +docs/cloud-sessions.md §"Plugins in sessions on this repo"): Claude Code builds its plugin/command/skill registry at process start and never re-reads it, so anything a SessionStart hook installs is invisible to the session that ran the hook. Our account environments fetch the standards cloud-environment component @@ -181,4 +181,4 @@ environment; add a second environment later only when a class of work needs isol handling sensitive material that has to run narrower than All, or an SDK heavy enough that its cache churn should be contained). This supersedes the "add a *Melodic* environment so Default stays pristine" option in -[docs/CLOUD-FLEET-SETUP.md](../docs/CLOUD-FLEET-SETUP.md) for the paste-once fleet play. +[docs/cloud-fleet-setup.md](../docs/cloud-fleet-setup.md) for the paste-once fleet play. diff --git a/scripts/cheatsheet-config.mjs b/scripts/cheatsheet-config.mjs index 9c7a5ae639..60321ea69f 100644 --- a/scripts/cheatsheet-config.mjs +++ b/scripts/cheatsheet-config.mjs @@ -1,5 +1,5 @@ // Hand-curated grouping layer for the generated skill cheat sheet -// (docs/SKILL-CHEAT-SHEET.md). Owns exactly three things: the stage/group +// (docs/skill-cheat-sheet.md). Owns exactly three things: the stage/group // vocabulary and order, the exclusion entries, and the shared summary guard. // Per-skill detail (stage, summary, cadence) lives in each SKILL.md's // `metadata:` frontmatter — never here. diff --git a/scripts/check-docs-naming.sh b/scripts/check-docs-naming.sh new file mode 100755 index 0000000000..94b7ae1ef4 --- /dev/null +++ b/scripts/check-docs-naming.sh @@ -0,0 +1,106 @@ +#!/usr/bin/env bash +# Check that every tracked file under docs/ carries a lower-kebab-case basename. +# +# scripts/check-docs-naming.sh discover: list every offender +# scripts/check-docs-naming.sh --check same, explicit form matching the +# sibling gates (exit 1 on any offender) +# +# The rule: a basename matches `^[a-z0-9]+([.-][a-z0-9]+)*\.[a-z0-9]+$`, so +# `plugin-philosophy.md`, `v1.2.schema.json`, and `0001-first.md` pass while +# `UPPER-KEBAB.md`, `snake_case.md`, `Mixed.md`, `foo..md`, and `foo.md.` do +# not (every dot- or hyphen-separated segment is non-empty, and the name ends +# in a non-empty extension). Exempt: +# +# - `README.md`, `CHANGELOG.md`, `INDEX.md` anywhere under docs/, the +# conventional uppercase names tooling and forges look for by exact spelling +# (INDEX.md is the topic-docs convention's reserved index name) +# - everything under `docs/topics/`, the branch-only contract slice whose +# file names (`PLAN.md`, `BRIEF.md`, ...) are owned by the topic-docs +# convention and pruned before merge +# - code files by extension (`py sh mjs js ps1`), whose casing is the +# language's convention, not this one +# +# Independently of the regex, no two tracked paths under docs/ may differ only +# by case: a case-insensitive checkout (Windows, macOS) writes the second over +# the first, and two of this repository's CI jobs check out the tree on +# windows-2025. +# +# WHY. docs/ carried a mix of UPPER-KEBAB, lower-kebab, and mixed-case names +# for years, and every reference to a doc had to remember which spelling that +# one file used. One rule, enforced here, means a new file's name needs no +# lookup and a rename never happens twice. The three uppercase names stay +# because they are conventions readers already know, and code files stay +# because their language owns their casing. The ADR that records the decision +# cites this script as the gate: a path-scoped rule, where one exists, loads +# when a covered file is read, never when one is created, so a rule alone +# cannot catch a new file. +# +# Output follows the check-script contract (README.md, "The check-script +# contract"): one `path: reason` finding per offender on stderr, the clean-run +# statement on stdout. Exit: 0 clean, 1 any offender, 2 environment or usage +# (git missing, repo root unresolved, bad argument). +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" || exit 2 +cd "$SCRIPT_DIR/.." || exit 2 + +case "${1:-}" in +'' | --check) ;; +*) + printf 'usage: %s [--check]\n' "${0##*/}" >&2 + exit 2 + ;; +esac + +if ! command -v git >/dev/null 2>&1; then + printf 'check-docs-naming: git is required to list the tracked files under docs/\n' >&2 + exit 2 +fi +if ! git rev-parse --show-toplevel >/dev/null 2>&1; then + printf 'check-docs-naming: not inside a git repository, nothing inspected\n' >&2 + exit 2 +fi + +NAME_RE='^[a-z0-9]+([.-][a-z0-9]+)*\.[a-z0-9]+$' +offenders=() + +# One pass for the basename rule. Exemptions are checked in the order the +# header lists them; the regex only sees what nothing exempted. +while IFS= read -r -d '' path; do + [[ "$path" == docs/topics/* ]] && continue + base="${path##*/}" + [[ "$base" == README.md || "$base" == CHANGELOG.md || "$base" == INDEX.md ]] && continue + ext="${base##*.}" + case "$ext" in + py | sh | mjs | js | ps1) continue ;; + *) ;; + esac + if [[ ! "$base" =~ $NAME_RE ]]; then + offenders+=("$path: basename is not lower-kebab-case (rule: $NAME_RE)") + fi +done < <(git ls-files -z -- docs/) + +# One pass for case collisions, over EVERY tracked path under docs/ (exempt +# names included: `docs/README.md` beside `docs/readme.md` still collides). +# Lower-casing each path and looking for duplicates finds every pair; each +# member of a colliding group is reported against the group's folded form. +# The fold goes through `tr`, never `${path,,}`: that expansion is Bash 4+, +# and the checkouts this rule protects include stock macOS Bash 3.2. +while IFS= read -r folded; do + [[ -n "$folded" ]] || continue + while IFS= read -r -d '' path; do + if [[ "$(printf '%s' "$path" | tr '[:upper:]' '[:lower:]')" == "$folded" ]]; then + offenders+=("$path: differs only by case from another tracked path ($folded)") + fi + done < <(git ls-files -z -- docs/) +done < <(git ls-files -- docs/ | tr '[:upper:]' '[:lower:]' | sort | uniq -d) + +if ((${#offenders[@]} == 0)); then + printf 'check-docs-naming: every tracked file under docs/ is lower-kebab-case.\n' + exit 0 +fi + +printf '%s\n' "${offenders[@]}" | sort -u >&2 +printf 'check-docs-naming: %d offender(s); rename to lower-kebab-case (see the header of %s).\n' \ + "${#offenders[@]}" "scripts/${0##*/}" >&2 +exit 1 diff --git a/scripts/check-docs-naming.test.sh b/scripts/check-docs-naming.test.sh new file mode 100755 index 0000000000..726e971913 --- /dev/null +++ b/scripts/check-docs-naming.test.sh @@ -0,0 +1,128 @@ +#!/usr/bin/env bash +# Black-box contract test for check-docs-naming.sh. +# +# Self-contained and cwd-independent: builds a throwaway git repository with a +# fixture docs/ tree, runs the checker against it, and asserts on exit code + +# output. Mutates only its own mktemp dir. The SUT resolves the repository root +# relative to its own location, so the fixture tree carries a copy of it under +# scripts/ and every case commits its files so `git ls-files` sees them. +set -uo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +SUT_SRC="$SCRIPT_DIR/check-docs-naming.sh" + +# shellcheck source=lib/test-harness.sh +. "$SCRIPT_DIR/lib/test-harness.sh" +# shellcheck source=lib/fixture-tree.sh +. "$SCRIPT_DIR/lib/fixture-tree.sh" + +# mk_repo : a throwaway repo with a committed, rule-abiding docs/ tree. +# The builder assigns through a nameref, which shellcheck cannot follow. +mk_repo() { + local dir + fixture_tree::build "$1" --sut "$SUT_SRC" --git || return 1 + dir="${!1}" + mkdir -p "$dir/docs/conventions/topic-docs" "$dir/docs/adr" + printf 'seed\n' >"$dir/docs/README.md" + printf 'seed\n' >"$dir/docs/plugin-philosophy.md" + printf 'seed\n' >"$dir/docs/conventions/topic-docs/README.md" + printf 'seed\n' >"$dir/docs/adr/0001-first.md" + git_test_config "$dir" add -A >/dev/null + git_test_config "$dir" commit -qm base +} + +# run_case