@entelligentsia/forgecli 0.6.6 → 0.7.6

package/dist/extensions/forgecli/review-code.js

@@ -0,0 +1,202 @@
+// forge:review-code — native kickoff handler (FORGE-S21-T10).
+//
+// Replaces the auto-generated stub previously installed by
+// registerAllForgeCommands (forge-commands.ts). Kickoff Shim archetype
+// (Pack-04 + Pack-06): single LLM handoff in current context, no fork.
+//
+// Note: The materialized workflow (review_code.md) declares
+// `audience: subagent` — advisory only. Users may invoke this command
+// manually from the CLI; assertAudience never refuses subagent-audience
+// workflows. Orchestrator chains still dispatch via runForgeSubagent
+// directly and do NOT route through this handler.
+//
+// Iron Laws:
+//   IL1 — code only under forge-cli/src/extensions/forgecli/.
+//   IL4 — no JSON.stringify-into-subagent dispatch.
+//   IL6 — no shell-string interpolation; no spawn calls here.
+//   IL7 — every failure path emits ctx.ui.notify and returns; no silent
+//         continuation.
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { assertAudience } from "./audience-gate.js";
+import { sendKickoff } from "./kickoff.js";
+import { loadPersona, PersonaSkillLoaderError } from "./loaders/persona-skill-loader.js";
+import { loadWorkflow, WorkflowLoaderError } from "./loaders/workflow-loader.js";
+export function parseReviewCodeArgs(rawArgs, cwd) {
+    const trimmed = (rawArgs ?? "").trim();
+    if (trimmed === "") {
+        return { mode: "empty", taskRef: "", sourceLabel: "(no input — supervisor infers task from store/context)" };
+    }
+    if (trimmed.startsWith("@")) {
+        const ref = trimmed.slice(1).trim();
+        const filePath = path.isAbsolute(ref) ? ref : path.resolve(cwd, ref);
+        const seed = fs.readFileSync(filePath, "utf8");
+        return { mode: "file", taskRef: seed, sourceLabel: `(seed from file: ${ref})` };
+    }
+    return { mode: "text", taskRef: trimmed, sourceLabel: "(seed from inline text)" };
+}
+// Frontmatter persona extraction (permissive) ------------------------------
+export function extractPersonaNames(workflowMd) {
+    const lines = workflowMd.split(/\r?\n/);
+    if (lines.length === 0 || lines[0] !== "---")
+        return [];
+    let inside = false;
+    let depsBlock = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (i === 0 && line === "---") {
+            inside = true;
+            continue;
+        }
+        if (!inside)
+            break;
+        if (line === "---")
+            break;
+        if (/^deps\s*:\s*$/.test(line)) {
+            depsBlock = true;
+            continue;
+        }
+        const m = /^\s*personas\s*:\s*\[([^\]]*)\]\s*$/.exec(line);
+        if (m && (depsBlock || /^\s/.test(line))) {
+            return m[1]
+                .split(",")
+                .map((s) => s.trim().replace(/^["']|["']$/g, ""))
+                .filter((s) => s.length > 0);
+        }
+        if (depsBlock && /^[A-Za-z0-9_-]+\s*:/.test(line) && !/^\s/.test(line)) {
+            depsBlock = false;
+        }
+    }
+    return [];
+}
+export function checkMaterialization(workflowPath, workflowMd) {
+    const missing = [];
+    if (!workflowMd.includes("Store-Write Verification")) {
+        missing.push("Store-Write Verification");
+    }
+    if (!workflowMd.includes("Iron Laws")) {
+        missing.push("Iron Laws");
+    }
+    if (!workflowMd.includes("forge_store")) {
+        missing.push("forge_store");
+    }
+    const personas = extractPersonaNames(workflowMd);
+    if (personas.length === 0) {
+        missing.push("deps.personas: declaration");
+    }
+    else {
+        const bodyStart = (() => {
+            if (!workflowMd.startsWith("---\n") && !workflowMd.startsWith("---\r\n"))
+                return 0;
+            const re = /\r?\n---\r?\n/;
+            const m = re.exec(workflowMd);
+            return m ? m.index + m[0].length : 0;
+        })();
+        const body = workflowMd.slice(bodyStart);
+        const anyHit = personas.some((name) => {
+            if (!name)
+                return false;
+            const tokenRegex = new RegExp(`\\b${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`);
+            return body.includes(`${name}.md`) || tokenRegex.test(body);
+        });
+        if (!anyHit) {
+            missing.push(`persona file path (${personas.join(", ")})`);
+        }
+    }
+    void workflowPath;
+    return { ok: missing.length === 0, missing };
+}
+export function composeKickoff(opts) {
+    const { workflowMd, personaIdentity, parsed } = opts;
+    const sections = ["# /forge:review-code", ""];
+    if (personaIdentity.trim().length > 0) {
+        sections.push(personaIdentity.trim(), "");
+    }
+    sections.push("## Dispatch", "", "Run the workflow below. Specifically:", "", "1. Read the implementation diff and PROGRESS.md for `engineering/sprints/<SPRINT_ID>/<TASK_ID>/` (the source of truth).", "2. Query the store for the task and its sprint/feature context via `forge_store_query` — do NOT raw-read `.forge/store/`.", "3. Follow the workflow Algorithm verbatim: review code for correctness, test coverage, security, and architecture compliance.", "4. Write `CODE_REVIEW.md` and `CODE-REVIEW-SUMMARY.json` to the task directory using the `write` tool.", "5. Update task status by calling the `forge_store` MCP tool: `{command:'update-status', args:['task','<TASK_ID>','status','<new-status>']}`. Never raw-write `.forge/store/`. Do NOT bash-shell `forge store ...`.", "6. Honour Pack-06 Read/Write/Ask/Store discipline: writes go via the `forge_store` MCP tool; in-conversation clarifications use `forge_ask_user`.");
+    sections.push("", "---", "", "## Workflow", "", workflowMd.trim(), "", "---");
+    if (parsed.mode === "empty") {
+        sections.push("", "## Input", "", "(no seed — infer task from sprint context and store)");
+    }
+    else {
+        sections.push("", `## Input — ${parsed.sourceLabel}`, "", parsed.taskRef.trim());
+    }
+    return sections.join("\n");
+}
+// Registration -------------------------------------------------------------
+const WORKFLOW_REL_PATH = path.join(".forge", "workflows", "review_code.md");
+export function registerReviewCode(pi, options = {}) {
+    pi.registerCommand("forge:review-code", {
+        description: "Run the review-code workflow for a Forge task. " +
+            "Usage: /forge:review-code [@<file> | <free-form text>]. " +
+            "Note: this workflow is subagent-only; standalone invocations are refused. " +
+            "Orchestrator chains dispatch directly via runForgeSubagent.",
+        async handler(args, ctx) {
+            const cwd = options.cwd ?? process.cwd();
+            const workflowPath = path.join(cwd, WORKFLOW_REL_PATH);
+            let workflowMd;
+            let workflowAudience;
+            try {
+                const loaded = loadWorkflow(workflowPath);
+                workflowMd = loaded.rawMarkdown;
+                workflowAudience = loaded.audience;
+            }
+            catch (err) {
+                if (err instanceof WorkflowLoaderError) {
+                    if (err.code === "missing_file") {
+                        ctx.ui.notify(`× forge:review-code — workflow not found at ${WORKFLOW_REL_PATH}; run /forge:init or /forge:regenerate first.`, "error");
+                    }
+                    else {
+                        ctx.ui.notify(`× forge:review-code — workflow load failed (${err.code}): ${err.message}`, "error");
+                    }
+                    return;
+                }
+                const e = err;
+                ctx.ui.notify(`× forge:review-code — failed to read workflow: ${e.message ?? "unknown"}`, "error");
+                return;
+            }
+            let parsed;
+            try {
+                parsed = parseReviewCodeArgs(args, cwd);
+            }
+            catch (err) {
+                const e = err;
+                ctx.ui.notify(`× forge:review-code — failed to read seed: ${e.message ?? "unknown"}`, "error");
+                return;
+            }
+            const check = checkMaterialization(workflowPath, workflowMd);
+            if (!check.ok) {
+                for (const marker of check.missing) {
+                    ctx.ui.notify(`× workflow regression: ${marker} not found in ${workflowPath}`, "error");
+                }
+                return;
+            }
+            const personas = extractPersonaNames(workflowMd);
+            let personaIdentity = "";
+            if (personas.length > 0) {
+                try {
+                    const persona = loadPersona(personas[0], { cwd });
+                    personaIdentity = persona.identity;
+                }
+                catch (err) {
+                    if (err instanceof PersonaSkillLoaderError) {
+                        ctx.ui.notify(`× forge:review-code — persona '${personas[0]}' load failed (${err.code}): ${err.message}`, "error");
+                        return;
+                    }
+                    const e = err;
+                    ctx.ui.notify(`× forge:review-code — persona load error: ${e.message ?? "unknown"}`, "error");
+                    return;
+                }
+            }
+            if (!assertAudience({ workflowName: "review_code", audience: workflowAudience }, ctx)) {
+                return;
+            }
+            const kickoff = composeKickoff({
+                workflowMd,
+                personaIdentity,
+                parsed,
+            });
+            sendKickoff(pi, kickoff);
+        },
+    });
+}
+//# sourceMappingURL=review-code.js.map

package/dist/extensions/forgecli/review-code.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"review-code.js","sourceRoot":"","sources":["../../../src/extensions/forgecli/review-code.ts"],"names":[],"mappings":"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"}

