From 296e865996fc4993b271630dc969bdbcff78237b Mon Sep 17 00:00:00 2001 From: "melodic-automation-lanes[bot]" <337595936+melodic-automation-lanes[bot]@users.noreply.github.com> Date: Sun, 22 Nov 2026 00:30:48 +0000 Subject: [PATCH 1/3] Resolve issue #18011 Lane-Activity: work-resolve-issue/resolve-issue --- ...ssue-issue-18011-44964524568-1-0d703719.md | 9 + docs/contracts/config-cascade/README.md | 7 +- docs/contracts/retired-conventions/README.md | 1 + .../improvement/.claude-plugin/plugin.json | 62 ++ plugins/improvement/README.md | 61 +- .../setup-apply-drafts-then-asks/prompt.md | 2 +- .../case.yaml | 2 +- .../prompt.md | 6 +- .../samples/both-probes.json | 8 +- .../samples/no-plugin-dir-write.json | 2 +- .../samples/recommends-local-gitignore.json | 10 +- .../evals/setup-check-both-new-wins/case.yaml | 41 + .../samples/lists-unapplied-key.json | 10 + .../samples/new-window-wins.json | 10 + .../samples/no-edit.json | 10 + .../samples/no-write.json | 10 + .../samples/warning-names-both.json | 9 + .../setup-check-both-new-wins/scaffold.sh | 20 + .../setup-check-new-layer-only/case.yaml | 37 + .../samples/no-edit.json | 10 + .../samples/no-old-file-warning.json | 10 + .../samples/no-write.json | 10 + .../samples/team-window-applies.json | 10 + .../setup-check-new-layer-only/scaffold.sh | 11 + .../setup-check-old-file-warns/case.yaml | 40 + .../samples/no-edit.json | 10 + .../samples/no-write.json | 10 + .../samples/old-value-applies.json | 10 + .../samples/reports-retirement-records.json | 10 + .../samples/warns-with-new-location.json | 11 + .../setup-check-old-file-warns/scaffold.sh | 23 + .../setup-check-zero-config-info/case.yaml | 8 +- .../samples/absent-is-info.json | 2 +- .../samples/names-three-layers.json | 10 +- .../setup-check-zero-config-info/scaffold.sh | 2 +- plugins/improvement/lib/check-retirements.sh | 730 ++++++++++++++++++ plugins/improvement/reference/config.md | 101 ++- plugins/improvement/retirements.yaml | 25 + .../schemas/improvement.schema.json | 94 +++ plugins/improvement/skills/find/SKILL.md | 34 +- .../skills/find/context/hotspots.md | 8 +- plugins/improvement/skills/setup/SKILL.md | 171 ++-- scripts/org-repo-tokens-allow.tsv | 1 + scripts/shared-copies.txt | 1 + 44 files changed, 1545 insertions(+), 124 deletions(-) create mode 100644 .changes/improvement/work-resolve-issue-issue-18011-44964524568-1-0d703719.md create mode 100644 plugins/improvement/evals/setup-check-both-new-wins/case.yaml create mode 100644 plugins/improvement/evals/setup-check-both-new-wins/samples/lists-unapplied-key.json create mode 100644 plugins/improvement/evals/setup-check-both-new-wins/samples/new-window-wins.json create mode 100644 plugins/improvement/evals/setup-check-both-new-wins/samples/no-edit.json create mode 100644 plugins/improvement/evals/setup-check-both-new-wins/samples/no-write.json create mode 100644 plugins/improvement/evals/setup-check-both-new-wins/samples/warning-names-both.json create mode 100755 plugins/improvement/evals/setup-check-both-new-wins/scaffold.sh create mode 100644 plugins/improvement/evals/setup-check-new-layer-only/case.yaml create mode 100644 plugins/improvement/evals/setup-check-new-layer-only/samples/no-edit.json create mode 100644 plugins/improvement/evals/setup-check-new-layer-only/samples/no-old-file-warning.json create mode 100644 plugins/improvement/evals/setup-check-new-layer-only/samples/no-write.json create mode 100644 plugins/improvement/evals/setup-check-new-layer-only/samples/team-window-applies.json create mode 100755 plugins/improvement/evals/setup-check-new-layer-only/scaffold.sh create mode 100644 plugins/improvement/evals/setup-check-old-file-warns/case.yaml create mode 100644 plugins/improvement/evals/setup-check-old-file-warns/samples/no-edit.json create mode 100644 plugins/improvement/evals/setup-check-old-file-warns/samples/no-write.json create mode 100644 plugins/improvement/evals/setup-check-old-file-warns/samples/old-value-applies.json create mode 100644 plugins/improvement/evals/setup-check-old-file-warns/samples/reports-retirement-records.json create mode 100644 plugins/improvement/evals/setup-check-old-file-warns/samples/warns-with-new-location.json create mode 100755 plugins/improvement/evals/setup-check-old-file-warns/scaffold.sh create mode 100755 plugins/improvement/lib/check-retirements.sh create mode 100644 plugins/improvement/retirements.yaml create mode 100644 plugins/improvement/schemas/improvement.schema.json diff --git a/.changes/improvement/work-resolve-issue-issue-18011-44964524568-1-0d703719.md b/.changes/improvement/work-resolve-issue-issue-18011-44964524568-1-0d703719.md new file mode 100644 index 00000000000..0e24b7d2a45 --- /dev/null +++ b/.changes/improvement/work-resolve-issue-issue-18011-44964524568-1-0d703719.md @@ -0,0 +1,9 @@ +--- +bump: minor +--- + +### Changed + +- Config resolves through the config-cascade layers: the plugin default, new `userConfig` options (one per key, with `evidence_sources_file` naming a YAML file of your Tier 2 sources), the team `docs/conventions/improvement.yaml`, then the gitignored `docs/conventions/improvement.local.yaml`. A schema for both files ships at `schemas/improvement.schema.json` ([#18011](https://github.com/melodic-software/claude-code-plugins/issues/18011)). +- `~/.claude/improvement.md`, `.claude/improvement.md` and `.claude/improvement.local.md` are still read while they exist, wherever the new location does not supply that layer. Each run prints one warning naming the old file, its new location and `/improvement:setup apply`. The two repository files are retirement records `improvement-r001` and `improvement-r002` in the new `retirements.yaml`, checked by the bundled `lib/check-retirements.sh`. +- `/improvement:setup check` names each old file, and when the new location also exists it lists the old keys that do not apply. `apply` shows a preview, and after your yes moves the old file's settings to the new location, checks they resolve the same values, then deletes the old file. Settings from `~/.claude/improvement.md` move to `userConfig` through `/plugin configure`; the old file is deleted on a later `apply` in a fresh session, once the options read the same values. diff --git a/docs/contracts/config-cascade/README.md b/docs/contracts/config-cascade/README.md index 85e2efd3e8d..26aaecf9642 100644 --- a/docs/contracts/config-cascade/README.md +++ b/docs/contracts/config-cascade/README.md @@ -715,7 +715,7 @@ its conformance cell. | `architecture` (`record-decision`) | no-floor | team `/architecture.yaml`, personal override `/architecture.local.yaml` (schema `plugins/architecture/schemas/architecture.schema.json`); per user: the plugin's `adr_template` and `adr_retirement` `userConfig` options | `userConfig` + team + personal for `adr_template` and `adr_retirement`; team + personal for `adr_extra_triggers` | later layer | per-key | conforms to [ADR 0075](../../adr/0075-resolve-plugin-settings-through-one-four-layer-cascade-and-a-bound-convention-home.md); keys owned by the plugin's [`reference/config.md`](../../../plugins/architecture/reference/config.md#decision-record-keys) and read in skill text by `/architecture:record-decision`, with no reader script. A repository's own ADR convention wins over `adr_template`. No folder-level layer | | `architecture` (`verification`) | team-only | team: `/architecture.yaml` (`` from the convention-home pointer line at the default branch, default `docs/conventions`; schema `plugins/architecture/schemas/architecture.schema.json`) | team only | the team file at the default branch; a skill entry over the plugin value; an invalid value resolves `standard`, no value `light` | per-key | conforms to the [location axis](#location-of-the-team-layer-a-docs-convention-file-or-claudename) ([ADR 0064](../../adr/0064-home-plugin-customization-in-docs-conventions-yaml.md)); no `userConfig` option, no `~/.claude` file, and `architecture.local.yaml` does not set it. `verification_skills.` beats `verification`. `lib/read-verification.sh` (the plugin's copy) reads the file at `origin/` after a fetch, never the working tree, so a branch cannot lower its own level, and names a working-tree copy that gives another level. An invalid value or a file that does not parse is named and resolves `standard`; no value resolves `light`. Levels owned by [`docs/contracts/verification-level/README.md`](../verification-level/README.md); read by `/architecture:improve`. This row covers `verification` and `verification_skills` | | `architecture` (`improve`) | no-floor | team `/architecture.yaml`, personal override `/architecture.local.yaml` (schema `plugins/architecture/schemas/architecture.schema.json`) | team + personal, then the invocation | later layer; the invocation prompt for one run | per-key (lists replace) | conforms to [ADR 0075](../../adr/0075-resolve-plugin-settings-through-one-four-layer-cascade-and-a-bound-convention-home.md); no `userConfig` option and no `~/.claude` file. `skills/improve/scripts/improve-settings.mjs` resolves the `improve` object and reports an unknown key or rejected value with its file and key, and that value is dropped. Keys owned by the plugin's [`reference/config.md`](../../../plugins/architecture/reference/config.md#improve-keys); read by `/architecture:improve` | -| `improvement` | lowest-value | team `.claude/improvement.md`; user-global `~/.claude/improvement.md`; personal override `.claude/improvement.local.md` | all three, then the invocation | later layer, then the invocation prompt for one run; lowest value for `find_open_item_cap` (policy floor) | per-key; `churn_exclude` unions; `evidence_sources` merges per name | conforms on layer set and precedence; the team layer is not yet on the [location axis](#location-of-the-team-layer-a-docs-convention-file-or-claudename). `find_open_item_cap` is the one policy-floor key: the team value, else the bundled default, sets it, the user-global and personal override layers apply only when lower, the invocation prompt cannot raise it, and a higher personal value is ignored and reported. Keys owned by the plugin's [`reference/config.md`](../../../plugins/improvement/reference/config.md); read by `/improvement:find`, verified and written by `/improvement:setup` | +| `improvement` | lowest-value | team `/improvement.yaml` (schema `plugins/improvement/schemas/improvement.schema.json`); per user: the plugin's `userConfig` option of each key's name, `evidence_sources_file` for `evidence_sources`; personal override `/improvement.local.yaml` | all four, then the invocation | later layer, then the invocation prompt for one run; lowest value for `find_open_item_cap` (policy floor) | per-key; `churn_exclude` unions; `evidence_sources` merges per name | conforms on the four layers and the [location axis](#location-of-the-team-layer-a-docs-convention-file-or-claudename). Dual-read window: while `.claude/improvement.md` or `.claude/improvement.local.md` exists it still supplies its layer where the new location does not, declared by the `migrate` retirement records `improvement-r001` and `improvement-r002` ([retired-conventions](../retired-conventions/README.md)); the machine-scope `~/.claude/improvement.md` is read the same way for each unset `userConfig` option, outside that mechanism. Each run prints one warning naming the old file, and `/improvement:setup apply` moves it and deletes it after a yes. `find_open_item_cap` is the one policy-floor key: the team value, else the bundled default, sets it, the `userConfig` and personal override layers apply only when lower, the invocation prompt cannot raise it, and a higher personal value is ignored and reported. Keys owned by the plugin's [`reference/config.md`](../../../plugins/improvement/reference/config.md); read by `/improvement:find`, verified and written by `/improvement:setup` | | `authoring-formats` | no-floor | convention doc at the consumer's convention home, `/authoring-formats/README.md` (the pointer line binds ``) | team, via pointer line | team via pointer line | convention doc | declared under the expression doctrine as a new surface, not a migration: no retired dedicated file, no retirement record, no dual-read window. One layer, no personal override channel, unknown keys inert. Keys (`acceptance_criteria_format`, `diagram_dialect.data`, `diagram_dialect.system`) owned by [`authoring-formats`](../authoring-formats/README.md#c4-dialect-surfaces), which also states the ladder each consuming plugin restates in one bundled file and maps the system key against architecture's `landscape_dialect` rather than restating mermaid fitness here. `diagram_dialect.system` deliberately has no default, so an absent surface emits no C4 container view. No policy-floor class: both keys are team format choices, and the doctrine gives this class no personal layer to weaken them from. **Read on `main` by `/planning:interview` and `/planning:prd` (`acceptance_criteria_format`), by `/planning:design` (`diagram_dialect.data`, `diagram_dialect.system`), by `/architecture:map-data` (`diagram_dialect.data`), and by `/architecture:map-components`, `/architecture:map-context`, `/architecture:map-containers`, and `/architecture:map-deployment` (`diagram_dialect.system`)**, each resolving `` through its plugin's bundled `lib/resolve-convention-home.sh`. Any further consuming slice lands per skill and updates that doc's Consumers table in the same change | | `instruction-placement` | team-only | `.claude/instruction-placement.md` | all three | team on conflict (policy-floor) | per-key | conforms; per-key override (suppression entries merge per `finding_id`), plus policy-floor inversion: the team layer wins a direct conflict and a personal-only entry is reported `personal-only, not applied`, since a decline removes a placement proposal from every future report and a personal layer hiding one the team never accepted is the weakening this class prevents. `suppressions` is the surface's only key today; the plugin's `userConfig` dials stay personal and are never keys here. Written (team layer only) by `/instruction-placement:realign` behind its per-item gate, read by `/instruction-placement:audit` and `/instruction-placement:delta`. Keys owned by the plugin's `reference/consumer-config.md`; suppression-entry keys by [`finding-suppression`](../finding-suppression/README.md) | | `overengineering` | team-only | `.claude/overengineering.md` | all three | team on conflict for protected keys | per-key | conforms; per-key override, plus policy-floor inversion on two key groups: the protected-categories set and the suppression entries (which merge per `finding_id`). On both, the team layer wins a direct conflict, personal layers may extend or tighten only, and a personal contribution is named in the report: a gitignored personal override emptying the protected set would defeat the plugin's FLAG-FOR-HUMAN cap on security-class artifacts, and a personal-only suppression is the same weakening `audit-pass` prevents above. Narrowing or emptying the protected set stays available on the tracked layer, spelled one category at a time so the diff names each protection dropped. The threshold and observation-window keys take ordinary refinement. Keys owned by the plugin's `reference/consumer-config.md`; suppression-entry keys by [`finding-suppression`](../finding-suppression/README.md) | @@ -800,7 +800,7 @@ model-run skill with no reader script, so the rule lives in the skill text. | `autonomy` | not yet | hooks anchor at `CLAUDE_PROJECT_DIR` (`hooks/hook-utils.sh`); `binding.json` has no shared reader script | | `architecture` (`record-decision`) | prose only | `/architecture:record-decision` resolves `` with the plugin's `lib/resolve-convention-home.sh` and skips both file layers when it exits 5 (the root is `$HOME`, an ancestor of it, or not a git work tree); no reader script; the `verification` key is read by `lib/read-verification.sh`, which sources the plugin's `lib/config-root.sh` | | `architecture` (`improve`) | prose only | `/architecture:improve` resolves `` in its skill text and passes `improve-settings.mjs` `--no-config` when no home resolves, so both file layers are skipped; the script does not classify the root itself | -| `improvement` | prose only | `/improvement:find` and `/improvement:setup` read the three layers in skill text, anchored at the repository root; no reader script | +| `improvement` | prose only | `/improvement:find` and `/improvement:setup` read the layers in skill text, anchored at `git rev-parse --show-toplevel`, and skip the team and personal override layers when that root is `$HOME`, an ancestor of it, or not a git working tree; no reader script | | `plugin-quality`, `architecture`, `authoring-formats` | not yet | each plugin's `lib/resolve-convention-home.sh`: `--root`, else `CLAUDE_PROJECT_DIR`, else git toplevel, else the current directory; team-only via pointer line, no user-global layer to collide with; plugin-quality's `verification` key is read by `lib/read-verification.sh`, which sources the plugin's `lib/config-root.sh` | | `ai-briefing`, `code-tidying` | prose only | team-only surfaces read by model-run skills | | `code-tidying` (`comment_lint*`) | implements (inline) | `scripts/comment-settings.sh`: the git toplevel of the directory it is given, else of the current directory; `lib/resolve-convention-home.sh` classifies the root, and the team layer is skipped when it is `$HOME`, an ancestor of it, or not a git working tree | @@ -865,7 +865,6 @@ tables above already declare policy-floor. | `codebase-health` | `.claude/codebase-health.md` | Markdown | | | `disk-hygiene` | `.claude/disk-hygiene.json` | JSON | user-global and team only | | `github` | `.claude/github/routing.yaml`, `.claude/github/conventions.md` | YAML, Markdown | policy-floor keys in `routing.yaml` | -| `improvement` | `.claude/improvement.md` | Markdown | policy-floor key `find_open_item_cap` | | `instruction-placement` | `.claude/instruction-placement.md` | Markdown | policy-floor | | `mutation-testing` | `.claude/mutation-testing-arid.md` | Markdown | a finding-suppression record; the settings are on the location axis at `docs/conventions/mutation-testing.yaml` | | `overengineering` | `.claude/overengineering.md` | Markdown | policy-floor | @@ -874,7 +873,7 @@ tables above already declare policy-floor. | `toolchain` | `.claude/ecosystems/.yaml` | YAML | also read by `code-metrics`, `review` and `code-tidying` | Already convention docs under ADR 0018, so outside this list: `plugin-quality`, `architecture` and -`authoring-formats`. Already on the location axis, so outside it too: `bugs`, the +`authoring-formats`. Already on the location axis, so outside it too: `bugs`, `improvement`, the `mutation-testing` settings, `planning`'s interview page settings and `source-control`. Declared location exceptions ([ADR 0042](../../adr/0042-ratify-consumer-config-location-outliers-in-place.md)), also outside it: `standards`' `/`, `songwriting`'s templates, and the `work-items` tracker binding and diff --git a/docs/contracts/retired-conventions/README.md b/docs/contracts/retired-conventions/README.md index 959964e72f5..ba8cd38b492 100644 --- a/docs/contracts/retired-conventions/README.md +++ b/docs/contracts/retired-conventions/README.md @@ -322,6 +322,7 @@ the row states the manifest as it exists on `main`. | `guardrails` | 4 | 2026-10-16 | | `attribution` | 4 | 2026-09-27 | | `harness-ops` | 5 | 2026-09-05 | +| `improvement` | 2 | 2026-11-22 | Row shape for a plugin adding itself: `` `` `` \| count \| `YYYY-MM-DD`. The convention-doc expression-form pilot was `plugin-quality`'s `.claude/plugin-quality.md` (ADR 0018), retired by that diff --git a/plugins/improvement/.claude-plugin/plugin.json b/plugins/improvement/.claude-plugin/plugin.json index ca2ea20706d..94e3c9eccd3 100644 --- a/plugins/improvement/.claude-plugin/plugin.json +++ b/plugins/improvement/.claude-plugin/plugin.json @@ -19,5 +19,67 @@ ], "metadata": { "category": "quality" + }, + "userConfig": { + "churn_window": { + "type": "string", + "title": "Churn window", + "description": "Your git log --since window for the hotspot recipe, such as 90 days ago. A repository's docs/conventions/improvement.yaml overrides it. Unset: 90 days ago." + }, + "churn_exclude": { + "type": "string", + "title": "Churn exclusions", + "description": "Extra ERE patterns, one per entry, left out of churn counting in every repository. Unioned with the repository's own patterns.", + "multiple": true + }, + "churn_exclude_defaults": { + "type": "boolean", + "title": "Exclude mechanical files from churn", + "description": "false drops the lockfiles, generated output, snapshots and vendored trees resolved from each repository, leaving only declared patterns. Unset: true." + }, + "find_open_item_cap": { + "type": "number", + "title": "Open item cap", + "description": "Lowers the cap on open items per source label that unattended /improvement:find files under. Applies only when below the repository's cap. 0 stops unattended filing.", + "min": 0 + }, + "find_run_item_cap": { + "type": "number", + "title": "Items filed per unattended run", + "description": "Where the adaptive per-run filing cap starts. Unset: 3.", + "min": 1 + }, + "find_run_item_cap_floor": { + "type": "number", + "title": "Per-run filing cap floor", + "description": "Lowest value the per-run filing cap adapts to. Unset: 1.", + "min": 1 + }, + "find_run_item_cap_ceiling": { + "type": "number", + "title": "Per-run filing cap ceiling", + "description": "Highest value the per-run filing cap adapts to. Unset: 5.", + "min": 1 + }, + "find_size_band": { + "type": "string", + "title": "Unattended size band", + "description": "Candidate sizes an unattended run ranks: all, small, medium or large. Unset: all." + }, + "find_scope": { + "type": "string", + "title": "Unattended scope", + "description": "What an unattended run scans: repo, or a target /improvement:find accepts. Unset: repo." + }, + "find_suppress_dismissed": { + "type": "boolean", + "title": "Suppress dismissed candidates", + "description": "Whether an unattended run leaves out candidates an operator dismissed before. Unset: true." + }, + "evidence_sources_file": { + "type": "file", + "title": "Evidence sources file", + "description": "A YAML file of yours whose evidence_sources key declares Tier 2 telemetry sources (MCP server, kind, scope, hints) for every repository. A repository's own declarations merge over it per source name." + } } } diff --git a/plugins/improvement/README.md b/plugins/improvement/README.md index 777ca4d400b..b4190085599 100644 --- a/plugins/improvement/README.md +++ b/plugins/improvement/README.md @@ -9,7 +9,7 @@ measured against a stated standard, as one small PR, ready or draft by the repos |---|---| | `/improvement:improve` | Improve-one-thing. Point it at any target (a symbol, file, feature, skill, doc, or process) with an optional focus such as performance, naming, or currency with current upstream guidance. It finds one gap against the repo's written standards (and upstream guidance when the focus asks for it), ships the smallest complete fix as one PR (ready or draft by the repository's open-state rule) within the [PR scope budget](reference/pr-scope-budget.md), and hands larger changes to planning. With no arguments it reads the conversation and confirms target and focus with you first. Runnable unattended on a schedule. | | `/improvement:find` | Evidence-first improvement finder. Point it at a repo, a feature, a concept, or a process surface, with a vague or specific prompt, and it produces a ranked, evidence-cited list of improvement candidates led by the highest value-to-effort, deliberates on the picked candidate through an interview, and hands off to the planning pipeline. Runnable unattended as a tech-debt-sweep routine. | -| `/improvement:setup` | Verifies or writes the `.claude/improvement.md` config cascade and reports the effective evidence-source configuration. `check` (default) is read-only across all three layers; `apply` interviews and writes the team file. Key contract: [reference/config.md](reference/config.md). | +| `/improvement:setup` | Verifies or writes the config cascade and reports the effective evidence-source configuration. `check` (default) is read-only across every layer and names any old-location file; `apply` moves an old file's settings to the new location after a yes, then interviews and writes the team file. Key contract: [reference/config.md](reference/config.md). | ## Install @@ -40,12 +40,16 @@ already does. ## Configuration Zero config is a fully working state: Tier 0 repo-native evidence needs nothing declared. To tune -churn analysis or declare Tier 2 MCP telemetry sources, run `/improvement:setup`. It manages the -`.claude/improvement.md` cascade. The resolution order is `~/.claude/improvement.md` (user-global), then -the team `.claude/improvement.md`, then the gitignored `.claude/improvement.local.md` personal override. The key contract lives in +churn analysis or declare Tier 2 MCP telemetry sources, run `/improvement:setup`. Settings resolve +lowest first from the bundled default, the plugin's `userConfig` options (per person, set with +`/plugin configure improvement@`), the team `docs/conventions/improvement.yaml`, +then the gitignored `docs/conventions/improvement.local.yaml`, per +[config locations](reference/config-locations.md). The key contract lives in [reference/config.md](reference/config.md). -This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](reference/config-locations.md) says. +The old files `~/.claude/improvement.md`, `.claude/improvement.md` and +`.claude/improvement.local.md` are still read while they exist, with a warning on each run; +`/improvement:setup apply` moves their settings to the new locations and deletes them. ## Running it as a standing routine @@ -83,7 +87,7 @@ Tuning — edit these lines as you observe real runs: ``` Cadence and time of day belong to the scheduler. The cap, scope, size band and dismissed-candidate -handling resolve from the prompt, then `.claude/improvement.md`, then the bundled default (see +handling resolve from the prompt, then the config cascade, then the bundled default (see [skills/find/context/unattended.md](skills/find/context/unattended.md) and [reference/config.md](reference/config.md)). The open cap is the exception: the prompt cannot raise it, and personal settings can only lower it. @@ -151,3 +155,48 @@ pushes a branch and opens a pull request, so its job needs `contents: write` and `/loop` is session-scoped only: it repeats a prompt inside one session and dies with it. It suits repeating a check during a working session, but it is not a standing schedule. A recurring unattended sweep needs a Routine or a cron workflow, which fire fresh sessions on a standing cadence. + + + +### Options reference + +Generated from this plugin's `.claude-plugin/plugin.json`. For how Claude Code asks for +these and hands them to the plugin, see [User configuration](https://code.claude.com/docs/en/plugins/manifest-reference#user-configuration). + +| Option | Type | Default | Description | +| --- | --- | --- | --- | +| `churn_window` | string | *(none)* | Your git log --since window for the hotspot recipe, such as 90 days ago. A repository's docs/conventions/improvement.yaml overrides it. Unset: 90 days ago. | +| `churn_exclude` | string (multiple) | *(none)* | Extra ERE patterns, one per entry, left out of churn counting in every repository. Unioned with the repository's own patterns. | +| `churn_exclude_defaults` | boolean | *(none)* | false drops the lockfiles, generated output, snapshots and vendored trees resolved from each repository, leaving only declared patterns. Unset: true. | +| `find_open_item_cap` | number
*min 0* | *(none)* | Lowers the cap on open items per source label that unattended /improvement:find files under. Applies only when below the repository's cap. 0 stops unattended filing. | +| `find_run_item_cap` | number
*min 1* | *(none)* | Where the adaptive per-run filing cap starts. Unset: 3. | +| `find_run_item_cap_floor` | number
*min 1* | *(none)* | Lowest value the per-run filing cap adapts to. Unset: 1. | +| `find_run_item_cap_ceiling` | number
*min 1* | *(none)* | Highest value the per-run filing cap adapts to. Unset: 5. | +| `find_size_band` | string | *(none)* | Candidate sizes an unattended run ranks: all, small, medium or large. Unset: all. | +| `find_scope` | string | *(none)* | What an unattended run scans: repo, or a target /improvement:find accepts. Unset: repo. | +| `find_suppress_dismissed` | boolean | *(none)* | Whether an unattended run leaves out candidates an operator dismissed before. Unset: true. | +| `evidence_sources_file` | file | *(none)* | A YAML file of yours whose evidence_sources key declares Tier 2 telemetry sources (MCP server, kind, scope, hints) for every repository. A repository's own declarations merge over it per source name. | + +### How to set these + +Set the options above for `improvement@`, replacing `` with the +marketplace you installed this plugin from: + +- **In a session or headless:** [`/plugin` in a session](https://code.claude.com/docs/en/plugins/cli-reference#plugin-in-a-session) or + [`claude plugin configure`](https://code.claude.com/docs/en/plugins/cli-reference#plugin-configure). The configure command is the preferred + headless route in the [plugin-reconfiguration convention](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/plugin-reconfiguration/README.md), which records its limits. +- **By hand:** under [`pluginConfigs`](https://code.claude.com/docs/en/settings-reference#pluginconfigs) in your **user** settings. + +Do **not** uninstall the plugin to reconfigure it: see [What an uninstall deletes and keeps](https://code.claude.com/docs/en/plugins/cli-reference#what-an-uninstall-deletes-and-keeps). +For a Claude Code release without `plugin configure`, see [Plugin install](https://code.claude.com/docs/en/plugins/cli-reference#plugin-install). + +### Upstream documentation + +- [User configuration](https://code.claude.com/docs/en/plugins/manifest-reference#user-configuration) +- [Plugin configure](https://code.claude.com/docs/en/plugins/cli-reference#plugin-configure) +- [Plugin install options](https://code.claude.com/docs/en/plugins/cli-reference#plugin-install) +- [Plugins and skills settings](https://code.claude.com/docs/en/settings-reference#plugins-and-skills) +- [Settings files and who they affect](https://code.claude.com/docs/en/settings#settings-files-and-who-they-affect) +- [Manage installed plugins](https://code.claude.com/docs/en/plugins/install#manage-installed-plugins) + + diff --git a/plugins/improvement/evals/setup-apply-drafts-then-asks/prompt.md b/plugins/improvement/evals/setup-apply-drafts-then-asks/prompt.md index 13b75294d60..57b3690c6d7 100644 --- a/plugins/improvement/evals/setup-apply-drafts-then-asks/prompt.md +++ b/plugins/improvement/evals/setup-apply-drafts-then-asks/prompt.md @@ -1,5 +1,5 @@ --- -description: "Legacy setup case apply-interviews-and-writes-team-file-only, first turn. Narration: no MCP server loads in a run, so the prompt names the session's configured servers as facts. Before writing anything, apply presents the effective baseline across layers ahead of its first question (baseline-before-question), drafts a churn_exclude entry for the committed src/generated/ tree (drafts-generated-exclusion) and the declared acme-telemetry server as an evidence-source candidate (drafts-telemetry-candidate), asks with a recommendation (asks-with-recommendation), names no telemetry server the session does not have as an mcp_server value (no-undeclared-source), and makes no Write or Edit call, so no layer is written before the user answers (no-write, no-edit). Writing only the team file is unmeasured: the run's writes under the workspace .claude/ are denied, so the case grades what apply produces before that write; a run that writes before asking is denied that Write, the no-write grader fails it, and the validity gate warns rather than voiding the batch. Slash-invoked (disable-model-invocation), so there is no Skill grader. Needs --scaffold and --allow-tools Write Edit so the write graders can fail." +description: "Legacy setup case apply-interviews-and-writes-team-file-only, first turn. Narration: no MCP server loads in a run, so the prompt names the session's configured servers as facts. Before writing anything, apply presents the effective baseline across layers ahead of its first question (baseline-before-question), drafts a churn_exclude entry for the committed src/generated/ tree (drafts-generated-exclusion) and the declared acme-telemetry server as an evidence-source candidate (drafts-telemetry-candidate), asks with a recommendation (asks-with-recommendation), names no telemetry server the session does not have as an mcp_server value (no-undeclared-source), and makes no Write or Edit call, so no layer is written before the user answers (no-write, no-edit). Writing only the team file is unmeasured: the case grades what apply produces before that write, and a run that writes docs/conventions/improvement.yaml before asking fails the no-write grader. Slash-invoked (disable-model-invocation), so there is no Skill grader. Needs --scaffold and --allow-tools Write Edit so the write graders can fail." tags: [setup, apply, interview, narration, no-network] max_turns: 15 timeout_seconds: 600 diff --git a/plugins/improvement/evals/setup-apply-verify-tracked-proposal/case.yaml b/plugins/improvement/evals/setup-apply-verify-tracked-proposal/case.yaml index 0c7aee5918a..3801508f377 100644 --- a/plugins/improvement/evals/setup-apply-verify-tracked-proposal/case.yaml +++ b/plugins/improvement/evals/setup-apply-verify-tracked-proposal/case.yaml @@ -56,6 +56,6 @@ graders: arm: both - name: recommends-local-gitignore type: regex - pattern: '\.claude/\*\*/\*\.local\.\*' + pattern: 'docs/conventions/\*\*/\*\.local\.\*' target: last_message arm: both diff --git a/plugins/improvement/evals/setup-apply-verify-tracked-proposal/prompt.md b/plugins/improvement/evals/setup-apply-verify-tracked-proposal/prompt.md index 047d15f63db..8ee5536ce4a 100644 --- a/plugins/improvement/evals/setup-apply-verify-tracked-proposal/prompt.md +++ b/plugins/improvement/evals/setup-apply-verify-tracked-proposal/prompt.md @@ -1,14 +1,14 @@ --- -description: "Legacy setup case verifies-tracked-and-offers-personal-override-convention. Narration: a run's writes under the workspace .claude/ are denied and setup needs no shell to propose, so the prompt switches writes and commands off and asks for the file, the verification and the report; the case grades that proposal, not a write or a probe run. The proposed team file holds churn keys (proposes-churn-keys) and no evidence_sources entry (no-evidence-source-entry), and the reply says Tier 2 stays an evidence gap (tier2-gap). The verification names both probes, git check-ignore and git ls-files --error-unmatch (both-probes), and reports the untracked file as needing a commit (untracked-commit-it). The reply recommends the recursive .claude/**/*.local.* line for the personal override (recommends-local-gitignore) and neither writes nor edits .gitignore or anything under the plugin or plugin-data folders (no-gitignore-write, no-gitignore-edit, no-plugin-dir-write). Slash-invoked (disable-model-invocation), so there is no Skill grader. Needs --scaffold and --allow-tools Write Edit so the write graders can fail." +description: "Legacy setup case verifies-tracked-and-offers-personal-override-convention. Narration: a run's writes under the workspace docs/conventions/ are denied and setup needs no shell to propose, so the prompt switches writes and commands off and asks for the file, the verification and the report; the case grades that proposal, not a write or a probe run. The proposed team file holds churn keys (proposes-churn-keys) and no evidence_sources entry (no-evidence-source-entry), and the reply says Tier 2 stays an evidence gap (tier2-gap). The verification names both probes, git check-ignore and git ls-files --error-unmatch (both-probes), and reports the untracked file as needing a commit (untracked-commit-it). The reply recommends the recursive docs/conventions/**/*.local.* line for the personal file (recommends-local-gitignore) and neither writes nor edits .gitignore or anything under the plugin or plugin-data folders (no-gitignore-write, no-gitignore-edit, no-plugin-dir-write). Slash-invoked (disable-model-invocation), so there is no Skill grader. Needs --scaffold and --allow-tools Write Edit so the write graders can fail." tags: [setup, apply, verify, narration, no-network] max_turns: 15 timeout_seconds: 600 allowed_tools: [Read, Glob, Grep, Skill, Write, Edit] -expected_outcome: "The reply shows a .claude/improvement.md holding only confirmed churn keys and no evidence_sources entry, says Tier 2 stays an evidence gap, names git check-ignore -v and git ls-files --error-unmatch as the post-write checks, says the freshly written file is untracked and must be committed (not a success), and recommends adding .claude/**/*.local.* to .gitignore without editing it." +expected_outcome: "The reply shows a docs/conventions/improvement.yaml holding only confirmed churn keys and no evidence_sources entry, says Tier 2 stays an evidence gap, names git check-ignore -v and git ls-files --error-unmatch as the post-write checks, says the freshly written file is untracked and must be committed (not a success), and recommends adding docs/conventions/**/*.local.* to .gitignore without editing it." --- /improvement:setup apply Just write a sensible config for this repo. Churn defaults are fine, no telemetry sources yet. -Writes under .claude/ are denied in this sandbox and shell commands are off, so write nothing and run nothing: show the exact file you would write, the verification you would run on it once written, and what you would report. +Writes under docs/conventions/ are denied in this sandbox and shell commands are off, so write nothing and run nothing: show the exact file you would write, the verification you would run on it once written, and what you would report. diff --git a/plugins/improvement/evals/setup-apply-verify-tracked-proposal/samples/both-probes.json b/plugins/improvement/evals/setup-apply-verify-tracked-proposal/samples/both-probes.json index e2328dab20a..18161070ebe 100644 --- a/plugins/improvement/evals/setup-apply-verify-tracked-proposal/samples/both-probes.json +++ b/plugins/improvement/evals/setup-apply-verify-tracked-proposal/samples/both-probes.json @@ -1,21 +1,21 @@ { "pass": [ { - "answer": "Verify:\n\n```bash\ngit check-ignore -v .claude/improvement.md\ngit ls-files --error-unmatch .claude/improvement.md\n```", + "answer": "Verify:\n\n```bash\ngit check-ignore -v docs/conventions/improvement.yaml\ngit ls-files --error-unmatch docs/conventions/improvement.yaml\n```", "why": "both probes" }, { - "answer": "Run `git check-ignore -v .claude/improvement.md` (expect no output) and `git ls-files --error-unmatch .claude/improvement.md` (expect exit 1 until committed).", + "answer": "Run `git check-ignore -v docs/conventions/improvement.yaml` (expect no output) and `git ls-files --error-unmatch docs/conventions/improvement.yaml` (expect exit 1 until committed).", "why": "inline" } ], "fail": [ { - "answer": "Verify with `git check-ignore -v .claude/improvement.md`; no output means it is shared.", + "answer": "Verify with `git check-ignore -v docs/conventions/improvement.yaml`; no output means it is shared.", "why": "not-ignored probe only" }, { - "answer": "Verify with `git ls-files --error-unmatch .claude/improvement.md`.", + "answer": "Verify with `git ls-files --error-unmatch docs/conventions/improvement.yaml`.", "why": "tracked probe only" } ] diff --git a/plugins/improvement/evals/setup-apply-verify-tracked-proposal/samples/no-plugin-dir-write.json b/plugins/improvement/evals/setup-apply-verify-tracked-proposal/samples/no-plugin-dir-write.json index 5c0b55d4b15..513edb1b712 100644 --- a/plugins/improvement/evals/setup-apply-verify-tracked-proposal/samples/no-plugin-dir-write.json +++ b/plugins/improvement/evals/setup-apply-verify-tracked-proposal/samples/no-plugin-dir-write.json @@ -5,7 +5,7 @@ { "tool": "Write", "input": { - "file_path": "/ws/.claude/improvement.md", + "file_path": "/ws/docs/conventions/improvement.yaml", "content": "x" } } diff --git a/plugins/improvement/evals/setup-apply-verify-tracked-proposal/samples/recommends-local-gitignore.json b/plugins/improvement/evals/setup-apply-verify-tracked-proposal/samples/recommends-local-gitignore.json index 9551819bb38..d6325f9053a 100644 --- a/plugins/improvement/evals/setup-apply-verify-tracked-proposal/samples/recommends-local-gitignore.json +++ b/plugins/improvement/evals/setup-apply-verify-tracked-proposal/samples/recommends-local-gitignore.json @@ -1,18 +1,22 @@ { "pass": [ { - "answer": "Add this line to .gitignore yourself:\n\n```gitignore\n.claude/**/*.local.*\n```", + "answer": "Add this line to .gitignore yourself:\n\n```gitignore\ndocs/conventions/**/*.local.*\n```", "why": "recursive line" } ], "fail": [ { - "answer": "Add `.claude/improvement.local.md` to .gitignore.", + "answer": "Add `docs/conventions/improvement.local.yaml` to .gitignore.", "why": "single file, not the recursive line" }, { "answer": "Add `*.local.*` to .gitignore.", - "why": "not scoped to .claude" + "why": "not scoped to the convention home" + }, + { + "answer": "Add `.claude/**/*.local.*` to .gitignore.", + "why": "the old location's line, with no old personal file present" } ] } diff --git a/plugins/improvement/evals/setup-check-both-new-wins/case.yaml b/plugins/improvement/evals/setup-check-both-new-wins/case.yaml new file mode 100644 index 00000000000..79287906127 --- /dev/null +++ b/plugins/improvement/evals/setup-check-both-new-wins/case.yaml @@ -0,0 +1,41 @@ +schema_version: "1.1" +name: setup-check-both-new-wins +description: 'Bare /improvement:setup runs the read-only check on a repository holding both team files: the new docs/conventions/improvement.yaml (churn_window 30 days ago) and the old .claude/improvement.md (churn_window 180 days ago, find_size_band small). The new file wins the team layer, so the effective window is 30 days from improvement.yaml (new-window-wins); the warning names both files (warning-names-both) and lists find_size_band as an old key that does not apply (lists-unapplied-key), so no old setting is dropped silently. It neither writes nor edits (no-write, no-edit). Slash-invoked (disable-model-invocation), so there is no Skill-fired grader. Needs --scaffold and --allow-tools Write Edit so the write graders can fail.' +tags: [setup, check, config-cascade, dual-read, no-network] +expected_outcome: 'A PASS/FAIL/WARN/INFO report in which the effective churn_window is 30 days ago from docs/conventions/improvement.yaml, a WARN names both .claude/improvement.md and docs/conventions/improvement.yaml and says the new file wins, and find_size_band (set only in the old file) is listed as not applied. Nothing is written.' +context: + scaffold_script: scaffold.sh +execution: + prompt: '/improvement:setup' + allowed_tools: [Read, Glob, Grep, Bash, Skill, Write, Edit] + max_turns: 15 + timeout_seconds: 600 +graders: + - name: no-write + type: tool_used + tool: 'Write' + min: 0 + max: 0 + arm: both + - name: no-edit + type: tool_used + tool: 'Edit' + min: 0 + max: 0 + arm: both + - name: new-window-wins + type: regex + pattern: '(? docs/conventions/improvement.yaml <<'CONFIG' +churn_window: "30 days ago" +CONFIG +cat > .claude/improvement.md <<'CONFIG' +# improvement config + +```yaml +churn_window: "180 days ago" +find_size_band: small +``` +CONFIG diff --git a/plugins/improvement/evals/setup-check-new-layer-only/case.yaml b/plugins/improvement/evals/setup-check-new-layer-only/case.yaml new file mode 100644 index 00000000000..5059dae04cb --- /dev/null +++ b/plugins/improvement/evals/setup-check-new-layer-only/case.yaml @@ -0,0 +1,37 @@ +schema_version: "1.1" +name: setup-check-new-layer-only +description: 'Bare /improvement:setup runs the read-only check on a repository whose only improvement config is the new team file docs/conventions/improvement.yaml, setting churn_window to 30 days ago. The reply gives the effective churn window as 30 days with the team file as its layer (team-window-applies), prints no dual-read warning about an old .claude/ file (no-old-file-warning), and neither writes nor edits (no-write, no-edit). Slash-invoked (disable-model-invocation), so there is no Skill-fired grader. Needs --scaffold and --allow-tools Write Edit so the write graders can fail.' +tags: [setup, check, config-cascade, no-network] +expected_outcome: 'A PASS/FAIL/WARN/INFO report reading the team layer from docs/conventions/improvement.yaml: the effective churn_window is 30 days ago, supplied by the team file. No old-location file exists, so no dual-read warning names one. Nothing is written.' +context: + scaffold_script: scaffold.sh +execution: + prompt: '/improvement:setup' + allowed_tools: [Read, Glob, Grep, Bash, Skill, Write, Edit] + max_turns: 15 + timeout_seconds: 600 +graders: + - name: no-write + type: tool_used + tool: 'Write' + min: 0 + max: 0 + arm: both + - name: no-edit + type: tool_used + tool: 'Edit' + min: 0 + max: 0 + arm: both + - name: team-window-applies + type: regex + pattern: '30 days(?: ago)?[^\n]{0,200}?(?:\bteam\b|improvement\.yaml)|(?:\bteam\b|(? docs/conventions/improvement.yaml <<'CONFIG' +churn_window: "30 days ago" +CONFIG diff --git a/plugins/improvement/evals/setup-check-old-file-warns/case.yaml b/plugins/improvement/evals/setup-check-old-file-warns/case.yaml new file mode 100644 index 00000000000..3dbdf131ffb --- /dev/null +++ b/plugins/improvement/evals/setup-check-old-file-warns/case.yaml @@ -0,0 +1,40 @@ +schema_version: "1.1" +name: setup-check-old-file-warns +description: 'Bare /improvement:setup runs the read-only check on a repository whose only improvement config is the old team file .claude/improvement.md, setting churn_window to 30 days ago, and the old personal file .claude/improvement.local.md, setting find_size_band to small, with no docs/conventions/improvement*.yaml. The dual-read window still applies the old value, reported with the old file as its layer (old-value-applies), and the reply prints a warning naming the old file, its new location docs/conventions/improvement.yaml and /improvement:setup apply (warns-with-new-location). The retirement helper reports both records (reports-retirement-records). It neither writes, edits nor deletes anything (no-write, no-edit). Slash-invoked (disable-model-invocation), so there is no Skill-fired grader. Needs --scaffold and --allow-tools Write Edit so the write graders can fail.' +tags: [setup, check, config-cascade, dual-read, no-network] +expected_outcome: 'A PASS/FAIL/WARN/INFO report in which the effective churn_window is 30 days ago, supplied by the old .claude/improvement.md, and a WARN names that file, says to move it to docs/conventions/improvement.yaml, and names /improvement:setup apply as the command that moves it. Nothing is written or deleted.' +context: + scaffold_script: scaffold.sh +execution: + prompt: '/improvement:setup' + allowed_tools: [Read, Glob, Grep, Bash, Skill, Write, Edit] + max_turns: 15 + timeout_seconds: 600 +graders: + - name: no-write + type: tool_used + tool: 'Write' + min: 0 + max: 0 + arm: both + - name: no-edit + type: tool_used + tool: 'Edit' + min: 0 + max: 0 + arm: both + - name: old-value-applies + type: regex + pattern: '30 days(?: ago)?[^\n]{0,200}?(? .claude/improvement.md <<'CONFIG' +# improvement config + +```yaml +churn_window: "30 days ago" +``` +CONFIG +cat > .claude/improvement.local.md <<'CONFIG' +# improvement personal config + +```yaml +find_size_band: small +``` +CONFIG diff --git a/plugins/improvement/evals/setup-check-zero-config-info/case.yaml b/plugins/improvement/evals/setup-check-zero-config-info/case.yaml index a20b118d9f4..825c457ca21 100644 --- a/plugins/improvement/evals/setup-check-zero-config-info/case.yaml +++ b/plugins/improvement/evals/setup-check-zero-config-info/case.yaml @@ -1,13 +1,13 @@ schema_version: "1.1" name: setup-check-zero-config-info -description: 'Legacy setup case check-reports-effective-config-read-only. Bare /improvement:setup runs the read-only check on a repository with no improvement config in any layer. The reply names all three cascade layers, user-global, team and personal override (names-three-layers), reports their absence as INFO (absent-is-info) with no FAIL status (no-fail-status), gives the effective churn window as the bundled default of 90 days (bundled-default-window), and neither writes, edits nor runs the /improvement:find scan (no-write, no-edit, no-scan). Slash-invoked (disable-model-invocation), so there is no Skill-fired grader. Needs --scaffold and --allow-tools Write Edit so the write graders can fail.' +description: 'Legacy setup case check-reports-effective-config-read-only. Bare /improvement:setup runs the read-only check on a repository with no improvement config in any layer. The reply names the three configurable cascade layers, userConfig, team and personal (names-three-layers), reports their absence as INFO (absent-is-info) with no FAIL status (no-fail-status), gives the effective churn window as the bundled default of 90 days (bundled-default-window), and neither writes, edits nor runs the /improvement:find scan (no-write, no-edit, no-scan). Slash-invoked (disable-model-invocation), so there is no Skill-fired grader. Needs --scaffold and --allow-tools Write Edit so the write graders can fail.' tags: [setup, check, zero-config, no-network] -expected_outcome: 'A PASS/FAIL/INFO report saying no layer exists (user-global ~/.claude/improvement.md, team .claude/improvement.md, personal override .claude/improvement.local.md), reported as INFO: the bundled defaults apply (churn window 90 days ago, default exclusions) and Tier 2 is an evidence gap. Nothing is written and no scan runs.' +expected_outcome: 'A PASS/FAIL/INFO report saying no layer exists (no userConfig option set, no team docs/conventions/improvement.yaml, no personal docs/conventions/improvement.local.yaml, and no old file), reported as INFO: the bundled defaults apply (churn window 90 days ago, default exclusions) and Tier 2 is an evidence gap. Nothing is written and no scan runs.' context: scaffold_script: scaffold.sh execution: prompt: '/improvement:setup' - allowed_tools: [Read, Glob, Grep, Skill, Write, Edit] + allowed_tools: [Read, Glob, Grep, Bash, Skill, Write, Edit] max_turns: 15 timeout_seconds: 600 graders: @@ -32,7 +32,7 @@ graders: arm: both - name: names-three-layers type: regex - pattern: '(?=[\s\S]*(?:~/\.claude/improvement\.md|\buser[- ]global\b))(?=[\s\S]*(?:improvement\.local\.md|\bpersonal override\b))[\s\S]*(?:\bteam\b|(?-rNNN — unique within the manifest, never reused +# retired YYYY-MM-DD +# plugin_version semver of the release that retired the convention +# kind file | dir | line | block +# path repo-relative; absolute, `..` segments, a leading `~`, +# backslashes, `.` and tabs are rejected +# match POSIX ERE — REQUIRED for kind line and block, forbidden +# otherwise +# heading optional ATX heading (1-6 hashes, whitespace, title), kind +# line only: the record only fires when a matching line sits +# in that heading's section body, so a standalone occurrence +# elsewhere in a markdown file is not a leftover +# content_match optional POSIX ERE, kind file only: the record only fires +# when the file's content matches, so a path the successor +# reuses is not reported as a leftover +# action delete | remove-line | migrate — remove-line only with kind +# line, delete only with kind file or dir, kind block only +# with migrate +# successor prose the model follows for a migrate — REQUIRED for migrate +# note one line, required +# status optional; active (default) | report-only (the demotion) +# +# DETECTION. Per kind: file = a regular file exists at path AND (no +# content_match OR it matches); dir = a directory exists; line = the file +# exists AND some line matches `match` (and, when `heading` is set, that line +# sits in the body of a markdown section whose heading line equals `heading`); +# block = the file exists AND some line matches `match`, that line starting a +# block that also holds every following blank line, line indented deeper than +# it, or `-` sequence item at its own indent, up to the next other non-blank +# line indented no deeper (a YAML key and its value). A section runs from the line after that heading through the line before the +# next ATX heading of the same or higher level, or EOF; every such section is +# searched. A trailing carriage return is stripped from every line before +# matching, so a `$`-anchored pattern matches a CRLF-authored file. One TSV +# row per leftover on stdout: +# +# idkindpathactionstatusnote +# +# Paths are emitted exactly as declared — repo-relative, never joined onto the +# root (docs/contracts/windows-path-emit). A human summary goes to stderr. +# +# NON-REPOSITORY ROOT. When the root is $HOME, or has no `.git` and is not +# inside a git work tree, a kind file record is not evaluated: there a +# `.claude/.json` path names the live user-global layer, not a retired +# team file. Its line goes to stderr as `: skipped: root is not a +# repository`, no row is written, and `--clean` of that record is refused. +# +# CLEANUP. `--clean ` cleans exactly one record's artifact. delete unlinks +# the file (only if content_match, when declared, still matches) or removes the +# directory (only after re-resolving that it is inside the root and is not the +# root itself). remove-line rewrites the file keeping every non-matching line +# byte-for-byte — each line's own ending survives, so a CRLF file stays CRLF — +# via a temp file in the same directory and a rename. When `heading` is set, +# only matching lines inside that heading's section body are removed. block +# rewrites the file the same way without each matched block, and removes the +# file when no non-blank line is left. A migrate +# record refuses to clean until `--i-migrated` states that the successor prose +# was followed; it then removes the artifact the way its kind implies. +# +# VALIDATION FAILS THE WHOLE RUN. An invalid record — bad kind, missing match, +# absolute path, duplicate id, migrate without successor, an unknown key — is +# exit 2 before any row is written, naming the record and the field. A skipped +# record would be a leftover nobody hears about, which is the failure this +# helper exists to end. +# +# Usage: +# check-retirements.sh --manifest [--root ] +# check-retirements.sh --manifest --clean [--i-migrated] [--root ] +# check-retirements.sh --help +# +# --root defaults to ${CLAUDE_PROJECT_DIR}, else the git toplevel, else cwd. +# When the root is a linked worktree, a `.git/` path resolves under the +# common git dir (`.git/hooks/x` is `/hooks/x`). +# +# Exit (detect): 0 no active leftover (report-only hits may still be listed); +# 1 at least one active leftover; 2 usage, unreadable manifest, +# or an invalid record. +# Exit (clean): 0 cleaned; 1 nothing present to clean; 2 usage, invalid +# record, unknown id, migrate without --i-migrated, a file +# record at a non-repository root, or a failed +# remove/rename (on Windows usually a locked file — close it and +# re-run; nothing is left half-done). +# +# Shared source: lib/check-retirements.sh at the marketplace repo root is the canonical source; the copies in the plugins +# that carry it are generated by scripts/sync-shared-copies.sh and registered in +# scripts/shared-copies.txt. Bash 3.2-compatible on purpose: no associative +# arrays, no mapfile, no jq, no python. + +set -uo pipefail + +usage() { + cat <<'EOF' +check-retirements.sh — detect and clean a plugin's retired conventions. + +Evaluates every record of a retirements.yaml against a consumer repository and +prints one TSV row per leftover: + + idkindpathactionstatusnote + +Usage: + check-retirements.sh --manifest [--root ] + check-retirements.sh --manifest --clean [--i-migrated] [--root ] + check-retirements.sh --help + + --manifest the plugin's retirements.yaml + --root consumer repository root; defaults to ${CLAUDE_PROJECT_DIR}, + else the git toplevel, else the current directory + --clean clean exactly that record's artifact instead of detecting + --i-migrated required with --clean on a migrate record: states that the + successor prose was followed, so the artifact may go + +Exit (detect): 0 no active leftover; 1 at least one active leftover; 2 usage, + unreadable manifest, or an invalid record (the whole run fails). +Exit (clean): 0 cleaned; 1 nothing present to clean; 2 error. + +At $HOME or outside a git work tree, kind file records are skipped (stderr: +`: skipped: root is not a repository`) and --clean refuses them. +EOF +} + +die() { + echo "ERROR: $*" >&2 + exit 2 +} + +MANIFEST="" +ROOT_ARG="" +CLEAN_ID="" +I_MIGRATED=0 +while [[ $# -gt 0 ]]; do + case "$1" in + -h | --help) + usage + exit 0 + ;; + --manifest) + [[ $# -ge 2 ]] || die "--manifest needs a path" + MANIFEST="$2" + shift 2 + ;; + --root) + [[ $# -ge 2 ]] || die "--root needs a path" + ROOT_ARG="$2" + shift 2 + ;; + --clean) + [[ $# -ge 2 ]] || die "--clean needs a record id" + CLEAN_ID="$2" + shift 2 + ;; + --i-migrated) + I_MIGRATED=1 + shift + ;; + *) + echo "ERROR: unknown argument: $1" >&2 + usage >&2 + exit 2 + ;; + esac +done + +[[ -n "$MANIFEST" ]] || die "--manifest is required (see --help)" +[[ -f "$MANIFEST" && -r "$MANIFEST" ]] || die "manifest is not a readable file: $MANIFEST" +[[ $I_MIGRATED -eq 0 || -n "$CLEAN_ID" ]] || die "--i-migrated only makes sense with --clean " + +if [[ -n "$ROOT_ARG" ]]; then + ROOT="$ROOT_ARG" +elif [[ -n "${CLAUDE_PROJECT_DIR:-}" ]]; then + ROOT="$CLAUDE_PROJECT_DIR" +else + # tr -d '\r': Git on Windows can return a CRLF-terminated path. + ROOT=$(git rev-parse --show-toplevel 2>/dev/null | tr -d '\r') + [[ -n "$ROOT" ]] || ROOT="$PWD" +fi +[[ -d "$ROOT" ]] || die "--root is not a directory: $ROOT" +ROOT="${ROOT%/}" + +# ROOT_IS_REPO=0 at $HOME or outside a git work tree: kind file records are +# skipped there (see NON-REPOSITORY ROOT above). +# A `.git` at the root also counts: git may be missing, or refuse a repository +# another user owns ("dubious ownership"), and a skip there would read as PASS. +ROOT_IS_REPO=1 +real_root_dir=$(CDPATH='' cd -- "$ROOT" 2>/dev/null && pwd -P) +real_home_dir="" +[[ -n "${HOME:-}" ]] && real_home_dir=$(CDPATH='' cd -- "$HOME" 2>/dev/null && pwd -P) +if [[ -n "$real_home_dir" && "$real_root_dir" == "$real_home_dir" ]]; then + ROOT_IS_REPO=0 +elif [[ ! -e "$ROOT/.git" ]] && + [[ "$(git -C "$ROOT" rev-parse --is-inside-work-tree 2>/dev/null | tr -d '\r')" != "true" ]]; then + ROOT_IS_REPO=0 +fi +NOT_REPO_REASON="skipped: root is not a repository" + +# --------------------------------------------------------------------------- +# Manifest parsing — every record is validated before anything is evaluated. +# Parallel indexed arrays rather than one associative array per record: the +# helper has to run on the bash 3.2 that stock macOS ships. +# --------------------------------------------------------------------------- + +REC_ID=() +REC_KIND=() +REC_PATH=() +REC_MATCH=() +REC_HEADING=() +REC_CONTENT_MATCH=() +REC_ACTION=() +REC_SUCCESSOR=() +REC_NOTE=() +REC_STATUS=() +REC_COUNT=0 +SEEN_IDS=" +" + +# Built without backslash-bearing literals: shellcheck's SC1003 fires on every +# spelling of one inside quotes. +BACKSLASH=$(printf '%b' '\134') +TAB=$(printf '\t') + +# ere_valid — 0 when grep -E accepts the pattern. grep exits 2 on a +# malformed expression and 1 on the (expected) no-match against empty input. +ere_valid() { + local rc=0 + grep -E -e "$1" /dev/null 2>&1 || rc=$? + [[ $rc -ne 2 ]] +} + +# Current record's fields: reset_record initializes them before the first line +# is read and resets them at each `---`. +reset_record() { + r_start=$1 + r_id="" r_retired="" r_plugin_version="" r_kind="" r_path="" r_match="" + r_heading="" r_content_match="" r_action="" r_successor="" r_note="" r_status="" + r_keys=" " + r_nonempty=0 +} + +# record_label — how a validation message names the record being checked. +record_label() { + if [[ -n "$r_id" ]]; then + printf 'record %d (id: %s, line %d)' "$((REC_COUNT + 1))" "$r_id" "$r_start" + else + printf 'record %d (line %d)' "$((REC_COUNT + 1))" "$r_start" + fi +} + +bad_record() { + echo "ERROR: $MANIFEST: $(record_label): $1" >&2 + exit 2 +} + +# invalid +invalid() { bad_record "field '$1' $2"; } + +# strip_quotes — remove one layer of matching single or double quotes. +# Each pattern needs both quote characters, so a value that matches is always +# at least two characters long. +strip_quotes() { + local v="$1" + case "$v" in + \'*\') + v="${v#\'}" + v="${v%\'}" + ;; + \"*\") + v="${v#\"}" + v="${v%\"}" + ;; + *) ;; + esac + printf '%s' "$v" +} + +finish_record() { + [[ $r_nonempty -eq 1 ]] || return 0 + + [[ -n "$r_id" ]] || invalid id "is required" + grep -Eq '^[a-z0-9]([a-z0-9-]*[a-z0-9])?-r[0-9]{3,}$' <<<"$r_id" || + invalid id "must be -rNNN: '$r_id'" + case "$SEEN_IDS" in + *" +$r_id +"*) invalid id "duplicates an earlier record's id: '$r_id'" ;; + *) ;; + esac + SEEN_IDS="${SEEN_IDS}${r_id} +" + + [[ -n "$r_retired" ]] || invalid retired "is required" + grep -Eq '^[0-9]{4}-[0-9]{2}-[0-9]{2}$' <<<"$r_retired" || + invalid retired "must be YYYY-MM-DD: '$r_retired'" + + [[ -n "$r_plugin_version" ]] || invalid plugin_version "is required" + grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$' <<<"$r_plugin_version" || + invalid plugin_version "must be semver: '$r_plugin_version'" + + case "$r_kind" in + file | dir | line | block) ;; + "") invalid kind "is required" ;; + *) invalid kind "must be file, dir, line or block: '$r_kind'" ;; + esac + + [[ -n "$r_path" ]] || invalid path "is required" + case "$r_path" in + /*) invalid path "must be repo-relative, not absolute: '$r_path'" ;; + [A-Za-z]:*) invalid path "must be repo-relative, not a drive path: '$r_path'" ;; + '~'*) invalid path "must not start with ~: '$r_path'" ;; + *"$BACKSLASH"*) invalid path "must use forward slashes: '$r_path'" ;; + *"$TAB"*) invalid path "must not contain a tab: '$r_path'" ;; + . | ./ | ./. | */. | */./ | *//*) invalid path "must name a file or directory inside the repo, not the repo itself: '$r_path'" ;; + *) ;; + esac + grep -Eq '(^|/)\.\.(/|$)' <<<"$r_path" && + invalid path "must not contain a .. segment: '$r_path'" + + if [[ "$r_kind" == "line" || "$r_kind" == "block" ]]; then + [[ -n "$r_match" ]] || invalid match "is required for kind $r_kind" + ere_valid "$r_match" || invalid match "is not a valid POSIX ERE: '$r_match'" + elif [[ -n "$r_match" ]]; then + invalid match "is only allowed for kind line or block (kind is $r_kind)" + fi + + if [[ -n "$r_heading" ]]; then + [[ "$r_kind" == "line" ]] || invalid heading "is only allowed for kind line (kind is $r_kind)" + grep -Eq '^#{1,6}[[:space:]]+[^[:space:]]' <<<"$r_heading" || + invalid heading "must be an ATX heading (1-6 hashes, whitespace, title): '$r_heading'" + fi + + if [[ -n "$r_content_match" ]]; then + [[ "$r_kind" == "file" ]] || invalid content_match "is only allowed for kind file (kind is $r_kind)" + ere_valid "$r_content_match" || invalid content_match "is not a valid POSIX ERE: '$r_content_match'" + fi + + case "$r_action" in + delete) + [[ "$r_kind" != "line" ]] || invalid action "delete is not allowed for kind line (use remove-line)" + [[ "$r_kind" != "block" ]] || invalid action "kind block takes only migrate (action is delete)" + ;; + remove-line) + [[ "$r_kind" == "line" ]] || invalid action "remove-line requires kind line (kind is $r_kind)" + ;; + migrate) + [[ -n "$r_successor" ]] || invalid successor "is required for action migrate" + ;; + "") invalid action "is required" ;; + *) invalid action "must be delete, remove-line or migrate: '$r_action'" ;; + esac + + [[ -n "$r_note" ]] || invalid note "is required" + [[ "$r_note" != *"$TAB"* ]] || invalid note "must not contain a tab" + + case "$r_status" in + "") r_status="active" ;; + active | report-only) ;; + *) invalid status "must be active or report-only: '$r_status'" ;; + esac + + REC_ID[REC_COUNT]="$r_id" + REC_KIND[REC_COUNT]="$r_kind" + REC_PATH[REC_COUNT]="$r_path" + REC_MATCH[REC_COUNT]="$r_match" + REC_HEADING[REC_COUNT]="$r_heading" + REC_CONTENT_MATCH[REC_COUNT]="$r_content_match" + REC_ACTION[REC_COUNT]="$r_action" + REC_SUCCESSOR[REC_COUNT]="$r_successor" + REC_NOTE[REC_COUNT]="$r_note" + REC_STATUS[REC_COUNT]="$r_status" + REC_COUNT=$((REC_COUNT + 1)) +} + +lineno=0 +reset_record 1 +while IFS= read -r line || [[ -n "$line" ]]; do + lineno=$((lineno + 1)) + line="${line%$'\r'}" + if [[ "$line" == --- ]]; then + finish_record + reset_record $((lineno + 1)) + continue + fi + # Leading whitespace only ever precedes a comment or nothing in a flat + # manifest; anything else is a nesting attempt and is rejected below. + case "${line#"${line%%[![:space:]]*}"}" in + "" | \#*) continue ;; + *) ;; + esac + [[ "$line" =~ ^([a-z_]+):[[:space:]]*(.*)$ ]] || + bad_record "line $lineno is not 'key: value': $line" + key="${BASH_REMATCH[1]}" + value="${BASH_REMATCH[2]}" + value="${value%"${value##*[![:space:]]}"}" + value="$(strip_quotes "$value")" + r_nonempty=1 + [[ "$r_keys" != *" $key "* ]] || invalid "$key" "is set twice (line $lineno)" + r_keys="${r_keys}${key} " + case "$key" in + id) r_id="$value" ;; + retired) r_retired="$value" ;; + plugin_version) r_plugin_version="$value" ;; + kind) r_kind="$value" ;; + path) r_path="$value" ;; + match) r_match="$value" ;; + heading) r_heading="$value" ;; + content_match) r_content_match="$value" ;; + action) r_action="$value" ;; + successor) r_successor="$value" ;; + note) r_note="$value" ;; + status) r_status="$value" ;; + *) invalid "$key" "is not part of the schema (line $lineno)" ;; + esac +done <"$MANIFEST" +finish_record + +# --------------------------------------------------------------------------- +# Detection primitives +# --------------------------------------------------------------------------- + +# content_hits — 0 when some line of , its trailing CR +# stripped, matches . grep is used WITHOUT -q so it drains the pipe: under +# pipefail an early-closing grep would turn awk's SIGPIPE into a failed test. +content_hits() { + awk '{ sub(/\r$/, ""); print }' "$1" | grep -E -e "$2" >/dev/null +} + +# section_body_nrs — one 1-based line number per line that +# sits in the body of every markdown section whose heading line equals +# (trailing whitespace ignored on both sides). The heading line +# itself is excluded. A section ends at the next ATX heading of the same or +# higher level, or EOF. POSIX awk only: no interval quantifiers. +section_body_nrs() { + awk -v heading="$2" ' + function rtrim(s) { + sub(/[ \t]+$/, "", s) + return s + } + function atx_level(s, n) { + n = 0 + while (substr(s, n + 1, 1) == "#") n++ + if (n >= 1 && n <= 6 && substr(s, n + 1, 1) ~ /[ \t]/) return n + return 0 + } + { + sub(/\r$/, "") + trimmed = rtrim($0) + if (in_section) { + lvl = atx_level(trimmed) + if (lvl > 0 && lvl <= start_level) in_section = 0 + } + if (in_section == 0 && trimmed == heading) { + in_section = 1 + start_level = atx_level(trimmed) + if (start_level == 0) start_level = 6 + next + } + if (in_section) print NR + } + ' "$1" +} + +# matching_line_nrs [heading] — space-separated 1-based line +# numbers whose text (CR stripped) matches . When is non-empty, +# only lines inside that heading's section body. +matching_line_nrs() { + local file="$1" ere="$2" heading="${3:-}" all scoped n + all=$(awk '{ sub(/\r$/, ""); print }' "$file" | grep -E -n -e "$ere" | cut -d: -f1 | tr '\n' ' ') + if [[ -z "$heading" ]]; then + printf '%s' "$all" + return + fi + scoped=$(section_body_nrs "$file" "$heading" | tr '\n' ' ') + for n in $all; do + case " $scoped " in + *" $n "*) printf '%s ' "$n" ;; + *) ;; + esac + done +} + +# block_line_nrs — space-separated line numbers of every +# block that starts at one of : the start line, then each following +# line (CR stripped) that is blank, indented deeper than the start line, or a +# `-` sequence item at the start line's own indent (YAML lets a key's sequence +# sit there), ending before the first other non-blank line indented no deeper. +block_line_nrs() { + awk -v starts=" $2" ' + { sub(/\r$/, "") } + index(starts, " " NR " ") > 0 { match($0, /^[ \t]*/); indent = RLENGTH; inside = 1; printf "%d ", NR; next } + inside && $0 ~ /^[ \t]*$/ { printf "%d ", NR; next } + inside { + match($0, /^[ \t]*/) + if (RLENGTH > indent || (RLENGTH == indent && substr($0, indent + 1) ~ /^-([ \t]|$)/)) { printf "%d ", NR; next } + inside = 0 + } + ' "$1" +} + +# A linked worktree's .git is a file, and git's shared files (hooks among them) +# sit in the main checkout's git dir, so there a `.git/` record path resolves +# under `git rev-parse --git-common-dir`. Empty in a normal checkout. +COMMON_DIR="" +if [[ -f "$ROOT/.git" ]]; then + COMMON_DIR=$(git -C "$ROOT" rev-parse --git-common-dir 2>/dev/null | tr -d '\r') + case "$COMMON_DIR" in + "" | /* | [A-Za-z]:*) ;; + *) COMMON_DIR="$ROOT/$COMMON_DIR" ;; + esac + COMMON_DIR="${COMMON_DIR%/}" +fi + +# target_base — the directory a record path resolves under: the common +# git dir for a `.git/` path in a linked worktree, else ROOT. target_of +# — the path on disk. +target_base() { + if [[ -n "$COMMON_DIR" && "$1" == .git/* ]]; then + printf '%s' "$COMMON_DIR" + else + printf '%s' "$ROOT" + fi +} +target_of() { + if [[ -n "$COMMON_DIR" && "$1" == .git/* ]]; then + printf '%s/%s' "$COMMON_DIR" "${1#.git/}" + else + printf '%s/%s' "$ROOT" "$1" + fi +} + +# present — 0 when record 's artifact is present in ROOT. +present() { + local i="$1" target nrs + target=$(target_of "${REC_PATH[$i]}") + case "${REC_KIND[$i]}" in + file) + [[ -f "$target" ]] || return 1 + [[ -z "${REC_CONTENT_MATCH[$i]}" ]] && return 0 + content_hits "$target" "${REC_CONTENT_MATCH[$i]}" + ;; + dir) + [[ -d "$target" ]] + ;; + line | block) + [[ -f "$target" ]] || return 1 + nrs=$(matching_line_nrs "$target" "${REC_MATCH[$i]}" "${REC_HEADING[$i]}") + [[ -n "${nrs// /}" ]] + ;; + *) return 1 ;; + esac +} + +# --------------------------------------------------------------------------- +# Detect mode +# --------------------------------------------------------------------------- + +if [[ -z "$CLEAN_ID" ]]; then + active_hits=0 + report_only_hits=0 + skipped=0 + i=0 + while [[ $i -lt $REC_COUNT ]]; do + if [[ $ROOT_IS_REPO -eq 0 && "${REC_KIND[$i]}" == "file" ]]; then + echo "check-retirements: ${REC_ID[$i]}: $NOT_REPO_REASON" >&2 + skipped=$((skipped + 1)) + elif present "$i"; then + printf '%s\t%s\t%s\t%s\t%s\t%s\n' \ + "${REC_ID[$i]}" "${REC_KIND[$i]}" "${REC_PATH[$i]}" \ + "${REC_ACTION[$i]}" "${REC_STATUS[$i]}" "${REC_NOTE[$i]}" + if [[ "${REC_STATUS[$i]}" == "active" ]]; then + active_hits=$((active_hits + 1)) + else + report_only_hits=$((report_only_hits + 1)) + fi + fi + i=$((i + 1)) + done + skipped_note="" + [[ $skipped -eq 0 ]] || skipped_note=", $skipped skipped" + echo "check-retirements: $MANIFEST: $REC_COUNT record(s) evaluated against $ROOT — $active_hits active leftover(s), $report_only_hits report-only${skipped_note}." >&2 + [[ $active_hits -eq 0 ]] && exit 0 + exit 1 +fi + +# --------------------------------------------------------------------------- +# Clean mode +# --------------------------------------------------------------------------- + +idx=-1 +i=0 +while [[ $i -lt $REC_COUNT ]]; do + if [[ "${REC_ID[$i]}" == "$CLEAN_ID" ]]; then + idx=$i + break + fi + i=$((i + 1)) +done +[[ $idx -ge 0 ]] || die "$MANIFEST has no record with id '$CLEAN_ID'" + +kind="${REC_KIND[$idx]}" +path="${REC_PATH[$idx]}" +action="${REC_ACTION[$idx]}" +target=$(target_of "$path") +base=$(target_base "$path") + +[[ $ROOT_IS_REPO -eq 1 || "$kind" != "file" ]] || + die "$CLEAN_ID: refusing to clean $path — $NOT_REPO_REASON ($ROOT); there it can be a live user-global file" + +if [[ "$action" == "migrate" && $I_MIGRATED -eq 0 ]]; then + echo "ERROR: $CLEAN_ID is a migrate record: its content must be carried over before the artifact goes." >&2 + echo " successor: ${REC_SUCCESSOR[$idx]}" >&2 + echo " Re-run with --i-migrated once that is done." >&2 + exit 2 +fi + +locked_hint="re-run after closing the file (on Windows a locked file makes the remove fail; nothing was changed)" + +# File and line cleanup share this: a syntactically clean repo-relative path can +# still walk a symlink parent out of its base (ROOT, or the common git dir). +# Re-resolve at the moment of use. +assert_target_inside_root() { + local real_root real_parent + real_root=$(cd "$base" 2>/dev/null && pwd -P) || die "cannot resolve root: $base" + real_parent=$(cd "$(dirname -- "$target")" 2>/dev/null && pwd -P) || die "cannot resolve $path" + case "$real_parent" in + "$real_root" | "$real_root"/*) ;; + *) die "refusing to remove $path — it resolves outside the repository root ($real_parent)" ;; + esac +} + +if ! present "$idx"; then + if [[ "$kind" == "file" && -f "$target" && -n "${REC_CONTENT_MATCH[$idx]}" ]]; then + echo "check-retirements: $CLEAN_ID: $path exists but its content no longer matches the record — the path is in use by something else; nothing to clean." >&2 + else + echo "check-retirements: $CLEAN_ID: nothing present at $path to clean." >&2 + fi + exit 1 +fi + +case "$kind" in +file) + assert_target_inside_root + rm -f "$target" || die "could not remove $path — $locked_hint" + echo "check-retirements: $CLEAN_ID: removed $path." >&2 + exit 0 + ;; +dir) + # rm -rf is the one thing here that can do real damage, so the path is + # re-resolved at the moment of use: it must land strictly inside its base + # and must not be the base itself, whatever the manifest text said. + real_root=$(cd "$base" 2>/dev/null && pwd -P) || die "cannot resolve root: $base" + real_target=$(cd "$target" 2>/dev/null && pwd -P) || die "cannot resolve $path" + [[ "$real_target" != "$real_root" ]] || die "refusing to remove $path — it resolves to the repository root" + case "$real_target" in + "$real_root"/*) ;; + *) die "refusing to remove $path — it resolves outside the repository root ($real_target)" ;; + esac + rm -rf "$target" || die "could not remove directory $path — $locked_hint" + echo "check-retirements: $CLEAN_ID: removed directory $path." >&2 + exit 0 + ;; +line | block) + assert_target_inside_root + match="${REC_MATCH[$idx]}" + # Which input lines match, by number, decided once by grep -E (the same ERE + # dialect detection used); when heading is set, only section-body hits + # count, and for a block each hit widens to its whole block. awk then copies + # every other line through with its own bytes, CR included. Only the matched + # lines' text is stripped of the CR, and only for the comparison. + matched_lines=$(matching_line_nrs "$target" "$match" "${REC_HEADING[$idx]}") + [[ -n "$matched_lines" ]] || { + echo "check-retirements: $CLEAN_ID: no line of $path matches; nothing to clean." >&2 + exit 1 + } + [[ "$kind" == "line" ]] || matched_lines=$(block_line_nrs "$target" "$matched_lines") + # Whether the original's last line carries a newline: `tail -c 1` prints the + # final byte and command substitution eats a trailing newline, so an empty + # result means the file ended with one. + ends_with_newline=1 + [[ -z "$(tail -c 1 "$target")" ]] || ends_with_newline=0 + dir=$(dirname "$target") + tmp=$(mktemp "$dir/.check-retirements.XXXXXX") || die "could not create a temp file beside $path" + # cp -p so the rewritten file keeps the original's mode; the content is + # replaced by the redirect below. + cp -p "$target" "$tmp" 2>/dev/null || true + if ! awk -v skip=" $matched_lines" -v nl="$ends_with_newline" ' + { if (index(skip, " " NR " ") > 0) next; kept[++k] = $0; at[k] = NR } + END { + for (i = 1; i <= k; i++) { + printf "%s", kept[i] + # Every line but the original last one had a newline after it; the + # last one had it only if the file did. + if (at[i] < NR || nl) printf "\n" + } + }' "$target" >"$tmp"; then + rm -f "$tmp" + die "could not rewrite $path — $locked_hint" + fi + if ! mv -f "$tmp" "$target"; then + rm -f "$tmp" + die "could not replace $path with the rewritten file — $locked_hint" + fi + removed=$(printf '%s' "$matched_lines" | wc -w | tr -d ' ') + if [[ "$kind" == "block" ]] && ! grep -q '[^[:space:]]' "$target"; then + rm -f "$target" || die "could not remove $path, left with no content — $locked_hint" + echo "check-retirements: $CLEAN_ID: removed $removed line(s) from $path, then the file, which held nothing else." >&2 + exit 0 + fi + echo "check-retirements: $CLEAN_ID: removed $removed line(s) from $path." >&2 + exit 0 + ;; +*) die "unreachable kind: $kind" ;; +esac diff --git a/plugins/improvement/reference/config.md b/plugins/improvement/reference/config.md index aa1290b82f3..f6dd6a2bfb3 100644 --- a/plugins/improvement/reference/config.md +++ b/plugins/improvement/reference/config.md @@ -1,29 +1,72 @@ # improvement: consumer configuration -The single home for the `improvement` plugin's config-key contract. The surface is -`.claude/improvement.md`, layered per the marketplace's config-cascade convention. It is read by -`/improvement:find` for Tier 2 evidence-source resolution, the hotspot recipe's churn window and -exclusion patterns, and the unattended run controls, and verified/written by `/improvement:setup`. All layers are optional: -**zero config is a fully working state**. Tier 0 repo-native evidence needs nothing declared, and -an absent Tier 2 declaration is a recorded evidence gap in the finder's report, never an error. +The single home for the `improvement` plugin's config-key contract. The surface resolves through +the four layers of the marketplace's +[config-cascade contract](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#the-layers). +It is read by `/improvement:find` for Tier 2 evidence-source resolution, the hotspot recipe's +churn window and exclusion patterns, and the unattended run controls, and verified/written by +`/improvement:setup`. All layers are optional: **zero config is a fully working state**. Tier 0 +repo-native evidence needs nothing declared, and an absent Tier 2 declaration is a recorded +evidence gap in the finder's report, never an error. ## Layers and resolution order -Three layers, resolved in this order, where a later layer refines an earlier one: +Four layers, lowest first, where a later layer refines an earlier one: -| Order | Layer | Path | Version control | +| Order | Layer | Source | Version control | |---|---|---|---| -| 1 | user-global | `~/.claude/improvement.md`: one Read of that literal path, `~` kept; never Glob for it, spell out a home directory, or search the home tree | outside the worktree, so no git verdict applies | -| 2 | team (tracked) | `${CLAUDE_PROJECT_DIR}/.claude/improvement.md` | must be tracked, the only layer teammates receive | -| 3 | personal override | `${CLAUDE_PROJECT_DIR}/.claude/improvement.local.md` | must be gitignored, never staged | - -This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](config-locations.md) says. - -Resolution anchors at the repo root, `${CLAUDE_PROJECT_DIR}` when set and otherwise -`git rev-parse --show-toplevel`, never at the CWD. Every layer that exists is read and merged; -reading one layer and stopping is not resolution. A malformed layer degrades soft: surface the -error, name the layer, resolve as if that layer were absent. Unknown keys are inert. Whenever the -effective config is surfaced to a human, report which layer supplied each value. +| 0 | plugin default | the Default column of [Keys](#keys) | n/a | +| 1 | `userConfig` | the plugin's `userConfig` option for the key ([userConfig options](#userconfig-options)), per person, across repositories | outside the worktree, so no git verdict applies | +| 2 | team | `/improvement.yaml`, validated by [`schemas/improvement.schema.json`](../schemas/improvement.schema.json) | must be tracked, the only layer teammates receive | +| 3 | personal | `/improvement.local.yaml`, same schema | must be gitignored, never staged | + +`` is the convention home the pointer region of `AGENTS.md` or `CLAUDE.md` binds, else +`docs/conventions` ([config locations](config-locations.md)). Resolution anchors at the repository +root (``), `git rev-parse --show-toplevel`, never at the CWD; `` is relative to it. When that root is `$HOME`, an ancestor of +`$HOME`, or not inside a git working tree, the team and personal layers are not applicable: report +both with that reason and resolve the default and `userConfig` only. + +Every layer that exists is read and merged; reading one layer and stopping is not resolution. A +malformed layer degrades soft: name the file, key and value, and resolve as if that layer were +absent, so a valid higher layer still wins, otherwise the default. Unknown keys are inert. Whenever +the effective config is surfaced to a human, report which layer supplied each value. + +### userConfig options + +Each key in [Keys](#keys) has a `userConfig` option of the same name, except `evidence_sources`: +a nested map that `userConfig` cannot hold, so its option is `evidence_sources_file`, a `file` +option naming a YAML file of the user's whose top-level `evidence_sources` key has the shape below. +The options have no manifest default: an option that reads empty, or still reads as a literal +`${user_config.…}` placeholder, is unset and supplies nothing. `${user_config.KEY}` is substituted +only in skill content, so each skill that reads this surface carries the option values in its own +`SKILL.md`. Values are set through Claude Code's plugin configuration +(`/plugin configure improvement@`); no skill writes `pluginConfigs` or user settings. + +## Old locations (dual-read window) + +Before this surface adopted the four layers it read three other files. While one of them exists, +it is still read, and a run that finds one prints **one** warning line naming each old file found, +the location to move it to, and `/improvement:setup apply`, which moves it: + +| Old path | Read as | Moves to | +|---|---|---| +| `~/.claude/improvement.md`: one Read of that literal path, `~` kept; never Glob for it, spell out a home directory, or search the home tree | the `userConfig` layer, for each key whose option is unset | the `userConfig` options ([userConfig options](#userconfig-options)) | +| `/.claude/improvement.md` | the team layer, when `/improvement.yaml` is absent | `/improvement.yaml` | +| `/.claude/improvement.local.md` | the personal layer, when `/improvement.local.yaml` is absent | `/improvement.local.yaml` | + +An old file uses the old format: Markdown holding one fenced `yaml` block with the keys below. When +the new location also supplies that layer, the new one wins, and the warning lists each key the old +file sets that therefore does not apply, so no old setting is dropped silently: for the team and +personal files it names both files; for `~/.claude/improvement.md` it names the options already +set. The old team and personal files take the root rule and the tracked and ignored verdicts of the +layer they stand in for, so at a root that is `$HOME` they are not read as team or personal layers. + +The repository-scope window is declared by the plugin's retirement records, +[`retirements.yaml`](../retirements.yaml): `improvement-r001` (`.claude/improvement.md`) and +`improvement-r002` (`.claude/improvement.local.md`), both `migrate`, evaluated by +`lib/check-retirements.sh` from `/improvement:setup`. `~/.claude/improvement.md` is machine scope, +outside that mechanism, so setup detects it with its own Read. Removing these reads is a separate +later change (demoting the records to `report-only`), made once no run reports an old file. ## Merge semantics @@ -34,7 +77,7 @@ refinements and one ceiling.** `find_open_item_cap`): a later layer replaces the value key by key; a key absent from a later layer keeps the earlier layer's value. - **`find_open_item_cap`** is a ceiling personal settings can only lower. The team layer's value, - else the bundled default, sets it. The user-global and personal override layers each apply only + else the bundled default, sets it. The `userConfig` and personal layers each apply only when lower, so the effective cap is the smallest of the three. A higher personal value is ignored and reported. - **`churn_exclude`**: entries **union** across layers, and with the mechanical files resolved from @@ -48,11 +91,8 @@ Wholesale replacement of an earlier layer is forbidden. ## File format -Markdown with a fenced YAML block (human-readable, shell-greppable). Prose outside the block is -the consumer's own commentary and is not parsed. - -````markdown -# improvement config +The team and personal files are plain YAML. The `evidence_sources_file` a `userConfig` option names +holds only the `evidence_sources` key, in the same shape. ```yaml churn_window: "90 days ago" @@ -74,7 +114,6 @@ evidence_sources: scope: production web tier hints: start with request failure rate and p95 latency ``` -```` ## Keys @@ -111,12 +150,12 @@ hard error and never a fabricated reading. ## Consumer `.gitignore` -This recursive line ignores the personal override this plugin reads today, -`.claude/improvement.local.md`. A personal override at `` needs `/**/*.local.*` -instead; see [config locations](config-locations.md). +This recursive line ignores the personal file, written out for the default home: ```gitignore -.claude/**/*.local.* +docs/conventions/**/*.local.* ``` -`/improvement:setup` recommends this line; no plugin writes the consumer's `.gitignore`. +Write the bound `` in place of `docs/conventions`. While an old +`.claude/improvement.local.md` exists, `.claude/**/*.local.*` keeps it ignored. +`/improvement:setup` recommends these lines; no plugin writes the consumer's `.gitignore`. diff --git a/plugins/improvement/retirements.yaml b/plugins/improvement/retirements.yaml new file mode 100644 index 00000000000..a86cb70ae3b --- /dev/null +++ b/plugins/improvement/retirements.yaml @@ -0,0 +1,25 @@ +# Retired consumer-facing conventions for the improvement plugin. +# Append-only: records are never deleted and their detection fields are never +# edited once published (demote with `status: report-only` instead). Schema and +# helper contract: docs/contracts/retired-conventions/README.md in the +# consuming marketplace; evaluated by lib/check-retirements.sh from setup. +--- +id: improvement-r001 +retired: 2026-11-22 +plugin_version: 0.9.0 +kind: file +path: .claude/improvement.md +content_match: '^[[:space:]]*(churn_window|churn_exclude|churn_exclude_defaults|find_[a-z_]+|evidence_sources):' +action: migrate +successor: "the team layer moved to /improvement.yaml (reference/config.md): carry every key of the old file's fenced yaml block into that file as plain YAML, keeping any key the new file already sets, resolve the team layer from the new file alone and confirm each moved key resolves the old value, have the operator confirm, then clean" +note: "old team config file; values move to /improvement.yaml" +--- +id: improvement-r002 +retired: 2026-11-22 +plugin_version: 0.9.0 +kind: file +path: .claude/improvement.local.md +content_match: '^[[:space:]]*(churn_window|churn_exclude|churn_exclude_defaults|find_[a-z_]+|evidence_sources):' +action: migrate +successor: "the personal layer moved to /improvement.local.yaml (reference/config.md): confirm git check-ignore covers that path first, carry every key of the old file's fenced yaml block into it as plain YAML, keeping any key the new file already sets, resolve the personal layer from the new file alone and confirm each moved key resolves the old value, have the operator confirm, then clean" +note: "old personal config file; values move to /improvement.local.yaml" diff --git a/plugins/improvement/schemas/improvement.schema.json b/plugins/improvement/schemas/improvement.schema.json new file mode 100644 index 00000000000..ac64d92be32 --- /dev/null +++ b/plugins/improvement/schemas/improvement.schema.json @@ -0,0 +1,94 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/plugins/improvement/schemas/improvement.schema.json", + "title": "Improvement team config", + "description": "Schema for /improvement.yaml and /improvement.local.yaml: the keys /improvement:find and /improvement:setup read through the four config-cascade layers. Key contract and merge semantics: plugins/improvement/reference/config.md.", + "type": "object", + "additionalProperties": false, + "properties": { + "$schema": { "type": "string" }, + "churn_window": { + "description": "The hotspot recipe's change-frequency window, a value git log --since accepts.", + "type": "string", + "minLength": 1, + "default": "90 days ago" + }, + "churn_exclude": { + "description": "Extra ERE patterns excluded from churn counting. Unioned across layers.", + "type": "array", + "items": { "type": "string", "minLength": 1 }, + "default": [] + }, + "churn_exclude_defaults": { + "description": "false drops the mechanical-file exclusions resolved from the repository, leaving only declared patterns.", + "type": "boolean", + "default": true + }, + "find_open_item_cap": { + "description": "Per source label: unattended /improvement:find files nothing while the open items carrying it number at or above this. The personal file can only lower it.", + "type": "integer", + "minimum": 0, + "default": 5 + }, + "find_run_item_cap": { + "description": "Where the adaptive per-run filing cap starts.", + "type": "integer", + "minimum": 1, + "default": 3 + }, + "find_run_item_cap_floor": { + "description": "Lowest value the per-run filing cap adapts to.", + "type": "integer", + "minimum": 1, + "default": 1 + }, + "find_run_item_cap_ceiling": { + "description": "Highest value the per-run filing cap adapts to.", + "type": "integer", + "minimum": 1, + "default": 5 + }, + "find_size_band": { + "description": "The candidate sizes an unattended run ranks.", + "enum": ["all", "small", "medium", "large"], + "default": "all" + }, + "find_scope": { + "description": "What an unattended run scans: repo, or a target /improvement:find accepts.", + "type": "string", + "minLength": 1, + "default": "repo" + }, + "find_suppress_dismissed": { + "description": "Whether an unattended run suppresses candidates an operator dismissed before.", + "type": "boolean", + "default": true + }, + "evidence_sources": { + "description": "Tier 2 application-telemetry declarations, one entry per source name. A null or empty entry in a later layer removes the inherited source.", + "type": "object", + "additionalProperties": { + "oneOf": [ + { "type": "null" }, + { + "type": "object", + "additionalProperties": false, + "maxProperties": 0 + }, + { + "type": "object", + "additionalProperties": false, + "required": ["mcp_server"], + "properties": { + "mcp_server": { "type": "string", "minLength": 1, "description": "The MCP server as named in the consumer's own MCP configuration." }, + "kind": { "enum": ["metrics", "logs", "errors", "traces", "events"] }, + "scope": { "type": "string", "description": "The product surface the source covers." }, + "hints": { "type": "string", "description": "Where to start: key queries, dashboards, or tables worth reading first." } + } + } + ] + }, + "default": {} + } + } +} diff --git a/plugins/improvement/skills/find/SKILL.md b/plugins/improvement/skills/find/SKILL.md index f836fe6d595..11d0f7bfed9 100644 --- a/plugins/improvement/skills/find/SKILL.md +++ b/plugins/improvement/skills/find/SKILL.md @@ -129,10 +129,36 @@ Two hard rules follow: - **Tier 1. Local Claude Code telemetry.** When `harness-ops:observability` is enabled, consult it for session/cost/hook telemetry relevant to the operational-setup dimension. - **Tier 2. Configured application telemetry.** Whatever MCP telemetry sources the consumer - declares through the `.claude/improvement.md` config cascade (team file + `.local` personal override + - user-global; key contract in the plugin's reference/config.md). Never hardcode a vendor; if no - source is configured, Tier 2 is an evidence gap, and product-level candidates fall back down the - ladder. + declares through the config cascade ([Configuration](#configuration)). Never hardcode a vendor; + if no source is configured, Tier 2 is an evidence gap, and product-level candidates fall back + down the ladder. + +## Configuration + +The churn keys, the unattended controls and the Tier 2 sources resolve through the layers in +`${CLAUDE_PLUGIN_ROOT}/reference/config.md` (one Read of that file): plugin default, `userConfig`, +the team `/improvement.yaml`, then the personal `/improvement.local.yaml`, with that +file's merge semantics, root rule and dual-read window. While an old file +(`~/.claude/improvement.md`, `.claude/improvement.md` or `.claude/improvement.local.md`) exists, +read it as that file says and print its one warning line in the run's output, naming each old +file, its new location and `/improvement:setup apply`. + +The `userConfig` layer, as substituted into this skill (empty, or a literal `${user_config.…}` +placeholder, means unset): + +| Option | Value | +|---|---| +| `churn_window` | `${user_config.churn_window}` | +| `churn_exclude` | `${user_config.churn_exclude}` | +| `churn_exclude_defaults` | `${user_config.churn_exclude_defaults}` | +| `find_open_item_cap` | `${user_config.find_open_item_cap}` | +| `find_run_item_cap` | `${user_config.find_run_item_cap}` | +| `find_run_item_cap_floor` | `${user_config.find_run_item_cap_floor}` | +| `find_run_item_cap_ceiling` | `${user_config.find_run_item_cap_ceiling}` | +| `find_size_band` | `${user_config.find_size_band}` | +| `find_scope` | `${user_config.find_scope}` | +| `find_suppress_dismissed` | `${user_config.find_suppress_dismissed}` | +| `evidence_sources_file` | `${user_config.evidence_sources_file}` | **GitHub access-path probe ladder.** For CI and repo-platform data, probe in order: GitHub MCP tools (`actions_*` and repo tools) → `gh` CLI → none. On "none", record the evidence gap and rank diff --git a/plugins/improvement/skills/find/context/hotspots.md b/plugins/improvement/skills/find/context/hotspots.md index 8ffe89788f0..f724c3427f5 100644 --- a/plugins/improvement/skills/find/context/hotspots.md +++ b/plugins/improvement/skills/find/context/hotspots.md @@ -68,10 +68,10 @@ Raw churn is dominated by mechanical files that say nothing about improvement va generated or minified output, snapshots, vendored trees. The plugin ships no list of them. Build Step 1's `excludes` as one ERE, alternatives joined with `|`, from two sources: -1. **Declared patterns:** `churn_exclude`, unioned across the `.claude/improvement.md` config - cascade (team file, `.claude/improvement.local.md` gitignored personal override, - `~/.claude/improvement.md` user-global), which also sets the churn window. These are already - EREs: use them as written. Key contract: `../../../reference/config.md`. +1. **Declared patterns:** `churn_exclude`, unioned across the config cascade (`userConfig`, the + team `/improvement.yaml`, the gitignored personal `/improvement.local.yaml`, and + any old file its dual-read window still reads), which also sets the churn window. These are + already EREs: use them as written. Key contract: `../../../reference/config.md`. 2. **The repository's own mechanical files**, unless `churn_exclude_defaults` is `false`: resolve them through the plugin's copy of the ecosystem-resolution steps, [`reference/ecosystem-resolution.md`](../../../reference/ecosystem-resolution.md). Read the diff --git a/plugins/improvement/skills/setup/SKILL.md b/plugins/improvement/skills/setup/SKILL.md index 286362416d6..dc35d95de5c 100644 --- a/plugins/improvement/skills/setup/SKILL.md +++ b/plugins/improvement/skills/setup/SKILL.md @@ -1,5 +1,5 @@ --- -description: "Verify and configure the improvement plugin for this repository. check (default) inspects the .claude/improvement.md config cascade read-only across all three layers, user-global, team, personal override, and reports the effective evidence-source configuration: which layers exist, what churn window and exclusion patterns resolve, and which Tier 2 MCP telemetry sources are declared. apply interviews the user and writes the team file. Zero config is a valid state. Tier 0 evidence needs nothing configured. Use when: 'set up improvement', 'configure improvement', 'is improvement configured', 'improvement setup', 'declare a telemetry source for the improvement finder', 'tune churn exclusions', or /improvement:find reports Tier 2 as an evidence gap to close. Re-runnable. Safe to invoke again to reconfigure." +description: "Verify and configure the improvement plugin for this repository. check (default) inspects the config cascade read-only (userConfig, team, personal override), names any old-location file still read, and reports the effective evidence-source configuration: which layers exist, what churn window and exclusion patterns resolve, and which Tier 2 MCP telemetry sources are declared. apply moves an old file's settings after a yes, then interviews the user and writes the team file. Zero config is a valid state. Tier 0 evidence needs nothing configured. Use when: 'set up improvement', 'configure improvement', 'is improvement configured', 'improvement setup', 'declare a telemetry source for the improvement finder', 'tune churn exclusions', or /improvement:find reports Tier 2 as an evidence gap to close. Re-runnable. Safe to invoke again to reconfigure." argument-hint: "[check|apply]" user-invocable: true disable-model-invocation: true @@ -8,8 +8,9 @@ disable-model-invocation: true ## Purpose Verify and manage the consuming repo's tracked evidence-source config at -`.claude/improvement.md`, so `/improvement:find` resolves Tier 2 telemetry sources and churn -tuning from a declared contract instead of having nothing to consult. +`/improvement.yaml`, so `/improvement:find` resolves Tier 2 telemetry sources and churn +tuning from a declared contract instead of having nothing to consult, and move config out of the +old locations so it ends in one home. The config is optional in every layer: with none, the finder runs fully on Tier 0 repo-native evidence with the default churn settings, and Tier 2 is a recorded evidence gap, so total @@ -24,65 +25,129 @@ then the interview-and-write flow. Any other argument is an error naming these t ## The config cascade -Three layers, resolved user-global (`~/.claude/improvement.md`) → team -(`.claude/improvement.md`, tracked) → personal override (`.claude/improvement.local.md`, -gitignored), merged per the semantics declared in +Four layers, resolved plugin default → `userConfig` → team (`/improvement.yaml`, tracked) → +personal (`/improvement.local.yaml`, gitignored), merged per the semantics declared in `${CLAUDE_PLUGIN_ROOT}/reference/config.md`: per-key override for scalars, a ceiling personal layers can only lower for `find_open_item_cap`, union for -`churn_exclude`, per-source-name merge for `evidence_sources` with an empty-body opt-out. This -skill writes only the **team** file; changes to the user-global layer or the personal override are the -user's to make. Anchor every repo-relative read at the repo root (`${CLAUDE_PROJECT_DIR}` when -set, otherwise `git rev-parse --show-toplevel`), never at the CWD. - -This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](../../reference/config-locations.md) says. +`churn_exclude`, per-source-name merge for `evidence_sources` with an empty-body opt-out. That +file also owns ``, the root rule, and the dual-read window for the old files +(`~/.claude/improvement.md`, `.claude/improvement.md`, `.claude/improvement.local.md`). Anchor +every repo-relative read at the repo root (`git rev-parse --show-toplevel`), never at the CWD. + +The `userConfig` layer, as Claude Code substituted it into this skill (empty, or a literal +`${user_config.…}` placeholder, means unset): + +| Option | Value | +|---|---| +| `churn_window` | `${user_config.churn_window}` | +| `churn_exclude` | `${user_config.churn_exclude}` | +| `churn_exclude_defaults` | `${user_config.churn_exclude_defaults}` | +| `find_open_item_cap` | `${user_config.find_open_item_cap}` | +| `find_run_item_cap` | `${user_config.find_run_item_cap}` | +| `find_run_item_cap_floor` | `${user_config.find_run_item_cap_floor}` | +| `find_run_item_cap_ceiling` | `${user_config.find_run_item_cap_ceiling}` | +| `find_size_band` | `${user_config.find_size_band}` | +| `find_scope` | `${user_config.find_scope}` | +| `find_suppress_dismissed` | `${user_config.find_suppress_dismissed}` | +| `evidence_sources_file` | `${user_config.evidence_sources_file}` | + +This skill writes the team file, the personal file only to move an old personal file there, and +the `evidence_sources_file` only to move an old user-global file's sources there. It never writes +`userConfig`: an option is set through `/plugin configure improvement@`, and a fresh +session observes the new value. ## `check` (read-only) Inspect the effective merged config and report a PASS/FAIL/WARN/INFO table with one remediation line per FAIL. Modify nothing, and do not run a scan. That is `/improvement:find`. -1. **Layer presence.** Load every layer you can access and report which exist. Look up the user-global layer with one Read of the literal path `~/.claude/improvement.md`, `~` kept; never Glob for it, spell out a home directory, or search the home tree. A Read that finds no file means the layer is absent. All absent → +1. **Layer presence.** Resolve `` and classify the root as the config contract says, then + report each layer: every `userConfig` option set in the table above, `/improvement.yaml`, + and `/improvement.local.yaml`. Look up the old user-global file with one Read of the + literal path `~/.claude/improvement.md`, `~` kept; never Glob for it, spell out a home + directory, or search the home tree. A Read that finds no file means it is absent. All absent → INFO: the finder uses bundled defaults and records Tier 2 as an evidence gap; `apply` writes - `.claude/improvement.md` to declare sources. When a layer outside the repo (the user-global - base) cannot be read, WARN it was not considered rather than presenting the readable layers - as the whole effective config. -2. **Effective configuration.** Report the merged result and which layer supplied each value: + `/improvement.yaml` to declare sources. When the old user-global file or the + `evidence_sources_file` cannot be read, WARN it was not considered rather than presenting the + readable layers as the whole effective config. +2. **Old files.** Retired conventions: run + `bash "${CLAUDE_PLUGIN_ROOT}/lib/check-retirements.sh" --manifest "${CLAUDE_PLUGIN_ROOT}/retirements.yaml"`. + Exit 0 → PASS. Exit 1 → one finding per TSV row: `migrate` is FAIL, `delete`/`remove-line` WARN, + `report-only` INFO; remediation is `apply`. Exit 2 → FAIL, never silent. Bash unavailable → + report the step UNKNOWN with remediation, never green. The records cover + `.claude/improvement.md` (`improvement-r001`) and `.claude/improvement.local.md` + (`improvement-r002`); `~/.claude/improvement.md` is machine scope, outside the manifest, so a + present one is a WARN row from the Read above. Each old file's row names it, the layer it is + read as, its new location, and `/improvement:setup apply` to move it. When the new location also supplies that + layer, the row names both files, says the new one wins, and lists the old file's keys that do + not apply. Print the contract's one dual-read warning line for the run. +3. **Effective configuration.** Report the merged result and which layer supplied each value (an + old file's value names the old file as its layer): the effective `churn_window`, whether exclusions resolved from the repository are on (`churn_exclude_defaults`), declared `churn_exclude` additions, the effective `find_open_item_cap` and unattended run controls (`find_run_item_cap`, its floor and ceiling, `find_size_band`, `find_scope`, `find_suppress_dismissed`), and every `evidence_sources` entry (name, `mcp_server`, `kind`, scope), including entries a later layer opted out, reported as removed, not broken. A malformed layer degrades soft: name it, resolve as if absent, report the parse error. -3. **Key validity.** Each `evidence_sources` entry names an `mcp_server`; an entry missing it is +4. **Key validity.** Each `evidence_sources` entry names an `mcp_server`; an entry missing it is FAIL, naming the entry. A `find_open_item_cap` that is not a non-negative integer is FAIL, naming the layer, and a personal value above the team value or default is WARN: it is ignored. Any other `find_*` value outside its type in the key contract, or a run cap whose floor, start and ceiling do not ascend, is FAIL, naming the layer. Where the session can enumerate available MCP servers, note (INFO) any declared server not currently available. At find-time that source becomes an evidence-gap line, which may be expected on this machine. -4. **Tracked, not ignored.** A present team file must be committed to be team-shared, and - "not ignored" is not "tracked". Probe both: `git check-ignore -v .claude/improvement.md` +5. **Tracked, not ignored.** A present team file (`/improvement.yaml`, or the old + `.claude/improvement.md` while it stands in) must be committed to be team-shared, and + "not ignored" is not "tracked". Probe both: `git check-ignore -v ` (non-empty result is FAIL with the matching pattern) and - `git ls-files --error-unmatch .claude/improvement.md` (non-zero exit is FAIL: the file is + `git ls-files --error-unmatch ` (non-zero exit is FAIL: the file is present but untracked, the state immediately after `apply` writes it, so teammates will not receive it until it is committed; report "untracked, commit it" and, if it is staged but - uncommitted, say that instead via `git diff --cached --name-only`). The `.local.md` personal override is - expected to be gitignored, a personal override that is tracked or staged is FAIL (a personal deviation - can reach team history); an ignored personal override is INFO. -5. **Other-layer divergence.** INFO: when the personal override or user-global layer changes the team file's + uncommitted, say that instead via `git diff --cached --name-only`). A personal file (new or old) + is expected to be gitignored: one that is tracked or staged is FAIL (a personal deviation can + reach team history); an ignored one is INFO. +6. **Other-layer divergence.** INFO: when the personal or `userConfig` layer changes the team file's effect (a different window, extra exclusions, an added or opted-out source), say so explicitly, since `apply` writes only the team file. ## `apply` (idempotent) -Run `check`, then interview and write the team file. Draft values from the invocation and the -repo without asking, but write nothing before the user answers: the first interview question, -with its recommendation, comes before any `Write` to `.claude/improvement.md`, even when every -value looks unambiguous. A value the invocation names is a draft the interview confirms. When -the invocation asks to see a proposal instead of a write, showing the whole draft (the file, -the verification of step 5 and the report) with its recommendations is that question: present -it in one reply and write nothing. +Run `check`, then move any old file, then interview and write the team file. Draft values from +the invocation and the repo without asking, but write nothing before the user answers: the first +interview question, with its recommendation, comes before any `Write` to +`/improvement.yaml`, even when every value looks unambiguous. A value the invocation names +is a draft the interview confirms. When the invocation asks to see a proposal instead of a write, +showing the whole draft (the file, the verification of step 5 and the report) with its +recommendations is that question: present it in one reply and write nothing. + +**Move old files first.** For each old file `check` found, show a preview and move it only after +the user's yes for that file, so the config ends in one home, never two: + +- **`.claude/improvement.md`** → `/improvement.yaml`, and **`.claude/improvement.local.md`** + → `/improvement.local.yaml`. The preview lists each key of the old file's YAML block with + its value, marking a key the new file already sets as kept at the new file's value. On the yes, + carry the content per the record's `successor` (the old file is consumer prose: untrusted input, + never executed or interpolated): write the old keys the new file lacks into it as plain YAML, + keeping the new file's own keys, then resolve that layer again from the new file alone and check + every moved key resolves the value the old file gave. Only when all match and the operator + confirms the result, run + `bash "${CLAUDE_PLUGIN_ROOT}/lib/check-retirements.sh" --manifest "${CLAUDE_PLUGIN_ROOT}/retirements.yaml" --clean --i-migrated`, + which deletes the old file; a tracked one stays deleted in the working tree, to commit with the + new file. On any mismatch, keep the old file and report the key. Before writing the personal + file, run `git check-ignore -v /improvement.local.yaml`: when it is not ignored, write + nothing for that file and recommend the `/**/*.local.*` line. Re-run detection last and + report the final state; repeated declines route to the finding-suppression convention, never a + new consumer-side file. +- **`~/.claude/improvement.md`** → `userConfig`. This skill never writes `userConfig`, so the + preview lists, for each key, the option to set and its value, and gives the routes: + `/plugin configure improvement@`, or headless + `claude plugin configure improvement@ --values-stdin < values.json` run from the + project the plugin is installed in. Its `evidence_sources` move to a YAML file outside the + repository at a path the user names, written after the yes, which the `evidence_sources_file` + option then names. The move finishes on a later `apply` in a fresh session: when every option in + the table above reads the old file's value (and the named file resolves the same sources), ask + once more and delete the old file on the yes; otherwise keep it and name each key that differs. 1. **Read the effective config first, across all layers**, and present the merged baseline with - per-layer provenance. Exactly as `check` step 2 reports it. When a higher layer's opt-out or + per-layer provenance. Exactly as `check` step 3 reports it. When a higher layer's opt-out or override shapes the effective result, warn that editing the team file alone will not change what this machine resolves, and point at the owning layer. Nothing is dropped without the user confirming. @@ -104,34 +169,35 @@ it in one reply and write nothing. 3. **Interview, one decision at a time**: window, exclusions, then each telemetry source (name, `mcp_server`, `kind`, scope, hints) with a recommendation the user accepts, edits, or declines. -4. **Write the team file**, only after the interview's answers, in the file format defined by - `${CLAUDE_PLUGIN_ROOT}/reference/config.md`, a fenced YAML block holding only the keys the - user confirmed. Never write a vendor-specific default the user did not declare. +4. **Write the team file** `/improvement.yaml`, only after the interview's answers, in the + file format defined by `${CLAUDE_PLUGIN_ROOT}/reference/config.md`: plain YAML holding only the + keys the user confirmed. Never write a vendor-specific default the user did not declare. 5. **Verify after writing.** Re-run the `check` probes on the written file: both - `git check-ignore -v .claude/improvement.md` (surface a matching pattern and offer a - `.gitignore` fix) and `git ls-files --error-unmatch .claude/improvement.md` (non-zero exit + `git check-ignore -v /improvement.yaml` (surface a matching pattern and offer a + `.gitignore` fix) and `git ls-files --error-unmatch /improvement.yaml` (non-zero exit means the file is un-ignored but still untracked, the guaranteed state right after this step writes it, so report "written but untracked: commit it to share with the team", never - success). Then offer the personal override - convention: personal overrides go in `.claude/improvement.local.md`; recommend the consumer - add the recursive `.claude/**/*.local.*` line to `.gitignore` if not already covered. But - never edit their `.gitignore` yourself. + success). Then offer the personal convention: personal values go in + `/improvement.local.yaml`; recommend the consumer add the recursive `/**/*.local.*` + line (written with the bound home) to `.gitignore` if not already covered. But never edit + their `.gitignore` yourself. Re-running `apply` after everything passes changes nothing and reports "already configured". ## Output `check`: the PASS/FAIL/WARN/INFO table plus the effective evidence-source configuration with -per-layer provenance. `apply`: a tracked `.claude/improvement.md`, the re-run check result, and -one paragraph on what was written and how to re-run this setup to reconfigure. +per-layer provenance. `apply`: each old file moved or the reason it stayed, a tracked +`/improvement.yaml`, the re-run check result, and one paragraph on what was written and how +to re-run this setup to reconfigure. ## What this skill does not do - Run an improvement scan. That is `/improvement:find`; `check` only inspects config. - Install or configure MCP servers. It declares which configured server carries telemetry; provisioning the server is the consumer's own MCP setup. -- Write the user-global layer, the `.local.md` personal override, or the consumer's `.gitignore`. Team - file only; everything else is recommended, not written. +- Write `userConfig`, user settings, `pluginConfigs`, or the consumer's `.gitignore`. Beyond the + team file it writes only the targets of a confirmed move of an old file. - Write machine-local state. Configuration lives in the consumer's tracked file, never in the plugin directory or the plugin data directory. @@ -140,10 +206,13 @@ one paragraph on what was written and how to re-run this setup to reconfigure. - **All layers absent is healthy.** Tier 0 evidence needs no config; do not manufacture a FAIL (or a config file) for a repo that has not opted into Tier 2 or churn tuning. - **CWD is not the repo root.** Invoked from a subdirectory, a CWD-relative read finds a - nonexistent `/.claude/improvement.md` and silently reports an absent config. Anchor + nonexistent `//improvement.yaml` and silently reports an absent config. Anchor at the root in every self-contained shell call. -- **The team file is the only thing `apply` writes.** An effective value contributed by the - personal override or user-global layer cannot be changed here; say which layer owns it instead of +- **The interview writes the team file only.** An effective value contributed by the + personal or `userConfig` layer cannot be changed by it; say which layer owns it instead of writing a team value that the higher layer will keep overriding. -- **No git verdict on the user-global layer.** `git check-ignore` against a path outside the - worktree is meaningless (or confidently wrong when the home directory is itself a repo); the tracked/ignored probes apply to the two in-repo layers only. +- **No git verdict outside the repository.** `git check-ignore` against `~/.claude/improvement.md` + or an `evidence_sources_file` outside the worktree is meaningless (or confidently wrong when the + home directory is itself a repo); the tracked/ignored probes apply to in-repo files only. +- **A same-session `check` can show an old `userConfig` value.** Substitution happens when the + skill loads; confirm a changed option in a fresh session before deleting the old user-global file. diff --git a/scripts/org-repo-tokens-allow.tsv b/scripts/org-repo-tokens-allow.tsv index 850cdb7a843..5c751fd144a 100644 --- a/scripts/org-repo-tokens-allow.tsv +++ b/scripts/org-repo-tokens-allow.tsv @@ -66,6 +66,7 @@ plugins/harness-ops/skills/changelog/context/read-actions.md melodic-software/cl plugins/harness-ops/skills/observability/context/operator-setup-retention.md melodic-software/provisioning 2 names another repository of the publishing organization in prose or an example plugins/implementation/schemas/implementation.schema.json melodic-software/claude-code-plugins 1 schema $id or $ref naming this marketplace's published schema plugins/improvement/README.md melodic-software/claude-code-plugins 1 names this marketplace's own repository (install, issue target or example) +plugins/improvement/schemas/improvement.schema.json melodic-software/claude-code-plugins 1 schema $id or $ref naming this marketplace's published schema plugins/improvement/skills/find/context/unattended.md melodic-software/claude-code-plugins 1 raw link to this marketplace's own published doc plugins/instruction-placement/git-hooks/entries.json melodic-software/claude-code-plugins 1 shipped default lefthook remote; install.mjs uses the installed marketplace's git URL when it has one plugins/instruction-placement/skills/migrate/reference/sources.md melodic-software/ci-workflows 3 names another repository of the publishing organization in prose or an example diff --git a/scripts/shared-copies.txt b/scripts/shared-copies.txt index 76f81a95c50..aae740ef4c9 100644 --- a/scripts/shared-copies.txt +++ b/scripts/shared-copies.txt @@ -199,6 +199,7 @@ lib/check-retirements.sh plugins/harness-ops/lib/check-retirements.sh lib/check-retirements.sh plugins/attribution/lib/check-retirements.sh lib/check-retirements.sh plugins/docs-naming/lib/check-retirements.sh lib/check-retirements.sh plugins/guardrails/lib/check-retirements.sh +lib/check-retirements.sh plugins/improvement/lib/check-retirements.sh lib/state-key.sh plugins/harness-config/lib/state-key.sh lib/state-key.sh plugins/harness-memory/lib/state-key.sh lib/state-key.sh plugins/harness-ops/lib/state-key.sh From 17ee00152546f3ca3338156d5b5085f90a4e8ebc Mon Sep 17 00:00:00 2001 From: "melodic-automation-lanes[bot]" <337595936+melodic-automation-lanes[bot]@users.noreply.github.com> Date: Sun, 22 Nov 2026 01:07:46 +0000 Subject: [PATCH 2/3] Address review feedback on work-resolve-issue/issue-18011-44964524568-1 Lane-Activity: pr-unblock/address-feedback Lane-Thread: PRRT_kwDOTCGFQM66eRSd Lane-Thread: PRRT_kwDOTCGFQM66eRSi Lane-Thread: PRRT_kwDOTCGFQM66eRXA Lane-Thread: PRRT_kwDOTCGFQM66eRXF Lane-Thread: PRRT_kwDOTCGFQM66eRXK Lane-Thread: PRRT_kwDOTCGFQM66eRXP --- plugins/improvement/.claude-plugin/plugin.json | 3 ++- .../find-unattended-open-cap-stops/case.yaml | 6 ++++++ .../find-unattended-open-cap-stops/prompt.md | 6 +++--- .../samples/warns-old-file.json | 11 +++++++++++ .../find-unattended-open-cap-stops/scaffold.sh | 11 +++++++++++ .../case.yaml | 2 +- .../prompt.md | 2 +- .../scaffold.sh | 8 ++------ .../find-unattended-run-cap-from-config/case.yaml | 2 +- .../find-unattended-run-cap-from-config/prompt.md | 2 +- .../scaffold.sh | 8 ++------ plugins/improvement/reference/config.md | 5 +++-- .../improvement/schemas/improvement.schema.json | 3 ++- .../improvement/skills/find/context/hotspots.md | 15 ++++++++++++--- plugins/improvement/skills/setup/SKILL.md | 15 ++++++++++----- 15 files changed, 68 insertions(+), 31 deletions(-) create mode 100644 plugins/improvement/evals/find-unattended-open-cap-stops/samples/warns-old-file.json diff --git a/plugins/improvement/.claude-plugin/plugin.json b/plugins/improvement/.claude-plugin/plugin.json index 94e3c9eccd3..561e69a75f5 100644 --- a/plugins/improvement/.claude-plugin/plugin.json +++ b/plugins/improvement/.claude-plugin/plugin.json @@ -64,7 +64,8 @@ "find_size_band": { "type": "string", "title": "Unattended size band", - "description": "Candidate sizes an unattended run ranks: all, small, medium or large. Unset: all." + "description": "Candidate sizes an unattended run ranks: all, small, medium or large. Unset: all.", + "options": ["all", "small", "medium", "large"] }, "find_scope": { "type": "string", diff --git a/plugins/improvement/evals/find-unattended-open-cap-stops/case.yaml b/plugins/improvement/evals/find-unattended-open-cap-stops/case.yaml index 1fb5047a989..6995c6e8dd3 100644 --- a/plugins/improvement/evals/find-unattended-open-cap-stops/case.yaml +++ b/plugins/improvement/evals/find-unattended-open-cap-stops/case.yaml @@ -28,6 +28,12 @@ graders: flags: 'i' target: last_message arm: both + - name: warns-old-file + type: regex + pattern: '^(?=.*\.claude[\\/]improvement\.md)(?=.*docs[\\/]conventions[\\/]improvement\.yaml)(?=.*/improvement:setup apply).*$' + flags: 'm' + target: last_message + arm: both - name: files-nothing-at-open-cap type: llm criteria: 'PASS only if the reply plans to file no work item this run and gives as the reason that the five open items already carrying the source: improvement-find label meet the open cap of 5. FAIL if the reply would file any item (including up to the prompt''s cap of 3), or if it stops filing for another reason only, such as duplicates, a missing label or the adaptive cap.' diff --git a/plugins/improvement/evals/find-unattended-open-cap-stops/prompt.md b/plugins/improvement/evals/find-unattended-open-cap-stops/prompt.md index 65167432ccb..3d94fa8fc2e 100644 --- a/plugins/improvement/evals/find-unattended-open-cap-stops/prompt.md +++ b/plugins/improvement/evals/find-unattended-open-cap-stops/prompt.md @@ -1,14 +1,14 @@ --- -description: "Unattended find with the open cap reached. Narration: like find-unattended-files-capped, the prompt gives the state key and the tracker's state as facts and switches writes and filing off, so the case grades the declared plan. Five open items already carry the source: improvement-find label, the config sets no find_open_item_cap (default 5), and the prompt asks for up to 3 filings. The reply asks no question (no-ask-tool), writes nothing into the repository (no-repo-write), edits nothing (no-edit), names the open cap as why nothing is filed (names-open-cap), and plans no filing despite the prompt's cap of 3 (files-nothing-at-open-cap, llm). The real tracker count is unmeasured. Needs --scaffold and --allow-tools Write Edit so the write graders can fail." +description: "Unattended find with the open cap reached. Narration: like find-unattended-files-capped, the prompt gives the state key and the tracker's state as facts and switches writes and filing off, so the case grades the declared plan. Five open items already carry the source: improvement-find label, the only config is an old-location .claude/improvement.md that sets no find_open_item_cap (default 5), and the prompt asks for up to 3 filings. The reply asks no question (no-ask-tool), writes nothing into the repository (no-repo-write), edits nothing (no-edit), names the open cap as why nothing is filed (names-open-cap), prints the dual-read warning line naming the old file, docs/conventions/improvement.yaml and /improvement:setup apply (warns-old-file), and plans no filing despite the prompt's cap of 3 (files-nothing-at-open-cap, llm). The real tracker count is unmeasured. Needs --scaffold and --allow-tools Write Edit so the write graders can fail." tags: [find, unattended, narration, no-network] max_turns: 25 timeout_seconds: 900 allowed_tools: [Read, Glob, Grep, Skill, Write, Edit, AskUserQuestion] -expected_outcome: "The run asks nothing, still ranks candidates for the report, and files nothing because five open items carrying the source: improvement-find label meet the open cap of 5, which the prompt's 'file at most 3' does not raise; it says so." +expected_outcome: "The run asks nothing, prints one warning naming the old .claude/improvement.md, docs/conventions/improvement.yaml as where to move it and /improvement:setup apply, still ranks candidates for the report, and files nothing because five open items carrying the source: improvement-find label meet the open cap of 5, which the prompt's 'file at most 3' does not raise; it says so." --- /improvement:find --unattended This runs unattended as a scheduled routine; there is no interactive user to answer any question. File at most 3 items this run. -Facts for this run, take them as given: the plugin's state-key helper printed `github.com/acme/checkout-service/3f9a1c2e`. No `.claude/improvement.md` config layer exists. work-items:track is installed and bound to this repository's tracker, and the repository has the `source: improvement-find` label. Its open items carrying that label are #61 "Cache the tax-rate lookup", #62 "Split the checkout handler", #63 "Add a retry budget to the payment client", #64 "Remove the unused coupon exporter" and #65 "Raise test coverage on refunds"; none of them has been triaged yet. No candidate has been dismissed before. Writes and tracker calls are switched off in this sandbox, so write nothing and invoke no work-items skill: instead give the exact path the report would be persisted to, and say what the filing step decides and the title of any item it would file. +Facts for this run, take them as given: the plugin's state-key helper printed `github.com/acme/checkout-service/3f9a1c2e`. Read the config layers in this workspace yourself; no user-global layer exists. work-items:track is installed and bound to this repository's tracker, and the repository has the `source: improvement-find` label. Its open items carrying that label are #61 "Cache the tax-rate lookup", #62 "Split the checkout handler", #63 "Add a retry budget to the payment client", #64 "Remove the unused coupon exporter" and #65 "Raise test coverage on refunds"; none of them has been triaged yet. No candidate has been dismissed before. Writes and tracker calls are switched off in this sandbox, so write nothing and invoke no work-items skill: instead give the exact path the report would be persisted to, and say what the filing step decides and the title of any item it would file. diff --git a/plugins/improvement/evals/find-unattended-open-cap-stops/samples/warns-old-file.json b/plugins/improvement/evals/find-unattended-open-cap-stops/samples/warns-old-file.json new file mode 100644 index 00000000000..2feb97406bd --- /dev/null +++ b/plugins/improvement/evals/find-unattended-open-cap-stops/samples/warns-old-file.json @@ -0,0 +1,11 @@ +{ + "pass": [ + { "answer": "WARN: read .claude/improvement.md (old location); move it to docs/conventions/improvement.yaml with /improvement:setup apply.", "why": "one line with the old file, the new location and the command" }, + { "answer": "Filing: nothing filed (open cap 5 reached).\n\nOld config: .claude/improvement.md is still read as the team layer; run /improvement:setup apply to move it to docs/conventions/improvement.yaml.", "why": "warning line in any order" } + ], + "fail": [ + { "answer": "WARN: .claude/improvement.md is an old location.", "why": "no new location, no command" }, + { "answer": "WARN: .claude/improvement.md is an old location.\nMove it to docs/conventions/improvement.yaml with /improvement:setup apply.", "why": "split over two lines, not one warning line" }, + { "answer": "Move .claude/improvement.md to docs/conventions/improvement.yaml.", "why": "no setup command" } + ] +} diff --git a/plugins/improvement/evals/find-unattended-open-cap-stops/scaffold.sh b/plugins/improvement/evals/find-unattended-open-cap-stops/scaffold.sh index 9492f33732a..9580c9eed77 100755 --- a/plugins/improvement/evals/find-unattended-open-cap-stops/scaffold.sh +++ b/plugins/improvement/evals/find-unattended-open-cap-stops/scaffold.sh @@ -2,3 +2,14 @@ set -euo pipefail bash "$(dirname "${BASH_SOURCE[0]}")/../fixtures/seed-checkout-service.sh" + +# An old-location team file, read through the dual-read window. It sets only the default +# churn window, so the open cap stays at its default of 5. +mkdir -p .claude +cat > .claude/improvement.md <<'CONFIG' +# improvement config + +```yaml +churn_window: "90 days ago" +``` +CONFIG diff --git a/plugins/improvement/evals/find-unattended-personal-cap-cannot-raise/case.yaml b/plugins/improvement/evals/find-unattended-personal-cap-cannot-raise/case.yaml index 90af10dad43..69b51837e6e 100644 --- a/plugins/improvement/evals/find-unattended-personal-cap-cannot-raise/case.yaml +++ b/plugins/improvement/evals/find-unattended-personal-cap-cannot-raise/case.yaml @@ -25,7 +25,7 @@ graders: - name: reads-personal-layer type: tool_used tool: 'Read' - input_match: 'improvement\.local\.md' + input_match: 'docs[\\/]+conventions[\\/]+improvement\.local\.yaml' min: 1 - name: personal-value-does-not-raise-cap type: llm diff --git a/plugins/improvement/evals/find-unattended-personal-cap-cannot-raise/prompt.md b/plugins/improvement/evals/find-unattended-personal-cap-cannot-raise/prompt.md index ea7d67ab431..2148fd9b1a6 100644 --- a/plugins/improvement/evals/find-unattended-personal-cap-cannot-raise/prompt.md +++ b/plugins/improvement/evals/find-unattended-personal-cap-cannot-raise/prompt.md @@ -1,5 +1,5 @@ --- -description: "Unattended find whose personal config tries to raise the open cap. Narration: a scaffolded .claude/improvement.local.md sets find_open_item_cap to 9, no team layer exists, and the prompt gives five open items carrying the source label as facts and switches writes and filing off. The reply asks nothing (no-ask-tool), writes and edits nothing in the repository (no-repo-write, no-edit), reads the personal layer (reads-personal-layer), and files nothing because the cap stays 5 (personal-value-does-not-raise-cap, llm). Real filing is unmeasured. Needs --scaffold and --allow-tools Write Edit so the write graders can fail." +description: "Unattended find whose personal config tries to raise the open cap. Narration: a scaffolded personal file, docs/conventions/improvement.local.yaml, sets find_open_item_cap to 9, no team layer exists, and the prompt gives five open items carrying the source label as facts and switches writes and filing off. The reply asks nothing (no-ask-tool), writes and edits nothing in the repository (no-repo-write, no-edit), reads the personal layer (reads-personal-layer), and files nothing because the cap stays 5 (personal-value-does-not-raise-cap, llm). Real filing is unmeasured. Needs --scaffold and --allow-tools Write Edit so the write graders can fail." tags: [find, unattended, narration, no-network] max_turns: 25 timeout_seconds: 900 diff --git a/plugins/improvement/evals/find-unattended-personal-cap-cannot-raise/scaffold.sh b/plugins/improvement/evals/find-unattended-personal-cap-cannot-raise/scaffold.sh index 2d95a2c9fbe..f0de59d3be0 100755 --- a/plugins/improvement/evals/find-unattended-personal-cap-cannot-raise/scaffold.sh +++ b/plugins/improvement/evals/find-unattended-personal-cap-cannot-raise/scaffold.sh @@ -3,11 +3,7 @@ set -euo pipefail bash "$(dirname "${BASH_SOURCE[0]}")/../fixtures/seed-checkout-service.sh" -mkdir -p .claude -cat > .claude/improvement.local.md <<'CONFIG' -# personal improvement config - -```yaml +mkdir -p docs/conventions +cat > docs/conventions/improvement.local.yaml <<'CONFIG' find_open_item_cap: 9 -``` CONFIG diff --git a/plugins/improvement/evals/find-unattended-run-cap-from-config/case.yaml b/plugins/improvement/evals/find-unattended-run-cap-from-config/case.yaml index da38e2c7c4f..3f5dc515c77 100644 --- a/plugins/improvement/evals/find-unattended-run-cap-from-config/case.yaml +++ b/plugins/improvement/evals/find-unattended-run-cap-from-config/case.yaml @@ -25,7 +25,7 @@ graders: - name: reads-team-layer type: tool_used tool: 'Read' - input_match: '\.claude[\\/]+improvement\.md' + input_match: 'docs[\\/]+conventions[\\/]+improvement\.yaml' min: 1 - name: files-one-item-from-config type: llm diff --git a/plugins/improvement/evals/find-unattended-run-cap-from-config/prompt.md b/plugins/improvement/evals/find-unattended-run-cap-from-config/prompt.md index 6e95ccea892..c28c57601a8 100644 --- a/plugins/improvement/evals/find-unattended-run-cap-from-config/prompt.md +++ b/plugins/improvement/evals/find-unattended-run-cap-from-config/prompt.md @@ -1,5 +1,5 @@ --- -description: "Unattended find whose team config sets the per-run filing cap. Narration: a scaffolded .claude/improvement.md sets find_run_item_cap to 1, and the prompt gives the tracker's state as facts and switches writes and filing off. The reply asks nothing (no-ask-tool), writes and edits nothing in the repository (no-repo-write, no-edit), reads the team layer (reads-team-layer), and plans one filing because the configured cap is 1 (files-one-item-from-config, llm). Real filing is unmeasured. Needs --scaffold and --allow-tools Write Edit so the write graders can fail." +description: "Unattended find whose team config sets the per-run filing cap. Narration: a scaffolded team file, docs/conventions/improvement.yaml, sets find_run_item_cap to 1, and the prompt gives the tracker's state as facts and switches writes and filing off. The reply asks nothing (no-ask-tool), writes and edits nothing in the repository (no-repo-write, no-edit), reads the team layer (reads-team-layer), and plans one filing because the configured cap is 1 (files-one-item-from-config, llm). Real filing is unmeasured. Needs --scaffold and --allow-tools Write Edit so the write graders can fail." tags: [find, unattended, narration, no-network] max_turns: 25 timeout_seconds: 900 diff --git a/plugins/improvement/evals/find-unattended-run-cap-from-config/scaffold.sh b/plugins/improvement/evals/find-unattended-run-cap-from-config/scaffold.sh index 547a2d72ff6..c0221714123 100755 --- a/plugins/improvement/evals/find-unattended-run-cap-from-config/scaffold.sh +++ b/plugins/improvement/evals/find-unattended-run-cap-from-config/scaffold.sh @@ -3,11 +3,7 @@ set -euo pipefail bash "$(dirname "${BASH_SOURCE[0]}")/../fixtures/seed-checkout-service.sh" -mkdir -p .claude -cat > .claude/improvement.md <<'CONFIG' -# improvement config - -```yaml +mkdir -p docs/conventions +cat > docs/conventions/improvement.yaml <<'CONFIG' find_run_item_cap: 1 -``` CONFIG diff --git a/plugins/improvement/reference/config.md b/plugins/improvement/reference/config.md index f6dd6a2bfb3..55380cfbcfa 100644 --- a/plugins/improvement/reference/config.md +++ b/plugins/improvement/reference/config.md @@ -64,7 +64,8 @@ layer they stand in for, so at a root that is `$HOME` they are not read as team The repository-scope window is declared by the plugin's retirement records, [`retirements.yaml`](../retirements.yaml): `improvement-r001` (`.claude/improvement.md`) and `improvement-r002` (`.claude/improvement.local.md`), both `migrate`, evaluated by -`lib/check-retirements.sh` from `/improvement:setup`. `~/.claude/improvement.md` is machine scope, +`lib/check-retirements.sh` from `/improvement:setup`, always with `--root ` so the helper +checks the same root as every other read (left out, it checks `${CLAUDE_PROJECT_DIR}` first). `~/.claude/improvement.md` is machine scope, outside that mechanism, so setup detects it with its own Read. Removing these reads is a separate later change (demoting the records to `report-only`), made once no run reports an old file. @@ -119,7 +120,7 @@ evidence_sources: | Key | Type | Default | Meaning | |---|---|---|---| -| `churn_window` | string accepted by `git log --since` | `"90 days ago"` | The hotspot recipe's change-frequency window, its main tuning knob. The recipe's history-depth gate still applies: a window the history does not cover shrinks or downgrades to an evidence gap regardless of this value. | +| `churn_window` | string accepted by `git log --since`, made of letters, digits, spaces and `.:,/+-` only | `"90 days ago"` | The hotspot recipe's change-frequency window, its main tuning knob. A value with any other character is malformed and never reaches the command. The recipe's history-depth gate still applies: a window the history does not cover shrinks or downgrades to an evidence gap regardless of this value. | | `churn_exclude` | list of ERE patterns | `[]` | Extra patterns matched against paths from `git log --name-only` and excluded from churn counting. Unioned across layers and with the mechanical files resolved from the repository. | | `churn_exclude_defaults` | boolean (`true` \| `false`, since bare `on`/`off` is the YAML 1.1 coercion footgun and is not accepted) | `true` | `false` drops the exclusions resolved from the repository (the lockfiles, generated or minified output, snapshots and vendored trees its `.gitattributes`, build and manifest files show: the hotspot recipe's Step 2), leaving only declared patterns. The plugin ships no exclusion list. | | `find_open_item_cap` | non-negative integer | `5` | Applied to each source label on its own (`source: improvement-find`, `source: architecture-improve`): unattended `/improvement:find` files nothing under a label while the open items carrying it number at or above this, and otherwise files no more than the room left under it. A hard stop the invocation prompt cannot raise, and personal layers can only lower ("Merge semantics"); `0` stops all unattended filing. A value that is not a non-negative integer is malformed: that layer's value is ignored and reported. | diff --git a/plugins/improvement/schemas/improvement.schema.json b/plugins/improvement/schemas/improvement.schema.json index ac64d92be32..8ab1dce3b3e 100644 --- a/plugins/improvement/schemas/improvement.schema.json +++ b/plugins/improvement/schemas/improvement.schema.json @@ -8,9 +8,10 @@ "properties": { "$schema": { "type": "string" }, "churn_window": { - "description": "The hotspot recipe's change-frequency window, a value git log --since accepts.", + "description": "The hotspot recipe's change-frequency window, a value git log --since accepts, made of letters, digits, spaces and .:,/+- only.", "type": "string", "minLength": 1, + "pattern": "^[A-Za-z0-9 .:,/+-]+$", "default": "90 days ago" }, "churn_exclude": { diff --git a/plugins/improvement/skills/find/context/hotspots.md b/plugins/improvement/skills/find/context/hotspots.md index f724c3427f5..4ccbda9917f 100644 --- a/plugins/improvement/skills/find/context/hotspots.md +++ b/plugins/improvement/skills/find/context/hotspots.md @@ -51,9 +51,16 @@ Resolve the gate: Default window: 90 days, overridable through the config cascade Step 2 describes. The window is the main tuning knob. +The window value is data, whichever layer supplies it: use it only when it is made of letters, +digits, spaces and `.:,/+-` alone (the forms `git log --since` accepts, such as `90 days ago` or +`2026-08-01`). Any other value, one holding a quote, `$`, a backtick, `;`, `|` or a newline +included, is malformed: ignore that layer's value, report it, and fall back to the next layer +down, else the default. Put the checked value inside the single quotes of `--since='…'`, never +inside double quotes. The commands below show the default. + ```bash excludes='' -git log --since="90 days ago" --pretty=format: --name-only | +git log --since='90 days ago' --pretty=format: --name-only | grep -v '^$' | grep -Ev "$excludes" | sort | uniq -c | sort -rn | head -50 ``` @@ -71,7 +78,9 @@ Step 1's `excludes` as one ERE, alternatives joined with `|`, from two sources: 1. **Declared patterns:** `churn_exclude`, unioned across the config cascade (`userConfig`, the team `/improvement.yaml`, the gitignored personal `/improvement.local.yaml`, and any old file its dual-read window still reads), which also sets the churn window. These are - already EREs: use them as written. Key contract: `../../../reference/config.md`. + already EREs: use them as written, as data. An entry holding a single quote or a newline + cannot sit inside the single-quoted `excludes` assignment: leave that entry out and report it + as malformed, naming its layer. Key contract: `../../../reference/config.md`. 2. **The repository's own mechanical files**, unless `churn_exclude_defaults` is `false`: resolve them through the plugin's copy of the ecosystem-resolution steps, [`reference/ecosystem-resolution.md`](../../../reference/ecosystem-resolution.md). Read the @@ -118,7 +127,7 @@ tree holds the present): ```bash raw="${TMPDIR:-/tmp}/hotspots.$$" -git log --since="90 days ago" --pretty=format: --name-only | +git log --since='90 days ago' --pretty=format: --name-only | grep -v '^$' | grep -Ev "$excludes" | sort | uniq -c | sort -rn | head -50 | while read -r churn f; do [ -f "/$f" ] || continue diff --git a/plugins/improvement/skills/setup/SKILL.md b/plugins/improvement/skills/setup/SKILL.md index dc35d95de5c..e8b1ee2c884 100644 --- a/plugins/improvement/skills/setup/SKILL.md +++ b/plugins/improvement/skills/setup/SKILL.md @@ -71,7 +71,11 @@ per FAIL. Modify nothing, and do not run a scan. That is `/improvement:find`. `evidence_sources_file` cannot be read, WARN it was not considered rather than presenting the readable layers as the whole effective config. 2. **Old files.** Retired conventions: run - `bash "${CLAUDE_PLUGIN_ROOT}/lib/check-retirements.sh" --manifest "${CLAUDE_PLUGIN_ROOT}/retirements.yaml"`. + `bash "${CLAUDE_PLUGIN_ROOT}/lib/check-retirements.sh" --manifest "${CLAUDE_PLUGIN_ROOT}/retirements.yaml" --root ""`, + with `` the path `git rev-parse --show-toplevel` printed (the root every other read in + this skill anchors at). Never leave out `--root`: the helper otherwise checks + `${CLAUDE_PROJECT_DIR}` first, a subdirectory when the session started in one. When the root + does not resolve, the root rule already skips these layers: skip this step and say so. Exit 0 → PASS. Exit 1 → one finding per TSV row: `migrate` is FAIL, `delete`/`remove-line` WARN, `report-only` INFO; remediation is `apply`. Exit 2 → FAIL, never silent. Bash unavailable → report the step UNKNOWN with remediation, never green. The records cover @@ -129,8 +133,8 @@ the user's yes for that file, so the config ends in one home, never two: keeping the new file's own keys, then resolve that layer again from the new file alone and check every moved key resolves the value the old file gave. Only when all match and the operator confirms the result, run - `bash "${CLAUDE_PLUGIN_ROOT}/lib/check-retirements.sh" --manifest "${CLAUDE_PLUGIN_ROOT}/retirements.yaml" --clean --i-migrated`, - which deletes the old file; a tracked one stays deleted in the working tree, to commit with the + `bash "${CLAUDE_PLUGIN_ROOT}/lib/check-retirements.sh" --manifest "${CLAUDE_PLUGIN_ROOT}/retirements.yaml" --root "" --clean --i-migrated`, + with the same `` as `check` step 2, which deletes the old file; a tracked one stays deleted in the working tree, to commit with the new file. On any mismatch, keep the old file and report the key. Before writing the personal file, run `git check-ignore -v /improvement.local.yaml`: when it is not ignored, write nothing for that file and recommend the `/**/*.local.*` line. Re-run detection last and @@ -198,8 +202,9 @@ to re-run this setup to reconfigure. provisioning the server is the consumer's own MCP setup. - Write `userConfig`, user settings, `pluginConfigs`, or the consumer's `.gitignore`. Beyond the team file it writes only the targets of a confirmed move of an old file. -- Write machine-local state. Configuration lives in the consumer's tracked file, never in the - plugin directory or the plugin data directory. +- Write into the plugin directory or the plugin data directory. Configuration lives in the + consumer's team and personal files and, after a confirmed move of the old user-global file, the + user's own `evidence_sources_file`. ## Gotchas From c11e04de4245c1befdf9eaa8e1be219ad1cdaa77 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Sat, 21 Nov 2026 20:25:45 -0500 Subject: [PATCH 3/3] fix(improvement): give find config evals a git root and drop find_size_band options The find config cases (open-cap-stops, run-cap-from-config, personal-cap-cannot-raise) seeded no git tree, so under the root rule in reference/config.md the team and personal layers were not applicable and their layer graders could not pass. Each scaffold now commits the seeded tree as seed-ledger-cli.sh does, the personal case ignores docs/conventions/**/*.local.* so its file gets the ignored verdict, and the three cases allow Bash, as the setup-check cases do, so the model can run git rev-parse --show-toplevel and the tracked and ignored checks. claude plugin validate rejected the manifest: a userConfig field with options needs a default among them or required: true, and a plugin whose options break that rule fails to load. find_size_band has no manifest default by design (an unset option lets the old ~/.claude/improvement.md supply the value), so options is dropped; find reports any other value as malformed. Comment lint flagged the scaffold headers and the retirements.yaml header: the scaffold intent lives in each case's description, the retirements contract in docs/contracts/retired-conventions/README.md. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01RAoAtUnz4WHB5auUnwQYq7 --- plugins/improvement/.claude-plugin/plugin.json | 3 +-- .../evals/find-unattended-open-cap-stops/prompt.md | 4 ++-- .../evals/find-unattended-open-cap-stops/scaffold.sh | 7 +++++-- .../find-unattended-personal-cap-cannot-raise/prompt.md | 4 ++-- .../find-unattended-personal-cap-cannot-raise/scaffold.sh | 8 ++++++++ .../evals/find-unattended-run-cap-from-config/prompt.md | 4 ++-- .../evals/find-unattended-run-cap-from-config/scaffold.sh | 5 +++++ .../evals/setup-check-both-new-wins/scaffold.sh | 3 --- .../evals/setup-check-new-layer-only/scaffold.sh | 2 -- .../evals/setup-check-old-file-warns/scaffold.sh | 3 --- .../evals/setup-check-zero-config-info/scaffold.sh | 2 -- plugins/improvement/retirements.yaml | 5 ----- 12 files changed, 25 insertions(+), 25 deletions(-) diff --git a/plugins/improvement/.claude-plugin/plugin.json b/plugins/improvement/.claude-plugin/plugin.json index 561e69a75f5..94e3c9eccd3 100644 --- a/plugins/improvement/.claude-plugin/plugin.json +++ b/plugins/improvement/.claude-plugin/plugin.json @@ -64,8 +64,7 @@ "find_size_band": { "type": "string", "title": "Unattended size band", - "description": "Candidate sizes an unattended run ranks: all, small, medium or large. Unset: all.", - "options": ["all", "small", "medium", "large"] + "description": "Candidate sizes an unattended run ranks: all, small, medium or large. Unset: all." }, "find_scope": { "type": "string", diff --git a/plugins/improvement/evals/find-unattended-open-cap-stops/prompt.md b/plugins/improvement/evals/find-unattended-open-cap-stops/prompt.md index 3d94fa8fc2e..c56637a8e1e 100644 --- a/plugins/improvement/evals/find-unattended-open-cap-stops/prompt.md +++ b/plugins/improvement/evals/find-unattended-open-cap-stops/prompt.md @@ -1,9 +1,9 @@ --- -description: "Unattended find with the open cap reached. Narration: like find-unattended-files-capped, the prompt gives the state key and the tracker's state as facts and switches writes and filing off, so the case grades the declared plan. Five open items already carry the source: improvement-find label, the only config is an old-location .claude/improvement.md that sets no find_open_item_cap (default 5), and the prompt asks for up to 3 filings. The reply asks no question (no-ask-tool), writes nothing into the repository (no-repo-write), edits nothing (no-edit), names the open cap as why nothing is filed (names-open-cap), prints the dual-read warning line naming the old file, docs/conventions/improvement.yaml and /improvement:setup apply (warns-old-file), and plans no filing despite the prompt's cap of 3 (files-nothing-at-open-cap, llm). The real tracker count is unmeasured. Needs --scaffold and --allow-tools Write Edit so the write graders can fail." +description: "Unattended find with the open cap reached. Narration: like find-unattended-files-capped, the prompt gives the state key and the tracker's state as facts and switches writes and filing off, so the case grades the declared plan. Five open items already carry the source: improvement-find label, the only config is an old-location .claude/improvement.md that sets no find_open_item_cap (default 5), and the prompt asks for up to 3 filings. The reply asks no question (no-ask-tool), writes nothing into the repository (no-repo-write), edits nothing (no-edit), names the open cap as why nothing is filed (names-open-cap), prints the dual-read warning line naming the old file, docs/conventions/improvement.yaml and /improvement:setup apply (warns-old-file), and plans no filing despite the prompt's cap of 3 (files-nothing-at-open-cap, llm). The real tracker count is unmeasured. Needs --scaffold and --allow-tools Bash Write Edit: Bash for the git root and tracked or ignored checks, Write and Edit so the write graders can fail." tags: [find, unattended, narration, no-network] max_turns: 25 timeout_seconds: 900 -allowed_tools: [Read, Glob, Grep, Skill, Write, Edit, AskUserQuestion] +allowed_tools: [Read, Glob, Grep, Bash, Skill, Write, Edit, AskUserQuestion] expected_outcome: "The run asks nothing, prints one warning naming the old .claude/improvement.md, docs/conventions/improvement.yaml as where to move it and /improvement:setup apply, still ranks candidates for the report, and files nothing because five open items carrying the source: improvement-find label meet the open cap of 5, which the prompt's 'file at most 3' does not raise; it says so." --- diff --git a/plugins/improvement/evals/find-unattended-open-cap-stops/scaffold.sh b/plugins/improvement/evals/find-unattended-open-cap-stops/scaffold.sh index 9580c9eed77..b8cf262844e 100755 --- a/plugins/improvement/evals/find-unattended-open-cap-stops/scaffold.sh +++ b/plugins/improvement/evals/find-unattended-open-cap-stops/scaffold.sh @@ -3,8 +3,6 @@ set -euo pipefail bash "$(dirname "${BASH_SOURCE[0]}")/../fixtures/seed-checkout-service.sh" -# An old-location team file, read through the dual-read window. It sets only the default -# churn window, so the open cap stays at its default of 5. mkdir -p .claude cat > .claude/improvement.md <<'CONFIG' # improvement config @@ -13,3 +11,8 @@ cat > .claude/improvement.md <<'CONFIG' churn_window: "90 days ago" ``` CONFIG + +git init -q -b main +git add -A +git -c user.name=Checkout -c user.email=checkout@example.invalid -c commit.gpgsign=false \ + commit -q -m "Add checkout service" diff --git a/plugins/improvement/evals/find-unattended-personal-cap-cannot-raise/prompt.md b/plugins/improvement/evals/find-unattended-personal-cap-cannot-raise/prompt.md index 2148fd9b1a6..bbf708bb433 100644 --- a/plugins/improvement/evals/find-unattended-personal-cap-cannot-raise/prompt.md +++ b/plugins/improvement/evals/find-unattended-personal-cap-cannot-raise/prompt.md @@ -1,9 +1,9 @@ --- -description: "Unattended find whose personal config tries to raise the open cap. Narration: a scaffolded personal file, docs/conventions/improvement.local.yaml, sets find_open_item_cap to 9, no team layer exists, and the prompt gives five open items carrying the source label as facts and switches writes and filing off. The reply asks nothing (no-ask-tool), writes and edits nothing in the repository (no-repo-write, no-edit), reads the personal layer (reads-personal-layer), and files nothing because the cap stays 5 (personal-value-does-not-raise-cap, llm). Real filing is unmeasured. Needs --scaffold and --allow-tools Write Edit so the write graders can fail." +description: "Unattended find whose personal config tries to raise the open cap. Narration: a scaffolded personal file, docs/conventions/improvement.local.yaml, sets find_open_item_cap to 9, no team layer exists, and the prompt gives five open items carrying the source label as facts and switches writes and filing off. The reply asks nothing (no-ask-tool), writes and edits nothing in the repository (no-repo-write, no-edit), reads the personal layer (reads-personal-layer), and files nothing because the cap stays 5 (personal-value-does-not-raise-cap, llm). Real filing is unmeasured. Needs --scaffold and --allow-tools Bash Write Edit: Bash for the git root and tracked or ignored checks, Write and Edit so the write graders can fail." tags: [find, unattended, narration, no-network] max_turns: 25 timeout_seconds: 900 -allowed_tools: [Read, Glob, Grep, Skill, Write, Edit, AskUserQuestion] +allowed_tools: [Read, Glob, Grep, Bash, Skill, Write, Edit, AskUserQuestion] expected_outcome: "The run asks nothing, keeps the open cap at the default 5 despite the personal value of 9, and files nothing because five open items already carry the label." --- diff --git a/plugins/improvement/evals/find-unattended-personal-cap-cannot-raise/scaffold.sh b/plugins/improvement/evals/find-unattended-personal-cap-cannot-raise/scaffold.sh index f0de59d3be0..0550f465fd1 100755 --- a/plugins/improvement/evals/find-unattended-personal-cap-cannot-raise/scaffold.sh +++ b/plugins/improvement/evals/find-unattended-personal-cap-cannot-raise/scaffold.sh @@ -7,3 +7,11 @@ mkdir -p docs/conventions cat > docs/conventions/improvement.local.yaml <<'CONFIG' find_open_item_cap: 9 CONFIG +cat > .gitignore <<'IGNORE' +docs/conventions/**/*.local.* +IGNORE + +git init -q -b main +git add -A +git -c user.name=Checkout -c user.email=checkout@example.invalid -c commit.gpgsign=false \ + commit -q -m "Add checkout service" diff --git a/plugins/improvement/evals/find-unattended-run-cap-from-config/prompt.md b/plugins/improvement/evals/find-unattended-run-cap-from-config/prompt.md index c28c57601a8..ebfcb95feda 100644 --- a/plugins/improvement/evals/find-unattended-run-cap-from-config/prompt.md +++ b/plugins/improvement/evals/find-unattended-run-cap-from-config/prompt.md @@ -1,9 +1,9 @@ --- -description: "Unattended find whose team config sets the per-run filing cap. Narration: a scaffolded team file, docs/conventions/improvement.yaml, sets find_run_item_cap to 1, and the prompt gives the tracker's state as facts and switches writes and filing off. The reply asks nothing (no-ask-tool), writes and edits nothing in the repository (no-repo-write, no-edit), reads the team layer (reads-team-layer), and plans one filing because the configured cap is 1 (files-one-item-from-config, llm). Real filing is unmeasured. Needs --scaffold and --allow-tools Write Edit so the write graders can fail." +description: "Unattended find whose team config sets the per-run filing cap. Narration: a scaffolded team file, docs/conventions/improvement.yaml, sets find_run_item_cap to 1, and the prompt gives the tracker's state as facts and switches writes and filing off. The reply asks nothing (no-ask-tool), writes and edits nothing in the repository (no-repo-write, no-edit), reads the team layer (reads-team-layer), and plans one filing because the configured cap is 1 (files-one-item-from-config, llm). Real filing is unmeasured. Needs --scaffold and --allow-tools Bash Write Edit: Bash for the git root and tracked or ignored checks, Write and Edit so the write graders can fail." tags: [find, unattended, narration, no-network] max_turns: 25 timeout_seconds: 900 -allowed_tools: [Read, Glob, Grep, Skill, Write, Edit, AskUserQuestion] +allowed_tools: [Read, Glob, Grep, Bash, Skill, Write, Edit, AskUserQuestion] expected_outcome: "The run asks nothing, reads find_run_item_cap: 1 from the team config, and plans to file exactly one item under source: improvement-find, leaving the other candidates in the report." --- diff --git a/plugins/improvement/evals/find-unattended-run-cap-from-config/scaffold.sh b/plugins/improvement/evals/find-unattended-run-cap-from-config/scaffold.sh index c0221714123..8ef7741e7a2 100755 --- a/plugins/improvement/evals/find-unattended-run-cap-from-config/scaffold.sh +++ b/plugins/improvement/evals/find-unattended-run-cap-from-config/scaffold.sh @@ -7,3 +7,8 @@ mkdir -p docs/conventions cat > docs/conventions/improvement.yaml <<'CONFIG' find_run_item_cap: 1 CONFIG + +git init -q -b main +git add -A +git -c user.name=Checkout -c user.email=checkout@example.invalid -c commit.gpgsign=false \ + commit -q -m "Add checkout service" diff --git a/plugins/improvement/evals/setup-check-both-new-wins/scaffold.sh b/plugins/improvement/evals/setup-check-both-new-wins/scaffold.sh index 3cbd244770a..ebdd3b73943 100755 --- a/plugins/improvement/evals/setup-check-both-new-wins/scaffold.sh +++ b/plugins/improvement/evals/setup-check-both-new-wins/scaffold.sh @@ -1,7 +1,4 @@ #!/usr/bin/env bash -# Seeds the ledger-cli repository with both team files: the new docs/conventions/improvement.yaml -# (churn_window 30 days ago) and the old .claude/improvement.md (churn_window 180 days ago plus -# find_size_band small, a key the new file does not set). set -euo pipefail bash "$(dirname "${BASH_SOURCE[0]}")/../fixtures/seed-ledger-cli.sh" diff --git a/plugins/improvement/evals/setup-check-new-layer-only/scaffold.sh b/plugins/improvement/evals/setup-check-new-layer-only/scaffold.sh index c2a842fcc8d..35f108bf465 100755 --- a/plugins/improvement/evals/setup-check-new-layer-only/scaffold.sh +++ b/plugins/improvement/evals/setup-check-new-layer-only/scaffold.sh @@ -1,6 +1,4 @@ #!/usr/bin/env bash -# Seeds the ledger-cli repository with only the new team file, docs/conventions/improvement.yaml, -# and no old .claude/improvement.md or .claude/improvement.local.md. set -euo pipefail bash "$(dirname "${BASH_SOURCE[0]}")/../fixtures/seed-ledger-cli.sh" diff --git a/plugins/improvement/evals/setup-check-old-file-warns/scaffold.sh b/plugins/improvement/evals/setup-check-old-file-warns/scaffold.sh index 82d3c70f63b..ffe64f3fc7d 100755 --- a/plugins/improvement/evals/setup-check-old-file-warns/scaffold.sh +++ b/plugins/improvement/evals/setup-check-old-file-warns/scaffold.sh @@ -1,7 +1,4 @@ #!/usr/bin/env bash -# Seeds the ledger-cli repository with only the old files, .claude/improvement.md (team) and -# .claude/improvement.local.md (personal), and no docs/conventions/improvement*.yaml, so the -# dual-read window reads both and the retirement records improvement-r001 and -r002 fire. set -euo pipefail bash "$(dirname "${BASH_SOURCE[0]}")/../fixtures/seed-ledger-cli.sh" diff --git a/plugins/improvement/evals/setup-check-zero-config-info/scaffold.sh b/plugins/improvement/evals/setup-check-zero-config-info/scaffold.sh index f647e79c7a5..2cadeb99356 100755 --- a/plugins/improvement/evals/setup-check-zero-config-info/scaffold.sh +++ b/plugins/improvement/evals/setup-check-zero-config-info/scaffold.sh @@ -1,6 +1,4 @@ #!/usr/bin/env bash -# Seeds the workspace root as the ledger-cli repository, which declares no improvement config in -# any layer: no docs/conventions/improvement.yaml, no improvement.local.yaml and no old .claude/ file. set -euo pipefail bash "$(dirname "${BASH_SOURCE[0]}")/../fixtures/seed-ledger-cli.sh" diff --git a/plugins/improvement/retirements.yaml b/plugins/improvement/retirements.yaml index a86cb70ae3b..2ea450b5813 100644 --- a/plugins/improvement/retirements.yaml +++ b/plugins/improvement/retirements.yaml @@ -1,8 +1,3 @@ -# Retired consumer-facing conventions for the improvement plugin. -# Append-only: records are never deleted and their detection fields are never -# edited once published (demote with `status: report-only` instead). Schema and -# helper contract: docs/contracts/retired-conventions/README.md in the -# consuming marketplace; evaluated by lib/check-retirements.sh from setup. --- id: improvement-r001 retired: 2026-11-22