Skip to content

feat(instruction-placement): read suppressions from the config-cascade layers - #18085

Open
melodic-automation-lanes[bot] wants to merge 3 commits into
mainfrom
work-resolve-issue/issue-18012-44964532394-1
Open

melodic-automation-lanes[bot] wants to merge 3 commits into
mainfrom
work-resolve-issue/issue-18012-44964532394-1

Conversation

@melodic-automation-lanes

@melodic-automation-lanes melodic-automation-lanes Bot commented Nov 22, 2026 •

Copy link
Copy Markdown
Contributor

Closes #18012

Summary

Opened by the work-resolve-issue lane. The run's own summary:

instruction-placement now reads declined findings from the config-cascade layers. The team layer is <home>/instruction-placement.yaml, checked by a new JSON Schema, and the personal override is <home>/instruction-placement.local.yaml. There is no userConfig option, by the issue's placement rule: a decline is a per-repo convention. The three old paths (.claude/instruction-placement.md, .claude/instruction-placement.local.md and ~/.claude/instruction-placement.md) are still read for their layer while no new file supplies that layer. Each run prints one warning naming the old file, the new location and /instruction-placement:setup apply migrate-config. When both files exist the new one wins, and the warning names both and lists the ids that are only in the old file or differ. The new setup action previews the move, writes only on a yes, reads the result back, and deletes the old file only after the readback matches. Choices and their basis: suppressions are keyed policy-floor data, so the team file is YAML (.yaml), not prose (.md), per config-cascade 'Location of the team layer', and the personal override keeps that extension per the .local.&lt;ext&gt; rule. The old user-global file moves to the personal override, not userConfig, because a personal-layer entry never suppresses on its own, so no result changes. No retirements.yaml manifest was added: config-cascade says a .claude/&lt;name&gt; team file is a supported fallback with no retirement record, and a manifest path cannot start with ~. The old-paths section is named 'read until moved' so it does not borrow the record-backed 'dual-read window' term.

Not verified

  • Tidy skipped: the change has 28 files and touches the shared path scripts/ and three areas (plugins/instruction-placement, docs/contracts, plugins/playbooks), all over the tidy cutoffs
  • Eval suites (the two new cases and the four updated ones) and validate-cases.py were not run here: no model access and no interpreter in this lane. Left to the PR's CI eval-cases and evals-schema jobs
  • check-convention-yaml.sh, check-org-repo-tokens.sh and the config-cascade-semantics sync check are CI-only and did not run here. Left to the PR's CI
  • comment-hygiene, size-check and typos were skipped by check-affected in this lane (fetch blocked, missing script, tool not installed)
  • No retirements.yaml manifest for the old paths. A reviewer cited docs/contracts/retired-conventions 'The dual-read deprecation window'. This change follows config-cascade instead, which says a .claude/<name> team file is a supported fallback with no record, and a manifest path cannot start…
  • Untracked dotfiles at the checkout root (.bashrc, .bash_profile, .profile, .zshrc, .zprofile, .gitconfig, .ripgreprc, .mcp.json, .idea, .vscode) came from the sandbox environment, not this run; they are not part of the change