package/dist/extensions/forgecli/review-plan.d.ts

@@ -0,0 +1,24 @@
+import type { ExtensionAPI } from "@entelligentsia/pi-coding-agent";
+export type ArgMode = "empty" | "file" | "text";
+export interface ParsedArgs {
+    mode: ArgMode;
+    taskRef: string;
+    sourceLabel: string;
+}
+export declare function parseReviewPlanArgs(rawArgs: string, cwd: string): ParsedArgs;
+export declare function extractPersonaNames(workflowMd: string): string[];
+export interface MaterializationCheck {
+    ok: boolean;
+    missing: string[];
+}
+export declare function checkMaterialization(workflowPath: string, workflowMd: string): MaterializationCheck;
+export interface ComposeKickoffOpts {
+    workflowMd: string;
+    personaIdentity: string;
+    parsed: ParsedArgs;
+}
+export declare function composeKickoff(opts: ComposeKickoffOpts): string;
+export interface RegisterReviewPlanOptions {
+    cwd?: string;
+}
+export declare function registerReviewPlan(pi: ExtensionAPI, options?: RegisterReviewPlanOptions): void;

package/dist/extensions/forgecli/review-plan.js

@@ -0,0 +1,203 @@
+// forge:review-plan — native kickoff handler (FORGE-S21-T10).
+//
+// Replaces the auto-generated stub previously installed by
+// registerAllForgeCommands (forge-commands.ts). Kickoff Shim archetype
+// (Pack-04 + Pack-06): single LLM handoff in current context, no fork.
+//
+// Note: The materialized workflow (review_plan.md) declares
+// `audience: subagent` — advisory only. Users may invoke this command
+// manually from the CLI; assertAudience never refuses subagent-audience
+// workflows. Orchestrator chains (run-task, run-sprint, fix-bug) still
+// dispatch via runForgeSubagent directly and do NOT route through this
+// handler.
+//
+// Iron Laws:
+//   IL1 — code only under forge-cli/src/extensions/forgecli/.
+//   IL4 — no JSON.stringify-into-subagent dispatch.
+//   IL6 — no shell-string interpolation; no spawn calls here.
+//   IL7 — every failure path emits ctx.ui.notify and returns; no silent
+//         continuation.
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { assertAudience } from "./audience-gate.js";
+import { sendKickoff } from "./kickoff.js";
+import { loadPersona, PersonaSkillLoaderError } from "./loaders/persona-skill-loader.js";
+import { loadWorkflow, WorkflowLoaderError } from "./loaders/workflow-loader.js";
+export function parseReviewPlanArgs(rawArgs, cwd) {
+    const trimmed = (rawArgs ?? "").trim();
+    if (trimmed === "") {
+        return { mode: "empty", taskRef: "", sourceLabel: "(no input — supervisor infers task from store/context)" };
+    }
+    if (trimmed.startsWith("@")) {
+        const ref = trimmed.slice(1).trim();
+        const filePath = path.isAbsolute(ref) ? ref : path.resolve(cwd, ref);
+        const seed = fs.readFileSync(filePath, "utf8");
+        return { mode: "file", taskRef: seed, sourceLabel: `(seed from file: ${ref})` };
+    }
+    return { mode: "text", taskRef: trimmed, sourceLabel: "(seed from inline text)" };
+}
+// Frontmatter persona extraction (permissive) ------------------------------
+export function extractPersonaNames(workflowMd) {
+    const lines = workflowMd.split(/\r?\n/);
+    if (lines.length === 0 || lines[0] !== "---")
+        return [];
+    let inside = false;
+    let depsBlock = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (i === 0 && line === "---") {
+            inside = true;
+            continue;
+        }
+        if (!inside)
+            break;
+        if (line === "---")
+            break;
+        if (/^deps\s*:\s*$/.test(line)) {
+            depsBlock = true;
+            continue;
+        }
+        const m = /^\s*personas\s*:\s*\[([^\]]*)\]\s*$/.exec(line);
+        if (m && (depsBlock || /^\s/.test(line))) {
+            return m[1]
+                .split(",")
+                .map((s) => s.trim().replace(/^["']|["']$/g, ""))
+                .filter((s) => s.length > 0);
+        }
+        if (depsBlock && /^[A-Za-z0-9_-]+\s*:/.test(line) && !/^\s/.test(line)) {
+            depsBlock = false;
+        }
+    }
+    return [];
+}
+export function checkMaterialization(workflowPath, workflowMd) {
+    const missing = [];
+    if (!workflowMd.includes("Store-Write Verification")) {
+        missing.push("Store-Write Verification");
+    }
+    if (!workflowMd.includes("Iron Laws")) {
+        missing.push("Iron Laws");
+    }
+    if (!workflowMd.includes("forge_store")) {
+        missing.push("forge_store");
+    }
+    const personas = extractPersonaNames(workflowMd);
+    if (personas.length === 0) {
+        missing.push("deps.personas: declaration");
+    }
+    else {
+        const bodyStart = (() => {
+            if (!workflowMd.startsWith("---\n") && !workflowMd.startsWith("---\r\n"))
+                return 0;
+            const re = /\r?\n---\r?\n/;
+            const m = re.exec(workflowMd);
+            return m ? m.index + m[0].length : 0;
+        })();
+        const body = workflowMd.slice(bodyStart);
+        const anyHit = personas.some((name) => {
+            if (!name)
+                return false;
+            const tokenRegex = new RegExp(`\\b${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`);
+            return body.includes(`${name}.md`) || tokenRegex.test(body);
+        });
+        if (!anyHit) {
+            missing.push(`persona file path (${personas.join(", ")})`);
+        }
+    }
+    void workflowPath;
+    return { ok: missing.length === 0, missing };
+}
+export function composeKickoff(opts) {
+    const { workflowMd, personaIdentity, parsed } = opts;
+    const sections = ["# /forge:review-plan", ""];
+    if (personaIdentity.trim().length > 0) {
+        sections.push(personaIdentity.trim(), "");
+    }
+    sections.push("## Dispatch", "", "Run the workflow below. Specifically:", "", "1. Read the plan at `engineering/sprints/<SPRINT_ID>/<TASK_ID>/PLAN.md` (the source of truth).", "2. Query the store for the task and its sprint/feature context via `forge_store_query` — do NOT raw-read `.forge/store/`.", "3. Follow the workflow Algorithm verbatim: review the plan for correctness, completeness, and risk.", "4. Write `PLAN_REVIEW.md` and `PLAN-REVIEW-SUMMARY.json` to the task directory using the `write` tool.", "5. Update task status by calling the `forge_store` MCP tool: `{command:'update-status', args:['task','<TASK_ID>','status','<new-status>']}`. Never raw-write `.forge/store/`. Do NOT bash-shell `forge store ...`.", "6. Honour Pack-06 Read/Write/Ask/Store discipline: writes go via the `forge_store` MCP tool; in-conversation clarifications use `forge_ask_user`.");
+    sections.push("", "---", "", "## Workflow", "", workflowMd.trim(), "", "---");
+    if (parsed.mode === "empty") {
+        sections.push("", "## Input", "", "(no seed — infer task from sprint context and store)");
+    }
+    else {
+        sections.push("", `## Input — ${parsed.sourceLabel}`, "", parsed.taskRef.trim());
+    }
+    return sections.join("\n");
+}
+// Registration -------------------------------------------------------------
+const WORKFLOW_REL_PATH = path.join(".forge", "workflows", "review_plan.md");
+export function registerReviewPlan(pi, options = {}) {
+    pi.registerCommand("forge:review-plan", {
+        description: "Run the review-plan workflow for a Forge task. " +
+            "Usage: /forge:review-plan [@<file> | <free-form text>]. " +
+            "Note: this workflow is subagent-only; standalone invocations are refused. " +
+            "Orchestrator chains dispatch directly via runForgeSubagent.",
+        async handler(args, ctx) {
+            const cwd = options.cwd ?? process.cwd();
+            const workflowPath = path.join(cwd, WORKFLOW_REL_PATH);
+            let workflowMd;
+            let workflowAudience;
+            try {
+                const loaded = loadWorkflow(workflowPath);
+                workflowMd = loaded.rawMarkdown;
+                workflowAudience = loaded.audience;
+            }
+            catch (err) {
+                if (err instanceof WorkflowLoaderError) {
+                    if (err.code === "missing_file") {
+                        ctx.ui.notify(`× forge:review-plan — workflow not found at ${WORKFLOW_REL_PATH}; run /forge:init or /forge:regenerate first.`, "error");
+                    }
+                    else {
+                        ctx.ui.notify(`× forge:review-plan — workflow load failed (${err.code}): ${err.message}`, "error");
+                    }
+                    return;
+                }
+                const e = err;
+                ctx.ui.notify(`× forge:review-plan — failed to read workflow: ${e.message ?? "unknown"}`, "error");
+                return;
+            }
+            let parsed;
+            try {
+                parsed = parseReviewPlanArgs(args, cwd);
+            }
+            catch (err) {
+                const e = err;
+                ctx.ui.notify(`× forge:review-plan — failed to read seed: ${e.message ?? "unknown"}`, "error");
+                return;
+            }
+            const check = checkMaterialization(workflowPath, workflowMd);
+            if (!check.ok) {
+                for (const marker of check.missing) {
+                    ctx.ui.notify(`× workflow regression: ${marker} not found in ${workflowPath}`, "error");
+                }
+                return;
+            }
+            const personas = extractPersonaNames(workflowMd);
+            let personaIdentity = "";
+            if (personas.length > 0) {
+                try {
+                    const persona = loadPersona(personas[0], { cwd });
+                    personaIdentity = persona.identity;
+                }
+                catch (err) {
+                    if (err instanceof PersonaSkillLoaderError) {
+                        ctx.ui.notify(`× forge:review-plan — persona '${personas[0]}' load failed (${err.code}): ${err.message}`, "error");
+                        return;
+                    }
+                    const e = err;
+                    ctx.ui.notify(`× forge:review-plan — persona load error: ${e.message ?? "unknown"}`, "error");
+                    return;
+                }
+            }
+            if (!assertAudience({ workflowName: "review_plan", audience: workflowAudience }, ctx)) {
+                return;
+            }
+            const kickoff = composeKickoff({
+                workflowMd,
+                personaIdentity,
+                parsed,
+            });
+            sendKickoff(pi, kickoff);
+        },
+    });
+}
+//# sourceMappingURL=review-plan.js.map

package/dist/extensions/forgecli/review-plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"review-plan.js","sourceRoot":"","sources":["../../../src/extensions/forgecli/review-plan.ts"],"names":[],"mappings":"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"}

