instruction-placement/delta: persist baseline in artifact-protocol baselines/ slot instead of ephemeral state-key

[kyle-sexton]

Parent

Refs #3803

Agent Brief

Type: Feature
Summary: The instruction-placement delta skill persists its diff spine in the artifact-protocol baselines slot, and records declined findings on the marketplace finding-suppression surface, replacing its ephemeral state-key mechanism.

Amended 2026-09-06. The original brief asked for a single move: put the baseline in the artifact-protocol baselines slot "the same way the overengineering delta skill uses", and expect a declined finding to survive into another worktree from there. Verification of the first attempt (#3833) established that the sibling plugin does not work that way, and that the destination cannot satisfy the durability requirement. Overengineering keeps its baseline branch-keyed in the memory tier for the diff spine, and records declined findings against the marketplace contract in docs/conventions/finding-suppression/README.md, saying so directly in plugins/overengineering/reference/consumer-config.md: "The entry format is the marketplace's finding-suppression contract, not this plugin's." The baselines slot lives in the memory tier, and docs/conventions/topic-docs/README.md states that a memory document is visible "only in the checkout that wrote it", marks a sibling worktree invisible, and forbids carrying this file class across with .worktreeinclude ("never baselines or raw scratch"). Routing declines into the baselines slot would therefore fail the durability criterion under every default configuration, and would mint a third mechanism for suppression, which is the breach this issue exists to remove. The criteria below split the two concerns accordingly.

Current behavior:
The instruction-placement delta skill stores its previous-run baseline under an ephemeral state key. The sibling overengineering delta skill splits the same state across two homes: a branch-keyed baseline in the artifact-protocol baselines slot for the diff spine, and declined findings on the tracked finding-suppression surface. Two ways of persisting the same kind of state, which is the silent second way the reuse-or-replace discipline forbids. A practical consequence: declined findings do not survive a move to a different worktree, so a re-run resurrects findings the operator already dismissed.

Desired behavior:
The delta skill becomes an artifact-protocol participant for its diff spine, and a finding-suppression consumer for operator judgment. The diff spine is written to and read from the baselines slot the protocol defines, branch-keyed, the same slot and the same way the overengineering delta skill uses it. Declined findings are recorded on the tracked .claude/<surface-name>.md surface the finding-suppression contract defines, so git carries them between checkouts. A finding declined on one branch and committed is still declined when the skill runs from another worktree whose branch carries that commit. The ephemeral state key is removed, not left in place as a fallback.

Key interfaces:

• The delta skill's diff-spine read and write — moves from the state-key mechanism to the artifact-protocol baselines slot, branch-keyed.
• The delta skill's declined-finding read — moves from the state-key mechanism to the finding-suppression surface.
• The realign skill's decline write — currently writes declined only into the branch-scoped findings artifact; must also record the decline on the finding-suppression surface, since realign is where an operator's decline originates.
• The plugin's own surface name under the finding-suppression contract — new, following the naming the contract prescribes.
• The skill's own artifact-protocol reference document — new, describing which slots the skill uses and what it stores in them, in the shape the other protocol participants use.

Acceptance criteria:

• The delta skill reads and writes its diff spine in the artifact-protocol baselines slot, branch-keyed, and no ephemeral state-key path remains anywhere in the plugin.
• Declined findings are recorded on a tracked .claude/<surface-name>.md surface conforming to docs/conventions/finding-suppression/README.md, with the plugin's surface name registered the way the contract requires.
• The realign skill writes an operator's decline to that suppression surface, not only to the branch-scoped findings artifact.
• Declining a finding on one branch and committing the surface file, then running the skill from a different worktree of the same repository whose branch carries that commit, does not resurface the declined finding.
• The skill ships its own artifact-protocol reference document following the shape used by the existing protocol participants.
• The findings-artifact document's schema version is incremented if the change edits its location formula, per that document's own rule, and no statement in it is left describing the retired mechanism.
• /skill-quality:check passes for every instruction-placement skill the change touches.
• markdownlint passes on the changed files.
• The instruction-placement plugin version is bumped per repo convention.
• The plugin README and any reference doc listing the plugin's skills or protocol participants reflect the change.

Out of scope:

• Changing what the delta skill detects, its noise budget, or its report shape.
• Changing the overengineering delta skill.
• Changing the artifact protocol itself, or the finding-suppression contract itself.

Blocked by

None

[kyle-sexton]

Claimed by the autonomous worker lane.

• instance: vm-worker-202609050257
• lease expires: 2026-09-06T09:10:00Z (60 min TTL, renewed while active)
• scope: implement, test, independently review, open a close-linked draft PR. This lane does not merge.

Running concurrently with #3810 on a disjoint plugin tree. Both may touch one row each of docs/SKILL-CHEAT-SHEET.md; distinct lines, so a conflict is unlikely, and the worker is instructed to merge rather than force if one appears.

---

Generated by Claude Code

[kyle-sexton]

[kyle-sexton]

Handoff: PR #3831 is open, close-linked and review-ready. Lease released; the merge lane owns it from here.

Baseline now lives at .work/instruction-placement/<branch-slug>/baselines/delta-baseline.md, resolved through the plugin-local binding and a cmp-verified copy of the artifact protocol.

Read before closing this issue. Criterion 2 (a declined record surviving a different worktree) is not met — the default memory root is still per-checkout, and full cross-checkout durability needs a tracked suppression surface. The PR states this plainly and records it as a revisit trigger; a reviewer may prefer to reopen or split rather than accept the partial.

Also worth knowing: review caught that nothing in the plugin ever wrote a first baseline, so as originally written every delta run would have routed out forever. A bootstrap cycle mirroring overengineering fixes that.

---

Generated by Claude Code

[kyle-sexton]

Two spec decisions this issue needs before either implementation can merge

Raised by the merge lane (ccr-session-babysit-loop-20260906) while deduplicating this issue's PRs. Two autonomous worker-lane sessions implemented #3811 independently: #3831 (claude/3811-delta-artifact-slot) and #3833 (feat/3811-delta-baseline-slot). #3833 is closed as a duplicate; #3831 is canonical and is now blocked, waiting on the two questions below. Neither is a code defect a PR author can just fix, so recording them here rather than letting them die with the closed PR.

1. Acceptance criterion 2 does not hold, and the fix amends this issue

A fresh-context verifier on #3833, working with the authoring rationale withheld, found that criterion 2 fails for two independent reasons.

Mechanism. realign writes declined into the branch-scoped findings artifact and never touches the baseline; delta mirrors decisions from that artifact. The sequence the criterion describes, decline in one worktree then run from another, never gets the decline into the baseline at all, because no delta run happens on the declining branch after the decline.

Visibility. The baseline resolves into the memory tier. The topic-docs convention marks a sibling worktree invisible and says a memory document is visible "only in the checkout that wrote it" unless a .worktreeinclude pattern carries it, and it then forbids that escape hatch for this file class: carried patterns cover slice indexes, stage indexes and ledgers, "never baselines or raw scratch (machine-bound)."

The reuse question underneath it. docs/conventions/finding-suppression/README.md is this marketplace's owner doc for the record that a finding is known and accepted, and it lives on a tracked surface precisely so git carries it across checkouts. plugins/overengineering already adopts it and says so: "The entry format is the marketplace's finding-suppression contract, not this plugin's." It keeps its baseline branch-keyed in the memory tier and puts declines somewhere else. So the two concerns are separate, and this issue conflated them: routing declines into the baselines slot mints a third suppression mechanism, which is the reuse-or-replace breach this issue was filed to remove.

#3831 reaches the same wall from the other side. Its body concedes: "Full cross-checkout durability for an operator judgment needs a tracked suppression surface (docs/conventions/finding-suppression/, the shape overengineering uses), which this PR does not add."

The decision: does #3811 keep criterion 2 as written, which requires splitting the state, the diff spine in the artifact-protocol baselines slot branch-keyed and the durable declines on the tracked finding-suppression surface, or is criterion 2 amended to the branch-keyed baseline that #3831 actually delivers, with cross-checkout decline durability split out to a follow-up? #3833's commits a40aeb3a onward attempted the split and the branch ended red, which is some evidence the split is the larger change.

2. The branch-mismatch bootstrap contradicts itself, and either fix changes behavior

Independently flagged by both review lanes on #3831, and confirmed against the source:

• Branch-mismatch: the stored baseline "is kept, not overwritten, and the run takes the bootstrap path below."
• The bootstrap path captures "over baselines/delta-baseline.md in the same home before comparing anything."
• One baseline path exists per home, so those are the same file.
• The skill's own hard rule: "A baseline the run did not consume is never overwritten."

context/findings-artifact.md calls the bootstrap "a separate write", but no separate location is defined anywhere, so that phrase is unimplementable under the single-slot design. Concretely, two branch names that slug to one directory (documented as possible, "The slug mapping is lossy") let one branch's delta run destroy the other's declined records, which #3831 itself calls "the one judgment in this plugin that no other surface can reconstruct."

The decision: on a branch: mismatch, route out the way a missing artifact does, preserving the hard rule and never bootstrapping over another branch's baseline, or drop the "kept, not overwritten / separate write" language from both the skill and the contract and accept the overwrite? Question 1's outcome constrains this one, since moving declines to a tracked surface changes what is actually at risk in the collision.

Both are the repo owner's call. #3831 is held rather than guessed at.

---

Merge lane ccr-session-babysit-loop-20260906. Canonical PR: #3831. Closed duplicate: #3833.

---

Generated by Claude Code