@loucompanion/forge-bridge 0.1.3-dev.b6be5e7f9668 → 0.1.3-dev.bf78fdcaa623

package/dist/session/provider-cli/provider-cli.artifacts.js

@@ -0,0 +1,754 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { artifactRootFor, artifactRootForOwner, debugCompletionPhaseOrder, draftCompletionGateOrder, qaCompletionGateOrder, readCompletionArtifact } from "../phase-completion.js";
+import { ensureNoSymbolicLinkPathSegments, isPathUnderRoot, sha256File } from "../qa-sidecar-validation.js";
+import { hasLaunchTarget } from "./provider-cli.qa-sidecars.js";
+import { clip, isNodeError, messageFromError, normalizedString, parseJsonLine, stringField } from "./provider-output-state.js";
+const developCyclePhaseOrder = ["implementation", "self_review", "validation"];
+export async function emitDraftGateArtifacts(emit, worktreePath, workItemId) {
+    const draftArtifactFiles = {
+        draft_intent: "draft.intent.json",
+        draft_repo_context: "draft.repo-context.json",
+        draft_graph_context: "draft.graph-context.json",
+        draft_product_scope: "draft.product-scope.json",
+        draft_work_order_plan: "draft.work-order-plan.json",
+        draft_critic: "draft.critic.json",
+        draft_proposal: "draft.proposal.json"
+    };
+    for (const gate of draftCompletionGateOrder) {
+        const actualPath = path.join(worktreePath, ".forge", "work-items", workItemId, "artifacts", draftArtifactFiles[gate]);
+        if (!await fileExists(actualPath)) {
+            continue;
+        }
+        const relativePath = path.relative(worktreePath, actualPath).split(path.sep).join("/");
+        await emit({
+            role: "tool",
+            kind: "tool_result",
+            content: `Forge Draft completion tool recorded ${gate} artifact ${relativePath}.`,
+            eventType: "completion_tool_artifact_recorded",
+            data: JSON.stringify({ phase: "draft", draft_gate: gate, artifact_relative_paths: [relativePath] })
+        });
+        await emit({
+            role: "hook",
+            kind: "checkpoint",
+            content: `phase_gate: ${gate} artifact accepted with status pass.`,
+            eventType: "phase_gate"
+        });
+        const next = draftCompletionGateOrder[draftCompletionGateOrder.indexOf(gate) + 1];
+        if (next) {
+            await emit({
+                role: "hook",
+                kind: "checkpoint",
+                content: `phase_progression: ${gate} -> ${next}`,
+                eventType: "phase_gate"
+            });
+        }
+    }
+}
+export async function emitDecomposeGateArtifacts(emit, worktreePath, workItemId) {
+    const decomposeArtifactFiles = {
+        decompose_subject_intake: "decompose.subject-intake.json",
+        decompose_context_review: "decompose.context-review.json",
+        decompose_breakdown_strategy: "decompose.breakdown-strategy.json",
+        decompose_child_items: "decompose.child-items.json",
+        decompose_dependency_graph: "decompose.dependency-graph.json",
+        decompose_critic: "decompose.critic.json",
+        decompose_proposal: "decompose.proposal.json"
+    };
+    const gates = Object.keys(decomposeArtifactFiles);
+    for (const gate of gates) {
+        const actualPath = path.join(worktreePath, ".forge", "work-items", workItemId, "artifacts", decomposeArtifactFiles[gate]);
+        if (!await fileExists(actualPath)) {
+            continue;
+        }
+        const relativePath = path.relative(worktreePath, actualPath).split(path.sep).join("/");
+        await emit({
+            role: "tool",
+            kind: "tool_result",
+            content: `Forge Decompose completion tool recorded ${gate} artifact ${relativePath}.`,
+            eventType: "completion_tool_artifact_recorded",
+            data: JSON.stringify({ phase: "decompose", decompose_gate: gate, artifact_relative_paths: [relativePath] })
+        });
+        await emit({
+            role: "hook",
+            kind: "checkpoint",
+            content: `phase_gate: ${gate} artifact accepted with status pass.`,
+            eventType: "phase_gate"
+        });
+        const next = gates[gates.indexOf(gate) + 1];
+        if (next) {
+            await emit({
+                role: "hook",
+                kind: "checkpoint",
+                content: `phase_progression: ${gate} -> ${next}`,
+                eventType: "phase_gate"
+            });
+        }
+    }
+}
+export async function fileExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function summarizeStderr(stderr) {
+    const trimmed = stderr.trim();
+    return trimmed ? `: ${clip(trimmed, 1000)}` : "";
+}
+export async function waitForCompletionArtifact(worktreePath, workItemId, phase, signal) {
+    while (!signal?.aborted) {
+        const artifact = await readCompletionArtifact(worktreePath, workItemId, phase);
+        if (artifact) {
+            return artifact;
+        }
+        await delay(1000, signal);
+    }
+    throw new Error(`${phase} proposal artifact wait was cancelled.`);
+}
+export async function delay(ms, signal) {
+    if (!signal) {
+        await new Promise((resolve) => setTimeout(resolve, ms));
+        return;
+    }
+    const abortSignal = signal;
+    if (abortSignal.aborted) {
+        return;
+    }
+    await new Promise((resolve) => {
+        const timeout = setTimeout(done, ms);
+        const abort = () => done();
+        function done() {
+            clearTimeout(timeout);
+            abortSignal.removeEventListener("abort", abort);
+            resolve();
+        }
+        abortSignal.addEventListener("abort", abort, { once: true });
+        if (abortSignal.aborted) {
+            done();
+        }
+    });
+}
+export async function cleanupCompletionTools(completionTools, emit) {
+    try {
+        await completionTools.cleanup();
+    }
+    catch (error) {
+        await emit({
+            role: "runner",
+            kind: "checkpoint",
+            content: `Forge completion tool cleanup failed and was ignored: ${clip(messageFromError(error), 600)}`,
+            eventType: "completion_tools_cleanup_failed"
+        }).catch(() => undefined);
+    }
+}
+export async function commitWorktreeChanges(git, worktreePath, workItemId) {
+    await git.run(worktreePath, ["add", "-A"]);
+    await git.run(worktreePath, ["reset", "--", ".forge"]).catch(() => "");
+    const changedFiles = (await git.run(worktreePath, ["diff", "--cached", "--name-only"]))
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+    if (changedFiles.length > 0) {
+        await git.run(worktreePath, ["commit", "-m", `provider cli changeset for ${workItemId.slice(0, 8)}`]);
+    }
+    else {
+        await git.run(worktreePath, ["commit", "--allow-empty", "-m", `provider cli completed for ${workItemId.slice(0, 8)}`]);
+    }
+    const commitSha = (await git.run(worktreePath, ["rev-parse", "HEAD"])).trim();
+    return { commitSha, changedFiles };
+}
+export function phaseCompleteEventType(phase) {
+    return phase === "implementation" ? "implementation_complete" : `${phase}_complete`;
+}
+export function isDebugCompletionPhaseForProvider(phase) {
+    return debugCompletionPhaseOrder.includes(phase);
+}
+const qaArtifactFileNames = {
+    plan: "qa.plan.json",
+    evidence: "qa.evidence.json",
+    findings: "qa.findings.json",
+    verdict: "qa.verdict.json",
+    report: "qa.report.md"
+};
+const qaGateArtifactFileNames = {
+    qa_plan: "qa.plan.json",
+    qa_regression: "qa.regression.json",
+    qa_api: "qa.api.json",
+    qa_manual_web: "qa.manual-web.json",
+    qa_bug_repro: "qa.bug-repro.json",
+    qa_findings: "qa.findings.json",
+    qa_verdict: "qa.verdict.json"
+};
+export async function emitQaArtifactRecorded(emit, worktreePath, artifact) {
+    const relativePath = path.relative(worktreePath, artifact.path) || path.basename(artifact.path);
+    await emit({
+        role: "tool",
+        kind: "tool_result",
+        content: `Forge QA artifact recorded ${relativePath} (${artifact.status}).`,
+        eventType: "qa_artifact_recorded"
+    });
+    await emit({
+        role: "hook",
+        kind: "checkpoint",
+        content: `phase_gate: qa artifact accepted with status ${artifact.status}.`,
+        eventType: "phase_gate"
+    });
+}
+export async function readQaCompletionArtifactBundle(worktreePath, workItemId, ownerType, ownerId) {
+    const artifact = await readCompletionArtifact(worktreePath, workItemId, "qa", ownerType, ownerId);
+    if (!artifact || !await hasCompleteQaArtifactBundle(worktreePath, workItemId, ownerType, ownerId)) {
+        return null;
+    }
+    const artifactRoot = ownerType && ownerId
+        ? artifactRootForOwner(worktreePath, ownerType, ownerId)
+        : artifactRootFor(worktreePath, workItemId);
+    const planJson = await fs.readFile(path.join(artifactRoot, qaArtifactFileNames.plan), "utf8");
+    const evidenceJson = await fs.readFile(path.join(artifactRoot, qaArtifactFileNames.evidence), "utf8");
+    const findingsJson = await fs.readFile(path.join(artifactRoot, qaArtifactFileNames.findings), "utf8");
+    await validateQaBundleSidecarReferences(worktreePath, workItemId, ownerType, ownerId);
+    return {
+        ...artifact,
+        planJson,
+        evidenceJson,
+        findingsJson
+    };
+}
+export async function hasCompleteQaArtifactBundle(worktreePath, workItemId, ownerType, ownerId) {
+    const artifactRoot = ownerType && ownerId
+        ? artifactRootForOwner(worktreePath, ownerType, ownerId)
+        : artifactRootFor(worktreePath, workItemId);
+    for (const fileName of Object.values(qaArtifactFileNames)) {
+        try {
+            const stat = await fs.stat(path.join(artifactRoot, fileName));
+            if (!stat.isFile()) {
+                return false;
+            }
+        }
+        catch (error) {
+            if (isNodeError(error) && error.code === "ENOENT") {
+                return false;
+            }
+            throw error;
+        }
+    }
+    return true;
+}
+export function enforceQaBrowserLaunchTargetGate(dispatch, artifact) {
+    const qaBrowser = dispatch.qaBrowser;
+    if (!qaBrowser?.required || hasLaunchTarget(qaBrowser.launchTarget ?? null)) {
+        return;
+    }
+    const verdict = parseJsonLine(artifact.verdictJson) ?? {};
+    const status = normalizedString(stringField(verdict, "status") ?? artifact.status ?? "");
+    const blockerReason = normalizedString(stringField(verdict, "blocker_reason") ?? "");
+    if (status !== "blocked" || blockerReason !== "missing_app_launch_target") {
+        throw new Error("QA browser testing is required but no app launch target was provided; provider must return blocked with blocker_reason missing_app_launch_target.");
+    }
+}
+export async function validateQaBundleSidecarReferences(worktreePath, workItemId, ownerType, ownerId) {
+    const artifactRoot = ownerType && ownerId
+        ? artifactRootForOwner(worktreePath, ownerType, ownerId)
+        : artifactRootFor(worktreePath, workItemId);
+    const evidence = await readJsonObjectFile(path.join(artifactRoot, qaArtifactFileNames.evidence));
+    const sidecars = arrayField(evidence, "sidecars");
+    if (sidecars.length === 0) {
+        return;
+    }
+    const qaSidecarRoot = path.resolve(artifactRoot, "qa");
+    for (const [index, sidecar] of sidecars.entries()) {
+        const sidecarPath = stringField(sidecar, "path");
+        const expectedHash = stringField(sidecar, "content_hash");
+        const expectedBytes = sidecar.bytes;
+        if (!sidecarPath || !expectedHash || typeof expectedBytes !== "number" || !Number.isFinite(expectedBytes) || expectedBytes <= 0) {
+            throw new Error(`QA sidecar ${index} must include path, content_hash, and positive bytes.`);
+        }
+        if (path.isAbsolute(sidecarPath)) {
+            throw new Error(`QA sidecar ${index} path must be relative to the worktree.`);
+        }
+        const fullPath = path.resolve(worktreePath, sidecarPath);
+        if (!isPathUnderRoot(qaSidecarRoot, fullPath)) {
+            const ownerDirectory = ownerType && ownerId && ownerType.trim().toLowerCase() === "story" ? "stories" : "work-items";
+            const ownerSegment = ownerType && ownerId ? ownerId : workItemId;
+            throw new Error(`QA sidecar ${index} path must be under .forge/${ownerDirectory}/${ownerSegment}/artifacts/qa/.`);
+        }
+        const stat = await fs.lstat(fullPath).catch((error) => {
+            if (isNodeError(error) && error.code === "ENOENT") {
+                throw new Error(`QA sidecar ${index} file does not exist: ${sidecarPath}`);
+            }
+            throw error;
+        });
+        if (!stat.isFile() || stat.isSymbolicLink()) {
+            throw new Error(`QA sidecar ${index} must reference a regular file.`);
+        }
+        await ensureNoSymbolicLinkPathSegments(qaSidecarRoot, path.dirname(fullPath), `QA sidecar ${index} path must not traverse symbolic links.`);
+        if (stat.size !== expectedBytes) {
+            throw new Error(`QA sidecar ${index} bytes do not match the referenced file.`);
+        }
+        const actualHash = await sha256File(fullPath);
+        if (actualHash !== expectedHash.trim().toLowerCase()) {
+            throw new Error(`QA sidecar ${index} content_hash does not match the referenced file.`);
+        }
+    }
+}
+export async function emitQaStructuredEvents(emit, artifact) {
+    const artifactRoot = path.dirname(artifact.path);
+    const plan = await readJsonObjectFile(path.join(artifactRoot, qaArtifactFileNames.plan));
+    const evidence = await readJsonObjectFile(path.join(artifactRoot, qaArtifactFileNames.evidence));
+    const findings = await readJsonObjectFile(path.join(artifactRoot, qaArtifactFileNames.findings));
+    const verdict = parseJsonLine(artifact.verdictJson) ?? {};
+    const status = stringField(verdict, "status") ?? artifact.status ?? "unknown";
+    const checklist = stringArrayField(plan, "checklist");
+    await emit({
+        role: "worker",
+        kind: "message",
+        content: checklist.length > 0
+            ? `QA plan: ${checklist.join("; ")}`
+            : "QA plan recorded.",
+        eventType: "qa_plan"
+    });
+    for (const browserCheck of arrayField(evidence, "browser_checks")) {
+        await emit({
+            role: "worker",
+            kind: "checkpoint",
+            content: `QA browser check: ${summarizeQaObject(browserCheck)}`,
+            eventType: "qa_browser_check"
+        });
+    }
+    for (const finding of [...arrayField(findings, "findings"), ...arrayField(findings, "candidate_bugs")]) {
+        await emit({
+            role: "worker",
+            kind: "checkpoint",
+            content: `QA finding: ${summarizeQaObject(finding)}`,
+            eventType: "qa_finding"
+        });
+    }
+    await emit({
+        role: "assistant",
+        kind: "message",
+        content: status === "blocked"
+            ? `QA blocked: ${stringField(verdict, "summary") ?? "No summary provided."}`
+            : `QA completed with status ${status}: ${stringField(verdict, "summary") ?? "No summary provided."}`,
+        eventType: status === "blocked" ? "qa_blocked" : "qa_complete"
+    });
+}
+export function qaArtifactRootForDispatch(worktreePath, workItemId, dispatch) {
+    return dispatch.cycleRun.ownerType && dispatch.cycleRun.ownerId
+        ? artifactRootForOwner(worktreePath, dispatch.cycleRun.ownerType, dispatch.cycleRun.ownerId)
+        : artifactRootFor(worktreePath, workItemId);
+}
+export async function readQaGateArtifact(artifactRoot, gate) {
+    const artifactPath = path.join(artifactRoot, qaGateArtifactFileNames[gate]);
+    try {
+        const stat = await fs.stat(artifactPath);
+        if (!stat.isFile()) {
+            return null;
+        }
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+    const payload = await readJsonObjectFile(artifactPath);
+    return {
+        gate,
+        path: artifactPath,
+        status: stringField(payload, "status") ?? "unknown",
+        producedBy: stringField(payload, "produced_by") ?? stringField(payload, "producedBy") ?? undefined,
+        contentHash: stringField(payload, "content_hash") ?? undefined
+    };
+}
+export function nextQaGate(gate) {
+    const index = qaCompletionGateOrder.indexOf(gate);
+    return index >= 0 ? qaCompletionGateOrder[index + 1] ?? null : null;
+}
+export async function emitQaGateAccepted(emit, worktreePath, artifact, nextGate) {
+    const relativePath = path.relative(worktreePath, artifact.path).split(path.sep).join("/");
+    await emit({
+        role: "hook",
+        kind: artifact.status === "blocked" ? "error" : "checkpoint",
+        content: `phase_gate: ${artifact.gate} artifact accepted with status ${artifact.status}.`,
+        eventType: "phase_gate",
+        data: JSON.stringify({
+            phase: "qa",
+            qa_gate: artifact.gate,
+            status: artifact.status,
+            artifact_relative_paths: [relativePath],
+            content_hash: artifact.contentHash ?? null,
+            produced_by: artifact.producedBy ?? null
+        })
+    });
+    if (!nextGate) {
+        return;
+    }
+    await emit({
+        role: "hook",
+        kind: "checkpoint",
+        content: `phase_progression: ${artifact.gate} -> ${nextGate}`,
+        eventType: "phase_gate",
+        data: JSON.stringify({
+            phase: "qa",
+            from_gate: artifact.gate,
+            to_gate: nextGate
+        })
+    });
+}
+export class LiveQaArtifactEmitter {
+    worktreePath;
+    workItemId;
+    dispatch;
+    emit;
+    emittedBundle = false;
+    emittedGates = new Set();
+    timer = null;
+    pending = Promise.resolve();
+    constructor(worktreePath, workItemId, dispatch, emit) {
+        this.worktreePath = worktreePath;
+        this.workItemId = workItemId;
+        this.dispatch = dispatch;
+        this.emit = emit;
+    }
+    start() {
+        void this.pollQueued();
+        this.timer = setInterval(() => {
+            void this.pollQueued();
+        }, 250);
+    }
+    async stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        await this.pollQueued();
+    }
+    hasEmitted() {
+        return this.emittedBundle;
+    }
+    pollQueued() {
+        this.pending = this.pending
+            .then(() => this.poll())
+            .catch(() => undefined);
+        return this.pending;
+    }
+    async poll() {
+        await this.emitAvailableGateEvents();
+        if (this.emittedBundle) {
+            return;
+        }
+        const artifact = await readQaCompletionArtifactBundle(this.worktreePath, this.workItemId, this.dispatch.cycleRun.ownerType, this.dispatch.cycleRun.ownerId);
+        if (!artifact) {
+            return;
+        }
+        enforceQaBrowserLaunchTargetGate(this.dispatch, artifact);
+        this.emittedBundle = true;
+        await emitQaArtifactRecorded(this.emit, this.worktreePath, artifact);
+        await emitQaStructuredEvents(this.emit, artifact);
+    }
+    async emitAvailableGateEvents() {
+        const artifactRoot = qaArtifactRootForDispatch(this.worktreePath, this.workItemId, this.dispatch);
+        for (const gate of qaCompletionGateOrder) {
+            if (this.emittedGates.has(gate)) {
+                continue;
+            }
+            const artifact = await readQaGateArtifact(artifactRoot, gate);
+            if (!artifact) {
+                return;
+            }
+            this.emittedGates.add(gate);
+            await emitQaGateAccepted(this.emit, this.worktreePath, artifact, nextQaGate(gate));
+        }
+    }
+}
+export class LiveArchitectArtifactEmitter {
+    worktreePath;
+    workItemId;
+    emit;
+    emitted = false;
+    timer = null;
+    pending = Promise.resolve();
+    constructor(worktreePath, workItemId, emit) {
+        this.worktreePath = worktreePath;
+        this.workItemId = workItemId;
+        this.emit = emit;
+    }
+    start() {
+        void this.pollQueued();
+        this.timer = setInterval(() => {
+            void this.pollQueued();
+        }, 250);
+    }
+    async stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        await this.pollQueued();
+    }
+    hasEmitted() {
+        return this.emitted;
+    }
+    pollQueued() {
+        this.pending = this.pending
+            .then(() => this.poll())
+            .catch(() => undefined);
+        return this.pending;
+    }
+    async poll() {
+        if (this.emitted || !await hasCompleteArchitectArtifactBundle(this.worktreePath, this.workItemId)) {
+            return;
+        }
+        const artifact = await readCompletionArtifact(this.worktreePath, this.workItemId, "architect");
+        if (!artifact) {
+            return;
+        }
+        this.emitted = true;
+        await emitCompletionArtifactRecorded(this.emit, this.worktreePath, artifact);
+        await emitArchitectStructuredEvents(this.emit, this.worktreePath, this.workItemId, artifact);
+    }
+}
+export async function hasCompleteArchitectArtifactBundle(worktreePath, workItemId) {
+    const artifactRoot = artifactRootFor(worktreePath, workItemId);
+    for (const fileName of ["implementation.plan.json", "qa.plan.json", "architect.verdict.json", "architect.report.md"]) {
+        try {
+            const stat = await fs.stat(path.join(artifactRoot, fileName));
+            if (!stat.isFile()) {
+                return false;
+            }
+        }
+        catch (error) {
+            if (isNodeError(error) && error.code === "ENOENT") {
+                return false;
+            }
+            throw error;
+        }
+    }
+    return true;
+}
+export async function emitArchitectStructuredEvents(emit, worktreePath, workItemId, artifact) {
+    const artifactRoot = artifactRootFor(worktreePath, workItemId);
+    const implementationPlan = await readJsonObjectFile(path.join(artifactRoot, "implementation.plan.json"));
+    const qaPlan = await readJsonObjectFile(path.join(artifactRoot, "qa.plan.json"));
+    const verdict = parseJsonLine(artifact.verdictJson) ?? {};
+    const status = stringField(verdict, "status") ?? artifact.status ?? "unknown";
+    const planId = stringField(implementationPlan, "plan_id") ?? "unknown";
+    await emit({
+        role: "worker",
+        kind: "checkpoint",
+        content: `Architect plan recorded: ${planId} with ${arrayField(implementationPlan, "phases").length} phases and ${arrayField(implementationPlan, "tasks").length} tasks.`,
+        eventType: "architect_plan"
+    });
+    await emit({
+        role: "worker",
+        kind: "checkpoint",
+        content: `Architect QA seed recorded with ${arrayField(qaPlan, "final_qa").length} final QA items.`,
+        eventType: "architect_qa_seed"
+    });
+    await emit({
+        role: "hook",
+        kind: status === "pass" ? "checkpoint" : "error",
+        content: `architect_mcp_complete: ${status === "pass" ? "accepted" : "recorded"} - ${stringField(verdict, "summary") ?? "Architect completion payload recorded."}`,
+        eventType: "architect_mcp_complete"
+    });
+}
+export async function readJsonObjectFile(filePath) {
+    const content = await fs.readFile(filePath, "utf8").catch(() => "");
+    return parseJsonLine(content) ?? {};
+}
+export function arrayField(source, key) {
+    const value = source[key];
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((entry) => Boolean(entry) && typeof entry === "object" && !Array.isArray(entry));
+}
+export function stringArrayField(source, key) {
+    const value = source[key];
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((entry) => typeof entry === "string" && entry.trim().length > 0);
+}
+export function summarizeQaObject(source) {
+    return clip(stringField(source, "title")
+        ?? stringField(source, "summary")
+        ?? stringField(source, "id")
+        ?? JSON.stringify(source), 500);
+}
+export function qaArtifactRelativePath(workItemId, fileName, ownerType, ownerId) {
+    if (ownerType && ownerId) {
+        const ownerDirectory = ownerType.trim().toLowerCase() === "story" ? "stories" : "work-items";
+        return [".forge", ownerDirectory, ownerId, "artifacts", fileName].join("/");
+    }
+    return [".forge", "work-items", workItemId, "artifacts", fileName].join("/");
+}
+export async function emitCompletionArtifactRecorded(emit, worktreePath, artifact) {
+    const relativePath = path.relative(worktreePath, artifact.path) || path.basename(artifact.path);
+    await emit({
+        role: "tool",
+        kind: "checkpoint",
+        content: `Forge completion tool validation passed for ${artifact.phase ?? "unknown"} (${artifact.status}).`,
+        eventType: "completion_tool_validation_passed",
+        data: JSON.stringify({
+            phase: artifact.phase ?? "unknown",
+            status: artifact.status,
+            artifact_relative_paths: [relativePath.split(path.sep).join("/")]
+        })
+    });
+    await emit({
+        role: "tool",
+        kind: "tool_result",
+        content: `Forge completion tool recorded ${artifact.phase ?? "unknown"} artifact ${relativePath} (${artifact.status}).`,
+        eventType: "completion_tool_artifact_recorded",
+        data: JSON.stringify({
+            phase: artifact.phase ?? "unknown",
+            status: artifact.status,
+            artifact_relative_paths: [relativePath.split(path.sep).join("/")]
+        })
+    });
+}
+export async function emitPhaseCompletionEvent(emit, artifact) {
+    const phase = completionPhaseFromArtifact(artifact);
+    await emit({
+        role: "assistant",
+        kind: "message",
+        content: `${phase.replace(/_/g, " ")} completion artifact recorded with status ${artifact.status}.`,
+        eventType: phaseCompleteEventType(phase)
+    });
+}
+export async function emitPhaseGateEvents(emit, artifact) {
+    const phase = completionPhaseFromArtifact(artifact);
+    const status = (artifact.status ?? "").trim().toLowerCase() || "unknown";
+    await emit({
+        role: "hook",
+        kind: "checkpoint",
+        content: `phase_gate: ${phase} artifact accepted with status ${status}.`,
+        eventType: "phase_gate"
+    });
+    if (status !== "pass") {
+        return;
+    }
+    const progression = phase === "implementation"
+        ? "phase_progression: implementation -> self_review"
+        : phase === "self_review"
+            ? "phase_progression: self_review -> validation"
+            : phase === "debug_repro"
+                ? "phase_progression: debug_repro -> debug_root_cause"
+                : phase === "debug_root_cause"
+                    ? "phase_progression: debug_root_cause -> debug_fix"
+                    : phase === "debug_fix"
+                        ? "phase_progression: debug_fix -> debug_regression"
+                        : phase === "debug_regression"
+                            ? "phase_progression: debug_regression -> QA ready"
+                            : "phase_progression: validation -> QA ready";
+    await emit({
+        role: "hook",
+        kind: "checkpoint",
+        content: progression,
+        eventType: "phase_gate"
+    });
+}
+export function completionPhaseFromArtifact(artifact) {
+    const phase = artifact.phase?.trim();
+    return phase === "self_review" || phase === "validation" || phase === "implementation" || phase === "qa"
+        || phase === "architect" || phase === "debug_repro" || phase === "debug_root_cause" || phase === "debug_fix" || phase === "debug_regression"
+        ? phase
+        : "implementation";
+}
+export class LiveCompletionArtifactEmitter {
+    worktreePath;
+    workItemId;
+    emit;
+    phases;
+    emitted = new Set();
+    timer = null;
+    pending = Promise.resolve();
+    constructor(worktreePath, workItemId, phase, developCycle, debugCycle, emit) {
+        this.worktreePath = worktreePath;
+        this.workItemId = workItemId;
+        this.emit = emit;
+        if (debugCycle && isDebugCompletionPhaseForProvider(phase)) {
+            this.phases = debugCompletionPhaseOrder.slice(debugCompletionPhaseOrder.indexOf(phase));
+        }
+        else {
+            this.phases = developCycle
+                ? developCyclePhaseOrder.slice(developCyclePhaseOrder.indexOf(phase))
+                : [phase];
+        }
+    }
+    start() {
+        void this.pollQueued();
+        this.timer = setInterval(() => {
+            void this.pollQueued();
+        }, 250);
+    }
+    async stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        await this.pollQueued();
+    }
+    hasEmitted(phase) {
+        return this.emitted.has(phase);
+    }
+    pollQueued() {
+        this.pending = this.pending
+            .then(() => this.poll())
+            .catch(() => undefined);
+        return this.pending;
+    }
+    async poll() {
+        for (const phase of this.phases) {
+            if (this.emitted.has(phase)) {
+                continue;
+            }
+            const artifact = await readCompletionArtifact(this.worktreePath, this.workItemId, phase);
+            if (!artifact) {
+                return;
+            }
+            this.emitted.add(phase);
+            await emitCompletionArtifactRecorded(this.emit, this.worktreePath, artifact);
+            await emitPhaseCompletionEvent(this.emit, artifact);
+            await emitPhaseGateEvents(this.emit, artifact);
+            if ((artifact.status ?? "").trim().toLowerCase() !== "pass") {
+                return;
+            }
+        }
+    }
+}
+export async function readCompletionArtifactsForRun(worktreePath, workItemId, phase, developCycle, debugCycle) {
+    if (!developCycle && !debugCycle) {
+        const artifact = await readCompletionArtifact(worktreePath, workItemId, phase);
+        if (!artifact) {
+            throw new Error(`Provider CLI completed but did not call the Forge ${phase} completion tool.`);
+        }
+        return [artifact];
+    }
+    const expectedPhases = debugCycle && isDebugCompletionPhaseForProvider(phase)
+        ? debugCompletionPhaseOrder.slice(debugCompletionPhaseOrder.indexOf(phase))
+        : ["implementation", "self_review", "validation"];
+    const artifacts = [];
+    for (const expectedPhase of expectedPhases) {
+        const artifact = await readCompletionArtifact(worktreePath, workItemId, expectedPhase);
+        if (!artifact) {
+            if (artifacts.length === 0) {
+                throw new Error(`Provider CLI completed but did not call the Forge ${expectedPhase} completion tool.`);
+            }
+            const previous = artifacts[artifacts.length - 1];
+            if ((previous.status ?? "").trim().toLowerCase() === "pass") {
+                throw new Error(`Provider CLI completed after ${previous.phase} passed but did not call the Forge ${expectedPhase} completion tool.`);
+            }
+            return artifacts;
+        }
+        artifacts.push(artifact);
+        if ((artifact.status ?? "").trim().toLowerCase() !== "pass") {
+            return artifacts;
+        }
+    }
+    return artifacts;
+}