package/dist/extensions/forgecli/run-sprint.d.ts

@@ -1,5 +1,23 @@
 import type { ExtensionAPI } from "@entelligentsia/pi-coding-agent";
+import type { StreamFn } from "@entelligentsia/pi-agent-core";
+/**
+ * Test-only seam (forge-cli#17). Resolves a StreamFn for a given dispatch
+ * context — ceremony or per-phase. Production callers leave this undefined.
+ */
+export type SprintStreamFnFactory = (ctx: {
+    kind: "task-phase" | "ceremony";
+    persona: string;
+    phase?: string;
+    taskId?: string;
+}) => StreamFn | undefined;
 export interface RegisterRunSprintOptions {
     cwd?: string;
+    /**
+     * Test-only seam (forge-cli#17). When set, each `runForgeSubagent` call
+     * spawned by the sprint handler (ceremony) and by the per-task pipeline
+     * (each phase) is dispatched with `streamFn = factory({...})`. Production
+     * callers leave this undefined.
+     */
+    streamFnFactory?: SprintStreamFnFactory;
 }
 export declare function registerRunSprint(pi: ExtensionAPI, options?: RegisterRunSprintOptions): void;

package/dist/extensions/forgecli/run-sprint.js

@@ -30,6 +30,7 @@ import { loadWorkflow } from "./loaders/workflow-loader.js";
 import { discoverForgeConfig } from "./forge-root.js";
 import { getSessionRegistry } from "./session-registry.js";
 import { loadForgePersona, runForgeSubagent } from "./forge-subagent.js";
