@yagni-app/code 0.3.1 → 0.3.3

package/dist/extension/pipeline/orchestrator.js

@@ -3,7 +3,11 @@
  *
  * Sequences `runStage` for the build stages (map → plan → implement), threading
  * each stage's `finalOutput` into the next as `{previous}` (mirrors the subagent
- * example's chain). Then it runs the bounded review→fix LOOP: each round fans the
+ * example's chain). In MISSION mode (`deps.mission`, from the headless entry's
+ * `--plan-file` / `--memo-file`) the build half is entered part-way: an approved
+ * plan skips map + plan and seeds implement, an injected memo stands in for the
+ * map brief, and the review→fix loop below runs exactly as it always does — see
+ * mission.ts. Then it runs the bounded review→fix LOOP: each round fans the
  * review stage out across the 3 lenses (parallel, bounded by MAX_CONCURRENCY),
  * parses each lens with `parseFindings` (with ONE cheap format-recovery re-ask
  * for a healthy lens that broke the findings contract — spec §3e), unions them,
@@ -21,13 +25,16 @@
  * findings — i.e. a false "reviewed and clean").
  */
 import { addRunUsage, aggregateRunUsage, DEFAULT_RUN_BUDGET, EMPTY_RUN_USAGE, exceedsBudget } from "./budget.js";
+import { attributeFindings, checkerFindings, composeFixNote, composeResidue, composeSynthesizerInput, mergeFindings, parseOpenFindings, renderFindings, stripOpenFindings, } from "./checker.js";
+import { auditClaims, parsePartition } from "./fanout.js";
 import { extractFindingsBlock, hasBlockingFindings, parseFindings, shouldStop, unionFindings } from "./findings.js";
+import { missionSeed, missionSkippedStages, normalizeMission } from "./mission.js";
 import { withResilience } from "./resilience.js";
 import { runStage as defaultRunStage } from "./runner.js";
-import { makeRunVerify, parseChangedPaths } from "./verify.js";
-import { REQUIRED_LENSES, REVIEW_LENSES, reaskStage, reviewStage, selectStages } from "./stages.js";
+import { makeRunVerify, makeWorkstreamCheck, parseChangedPaths, } from "./verify.js";
+import { builderStage, fixerStage, orchestratorStage, partitionReaskStage, PARTITION_CALLER_LABEL, REQUIRED_LENSES, REVIEW_LENSES, reaskStage, reviewStage, selectStages, synthesizerFixStage, synthesizerStage, SYNTHESIZER_CALLER_LABEL, workstreamCallerLabel, } from "./stages.js";
 import { snapshotWorkspace as defaultSnapshotWorkspace, workspaceChanged } from "./workspace.js";
-import { DEFAULT_RESILIENCE_POLICY, MAX_CONCURRENCY, MIN_TOOL_CALLS_FOR_HEALTH, TOOL_ERROR_FAIL_RATE, } from "./types.js";
+import { DEFAULT_RESILIENCE_POLICY, MAX_CONCURRENCY, MAX_FANOUT_CONCURRENCY, MAX_FANOUT_CONCURRENCY_ULTRA, MAX_FIX_TURNS, MIN_TOOL_CALLS_FOR_HEALTH, TOOL_ERROR_FAIL_RATE, } from "./types.js";
 /** Error thrown when a build stage fails; carries the partial run for the caller. */
 export class PipelineStageError extends Error {
     stageId;
@@ -134,6 +141,35 @@ function serializeBlocking(findings) {
     })
         .join("\n");
 }
