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,12 @@
---
bump: minor
---

### Changed

- **Declined findings live at the config-cascade layers.** The team layer is now `<home>/instruction-placement.yaml` (default home `docs/conventions`), checked against the new `schemas/instruction-placement.schema.json`, and the personal override is `<home>/instruction-placement.local.yaml`. `audit`, `delta` and `realign` read these, `realign` writes a decline to the team file, and the audit's scan set excludes both. There is no user-global file layer and no `userConfig` option for a decline ([#18012](https://github.com/melodic-software/claude-code-plugins/issues/18012)).
- **Old paths are still read, with a warning.** While `.claude/instruction-placement.md`, `.claude/instruction-placement.local.md` or `~/.claude/instruction-placement.md` exists, it is read for its layer when no new file supplies that layer, and every run prints one warning naming the old file, the new location and the command that moves it. When the new file exists too, the new file wins and the warning lists the ids only the old file carries.

### Added

- **`/instruction-placement:setup apply migrate-config`.** Moves each old suppression file to its new location behind a preview and a yes, checks the new location resolves the same entries, then deletes the old file. `setup check` reports each old file it finds.
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
bump: patch
---

### Changed

- **The repo-sweep hygiene catalog names instruction-placement's new suppression file.** The `instruction-placement` step's notes and claim now say realign writes a decline to `<home>/instruction-placement.yaml` (default home `docs/conventions`) instead of `.claude/instruction-placement.md`, following that plugin's move to the config-cascade layers ([#18012](https://github.com/melodic-software/claude-code-plugins/issues/18012)).
6 changes: 6 additions & 0 deletions docs/contracts/config-cascade/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,12 @@ adding an optional layer or relaxing a rule additively is a minor bump.

No contract change.