Fix

  • plugins/instruction-placement/reference/consumer-config.md: layer table now shows plugin default, userConfig (none), team <home>/instruction-placement.yaml and personal <home>/instruction-placement.local.yaml; new 'Old paths: read until moved' subsection with the old-path table, both…
  • plugins/instruction-placement/schemas/instruction-placement.schema.json: new JSON Schema for the team file (suppressions keyed by a 16-hex finding_id, with the five required entry keys)
  • plugins/instruction-placement/skills/setup/SKILL.md: check step 7 reports each old suppression file; new 'apply migrate-config' action (preview, yes gate, gitignore guard for the personal file, readback, then delete); description and argument-hint name the action
  • plugins/instruction-placement/skills/audit/SKILL.md: resolves the new surface plus old paths with the warning; scan-set exclusion now covers old-path files; link made relative
  • plugins/instruction-placement/skills/delta/SKILL.md: suppression surface is the new file plus old paths with the warning (two places)
  • plugins/instruction-placement/skills/realign/SKILL.md: writes declines to <home>/instruction-placement.yaml; asks for migrate-config first when the old team file still supplies the layer; resolve step and multi-repo write path updated
  • realign, delta, audit and setup SKILL.md: define <home> at first use as the convention home, not the memory-tier home
  • plugins/instruction-placement/README.md: artifact table and Configuration section name the new location and the old-path window
  • plugins/instruction-placement/context/findings-artifact.md: two references now name <home>/instruction-placement.yaml
  • plugins/instruction-placement/evals/dl-old-team-path-still-read-with-warning/{case.yaml,prompt.md,samples/old-path-warning.json}: new eval, old file only: values apply and the warning names the old file, the new location and the setup command
  • plugins/instruction-placement/evals/dl-both-team-paths-new-wins/{case.yaml,prompt.md,samples/both-files-named.json}: new eval, both present: new wins and the warning names both files and the old-only id
  • evals/su-migrate-config-preview-before-write: new eval: migrate-config previews and asks before any write, deletes only after readback, skips an unignored personal file
  • evals/au-suppression-file-not-a-candidate: new eval: a candidate on the suppression file is dropped
  • plugins/instruction-placement/evals/dl-committed-decline-holds-fresh-worktree/{prompt.md,samples/suppressed-by-team-layer.json}: now the 'new layer only' case at docs/conventions/instruction-placement.yaml
  • plugins/instruction-placement/evals/dl-personal-only-entry-not-applied/{prompt.md,samples/personal-only-not-applied.json}: personal override path is now docs/conventions/instruction-placement.local.yaml
  • plugins/instruction-placement/evals/ra-decline-offered-as-suppression/{case.yaml,prompt.md,samples/tracked-file-committed.json}: grader regex and samples target instruction-placement.yaml
  • plugins/instruction-placement/evals/su-config-values-with-sources/prompt.md: fixture names the new file and the absence of old paths
  • docs/contracts/config-cascade/README.md: the instruction-placement Implementers row names the new layers, schema and old-path reads; the plugin moves from the not-yet-migrated list to 'already on the location axis'
  • docs/contracts/config-cascade/CHANGELOG.md: Unreleased entry for the row change (no contract_version change)
  • plugins/playbooks/skills/repo-sweep/catalogs/hygiene.md: the instruction-placement step's notes and claim now name the new suppression file (its Recheck trigger had fired)
  • scripts/org-repo-tokens-allow.tsv: allowlist row for the new schema's $id URL, the same row other plugin schemas have
  • .changes/instruction-placement/work-resolve-issue-issue-18012-44964532394-1-690c26c6.md: minor changelog fragment
  • .changes/playbooks/work-resolve-issue-issue-18012-44964532394-1-66d94034.md: patch changelog fragment

Verification

The runner ran each check from the base copy against 7747063:

  • scripts/check-changelog-fragments.sh --check: passed
  • scripts/check-changed-skills.sh --merge-base: passed

The run reports:

  • check-changelog-fragments: all 4 fragments valid
  • check-changed-skills: 5 skills checked, 0 failed (setup description at first 1073 codepoints, over the 1024 limit; shortened to 1014 and re-run)
  • check-affected: 14 passed, 9 skipped (first run failed validate-plugins on the same setup description length; passed after the fix)
  • fresh-context review subagent over the whole diff: 2 high, 4 medium and 6 low findings. Fixed: org-repo-tokens allowlist row, config-cascade Implementers row and list, stale playbooks catalog claim, the delta 'three layers' line, the personal-override write wording, the migrate readback exception,…
  • The lane run: https://github.com/melodic-software/claude-code-plugins/actions/runs/44964532394

The review-feedback round after that run added the <home> definitions and the two evals, su-migrate-config-preview-before-write and au-suppression-file-not-a-candidate. That round ran no check, so the eval matcher samples and skill checks for those files are checked by CI on the new head.

Left out: the items under Not verified.

Related

#18012

Lane-Activity: work-resolve-issue/resolve-issue
@github-actions

Copy link
Copy Markdown
Contributor

Lane run report

Field Value
Activity pr-refine/fix-docs

Run 44968269419, attempt 1

Field Value
Model rung 0
Leg handoff
Run job success
Activity step success
Commits pushed none (read lane)
Run 44968269419

Failed GitHub API calls

No failed call recorded by the run job's scripts.

@github-actions

Copy link
Copy Markdown
Contributor

Lane run report

Field Value
Activity pr-unblock/resolve-conflicts

Run 44968663731, attempt 1

Field Value
Model rung 0
Leg handoff
Run job success
Activity step success
Commits pushed none (read lane)
Run 44968663731

Failed GitHub API calls

No failed call recorded by the run job's scripts.

Lane-Activity: pr-unblock/resolve-conflicts
@github-actions

Copy link
Copy Markdown
Contributor

Lane run report

Field Value
Activity pr-unblock/apply-conflict-patch

Run 44968663731, attempt 1

Field Value
Model rung 0
Leg base
Run job success
Activity step success
Commits pushed d5a37e2
Run 44968663731

Failed GitHub API calls

No failed call recorded by the run job's scripts.

@github-actions

github-actions Bot commented Nov 22, 2026 •

Copy link
Copy Markdown
Contributor

claude-security-review reviewed a92c2b04c85fa74bf710ebb2420a633bcd1a86e4: read 10 of 10 changed file(s); 0 finding(s), 0 as inline comments.

Security review: PR #18085, incremental (d5a37e2 → a92c2b0)

