@loucompanion/forge-bridge 0.1.1-dev.4f31cdd58cac → 0.1.1-dev.65ea6889412c

package/dist/session/phase-completion.d.ts

@@ -1,6 +1,6 @@
 import type { RunOnceDispatchPacket, RunnerDispatchArtifact } from "./session.types.js";
 import type { WorktreeHandle } from "../worktree/worktree.types.js";
-export type CompletionPhase = "implementation" | "self_review" | "validation";
+export type CompletionPhase = "implementation" | "self_review" | "validation" | "qa";
 export interface CompletionToolRuntime {
     readonly serverName: string;
     readonly command: string;
@@ -34,7 +34,7 @@ export interface CompletionToolCallResult {
             readonly allowed: boolean;
             readonly reason: string;
         };
-        readonly nextPhase: CompletionPhase | "dev_test_ready";
+        readonly nextPhase: CompletionPhase | "dev_test_ready" | "sign_off_ready";
         readonly nextInstruction: string;
     };
 }

package/dist/session/phase-completion.js

@@ -6,6 +6,17 @@ import { redactSecrets } from "../shared/redaction/redaction.js";
 const toolServerName = "forge";
 const completionRedactionSecretsEnv = "FORGE_COMPLETION_REDACTION_SECRETS";
 const completionPhaseOrder = ["implementation", "self_review", "validation"];