+/** Sum a fan's per-child usage into the one figure the fan summary reports. */
+function sumStageUsage(results) {
+    return results.reduce((acc, r) => ({
+        input: acc.input + r.usage.input,
+        output: acc.output + r.usage.output,
+        cacheRead: acc.cacheRead + r.usage.cacheRead,
+        cacheWrite: acc.cacheWrite + r.usage.cacheWrite,
+        cost: acc.cost + r.usage.cost,
+        turns: acc.turns + r.usage.turns,
+    }), { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 });
+}
+/**
+ * The implement handoff a FAN produces: the recorded decision, then each
+ * workstream's own report under its name and claims, then any edit that landed
+ * outside every claim. This is what `reviewInput` becomes today; the synthesizer
+ * (spec decision 5) takes it as its input and replaces it with a reconciled
+ * summary, so the shape is deliberately one a seam-reconciler can read.
+ */
+function composeFanHandoff(decision, workstreams, results, violations) {
+    const parts = [`Fanned ${workstreams.length} ways: ${decision.reason}`];
+    workstreams.forEach((w, i) => {
+        const body = results[i]?.finalOutput.trim() || "(this workstream reported nothing)";
+        parts.push(`## ${w.name} (${w.tier})\nClaimed: ${w.files.join(", ")}\n\n${body}`);
+    });
+    if (violations.length > 0) {
+        parts.push(["## Out-of-claim edits", "These paths changed outside every workstream's claims:", ...violations.map((p) => `- ${p}`)].join("\n"));
+    }
+    return parts.join("\n\n");
+}
 /** Bounded-concurrency map preserving input order (copied from the subagent example). */
 async function mapWithConcurrencyLimit(items, concurrency, fn) {
     if (items.length === 0)
@@ -165,6 +201,7 @@ export async function runPipeline(ticket, deps) {
         });
     const snapshotFn = deps.snapshotWorkspace ?? defaultSnapshotWorkspace;
     const runVerifyFn = deps.runVerify ?? makeRunVerify();
+    const runWorkstreamCheckFn = deps.runWorkstreamCheck ?? makeWorkstreamCheck();
     const progress = (p) => deps.onProgress?.(p);
     // Count of record_decision tool calls that completed without error across the
     // whole run, tapped off the NDJSON stream (spec §3c: the FINISH trailer's
