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

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

@@ -0,0 +1,10 @@
+import { type CompletionArtifactReference, type CompletionPhase, type CompletionToolServerConfig, type DecomposeCompletionGate, type DraftCompletionGate, type QaCompletionGate } from "./phase-completion.js";
+import type { RunnerDispatchArtifact } from "./session.types.js";
+export declare function writeDecomposeGateCompletionArtifact(config: CompletionToolServerConfig, gate: DecomposeCompletionGate, toolName: string, input: unknown): Promise<CompletionArtifactReference>;
+export declare function writeDraftGateCompletionArtifact(config: CompletionToolServerConfig, gate: DraftCompletionGate, toolName: string, input: unknown): Promise<CompletionArtifactReference>;
+export declare function writeCompletionArtifact(config: CompletionToolServerConfig, toolName: string, input: unknown): Promise<CompletionArtifactReference>;
+export declare function writeArchitectCompletionArtifact(config: CompletionToolServerConfig, payload: Record<string, unknown>, status: string, producedBy: string): Promise<CompletionArtifactReference>;
+export declare function writeQaGateCompletionArtifact(config: CompletionToolServerConfig, gate: QaCompletionGate, input: unknown): Promise<CompletionArtifactReference>;
+export declare function writeQaCompletionArtifact(config: CompletionToolServerConfig, payload: Record<string, unknown>, status: string, producedBy: string): Promise<CompletionArtifactReference>;
+export declare function readQaGateArtifact(config: CompletionToolServerConfig, gate: QaCompletionGate): Promise<Record<string, unknown>>;
+export declare function readCompletionArtifact(worktreePath: string, workItemId: string, phase: CompletionPhase, ownerType?: string | null, ownerId?: string | null): Promise<RunnerDispatchArtifact | null>;

package/dist/session/phase-completion.artifacts.js

