diff --git a/.changes/instruction-placement/work-resolve-issue-issue-18012-44964532394-1-690c26c6.md b/.changes/instruction-placement/work-resolve-issue-issue-18012-44964532394-1-690c26c6.md new file mode 100644 index 00000000000..b286bc9e995 --- /dev/null +++ b/.changes/instruction-placement/work-resolve-issue-issue-18012-44964532394-1-690c26c6.md @@ -0,0 +1,12 @@ +--- +bump: minor +--- + +### Changed + +- **Declined findings live at the config-cascade layers.** The team layer is now `/instruction-placement.yaml` (default home `docs/conventions`), checked against the new `schemas/instruction-placement.schema.json`, and the personal override is `/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. diff --git a/.changes/playbooks/work-resolve-issue-issue-18012-44964532394-1-66d94034.md b/.changes/playbooks/work-resolve-issue-issue-18012-44964532394-1-66d94034.md new file mode 100644 index 00000000000..8d71bb6f24c --- /dev/null +++ b/.changes/playbooks/work-resolve-issue-issue-18012-44964532394-1-66d94034.md @@ -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 `/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)). diff --git a/docs/contracts/config-cascade/CHANGELOG.md b/docs/contracts/config-cascade/CHANGELOG.md index d7311f3475f..7c45a07fee1 100644 --- a/docs/contracts/config-cascade/CHANGELOG.md +++ b/docs/contracts/config-cascade/CHANGELOG.md @@ -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 + `/instruction-placement.yaml` and the personal override `/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 diff --git a/docs/contracts/config-cascade/README.md b/docs/contracts/config-cascade/README.md index 7a35416edb2..5d69637955d 100644 --- a/docs/contracts/config-cascade/README.md +++ b/docs/contracts/config-cascade/README.md @@ -717,7 +717,7 @@ its conformance cell. | `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` | | `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) | +| `instruction-placement` | team-only | team: `/instruction-placement.yaml` (`` from the convention-home pointer line, default `docs/conventions`; schema `plugins/instruction-placement/schemas/instruction-placement.schema.json`); personal override `/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: `/multi-agent.yaml`, `` 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: `/multi-agent.yaml`, the role map's team file (`` 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.` 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 `/multi-agent:audit-defaults`. This row covers `verification` and `verification_skills` | @@ -866,7 +866,6 @@ 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 | @@ -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`, `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`' `/`, `songwriting`'s templates, and the `work-items` tracker binding and diff --git a/plugins/instruction-placement/README.md b/plugins/instruction-placement/README.md index 04831df59fd..dcc094171af 100644 --- a/plugins/instruction-placement/README.md +++ b/plugins/instruction-placement/README.md @@ -76,7 +76,7 @@ is what a decline costs to make twice: |---|---|---|---| | Findings (`audit` writes, `realign` updates statuses) | `.work/instruction-placement//findings.md` | Memory, branch-keyed | No | | Spine baseline (`delta` reads and captures) | `.work/instruction-placement//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) | `/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 @@ -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). +`/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. diff --git a/plugins/instruction-placement/context/findings-artifact.md b/plugins/instruction-placement/context/findings-artifact.md index 8a242e76a80..ee2b20e85de 100644 --- a/plugins/instruction-placement/context/findings-artifact.md +++ b/plugins/instruction-placement/context/findings-artifact.md @@ -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 `/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. @@ -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 `/instruction-placement.yaml`. That convention owns the entry's keys, the `finding_id` hash, the `anchor/v` 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. diff --git a/plugins/instruction-placement/evals/au-suppression-file-not-a-candidate/case.yaml b/plugins/instruction-placement/evals/au-suppression-file-not-a-candidate/case.yaml new file mode 100644 index 00000000000..b0de1dc06ef --- /dev/null +++ b/plugins/instruction-placement/evals/au-suppression-file-not-a-candidate/case.yaml @@ -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.' diff --git a/plugins/instruction-placement/evals/au-suppression-file-not-a-candidate/prompt.md b/plugins/instruction-placement/evals/au-suppression-file-not-a-candidate/prompt.md new file mode 100644 index 00000000000..9e7d591101a --- /dev/null +++ b/plugins/instruction-placement/evals/au-suppression-file-not-a-candidate/prompt.md @@ -0,0 +1,28 @@ +--- +description: 'With docs/conventions/instruction-placement.yaml present and the detector reporting a candidate on it, audit drops that candidate because the suppression surface is excluded from the scan set, still counts the file in coverage, applies its suppression, and proposes the remaining finding. surface-excluded reads the reply. Read-only tools plus Bash for the skill''s pre-computed context line (needs --allow-tools Bash), graded on the reply.' +tags: [audit, suppression, scan-set] +max_turns: 15 +timeout_seconds: 420 +allowed_tools: [Read, Glob, Grep, Skill, Bash] +expected_outcome: 'The reply raises no finding on docs/conventions/instruction-placement.yaml: it drops the detector''s promote candidate on that file because the suppression surface is excluded from the audit''s scan set, while the detector''s coverage numbers still count the file. It suppresses the Deploy conventions finding with its reason, date (2026-11-02) and the team layer, still proposes the Lint rules finding with paths: **/*.ts, and writes neither the suppression file nor any instruction file.' +--- + +/instruction-placement:audit + +No pointer region binds a convention home. The tracked `docs/conventions/instruction-placement.yaml` holds: + +```yaml +suppressions: + 9c1e0b7a44d2f310: + check: instruction-placement/audit/demote + claim: narrower-scope:path-scoped-rule + sites: + - surface: CLAUDE.md + anchor/v1: "71d0c3aa" + reason: "Ops reads this section during incidents; it stays always-loaded." + date: 2026-11-02 +``` + +There is no `docs/conventions/instruction-placement.local.yaml` and no file at an old suppression path. The detector read 214 tracked files and reports three candidates: a demote of Deploy conventions in the root `CLAUDE.md`, whose check, claim and site anchor derive `finding_id` `9c1e0b7a44d2f310`; a demote of Lint rules in the root `CLAUDE.md` (`paths: **/*.ts`, 140 matches), which derives an id with no entry; and a promote of `docs/conventions/instruction-placement.yaml`, which it reads as a convention file under the convention home that nothing loads. + +Treat the state above as what this run's reads and scripts return. The repository is not checked out in this session, so run nothing against it: say what the run does, in order, and give its report. diff --git a/plugins/instruction-placement/evals/au-suppression-file-not-a-candidate/samples/surface-excluded.json b/plugins/instruction-placement/evals/au-suppression-file-not-a-candidate/samples/surface-excluded.json new file mode 100644 index 00000000000..c33e437f585 --- /dev/null +++ b/plugins/instruction-placement/evals/au-suppression-file-not-a-candidate/samples/surface-excluded.json @@ -0,0 +1,29 @@ +{ + "pass": [ + { + "answer": "docs/conventions/instruction-placement.yaml is the suppression surface, so it is excluded from the candidate set.", + "why": "names the file and its exclusion" + }, + { + "answer": "Dropped the promote candidate on `docs/conventions/instruction-placement.yaml`: the suppression file is never a candidate.", + "why": "paraphrase dropping the candidate" + } + ], + "fail": [ + { + "answer": "IP-002 promote: docs/conventions/instruction-placement.yaml reads as a convention nothing loads; move it to a nested AGENTS.md.", + "why": "proposes a finding on the suppression file" + }, + { + "answer": "Suppressed: Deploy conventions (team layer, docs/conventions/instruction-placement.yaml, 2026-11-02).", + "why": "near miss: names the file only as the layer source" + }, + { + "answer": "Excluded the suppression surface from the candidate set.", + "why": "near miss: never names the file" + }, + { + "answer": "" + } + ] +} diff --git a/plugins/instruction-placement/evals/dl-both-team-paths-new-wins/case.yaml b/plugins/instruction-placement/evals/dl-both-team-paths-new-wins/case.yaml new file mode 100644 index 00000000000..c1c687b5c21 --- /dev/null +++ b/plugins/instruction-placement/evals/dl-both-team-paths-new-wins/case.yaml @@ -0,0 +1,11 @@ +schema_version: "1.1" +name: dl-both-team-paths-new-wins +graders: + - name: 'both-files-named' + type: 'regex' + pattern: '^(?=[^\n]*\.claude/instruction-placement\.md\b)(?=[^\n]*\binstruction-placement\.yaml\b)(?=[^\n]*\b4d7f2a90c1e3b856\b)' + flags: 'im' + target: 'last_message' + - name: 'meets-expectations' + type: 'llm' + criteria: 'Read the reply as the account of what the delta run does with both team files present. PASS only if it satisfies every point: (1) Applies docs/conventions/instruction-placement.yaml as the team layer and suppresses Deploy conventions from it; (2) Does not apply the old .claude/instruction-placement.md, so Lint rules is still reported; (3) Warns naming both files and the id 4d7f2a90c1e3b856 that only the old file carries; (4) Names /instruction-placement:setup apply migrate-config to merge it, and writes neither 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.' diff --git a/plugins/instruction-placement/evals/dl-both-team-paths-new-wins/prompt.md b/plugins/instruction-placement/evals/dl-both-team-paths-new-wins/prompt.md new file mode 100644 index 00000000000..93dd3431e7e --- /dev/null +++ b/plugins/instruction-placement/evals/dl-both-team-paths-new-wins/prompt.md @@ -0,0 +1,28 @@ +--- +description: 'With both docs/conventions/instruction-placement.yaml and the old .claude/instruction-placement.md present, delta applies the new file as the team layer, does not apply the old one, and warns naming both files and the id only the old file carries. both-files-named reads the reply. Read-only tools plus Bash for the skill''s pre-computed context line (needs --allow-tools Bash), graded on the reply.' +tags: [delta, suppression, old-path] +max_turns: 15 +timeout_seconds: 420 +allowed_tools: [Read, Glob, Grep, Skill, Bash] +expected_outcome: 'The reply applies docs/conventions/instruction-placement.yaml as the team layer and suppresses the Deploy conventions finding from it. It does not apply the old .claude/instruction-placement.md, so the Lint rules finding, whose id only the old file carries, is still reported. It prints a warning naming both files, saying the new one supplies the team layer, listing 4d7f2a90c1e3b856 as the id only in the old file, and naming /instruction-placement:setup apply migrate-config to merge it. It writes neither file.' +--- + +/instruction-placement:delta + +This branch's memory-tier home holds a spine baseline from the 2026-11-01 run. No pointer region binds a convention home. The tracked `docs/conventions/instruction-placement.yaml` holds one entry: + +```yaml +suppressions: + 9c1e0b7a44d2f310: + check: instruction-placement/audit/demote + claim: narrower-scope:path-scoped-rule + sites: + - surface: CLAUDE.md + anchor/v1: "71d0c3aa" + reason: "Ops reads this section during incidents; it stays always-loaded." + date: 2026-11-02 +``` + +The tracked `.claude/instruction-placement.md` is still there too. Its fenced block holds the same `9c1e0b7a44d2f310` entry and one more, `4d7f2a90c1e3b856`, for the Lint rules demote finding, with the reason "Lint rules stay global while the TypeScript migration runs" and the date 2026-10-20. There is no personal override at either path and no `~/.claude/instruction-placement.md`. The detector reports two demote candidates in the root `CLAUDE.md`: Deploy conventions (`finding_id` `9c1e0b7a44d2f310`) and Lint rules (`paths: **/*.ts`, 140 matches, `finding_id` `4d7f2a90c1e3b856`). + +Treat the state above as what this run's reads and scripts return. The repository is not checked out in this session, so run nothing against it: say what the run does, in order, and give its report. diff --git a/plugins/instruction-placement/evals/dl-both-team-paths-new-wins/samples/both-files-named.json b/plugins/instruction-placement/evals/dl-both-team-paths-new-wins/samples/both-files-named.json new file mode 100644 index 00000000000..56b4d040371 --- /dev/null +++ b/plugins/instruction-placement/evals/dl-both-team-paths-new-wins/samples/both-files-named.json @@ -0,0 +1,29 @@ +{ + "pass": [ + { + "answer": "instruction-placement: old config path .claude/instruction-placement.md is not applied because docs/conventions/instruction-placement.yaml supplies this layer; ids only in the old file: 4d7f2a90c1e3b856; ids that differ: none; merge them with /instruction-placement:setup apply migrate-config", + "why": "the documented warning line" + }, + { + "answer": "| `.claude/instruction-placement.md` | not applied: `docs/conventions/instruction-placement.yaml` wins; `4d7f2a90c1e3b856` (Lint rules) is only in the old file |", + "why": "table row naming both files and the id" + } + ], + "fail": [ + { + "answer": "Suppressed: Lint rules (4d7f2a90c1e3b856, team layer, docs/conventions/instruction-placement.yaml).", + "why": "credits the new file with the old file's entry" + }, + { + "answer": "docs/conventions/instruction-placement.yaml supplies the team layer; .claude/instruction-placement.md is not applied.", + "why": "near miss: never lists the id only the old file carries" + }, + { + "answer": "Changed: Lint rules (4d7f2a90c1e3b856).", + "why": "silent about both files" + }, + { + "answer": "" + } + ] +} diff --git a/plugins/instruction-placement/evals/dl-committed-decline-holds-fresh-worktree/prompt.md b/plugins/instruction-placement/evals/dl-committed-decline-holds-fresh-worktree/prompt.md index f4462b2b389..5431c7bb7e1 100644 --- a/plugins/instruction-placement/evals/dl-committed-decline-holds-fresh-worktree/prompt.md +++ b/plugins/instruction-placement/evals/dl-committed-decline-holds-fresh-worktree/prompt.md @@ -1,15 +1,15 @@ --- -description: 'Legacy delta 6. In a fresh worktree with no spine baseline, delta still suppresses a finding declined on main through the committed .claude/instruction-placement.md entry, reports the suppression with reason, date and layer, and never writes that file. suppressed-by-team-layer reads the reply. Read-only tools plus Bash for the skill''s pre-computed context line (needs --allow-tools Bash), graded on the reply.' +description: 'Legacy delta 6. In a fresh worktree with no spine baseline, delta still suppresses a finding declined on main through the committed docs/conventions/instruction-placement.yaml entry, reports the suppression with reason, date and layer, and never writes that file. suppressed-by-team-layer reads the reply. Read-only tools plus Bash for the skill''s pre-computed context line (needs --allow-tools Bash), graded on the reply.' tags: [delta, suppression, worktree] max_turns: 15 timeout_seconds: 420 allowed_tools: [Read, Glob, Grep, Skill, Bash] -expected_outcome: 'The reply says this worktree has no spine baseline, which is expected because the memory tier does not cross checkouts, and still does not surface the Deploy conventions finding. It resolves .claude/instruction-placement.md across its three layers, derives the finding''s finding_id from its check, claim and site anchor, matches the committed team-layer entry, and suppresses it, naming the tracked file (not a baseline) as what carried the decline across checkouts. It reports the suppression with its reason, its date (2026-11-02) and its contributing layer (team), plus any entry that did not suppress. It writes only its own memory-tier baseline and never edits the suppression file, which realign owns.' +expected_outcome: 'The reply says this worktree has no spine baseline, which is expected because the memory tier does not cross checkouts, and still does not surface the Deploy conventions finding. It resolves docs/conventions/instruction-placement.yaml across its layers, derives the finding''s finding_id from its check, claim and site anchor, matches the committed team-layer entry, and suppresses it, naming the tracked file (not a baseline) as what carried the decline across checkouts. It reports the suppression with its reason, its date (2026-11-02) and its contributing layer (team), plus any entry that did not suppress. No old-path file exists, so it prints no old-path warning. It writes only its own memory-tier baseline and never edits the suppression file, which realign owns.' --- -/instruction-placement:delta fresh worktree of the same repo, branch cut from main. On main I declined the deploy-conventions demote finding and committed .claude/instruction-placement.md. +/instruction-placement:delta fresh worktree of the same repo, branch cut from main. On main I declined the deploy-conventions demote finding and committed docs/conventions/instruction-placement.yaml. -This worktree's memory-tier home is empty: no spine baseline and no findings artifact. The tracked `.claude/instruction-placement.md` holds one entry: +This worktree's memory-tier home is empty: no spine baseline and no findings artifact. No pointer region binds a convention home, and the tracked `docs/conventions/instruction-placement.yaml` holds one entry: ```yaml suppressions: @@ -23,6 +23,6 @@ suppressions: date: 2026-11-02 ``` -There is no `~/.claude/instruction-placement.md` and no `.claude/instruction-placement.local.md`. The detector reports two demote candidates in the root `CLAUDE.md`: Deploy conventions, whose check, claim and site anchor derive `finding_id` `9c1e0b7a44d2f310`, and Lint rules (`paths: **/*.ts`, 140 matches), which derives an id with no entry. +There is no `docs/conventions/instruction-placement.local.yaml`, and none of the old paths exists: no `.claude/instruction-placement.md`, no `.claude/instruction-placement.local.md`, no `~/.claude/instruction-placement.md`. The detector reports two demote candidates in the root `CLAUDE.md`: Deploy conventions, whose check, claim and site anchor derive `finding_id` `9c1e0b7a44d2f310`, and Lint rules (`paths: **/*.ts`, 140 matches), which derives an id with no entry. Treat the state above as what this run's reads and scripts return. The repository is not checked out in this session, so run nothing against it: say what the run does, in order, and give its report. diff --git a/plugins/instruction-placement/evals/dl-committed-decline-holds-fresh-worktree/samples/suppressed-by-team-layer.json b/plugins/instruction-placement/evals/dl-committed-decline-holds-fresh-worktree/samples/suppressed-by-team-layer.json index d9d921f21c7..ed0b986087a 100644 --- a/plugins/instruction-placement/evals/dl-committed-decline-holds-fresh-worktree/samples/suppressed-by-team-layer.json +++ b/plugins/instruction-placement/evals/dl-committed-decline-holds-fresh-worktree/samples/suppressed-by-team-layer.json @@ -9,8 +9,8 @@ "why": "table row" }, { - "answer": "| `9c1e0b7a44d2f310` (Deploy conventions, `demote`, `narrower-scope:path-scoped-rule`, CLAUDE.md `71d0c3aa`) | tracked `.claude/instruction-placement.md` | Suppressed. Reason: \"Ops reads this section during incidents; it stays always-loaded.\" (2026-11-02) |", - "why": "smoke reply: layer named as the tracked file" + "answer": "| `9c1e0b7a44d2f310` (Deploy conventions, `demote`, `narrower-scope:path-scoped-rule`, CLAUDE.md `71d0c3aa`) | tracked `docs/conventions/instruction-placement.yaml` | Suppressed. Reason: \"Ops reads this section during incidents; it stays always-loaded.\" (2026-11-02) |", + "why": "layer named as the tracked file" } ], "fail": [ diff --git a/plugins/instruction-placement/evals/dl-old-team-path-still-read-with-warning/case.yaml b/plugins/instruction-placement/evals/dl-old-team-path-still-read-with-warning/case.yaml new file mode 100644 index 00000000000..026dda15d39 --- /dev/null +++ b/plugins/instruction-placement/evals/dl-old-team-path-still-read-with-warning/case.yaml @@ -0,0 +1,11 @@ +schema_version: "1.1" +name: dl-old-team-path-still-read-with-warning +graders: + - name: 'old-path-warning' + type: 'regex' + pattern: '^(?=[^\n]*\.claude/instruction-placement\.md\b)(?=[^\n]*\binstruction-placement\.yaml\b)(?=[^\n]*\bmigrate-config\b)' + flags: 'im' + target: 'last_message' + - name: 'meets-expectations' + type: 'llm' + criteria: 'Read the reply as the account of what the delta run does with only the old team file present. PASS only if it satisfies every point: (1) Reads the old .claude/instruction-placement.md and suppresses the Deploy conventions finding, with reason, date and layer; (2) Prints a warning naming the old file and docs/conventions/instruction-placement.yaml as where it moves; (3) Names /instruction-placement:setup apply migrate-config as the command that moves it; (4) Still reports the Lint rules finding and writes neither 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.' diff --git a/plugins/instruction-placement/evals/dl-old-team-path-still-read-with-warning/prompt.md b/plugins/instruction-placement/evals/dl-old-team-path-still-read-with-warning/prompt.md new file mode 100644 index 00000000000..9ca720d75b7 --- /dev/null +++ b/plugins/instruction-placement/evals/dl-old-team-path-still-read-with-warning/prompt.md @@ -0,0 +1,28 @@ +--- +description: 'With only the old .claude/instruction-placement.md present, delta still reads it as the team layer, suppresses the finding it carries, and prints one warning naming the old file, docs/conventions/instruction-placement.yaml as the new location, and /instruction-placement:setup apply migrate-config. old-path-warning reads the reply. Read-only tools plus Bash for the skill''s pre-computed context line (needs --allow-tools Bash), graded on the reply.' +tags: [delta, suppression, old-path] +max_turns: 15 +timeout_seconds: 420 +allowed_tools: [Read, Glob, Grep, Skill, Bash] +expected_outcome: 'The reply reads the old .claude/instruction-placement.md as the team layer because no docs/conventions/instruction-placement.yaml supplies it, and still suppresses the Deploy conventions finding with its reason, date (2026-11-02) and layer. It prints one warning that names the old file, the new location docs/conventions/instruction-placement.yaml, and /instruction-placement:setup apply migrate-config as the command that moves it. It still reports the Lint rules finding, and it writes neither file.' +--- + +/instruction-placement:delta + +This branch's memory-tier home holds a spine baseline from the 2026-11-01 run. No pointer region binds a convention home, and there is no `docs/conventions/instruction-placement.yaml` and no `docs/conventions/instruction-placement.local.yaml`. The tracked `.claude/instruction-placement.md` holds this fenced block: + +```yaml +suppressions: + 9c1e0b7a44d2f310: + check: instruction-placement/audit/demote + claim: narrower-scope:path-scoped-rule + sites: + - surface: CLAUDE.md + anchor/v1: "71d0c3aa" + reason: "Ops reads this section during incidents; it stays always-loaded." + date: 2026-11-02 +``` + +There is no `.claude/instruction-placement.local.md` and no `~/.claude/instruction-placement.md`. The detector reports two demote candidates in the root `CLAUDE.md`: Deploy conventions, whose check, claim and site anchor derive `finding_id` `9c1e0b7a44d2f310`, and Lint rules (`paths: **/*.ts`, 140 matches), which derives an id with no entry. + +Treat the state above as what this run's reads and scripts return. The repository is not checked out in this session, so run nothing against it: say what the run does, in order, and give its report. diff --git a/plugins/instruction-placement/evals/dl-old-team-path-still-read-with-warning/samples/old-path-warning.json b/plugins/instruction-placement/evals/dl-old-team-path-still-read-with-warning/samples/old-path-warning.json new file mode 100644 index 00000000000..c0cf5f9a9b0 --- /dev/null +++ b/plugins/instruction-placement/evals/dl-old-team-path-still-read-with-warning/samples/old-path-warning.json @@ -0,0 +1,29 @@ +{ + "pass": [ + { + "answer": "instruction-placement: old config path .claude/instruction-placement.md is still read; move it to docs/conventions/instruction-placement.yaml with /instruction-placement:setup apply migrate-config", + "why": "the documented warning line" + }, + { + "answer": "Warning: `.claude/instruction-placement.md` is an old path, still applied; run `/instruction-placement:setup apply migrate-config` to move it to `docs/conventions/instruction-placement.yaml`.", + "why": "paraphrase with all three names" + } + ], + "fail": [ + { + "answer": "Suppressed: Deploy conventions (team layer, .claude/instruction-placement.md, 2026-11-02).", + "why": "applies the old file with no warning" + }, + { + "answer": ".claude/instruction-placement.md is an old path; move it to docs/conventions/instruction-placement.yaml.", + "why": "near miss: no setup command" + }, + { + "answer": "Ignoring .claude/instruction-placement.md; run migrate-config.", + "why": "drops the old file and never names the new location" + }, + { + "answer": "" + } + ] +} diff --git a/plugins/instruction-placement/evals/dl-personal-only-entry-not-applied/prompt.md b/plugins/instruction-placement/evals/dl-personal-only-entry-not-applied/prompt.md index 81205886850..3a7e8ebd475 100644 --- a/plugins/instruction-placement/evals/dl-personal-only-entry-not-applied/prompt.md +++ b/plugins/instruction-placement/evals/dl-personal-only-entry-not-applied/prompt.md @@ -4,11 +4,11 @@ tags: [delta, suppression, personal-layer] max_turns: 15 timeout_seconds: 420 allowed_tools: [Read, Glob, Grep, Skill, Bash] -expected_outcome: 'The reply still reports the Testing conventions finding rather than suppressing it. It explains that .claude/instruction-placement.local.md is the personal layer, and on this policy-floor surface a personal-layer entry for a finding_id the team layer does not carry is read, reported as personal-only, not applied, and takes no effect, since absence from the team layer is the team''s unsuppressed state. It names the contributing layer and points at promoting the entry to the tracked .claude/instruction-placement.md (through realign) as what makes it effective, neither silently honoring nor silently dropping it.' +expected_outcome: 'The reply still reports the Testing conventions finding rather than suppressing it. It explains that docs/conventions/instruction-placement.local.yaml is the personal layer, and on this policy-floor surface a personal-layer entry for a finding_id the team layer does not carry is read, reported as personal-only, not applied, and takes no effect, since absence from the team layer is the team''s unsuppressed state. It names the contributing layer and points at promoting the entry to the tracked docs/conventions/instruction-placement.yaml (through realign) as what makes it effective, neither silently honoring nor silently dropping it.' --- -/instruction-placement:delta I put an entry in .claude/instruction-placement.local.md for the CLAUDE.md testing-conventions finding, so it should be quiet now. +/instruction-placement:delta I put an entry in docs/conventions/instruction-placement.local.yaml for the CLAUDE.md testing-conventions finding, so it should be quiet now. -This branch's memory-tier home holds the spine baseline and findings artifact from the 2026-10-31 run, where IP-002 (demote the Testing conventions section of the root `CLAUDE.md` to `.claude/rules/testing.md`, `paths: **/*.test.ts`, 52 matches) is open. Its source section has since gained a paragraph, so the detector reports it as changed. The gitignored `.claude/instruction-placement.local.md` holds one entry whose key equals IP-002's derived `finding_id`, with a reason and a date. The tracked `.claude/instruction-placement.md` exists with no `suppressions` entries, and there is no `~/.claude/instruction-placement.md`. +This branch's memory-tier home holds the spine baseline and findings artifact from the 2026-10-31 run, where IP-002 (demote the Testing conventions section of the root `CLAUDE.md` to `.claude/rules/testing.md`, `paths: **/*.test.ts`, 52 matches) is open. Its source section has since gained a paragraph, so the detector reports it as changed. No pointer region binds a convention home. The gitignored `docs/conventions/instruction-placement.local.yaml` holds one entry whose key equals IP-002's derived `finding_id`, with a reason and a date. The tracked `docs/conventions/instruction-placement.yaml` exists with no `suppressions` entries, and none of the old paths (`.claude/instruction-placement.md`, `.claude/instruction-placement.local.md`, `~/.claude/instruction-placement.md`) exists. Treat the state above as what this run's reads and scripts return. The repository is not checked out in this session, so run nothing against it: say what the run does, in order, and give its report. diff --git a/plugins/instruction-placement/evals/dl-personal-only-entry-not-applied/samples/personal-only-not-applied.json b/plugins/instruction-placement/evals/dl-personal-only-entry-not-applied/samples/personal-only-not-applied.json index 79d0ff43890..05c8e1e9e1a 100644 --- a/plugins/instruction-placement/evals/dl-personal-only-entry-not-applied/samples/personal-only-not-applied.json +++ b/plugins/instruction-placement/evals/dl-personal-only-entry-not-applied/samples/personal-only-not-applied.json @@ -1,7 +1,7 @@ { "pass": [ { - "answer": "IP-002 entry in `.claude/instruction-placement.local.md` (personal override): personal-only, not applied.", + "answer": "IP-002 entry in `docs/conventions/instruction-placement.local.yaml` (personal override): personal-only, not applied.", "why": "skill's wording" }, { @@ -11,7 +11,7 @@ ], "fail": [ { - "answer": "Suppressed: IP-002 (personal layer, .claude/instruction-placement.local.md).", + "answer": "Suppressed: IP-002 (personal layer, docs/conventions/instruction-placement.local.yaml).", "why": "honors the personal entry" }, { diff --git a/plugins/instruction-placement/evals/ra-decline-offered-as-suppression/case.yaml b/plugins/instruction-placement/evals/ra-decline-offered-as-suppression/case.yaml index bc40ab64a00..bc990ebccbe 100644 --- a/plugins/instruction-placement/evals/ra-decline-offered-as-suppression/case.yaml +++ b/plugins/instruction-placement/evals/ra-decline-offered-as-suppression/case.yaml @@ -3,7 +3,7 @@ name: ra-decline-offered-as-suppression graders: - name: 'tracked-file-committed' type: 'regex' - pattern: '^(?=[^\n]*(?:\.claude/instruction-placement\.md\b|\bteam[- ]layer\b|\bfile is tracked\b))(?=[^\n]*\bcommit\w*)' + pattern: '^(?=[^\n]*(?:\binstruction-placement\.yaml\b|\bteam[- ]layer\b|\bfile is tracked\b))(?=[^\n]*\bcommit\w*)' flags: 'im' target: 'last_message' - name: 'meets-expectations' diff --git a/plugins/instruction-placement/evals/ra-decline-offered-as-suppression/prompt.md b/plugins/instruction-placement/evals/ra-decline-offered-as-suppression/prompt.md index 47e919f6dd0..310bb73c25e 100644 --- a/plugins/instruction-placement/evals/ra-decline-offered-as-suppression/prompt.md +++ b/plugins/instruction-placement/evals/ra-decline-offered-as-suppression/prompt.md @@ -1,14 +1,14 @@ --- -description: 'Legacy realign 7. Told to leave a finding where it is and stop asking weekly, realign records declined in the artifact, then shows a composed suppression entry for the tracked .claude/instruction-placement.md, writes it only on a yes, and says it must be committed to reach other checkouts. tracked-file-committed reads the reply. Read-only tools plus Bash for the skill''s pre-computed context line (needs --allow-tools Bash), graded on the reply.' +description: 'Legacy realign 7. Told to leave a finding where it is and stop asking weekly, realign records declined in the artifact, then shows a composed suppression entry for the tracked docs/conventions/instruction-placement.yaml, writes it only on a yes, and says it must be committed to reach other checkouts. tracked-file-committed reads the reply. Read-only tools plus Bash for the skill''s pre-computed context line (needs --allow-tools Bash), graded on the reply.' tags: [realign, decline, suppression] max_turns: 15 timeout_seconds: 420 allowed_tools: [Read, Glob, Grep, Skill, Bash] -expected_outcome: 'The reply records declined for IP-004 in the findings artifact, then treats the second half of the request as its own decision. It explains that the artifact is memory tier and invisible from any other checkout, composes the suppression entry for the tracked .claude/instruction-placement.md (check, claim, the site with its anchor, the operator''s own reason, and today''s date, keyed by the derived finding_id), shows it in full, and writes it only on an explicit yes. It targets the team-tracked layer, never ~/.claude/ and never the gitignored personal override, and says the file is tracked and the decision reaches other worktrees once committed.' +expected_outcome: 'The reply records declined for IP-004 in the findings artifact, then treats the second half of the request as its own decision. It explains that the artifact is memory tier and invisible from any other checkout, composes the suppression entry for the tracked docs/conventions/instruction-placement.yaml (check, claim, the site with its anchor, the operator''s own reason, and today''s date, keyed by the derived finding_id), shows it in full, and writes it only on an explicit yes. It targets the team-tracked layer, never ~/.claude/, an old .claude/ path, or the gitignored personal override, and says the file is tracked and the decision reaches other worktrees once committed.' --- /instruction-placement:realign IP-004, the deploy conventions one. No, leave it where it is, and stop asking me about it every week. -This branch's findings artifact (branch and Claude Code version both match) lists IP-004 as `proposed`: the Deploy conventions section at `CLAUDE.md` lines 60 to 74, destination `.claude/rules/deploy.md` with `paths: deploy/**`. The repository has no suppression file yet, and a weekly scheduled delta run reads this repository. Today is 2026-11-07. +This branch's findings artifact (branch and Claude Code version both match) lists IP-004 as `proposed`: the Deploy conventions section at `CLAUDE.md` lines 60 to 74, destination `.claude/rules/deploy.md` with `paths: deploy/**`. No pointer region binds a convention home. The repository has no suppression file yet, at the new path or any old one, and a weekly scheduled delta run reads this repository. Today is 2026-11-07. Treat the state above as what this run's reads and scripts return. The repository is not checked out in this session, so run nothing against it: say what the run does, in order, and give its report. diff --git a/plugins/instruction-placement/evals/ra-decline-offered-as-suppression/samples/tracked-file-committed.json b/plugins/instruction-placement/evals/ra-decline-offered-as-suppression/samples/tracked-file-committed.json index 619d052fd0d..477f2931206 100644 --- a/plugins/instruction-placement/evals/ra-decline-offered-as-suppression/samples/tracked-file-committed.json +++ b/plugins/instruction-placement/evals/ra-decline-offered-as-suppression/samples/tracked-file-committed.json @@ -1,16 +1,16 @@ { "pass": [ { - "answer": "`.claude/instruction-placement.md` is tracked: once you commit it, other worktrees stop seeing IP-004.", + "answer": "`docs/conventions/instruction-placement.yaml` is tracked: once you commit it, other worktrees stop seeing IP-004.", "why": "commit tied to the file" }, { - "answer": "Commit .claude/instruction-placement.md so the decline reaches every checkout.", + "answer": "Commit docs/conventions/instruction-placement.yaml so the decline reaches every checkout.", "why": "imperative" }, { - "answer": "| If you do say yes | I'd write the entry to the team-layer file only, never `~/.claude/**` or the `.local.md` file. The file is tracked, so the decision reaches other checkouts and the scheduled run only after you commit it. I won't commit it unless you ask. |", - "why": "smoke reply: team-layer file, commit" + "answer": "| If you do say yes | I'd write the entry to the team-layer file only, never `~/.claude/**` or the `.local.yaml` file. The file is tracked, so the decision reaches other checkouts and the scheduled run only after you commit it. I won't commit it unless you ask. |", + "why": "team-layer file, commit" } ], "fail": [ @@ -23,7 +23,7 @@ "why": "artifact only" }, { - "answer": "Entry for `.claude/instruction-placement.md` shown above; say yes to write it.", + "answer": "Entry for `docs/conventions/instruction-placement.yaml` shown above; say yes to write it.", "why": "never says it must be committed" }, { diff --git a/plugins/instruction-placement/evals/su-config-values-with-sources/prompt.md b/plugins/instruction-placement/evals/su-config-values-with-sources/prompt.md index 0912fa9b71b..d59c9473e56 100644 --- a/plugins/instruction-placement/evals/su-config-values-with-sources/prompt.md +++ b/plugins/instruction-placement/evals/su-config-values-with-sources/prompt.md @@ -9,6 +9,6 @@ expected_outcome: 'The reply prints the effective configuration with a source fo /instruction-placement:setup check: why is it calling our **/*.md rule over-broad? -The repository tracks 1,000 files, 880 of them Markdown, and `.claude/rules/prose.md` uses `paths: **/*.md`. The plugin has no `user_config` values set and the repository has no `.claude/instruction-placement.md`. The root `CLAUDE.md` is the single line `@AGENTS.md`, the root `AGENTS.md` carries an index block that matches both rules, and `git`, `jq` and the Claude Code CLI are on `PATH`. +The repository tracks 1,000 files, 880 of them Markdown, and `.claude/rules/prose.md` uses `paths: **/*.md`. The plugin has no `user_config` values set and the repository has no `docs/conventions/instruction-placement.yaml` and no file at an old suppression path. The root `CLAUDE.md` is the single line `@AGENTS.md`, the root `AGENTS.md` carries an index block that matches both rules, and `git`, `jq` and the Claude Code CLI are on `PATH`. Treat the state above as what this run's reads and scripts return. The repository is not checked out in this session, so run nothing against it: say what the run does, in order, and give its report. diff --git a/plugins/instruction-placement/evals/su-migrate-config-preview-before-write/case.yaml b/plugins/instruction-placement/evals/su-migrate-config-preview-before-write/case.yaml new file mode 100644 index 00000000000..8d63414e6a4 --- /dev/null +++ b/plugins/instruction-placement/evals/su-migrate-config-preview-before-write/case.yaml @@ -0,0 +1,11 @@ +schema_version: "1.1" +name: su-migrate-config-preview-before-write +graders: + - name: 'preview-asks-first' + type: 'regex' + pattern: '^(?=[^\n]*\bdocs/conventions/instruction-placement\.yaml\b)(?=[^\n]*(?:\byes\b|\bconfirm|\bapprov|\bgo ahead\b|\bproceed\b))' + flags: 'im' + target: 'last_message' + - name: 'meets-expectations' + type: 'llm' + criteria: 'Read the reply as the account of what the setup apply migrate-config run does with the two old files and no answer from the operator yet. PASS only if it satisfies every point: (1) Names .claude/instruction-placement.md and its target docs/conventions/instruction-placement.yaml, and shows the target as it will read, carrying the 9c1e0b7a44d2f310 entry; (2) Asks for an explicit yes for that file before writing it, and writes and deletes nothing in this run; (3) Says the old file is deleted only after the new file is written and read back resolving the same entries, never before; (4) For .claude/instruction-placement.local.md, says the target docs/conventions/instruction-placement.local.yaml is not gitignored, names the missing docs/conventions/**/*.local.* line, and says that file is skipped and left in place (now, or once the check runs after a yes) rather than written. 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, or if the reply reports any file written or deleted.' diff --git a/plugins/instruction-placement/evals/su-migrate-config-preview-before-write/prompt.md b/plugins/instruction-placement/evals/su-migrate-config-preview-before-write/prompt.md new file mode 100644 index 00000000000..a06647833da --- /dev/null +++ b/plugins/instruction-placement/evals/su-migrate-config-preview-before-write/prompt.md @@ -0,0 +1,42 @@ +--- +description: 'With an old team file and an old personal file present and no answer from the operator yet, setup apply migrate-config previews the team file''s move to docs/conventions/instruction-placement.yaml and asks for a yes, writes and deletes nothing, deletes an old file only after the readback, and skips the personal file because its target is not gitignored. preview-asks-first reads the reply. Read-only tools plus Bash for the skill''s pre-computed context line (needs --allow-tools Bash), graded on the reply.' +tags: [setup, migrate-config, old-path] +max_turns: 15 +timeout_seconds: 420 +allowed_tools: [Read, Glob, Grep, Skill, Bash] +expected_outcome: 'The reply previews moving .claude/instruction-placement.md to docs/conventions/instruction-placement.yaml, showing the target as it will read with the 9c1e0b7a44d2f310 entry, and asks for an explicit yes for that file before writing it. It writes nothing and deletes nothing in this run, and says the old file is deleted only after the new file is written and read back resolving the same entries. For .claude/instruction-placement.local.md it says the target docs/conventions/instruction-placement.local.yaml is not gitignored, names the missing docs/conventions/**/*.local.* line, and leaves that file in place.' +--- + +/instruction-placement:setup apply migrate-config + +No pointer region binds a convention home, and there is no `docs/conventions/instruction-placement.yaml` and no `docs/conventions/instruction-placement.local.yaml`. The tracked `.claude/instruction-placement.md` holds this fenced block: + +```yaml +suppressions: + 9c1e0b7a44d2f310: + check: instruction-placement/audit/demote + claim: narrower-scope:path-scoped-rule + sites: + - surface: CLAUDE.md + anchor/v1: "71d0c3aa" + reason: "Ops reads this section during incidents; it stays always-loaded." + date: 2026-11-02 +``` + +The untracked `.claude/instruction-placement.local.md` holds this fenced block: + +```yaml +suppressions: + 4d7a2f0c81e35b96: + check: instruction-placement/audit/demote + claim: narrower-scope:path-scoped-rule + sites: + - surface: CLAUDE.md + anchor/v1: "a3e19c42" + reason: "I keep the release notes section in view while I cut releases." + date: 2026-11-04 +``` + +There is no `~/.claude/instruction-placement.md`. The `.gitignore` has no `docs/conventions/**/*.local.*` line, so `git check-ignore -q docs/conventions/instruction-placement.local.yaml` exits 1. The operator has not answered any question in this session. + +Treat the state above as what this run's reads and scripts return. The repository is not checked out in this session, so run nothing against it: say what the run does, in order, and give its report. diff --git a/plugins/instruction-placement/evals/su-migrate-config-preview-before-write/samples/preview-asks-first.json b/plugins/instruction-placement/evals/su-migrate-config-preview-before-write/samples/preview-asks-first.json new file mode 100644 index 00000000000..797b6f81066 --- /dev/null +++ b/plugins/instruction-placement/evals/su-migrate-config-preview-before-write/samples/preview-asks-first.json @@ -0,0 +1,29 @@ +{ + "pass": [ + { + "answer": "Move `.claude/instruction-placement.md` to `docs/conventions/instruction-placement.yaml`? Reply yes to write it; nothing is written or deleted before that.", + "why": "names the target and asks for the yes" + }, + { + "answer": "Shall I proceed with writing docs/conventions/instruction-placement.yaml as previewed above?", + "why": "paraphrase asking before the write" + } + ], + "fail": [ + { + "answer": "Moved .claude/instruction-placement.md to docs/conventions/instruction-placement.yaml, verified the entry, and deleted the old file.", + "why": "writes and deletes without asking" + }, + { + "answer": "Reply yes to continue.", + "why": "near miss: asks but never names the target" + }, + { + "answer": "Target: docs/conventions/instruction-placement.local.yaml, confirm?", + "why": "near miss: names only the personal target" + }, + { + "answer": "" + } + ] +} diff --git a/plugins/instruction-placement/reference/consumer-config.md b/plugins/instruction-placement/reference/consumer-config.md index 30a191965d8..8e4bad648e8 100644 --- a/plugins/instruction-placement/reference/consumer-config.md +++ b/plugins/instruction-placement/reference/consumer-config.md @@ -1,8 +1,8 @@ # instruction-placement: consumer configuration -Owner doc for this plugin's tracked configuration file: `.claude/instruction-placement.md` in the +Owner doc for this plugin's tracked configuration file: `/instruction-placement.yaml` in the consuming repository, layered per the consuming marketplace's config-cascade convention. Every layer -is optional, and all three absent is a valid state that means no suppressions. +is optional, and all of them absent is a valid state that means no suppressions. The surface carries one key today, `suppressions`: the durable record of the findings an operator has declined. It is declared here rather than in the plugin's `README.md` because the cascade's boundary @@ -27,15 +27,20 @@ carries it. ## Layers and merge semantics -Three layers, resolved in this order: +The config-cascade layers, lowest first +([the layers](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#the-layers)): -| Order | Layer | Path | +| Order | Layer | Source | |---|---|---| -| 1 | user-global | `~/.claude/instruction-placement.md` | -| 2 | team (tracked) | `${CLAUDE_PROJECT_DIR}/.claude/instruction-placement.md` | -| 3 | personal override (gitignored) | `${CLAUDE_PROJECT_DIR}/.claude/instruction-placement.local.md` | +| 0 | plugin default | no suppressions | +| 1 | `userConfig` | none: a decline is a repository's judgment, so no `userConfig` option holds one (see above) | +| 2 | team (tracked) | `/instruction-placement.yaml` | +| 3 | personal override (gitignored) | `/instruction-placement.local.yaml` | -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. +Every path is relative to the repository root (`git rev-parse --show-toplevel`; on a +multi-repository run, the worktree that run names). `` is the convention home that the marked +pointer region in the root `AGENTS.md` or `CLAUDE.md` binds, and `docs/conventions` when no region +binds one. [Config locations](config-locations.md) lists where every plugin's config lives. **Merge form: per-key override**, declared here as the cascade convention requires. Entries merge per `finding_id`: a later layer's entry for one id wins for that id only, and every id it does not @@ -50,12 +55,45 @@ from the team layer is the team's unsuppressed state. Whenever a personal layer output, the run names the contributing layer. That reporting is what makes the class hold, and it is behavioral rather than declarative. -## File format +### Old paths: read until moved + +Three old paths are still read while they exist, so no entry in them is lost, and every run prints +one warning line for each one it finds: + +| Old path | Read as | Read when | Move to | +|---|---|---|---| +| `.claude/instruction-placement.md` | team | `/instruction-placement.yaml` is absent | `/instruction-placement.yaml` | +| `.claude/instruction-placement.local.md` | personal | `/instruction-placement.local.yaml` is absent | `/instruction-placement.local.yaml` | +| `~/.claude/instruction-placement.md` | personal, below `.claude/instruction-placement.local.md` per `finding_id` | `/instruction-placement.local.yaml` is absent | `/instruction-placement.local.yaml` | -Markdown with a fenced YAML block, human-readable in review and greppable from a shell. +An old file holds its `suppressions` in the fenced YAML block of a Markdown file; the keys are the +same. The old user-global file moves to the personal override, not to `userConfig`, by the placement +rule: a decline is a per-repository judgment, and a personal-layer entry suppresses nothing on its +own, so the move keeps every result the same. + +The warning names the old file, the new location, and the command that moves it: + +```text +instruction-placement: old config path is still read; move it to with /instruction-placement:setup apply migrate-config +``` + +When the new file for that layer exists too, the new file wins and the old one is not applied. The +warning then names both files and lists the old file's `finding_id`s that the new file lacks or +holds with different values, so nothing in the old file drops out unseen: + +```text +instruction-placement: old config path is not applied because supplies this layer; ids only in the old file: ; ids that differ: ; merge them with /instruction-placement:setup apply migrate-config +``` + +`/instruction-placement:setup apply migrate-config` moves each old file to its new location behind +a preview and a yes, checks the new location resolves the same entries, and then deletes the old +file, so the config ends in one place. Dropping the old-path reads is a separate later change, made +once no run reports an old file. + +## File format -````markdown -# instruction-placement suppressions +A YAML file, checked against +[`schemas/instruction-placement.schema.json`](../schemas/instruction-placement.schema.json): ```yaml suppressions: @@ -76,9 +114,9 @@ suppressions: reason: "Owned by the release runbook; promoting it would fork the source of truth." date: 2026-09-06 ``` -```` -Unknown keys are inert per the cascade's soft-degradation rule. An entry missing any required key is +Unknown keys are inert at runtime per the cascade's soft-degradation rule; the schema check a +repository runs in CI rejects an unknown top-level key. An entry missing any required key is reported as malformed and does not suppress. **The entries above are derived, not illustrative.** Their `anchor/v1` values are this plugin's @@ -123,10 +161,12 @@ Three obligations this plugin takes on top of the convention: contributing layer, and every entry that did *not* suppress: each `personal-only, not applied` and each malformed one. A scoped run reports what it examined: it evaluates only entries with a site in its scope and marks the rest **not evaluated this run**. -- **Team layer only, and never user-global.** A decline is written to - `${CLAUDE_PROJECT_DIR}/.claude/instruction-placement.md` so git carries it to every checkout. The - convention forbids editing a user-scope file to record a suppression, and this plugin never writes - `~/.claude/**`. A personal draft there is read, reported, and left for the operator to promote. +- **Team layer only.** A decline is written to `/instruction-placement.yaml` so git carries + it to every checkout, never to the personal override, an old path, or `~/.claude/**`. The + convention forbids editing a user-scope file to record a suppression. A personal draft is read, + reported, and left for the operator to promote. Moving config is not recording a decline: + `setup apply migrate-config` writes the personal override from an old personal or user-global + file, and deletes each old-path file, every step after the operator's yes. **Declared deviation: a fifth disposition for a scoped run.** The convention requires a skill to resolve every entry to exactly one of four dispositions. `instruction-placement:audit` accepts a @@ -138,20 +178,23 @@ inside the scope still resolves to one of the convention's four. A full run neve deviation is additive and reporting-only: no entry suppresses on it, and no entry escapes a disposition because of it. -`.claude/instruction-placement.md` and its layers are **excluded from the audit's own scan set**. -Otherwise recording a decline would change the instruction layer the next run sweeps, and any -idempotence claim about that run would be unfalsifiable. +`/instruction-placement.yaml`, `/instruction-placement.local.yaml`, and every old-path +file still read under "Old paths: read until moved" are **excluded from the audit's own scan set**. Otherwise +recording a decline would change the instruction layer the next run sweeps, and any idempotence +claim about that run would be unfalsifiable. ## Consumer `.gitignore` The personal override is gitignored by the cascade's one recursive line, which covers every current and -future surface at once: +future surface at once, with `` written out (the default home shown): ```gitignore -.claude/**/*.local.* +docs/conventions/**/*.local.* ``` -No skill in this plugin writes the consumer's `.gitignore`. +No skill in this plugin writes the consumer's `.gitignore`. When the personal override would not be +ignored, `setup apply migrate-config` names the missing line and leaves the personal file where it +is. ## Trades recorded, so they are not silently re-litigated diff --git a/plugins/instruction-placement/schemas/instruction-placement.schema.json b/plugins/instruction-placement/schemas/instruction-placement.schema.json new file mode 100644 index 00000000000..c53c8ba71e7 --- /dev/null +++ b/plugins/instruction-placement/schemas/instruction-placement.schema.json @@ -0,0 +1,35 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "Instruction-placement team config", + "description": "Schema for instruction-placement.yaml in a repository's convention home (default docs/conventions): the declined findings that /instruction-placement:audit, delta and realign read and realign writes, listed in plugins/instruction-placement/reference/consumer-config.md. Entry format: the finding-suppression contract.", + "type": "object", + "additionalProperties": false, + "properties": { + "$schema": { "type": "string" }, + "suppressions": { + "type": "object", + "description": "Declined findings keyed by finding_id, the hash of each entry's check, claim and sites.", + "propertyNames": { "pattern": "^[0-9a-f]{16}$" }, + "additionalProperties": { + "type": "object", + "required": ["check", "claim", "sites", "reason", "date"], + "properties": { + "check": { "type": "string", "minLength": 1 }, + "claim": { "type": "string", "minLength": 1 }, + "sites": { + "type": "array", + "minItems": 1, + "items": { + "type": "object", + "required": ["surface"], + "properties": { "surface": { "type": "string", "minLength": 1 } }, + "patternProperties": { "^anchor/v[0-9]+$": { "type": "string" } } + } + }, + "reason": { "type": "string", "minLength": 1 }, + "date": { "description": "The day the decline was recorded, as YYYY-MM-DD." } + } + } + } + } +} diff --git a/plugins/instruction-placement/skills/audit/SKILL.md b/plugins/instruction-placement/skills/audit/SKILL.md index 7c73205e9fd..737bb5b1a62 100644 --- a/plugins/instruction-placement/skills/audit/SKILL.md +++ b/plugins/instruction-placement/skills/audit/SKILL.md @@ -207,11 +207,14 @@ operator's `declined` decision must survive a re-audit. ## The suppression surface -Before ranking, resolve the tracked suppression surface `.claude/instruction-placement.md` across -its three layers ([`${CLAUDE_PLUGIN_ROOT}/reference/consumer-config.md`](${CLAUDE_PLUGIN_ROOT}/reference/consumer-config.md)) -and suppress every candidate whose `finding_id` it carries. That file is how a decline reaches a -checkout the findings artifact never does, so a sweep that ignores it re-proposes decisions the -operator already made elsewhere. +Before ranking, resolve the tracked suppression surface `/instruction-placement.yaml` across +its layers (`` is the convention home that the marked pointer region in the root `AGENTS.md` +or `CLAUDE.md` binds, `docs/conventions` when no region binds one, not the memory-tier home the +artifact above is written under), old paths included while they exist, and print the old-path warning for each one found +([`${CLAUDE_PLUGIN_ROOT}/reference/consumer-config.md`](../../reference/consumer-config.md) +"Layers and merge semantics"). Suppress every candidate whose `finding_id` it carries. That file is +how a decline reaches a checkout the findings artifact never does, so a sweep that ignores it +re-proposes decisions the operator already made elsewhere. Derive a candidate's `anchor/v1` and `finding_id` by running `detect.sh identity`, never by hand. `--file` is the repo-relative path: @@ -224,8 +227,8 @@ Derive a candidate's `anchor/v1` and `finding_id` by running `detect.sh identity Three obligations, none optional. **Read, never write**: `realign` composes an entry behind its per-item gate and nothing here does. **Report the suppressions**, each with its reason, date, and contributing layer, and every entry that did *not* suppress: personal-only, malformed, or outside -this run's scope. **Exclude the surface and its layers**, because auditing the file that records the -decisions would make recording one perturb the next run. That exclusion is applied to the candidate +this run's scope. **Exclude the surface, its layers and its old-path files**, because auditing the +file that records the decisions would make recording one perturb the next run. That exclusion is applied to the candidate set after the detector has run, not to the corpus: the corpus document above stays the one owner of what is swept, and the detector's coverage numbers keep counting every file it read. diff --git a/plugins/instruction-placement/skills/delta/SKILL.md b/plugins/instruction-placement/skills/delta/SKILL.md index edc46b94c2d..a2b96b6098d 100644 --- a/plugins/instruction-placement/skills/delta/SKILL.md +++ b/plugins/instruction-placement/skills/delta/SKILL.md @@ -57,7 +57,12 @@ the home `findings-artifact.md` defines. Memory tier and checkout-local, which i spine is recomputed next run, and one from another checkout describes a tree this one lacks. **The suppression surface** is where an operator's decline lives: the tracked -`.claude/instruction-placement.md`, resolved across the three cascade layers. It is tracked because +`/instruction-placement.yaml`, resolved across its cascade layers, old paths included while +they exist, with the old-path warning printed for each. `` is the convention home that the +marked pointer region in the root `AGENTS.md` or `CLAUDE.md` binds, `docs/conventions` when no +region binds one, not the memory-tier home the baseline lives under +([`${CLAUDE_PLUGIN_ROOT}/reference/consumer-config.md`](../../reference/consumer-config.md) "Layers +and merge semantics"). It is tracked because that is the only mechanism that crosses checkouts: git moves the file, and a memory-tier baseline never reaches another worktree. Read it, honor every entry it merges to, and **never write it**: `realign` owns that write, behind its per-item gate. @@ -118,7 +123,8 @@ else noticing between `check` runs. Each step names what "done" looks like, so a partial run is visible rather than assumed complete. 1. Resolve the home, read this branch's spine baseline and findings artifact, - and resolve the suppression surface across its three layers; a missing surface is the ordinary + and resolve the suppression surface across its layers, old paths included while they exist, + printing the old-path warning for each; a missing surface is the ordinary no-suppressions state. All four baseline/artifact combinations resolve explicitly, none an error: | Baseline | Artifact | Disposition | diff --git a/plugins/instruction-placement/skills/realign/SKILL.md b/plugins/instruction-placement/skills/realign/SKILL.md index 444a481142b..e65855e778c 100644 --- a/plugins/instruction-placement/skills/realign/SKILL.md +++ b/plugins/instruction-placement/skills/realign/SKILL.md @@ -80,8 +80,11 @@ operator is asked again. So a decline has **two** writes, and the second is what 1. **`declined` into the findings artifact.** Unchanged, and still the record this branch's run reads. -2. **An entry on the tracked suppression surface**, `${CLAUDE_PROJECT_DIR}/.claude/instruction-placement.md`. - Git carries that file to every checkout whose branch holds the commit, which is the only mechanism +2. **An entry on the tracked suppression surface**, `/instruction-placement.yaml`. + Here and below, `` is the convention home that the marked pointer region in the root + `AGENTS.md` or `CLAUDE.md` binds, `docs/conventions` when no region binds one + (`consumer-config.md` "Layers and merge semantics"). It is not the memory-tier home the findings + artifact lives under, which is gitignored and checkout-local. Git carries that file to every checkout whose branch holds the commit, which is the only mechanism that crosses checkouts at all. The entry's five required keys, its `finding_id`, and the layer rules are owned by the two documents @@ -93,11 +96,15 @@ in the table above. Do not invent a format here. Four rules bind the write: - **A reason is required, and it is theirs, not yours.** An entry with no stated reason cannot be reviewed or retired later. If the operator gives none, ask once; if they still give none, record `declined` in the artifact only and say the decline will not survive this checkout. -- **Team layer only.** Write `${CLAUDE_PROJECT_DIR}/.claude/instruction-placement.md` (on a - multi-repository run, the worktree's: "Over several repositories"), never - `~/.claude/**` and never the `.local.md` personal override: a personal-layer entry the team layer does not - carry is reported `personal-only, not applied` and suppresses nothing, so writing one would look - like recording a decision while recording none. +- **Team layer only.** Write `/instruction-placement.yaml` at the repository root (on a + multi-repository run, the worktree's: "Over several repositories"), and name that path in the + shown entry. Never write `~/.claude/**`, an old path, or the `.local.yaml` personal override: a + personal-layer entry the team layer does not carry is reported `personal-only, not applied` and + suppresses nothing, so writing one would look like recording a decision while recording none. + When the old `.claude/instruction-placement.md` still supplies the team layer, ask the operator to + run `/instruction-placement:setup apply migrate-config` first: an entry written to the new file + alone makes the old file's entries stop applying. If they decline, write the new file and name + each old entry that stops applying. - **Say that it needs committing.** The file is tracked, and an uncommitted entry has reached no other worktree yet. Name that rather than implying the decision is already everywhere. @@ -131,15 +138,16 @@ with no `*` (how such a rule matches: ## Prerequisites -Read the artifact from the home `findings-artifact.md` "Where it lives" defines. +Read the artifact from the memory-tier home `findings-artifact.md` "Where it lives" defines. If it is absent, say no audit has been run for this branch and offer to run one. Do **not** fall back to another path or another branch's artifact: findings cite line ranges, and a range derived elsewhere points at different text here. Name such a file a leftover and run a fresh audit instead. -Then, **before the first finding is presented**, resolve `.claude/instruction-placement.md` across -its three layers and drop every finding the merged surface covers, reporting each as suppressed with -its reason, date, and contributing layer. Match on the `finding_id` the artifact's `Suppression key` +Then, **before the first finding is presented**, resolve `/instruction-placement.yaml` across +its layers, old paths included while they exist, with the old-path warning printed for each +(`consumer-config.md` "Layers and merge semantics"), and drop every finding the merged surface +covers, reporting each as suppressed with its reason, date, and contributing layer. Match on the `finding_id` the artifact's `Suppression key` already carries; **do not derive one here.** This skill has no detector stream, and a second derivation is a second heading parse whose disagreement produces a decline nothing ever matches. @@ -177,9 +185,9 @@ and "Resolving repositories" say. What differs here: repository resolves to. Select the entry on the branch `instruction-placement/realign` in `git -C worktree list --porcelain`, never another worktree of the clone, and run the whole procedure there: `--root` set to it on every `glob-tools.sh`, `render-index.sh` and - `verify-load.sh` call, the worktree's branch as the branch identity for the home and the branch + `verify-load.sh` call, the worktree's branch as the branch identity for the memory-tier home and the branch match, every edit under it, and a decline's suppression entry written to its - `.claude/instruction-placement.md`, not this checkout's. A repository with no worktree on that + `/instruction-placement.yaml`, not this checkout's. A repository with no worktree on that branch, or no artifact in it, is reported as "no audit run" and skipped. - **The quote check runs once.** It reads docs pages, not a repository: run it once, with no arguments, before the first repository's artifact is read. diff --git a/plugins/instruction-placement/skills/setup/SKILL.md b/plugins/instruction-placement/skills/setup/SKILL.md index 7d353cb8e28..3219eb462d5 100644 --- a/plugins/instruction-placement/skills/setup/SKILL.md +++ b/plugins/instruction-placement/skills/setup/SKILL.md @@ -1,6 +1,6 @@ --- -description: "Verify instruction-placement's prerequisites, resolve its effective configuration for this repository, and register its rules-index git pre-commit entry. Confirm that the index target exists AND that nothing in the repository stops Claude Code loading it (a root CLAUDE.md is read instead of the AGENTS.md beside it, so an unimported AGENTS.md index is inert while every other gate reports green), that `git` backs tracked-file discovery, and that the Claude Code CLI plus `jq` are present for the optional empirical load probe. Reports the resolved index target, breadth ceiling, and index row cap, naming which came from configuration and which from a default. Use when: 'set up instruction-placement', 'configure instruction-placement', 'where will the index go', 'why is my index not loading', 'is instruction-placement working', or before a first audit on a new repository. Actions: check (read-only, default) | check inspect (read-only) | apply | apply install-git-hooks [scope=local|shared]. Re-runnable." -argument-hint: "[check|apply] [inspect|install-git-hooks [scope=local|shared]]" +description: "Verify instruction-placement's prerequisites, resolve its effective configuration for this repository, and register its rules-index git pre-commit entry. Confirm that the index target exists AND that nothing in the repository stops Claude Code loading it (a root CLAUDE.md is read instead of the AGENTS.md beside it, so an unimported AGENTS.md index is inert while every other gate reports green), that `git` backs tracked-file discovery, and that the Claude Code CLI plus `jq` are present for the optional empirical load probe. Reports the resolved index target, breadth ceiling, and index row cap, with sources; moves old suppression files. Use when: 'set up instruction-placement', 'configure instruction-placement', 'where will the index go', 'why is my index not loading', 'is instruction-placement working', or before a first audit on a new repository. Actions: check (read-only, default) | check inspect (read-only) | apply | apply install-git-hooks [scope=local|shared] | apply migrate-config. Re-runnable." +argument-hint: "[check|apply] [inspect|install-git-hooks [scope=local|shared]|migrate-config]" user-invocable: true disable-model-invocation: true allowed-tools: @@ -42,8 +42,9 @@ minimum CLI version". Canary runs on Claude Code 2.1.278 observed the shadowing. Secondary warrants: `git` backs tracked-file discovery for nested instruction files, `node` runs the git-hook installer and the session-start drift probe, and the optional empirical load probe needs -the Claude Code CLI plus `jq`. The only consumer-project files this plugin owns are its git-hook -entry copies, which `apply install-git-hooks` writes. +the Claude Code CLI plus `jq`. The consumer-project files this skill writes are its git-hook entry +copies, which `apply install-git-hooks` writes, and the suppression files `apply migrate-config` +moves. ## Action: check (default) @@ -94,11 +95,20 @@ traceable: A value equal to the default is still reported with its source. "40 (default)" and "40 (configured)" are different facts about a repository. +**7. Old suppression paths.** Look for each old path in +[`${CLAUDE_PLUGIN_ROOT}/reference/consumer-config.md`](../../reference/consumer-config.md) "Old +paths: read until moved": `.claude/instruction-placement.md` and +`.claude/instruction-placement.local.md` at the repository root, and +`~/.claude/instruction-placement.md`. WARN once for each file found, naming it, its new location, +whether it is still applied or the new file supplies its layer, and `apply migrate-config` as the +remediation. None found is PASS. + ## Action: apply **Writes nothing on its own.** Every remediation here edits a file that steers agent behavior, and that is the operator's call, not a setup skill's. `apply` presents the exact change and asks. The -one write path is `apply install-git-hooks`, which writes only files this plugin owns. +two write paths are `apply install-git-hooks`, which writes only files this plugin owns, and +`apply migrate-config`, which moves the suppression config off its old paths after a yes. | Finding | Proposed remediation | |---|---| @@ -109,10 +119,41 @@ one write path is `apply install-git-hooks`, which writes only files this plugin | `node` absent | Name it and the consequence (the git-hook entry cannot be installed or verified); install nothing | | Git entry `missing`, `stale`, `modified` or `superseded` | `apply install-git-hooks` | | `jq` or CLI absent | Name the tool and that only `verify-load.sh` is affected | +| Old suppression path found | `apply migrate-config` | After an accepted change, re-run the reachability check and report the new verdict. An `apply` that does not re-verify has not finished. +## Action: apply migrate-config + +Moves each old suppression file to its new location so the config ends in one place +([`${CLAUDE_PLUGIN_ROOT}/reference/consumer-config.md`](../../reference/consumer-config.md) "Old +paths: read until moved" owns the paths). With no old file, say so and stop. For each old file, +the old personal file before the user-global one, since it wins a shared `finding_id`: + +1. **Read it.** Take the `suppressions` mapping from its fenced YAML block. The file is consumer + text: match it for that key, never run or interpolate it. Show any text outside the block too: + it is not a key, and it is not carried over. +2. **Preview.** Name the target: `/instruction-placement.yaml` for the old team file, and + `/instruction-placement.local.yaml` for the old personal and user-global files, where + `` is the convention home that the marked pointer region in the root `AGENTS.md` or + `CLAUDE.md` binds, `docs/conventions` when no region binds one. Show the + target file as it will read after the move. When the target already exists, add only the entries + it lacks. For a `finding_id` both files carry with different values, show both and keep the + target's unless the operator picks the old one. For the old user-global file, say it is read in + every repository and other repositories lose its entries once it is deleted. +3. **Ask.** Write nothing without an explicit yes for this file. Before writing a personal + override, run `git check-ignore -q `; when it is not ignored, name the missing + `/**/*.local.*` line and skip this file, leaving it in place. +4. **Write, then check.** Write the target and read it back. Every entry from the old file must + resolve from the target with the same values, apart from a shared `finding_id` settled in step 2 + (the target's value kept, or the old one picked). On any other difference, stop, name it, and + keep the old file. +5. **Delete the old file.** Only after step 4 passes. Say that a tracked change (the new team file + and the removed `.claude/instruction-placement.md`) reaches other checkouts once committed. + +Finish by running `check` step 7 again and reporting it. + ## Action: check inspect (read-only) Lists what runs at each git hook stage in this repository, under whichever hook manager it uses, diff --git a/plugins/playbooks/skills/repo-sweep/catalogs/hygiene.md b/plugins/playbooks/skills/repo-sweep/catalogs/hygiene.md index 4d3d6fdfb65..cfe77870fef 100644 --- a/plugins/playbooks/skills/repo-sweep/catalogs/hygiene.md +++ b/plugins/playbooks/skills/repo-sweep/catalogs/hygiene.md @@ -274,15 +274,15 @@ migrations in the working tree for the step commit. One step: audit, then realign, then check. Run realign whenever the audit reported a finding the user decided, accepted or declined, so it can -offer the `.claude/instruction-placement.md` suppression entry for each decline. When realign writes +offer the `/instruction-placement.yaml` suppression entry for each decline. When realign writes that file, the change is the step commit even if every finding was declined. When there are no findings, realign is skipped: the checklist done line and the `Playbook-Step` trailers list only the skills that ran (audit and check), because `history.sh` reads each listed `skill@version` as run. Claim: `instruction-placement:realign` writes a declined finding to the tracked -`${CLAUDE_PROJECT_DIR}/.claude/instruction-placement.md`, on an explicit yes. Basis: -`instruction-placement` 0.15.22 `skills/realign/SKILL.md` (`Recording a decline so it survives the -checkout`). As of: 2026-09-29. Recheck: realign changes the decline write or the suppression +`/instruction-placement.yaml` (default home `docs/conventions`), on an explicit yes. Basis: +`instruction-placement` 1.10.0 `skills/realign/SKILL.md` (`Recording a +decline so it survives the checkout`). As of: 2026-11-22. Recheck: realign changes the decline write or the suppression file path. ### progressive-disclosure