@@ -185,13 +222,19 @@ export async function runPipeline(ticket, deps) {
     // backend unreachable) — attribution then degrades to the caller label alone,
     // never blocking the pipeline.
     const runId = deps.checkpointMeta?.runId;
-    const stageDepsFor = (tag) => {
+    // `callerLabel` is set only by the implement diamond's children (the
+    // partitioner's `go:implement:partition` and each builder's
+    // `go:implement:<workstream>`), so per-workstream spend attributes for free the
+    // way review lenses do. Every other stage leaves it undefined and keeps the
+    // runner's own `go:<stage>` default.
+    const stageDepsFor = (tag, callerLabel) => {
         const onEvent = deps.onEvent;
         return {
             cwd: deps.cwd,
             signal: deps.signal,
             ...(deps.childEnv ? { env: deps.childEnv } : {}),
             ...(runId ? { attribution: { runId } } : {}),
+            ...(callerLabel ? { callerLabel } : {}),
             onEvent: (ev) => {
                 if (ev.type === "tool_execution_end" && ev.toolName === "record_decision" && !ev.isError) {
                     decisionsRecorded += 1;
@@ -212,7 +255,24 @@ export async function runPipeline(ticket, deps) {
     const all = deps.stages ?? selectStages("full");
     // R3-b: aggregate usage ceiling, checked at each stage boundary.
     const budget = deps.budget ?? DEFAULT_RUN_BUDGET;
-    const buildStages = all.filter((s) => BUILD_STAGE_IDS.includes(s.id));
+    // Mission mode (spec: sandbox harness parity). The factory produced the plan
+    // and a human approved it at the mission's plan gate, so re-running the
+    // pipeline's own map/plan would silently discard that approval and hollow out
+    // the gate: an injected plan enters the pipeline at implement instead. An
+    // injected memo is the repo brief the map stage would have written, so map is
+    // skipped whenever either input is present. All three rules are pure (see
+    // mission.ts); the orchestrator only applies them to the stage list + seed.
+    const mission = normalizeMission(deps.mission);
+    const missionSkipped = missionSkippedStages(mission);
+    const buildStages = all.filter((s) => BUILD_STAGE_IDS.includes(s.id) && !missionSkipped.includes(s.id));
+    if (mission) {
+        log("mission_mode", {
+            plan: Boolean(mission.plan),
+            memo: Boolean(mission.memo),
+            skipped: missionSkipped,
+            entry: buildStages[0]?.id,
+        });
+    }
     // The last build stage's handoff is the working-tree diff (checked by the
     // no_changes guard), not its prose; only the earlier stages thread text forward.
     const finalBuildId = buildStages[buildStages.length - 1]?.id;
@@ -270,6 +330,369 @@ export async function runPipeline(ticket, deps) {
     const priorUsage = resume?.priorUsage ?? EMPTY_RUN_USAGE;
     const currentUsage = () => addRunUsage(priorUsage, aggregateRunUsage(stages, rounds));
     const overBudget = () => exceedsBudget(currentUsage(), budget);
+    // The map stage's brief, kept for the partitioner's repo context. Absent on a
+    // mission run (map is skipped there — the injected memo stands in) and on any
+    // run whose map stage did not produce one; the partition contract is explicit
+    // that thin context means single-writer, never a guessed partition.
+    let mapBrief;
+    /**
+     * The diamond's CHECKER (spec decision 6): each workstream's own claims
+     * typechecked in their package dirs (attribution), then ONE full verify —
+     * typecheck plus the repo's own tests, `baselinePaths`-scoped as always — on the
+     * merged tree. The full suite runs on the tree that ships, not once per child.
+     *
+     * Fail-open on both halves: a seam that throws records an honest log line and
+     * contributes no findings, because the candidate is real work sitting in the
+     * working tree and the review loop's own gate still runs downstream.
+     */
+    const runChecker = async (targets) => {
+        if (deps.signal?.aborted)
+            return { scoped: [], verify: null };
+        let scoped = [];
+        if (targets.length > 0) {
+            try {
+                scoped = await runWorkstreamCheckFn(deps.cwd, targets, deps.signal);
+            }
+            catch (err) {
+                log("checker_scoped_failed", { error: err instanceof Error ? err.message : String(err) });
+            }
+        }
+        let verify = null;
+        try {
+            verify = await runVerifyFn(deps.cwd, deps.signal, baselinePaths);
+        }
+        catch (err) {
+            log("checker_verify_failed", { error: err instanceof Error ? err.message : String(err) });
+        }
+        log("checker_done", {
+            scoped: scoped.map((s) => ({ name: s.name, ran: s.ran, findings: s.findings.length })),
+            verify: verify ? { ran: verify.ran, ok: verify.ok, findings: verify.findings.length } : null,
+        });
+        return { scoped, verify };
+    };
+    /**
+     * The checker → synthesizer → bounded fix loop (spec decisions 5, 6 and 7).
+     * Returns the text that becomes `reviewInput`.
+     *
+     * On a FAN the synthesizer always runs: with one shared worktree the union diff
+     * is already in place, so its job is the seams (plus the checker's findings and
+     * any out-of-claim edits the handoff already names), and its `finalOutput` IS
+     * the implement handoff. On the SINGLE-WRITER path there are no seams, so the
+     * builder's own output stays the handoff — byte-identical to today whenever
+     * verification is clean, which is the point.
+     *
+     * Then the fix loop: while verification (or the synthesizer's own "## Open
+     * findings") still reports concrete defects, re-engage the implicated builders
+     * at their ORIGINAL tier scoped to their claims, hand unattributable findings to
+     * the synthesizer (the one builder, on the single-writer path), and re-check.
+     * Capped at MAX_FIX_TURNS; findings still open at the cap are named in the
+     * handoff so the review loop inherits the truth, never a known-broken candidate
+     * dressed as clean.
+     */
+    const runImplementChecker = async (args) => {
+        const { stage, workstreams, handoff } = args;
+        const fanned = workstreams.length > 0;
+        const targets = workstreams.map((w) => ({ name: w.name, files: w.files }));
+        let report = await runChecker(targets);
+        let body = handoff;
+        // Defects the SYNTHESIZER named in its latest summary, kept apart from the
+        // deterministic ones: they are only re-read when the synthesizer itself ran
+        // again, so a stale "## Open findings" section can never keep the loop alive
+        // after the builders have fixed what it pointed at.
+        let summaryDefects = [];
+        if (fanned) {
+            const synth = await runStageFn({ ...synthesizerStage(), tools: stage.tools }, { ticket: promptTicket, previous: composeSynthesizerInput(handoff, report), grounded }, stageDepsFor({ stageId: stage.id }, SYNTHESIZER_CALLER_LABEL));
+            stages.push(synth);
+            if (!isFailed(synth) && synth.finalOutput.trim()) {
+                body = synth.finalOutput;
+                summaryDefects = parseOpenFindings(body);
+            }
+            else {
+                // An unreconciled fan is still real work in the tree: keep the fan's own
+                // handoff (every workstream named) rather than dropping to nothing.
+                log("synthesizer_degraded", { exitCode: synth.exitCode, stopReason: synth.stopReason });
+            }
+        }
+        let open = mergeFindings(checkerFindings(report), summaryDefects);
+        let turn = 0;
+        while (open.length > 0 && turn < MAX_FIX_TURNS) {
+            if (deps.signal?.aborted)
+                break;
+            const over = overBudget();
+            if (over) {
+                log("fix_loop_stop", { reason: "budget_exceeded", turn: turn + 1, detail: over });
+                break;
+            }
+            turn += 1;
+            const { assigned, unassigned } = attributeFindings(open, workstreams);
+            const reengaged = [];
+            // The implicated builders, each at its original tier and scoped to its own
+            // claims. Parallel under the same ceiling the fan itself ran at, because
+            // they are the same writers on the same disjoint file sets.
+            if (assigned.length > 0) {
+                const ceiling = deps.isUltra?.() ? MAX_FANOUT_CONCURRENCY_ULTRA : MAX_FANOUT_CONCURRENCY;
+                const fixes = await mapWithConcurrencyLimit(assigned, ceiling, async (a) => {
+                    const siblings = workstreams.filter((s) => s.name !== a.workstream.name);
+                    progress({ kind: "stage_start", stageId: stage.id, workstream: a.workstream.name });
+                    const fixed = await runStageFn({ ...fixerStage(a.workstream, renderFindings(a.findings), siblings), tools: stage.tools }, { ticket: promptTicket, grounded }, stageDepsFor({ stageId: stage.id, workstream: a.workstream.name }, workstreamCallerLabel(a.workstream.name)));
+                    progress({
+                        kind: "stage_done",
+                        stageId: stage.id,
+                        workstream: a.workstream.name,
+                        ...(isFailed(fixed) ? { degraded: "failed" } : {}),
+                    });
+                    return fixed;
+                });
+                stages.push(...fixes);
+                reengaged.push(...assigned.map((a) => a.workstream.name));
+                // A fix turn that CRASHED does not fail the stage: the merged candidate is
+                // still real work, the re-check below will simply still see the findings,
+                // and the cap bounds how long that can go on. Recorded, never silent.
+                const brokenFixes = fixes.map((r, i) => (isFailed(r) ? assigned[i].workstream.name : null)).filter(Boolean);
+                if (brokenFixes.length > 0)
+                    log("fix_turn_child_failed", { turn, workstreams: brokenFixes });
+            }
+            // Unattributable findings are seam work: the synthesizer's on a fan, and the
+            // one builder's on the single-writer path (where nothing is attributable by
+            // construction). Run AFTER the builders, never beside them: the synthesizer
+            // is the one child with no claims, so it must not write while they do.
+            if (unassigned.length > 0) {
+                const findingsText = renderFindings(unassigned);
+                const fixStage = fanned ? synthesizerFixStage(findingsText) : fixerStage(undefined, findingsText);
+                const fixed = await runStageFn({ ...fixStage, tools: stage.tools }, { ticket: promptTicket, grounded }, stageDepsFor({ stageId: stage.id }, fanned ? SYNTHESIZER_CALLER_LABEL : undefined));
+                stages.push(fixed);
+                if (fanned) {
+                    if (!isFailed(fixed) && fixed.finalOutput.trim()) {
+                        body = fixed.finalOutput;
+                        summaryDefects = parseOpenFindings(body);
+                    }
+                    reengaged.push("synthesizer");
+                }
+                else {
+                    reengaged.push("single writer");
+                }
+            }
+            else {
+                // Nobody re-read the summary this turn, so its findings were answered by
+                // the builders and the deterministic re-check below is the honest verdict.
+                // The section that named them goes with them: the synthesizer does not run
+                // again on this path, so an untouched "## Open findings" would ride into
+                // the review handoff beside a fix note calling the final check clean.
+                if (summaryDefects.length > 0)
+                    body = stripOpenFindings(body);
+                summaryDefects = [];
+            }
+            progress({ kind: "fix_turn", turn, findings: open.length, reengaged });
+            log("fix_turn", { turn, findings: open.length, reengaged });
+            report = await runChecker(targets);
+            open = mergeFindings(checkerFindings(report), summaryDefects);
+        }
+        if (open.length > 0) {
+            log("fix_loop_open", { turns: turn, findings: open.length });
+            return `${body}\n\n${composeResidue(open, turn)}`;
+        }
+        if (turn > 0)
+            return `${body}\n\n${composeFixNote(turn)}`;
+        return body;
+    };
+    /**
+     * The implement diamond (spec "Diamond execution"). Returns the StageResult the
+     * build loop treats as "the implement stage". The diamond owns `stages` for the
+     * whole implement boundary: every real child (partitioner, builders,
+     * synthesizer, fixers, and the single writer itself) is pushed here, and the
+     * SYNTHETIC fan summary never is — its children already carry the spend.
+     *
+     * The single-writer path deliberately runs exactly today's `runStageFn` call,
+     * with today's arguments and today's untagged deps; the checker gate that
+     * follows it changes nothing downstream unless verification actually found
+     * something.
+     */
+    const runImplementDiamond = async (stage, previous, beforeBuild) => {
+        const pinned = deps.fanout === "always";
+        const partitionCtx = {
+            ...(mapBrief?.trim() ? { repoBrief: mapBrief } : {}),
+            ...(mission?.memo ? { missionMemo: mission.memo } : {}),
+            ...(pinned ? { pinned: true } : {}),
+        };
+        // The LANE owns the tool whitelist: the blind eval lane strips the grounding
+        // tools from its stage list, and a diamond child rebuilt from the default
+        // stage data would quietly hand them back. So the partitioner drops
+        // `ask_yagni` when the run is blind, and every builder inherits the lane's own
+        // implement whitelist rather than PIPELINE_V1's.
+        const partitionDef = orchestratorStage(partitionCtx);
+        const partitionStage = grounded
+            ? partitionDef
+            : { ...partitionDef, tools: partitionDef.tools.filter((t) => t !== "ask_yagni") };
+        const partitionTag = { stageId: stage.id };
+        const runSingleWriter = async (decision) => {
+            recordDecision(decision, beforeBuild);
+            const written = await runStageFn(stage, { ticket: promptTicket, previous, grounded }, stageDepsFor({ stageId: stage.id }));
+            stages.push(written);
+            // A failed or credit-starved writer never reaches the checker: the build
+            // loop's own guard turns it into `partial` or the honest stage error, and
+            // verifying a tree nobody finished writing would only add noise.
+            if (isFailed(written) || creditExhaustionReason(written) || deps.signal?.aborted)
+                return written;
+            // Decision 7: the fix loop applies identically here — the same checker gate,
+            // the same one builder re-engaged, the same cap.
+            const text = await runImplementChecker({ stage, workstreams: [], handoff: written.finalOutput });
+            return text === written.finalOutput ? written : { ...written, finalOutput: text };
+        };
+        const partition = await runStageFn(partitionStage, { ticket: promptTicket, previous, grounded }, stageDepsFor(partitionTag, PARTITION_CALLER_LABEL));
+        stages.push(partition);
+        // A credit-starved partitioner exits 0 with an empty transcript; stop with the
+        // actionable message rather than degrading into a fan of equally starved children.
+        const partitionCredit = creditExhaustionReason(partition);
+        if (partitionCredit) {
+            log("pipeline_failed", { stageId: stage.id, reason: partitionCredit });
+            throw new PipelineStageError(stage.id, `Pipeline stopped at ${stage.id}: ${partitionCredit}`, stages);
+        }
+        // Overlapping claims are the HARD rejection (spec decision 3): fail here,
+        // naming the colliding paths, so no run ever discovers two writers on one file
+        // at merge time. Everything else is soft: one cheap format re-ask, then the
+        // recorded single-writer degrade.
+        let parsed = isFailed(partition) ? null : parsePartition(partition.finalOutput);
+        if (parsed && !parsed.ok && parsed.hard) {
+            log("fanout_collision", { collisions: parsed.collisions });
+            throw new PipelineStageError(stage.id, `Pipeline stopped at ${stage.id}: ${parsed.reason}`, stages);
+        }
+        if (parsed && !parsed.ok && partition.finalOutput.trim() && !deps.signal?.aborted) {
+            const reask = await runStageFn(partitionReaskStage(partitionStage), { ticket: promptTicket, previous: partition.finalOutput, grounded }, stageDepsFor(partitionTag, PARTITION_CALLER_LABEL));
+            stages.push(reask);
+            log("fanout_reask", { reason: parsed.reason });
+            if (!isFailed(reask) && reask.finalOutput.trim()) {
+                const second = parsePartition(reask.finalOutput);
+                if (!second.ok && second.hard) {
+                    log("fanout_collision", { collisions: second.collisions });
+                    throw new PipelineStageError(stage.id, `Pipeline stopped at ${stage.id}: ${second.reason}`, stages);
+                }
+                parsed = second;
+            }
+        }
+        if (!parsed || !parsed.ok) {
+            const why = !parsed
+                ? "the partitioner did not finish, so the plan was built by one writer"
+                : `the partition could not be read (${parsed.reason}), so the plan was built by one writer`;
+            return runSingleWriter({ mode: "single", reason: why });
+        }
+        if (parsed.decision.mode === "single")
+            return runSingleWriter(parsed.decision);
+        const workstreams = parsed.decision.workstreams ?? [];
+        // Decision 8: the budget seam is consulted once, and only for a real fan. A
+        // pinned benchmark lane skips the consult by design; an absent seam allows,
+        // and a seam that THROWS degrades to the single writer rather than crashing
+        // a run whose map and plan spend is already sunk.
+        if (!pinned && deps.fanoutBudget) {
+            let verdict;
+            try {
+                verdict = await deps.fanoutBudget();
+            }
+            catch {
+                verdict = { allow: false, reason: "the fan-out budget check could not be consulted" };
+            }
+            if (!verdict.allow) {
+                return runSingleWriter({
+                    mode: "single",
+                    reason: verdict.reason ?? "the fan-out budget check declined this run",
+                });
+            }
+        }
+        recordDecision(parsed.decision, beforeBuild);
+        // Width is what the partitioner chose; the session's parallel ceiling is what
+        // actually runs at once, so a width-8 partition runs 4-at-a-time outside ultra
+        // rather than being refused.
+        const ceiling = deps.isUltra?.() ? MAX_FANOUT_CONCURRENCY_ULTRA : MAX_FANOUT_CONCURRENCY;
+        log("fanout_start", { width: workstreams.length, concurrency: Math.min(workstreams.length, ceiling) });
+        const builders = await mapWithConcurrencyLimit(workstreams, ceiling, async (w) => {
+            const siblings = workstreams.filter((s) => s.name !== w.name);
+            // Per-builder lifecycle, exactly the review fan-out's shape: each child
+            // starts and finishes on its own timing, tagged so interleaved events stay
+            // attributed, and callers that ignore the tag still see one implement pair.
+            progress({ kind: "stage_start", stageId: stage.id, workstream: w.name });
+            const built = await runStageFn({ ...builderStage(w, siblings), tools: stage.tools }, { ticket: promptTicket, previous, grounded }, stageDepsFor({ stageId: stage.id, workstream: w.name }, workstreamCallerLabel(w.name)));
+            // A child that died says so on its own done beat (the `degraded` flag the
+            // review lenses already use), so no surface paints a dead builder as built.
+            progress({
+                kind: "stage_done",
+                stageId: stage.id,
+                workstream: w.name,
+                ...(isFailed(built) ? { degraded: "failed" } : {}),
+            });
+            return built;
+        });
+        stages.push(...builders);
+        const builderCredit = builders.map((r) => creditExhaustionReason(r)).find((v) => Boolean(v));
+        if (builderCredit) {
+            log("pipeline_failed", { stageId: stage.id, reason: builderCredit });
+            throw new PipelineStageError(stage.id, `Pipeline stopped at ${stage.id}: ${builderCredit}`, stages);
+        }
+        // Claim audit (spec decision 4): claims are prefixes, so anything the fan
+        // changed outside all of them — minus the tree's pre-run dirt — is a named
+        // violation for the synthesizer to reconcile, never a silent edit.
+        const afterFan = await snapshotFn(deps.cwd, deps.signal);
+        const baseline = new Set(baselinePaths ?? []);
+        const changedByFan = parseChangedPaths(afterFan.status).filter((p) => !baseline.has(p));
+        const violations = auditClaims(changedByFan, workstreams);
+        if (violations.length > 0)
+            log("fanout_claim_violations", { paths: violations });
+        // Failure is honest and mirrors today's write-stage semantics (decision 9):
+        // the summary carries the failure, and the build loop's existing guard turns
+        // it into `partial` when the tree changed (siblings' work preserved, the
+        // failing workstream named) or the hard PipelineStageError when it did not.
+        const failed = builders
+            .map((r, i) => ({ r, name: workstreams[i].name }))
+            .filter((x) => isFailed(x.r));
+        const failureNote = failed
+            .map((f) => `workstream "${f.name}" failed: ${toolFailureReason(f.r) ?? f.r.errorMessage ?? f.r.stderr ?? "(no output)"}`)
+            .join("; ");
+        // The fan's own handoff: the decision, every workstream's report under its
+        // name and claims, and any out-of-claim edit. On a healthy fan it is the
+        // synthesizer's INPUT (decision 5) and the reconciled summary becomes the
+        // handoff; when a builder hard-failed it stands alone, because no partial
+        // merge is ever checked, reconciled, or handed to review.
+        const handoff = composeFanHandoff(parsed.decision, workstreams, builders, violations);
+        const finalOutput = failed.length > 0 ? handoff : await runImplementChecker({ stage, workstreams, handoff });
+        const summary = {
+            stageId: stage.id,
+            agent: stage.agent,
+            exitCode: failed.length > 0 ? 1 : 0,
+            finalOutput,
+            // Summed for honesty in logs and handoffs only: this object is NEVER pushed
+            // into `stages` (its children already are), so the run's usage is counted once.
+            usage: sumStageUsage(builders),
+            stderr: builders.map((r) => r.stderr).filter(Boolean).join("\n"),
+            toolCalls: builders.reduce((n, r) => n + r.toolCalls, 0),
+            toolErrors: builders.reduce((n, r) => n + r.toolErrors, 0),
+            ...(failed.length > 0 ? { stopReason: "error", errorMessage: failureNote } : {}),
+        };
+        log("fanout_done", { width: workstreams.length, failed: failed.map((f) => f.name), violations: violations.length });
+        return summary;
+    };
+    /** Emit + journal the diamond's verdict the moment it resolves (decision 2). */
+    function recordDecision(decision, snapshot) {
+        const shape = decision.workstreams?.map((w) => ({
+            name: w.name,
+            tier: w.tier,
+            files: w.files.length,
+        }));
+        progress({
+            kind: "fanout",
+            mode: decision.mode,
+            ...(decision.width ? { width: decision.width } : {}),
+            reason: decision.reason,
+            ...(shape ? { workstreams: shape } : {}),
+        });
+        log("fanout_decision", { mode: decision.mode, width: decision.width, reason: decision.reason });
+        writeCheckpoint(mkRecord("fanout_decision", {
+            snapshot,
+            fanout: {
+                mode: decision.mode,
+                ...(decision.width ? { width: decision.width } : {}),
+                reason: decision.reason,
+                ...(shape ? { workstreams: shape } : {}),
+            },
+        }));
+    }
     if (resume) {
         // Resume path: the build half already ran and its diff is in the working
         // tree (the caller's planResume verified the tree still matches the
@@ -283,7 +706,11 @@ export async function runPipeline(ticket, deps) {
         }
     }
     else {
-        let previous;
+        // Mission mode seeds the first surviving build stage with work that already
+        // happened: the approved plan (plus the memo as labelled repo context), or
+        // the memo alone when only map was skipped. Absent on every interactive run,
+        // where the first stage's handoff is undefined exactly as before.
+        let previous = missionSeed(mission);
         // Baseline the working tree BEFORE the (read-only) recon stages so the no-op
         // guard below can attribute any change to the build half. A git-less / non-repo
         // cwd yields an untracked snapshot and the guard fails open (see workspace.ts).
@@ -295,8 +722,18 @@ export async function runPipeline(ticket, deps) {
         for (const stage of buildStages) {
             progress({ kind: "stage_start", stageId: stage.id });
             stageEvent(stage.id, "start");
-            let r = await runStageFn(stage, { ticket: promptTicket, previous, grounded }, stageDepsFor({ stageId: stage.id }));
-            stages.push(r);
+            // The implement stage is a DIAMOND (partition → parallel builders →
+            // checker → synthesizer → bounded fix loop); every other stage is the
+            // single child it always was. The diamond owns `stages` for its whole
+            // boundary, so nothing is pushed for it here.
+            let r;
+            if (stage.id === "implement") {
+                r = await runImplementDiamond(stage, previous, beforeBuild);
+            }
+            else {
+                r = await runStageFn(stage, { ticket: promptTicket, previous, grounded }, stageDepsFor({ stageId: stage.id }));
+                stages.push(r);
+            }
             log("stage_done", { stageId: stage.id, exitCode: r.exitCode });
             // Retry a non-final build stage ONCE when it exits cleanly but hands off an
             // incomplete fragment (length-truncated or empty). A reasoning model that
@@ -374,6 +811,10 @@ export async function runPipeline(ticket, deps) {
             // The plan finish carries its finalOutput so /go can record the plan onto the
             // work item; no other boundary streams the full stage text.
             stageEvent(stage.id, "finish", stage.id === "plan" ? { output: r.finalOutput } : undefined);
+            // The map brief is the partitioner's repo context on an interactive run
+            // (mission runs skip map and hand it the injected memo instead).
+            if (stage.id === "map")
+                mapBrief = r.finalOutput;
             previous = r.finalOutput;
             // R3-b: stop honestly if the build half alone blew the run budget.
             const over = overBudget();

package/dist/extension/pipeline/personas.d.ts

@@ -9,6 +9,12 @@
  *   - reviewer (business-fit lens): call `review_business_match` and treat a
  *     conflict with a recorded decision as at least High.
  *
+ * The implement diamond adds two more roles: `orchestrator` (the read-only
+ * partitioner, carrying the ```partition output contract `parsePartition` reads)
+ * and `synthesizer` (the seam-reconciler that writes the review handoff). Its
+ * parallel builders reuse the `worker` body plus a per-workstream clause from
+ * {@link builderPersonaClause}.
+ *
  * The reviewer also carries the strict, parseable findings output contract so
  * the `{previous}` handoff into the fix stage parses (see `findings.ts`).
  *
@@ -17,6 +23,7 @@
  * `--append-system-prompt` temp file. Inline TS constants (no .md copy step)
  * keep the whole thing pure and unit-testable.
  */
+import type { PartitionWorkstream } from "./fanout.js";
 import type { PipelineStage } from "./types.js";
 /** Persona body keyed by the agent name referenced in `stages.ts`. */
 export declare const PERSONA_BODIES: Record<string, string>;
@@ -29,10 +36,18 @@ export declare const PERSONA_BODIES: Record<string, string>;
  * measurement.
  */
 export declare const BLIND_PERSONA_BODIES: Record<string, string>;
+/**
+ * The per-workstream clause appended to a fan-out builder's (or fixer's) persona:
+ * the files it owns, what its siblings own, and the shared-tree discipline. With
+ * no workstream (the single-writer path, including its fix turns) only the
+ * shared-tree rules apply, since there is nothing to pin against.
+ */
+export declare function builderPersonaClause(workstream?: PartitionWorkstream, siblings?: PartitionWorkstream[]): string;
 /**
  * Resolve the system-prompt body for a stage. For non-review stages this is the
  * role body; for the review stage it appends the lens-specific clause and the
- * required findings output contract so the reviewer's output parses.
+ * required findings output contract so the reviewer's output parses. A stage
+ * carrying a `personaClause` (the fan-out builders) gets it appended last.
  *
  * `grounded` defaults true (every real /go stage). The M6 eval passes
  * `grounded: false` to select the grounding-free bodies + lens clauses for the