@@ -0,0 +1,627 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { redactSecrets } from "../shared/redaction/redaction.js";
+import { ensureNoSymbolicLinkPathSegments, isPathUnderRoot, sha256File } from "./qa-sidecar-validation.js";
+import { artifactRootFor, artifactRootForOwner, completionArtifactJsonPath, completionArtifactReportPath, decomposeGateFileNames, draftGateFileNames, phaseFiles, qaGateFileNames } from "./phase-completion.js";
+import { artifactOwnerFields, artifactReferenceOwnerFields, artifactOwnerRelativeRoot, defaultQaChecklist, fallbackReport, isNodeError, jsonText, normalizeArtifactPayload, normalizeCompletionStatus, normalizeQaGateArtifactPayload, normalizeQaGateStatus, normalizedString, optionalString, numberOrDefault, parseJsonObject, parseOptionalJsonObject, phaseFromToolName, qaArray, qaArtifactRelativePath, qaArtifactRelativePathForOwner, qaEvidenceSource, qaObjectArray, qaPolicyWarnings, qaStringArray, readOptionalFile, reportMarkdown, requiredRecord, requiredString, qaGateFromToolName, sha256, stableStringify, validateOptionalWorkItemId, validatePayloadShape, validateQaGatePayloadShape, validateQaScopeRecord, writeFileAtomic, asRecord } from "./phase-completion.validation.js";
+export async function writeDecomposeGateCompletionArtifact(config, gate, toolName, input) {
+    const payload = asRecord(input, "Decompose completion payload");
+    const status = normalizeDraftStatus(optionalString(payload, "status") ?? "pass");
+    if (gate === "decompose_proposal") {
+        const proposalJson = asRecord(payload["proposal_json"] ?? payload["decomposition_json"], "proposal_json");
+        validateDecomposeProposalJson(proposalJson);
+    }
+    const redactedPayload = redactSecrets({ ...payload, status, phase: "decompose", gate, tool_name: toolName }, config.redactionSecrets ?? []);
+    const root = artifactRootFor(config.worktreePath, config.workItemId);
+    await fs.mkdir(root, { recursive: true });
+    const artifactPath = path.join(root, decomposeGateFileNames[gate]);
+    const reportPath = gate === "decompose_proposal" ? path.join(root, phaseFiles.decompose.reportFileName) : path.join(root, `${gate}.md`);
+    const verdictJson = jsonText(redactedPayload);
+    const report = optionalString(redactedPayload, "report_markdown") ?? `# ${gate.replace(/_/g, " ")}
+
+${optionalString(redactedPayload, "summary") ?? "Decompose gate recorded."}
+`;
+    await writeFileAtomic(artifactPath, verdictJson);
+    await writeFileAtomic(reportPath, report);
+    return {
+        phase: "decompose",
+        workItemId: config.workItemId,
+        ownerType: config.ownerType,
+        ownerId: config.ownerId,
+        repoPath: path.resolve(config.worktreePath),
+        path: artifactPath,
+        reportPath,
+        contentHash: sha256(verdictJson),
+        status,
+        producedBy: config.producedBy ?? "forge-completion-tool"
+    };
+}
+export async function writeDraftGateCompletionArtifact(config, gate, toolName, input) {
+    const payload = asRecord(input, "Draft completion payload");
+    const status = normalizeDraftStatus(optionalString(payload, "status") ?? "pass");
+    if (gate === "draft_proposal") {
+        const draftJson = asRecord(payload["draft_json"], "draft_json");
+        validateDraftProposalJson(draftJson);
+    }
+    const redactedPayload = redactSecrets({ ...payload, status, phase: "draft", gate, tool_name: toolName }, config.redactionSecrets ?? []);
+    const root = artifactRootFor(config.worktreePath, config.workItemId);
+    await fs.mkdir(root, { recursive: true });
+    const artifactPath = path.join(root, draftGateFileNames[gate]);
+    const reportPath = gate === "draft_proposal" ? path.join(root, phaseFiles.draft.reportFileName) : path.join(root, `${gate}.md`);
+    const verdictJson = jsonText(redactedPayload);
+    const report = optionalString(redactedPayload, "report_markdown") ?? `# ${gate.replace(/_/g, " ")}\n\n${optionalString(redactedPayload, "summary") ?? "Draft gate recorded."}\n`;
+    await writeFileAtomic(artifactPath, verdictJson);
+    await writeFileAtomic(reportPath, report);
+    return {
+        phase: "draft",
+        workItemId: config.workItemId,
+        ownerType: config.ownerType,
+        ownerId: config.ownerId,
+        repoPath: path.resolve(config.worktreePath),
+        path: artifactPath,
+        reportPath,
+        contentHash: sha256(verdictJson),
+        status,
+        producedBy: config.producedBy ?? "forge-completion-tool"
+    };
+}
+function normalizeDraftStatus(value) {
+    const normalized = value.trim().toLowerCase();
+    return normalized === "blocked" || normalized === "needs_revision" || normalized === "needs_rework" ? normalized : "pass";
+}
+function validateDraftProposalJson(draftJson) {
+    if (draftJson.suggested_qa_scope !== undefined && draftJson.suggested_qa_scope !== null) {
+        if (!draftJson.suggested_qa_scope || typeof draftJson.suggested_qa_scope !== "object" || Array.isArray(draftJson.suggested_qa_scope)) {
+            throw new Error("draft_json.suggested_qa_scope: expected object when present.");
+        }
+        validateQaScopeRecord(draftJson.suggested_qa_scope, "draft_json.suggested_qa_scope");
+    }
+    if (isDecompositionDraftJson(draftJson)) {
+        return;
+    }
+    if (isWorkItemDraftJson(draftJson)) {
+        for (const key of ["title", "description", "acceptanceCriteria"]) {
+            if (typeof draftJson[key] !== "string" || draftJson[key].trim().length === 0) {
+                throw new Error(`draft_json.${key}: expected non-empty string`);
+            }
+        }
+        return;
+    }
+    for (const key of ["title", "summary", "objective", "planningPacket", "decompositionContext"]) {
+        if (typeof draftJson[key] !== "string" || draftJson[key].trim().length === 0) {
+            throw new Error(`draft_json.${key}: expected non-empty string`);
+        }
+    }
+}
+function isDecompositionDraftJson(draftJson) {
+    const summary = draftJson["summary"];
+    return typeof summary === "string"
+        && summary.trim().length > 0
+        && Array.isArray(draftJson["candidates"]);
+}
+function isWorkItemDraftJson(draftJson) {
+    return typeof draftJson.title === "string"
+        && typeof draftJson.description === "string"
+        && typeof draftJson.acceptanceCriteria === "string";
+}
+function validateDecomposeProposalJson(proposalJson) {
+    const candidates = proposalJson.candidates;
+    if (!Array.isArray(candidates)) {
+        throw new Error("proposal_json.candidates: expected array");
+    }
+    for (const [index, candidate] of candidates.entries()) {
+        if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) {
+            throw new Error(`proposal_json.candidates[${index}]: expected object.`);
+        }
+        const record = candidate;
+        validateOptionalCandidateQaScope(record, "estimated_qa_scope", `proposal_json.candidates[${index}].estimated_qa_scope`);
+        validateOptionalCandidateQaScope(record, "estimatedQaScope", `proposal_json.candidates[${index}].estimatedQaScope`);
+        validateOptionalCandidateQaScope(record, "qa_scope", `proposal_json.candidates[${index}].qa_scope`);
+        validateOptionalCandidateQaScope(record, "qaScope", `proposal_json.candidates[${index}].qaScope`);
+    }
+}
+function validateOptionalCandidateQaScope(candidate, key, pathLabel) {
+    const value = candidate[key];
+    if (value === undefined || value === null) {
+        return;
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${pathLabel}: expected object when present.`);
+    }
+    validateQaScopeRecord(value, pathLabel);
+}
+export async function writeCompletionArtifact(config, toolName, input) {
+    const phase = phaseFromToolName(toolName);
+    if (phase !== config.phase) {
+        throw new Error(`Tool ${toolName} is not allowed for phase ${config.phase}.`);
+    }
+    const qaGate = qaGateFromToolName(toolName);
+    if (qaGate && qaGate !== "qa_verdict") {
+        return await writeQaGateCompletionArtifact(config, qaGate, input);
+    }
+    const payload = asRecord(input, "completion payload");
+    const status = normalizeCompletionStatus(requiredString(payload, "status"), phase);
+    let validationPayload = { ...payload, status };
+    if (config.qaCycle && qaGate === "qa_verdict") {
+        validationPayload = await synthesizeQaCycleVerdictPayload(config, validationPayload, status);
+    }
+    validatePayloadShape(phase, validationPayload);
+    validateOptionalWorkItemId(validationPayload, config.workItemId);
+    const redactedPayload = redactSecrets(validationPayload, config.redactionSecrets ?? []);
+    const producedBy = optionalString(redactedPayload, "produced_by")
+        ?? optionalString(redactedPayload, "producedBy")
+        ?? config.producedBy
+        ?? "forge-completion-tool";
+    if (phase === "qa") {
+        return await writeQaCompletionArtifact(config, redactedPayload, status, producedBy);
+    }
+    if (phase === "architect") {
+        return await writeArchitectCompletionArtifact(config, redactedPayload, status, producedBy);
+    }
+    const artifactWithoutHash = normalizeArtifactPayload(redactedPayload, {
+        phase,
+        workItemId: config.workItemId,
+        ownerType: config.ownerType,
+        ownerId: config.ownerId,
+        producedBy,
+        status
+    });
+    const contentHash = sha256(stableStringify(artifactWithoutHash));
+    const artifact = {
+        ...artifactWithoutHash,
+        content_hash: contentHash
+    };
+    const artifactJson = `${JSON.stringify(artifact, null, 2)}\n`;
+    const report = reportMarkdown(redactedPayload, phase, status, producedBy, contentHash);
+    const artifactPath = completionArtifactJsonPath(config.worktreePath, config.workItemId, phase);
+    const reportPath = completionArtifactReportPath(config.worktreePath, config.workItemId, phase);
+    await fs.mkdir(path.dirname(artifactPath), { recursive: true });
+    await writeFileAtomic(artifactPath, artifactJson);
+    await writeFileAtomic(reportPath, report);
+    return {
+        phase,
+        workItemId: config.workItemId,
+        ...artifactReferenceOwnerFields(config),
+        repoPath: path.resolve(config.worktreePath),
+        path: artifactPath,
+        reportPath,
+        contentHash,
+        status,
+        producedBy
+    };
+}
+export async function writeArchitectCompletionArtifact(config, payload, status, producedBy) {
+    const ownerFields = artifactOwnerFields(config);
+    const artifactRoot = ownerFields.owner_type && ownerFields.owner_id
+        ? artifactRootForOwner(config.worktreePath, ownerFields.owner_type, ownerFields.owner_id)
+        : artifactRootFor(config.worktreePath, config.workItemId);
+    const implementationPlanPath = path.join(artifactRoot, "implementation.plan.json");
+    const qaPlanPath = path.join(artifactRoot, "qa.plan.json");
+    const verdictPath = path.join(artifactRoot, "architect.verdict.json");
+    const reportPath = path.join(artifactRoot, "architect.report.md");
+    const implementationPlan = requiredRecord(payload, "implementation_plan");
+    const qaPlan = requiredRecord(payload, "qa_plan");
+    const report = optionalString(payload, "report") ?? optionalString(payload, "report_markdown") ?? reportMarkdown(payload, "architect", status, producedBy, "pending");
+    const artifactWithoutHash = normalizeArtifactPayload(payload, {
+        phase: "architect",
+        workItemId: config.workItemId,
+        ownerType: config.ownerType,
+        ownerId: config.ownerId,
+        producedBy,
+        status
+    });
+    const contentHash = sha256(stableStringify(artifactWithoutHash));
+    const verdict = {
+        ...artifactWithoutHash,
+        content_hash: contentHash
+    };
+    await fs.mkdir(artifactRoot, { recursive: true });
+    await writeFileAtomic(implementationPlanPath, jsonText(implementationPlan));
+    await writeFileAtomic(qaPlanPath, jsonText(qaPlan));
+    await writeFileAtomic(verdictPath, jsonText(verdict));
+    await writeFileAtomic(reportPath, `${report.trim()}\n`);
+    return {
+        phase: "architect",
+        workItemId: config.workItemId,
+        ...artifactReferenceOwnerFields(config),
+        repoPath: path.resolve(config.worktreePath),
+        path: verdictPath,
+        reportPath,
+        contentHash,
+        status,
+        producedBy
+    };
+}
+export async function writeQaGateCompletionArtifact(config, gate, input) {
+    const payload = asRecord(input, "QA gate completion payload");
+    const status = normalizeQaGateStatus(requiredString(payload, "status"));
+    validateQaGatePayloadShape(gate, payload, status);
+    validateOptionalWorkItemId(payload, config.workItemId);
+    const ownerFields = artifactOwnerFields(config);
+    const validatedSidecars = gate === "qa_manual_web"
+        ? await validateQaSidecarReferences(config.worktreePath, config.workItemId, qaArray(payload, "sidecars", qaEvidenceSource(payload)), ownerFields.owner_type, ownerFields.owner_id)
+        : null;
+    const redactedPayload = redactSecrets({
+        ...payload,
+        status,
+        ...(validatedSidecars ? { sidecars: validatedSidecars } : {})
+    }, config.redactionSecrets ?? []);
+    const producedBy = optionalString(redactedPayload, "produced_by")
+        ?? optionalString(redactedPayload, "producedBy")
+        ?? config.producedBy
+        ?? "forge-completion-tool";
+    const artifactRoot = ownerFields.owner_type && ownerFields.owner_id
+        ? artifactRootForOwner(config.worktreePath, ownerFields.owner_type, ownerFields.owner_id)
+        : artifactRootFor(config.worktreePath, config.workItemId);
+    const fileName = qaGateFileNames[gate];
+    const artifactPath = path.join(artifactRoot, fileName);
+    const reportPath = path.join(artifactRoot, "qa.report.md");
+    const artifactWithoutHash = normalizeQaGateArtifactPayload(redactedPayload, {
+        gate,
+        workItemId: config.workItemId,
+        ownerType: config.ownerType,
+        ownerId: config.ownerId,
+        producedBy,
+        status
+    });
+    const contentHash = sha256(stableStringify(artifactWithoutHash));
+    const artifact = {
+        ...artifactWithoutHash,
+        content_hash: contentHash
+    };
+    await fs.mkdir(artifactRoot, { recursive: true });
+    await writeFileAtomic(artifactPath, jsonText(artifact));
+    return {
+        phase: "qa",
+        workItemId: config.workItemId,
+        ...artifactReferenceOwnerFields(config),
+        repoPath: path.resolve(config.worktreePath),
+        path: artifactPath,
+        reportPath,
+        contentHash,
+        status,
+        producedBy
+    };
+}
+export async function writeQaCompletionArtifact(config, payload, status, producedBy) {
+    const ownerFields = artifactOwnerFields(config);
+    const artifactRoot = ownerFields.owner_type && ownerFields.owner_id
+        ? artifactRootForOwner(config.worktreePath, ownerFields.owner_type, ownerFields.owner_id)
+        : 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 = ownerFields.owner_type && ownerFields.owner_id
+        ? qaArtifactRelativePathForOwner(ownerFields.owner_type, ownerFields.owner_id, "qa.evidence.json")
+        : qaArtifactRelativePath(config.workItemId, "qa.evidence.json");
+    const relativeFindingsPath = ownerFields.owner_type && ownerFields.owner_id
+        ? qaArtifactRelativePathForOwner(ownerFields.owner_type, ownerFields.owner_id, "qa.findings.json")
+        : qaArtifactRelativePath(config.workItemId, "qa.findings.json");
+    const relativeReportPath = ownerFields.owner_type && ownerFields.owner_id
+        ? qaArtifactRelativePathForOwner(ownerFields.owner_type, ownerFields.owner_id, "qa.report.md")
+        : qaArtifactRelativePath(config.workItemId, "qa.report.md");
+    const evidenceSource = qaEvidenceSource(payload);
+    const commands = qaArray(payload, "commands", evidenceSource);
+    const browserChecks = qaArray(payload, "browser_checks", evidenceSource);
+    const sidecars = await validateQaSidecarReferences(config.worktreePath, config.workItemId, qaArray(payload, "sidecars", evidenceSource), ownerFields.owner_type, ownerFields.owner_id);
+    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 policyWarnings = qaPolicyWarnings(payload);
+    const blockerReason = optionalString(payload, "blocker_reason");
+    const checklist = qaStringArray(payload, "checklist");
+    const planJson = jsonText({
+        schema_version: 1,
+        phase: "qa",
+        ...ownerFields,
+        checklist: checklist.length > 0 ? checklist : defaultQaChecklist(status),
+        acceptance_criteria: testedAcceptanceCriteria
+    });
+    const evidenceJson = jsonText({
+        schema_version: 1,
+        phase: "qa",
+        ...ownerFields,
+        commands,
+        browser_checks: browserChecks,
+        sidecars,
+        notes
+    });
+    const findingsJson = jsonText({
+        schema_version: 1,
+        phase: "qa",
+        ...ownerFields,
+        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",
+        ...ownerFields,
+        status,
+        summary: requiredString(payload, "summary"),
+        tested_acceptance_criteria: testedAcceptanceCriteria,
+        finding_ids: findingIds,
+        candidate_bug_ids: candidateBugIds,
+        policy_warnings: policyWarnings,
+        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,
+        ...artifactReferenceOwnerFields(config),
+        repoPath: path.resolve(config.worktreePath),
+        path: verdictPath,
+        reportPath,
+        contentHash,
+        status,
+        producedBy
+    };
+}
+async function synthesizeQaCycleVerdictPayload(config, payload, status) {
+    const qaPlan = await readQaGateArtifact(config, "qa_plan");
+    const qaRegression = await readQaGateArtifact(config, "qa_regression");
+    const qaApi = await readQaGateArtifact(config, "qa_api");
+    const qaManualWeb = await readQaGateArtifact(config, "qa_manual_web");
+    const qaBugRepro = await readQaGateArtifact(config, "qa_bug_repro");
+    const qaFindings = await readQaGateArtifact(config, "qa_findings");
+    const evidenceGates = [qaRegression, qaApi, qaManualWeb, qaBugRepro];
+    const payloadEvidence = qaEvidenceSource(payload);
+    const merged = { ...payload };
+    const checklist = qaStringArray(payload, "checklist");
+    if (checklist.length === 0) {
+        const plannedChecklist = qaStringArray(qaPlan, "checklist");
+        merged.checklist = plannedChecklist.length > 0 ? plannedChecklist : defaultQaChecklist(status);
+    }
+    const testedAcceptanceCriteria = qaStringArray(payload, "tested_acceptance_criteria");
+    if (testedAcceptanceCriteria.length === 0) {
+        const plannedAcceptanceCriteria = qaStringArray(qaPlan, "acceptance_criteria");
+        const payloadAcceptanceCriteria = qaStringArray(payload, "acceptance_criteria");
+        const acceptanceCriteria = plannedAcceptanceCriteria.length > 0 ? plannedAcceptanceCriteria : payloadAcceptanceCriteria;
+        if (acceptanceCriteria.length > 0) {
+            merged.tested_acceptance_criteria = acceptanceCriteria;
+        }
+    }
+    const payloadCommands = qaArray(payload, "commands", payloadEvidence);
+    const inheritedCommands = evidenceGates.flatMap((gate) => qaArray(gate, "commands"));
+    const inheritedDiagnosticCommandNotes = status === "pass"
+        ? qaNonPassingCommandNotes(inheritedCommands)
+        : [];
+    merged.commands = dedupeUnknownArray([
+        ...payloadCommands,
+        ...(status === "pass" ? inheritedCommands.filter(isQaPassingCommandEvidence) : inheritedCommands)
+    ]);
+    merged.browser_checks = dedupeUnknownArray([
+        ...qaArray(payload, "browser_checks", payloadEvidence),
+        ...evidenceGates.flatMap((gate) => qaArray(gate, "browser_checks").map(normalizeInheritedQaBrowserCheck))
+    ]);
+    merged.sidecars = dedupeUnknownArray([
+        ...qaArray(payload, "sidecars", payloadEvidence),
+        ...evidenceGates.flatMap((gate) => qaArray(gate, "sidecars"))
+    ]);
+    const notes = dedupeStrings([
+        optionalString(payload, "notes"),
+        optionalString(payloadEvidence, "notes"),
+        ...evidenceGates.map((gate) => optionalString(gate, "notes")),
+        ...inheritedDiagnosticCommandNotes
+    ]);
+    if (notes.length > 0) {
+        merged.notes = notes.join("\n");
+    }
+    merged.findings = mergeQaObjectArraysById(qaObjectArray(payload, "findings"), qaObjectArray(qaFindings, "findings"));
+    merged.candidate_bugs = mergeQaObjectArraysById(qaObjectArray(payload, "candidate_bugs"), qaObjectArray(qaFindings, "candidate_bugs"));
+    return merged;
+}
+export async function readQaGateArtifact(config, gate) {
+    const ownerFields = artifactOwnerFields(config);
+    const artifactRoot = ownerFields.owner_type && ownerFields.owner_id
+        ? artifactRootForOwner(config.worktreePath, ownerFields.owner_type, ownerFields.owner_id)
+        : artifactRootFor(config.worktreePath, config.workItemId);
+    const artifactPath = path.join(artifactRoot, qaGateFileNames[gate]);
+    const content = await readOptionalFile(artifactPath);
+    return content === null ? {} : parseOptionalJsonObject(content, qaGateFileNames[gate]);
+}
+function dedupeUnknownArray(values) {
+    const seen = new Set();
+    const deduped = [];
+    for (const value of values) {
+        const key = stableStringify(value);
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        deduped.push(value);
+    }
+    return deduped;
+}
+function isQaPassingCommandEvidence(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const record = value;
+    return record.exit_code === 0 && normalizedString(record.status) === "pass";
+}
+function qaNonPassingCommandNotes(values) {
+    return values
+        .filter((value) => !isQaPassingCommandEvidence(value))
+        .map((value, index) => {
+        if (!value || typeof value !== "object" || Array.isArray(value)) {
+            return `QA diagnostic command ${index + 1} was omitted from pass evidence because it was not a structured passing command.`;
+        }
+        const record = value;
+        const command = optionalString(record, "command") ?? "<missing command>";
+        const status = optionalString(record, "status") ?? "<missing status>";
+        const exitCode = typeof record.exit_code === "number" && Number.isFinite(record.exit_code)
+            ? String(record.exit_code)
+            : "<missing exit_code>";
+        const summary = optionalString(record, "summary");
+        return `QA diagnostic command omitted from pass evidence: ${command} (status ${status}, exit_code ${exitCode})${summary ? ` — ${summary}` : ""}.`;
+    });
+}
+function mergeQaObjectArraysById(primary, fallback) {
+    const seen = new Set();
+    const merged = [];
+    for (const value of [...primary, ...fallback]) {
+        const id = optionalString(value, "id");
+        const key = id ? `id:${id}` : stableStringify(value);
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        merged.push(value);
+    }
+    return merged;
+}
+function dedupeStrings(values) {
+    const seen = new Set();
+    const deduped = [];
+    for (const value of values) {
+        const trimmed = value?.trim();
+        if (!trimmed || seen.has(trimmed)) {
+            continue;
+        }
+        seen.add(trimmed);
+        deduped.push(trimmed);
+    }
+    return deduped;
+}
+function normalizeInheritedQaBrowserCheck(browserCheck) {
+    if (!browserCheck || typeof browserCheck !== "object" || Array.isArray(browserCheck)) {
+        return browserCheck;
+    }
+    const record = browserCheck;
+    if (optionalString(record, "summary")) {
+        return record;
+    }
+    const target = optionalString(record, "url") ?? optionalString(record, "route") ?? "the configured browser target";
+    const status = optionalString(record, "status") ?? "recorded";
+    return {
+        ...record,
+        summary: `Inherited browser check ${status} for ${target}.`
+    };
+}
+function normalizeSha256ContentHash(contentHash) {
+    const normalized = contentHash.trim().toLowerCase();
+    return normalized.startsWith("sha256:")
+        ? normalized.slice("sha256:".length)
+        : normalized;
+}
+async function validateQaSidecarReferences(worktreePath, workItemId, sidecars, ownerType, ownerId) {
+    if (sidecars.length === 0) {
+        return [];
+    }
+    const artifactRoot = ownerType && ownerId
+        ? artifactRootForOwner(worktreePath, ownerType, ownerId)
+        : artifactRootFor(worktreePath, workItemId);
+    const qaSidecarRoot = path.resolve(artifactRoot, "qa");
+    const validated = [];
+    for (const [index, sidecar] of sidecars.entries()) {
+        if (!sidecar || typeof sidecar !== "object" || Array.isArray(sidecar)) {
+            throw new Error(`sidecars[${index}] must be an object.`);
+        }
+        const record = sidecar;
+        const sidecarPath = optionalString(record, "path");
+        const contentHash = optionalString(record, "content_hash");
+        const bytes = record.bytes;
+        if (!sidecarPath || !contentHash || typeof bytes !== "number" || !Number.isFinite(bytes) || bytes <= 0) {
+            throw new Error(`sidecars[${index}] must include path, content_hash, and positive bytes.`);
+        }
+        if (path.isAbsolute(sidecarPath)) {
+            throw new Error(`sidecars[${index}].path must be relative to the worktree.`);
+        }
+        const fullPath = path.resolve(worktreePath, sidecarPath);
+        if (!isPathUnderRoot(qaSidecarRoot, fullPath)) {
+            throw new Error(`sidecars[${index}].path must be under ${artifactOwnerRelativeRoot(ownerType, ownerId, workItemId)}/qa/.`);
+        }
+        const stat = await fs.lstat(fullPath).catch((error) => {
+            if (isNodeError(error) && error.code === "ENOENT") {
+                throw new Error(`sidecars[${index}].path does not exist: ${sidecarPath}`);
+            }
+            throw error;
+        });
+        if (!stat.isFile() || stat.isSymbolicLink()) {
+            throw new Error(`sidecars[${index}].path must reference a regular file.`);
+        }
+        await ensureNoSymbolicLinkPathSegments(qaSidecarRoot, path.dirname(fullPath), `sidecars[${index}].path must not traverse symbolic links.`);
+        if (stat.size !== bytes) {
+            throw new Error(`sidecars[${index}].bytes does not match the referenced file.`);
+        }
+        const actualHash = await sha256File(fullPath);
+        if (actualHash !== normalizeSha256ContentHash(contentHash)) {
+            throw new Error(`sidecars[${index}].content_hash does not match the referenced file.`);
+        }
+        validated.push({
+            ...record,
+            path: path.relative(worktreePath, fullPath).split(path.sep).join("/"),
+            content_hash: actualHash,
+            bytes: stat.size
+        });
+    }
+    return validated;
+}
+export async function readCompletionArtifact(worktreePath, workItemId, phase, ownerType, ownerId) {
+    const artifactPath = completionArtifactJsonPath(worktreePath, workItemId, phase, ownerType, ownerId);
+    const reportPath = completionArtifactReportPath(worktreePath, workItemId, phase, ownerType, ownerId);
+    const verdictJson = await readOptionalFile(artifactPath);
+    if (verdictJson === null) {
+        return null;
+    }
+    const parsed = parseJsonObject(verdictJson, artifactPath);
+    const report = await readOptionalFile(reportPath) ?? fallbackReport(parsed, phase, artifactPath);
+    const artifactRoot = path.dirname(artifactPath);
+    const implementationPlanJson = phase === "architect"
+        ? await readOptionalFile(path.join(artifactRoot, "implementation.plan.json"))
+        : null;
+    const qaPlanJson = phase === "architect"
+        ? await readOptionalFile(path.join(artifactRoot, "qa.plan.json"))
+        : null;
+    return {
+        repoPath: path.resolve(worktreePath),
+        path: artifactPath,
+        verdictJson,
+        implementationPlanJson,
+        qaPlanJson,
+        report,
+        producedBy: optionalString(parsed, "produced_by") ?? optionalString(parsed, "producedBy") ?? "forge-completion-tool",
+        status: optionalString(parsed, "status") ?? "unknown",
+        phase
+    };
+}