+import { emitSyntheticEvent } from "./hook-dispatcher.js";
 import { runTaskPipeline, isNonInteractive, formatLocalTime, emitEvent, isoCompact, validateId, readState as readTaskState, isStateStale, } from "./run-task.js";
 function sprintStateFilePath(cwd, sprintId) {
     if (!validateId(sprintId)) {
@@ -90,7 +91,7 @@ function readSprintRecord(sprintId, storeCli, cwd) {
     }
 }
 async function dispatchSprintCeremony(params) {
-    const { sprintId, mode, completedTaskIds, pausedAfterIndex, cwd, forgeRoot, ctx, registry } = params;
+    const { sprintId, mode, completedTaskIds, pausedAfterIndex, cwd, forgeRoot, ctx, registry, streamFnFactory } = params;
     const startMs = Date.now();
     // Materialized workflow path — already shipped from base pack.
     const workflowName = "architect_review_sprint_completion";
@@ -131,6 +132,11 @@ async function dispatchSprintCeremony(params) {
             cwd,
             exportTag: `${sprintId}__ceremony`,
             forgeRoot,
+            streamFn: streamFnFactory?.({ kind: "ceremony", persona: personaName }),
+            // Sprint-scoped prompt-cache key — every subagent spawned across
+            // the sprint (ceremonies + per-task phases) shares this namespace
+            // so the system-prompt + persona prefix stays warm.
+            cacheSessionId: `forge:${sprintId}`,
         });
         model = result.model;
         provider = result.provider;
@@ -373,6 +379,14 @@ export function registerRunSprint(pi, options = {}) {
                     preflightGate,
                     registry,
                     resumeFromState,
+                    streamFnFactory: options.streamFnFactory
+                        ? (c) => options.streamFnFactory?.({
+                            kind: "task-phase",
+                            persona: c.persona,
+                            phase: c.phase,
+                            taskId: c.taskId,
+                        })
+                        : undefined,
                 });
                 // Capture model/provider from last task result (REVIEW FIX #1)
                 if (taskResult.model)