+const qaBlockerReasons = new Set([
+    "missing_app_launch_target",
+    "inconclusive",
+    "environment_failure",
+    "missing_validation_evidence",
+    "missing_worktree",
+    "runner_failure"
+]);
+const qaFindingSeverities = new Set(["critical", "major", "minor"]);
+const qaFindingScopes = new Set(["in_scope", "out_of_scope", "unclear"]);
+const qaCandidateBugActions = new Set(["create_bug", "create_follow_up", "accept_risk", "attach_to_current_item"]);
 const phaseFiles = {
     implementation: {
         jsonFileName: "implementation.completeness.json",
@@ -18,6 +29,10 @@ const phaseFiles = {
     validation: {
         jsonFileName: "validation.verdict.json",
         reportFileName: "validation.report.md"
+    },
+    qa: {
+        jsonFileName: "qa.verdict.json",
+        reportFileName: "qa.report.md"
     }
 };
 export function completionPhaseFromDispatch(dispatch) {
@@ -31,6 +46,9 @@ export function normalizeCompletionPhase(value) {
     if (normalized === "validate" || normalized === "validation") {
         return "validation";
     }
+    if (normalized === "qa" || normalized === "quality_assurance" || normalized === "qualityassurance") {
+        return "qa";
+    }
     return "implementation";
 }
 export function usesDevelopCycleCompletion(dispatch) {
@@ -47,7 +65,9 @@ export function completionToolNamesForPhase(phase) {
         ? "complete_implementation"
         : phase === "self_review"
             ? "complete_self_review"
-            : "complete_validation";
+            : phase === "validation"
+                ? "complete_validation"
+                : "complete_qa";
     return [`forge.${base}`, base];
 }
 export function expectedCompletionToolName(phase) {
@@ -126,6 +146,13 @@ export function completionPromptForPhase(phase) {
     const toolName = expectedCompletionToolName(phase);
     const alias = completionToolNamesForPhase(phase).find((name) => name !== toolName);
     const artifactName = phaseFiles[phase].jsonFileName;
+    if (phase === "qa") {
+        return `Forge completion tools are available through the MCP server named \`${toolServerName}\`.
+Do not write QA artifacts by hand. When QA is complete, call \`${toolName}(...)\`${alias ? ` (or \`${alias}\` if your client shows unqualified MCP tool names)` : ""} with the required structured QA payload.
+That tool writes the durable QA bundle under \`.forge/work-items/{workItemId}/artifacts/\`: \`qa.plan.json\`, \`qa.evidence.json\`, \`qa.findings.json\`, \`${artifactName}\`, and \`qa.report.md\`.
+Use \`status: "pass"\` only when the validated changes satisfy acceptance criteria with concrete evidence. Use \`status: "needs_rework"\` with actionable in-scope findings, or \`status: "blocked"\` with a concrete blocker_reason.
+Forge will mirror only the tool-written QA artifacts; reporting QA completion in prose is not enough.`;
+    }
     return `Forge completion tools are available through the MCP server named \`${toolServerName}\`.
 Do not write phase artifacts by hand. When the phase is complete, call \`${toolName}(...)\`${alias ? ` (or \`${alias}\` if your client shows unqualified MCP tool names)` : ""} with the required evidence payload.
 That tool writes \`.forge/work-items/{workItemId}/artifacts/${artifactName}\` and returns the artifact reference that Forge will mirror through the existing phase-artifact pipeline.
@@ -202,6 +229,9 @@ export class CompletionToolServerSession {
         };
     }
     advanceAfterPass(phase) {
+        if (phase === "qa") {
+            return "sign_off_ready";
+        }
         const next = nextPhaseAfter(phase);
         if (!this.config.developCycle) {
             return next ?? "dev_test_ready";
@@ -220,7 +250,7 @@ export async function writeCompletionArtifact(config, toolName, input) {
         throw new Error(`Tool ${toolName} is not allowed for phase ${config.phase}.`);
     }
     const payload = asRecord(input, "completion payload");
-    const status = normalizeCompletionStatus(requiredString(payload, "status"));
+    const status = normalizeCompletionStatus(requiredString(payload, "status"), phase);
     const validationPayload = { ...payload, status };
     validatePayloadShape(phase, validationPayload);
     validateOptionalWorkItemId(validationPayload, config.workItemId);
@@ -229,6 +259,9 @@ export async function writeCompletionArtifact(config, toolName, input) {
         ?? optionalString(redactedPayload, "producedBy")
         ?? config.producedBy
         ?? "forge-completion-tool";
+    if (phase === "qa") {
+        return await writeQaCompletionArtifact(config, redactedPayload, status, producedBy);
+    }
     const artifactWithoutHash = normalizeArtifactPayload(redactedPayload, {
         phase,
         workItemId: config.workItemId,
@@ -258,6 +291,101 @@ export async function writeCompletionArtifact(config, toolName, input) {
         producedBy
     };
 }
+async function writeQaCompletionArtifact(config, payload, status, producedBy) {
+    const artifactRoot = artifactRootFor(config.worktreePath, config.workItemId);
+    const planPath = path.join(artifactRoot, "qa.plan.json");
+    const evidencePath = path.join(artifactRoot, "qa.evidence.json");
+    const findingsPath = path.join(artifactRoot, "qa.findings.json");
+    const verdictPath = path.join(artifactRoot, "qa.verdict.json");
+    const reportPath = path.join(artifactRoot, "qa.report.md");
+    const relativeEvidencePath = qaArtifactRelativePath(config.workItemId, "qa.evidence.json");
+    const relativeFindingsPath = qaArtifactRelativePath(config.workItemId, "qa.findings.json");
+    const relativeReportPath = qaArtifactRelativePath(config.workItemId, "qa.report.md");
+    const evidenceSource = qaEvidenceSource(payload);
+    const commands = qaArray(payload, "commands", evidenceSource);
+    const browserChecks = qaArray(payload, "browser_checks", evidenceSource);
+    const notes = optionalString(payload, "notes") ?? optionalString(evidenceSource, "notes") ?? "";
+    const findings = qaObjectArray(payload, "findings");
+    const candidateBugs = qaObjectArray(payload, "candidate_bugs");
+    const testedAcceptanceCriteria = qaStringArray(payload, "tested_acceptance_criteria");
+    const explicitFindingIds = qaStringArray(payload, "finding_ids");
+    const explicitCandidateBugIds = qaStringArray(payload, "candidate_bug_ids");
+    const blockerReason = optionalString(payload, "blocker_reason");
+    const checklist = qaStringArray(payload, "checklist");
+    const planJson = jsonText({
+        schema_version: 1,
+        phase: "qa",
+        checklist: checklist.length > 0 ? checklist : defaultQaChecklist(status),
+        acceptance_criteria: testedAcceptanceCriteria
+    });
+    const evidenceJson = jsonText({
+        schema_version: 1,
+        phase: "qa",
+        commands,
+        browser_checks: browserChecks,
+        notes
+    });
+    const findingsJson = jsonText({
+        schema_version: 1,
+        phase: "qa",
+        findings,
+        candidate_bugs: candidateBugs
+    });
+    const findingIds = status === "pass"
+        ? []
+        : explicitFindingIds.length > 0
+            ? explicitFindingIds
+            : findings
+                .filter((finding) => normalizedString(finding.scope) === "in_scope")
+                .map((finding) => optionalString(finding, "id"))
+                .filter((id) => Boolean(id));
+    const candidateBugIds = explicitCandidateBugIds.length > 0
+        ? explicitCandidateBugIds
+        : candidateBugs
+            .map((candidateBug) => optionalString(candidateBug, "id"))
+            .filter((id) => Boolean(id));
+    const verdictWithoutHash = {
+        schema_version: numberOrDefault(payload.schema_version, 1),
+        phase: "qa",
+        status,
+        summary: requiredString(payload, "summary"),
+        tested_acceptance_criteria: testedAcceptanceCriteria,
+        finding_ids: findingIds,
+        candidate_bug_ids: candidateBugIds,
+        blocker_reason: status === "blocked" ? normalizedString(blockerReason) : null,
+        evidence_path: relativeEvidencePath,
+        findings_path: relativeFindingsPath,
+        report_path: relativeReportPath,
+        produced_by: producedBy
+    };
+    const contentHash = sha256(stableStringify({
+        plan: JSON.parse(planJson),
+        evidence: JSON.parse(evidenceJson),
+        findings: JSON.parse(findingsJson),
+        verdict: verdictWithoutHash
+    }));
+    const verdictJson = jsonText({
+        ...verdictWithoutHash,
+        content_hash: contentHash
+    });
+    const finalReport = reportMarkdown(payload, "qa", status, producedBy, contentHash);
+    await fs.mkdir(artifactRoot, { recursive: true });
+    await writeFileAtomic(planPath, planJson);
+    await writeFileAtomic(evidencePath, evidenceJson);
+    await writeFileAtomic(findingsPath, findingsJson);
+    await writeFileAtomic(verdictPath, verdictJson);
+    await writeFileAtomic(reportPath, finalReport);
+    return {
+        phase: "qa",
+        workItemId: config.workItemId,
+        repoPath: path.resolve(config.worktreePath),
+        path: verdictPath,
+        reportPath,
+        contentHash,
+        status,
+        producedBy
+    };
+}
 export async function readCompletionArtifact(worktreePath, workItemId, phase) {
     const artifactPath = completionArtifactJsonPath(worktreePath, workItemId, phase);
     const reportPath = completionArtifactReportPath(worktreePath, workItemId, phase);
@@ -316,7 +444,7 @@ export function parseCompletionMcpArgs(argv) {
             const rawPhase = argv[++index];
             const parsedPhase = parseStrictCompletionPhase(rawPhase);
             if (!parsedPhase) {
-                return { ok: false, error: "mcp --phase must be one of: implementation, self-review, validation." };
+                return { ok: false, error: "mcp --phase must be one of: implementation, self-review, validation, qa." };
             }
             phase = parsedPhase;
         }
@@ -448,6 +576,15 @@ function nextPhaseAfter(phase) {
     return index >= 0 ? completionPhaseOrder[index + 1] ?? null : null;
 }
 function completionToolNextInstruction(completedPhase, status, nextPhase) {
+    if (completedPhase === "qa") {
+        if (status === "blocked") {
+            return "QA blocked. Forge recorded the blocker reason and will surface the run for human attention.";
+        }
+        if (status === "needs_rework") {
+            return "QA findings recorded. Forge has the structured evidence needed to route this work back for implementation rework.";
+        }
+        return "QA accepted. Forge has the structured evidence needed to move this work item to Sign-Off.";
+    }
     if (status !== "pass") {
         return `Stay in ${completedPhase}, address the recorded blockers, then call ${expectedCompletionToolName(completedPhase)} again.`;
     }
@@ -457,7 +594,7 @@ function completionToolNextInstruction(completedPhase, status, nextPhase) {
     if (nextPhase === "validation") {
         return "Self-review accepted. Begin validation: run deterministic checks, prove acceptance criteria, and call forge.complete_validation with command evidence.";
     }
-    return "Validation accepted. Forge has the structured evidence needed to move this work item to Dev Test.";
+    return "Validation accepted. Forge has the structured evidence needed to move this work item to QA.";
 }
 function toolDescription(phase) {
     if (phase === "implementation") {
@@ -466,6 +603,9 @@ function toolDescription(phase) {
     if (phase === "self_review") {
         return "Complete Forge self-review by writing self-review.report.json with diff review, findings, security, edge-case, design, deterministic-comparison, fixes, and remaining-risk evidence.";
     }
+    if (phase === "qa") {
+        return "Complete Forge QA by writing qa.plan.json, qa.evidence.json, qa.findings.json, qa.verdict.json, and qa.report.md with structured pass, needs-rework, or blocked evidence.";
+    }
     return "Complete Forge validation by writing validation.verdict.json with command, build/test/lint/design, drift, acceptance-criteria, and ready-for-dev-test evidence.";
 }
 function toolInputSchema(phase) {
@@ -588,6 +728,83 @@ function toolInputSchema(phase) {
             }
         }, ["status", "summary"], "For status pass, include reviewed_diff, findings, security_review, edge_case_review, design_review, deterministic_comparison, fixes_applied, and remaining_risks.");
     }
+    if (phase === "qa") {
+        return objectToolSchema({
+            ...baseProperties,
+            status: {
+                type: "string",
+                enum: ["pass", "needs_rework", "blocked"],
+                description: "Use pass only when QA evidence satisfies acceptance criteria, needs_rework for actionable in-scope defects, or blocked for an inconclusive QA blocker."
+            },
+            checklist: {
+                type: "array",
+                description: "QA plan/checklist. Forge writes this to qa.plan.json; a default checklist is generated if omitted.",
+                items: { type: "string" }
+            },
+            tested_acceptance_criteria: {
+                type: "array",
+                description: "Required and non-empty for pass/needs_rework. Criteria actually tested by QA.",
+                items: { type: "string" }
+            },
+            commands: {
+                type: "array",
+                description: "Command evidence written to qa.evidence.json.",
+                items: commandEvidenceSchema()
+            },
+            browser_checks: {
+                type: "array",
+                description: "Browser/manual UI checks with URL, action, observed result, screenshot/trace references, console/network notes, and status when applicable.",
+                items: evidenceObjectSchema(["summary"], {
+                    summary: { type: "string" },
+                    url: { type: "string" },
+                    status: { type: "string" },
+                    screenshot: { type: "string" },
+                    trace: { type: "string" }
+                })
+            },
+            notes: { type: "string", description: "Additional QA evidence notes." },
+            evidence: {
+                type: "object",
+                description: "Optional wrapper containing commands, browser_checks, and notes when a client prefers nested evidence."
+            },
+            findings: {
+                type: "array",
+                description: "QA findings. needs_rework requires at least one actionable in_scope finding.",
+                items: evidenceObjectSchema(["id", "severity", "scope", "title"], {
+                    id: { type: "string" },
+                    severity: { type: "string", enum: ["critical", "major", "minor"] },
+                    scope: { type: "string", enum: ["in_scope", "out_of_scope", "unclear"] },
+                    title: { type: "string" },
+                    acceptance_criteria: { type: "array", items: { type: "string" } },
+                    repro_steps: { type: "array", items: { type: "string" } },
+                    expected: { type: "string" },
+                    actual: { type: "string" },
+                    evidence: { type: "object" },
+                    likely_area: { type: "array", items: { type: "string" } },
+                    required_fix: { type: "string" },
+                    required_regression: { type: "string" }
+                })
+            },
+            candidate_bugs: {
+                type: "array",
+                description: "Out-of-scope/follow-up bug candidates. They do not block the current item unless attached as in-scope findings.",
+                items: evidenceObjectSchema(["id", "title", "suggested_action"], {
+                    id: { type: "string" },
+                    title: { type: "string" },
+                    severity: { type: "string" },
+                    scope_reason: { type: "string" },
+                    repro_steps: { type: "array", items: { type: "string" } },
+                    evidence: { type: "object" },
+                    suggested_action: { type: "string", enum: ["create_bug", "create_follow_up", "accept_risk", "attach_to_current_item"] }
+                })
+            },
+            blocker_reason: {
+                type: "string",
+                enum: [...qaBlockerReasons],
+                description: "Required when status is blocked."
+            }
+        }, ["status", "summary"], "For pass, include tested_acceptance_criteria plus concrete command/browser/note evidence. For needs_rework, include at least one actionable in_scope finding. For blocked, include blocker_reason.");
+    }
     return objectToolSchema({
         ...baseProperties,
         commands: {
@@ -662,8 +879,15 @@ function reviewSectionProperties() {
         notes: { type: "string" }
     };
 }
-function normalizeCompletionStatus(value) {
+function normalizeCompletionStatus(value, phase) {
     const normalized = value.trim().toLowerCase().replace(/-/g, "_");
+    if (phase === "qa") {
+        const canonical = normalized === "needsrework" ? "needs_rework" : normalized;
+        if (canonical !== "pass" && canonical !== "needs_rework" && canonical !== "blocked") {
+            throw new Error("QA status must be pass, needs_rework, or blocked.");
+        }
+        return canonical;
+    }
     const canonical = normalized === "blocked" || normalized === "needsrework"
         ? "needs_rework"
         : normalized === "failed"
@@ -675,12 +899,16 @@ function normalizeCompletionStatus(value) {
     return canonical;
 }
 function validatePayloadShape(phase, payload) {
-    const status = normalizeCompletionStatus(requiredString(payload, "status"));
+    const status = normalizeCompletionStatus(requiredString(payload, "status"), phase);
     if (!status) {
         throw new Error("status is required.");
     }
-    const pass = status === "pass";
     requireField(payload, "summary");
+    if (phase === "qa") {
+        validateQaPayloadShape(payload, status);
+        return;
+    }
+    const pass = status === "pass";
     if (!pass) {
         requireNonPassEvidence(payload);
         return;
@@ -722,6 +950,117 @@ function validatePayloadShape(phase, payload) {
     requirePassingCommands(payload);
     requireSatisfiedAcceptanceCriteria(payload);
 }
+function validateQaPayloadShape(payload, status) {
+    const evidenceSource = qaEvidenceSource(payload);
+    const commands = qaArray(payload, "commands", evidenceSource);
+    const browserChecks = qaArray(payload, "browser_checks", evidenceSource);
+    const notes = optionalString(payload, "notes") ?? optionalString(evidenceSource, "notes") ?? "";
+    const testedAcceptanceCriteria = qaStringArray(payload, "tested_acceptance_criteria");
+    const findings = qaObjectArray(payload, "findings");
+    const candidateBugs = qaObjectArray(payload, "candidate_bugs");
+    const explicitFindingIds = qaStringArray(payload, "finding_ids");
+    const explicitCandidateBugIds = qaStringArray(payload, "candidate_bug_ids");
+    if (payload.schema_version !== undefined && payload.schema_version !== 1) {
+        throw new Error("QA schema_version must be numeric 1 when provided.");
+    }
+    if (status === "pass" || status === "needs_rework") {
+        if (testedAcceptanceCriteria.length === 0) {
+            throw new Error("QA pass/needs_rework requires tested_acceptance_criteria with at least one criterion.");
+        }
+        if (commands.length === 0 && browserChecks.length === 0 && notes.length === 0) {
+            throw new Error("QA pass/needs_rework requires at least one command, browser check, or evidence note.");
+        }
+    }
+    for (const [index, command] of commands.entries()) {
+        requireEvidenceRecord(command, `commands[${index}]`);
+        const record = command;
+        requireNonEmptyStringRecord(record, "command", `commands[${index}].`);
+        requireNonEmptyStringRecord(record, "status", `commands[${index}].`);
+        requireNonEmptyStringRecord(record, "summary", `commands[${index}].`);
+        if (typeof record.exit_code !== "number" || !Number.isFinite(record.exit_code)) {
+            throw new Error(`commands[${index}].exit_code is required.`);
+        }
+        if (status === "pass" && record.exit_code !== 0) {
+            throw new Error(`commands[${index}].exit_code must be 0 when QA status is pass.`);
+        }
+        if (status === "pass" && normalizedString(record.status) !== "pass") {
+            throw new Error(`commands[${index}].status must be pass when QA status is pass.`);
+        }
+    }
+    for (const [index, browserCheck] of browserChecks.entries()) {
+        requireEvidenceRecord(browserCheck, `browser_checks[${index}]`);
+        const record = browserCheck;
+        requireNonEmptyStringRecord(record, "summary", `browser_checks[${index}].`);
+        const checkStatus = optionalString(record, "status");
+        if (status === "pass" && checkStatus && normalizedString(checkStatus) !== "pass") {
+            throw new Error(`browser_checks[${index}].status must be pass when QA status is pass.`);
+        }
+    }
+    for (const [index, finding] of findings.entries()) {
+        requireNonEmptyStringRecord(finding, "id", `findings[${index}].`);
+        requireNonEmptyStringRecord(finding, "title", `findings[${index}].`);
+        requireKnownStringRecord(finding, "severity", qaFindingSeverities, `findings[${index}].`);
+        requireKnownStringRecord(finding, "scope", qaFindingScopes, `findings[${index}].`);
+        if (normalizedString(finding.scope) === "in_scope") {
+            validateActionableQaFinding(finding, index);
+        }
+    }
+    for (const [index, candidateBug] of candidateBugs.entries()) {
+        requireNonEmptyStringRecord(candidateBug, "id", `candidate_bugs[${index}].`);
+        requireNonEmptyStringRecord(candidateBug, "title", `candidate_bugs[${index}].`);
+        requireKnownStringRecord(candidateBug, "suggested_action", qaCandidateBugActions, `candidate_bugs[${index}].`);
+    }
+    const inScopeFindingIds = findings
+        .filter((finding) => normalizedString(finding.scope) === "in_scope")
+        .map((finding) => optionalString(finding, "id"))
+        .filter((id) => Boolean(id));
+    for (const findingId of explicitFindingIds) {
+        if (!inScopeFindingIds.includes(findingId)) {
+            throw new Error(`QA finding_ids contains '${findingId}', but findings has no matching in-scope finding.`);
+        }
+    }
+    const candidateBugIds = candidateBugs
+        .map((candidateBug) => optionalString(candidateBug, "id"))
+        .filter((id) => Boolean(id));
+    for (const candidateBugId of explicitCandidateBugIds) {
+        if (!candidateBugIds.includes(candidateBugId)) {
+            throw new Error(`QA candidate_bug_ids contains '${candidateBugId}', but candidate_bugs has no matching candidate bug.`);
+        }
+    }
+    if (status === "pass") {
+        if (explicitFindingIds.length > 0 || inScopeFindingIds.length > 0) {
+            throw new Error("QA pass must not include in-scope finding_ids or in-scope findings.");
+        }
+        if (optionalString(payload, "blocker_reason")) {
+            throw new Error("QA pass must not include blocker_reason.");
+        }
+    }
+    if (status === "needs_rework") {
+        if (inScopeFindingIds.length === 0) {
+            throw new Error("QA needs_rework requires at least one actionable in-scope finding.");
+        }
+        if (optionalString(payload, "blocker_reason")) {
+            throw new Error("QA needs_rework must not include blocker_reason.");
+        }
+    }
+    if (status === "blocked") {
+        const reason = normalizedString(optionalString(payload, "blocker_reason"));
+        if (!qaBlockerReasons.has(reason)) {
+            throw new Error("QA blocked requires blocker_reason to be one of missing_app_launch_target, inconclusive, environment_failure, missing_validation_evidence, missing_worktree, or runner_failure.");
+        }
+    }
+}
+function validateActionableQaFinding(finding, index) {
+    const prefix = `findings[${index}].`;
+    requireNonEmptyStringArrayRecord(finding, "acceptance_criteria", prefix);
+    requireNonEmptyStringArrayRecord(finding, "repro_steps", prefix);
+    requireNonEmptyStringRecord(finding, "expected", prefix);
+    requireNonEmptyStringRecord(finding, "actual", prefix);
+    requireSubstantiveEvidenceRecord(finding, prefix);
+    requireNonEmptyStringArrayRecord(finding, "likely_area", prefix);
+    requireNonEmptyStringRecord(finding, "required_fix", prefix);
+    requireNonEmptyStringRecord(finding, "required_regression", prefix);
+}
 function validateOptionalWorkItemId(payload, expectedWorkItemId) {
     const actual = optionalString(payload, "work_item_id") ?? optionalString(payload, "workItemId");
     if (actual && actual !== expectedWorkItemId) {
@@ -768,6 +1107,9 @@ function parseStrictCompletionPhase(value) {
     if (normalized === "validate" || normalized === "validation") {
         return "validation";
     }
+    if (normalized === "qa" || normalized === "quality_assurance" || normalized === "qualityassurance") {
+        return "qa";
+    }
     return null;
 }
 function parseCompletionRedactionSecrets(raw) {
@@ -796,6 +1138,9 @@ function phaseFromToolName(toolName) {
     if (normalized === "forge.complete_validation" || normalized === "complete_validation") {
         return "validation";
     }
+    if (normalized === "forge.complete_qa" || normalized === "complete_qa") {
+        return "qa";
+    }
     throw new Error(`Unknown Forge completion tool: ${toolName}`);
 }
 function requireField(payload, key) {
@@ -893,6 +1238,109 @@ function requireSatisfiedAcceptanceCriteria(payload) {
         }
     }
 }
+function qaEvidenceSource(payload) {
+    const evidence = payload.evidence;
+    return evidence && typeof evidence === "object" && !Array.isArray(evidence)
+        ? evidence
+        : {};
+}
+function qaArray(payload, key, fallback = {}) {
+    const value = payload[key] ?? fallback[key];
+    if (value === undefined || value === null) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new Error(`${key} must be an array.`);
+    }
+    return value;
+}
+function qaObjectArray(payload, key) {
+    return qaArray(payload, key).map((entry, index) => {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+            throw new Error(`${key}[${index}] must be an object.`);
+        }
+        return entry;
+    });
+}
+function qaStringArray(payload, key) {
+    const value = payload[key];
+    if (value === undefined || value === null) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new Error(`${key} must be an array.`);
+    }
+    return value.map((entry, index) => {
+        if (typeof entry !== "string" || entry.trim().length === 0) {
+            throw new Error(`${key}[${index}] must be a non-empty string.`);
+        }
+        return entry;
+    });
+}
+function requireEvidenceRecord(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${label} must be an object.`);
+    }
+}
+function requireNonEmptyStringRecord(source, key, prefix = "") {
+    if (!optionalString(source, key)) {
+        throw new Error(`${prefix}${key} is required.`);
+    }
+}
+function requireKnownStringRecord(source, key, allowed, prefix = "") {
+    const value = normalizedString(optionalString(source, key));
+    if (!allowed.has(value)) {
+        throw new Error(`${prefix}${key} must be one of ${[...allowed].sort().join(", ")}.`);
+    }
+}
+function requireNonEmptyStringArrayRecord(source, key, prefix = "") {
+    const value = source[key];
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new Error(`${prefix}${key} must include at least one value.`);
+    }
+    for (const [index, entry] of value.entries()) {
+        if (typeof entry !== "string" || entry.trim().length === 0) {
+            throw new Error(`${prefix}${key}[${index}] must be a non-empty string.`);
+        }
+    }
+}
+function requireSubstantiveEvidenceRecord(source, prefix = "") {
+    const evidence = source.evidence;
+    if (!evidence || typeof evidence !== "object" || Array.isArray(evidence)) {
+        throw new Error(`${prefix}evidence must be an object.`);
+    }
+    if (!Object.values(evidence).some(hasSubstantiveJsonValue)) {
+        throw new Error(`${prefix}evidence must include at least one concrete evidence reference or summary.`);
+    }
+}
+function hasSubstantiveJsonValue(value) {
+    if (typeof value === "string") {
+        return value.trim().length > 0;
+    }
+    if (Array.isArray(value)) {
+        return value.length > 0;
+    }
+    if (value && typeof value === "object") {
+        return Object.keys(value).length > 0;
+    }
+    return false;
+}
+function normalizedString(value) {
+    return typeof value === "string" ? value.trim().toLowerCase().replace(/-/g, "_") : "";
+}
+function defaultQaChecklist(status) {
+    return [
+        "Review the validated work item against acceptance criteria.",
+        "Inspect implementation, self-review, and validation evidence when available.",
+        status === "blocked" ? "Record the blocker reason preventing a conclusive QA verdict." : "Record concrete QA evidence and findings."
+    ];
+}
+function qaArtifactRelativePath(workItemId, fileName) {
+    return [".forge", "work-items", workItemId, "artifacts", fileName].join("/");
+}
+function jsonText(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
 function fallbackReport(parsed, phase, artifactPath) {
     return `# Forge ${phase.replace(/_/g, " ")} completion
 

package/dist/session/provider-cli/provider-cli.base.d.ts

@@ -1,7 +1,6 @@
 import type { ProviderCliRunContext, ProviderCliRunResult } from "./provider-cli.types.js";
-import type { RunOnceDispatchPacket, RunnerDispatchEvent } from "../session.types.js";
 export interface ProviderCliService {
     runImplementation(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
     runConflictResolve(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
-    runQa(dispatch: RunOnceDispatchPacket, emit: (event: RunnerDispatchEvent) => Promise<void>, signal?: AbortSignal): Promise<ProviderCliRunResult>;
+    runQa(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
 }

package/dist/session/provider-cli/provider-cli.service.d.ts

@@ -2,7 +2,7 @@ import { GitClient } from "../../shared/git/git.js";
 import { type CompletionToolRuntime } from "../phase-completion.js";
 import type { ProviderCliService } from "./provider-cli.base.js";
 import type { ProviderCliRunContext, ProviderCliRunResult } from "./provider-cli.types.js";
-import type { RunOnceDispatchPacket, RunnerDispatchEvent } from "../session.types.js";
+import type { RunOnceDispatchPacket } from "../session.types.js";
 export interface ProviderCliCommand {
     readonly command: string;
     readonly args: readonly string[];
@@ -31,21 +31,21 @@ export declare class RoutingProviderCliService implements ProviderCliService {
     constructor(realProvider?: ProviderCliService, deterministicProvider?: ProviderCliService);
     runImplementation(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
     runConflictResolve(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
-    runQa(dispatch: RunOnceDispatchPacket, emit: (event: RunnerDispatchEvent) => Promise<void>, signal?: AbortSignal): Promise<ProviderCliRunResult>;
+    runQa(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
 }
 export declare class ProcessBackedProviderCliService implements ProviderCliService {
     private readonly processRunner;
     private readonly git;
     constructor(processRunner?: ProviderProcessRunner, git?: GitClient);
     runImplementation(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
-    runQa(dispatch: RunOnceDispatchPacket, emit: (event: RunnerDispatchEvent) => Promise<void>, signal?: AbortSignal): Promise<ProviderCliRunResult>;
+    runQa(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
     runConflictResolve(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
 }
 export declare class DeterministicProviderCliService implements ProviderCliService {
     private readonly git;
     constructor(git?: GitClient);
     runImplementation(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
-    runQa(dispatch: RunOnceDispatchPacket, emit: (event: RunnerDispatchEvent) => Promise<void>): Promise<ProviderCliRunResult>;
+    runQa(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
     runConflictResolve(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
 }
 export declare class StreamingProviderProcessRunner implements ProviderProcessRunner {

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

@@ -7,7 +7,7 @@ import { promisify } from "node:util";
 import { GitClient } from "../../shared/git/git.js";
 import { resolveCursorAgentDirectLaunch } from "../../shared/cursor-agent/cursor-agent.launch.js";
 import { buildSpecBody, selectLaneCommand } from "../../worktree/artifact-injector.js";
-import { codexMcpConfigArgs, completionPhaseFromDispatch, completionPromptForDevelopCycle, completionPromptForPhase, completionRedactionEnv, expectedCompletionToolName, prepareCompletionToolRuntime, readCompletionArtifact, usesDevelopCycleCompletion, writeCompletionArtifact } from "../phase-completion.js";
+import { codexMcpConfigArgs, completionPhaseFromDispatch, completionPromptForDevelopCycle, completionPromptForPhase, completionRedactionEnv, expectedCompletionToolName, prepareCompletionToolRuntime, readCompletionArtifact, usesDevelopCycleCompletion, writeCompletionArtifact, artifactRootFor } from "../phase-completion.js";
 import { addUsage, buildProviderUsageEvent, emptyUsage, hasUsage, readUsageNumber } from "./provider-usage.js";
 const fakeWorkerModel = "server-local-fake-worker";
 const execFileAsync = promisify(execFile);
@@ -29,10 +29,10 @@ export class RoutingProviderCliService {
             ? await this.deterministicProvider.runConflictResolve(context)
             : await this.realProvider.runConflictResolve(context);
     }
-    async runQa(dispatch, emit, signal) {
-        return isFakeWorkerModel(dispatch.execution.model)
-            ? await this.deterministicProvider.runQa(dispatch, emit, signal)
-            : await this.realProvider.runQa(dispatch, emit, signal);
+    async runQa(context) {
+        return isFakeWorkerModel(context.dispatch.execution.model)
+            ? await this.deterministicProvider.runQa(context)
+            : await this.realProvider.runQa(context);
     }
 }
 export class ProcessBackedProviderCliService {
@@ -149,42 +149,82 @@ export class ProcessBackedProviderCliService {
             artifacts: completionArtifacts
         };
     }
-    async runQa(dispatch, emit, signal) {
+    async runQa(context) {
+        const { dispatch, worktree } = context;
+        const completionTools = await prepareCompletionToolRuntime({ dispatch, worktree, phase: "qa" });
         const command = buildProviderCliCommand(dispatch, {
-            prompt: buildQaPrompt(dispatch)
+            worktreePath: worktree.worktreePath,
+            prompt: buildQaPrompt(dispatch),
+            completionTools
         });
-        await emit({
+        const commandText = formatProviderCliCommand(command);
+        await context.emit({
             role: "runner",
             kind: "checkpoint",
-            content: `Starting provider CLI QA: ${formatProviderCliCommand(command)}`,
+            content: `Starting provider CLI QA: ${commandText} in ${worktree.worktreePath}`,
             eventType: "provider_cli_started"
         });
+        await context.emit({
+            role: "runner",
+            kind: "checkpoint",
+            content: "Forge QA completion tool configured; provider must call forge.complete_qa before exit.",
+            eventType: "completion_tools_configured"
+        });
         const outputState = createProviderOutputState(dispatch.execution.provider);
-        const result = await this.processRunner.run({
-            command: command.command,
-            args: command.args,
-            cwd: process.cwd()
-        }, {
-            onStdoutLine: async (line) => {
-                const event = outputState.consume(line);
-                if (event) {
-                    await emit(event);
+        const liveQaEvents = new LiveQaArtifactEmitter(worktree.worktreePath, dispatch.workItem.id, context.emit);
+        let result;
+        try {
+            liveQaEvents.start();
+            result = await this.processRunner.run({
+                command: command.command,
+                args: command.args,
+                cwd: worktree.worktreePath,
+                env: providerRedactionEnv(dispatch)
+            }, {
+                onStdoutLine: async (line) => {
+                    const event = outputState.consume(line);
+                    if (event) {
+                        await context.emit(event);
+                    }
                 }
-            }
-        }, signal);
+            }, context.signal);
+        }
+        finally {
+            await liveQaEvents.stop();
+            await cleanupCompletionTools(completionTools, context.emit);
+        }
         if (result.exitCode !== 0) {
             const stderr = clip(result.stderr.trim() || result.stdout.trim(), 1200);
             throw new Error(`${command.command} exited ${result.exitCode}${stderr ? `: ${stderr}` : ""}`);
         }
-        await emit({
+        await context.emit({
             role: "runner",
             kind: "checkpoint",
             content: `Provider CLI QA completed: ${command.command} exit ${result.exitCode}${outputState.sessionLabel ? ` ${outputState.sessionLabel}` : ""}.`,
             eventType: "provider_cli_completed"
         });
-        await emitProviderUsageEvent(emit, dispatch, outputState);
+        await emitProviderUsageEvent(context.emit, dispatch, outputState);
+        const qaArtifact = await readQaCompletionArtifactBundle(worktree.worktreePath, dispatch.workItem.id);
+        if (!qaArtifact) {
+            const verdictOnly = await readCompletionArtifact(worktree.worktreePath, dispatch.workItem.id, "qa");
+            throw new Error(verdictOnly
+                ? "Provider CLI QA completed but did not produce the complete durable QA artifact bundle."
+                : "Provider CLI QA completed but did not call the Forge QA completion tool.");
+        }
+        if (!liveQaEvents.hasEmitted()) {
+            await emitQaArtifactRecorded(context.emit, worktree.worktreePath, qaArtifact);
+            await emitQaStructuredEvents(context.emit, worktree.worktreePath, dispatch.workItem.id, qaArtifact);
+        }
+        const status = (qaArtifact.status ?? "unknown").trim().toLowerCase();
+        const statusSummary = status === "pass"
+            ? "passed"
+            : status === "blocked"
+                ? "blocked"
+                : "found rework";
         return {
-            summary: `${dispatch.execution.provider} CLI QA passed.`
+            summary: `${dispatch.execution.provider} CLI QA ${statusSummary}.`,
+            artifact: qaArtifact,
+            artifacts: [qaArtifact]
         };
     }
     async runConflictResolve(context) {
@@ -308,22 +348,32 @@ export class DeterministicProviderCliService {
             artifacts: completionArtifacts
         };
     }
-    async runQa(dispatch, emit) {
-        await emit({
+    async runQa(context) {
+        const { dispatch, worktree } = context;
+        await context.emit({
             role: "worker",
             kind: "message",
-            content: `Running ${dispatch.execution.provider} QA checks through forge-bridge.`,
-            eventType: "qa_analysis"
+            content: `Planning ${dispatch.execution.provider} QA checks through forge-bridge.`,
+            eventType: "qa_plan"
         });
-        await emit({
-            role: "assistant",
-            kind: "message",
-            content: "All checks passed. forge-bridge QA completed.",
-            eventType: "qa_complete"
+        const summary = "All checks passed. forge-bridge QA completed.";
+        const qaArtifact = await writeQaArtifacts({
+            worktreePath: worktree.worktreePath,
+            workItemId: dispatch.workItem.id,
+            acceptanceCriteria: dispatch.workItem.acceptanceCriteria,
+            producedBy: "forge-bridge",
+            provider: dispatch.execution.provider,
+            model: dispatch.execution.model,
+            command: "forge-bridge deterministic QA",
+            summary
         });
-        await emit(buildProviderUsageEvent(dispatch, estimatedDeterministicUsage()));
+        await emitQaArtifactRecorded(context.emit, worktree.worktreePath, qaArtifact);
+        await emitQaStructuredEvents(context.emit, worktree.worktreePath, dispatch.workItem.id, qaArtifact);
+        await context.emit(buildProviderUsageEvent(dispatch, estimatedDeterministicUsage()));
         return {
-            summary: "forge-bridge QA passed."
+            summary: "forge-bridge QA passed.",
+            artifact: qaArtifact,
+            artifacts: [qaArtifact]
         };
     }
     async runConflictResolve(context) {
@@ -426,6 +476,238 @@ function deterministicCompletionPayload(phase, dispatch, changesetBody) {
         ready_for_dev_test: true
     };
 }
+const qaArtifactFileNames = {
+    plan: "qa.plan.json",
+    evidence: "qa.evidence.json",
+    findings: "qa.findings.json",
+    verdict: "qa.verdict.json",
+    report: "qa.report.md"
+};
+async function writeQaArtifacts(request) {
+    const artifactRoot = artifactRootFor(request.worktreePath, request.workItemId);
+    await fs.mkdir(artifactRoot, { recursive: true });
+    const criterion = request.acceptanceCriteria.trim() || "Forge QA evidence exists";
+    const relativeEvidencePath = qaArtifactRelativePath(request.workItemId, qaArtifactFileNames.evidence);
+    const relativeFindingsPath = qaArtifactRelativePath(request.workItemId, qaArtifactFileNames.findings);
+    const relativeReportPath = qaArtifactRelativePath(request.workItemId, qaArtifactFileNames.report);
+    const planJson = jsonText({
+        schema_version: 1,
+        phase: "qa",
+        checklist: [
+            "Review the validated work item against acceptance criteria.",
+            "Run relevant provider QA verification.",
+            "Confirm no in-scope QA findings remain."
+        ],
+        acceptance_criteria: [criterion]
+    });
+    const evidenceJson = jsonText({
+        schema_version: 1,
+        phase: "qa",
+        commands: [
+            {
+                command: request.command,
+                exit_code: 0,
+                status: "pass",
+                summary: `${request.provider} QA completed successfully.`
+            }
+        ],
+        browser_checks: [],
+        notes: request.summary
+    });
+    const findingsJson = jsonText({
+        schema_version: 1,
+        phase: "qa",
+        findings: [],
+        candidate_bugs: []
+    });
+    const verdictJson = jsonText({
+        schema_version: 1,
+        phase: "qa",
+        status: "pass",
+        summary: request.summary,
+        tested_acceptance_criteria: [criterion],
+        finding_ids: [],
+        candidate_bug_ids: [],
+        blocker_reason: null,
+        evidence_path: relativeEvidencePath,
+        findings_path: relativeFindingsPath,
+        report_path: relativeReportPath
+    });
+    const report = `# QA report\n\n${request.summary}\n\n- Provider: ${singleLine(request.provider)}\n- Model: ${singleLine(request.model)}\n- Command: ${singleLine(request.command)}\n`;
+    await fs.writeFile(path.join(artifactRoot, qaArtifactFileNames.plan), planJson, "utf8");
+    await fs.writeFile(path.join(artifactRoot, qaArtifactFileNames.evidence), evidenceJson, "utf8");
+    await fs.writeFile(path.join(artifactRoot, qaArtifactFileNames.findings), findingsJson, "utf8");
+    const verdictPath = path.join(artifactRoot, qaArtifactFileNames.verdict);
+    await fs.writeFile(verdictPath, verdictJson, "utf8");
+    await fs.writeFile(path.join(artifactRoot, qaArtifactFileNames.report), report, "utf8");
+    return {
+        repoPath: request.worktreePath,
+        path: verdictPath,
+        verdictJson,
+        report,
+        producedBy: request.producedBy,
+        status: "pass",
+        phase: "qa"
+    };
+}
+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"
+    });
+}
+async function readQaCompletionArtifactBundle(worktreePath, workItemId) {
+    const artifact = await readCompletionArtifact(worktreePath, workItemId, "qa");
+    if (!artifact || !await hasCompleteQaArtifactBundle(worktreePath, workItemId)) {
+        return null;
+    }
+    return artifact;
+}
+async function hasCompleteQaArtifactBundle(worktreePath, workItemId) {
+    const artifactRoot = 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;
+}
+async function emitQaStructuredEvents(emit, worktreePath, workItemId, artifact) {
+    const artifactRoot = artifactRootFor(worktreePath, workItemId);
+    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"
+    });
+}
+class LiveQaArtifactEmitter {
+    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) {
+            return;
+        }
+        const artifact = await readQaCompletionArtifactBundle(this.worktreePath, this.workItemId);
+        if (!artifact) {
+            return;
+        }
+        this.emitted = true;
+        await emitQaArtifactRecorded(this.emit, this.worktreePath, artifact);
+        await emitQaStructuredEvents(this.emit, this.worktreePath, this.workItemId, artifact);
+    }
+}
+async function readJsonObjectFile(filePath) {
+    const content = await fs.readFile(filePath, "utf8").catch(() => "");
+    return parseJsonLine(content) ?? {};
+}
+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));
+}
+function stringArrayField(source, key) {
+    const value = source[key];
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((entry) => typeof entry === "string" && entry.trim().length > 0);
+}
+function summarizeQaObject(source) {
+    return clip(stringField(source, "title")
+        ?? stringField(source, "summary")
+        ?? stringField(source, "id")
+        ?? JSON.stringify(source), 500);
+}
+function qaArtifactRelativePath(workItemId, fileName) {
+    return [".forge", "work-items", workItemId, "artifacts", fileName].join("/");
+}
+function jsonText(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
 async function emitCompletionArtifactRecorded(emit, worktreePath, artifact) {
     const relativePath = path.relative(worktreePath, artifact.path) || path.basename(artifact.path);
     await emit({
@@ -460,7 +742,7 @@ async function emitPhaseGateEvents(emit, artifact) {
         ? "phase_progression: implementation -> self_review"
         : phase === "self_review"
             ? "phase_progression: self_review -> validation"
-            : "phase_progression: validation -> Dev Test ready";
+            : "phase_progression: validation -> QA ready";
     await emit({
         role: "hook",
         kind: "checkpoint",
@@ -470,7 +752,7 @@ async function emitPhaseGateEvents(emit, artifact) {
 }
 function completionPhaseFromArtifact(artifact) {
     const phase = artifact.phase?.trim();
-    return phase === "self_review" || phase === "validation" || phase === "implementation"
+    return phase === "self_review" || phase === "validation" || phase === "implementation" || phase === "qa"
         ? phase
         : "implementation";
 }
@@ -789,6 +1071,7 @@ function buildImplementationPrompt(dispatch, phase = completionPhaseFromDispatch
 
 Read .forge/work-items/${dispatch.workItem.id}/spec.md and any prior phase artifacts required by this phase.
 ${phaseWorkInstruction(phase)}
+${qaReworkImplementationInstruction(dispatch)}
 Use the repository's existing conventions. Run relevant tests when practical.
 Forge owns protocol files: worktree prep, injected .forge commands/hooks/skills, phase verdict artifacts, reports, and commits.
 Read Forge-provided context under .forge when needed, but do not edit .forge files or create Forge verdict/report artifacts by hand.
@@ -802,6 +1085,7 @@ function buildDevelopCyclePrompt(dispatch, phase = completionPhaseFromDispatch(d
 
 Read .forge/work-items/${dispatch.workItem.id}/spec.md, implement the work item, self-review the diff, then validate it in this same provider session.
 Start in the ${phase.replace(/_/g, " ")} phase. Do not stop after implementation if it passes; continue through self-review and validation using the next instruction returned by each completion tool.
+${qaReworkImplementationInstruction(dispatch)}
 Use the repository's existing conventions. Run relevant tests when practical.
 Forge owns protocol files: worktree prep, injected .forge commands/hooks/skills, phase verdict artifacts, reports, and commits.
 Read Forge-provided context under .forge when needed, but do not edit .forge files or create Forge verdict/report artifacts by hand.
@@ -810,20 +1094,64 @@ ${completionPromptForDevelopCycle(phase)}
 
 Finish with a concise summary of changed files and verification after the validation completion tool has accepted the work, or after the current phase tool records a non-pass blocker.`;
 }
+function qaReworkImplementationInstruction(dispatch) {
+    if (!dispatch.qaRework) {
+        return "";
+    }
+    return `
+QA rework context:
+- Attempt ${dispatch.qaRework.attempt}/${dispatch.qaRework.maxAttempts}
+- Rework packet: ${dispatch.qaRework.packetPath}
+- Required QA finding IDs: ${dispatch.qaRework.findingIds.join(", ")}
+Read the packet JSON and fix or explicitly dispute each listed finding. The implementation completion artifact must include resolved_findings entries for every required QA ID with qa_id, status, summary, evidence, changed_files, tests_added_or_updated, and regression_evidence.`;
+}
+function qaReworkRetestInstruction(dispatch) {
+    if (!dispatch.qaRework) {
+        return "";
+    }
+    return `
+QA retest context:
+- Rework attempt ${dispatch.qaRework.attempt}/${dispatch.qaRework.maxAttempts}
+- Rework packet: ${dispatch.qaRework.packetPath}
+- Priority finding IDs: ${dispatch.qaRework.findingIds.join(", ")}
+Prioritize retesting the listed QA findings and their required regressions before deciding pass, needs_rework, or blocked.`;
+}
 function phaseWorkInstruction(phase) {
     if (phase === "self_review") {
         return "Review the implementation diff, apply safe fixes when needed, and record remaining risks explicitly.";
     }
     if (phase === "validation") {
-        return "Run the validation commands and deterministic drift checks needed to prove the work is ready for Dev Test.";
+        return "Run the validation commands and deterministic drift checks needed to prove the work is ready for QA.";
     }
     return "Implement the work item and keep the change focused.";
 }
 function buildQaPrompt(dispatch) {
-    return `You are Forge's QA lane running locally.
+    return `You are Forge's QA lane running locally in a prepared git worktree.
+
+Work item: ${dispatch.workItem.id}
+Title: ${dispatch.workItem.title}
+Description:
+${dispatch.workItem.description || "Not provided."}
+
+Acceptance criteria:
+${dispatch.workItem.acceptanceCriteria || "Not specified."}
 
-Review the implementation for work item ${dispatch.workItem.id}: ${dispatch.workItem.title}
-Run relevant verification when practical and finish with a concise QA verdict.`;
+Repro steps / scenario:
+${dispatch.workItem.reproSteps || "Not provided."}
+
+System info / environment notes:
+${dispatch.workItem.systemInfo || "Not provided."}
+
+Inspect the validated implementation and Forge artifacts under .forge/work-items/${dispatch.workItem.id}/artifacts/ when present, especially implementation, self-review, and validation evidence.
+${qaReworkRetestInstruction(dispatch)}
+QA is read-mostly: inspect code, run commands, and exercise browser/app flows when available, but do not edit product source or tests.
+Record concrete evidence. For UI/browser work, include browser_checks with URLs, actions, observed results, screenshots/traces when available, and console/network notes.
+Report in-scope defects as actionable findings with repro steps, expected/actual behavior, evidence, likely area, required fix, and required regression.
+Out-of-scope or follow-up issues belong in candidate_bugs instead of blocking the current item.
+
+${completionPromptForPhase("qa")}
+
+Finish with a concise summary only after forge.complete_qa accepts the QA bundle.`;
 }
 function buildConflictResolvePrompt(dispatch, branchName) {
     const targetBranch = dispatch.cycleRun.requestedBase || dispatch.repo.defaultBranch || "main";
@@ -1180,3 +1508,6 @@ function stringField(source, key) {
     const value = source[key];
     return typeof value === "string" && value.trim().length > 0 ? value : null;
 }
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}

package/dist/session/session.service.js

@@ -50,21 +50,17 @@ export class BridgeSessionService {
             const role = dispatch.execution.role.toLowerCase();
             const isQa = role === "qa" || lane === "qa";
             const isConflictResolve = role === "conflict_resolve" || lane === "conflict_resolve";
+            const context = {
+                dispatch,
+                worktree,
+                emit,
+                signal
+            };
             const run = isQa
-                ? await this.providerCli.runQa(dispatch, emit, signal)
+                ? await this.providerCli.runQa(context)
                 : isConflictResolve
-                    ? await this.providerCli.runConflictResolve({
-                        dispatch,
-                        worktree,
-                        emit,
-                        signal
-                    })
-                    : await this.providerCli.runImplementation({
-                        dispatch,
-                        worktree,
-                        emit,
-                        signal
-                    });
+                    ? await this.providerCli.runConflictResolve(context)
+                    : await this.providerCli.runImplementation(context);
             const phaseArtifacts = run.artifacts?.length ? run.artifacts : run.artifact ? [run.artifact] : [];
             return redactSecrets({
                 schemaVersion: 1,

package/dist/session/session.types.d.ts

@@ -11,6 +11,15 @@ export interface RunOnceDispatchPacket {
     readonly apiKeySecretGrant?: ApiKeySecretGrant | null;
     readonly artifacts: readonly DispatchResolvedArtifact[];
     readonly warmPathOverrides?: readonly string[];
+    readonly qaRework?: DispatchQaReworkContext | null;
+}
+export interface DispatchQaReworkContext {
+    readonly attempt: number;
+    readonly maxAttempts: number;
+    readonly packetPath: string;
+    readonly packetJson: string;
+    readonly findingIds: readonly string[];
+    readonly findings: readonly Record<string, unknown>[];
 }
 export interface DispatchResolvedArtifact {
     readonly kind: string;

package/dist/session/session.types.js

@@ -17,7 +17,8 @@ export function parseRunOnceDispatchPacket(value) {
         serverLocal: parseServerLocal(packet.serverLocal),
         apiKeySecretGrant: parseApiKeySecretGrant(packet.apiKeySecretGrant),
         artifacts: parseArtifacts(packet.artifacts),
-        warmPathOverrides: parseWarmPathOverrides(packet.warmPathOverrides)
+        warmPathOverrides: parseWarmPathOverrides(packet.warmPathOverrides),
+        qaRework: parseQaRework(packet.qaRework)
     };
 }
 export function failureResult(summary, events = []) {
@@ -138,6 +139,33 @@ function parseWarmPathOverride(entry, index) {
     }
     return segments.join("/");
 }
+function parseQaRework(value) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    const qaRework = asObject(value, "qaRework");
+    const findingIdsValue = qaRework.findingIds;
+    if (!Array.isArray(findingIdsValue)) {
+        throw new Error("qaRework.findingIds must be an array.");
+    }
+    const findingsValue = qaRework.findings;
+    if (!Array.isArray(findingsValue)) {
+        throw new Error("qaRework.findings must be an array.");
+    }
+    return {
+        attempt: requiredNumber(qaRework, "attempt"),
+        maxAttempts: requiredNumber(qaRework, "maxAttempts"),
+        packetPath: requiredString(qaRework, "packetPath"),
+        packetJson: requiredString(qaRework, "packetJson"),
+        findingIds: findingIdsValue.map((entry, index) => {
+            if (typeof entry !== "string" || entry.trim().length === 0) {
+                throw new Error(`qaRework.findingIds[${index}] must be a non-empty string.`);
+            }
+            return entry;
+        }),
+        findings: findingsValue.map((entry, index) => asObject(entry, `qaRework.findings[${index}]`))
+    };
+}
 function parseArtifacts(value) {
     if (value === undefined || value === null) {
         return [];

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const forgeBridgeVersion = "0.1.1-dev.4f31cdd58cac";
+export declare const forgeBridgeVersion = "0.1.1-dev.65ea6889412c";

package/dist/version.js

@@ -1 +1 @@
-export const forgeBridgeVersion = "0.1.1-dev.4f31cdd58cac";
+export const forgeBridgeVersion = "0.1.1-dev.65ea6889412c";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loucompanion/forge-bridge",
-  "version": "0.1.1-dev.4f31cdd58cac",
+  "version": "0.1.1-dev.65ea6889412c",
   "description": "Forge runner bridge CLI for connecting local developer machines to Forge dispatch.",
   "license": "UNLICENSED",
   "type": "module",