orchestrate: catch incomplete shared-seam refactors earlier — implementer ripple report + verifier consistency lens

[TBarregren]

Filed for triage. Surfaced by the same AFK /orchestrate run on Kntnt/Mimer (#69) as the coding-standard companion #35, and related to #34. Here a change that made durable-fact promotion global updated two of three callers of a shared function; the inconsistency was caught only by the mandatory integration review. That safety net worked — but the catch can be moved earlier and cheaper.

Summary

When an implementer changes a shared function's contract or effective behaviour, an incomplete update (some callers left on the old contract) produces a locally-consistent diff that a per-issue verifier — bound to the diff — structurally cannot see. Today this class is caught only by the final integration review. Two low-cost orchestrate changes would surface most of it at the per-issue stage.

The incident

Building #69, an implementer changed durable-fact promotion to scope="global" and updated two of the three callers of distill_durable_entries, missing curate.py's cap-overflow path — stranding cap-evicted facts at project scope. The per-issue verify cleared (the diff was internally consistent); the mandatory integration review caught the cross-caller inconsistency and it was remediated. Correct end state, but a full extra integration-review + remediation cycle for something a targeted per-issue check could have flagged.

Proposed changes (both small; either helps, together stronger)

1 — Implementer "ripple" reporting. In the implement / fix prompts (engine skills/orchestrate/orchestrate.workflow.js) and in SKILL.md's three-bucket contract, instruct the implementer: if your change alters a shared symbol's contract or effective behaviour — especially beyond the files your task obviously owns — enumerate the affected call sites and state, in Assumptions & blockers, which you updated and which you did not. This turns a silent incomplete refactor into a reported one the orchestrator and the verifier can act on. It complements the coding-standard rule in #35, which the sub-agents also read via skill-by-reference.

2 — Verifier consistency / ripple lens. Give the per-issue verifier an explicit lens: when the diff changes a shared function's contract or effective behaviour, check the unchanged callers of that symbol for consistency, not only the diff itself. This is the one place a per-issue review can reach beyond the diff cheaply, and it is exactly where this class hides. Scope it to fire only when the diff touches a shared / multi-caller symbol, so it adds nothing on ordinary diffs.

Notes / non-goals

• The mandatory integration review stays as the backstop; this only shifts the common case earlier. Not every cross-cutting inconsistency is catchable per-issue, and that is fine.
• Orthogonal to Planner: model implicit issue relationships beyond Blocked-by edges — file overlap → serialize, cross-references → order #34: that is about scheduling colliding work concurrently; this is about reviewing a shared-seam change within a single issue.
• Pairs with coding-standard: general.md — when you change a shared contract, update ALL call sites (refactoring completeness) #35 (the language-agnostic coding-standard rule); this issue is the orchestrate-specific reporting + review side.

Acceptance criteria (for triage — final scope depends on the chosen direction)

• The implement / fix prompts and SKILL.md's three-bucket description instruct the implementer to enumerate and report shared-symbol call-site ripple (updated vs not) under Assumptions & blockers (Proposal 1).
• The per-issue verifier brief gains a consistency / ripple lens — on a diff that changes a shared symbol's contract or behaviour, verify the unchanged callers — firing only when a shared / multi-caller symbol is touched (Proposal 2).
• tests/test_orchestrate_skill.py (and/or the engine-prompt tests / lib/orchestrate/engine-helpers.mjs coverage) updated red-first to assert the new prompt / lens wording.
• CHANGELOG.md updated; scripts/audit.py and pytest green.

Blocked by

• None. (Related: Planner: model implicit issue relationships beyond Blocked-by edges — file overlap → serialize, cross-references → order #34, same-wave file-overlap scheduling; coding-standard: general.md — when you change a shared contract, update ALL call sites (refactoring completeness) #35, the coding-standard companion.)

Environment

• Plugin version (.claude-plugin/plugin.json): 0.12.0
• Client: Claude Code
• Operating system: macOS (darwin)

[TBarregren]

This was generated by AI during triage.

Agent Brief

Category: enhancement
Summary: Catch incomplete shared-seam refactors at the per-issue stage: the implementer reports call-site ripple (updated vs not) in its handoff, and the per-issue verifier gains a consistency lens that checks a changed shared symbol's unchanged callers.

Note for planning: Touches the same files as #46 (both edit the engine's implement/fix prompt text) — serialize after #46 or land in separate slices.

Current behavior:
When an implementer changes a shared symbol's contract or effective behaviour but updates only some callers, the diff is locally consistent; the per-issue verifier is bound to the diff and structurally cannot see the unchanged callers, so the class is caught only by the mandatory integration review — a full extra review + remediation cycle. Verified at triage: no ripple-report instruction exists in the implement/fix prompts and no unchanged-caller lens exists in the verifier briefs.

Desired behavior:

1. Implementer ripple report: the engine's implement and fix prompts — and the skill's three-bucket handoff contract — instruct the implementer: if your change alters a shared symbol's contract or effective behaviour, especially beyond the files your task obviously owns, enumerate the affected call sites and state under Assumptions & blockers which you updated and which you did not. A silent incomplete refactor becomes a reported one the orchestrator and verifier can act on.
2. Verifier consistency lens: the per-issue verifier brief gains an explicit lens: when the diff changes a shared function's contract or effective behaviour, check the unchanged callers of that symbol for consistency, not only the diff. Scoped to fire only when the diff touches a shared / multi-caller symbol, so ordinary diffs pay nothing.

Key interfaces:

• The implement and fix prompt text in the orchestrate workflow engine — gains the ripple-report instruction.
• SKILL.md's three-bucket handoff contract (Assumptions & blockers bucket) — documents the ripple report.
• The per-issue verifier brief/lens definitions — gain the conditional consistency lens.
• The repo's structural prompt/skill tests — red-first assertions for the new wording.

Acceptance criteria:

• Implement and fix prompts and the SKILL.md three-bucket description instruct the implementer to enumerate and report shared-symbol call-site ripple (updated vs not) under Assumptions & blockers.
• The per-issue verifier gains the consistency/ripple lens on unchanged callers, firing only when a shared / multi-caller symbol is touched.
• Structural tests updated red-first to assert the new prompt/lens wording; scripts/audit.py and pytest green.
• CHANGELOG.md updated.

Out of scope:

• The mandatory integration review — it stays unchanged as the backstop.
• Scheduling/serialization of colliding issues — that is Planner: model implicit issue relationships beyond Blocked-by edges — file overlap → serialize, cross-references → order #34.
• The coding-standard rule itself — that is coding-standard: general.md — when you change a shared contract, update ALL call sites (refactoring completeness) #35 (this issue is the orchestrate-side reporting + review complement).
• Any attempt to make the per-issue verifier catch every cross-cutting inconsistency — only the shared-symbol ripple class moves earlier.

[TBarregren]

Implemented test-first, independently verified, and integrated onto main by an /orchestrate --yes --merge run (green commit b566289). Gates green over the merged whole: audit.py 0 findings, 497 tests pass. Closed by the orchestrator after independent verification + integration.