agent-dealer 1.2.7 → 1.2.8

package/bundle/server/dist/coordinator/prompts-execution-contract.test.js

@@ -0,0 +1,107 @@
+// NOT-306: developer and reviewer prompts render the frozen execution contract
+// as dedicated sections — mode, non-goals, exit predicate, one-PR boundary,
+// per-criterion evidence — without telling the worker to rediscover them.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { buildDeveloperPrompt, buildReviewerPrompt } from "./prompts.js";
+import { parseReviewerResult } from "./reviewer-result.js";
+const CONTRACT = {
+    version: "v1",
+    executionMode: "bug fix",
+    nonGoals: ["Rewriting the Linear ticket from Dealer", "Changing product scope after start"],
+    exitPredicate: "The login retry succeeds observably on the second attempt.",
+    onePrStoppingPoint: "Stop after the retry fix lands with its regression test.",
+    acceptanceCriteria: [
+        { text: "Retry succeeds on the second attempt", evidence: "auth tests | npm run test:unit | green" },
+        { text: "No new warnings in the log", evidence: null },
+    ],
+};
+const LEGACY_SNAPSHOT = {
+    title: "Add widget",
+    description: "Build the widget.",
+    acceptanceCriteria: "Widget renders.",
+    repo: "acme/app",
+    baseBranch: "main",
+};
+const CONTRACT_SNAPSHOT = { ...LEGACY_SNAPSHOT, executionContract: CONTRACT };
+test("developer prompt renders every contract section verbatim, never as pointers", () => {
+    const prompt = buildDeveloperPrompt({ taskSnapshot: CONTRACT_SNAPSHOT, round: 1 });
+    assert.match(prompt, /## Execution contract \(frozen v1/);
+    assert.match(prompt, /### Execution mode/);
+    assert.ok(prompt.includes("bug fix"), "mode value must appear verbatim");
+    assert.match(prompt, /### Non-goals/);
+    assert.ok(prompt.includes("Rewriting the Linear ticket from Dealer"));
+    assert.ok(prompt.includes("Changing product scope after start"));
+    assert.match(prompt, /### Exit predicate/);
+    assert.ok(prompt.includes("The login retry succeeds observably on the second attempt."));
+    assert.match(prompt, /### One-PR stopping point/);
+    assert.ok(prompt.includes("Stop after the retry fix lands with its regression test."));
+    assert.match(prompt, /### Per-criterion evidence/);
+    assert.ok(prompt.includes("Retry succeeds on the second attempt"));
+    assert.ok(prompt.includes("Evidence: auth tests | npm run test:unit | green"));
+    assert.ok(prompt.includes("No new warnings in the log"));
+    assert.match(prompt, /do not rediscover/i);
+});
+test("reviewer prompt renders the contract and demands exit-predicate plus per-criterion evidence verdicts", () => {
+    const prompt = buildReviewerPrompt({
+        taskSnapshot: CONTRACT_SNAPSHOT,
+        round: 1,
+        baseSha: "a".repeat(40),
+        headSha: "b".repeat(40),
+        diff: "diff --git a/x b/x\n+added line\n",
+    });
+    assert.match(prompt, /## Execution contract \(frozen v1/);
+    assert.ok(prompt.includes("The login retry succeeds observably on the second attempt."));
+    assert.ok(prompt.includes("Evidence: auth tests | npm run test:unit | green"));
+    // The verdict contract assesses the exit predicate and each evidence line —
+    // not just the prose acceptance criteria.
+    assert.match(prompt, /"exitPredicateAssessment"/);
+    assert.match(prompt, /EACH criterion's stated evidence/i);
+    assert.match(prompt, /never a blanket "evidence looks good"/);
+    assert.match(prompt, /"approved" additionally requires the exit predicate to hold/);
+});
+test("legacy snapshots without a contract omit the contract section but keep the shared verdict shape", () => {
+    const developer = buildDeveloperPrompt({ taskSnapshot: LEGACY_SNAPSHOT, round: 1 });
+    assert.doesNotMatch(developer, /## Execution contract/);
+    assert.match(developer, /## Acceptance criteria/);
+    const reviewer = buildReviewerPrompt({
+        taskSnapshot: LEGACY_SNAPSHOT,
+        round: 1,
+        baseSha: "a".repeat(40),
+        headSha: "b".repeat(40),
+        diff: "diff --git a/x b/x\n+added line\n",
+    });
+    assert.doesNotMatch(reviewer, /## Execution contract/);
+    // The exit-predicate/evidence verdict rules apply to every review, so the
+    // reviewer shape always carries the optional assessment field.
+    assert.match(reviewer, /"exitPredicateAssessment"/);
+    assert.match(reviewer, /Tasks without a contract omit "exitPredicateAssessment"/);
+});
+test("a null contract is identical to an absent one", () => {
+    const absent = buildDeveloperPrompt({ taskSnapshot: LEGACY_SNAPSHOT, round: 1 });
+    assert.equal(buildDeveloperPrompt({ taskSnapshot: { ...LEGACY_SNAPSHOT, executionContract: null }, round: 1 }), absent);
+});
+test("reviewer output parses an exit-predicate assessment; legacy outputs still parse", () => {
+    const withPredicate = {
+        verdict: "approved",
+        baseSha: "aaaa",
+        headSha: "bbbb",
+        acceptanceCriteriaAssessment: "All criteria met.",
+        evidenceAssessment: "Criterion 1 verified via auth tests (green); criterion 2 has no stated evidence.",
+        exitPredicateAssessment: "The retry succeeds observably on the second attempt — holds at this tip.",
+        findings: [],
+        risks: [],
+    };
+    const parsed = parseReviewerResult(`\`\`\`json\n${JSON.stringify(withPredicate)}\n\`\`\``);
+    assert.deepEqual(parsed, withPredicate);
+    const legacy = {
+        verdict: "approved",
+        baseSha: "aaaa",
+        headSha: "bbbb",
+        acceptanceCriteriaAssessment: "Meets criteria.",
+        evidenceAssessment: "Tests pass.",
+        findings: [],
+        risks: [],
+    };
+    assert.deepEqual(parseReviewerResult(JSON.stringify(legacy)), legacy);
+});

package/bundle/server/dist/coordinator/prompts.js

@@ -1,4 +1,40 @@
+import { checkMuseVisualQa, museVisualQaPromptSection, } from "../adapters/muse-visual-qa.js";
 import { formatVerificationReceiptSection, } from "./verification-receipt.js";
+/**
+ * NOT-306: render the frozen execution contract as dedicated sections. These
+ * are the ticket's own execution semantics — the worker follows them as
+ * written and never goes back to the ticket (or anywhere else) to rediscover
+ * them. Empty/absent renders nothing so legacy prompts stay byte-for-byte.
+ */
+function executionContractSection(contract) {
+    if (!contract)
+        return [];
+    const lines = [
+        `## Execution contract (frozen ${contract.version} — follow as written, do not rediscover)`,
+        `These execution semantics come from the Planner-authored ticket and are frozen for this workflow. Do not re-derive them, do not renegotiate scope, and do not ask the operator to restate them.`,
+        ``,
+        `### Execution mode`,
+        contract.executionMode,
+        ``,
+        `### Non-goals (out of scope — do not build these)`,
+        ...contract.nonGoals.map((goal) => `- ${goal}`),
+        ``,
+        `### Exit predicate (you are done only when this observably holds)`,
+        contract.exitPredicate,
+        ``,
+        `### One-PR stopping point (stop here even if more work suggests itself)`,
+        contract.onePrStoppingPoint,
+        ``,
+        `### Per-criterion evidence (verify each criterion exactly this way)`,
+    ];
+    for (const criterion of contract.acceptanceCriteria) {
+        lines.push(`- ${criterion.text}`);
+        if (criterion.evidence)
+            lines.push(`  Evidence: ${criterion.evidence}`);
+    }
+    lines.push(``);
+    return lines;
+}
 function guidanceSection(guidance) {
     if (!guidance?.length)
         return [];
@@ -9,6 +45,28 @@ function guidanceSection(guidance) {
         ...guidance.flatMap((g) => [g.trim(), ``]),
     ];
 }
+/** NOT-310: the merge-conflict repair directive. Empty/absent renders nothing so
+ * ordinary rounds produce byte-for-byte the prompt they always did. */
+function conflictRepairSection(directive) {
+    const base = directive?.baseBranch?.trim();
+    const branch = directive?.branch?.trim();
+    if (!base || !branch)
+        return [];
+    const files = (directive?.files ?? []).map((f) => f.trim()).filter((f) => f.length > 0);
+    return [
+        `## Merge conflict with ${base} — resolve it first`,
+        `This PR's branch \`${branch}\` cannot merge into \`${base}\`: the base moved and merging it conflicts. Do this before any other work in this round:`,
+        ``,
+        `1. In your worktree: \`git fetch origin ${base}\` and \`git merge origin/${base}\`.`,
+        `2. Resolve every conflict preserving both sides' intent — the base side carries other tickets' merged work, never discard it to keep your side.`,
+        files.length > 0
+            ? `   Files seen conflicting at merge time: ${files.map((f) => `\`${f}\``).join(", ")}.`
+            : `   The conflicting files are unknown — your own merge output lists them; resolve all of them.`,
+        `3. Run the full verification suite on the resolved tree, then commit the resolution.`,
+        `4. Never rebase this published branch and never force-push — the coordinator publishes your tip with a plain push.`,
+        ``,
+    ];
+}
 /** NOT-272: a resolved product_scope_decision's human note, verbatim. Empty/absent
  * renders nothing so noteless resolves produce byte-for-byte the prompt they always did. */
 function scopeDecisionSection(note) {
@@ -78,9 +136,11 @@ export function buildDeveloperPrompt(input) {
             parts.push(...formatVerificationReceiptSection(input.priorVerificationReceipt));
         }
     }
+    // NOT-310: the conflict repair leads — it is this round's purpose, read before the task.
+    parts.push(...conflictRepairSection(input.conflictRepair));
     // NOT-272: the scope decision leads — the developer reads it before the task itself.
     parts.push(...scopeDecisionSection(input.scopeDecisionNote));
-    parts.push(`## Task`, input.taskSnapshot.title, input.taskSnapshot.description, ``, `## Acceptance criteria`, input.taskSnapshot.acceptanceCriteria, ``);
+    parts.push(`## Task`, input.taskSnapshot.title, input.taskSnapshot.description, ``, `## Acceptance criteria`, input.taskSnapshot.acceptanceCriteria, ``, ...executionContractSection(input.taskSnapshot.executionContract));
     if (input.findings?.length) {
         parts.push(`## Findings to address`);
         for (const f of input.findings) {
@@ -93,6 +153,12 @@ export function buildDeveloperPrompt(input) {
     parts.push(...agentDeckSection(input.worktreePath, input.deckId));
     if (input.museDeveloper)
         parts.push(...museCronProhibitionSection());
+    // NOT-303: the screenshot-path preflight verdict is embedded before the session
+    // starts, so the worker reads it instead of discovering the Chrome.app abort
+    // mid-session. Non-Muse developers are untouched.
+    if (input.museDeveloper) {
+        parts.push(...museVisualQaPromptSection(input.museVisualQa ?? checkMuseVisualQa()));
+    }
     parts.push(`## Required`, 
     // NOT-115: encourage incremental commits so a mid-session death leaves less
     // uncommitted work for dirty_worktree escalation — soft mitigation only.
@@ -102,7 +168,7 @@ export function buildDeveloperPrompt(input) {
     `Run targeted tests for the change. A clean handoff is valid with commits plus those targeted tests — full suite / Lens checks are not required inside this timed developer spawn (they run on a separate review/verify budget). Make incremental commits with \`git\` at coherent slice boundaries (for example after the tests for that slice pass) — do not leave all work uncommitted until the very end. A final commit of any remaining changes and the **implementation conclusion** remain required before you exit.`, `Commit any remaining changes with \`git\` — do NOT push and do NOT open a pull request; the coordinator pushes your branch and opens/updates the draft PR after this session ends.`, `End your reply with a short **implementation conclusion**: what changed, why, any deviations from the acceptance criteria, and known follow-ups. This is distinct from the PR description and is required every round.`);
     return parts.join("\n");
 }
-const REVIEWER_RESULT_SHAPE = '{"verdict":"approved"|"changes_requested"|"escalated","baseSha":"...","headSha":"...","acceptanceCriteriaAssessment":"...","evidenceAssessment":"...","findings":[{"fingerprint":"stable-slug","severity":"blocking"|"non_blocking","title":"...","rationale":"...","file":"...","line":0}],"risks":["..."],"productScopeQuestion":"..."}';
+const REVIEWER_RESULT_SHAPE = '{"verdict":"approved"|"changes_requested"|"escalated","baseSha":"...","headSha":"...","acceptanceCriteriaAssessment":"...","evidenceAssessment":"...","exitPredicateAssessment":"...","findings":[{"fingerprint":"stable-slug","severity":"blocking"|"non_blocking","title":"...","rationale":"...","file":"...","line":0}],"risks":["..."],"productScopeQuestion":"..."}';
 function reviewerContractSection(baseSha, headSha) {
     // Verdict table matches docs/PRD_ISSUE_COORDINATION.md §6.4 / design NOT-150 — do not drift.
     return [
@@ -113,9 +179,18 @@ function reviewerContractSection(baseSha, headSha) {
         `- Set "baseSha" to exactly "${baseSha}" and "headSha" to exactly "${headSha}" — these are the coordinator-verified SHAs you were checked out at, not values you compute.`,
         `- "fingerprint" must be a short, stable slug for the finding (e.g. "missing-null-check-args-ts") so the same issue re-found next round is recognized as recurring, not duplicated.`,
         `- "findings" holds every blocking AND non-blocking observation; "risks" is uncertainties that are not findings tied to a location.`,
+        // NOT-306: the execution contract (when the task carries one) is judged,
+        // not just the prose criteria — the exit predicate and each criterion's
+        // stated evidence get their own assessments on top of the AC verdict.
+        `- "acceptanceCriteriaAssessment" judges the acceptance criteria; "evidenceAssessment" must judge EACH criterion's stated evidence (where to look, action/command, expected result) one by one — never a blanket "evidence looks good".`,
+        `- When the task carries an execution contract, set "exitPredicateAssessment" to whether the frozen exit predicate observably holds at this tip, and "approved" additionally requires the exit predicate to hold (AC met alone is not enough). Tasks without a contract omit "exitPredicateAssessment".`,
         `- "approved": AC met for this tip and no finding is "blocking" (non_blocking nits allowed).`,
         `- "changes_requested": any "blocking" finding a coding pass can address — including incomplete review because AC-critical files were omitted/truncated from the diff. List omitted paths in a blocking finding.`,
         `- "escalated": only when acceptance criteria / product scope are ambiguous, contradictory, or need a human product call — not ordinary code defects, not "diff too large". You MUST set non-empty "productScopeQuestion"; omit the field otherwise.`,
+        // NOT-303: a missing screenshot is never a pass. Some runtimes (Muse Code: the
+        // Chrome.app headless abort) cannot do visual QA in-session and say so in the
+        // conclusion — echo that as "visual QA not run" in "evidenceAssessment".
+        `- A missing screenshot or DOM capture is never verification: if the change has UI-visible effects and no visual evidence is in the diff, the conclusion, or the checks, state "visual QA not run" in "evidenceAssessment" — do not read the absence as a pass.`,
         `- You cannot edit files, push, or publish anything — you only return this JSON. The coordinator publishes it to GitHub on your behalf.`,
     ];
 }
@@ -176,6 +251,7 @@ export function buildReviewerPrompt(input) {
         `## Acceptance criteria`,
         input.taskSnapshot.acceptanceCriteria,
         ``,
+        ...executionContractSection(input.taskSnapshot.executionContract),
         `## Diff (base ${input.baseSha.slice(0, 8)} → head ${input.headSha.slice(0, 8)})`,
         "```diff",
         formatDiffForPrompt(input.diff).text,

package/bundle/server/dist/coordinator/prompts.test.js

@@ -248,7 +248,90 @@ test("NOT-278: a non-Muse developer prompt has the deck bootstrap but no cron pr
     assert.match(prompt, /bind_workspace/);
     assert.doesNotMatch(prompt, /cron_create/);
 });
+// NOT-303: a Muse developer prompt carries the screenshot-path preflight verdict.
+// Default (no headless shell installed): unusable, naming the Chrome.app abort and
+// requiring an explicit `Visual QA: not run` conclusion line — never sandbox
+// widening. Env is scrubbed so the test is hermetic.
+test("NOT-303: museDeveloper prompt carries the visual-QA preflight (unusable by default)", () => {
+    const saved = process.env.MUSE_HEADLESS_SHELL_BIN;
+    delete process.env.MUSE_HEADLESS_SHELL_BIN;
+    try {
+        const prompt = buildDeveloperPrompt({ taskSnapshot, round: 1, deckId: "deck-1", worktreePath: "/wt", museDeveloper: true });
+        assert.match(prompt, /## Visual QA/);
+        assert.match(prompt, /Google Chrome\.app/);
+        assert.match(prompt, /RegisterApplication/);
+        assert.match(prompt, /do not spend steps probing/i);
+        assert.match(prompt, /Visual QA: not run/);
+        assert.doesNotMatch(prompt, /--disable-sandbox/);
+        assert.doesNotMatch(prompt, /--yolo/);
+    }
+    finally {
+        if (saved !== undefined)
+            process.env.MUSE_HEADLESS_SHELL_BIN = saved;
+    }
+});
+test("NOT-303: museDeveloper prompt names the pre-installed headless shell when injected", () => {
+    const prompt = buildDeveloperPrompt({
+        taskSnapshot,
+        round: 1,
+        deckId: "deck-1",
+        worktreePath: "/wt",
+        museDeveloper: true,
+        museVisualQa: {
+            usable: true,
+            binary: "/opt/headless/chrome-headless-shell",
+            args: ["--screenshot=<png>", "--window-size=1280,800"],
+            reason: "pre-installed headless shell",
+        },
+    });
+    assert.match(prompt, /\/opt\/headless\/chrome-headless-shell/);
+    assert.match(prompt, /--screenshot=<png>/);
+    assert.match(prompt, /Google Chrome\.app/);
+});
+test("NOT-303: a non-Muse developer prompt has no visual-QA section", () => {
+    const prompt = buildDeveloperPrompt({ taskSnapshot, round: 1, deckId: "deck-1", worktreePath: "/wt" });
+    assert.doesNotMatch(prompt, /## Visual QA/);
+});
+test("NOT-303: reviewer prompt states a missing screenshot is never a pass", () => {
+    const prompt = buildReviewerPrompt(reviewerBase);
+    assert.match(prompt, /missing screenshot/i);
+    assert.match(prompt, /visual QA not run/);
+    assert.match(prompt, /do not read the absence as a pass/);
+});
 test("a deckless developer prompt still fails closed", () => {
     const prompt = buildDeveloperPrompt({ taskSnapshot, round: 1, deckId: null });
     assert.match(prompt, /misconfigured: Agent Deck is required but missing/);
 });
+// NOT-310: the conflict-repair directive renders the base, the branch, and the
+// conflicting files first — the developer merges the base before any other work.
+test("NOT-310: conflict repair directive renders base, branch, and files before the task", () => {
+    const prompt = buildDeveloperPrompt({
+        taskSnapshot,
+        round: 3,
+        conflictRepair: { baseBranch: "main", branch: "issue-9", files: ["a.ts", "b.ts"] },
+    });
+    assert.match(prompt, /## Merge conflict with main/);
+    assert.ok(prompt.includes("`issue-9`"), "branch must be named");
+    assert.ok(prompt.includes("`a.ts`") && prompt.includes("`b.ts`"), "files must be named");
+    assert.ok(prompt.includes("git fetch origin main"), "must fetch the base");
+    assert.ok(prompt.includes("git merge origin/main"), "must merge the base");
+    assert.match(prompt, /never force-push/i);
+    assert.match(prompt, /never rebase/i);
+    assert.ok(prompt.indexOf("## Merge conflict") < prompt.indexOf("## Task"), "conflict section must precede the task");
+});
+test("NOT-310: unknown conflicting files render the discover-from-merge instruction", () => {
+    const prompt = buildDeveloperPrompt({
+        taskSnapshot,
+        round: 2,
+        conflictRepair: { baseBranch: "main", branch: "issue-9", files: [] },
+    });
+    assert.match(prompt, /## Merge conflict with main/);
+    assert.match(prompt, /conflicting files are unknown/);
+});
+test("NOT-310: no conflict directive produces byte-for-byte the same prompt as before", () => {
+    const base = { taskSnapshot, round: 2 };
+    const without = buildDeveloperPrompt(base);
+    assert.doesNotMatch(without, /## Merge conflict/);
+    assert.equal(buildDeveloperPrompt({ ...base, conflictRepair: undefined }), without);
+    assert.equal(buildDeveloperPrompt({ ...base, conflictRepair: { baseBranch: "", branch: "", files: [] } }), without);
+});

package/bundle/server/dist/coordinator/reflect-trigger.js

@@ -1,198 +1,62 @@
-import { parseProfileSnapshot, parseStringList } from "@agent-dealer/shared";
-import { randomUUID } from "node:crypto";
 import { checkAgentDeckHealth } from "../adapters/agent-deck.js";
 import { callDeckTool } from "../adapters/reflect-authority.js";
 import { getIssue } from "../repository/issues.js";
-import { getAgent } from "../repository/agents.js";
-import { listFindingsForIssue } from "../repository/findings.js";
-import { listWorkflowEventsForIssue } from "../repository/workflow-events.js";
-import { listWorkerSessionsForIssue } from "../repository/worker-sessions.js";
-import { createIssueArtifact, latestIssueArtifact } from "../repository/artifacts.js";
-import { listArtifactsForIssueByKind } from "../repository/artifacts-for-issue.js";
+import { createIssueArtifact } from "../repository/artifacts.js";
+import { collectPlaybookUseReceiptsForIssue, latestReceiptErrors, reportDeckFailureSignals, } from "./playbook-feedback.js";
 import { getHumanAction, resolveHumanAction, } from "../repository/human-actions.js";
-const REFLECT_TOOL_TIMEOUT_MS = 15_000;
-/**
- * Reflect targets the deck the developer actually ran with (frozen snapshot). Playbook
- * ids are no longer on the snapshot (NOT-149) — only dead legacy agent columns still
- * carry them for in-flight profiles. New agents with an empty legacy list skip reflect
- * until a follow-up discovers playbooks dynamically from the Deck.
- */
-function resolveReflectTargets(issue) {
-    const developerSessions = listWorkerSessionsForIssue(issue.id).filter((s) => s.role === "developer");
-    const finalSession = developerSessions[developerSessions.length - 1] ?? null;
-    const snapshot = finalSession ? parseProfileSnapshot(finalSession.profileSnapshotJson) : null;
-    const developerAgent = issue.developerAgentId ? getAgent(issue.developerAgentId) : null;
-    const deckId = snapshot?.deckId ?? developerAgent?.deckId ?? null;
-    if (!developerAgent)
-        return { deckId, playbookIds: [] };
-    const fromList = parseStringList(developerAgent.playbookIdsJson);
-    if (fromList.length)
-        return { deckId, playbookIds: fromList };
-    return { deckId, playbookIds: developerAgent.playbookId ? [developerAgent.playbookId] : [] };
-}
 const defaultDeps = {
     checkHealth: checkAgentDeckHealth,
     callTool: callDeckTool,
 };
-function readConclusionExcerpt(issueId) {
-    const artifact = latestIssueArtifact(issueId, "implementation_conclusion");
-    if (!artifact?.contentJson)
-        return null;
-    try {
-        const text = JSON.parse(artifact.contentJson).text?.trim();
-        if (!text)
-            return null;
-        return text.length > 800 ? `${text.slice(0, 800)}…` : text;
-    }
-    catch {
-        return null;
-    }
-}
-function reviewRoundCount(issueId) {
-    const verdicts = listWorkflowEventsForIssue(issueId)
-        .filter((e) => e.type === "review.submitted")
-        .map((e) => {
-        try {
-            return JSON.parse(e.payloadJson ?? "{}").verdict ?? "unknown";
-        }
-        catch {
-            return "unknown";
-        }
-    });
-    return { rounds: verdicts.length, verdicts };
-}
-function buildRationale(issueId) {
-    const issue = getIssue(issueId);
-    const findings = listFindingsForIssue(issueId);
-    const resolved = findings.filter((f) => f.status === "resolved").length;
-    const recurring = findings.filter((f) => f.status === "recurring").length;
-    const { rounds, verdicts } = reviewRoundCount(issueId);
-    const conclusion = readConclusionExcerpt(issueId);
-    const parts = [
-        `Issue "${issue.title}" completed after ${rounds} review round(s)${verdicts.length ? ` (${verdicts.join(" → ")})` : ""}.`,
-        `${findings.length} finding(s) tracked across rounds (${resolved} resolved, ${recurring} recurring).`,
-    ];
-    if (conclusion)
-        parts.push(`Final implementation conclusion: ${conclusion}`);
-    return parts.join(" ");
-}
-/**
- * Playbook ids this issue already has a `playbook_patch` artifact for, from any earlier
- * reflect attempt (i.e. a prior attempt that parked partway through, before a `retry`).
- * The retry loop skips these instead of re-proposing — otherwise a park on playbook N
- * after playbooks `1..N-1` already succeeded would duplicate their Notes items on retry
- * (PR #21 review finding #1). Reflect fires at most once per issue outside of retries, so
- * every artifact this finds genuinely belongs to this same reflection, never a later
- * unrelated one.
- *
- * NOT-96: queries `playbook_patch` rows by kind directly rather than scanning the
- * newest-first, all-kinds `listArtifactsForIssue` window — on an artifact-heavy issue an
- * older `playbook_patch` could otherwise fall outside that window and get re-proposed.
- */
-function alreadyProposedPlaybookIds(issueId) {
-    const ids = new Set();
-    for (const artifact of listArtifactsForIssueByKind(issueId, "playbook_patch")) {
-        try {
-            const playbookId = JSON.parse(artifact.contentJson ?? "{}").playbookId;
-            if (playbookId)
-                ids.add(playbookId);
-        }
-        catch {
-            // malformed content — nothing to skip on its account
-        }
-    }
-    return ids;
-}
-function recordStatus(issueId, content) {
-    createIssueArtifact({ issueId, kind: "reflect_status", author: "system", content });
-}
 /**
- * Fires once per completed workflow instance, only on final_review:complete. Never throws —
- * every failure mode (no deck/playbooks configured, Agent Deck offline, a failed patch
- * proposal) is recorded as a `reflect_status`/`playbook_patch` artifact and reported back
- * as a result the caller can log, not an exception that would undo the already-committed
- * human-action resolution.
+ * Records completion evidence for a terminal issue: actual-use receipts for every
+ * terminal worker session, then one idempotent `signal_only` Deck report per
+ * failure/correction trigger. Never throws — every failure mode is recorded as a
+ * `reflect_status`/`playbook_use_receipt` artifact, never as an exception that would
+ * undo the already-committed human-action resolution.
  */
 export async function triggerIssueReflect(issueId, deps = defaultDeps) {
     const issue = getIssue(issueId);
     if (!issue)
         return "skipped";
-    const { deckId, playbookIds } = resolveReflectTargets(issue);
-    if (!deckId || playbookIds.length === 0)
-        return "skipped";
-    const healthy = await deps.checkHealth().catch(() => false);
-    if (!healthy) {
-        recordStatus(issueId, { status: "skipped", reason: "Agent Deck offline" });
-        return "skipped";
-    }
-    const attemptId = randomUUID();
-    const rationale = buildRationale(issueId);
-    const alreadyProposed = alreadyProposedPlaybookIds(issueId);
-    let anySucceeded = false;
-    let anyFailed = false;
-    for (const playbookId of playbookIds) {
-        if (alreadyProposed.has(playbookId)) {
-            // A prior attempt for this issue already proposed this playbook's patch — a retry
-            // must not duplicate it (PR #21 review finding #1).
-            anySucceeded = true;
-            continue;
-        }
-        const playbook = await deps.callTool({
-            deckId,
-            toolName: "get_playbook",
-            arguments: { playbook_id: playbookId },
-            timeoutMs: REFLECT_TOOL_TIMEOUT_MS,
-        });
-        if (!playbook.ok) {
-            recordStatus(issueId, { status: "failed", attemptId, error: playbook.reason });
-            anyFailed = true;
-            continue;
-        }
-        const proposed = await deps.callTool({
-            deckId,
-            toolName: "propose_playbook_patch",
-            arguments: {
-                kind: "update",
-                playbook_id: playbookId,
-                ops: [{ op: "add_item", section: "Notes", text: rationale }],
-                rationale,
-            },
-            timeoutMs: REFLECT_TOOL_TIMEOUT_MS,
-        });
-        if (!proposed.ok) {
-            recordStatus(issueId, { status: "failed", attemptId, error: proposed.reason });
-            anyFailed = true;
-            continue;
-        }
+    const receipts = await collectPlaybookUseReceiptsForIssue(issueId, deps);
+    const signals = await reportDeckFailureSignals(issueId, deps);
+    // Incomplete receipt collection is a visible issue-level status even when no
+    // signal candidate exists — otherwise missing evidence leaves no trace. The reason
+    // names the actual receipt errors (Deck offline vs. malformed correlation
+    // response), never a blanket "offline". Collection resumes the next time issue
+    // reflection runs — a later instance-completing trigger re-attempts every session
+    // still missing a receipt — or via an explicit reflection retry. Never changes
+    // the issue outcome.
+    if (receipts.errors > 0) {
+        const details = latestReceiptErrors(issueId);
         createIssueArtifact({
             issueId,
-            kind: "playbook_patch",
+            kind: "reflect_status",
             author: "system",
             content: {
-                patchId: proposed.data.id,
-                playbookId,
-                playbookTitle: playbook.data.title,
-                rationale,
-                status: "proposed",
+                status: "failed",
+                reason: details.length > 0
+                    ? `playbook-use receipt collection incomplete — retried on the next reflection trigger: ${details.join("; ")}`
+                    : "playbook-use receipt collection incomplete — retried on the next reflection trigger",
+                pendingReceipts: receipts.pending,
             },
         });
-        anySucceeded = true;
     }
-    recordStatus(issueId, {
-        status: anySucceeded ? (anyFailed ? "partial" : "completed") : "failed",
-        attemptId,
-        playbookCount: playbookIds.length,
-    });
-    return anySucceeded ? "triggered" : "failed";
+    if (receipts.collected > 0 || signals.sent.length > 0)
+        return "triggered";
+    if (receipts.errors > 0 || signals.error)
+        return "failed";
+    return "skipped";
 }
 /**
  * Resolves an open `reflection_interaction_required` action. Deliberately bypasses
  * `resolveHumanActionAndAdvance`'s workflow state machine entirely (commands.ts) — that
  * machine requires an active workflow instance to advance, but this action is raised
- * against an issue that is already `done` with no active instance, and resolving it must
- * never reopen the issue or enqueue developer/reviewer work (NOT-94). `retry` starts a
- * brand new correlated reflection attempt with its own new authority; `dismiss` makes no
- * further Deck call.
+ * against an issue that is already terminal with no active instance, and resolving it
+ * must never reopen the issue or enqueue developer/reviewer work (NOT-94). `retry`
+ * starts a brand new correlated evidence-collection attempt with its own new authority;
+ * `dismiss` makes no further Deck call.
  */
 export function resolveReflectionInteractionAction(actionId, resolvedBy, choice, deps = defaultDeps) {
     const action = getHumanAction(actionId);