@loucompanion/forge-bridge 0.1.1-dev.ac486debe210 → 0.1.1-dev.caea7216568f

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.`;
     }
@@ -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.service.js

@@ -151,9 +151,11 @@ export class ProcessBackedProviderCliService {
     }
     async runQa(context) {
         const { dispatch, worktree } = context;
+        const completionTools = await prepareCompletionToolRuntime({ dispatch, worktree, phase: "qa" });
         const command = buildProviderCliCommand(dispatch, {
             worktreePath: worktree.worktreePath,
-            prompt: buildQaPrompt(dispatch)
+            prompt: buildQaPrompt(dispatch),
+            completionTools
         });
         const commandText = formatProviderCliCommand(command);
         await context.emit({
@@ -162,20 +164,35 @@ export class ProcessBackedProviderCliService {
             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: worktree.worktreePath,
-            env: providerRedactionEnv(dispatch)
-        }, {
-            onStdoutLine: async (line) => {
-                const event = outputState.consume(line);
-                if (event) {
-                    await context.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);
+                    }
                 }
-            }
-        }, context.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}` : ""}`);
@@ -187,20 +204,25 @@ export class ProcessBackedProviderCliService {
             eventType: "provider_cli_completed"
         });
         await emitProviderUsageEvent(context.emit, dispatch, outputState);
-        const summary = outputState.finalMessage || `${dispatch.execution.provider} CLI QA passed.`;
-        const qaArtifact = await writeQaArtifacts({
-            worktreePath: worktree.worktreePath,
-            workItemId: dispatch.workItem.id,
-            acceptanceCriteria: dispatch.workItem.acceptanceCriteria,
-            producedBy: `${dispatch.execution.provider}-cli`,
-            provider: dispatch.execution.provider,
-            model: dispatch.execution.model,
-            command: commandText,
-            summary
-        });
-        await emitQaArtifactRecorded(context.emit, worktree.worktreePath, qaArtifact);
+        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]
         };
@@ -331,8 +353,8 @@ export class DeterministicProviderCliService {
         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"
         });
         const summary = "All checks passed. forge-bridge QA completed.";
         const qaArtifact = await writeQaArtifacts({
@@ -346,12 +368,7 @@ export class DeterministicProviderCliService {
             summary
         });
         await emitQaArtifactRecorded(context.emit, worktree.worktreePath, qaArtifact);
-        await context.emit({
-            role: "assistant",
-            kind: "message",
-            content: summary,
-            eventType: "qa_complete"
-        });
+        await emitQaStructuredEvents(context.emit, worktree.worktreePath, dispatch.workItem.id, qaArtifact);
         await context.emit(buildProviderUsageEvent(dispatch, estimatedDeterministicUsage()));
         return {
             summary: "forge-bridge QA passed.",
@@ -548,6 +565,143 @@ async function emitQaArtifactRecorded(emit, worktreePath, artifact) {
         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("/");
 }
@@ -598,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";
 }
@@ -948,10 +1102,31 @@ function phaseWorkInstruction(phase) {
     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."}
+
+Repro steps / scenario:
+${dispatch.workItem.reproSteps || "Not provided."}
 
-Review the implementation for work item ${dispatch.workItem.id}: ${dispatch.workItem.title}
-Run relevant verification when practical and finish with a concise QA verdict.`;
+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.
+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";
@@ -1308,3 +1483,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/version.d.ts

@@ -1 +1 @@
-export declare const forgeBridgeVersion = "0.1.1-dev.ac486debe210";
+export declare const forgeBridgeVersion = "0.1.1-dev.caea7216568f";

package/dist/version.js

@@ -1 +1 @@
-export const forgeBridgeVersion = "0.1.1-dev.ac486debe210";
+export const forgeBridgeVersion = "0.1.1-dev.caea7216568f";

package/package.json

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