- **`instruction-placement` moves to the location axis.** Its row names the team file
`<home>/instruction-placement.yaml` and the personal override `<home>/instruction-placement.local.yaml`,
with no `userConfig` option and no user-global file; the old `.claude/` and `~/.claude/` paths are
still read, with a warning, until `/instruction-placement:setup apply migrate-config` moves them
(#18012). It leaves the not-yet-migrated list. The layering axis is unchanged, so
`contract_version` stays.
- **The `docs-naming` row reads `userConfig`, not `~/.claude/docs-naming.json`.** Its per-person
layer is the `file_names` option; the old user files are read only while it is unset or invalid,
with a warning, until a later change removes the read. The layering axis is unchanged, so
Expand Down
5 changes: 2 additions & 3 deletions docs/contracts/config-cascade/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -717,7 +717,7 @@ its conformance cell.
| `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` |
| `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) |
| `instruction-placement` | team-only | team: `<home>/instruction-placement.yaml` (`<home>` from the convention-home pointer line, default `docs/conventions`; schema `plugins/instruction-placement/schemas/instruction-placement.schema.json`); personal override `<home>/instruction-placement.local.yaml`; no `userConfig` option and no user-global file | team + personal override | team on conflict (policy-floor) | per-key | conforms to [ADR 0075](../../adr/0075-resolve-plugin-settings-through-one-four-layer-cascade-and-a-bound-convention-home.md). The old paths, `.claude/instruction-placement.md` for the team layer and `.claude/instruction-placement.local.md` and `~/.claude/instruction-placement.md` for the personal one, are still read while no new file supplies their layer, with a warning on every run that names `/instruction-placement:setup apply migrate-config`; that action moves each old file after a yes and deletes it. 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) |
| `multi-agent` | no-floor | team: `<home>/multi-agent.yaml`, `<home>` being the bound convention home, else `docs/conventions`; user-global `~/.claude/multi-agent.yaml`; personal override `.claude/multi-agent.local.yaml` | all three | later layer | per-key | the team file is validated by `plugins/multi-agent/schemas/multi-agent.schema.json`. The old team locations, the config block in `docs/conventions/multi-agent.md` and `.claude/multi-agent.yaml`, are not read; `/multi-agent:setup check` names each one it finds, and while the YAML is absent the first `/multi-agent:setup apply --layer team` write copies one old file's keys into it, leaving that file in place. Rule 5 holds: a layer that does not parse or names another schema is skipped and named, and an unknown key or a value outside its allowed set is reported and inert. No policy-floor class: every key is a routing dial, and turning the fan-out guard off is a documented opt-in on whichever layer sets it. Keys owned by [`plugins/multi-agent/reference/config.md`](../../../plugins/multi-agent/reference/config.md); resolved by `plugins/multi-agent/scripts/resolve-roles.sh`, read by `/multi-agent:route`, `/multi-agent:audit-defaults` and `/multi-agent:setup check`; written by `/multi-agent:setup apply` (any of the three layers, after a preview and an explicit yes) |
| `multi-agent` (`verification`) | team-only | team: `<home>/multi-agent.yaml`, the role map's team file (`<home>` from the convention-home pointer line at the default branch, default `docs/conventions`; schema `plugins/multi-agent/schemas/multi-agent.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, and the user-global and personal files do not set it: `scripts/resolve-roles.sh` passes over the keys in every layer, and `/multi-agent:setup apply` writes them to the team layer only. `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 `/multi-agent:audit-defaults`. This row covers `verification` and `verification_skills` |
Expand Down Expand Up @@ -866,15 +866,14 @@ tables above already declare policy-floor.
| `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 |
| `repo-fleet-hygiene` | `.claude/repo-fleet-hygiene.conf` | key-value conf | user-global and team only |
| `review`, `planning` | `.claude/standards.yaml` | YAML | roots `<standards_dir>/`; 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`, `instruction-placement`, 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
9 changes: 6 additions & 3 deletions plugins/instruction-placement/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ is what a decline costs to make twice:
|---|---|---|---|
| Findings (`audit` writes, `realign` updates statuses) | `.work/instruction-placement/<branch-slug>/findings.md` | Memory, branch-keyed | No |
| Spine baseline (`delta` reads and captures) | `.work/instruction-placement/<branch-slug>/baselines/spine-baseline.md` | Memory, branch-keyed | No |
| Declined findings (`realign` offers, `audit` and `delta` read) | `.claude/instruction-placement.md` | Tracked, three cascade layers | **Yes, once committed** |
| Declined findings (`realign` offers, `audit` and `delta` read) | `<home>/instruction-placement.yaml` (default home `docs/conventions`) | Tracked team layer, gitignored personal override | **Yes, once committed** |

The first two are evidence and a diff spine: recomputed by the next run, and worthless outside the
checkout that produced them. The third is the operator's judgment, which is expensive to reproduce
Expand Down Expand Up @@ -229,8 +229,11 @@ Conditions that should change this plugin, recorded so they are acted on rather

The options below are personal, enable-time dials. The one setting that is policy rather than taste,
the record of findings the operator has declined, lives on the tracked cascade surface
`.claude/instruction-placement.md` instead, whose keys, layers, and policy-floor merge are owned by
[`reference/consumer-config.md`](reference/consumer-config.md).
`<home>/instruction-placement.yaml` (default home `docs/conventions`) instead, whose keys, layers,
and policy-floor merge are owned by [`reference/consumer-config.md`](reference/consumer-config.md).
A file at an old path (`.claude/instruction-placement.md`, its `.local.md`, or
`~/.claude/instruction-placement.md`) is still read, with a warning, until
`/instruction-placement:setup apply migrate-config` moves it.

<!-- BEGIN GENERATED: plugin options. Edit plugin.json, then run scripts/sync-plugin-options-docs.py -->

Expand Down
4 changes: 2 additions & 2 deletions plugins/instruction-placement/context/findings-artifact.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ The findings artifact is **branch-scoped and checkout-local by design**. Its lin
true for the branch it was derived on, and a removed worktree or deleted memory root loses it. That
is fine for evidence and classifications, which are recomputed. It is not fine for operator
decisions, which is why a `declined` decision is also written to the tracked finding-suppression
surface `.claude/instruction-placement.md`
surface `<home>/instruction-placement.yaml`
([`../reference/consumer-config.md`](../reference/consumer-config.md)), where git carries it to
every other checkout, and why an applied move is reconstructable from the repository's own git
history regardless.
Expand Down Expand Up @@ -209,7 +209,7 @@ Identifiers are stable across runs and never reused after a finding is dropped.
## Finding ids and their constituents

A `declined` decision outlives the artifact that carried it, and the surface it outlives into is the
tracked finding-suppression record `.claude/instruction-placement.md`. That convention owns the
tracked finding-suppression record `<home>/instruction-placement.yaml`. That convention owns the
entry's keys, the `finding_id` hash, the `anchor/v<N>` versioning, and the four entry dispositions.
**What each constituent holds for a placement finding is owned here**, because deriving it is this
plugin's business and nobody else's.
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
schema_version: "1.1"
name: au-suppression-file-not-a-candidate
graders:
- name: 'surface-excluded'
type: 'regex'
pattern: '^(?=[^\n]*\binstruction-placement\.yaml\b)(?=[^\n]*(?:\bexclud|\bnot (?:a )?candidate|\bdropped\b|\bleft out\b|\bskipped\b|\bnot proposed\b|\bout of the candidate set\b))'
flags: 'im'
target: 'last_message'
- name: 'meets-expectations'
type: 'llm'
criteria: 'Read the reply as the account of what the audit run does with the stated repository. PASS only if it satisfies every point: (1) Raises no finding on docs/conventions/instruction-placement.yaml and says the detector''s candidate on it is dropped because that file is the suppression surface, excluded from the scan set; (2) Still counts that file in the detector''s coverage numbers rather than removing it from what was read; (3) Suppresses the Deploy conventions finding, reporting its reason, date (2026-11-02) and the team layer; (4) Still proposes the Lint rules finding with its `paths: **/*.ts` glob, and writes neither docs/conventions/instruction-placement.yaml nor any instruction file. A point counts only when the reply states it or plainly acts on it; it need not use the same words. FAIL if any point is missing or contradicted.'
Loading
Loading