@@ -442,6 +456,7 @@ export function registerRunSprint(pi, options = {}) {
                                 forgeRoot,
                                 ctx,
                                 registry,
+                                streamFnFactory: options.streamFnFactory,
                             });
                         }
                         const pausedEvent = {
@@ -489,6 +504,7 @@ export function registerRunSprint(pi, options = {}) {
                 forgeRoot,
                 ctx,
                 registry,
+                streamFnFactory: options.streamFnFactory,
             });
             const sprintEvent = {
                 eventId: `${isoCompact(sprintStartMs)}_${sprintId}_sprint_complete`,
@@ -511,6 +527,22 @@ export function registerRunSprint(pi, options = {}) {
             if (!emitResult.ok) {
                 ctx.ui.notify(`⚠ forge:run-sprint — sprint-complete event emit failed: ${emitResult.stderr.trim()}`, "warning");
             }
+            // ── Emit synthetic sprint-collate-complete event (FORGE-S21-T05) ──
+            // Fires the in-process hook for post-sprint-hook.ts to consume.
+            // Best-effort: failure-to-emit notifies but does NOT halt — sprint is
+            // already complete at this point.
+            try {
+                const collateEvent = {
+                    type: "sprint-collate-complete",
+                    sprintId,
+                    cwd,
+                };
+                await emitSyntheticEvent(collateEvent, ctx);
+            }
+            catch (err) {
+                const e = err;
+                ctx.ui.notify(`⚠ forge:run-sprint — sprint-collate-complete synthetic event emit failed: ${e.message ?? "unknown"}`, "warning");
+            }
             ctx.ui.setStatus?.(SPRINT_STATUS_KEY, undefined);
             if (ceremony.verdict === "complete") {
                 ctx.ui.notify(`〇 forge:run-sprint — sprint ${sprintId} complete (${completedTaskIds.length}/${taskIds.length} tasks).`, "info");