This review is blocking only: the lane already reviewed an earlier head, so it reports only CRITICAL and IMPORTANT findings.

I found no security issues. I read all 10 files in the incremental scope in full in .claude-lane/incremental.diff. None of them matches a trusted-path glob, none is a plugin manifest, and none is a trust control. The trusted-trigger check, the lane token, the kill switch, the broker or signer, and the merge holds are all unchanged.

What I checked:

  • Skill text (audit, delta, realign and setup SKILL.md under plugins/instruction-placement/skills/). These edits add prose that says what <home> means for the suppression surface. It is the convention home that the marked pointer region binds, or docs/conventions when no region binds one. It is not the memory-tier home. The edits delete or soften no standing instruction. The migrate-config safeguards from the prior review are unchanged:
    • a per-file preview and an explicit yes before any write;
    • a readback before the old file is deleted;
    • a git check-ignore check before the personal override is written.
      The edits add no tool grants and no commands.
  • Two new eval cases (au-suppression-file-not-a-candidate, su-migrate-config-preview-before-write). Each holds only a prompt, regex and LLM graders, and sample answers. Their allowed_tools are [Read, Glob, Grep, Skill, Bash], the same set the existing cases use. The prompts tell the model to run nothing against a repository. The new migrate-config case checks that the skill previews and asks before it writes, which supports the guardrail.
  • Embedded text: the evals and skill text hold no instructions aimed at the review lane.

Spend: none billable. Running the two new eval cases in CI uses prepaid model credit.

critical-findings: 0

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

claude-review: 4 inline finding(s) on d5a37e2e6e7633d1222c9347af74a36d184bf167; the summary is in this lane's pull request comment.

claude-lane: claude-review

plugins/improvement/README.md melodic-software/claude-code-plugins 1 names this marketplace's own repository (install, issue target or example)
plugins/improvement/skills/find/context/unattended.md melodic-software/claude-code-plugins 1 raw link to this marketplace's own published doc
plugins/instruction-placement/git-hooks/entries.json melodic-software/claude-code-plugins 1 shipped default lefthook remote; install.mjs uses the installed marketplace's git URL when it has one
plugins/instruction-placement/schemas/instruction-placement.schema.json melodic-software/claude-code-plugins 1 schema $id or $ref naming this marketplace's published schema

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Fail a change that loosens a check (kind 4: an allowlist entry was added).

  • Before: check-org-repo-tokens.sh rejected any file not on the allowlist that names melodic-software/claude-code-plugins.
  • After: it accepts that token in plugins/instruction-placement/schemas/instruction-placement.schema.json.

Issue #18012 is the only spec that counts here. It never mentions this allowlist entry or gives a reason for it. The PR body's explanation ("the same row other plugin schemas have") does not count as a reason, because only the issue text can give one.

To clear this, either have the issue name this entry and say why, or remove the entry together with the schema $id that needs it.

claude-lane: claude-review

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

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

Evidence: scripts/org-repo-tokens-allow.tsv:71, plugins/instruction-placement/schemas/instruction-placement.schema.json:3

The row at line 71 is a counted exception (count 1) for the schema's $id at instruction-placement.schema.json:3, which names this marketplace's published schema URL. It has the same reason text as the other plugin schema rows in this file (for example lines 5, 7, 9 and 13), and the file's header asks for a reason on each row, which this row has. So the entry is narrow and follows the file's convention. The finding is a different question: whether issue 18012 has to authorize the entry, since the review only counts issue text as a reason. This lane cannot settle that. A person has to choose: amend the issue to name the schema and its $id row, or accept the entry as the standard schema exception. Removing the row would also mean dropping the schema $id, which the other plugin schemas all carry, so this lane made no edit.

@github-actions

github-actions Bot commented Nov 22, 2026 •

Copy link
Copy Markdown
Contributor

claude-review reviewed a92c2b04c85fa74bf710ebb2420a633bcd1a86e4: read 10 of 10 changed file(s); 1 finding(s), 0 as inline comments.

Code review: PR #18085, changes since d5a37e2e (blocking only)

This lane already reviewed an earlier head, so this review is blocking only: it reports only blocking findings and leaves out advisory ones. I read every hunk of all 10 files in .claude-lane/incremental.diff.

