Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -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.
7 changes: 3 additions & 4 deletions docs/contracts/config-cascade/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -715,7 +715,7 @@ its conformance cell.
| `architecture` (`record-decision`) | no-floor | team `<home>/architecture.yaml`, personal override `<home>/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: `<home>/architecture.yaml` (`<home>` 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.<skill>` beats `verification`. `lib/read-verification.sh` (the plugin's copy) reads the file at `origin/<default>` 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 `<home>/architecture.yaml`, personal override `<home>/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 `<home>/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 `<home>/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, `<home>/authoring-formats/README.md` (the pointer line binds `<home>`) | 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 `<home>` 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) |
Expand Down Expand Up @@ -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 `<home>` 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 `<home>` 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 |
Expand Down Expand Up @@ -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 |
Expand All @@ -874,7 +873,7 @@ tables above already declare policy-floor.
| `toolchain` | `.claude/ecosystems/<ecosystem>.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`' `<standards_dir>/`, `songwriting`'s templates, and the `work-items` tracker binding and
Expand Down
1 change: 1 addition & 0 deletions docs/contracts/retired-conventions/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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: `` `<plugin>` `` \| count \| `YYYY-MM-DD`. The convention-doc
expression-form pilot was `plugin-quality`'s `.claude/plugin-quality.md` (ADR 0018), retired by that
Expand Down
62 changes: 62 additions & 0 deletions plugins/improvement/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
Expand Up @@ -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."
},
Comment thread
melodic-automation-lanes[bot] marked this conversation as resolved.
Resolved
"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
},
Comment on lines +29 to +34

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

manifest userConfig.churn_exclude: flag, free ERE patterns put into a shell command

This new option is a string with multiple: true, so it is not a selector and not inert. Its entries are joined into $excludes and passed to grep -Ev "$excludes" in skills/find/context/hotspots.md:57 and :122. The value comes from the user's own plugin settings, and the base ~/.claude/improvement.md already supplied the same key, so this flag shows no new attacker path. It is reported under the manifest default-deny rule.

severity: IMPORTANT

claude-lane: claude-security-review

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

pr-unblock / address-feedback: UNCERTAIN, left open

Evidence: plugins/improvement/skills/find/context/hotspots.md:81

This is a manifest default-deny flag on a security surface. The finding names no fix, and it says the value comes from the user's own settings and shows no new attacker path. A list of free ERE patterns cannot become a selector, so only a person can accept the flag. In the same round as the churn_window fix, the hotspot recipe now leaves out any churn_exclude entry that holds a single quote or a newline and reports it as malformed with its layer. Such an entry could otherwise break out of the single-quoted excludes assignment that feeds grep -Ev. Left open for a person to accept the remaining flag.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Accepted by the PR lane session. Exposed surface today: none outside the operator. The patterns come only from the operator's own plugin settings, the same per-user scope the old ~/.claude/improvement.md supplied, and the recipe now drops an entry holding a single quote or newline. No permission, trust boundary or cost changes. Condition: if automation or untrusted input ever fills this option, pass it through a file instead of a shell string.

"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
},
Comment on lines +40 to +45

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

manifest userConfig.find_open_item_cap: flag, a number that reaches a command argument

This key is a guard. It has no manifest default, and the cascade lets userConfig only lower the team cap (reference/config.md Merge semantics). So the guard is not widened. It is still not inert, because the value reaches a command: /work-items:track list --label "<source label>" --state open --limit <open cap + 1> in skills/find/context/unattended.md:190-191. The value is a number with min: 0, so it carries little injection risk. It is reported under the manifest default-deny rule.

severity: IMPORTANT

claude-lane: claude-security-review

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

pr-unblock / address-feedback: UNCERTAIN, left open

Evidence: plugins/improvement/.claude-plugin/plugin.json:40, plugins/improvement/reference/config.md:79

The finding reports the key under the manifest default-deny rule. It also says the guard is not widened: the merge semantics in reference/config.md let userConfig only lower the cap. The value is a number with min 0, so it reaches the --limit argument only as a number. No change to the manifest turns a number cap into a selector or makes it inert. This is a security-surface policy flag, and accepting it is a person's decision. Left open for that decision.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Accepted by the PR lane session. Exposed surface today: none outside the operator. The value is a number with min 0 from the operator's own settings, and the cascade lets it only lower the team cap, so the guard is not widened. No permission, trust boundary or cost changes.

"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."
},
Comment thread
melodic-automation-lanes[bot] marked this conversation as resolved.
Resolved
"find_scope": {
"type": "string",
"title": "Unattended scope",
"description": "What an unattended run scans: repo, or a target /improvement:find accepts. Unset: repo."
},
Comment on lines +69 to +73

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

manifest userConfig.find_scope: flag, a free string that sets what an unattended run scans

This key is a string with no options, and its value is "repo, or a target /improvement:find accepts". It is substituted into skills/find/SKILL.md:159 and skills/setup/SKILL.md:50, and sets the scan target of unattended runs (skills/find/context/unattended.md:30). The value comes from the user's own settings, and the base ~/.claude/improvement.md already supplied the same key, so this flag shows no new attacker path. It is reported under the manifest default-deny rule.

severity: IMPORTANT

claude-lane: claude-security-review

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

pr-unblock / address-feedback: UNCERTAIN, left open

Evidence: plugins/improvement/.claude-plugin/plugin.json:70, plugins/improvement/reference/config.md:130

The finding reports find_scope under the manifest default-deny rule and says it shows no new attacker path, since the base user-global file already supplied the same key. The key's contract allows repo or any target /improvement:find accepts, so it cannot be cut down to an options list without dropping a documented use. The finding names no fix. Accepting a free-string flag on a security surface is a person's decision, so the thread is left open for it.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Accepted by the PR lane session. Exposed surface today: none outside the operator. find_scope comes only from the operator's own settings, the same per-user scope the old ~/.claude/improvement.md supplied, and it picks what the operator's own run scans. No permission, trust boundary or cost changes. Condition: if automation or untrusted input ever fills it, restrict it to the targets /improvement:find accepts.

"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."
}
Comment on lines +79 to +83

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

manifest userConfig.evidence_sources_file: flag, a file-typed path that names the MCP servers Tier 2 queries

This new file option is a filesystem path the skills Read (skills/find/SKILL.md:161, skills/setup/SKILL.md:52, :71). Its evidence_sources entries name the MCP telemetry servers /improvement:find queries for Tier 2 evidence, and they merge under the repository's own declarations per source name. The path and the file both come from the user's own settings, and the base user-global evidence_sources map came from the same per-user scope, so this flag shows no new attacker path. It is reported under the manifest default-deny rule, because a path-valued key is never a selector or an inert key.

severity: IMPORTANT

claude-lane: claude-security-review

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

pr-unblock / address-feedback: UNCERTAIN, left open

Evidence: plugins/improvement/.claude-plugin/plugin.json:80, plugins/improvement/reference/config.md:36

The finding reports the file-typed evidence_sources_file option under the manifest default-deny rule, because a path-valued key is never a selector or inert. It also says the path and file come from the user's own settings, the same per-user scope as the old user-global evidence_sources map. reference/config.md explains why this option exists: userConfig cannot hold the nested evidence_sources map. Removing the option would drop that layer. The finding names no fix, so accepting the flag is a person's decision. Left open for it.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Accepted by the PR lane session. Exposed surface today: none outside the operator. The path and the file come only from the operator's own settings, the same per-user scope as the old user-global evidence_sources map, and they name the MCP servers the operator already configured. No permission, trust boundary or cost changes.

}
}
Loading
Loading