What this push changes

  • <home> is now defined. realign, delta, audit and setup now say at first use that <home> is the convention home: the one the pointer region binds, or docs/conventions when none does. They also say it is not the memory-tier home. In realign, the old "the home" wording at lines 141 and 188 now reads "the memory-tier home". This addresses my earlier comment on realign/SKILL.md:96.

  • New eval su-migrate-config-preview-before-write. It tests three things:

    • the preview comes before any write;
    • nothing is written or deleted without a yes;
    • the old file is deleted only after the new file is read back;
    • the git check-ignore skip for the personal target.

    This matches steps 2–5 of setup/SKILL.md "Action: apply migrate-config" (lines 137–153). It covers the criterion from my earlier setup/SKILL.md:127 comment.

  • New eval au-suppression-file-not-a-candidate. It checks that the candidate on docs/conventions/instruction-placement.yaml is dropped while the coverage numbers still count that file. This matches audit/SKILL.md:230-233. It covers the scan-set exclusion criterion from my earlier audit/SKILL.md:227-228 comment.

  • Regex graders. I checked each regex grader by hand against its pass and fail samples, and every sample is classified as its file says. The near-miss samples are rejected as intended. For example, instruction-placement.local.yaml does not match instruction-placement\.yaml, and a line that names the file only as the layer has none of the exclusion words. Both case files use the same layout as the existing dl-* cases.

Blocking

Other notes

  • No .claude-plugin/plugin.json or marketplace.json changed in this push, so there are no manifest lines.
  • No settled-threads file was provided, so no thread counted as settled.
  • Spend: the two new eval cases add eval runs on prepaid model credits.
  • I ran nothing. I did not run the new evals or the graders; my check of the samples was done by reading them.

Loosened checks would be marked: fail. This is the default, because the prompt has no loosened_check_verdict: or loosened_check_patterns: line; patterns: 0. The prompt has no loosened_check_decision_record: line either, so the citation requirement was not checked.

No verifier subagents were dispatched: the push's only candidates were checked directly against the skill text.

Verifier dropped 0 of 0 candidates.

@github-actions

Copy link
Copy Markdown
Contributor

Lane run report

Field Value
Activity pr-unblock/address-feedback

Run 44969694312, attempt 1

Field Value
Model rung 0
Leg handoff
Run job success
Activity step success
Commits pushed none (read lane)
Run 44969694312

Failed GitHub API calls

No failed call recorded by the run job's scripts.

Lane-Activity: pr-unblock/address-feedback
Lane-Thread: PRRT_kwDOTCGFQM66eaQg
Lane-Thread: PRRT_kwDOTCGFQM66eaQj
Lane-Thread: PRRT_kwDOTCGFQM66eaQn
@github-actions

Copy link
Copy Markdown
Contributor

Lane run report

Field Value
Activity pr-unblock/apply-feedback-patch

Run 44969694312, attempt 1

Field Value
Model rung 0
Leg base
Run job success
Activity step success
Commits pushed a92c2b0
Run 44969694312

Failed GitHub API calls

No failed call recorded by the run job's scripts.

@melodic-automation-lanes

Copy link
Copy Markdown
Contributor Author

pr-unblock / address-feedback finished round 1 of max 4 on a92c2b0.

@github-actions

Copy link
Copy Markdown
Contributor

Lane run report

Field Value
Activity pr-unblock/publish-feedback

Run 44969694312, attempt 1

Field Value
Model rung 0
Leg base
Run job success
Activity step success
Commits pushed none recorded
Run 44969694312

Failed GitHub API calls

No failed call recorded by the run job's scripts.

@melodic-automation-lanes

Copy link
Copy Markdown
Contributor Author

Unattended merge: native auto-merge leaves this pull request unarmed at head a92c2b04c85fa74bf710ebb2420a633bcd1a86e4. No person needs to act: a lane clears this reason, and the next scheduled run judges it again.

pr-merge's gate refuses its verifier verdict (verify:missing)

@melodic-automation-lanes melodic-automation-lanes Bot added the needs-human Human-in-the-loop required; autonomous sessions must not resolve items carrying this. label Nov 22, 2026
@melodic-automation-lanes

Copy link
Copy Markdown
Contributor Author

The pr-unblock lane stopped on this pull request and needs a person: an adjudicator found that a disputed review finding turns on what the change is meant to do, which a person decides.

Reason: intent

  • Reason: feedback-question-intent
  • Resume key: a92c2b04c85fa74bf710ebb2420a633bcd1a86e4 (the head the lane stopped on)

To resume, deal with the reason above, remove the needs-human label (and do-not-merge, if set), then dispatch the pr-unblock workflow with pr-number=18085 and activity=address-feedback:

gh workflow run pr-unblock.yml -R melodic-software/claude-code-plugins -f pr-number=18085 -f activity=address-feedback

@github-actions

Copy link
Copy Markdown
Contributor

Lane run report

Field Value
Activity pr-unblock/report-escalation

Run 44969694312, attempt 1

Field Value
Model rung 0
Leg base
Run job success
Activity step success
Commits pushed none recorded
Run 44969694312

Failed GitHub API calls

No failed call recorded by the run job's scripts.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

needs-human Human-in-the-loop required; autonomous sessions must not resolve items carrying this.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

instruction-placement: read config from the config-cascade layers, not ~/.claude

0 participants