@loucompanion/forge-bridge 0.1.3-dev.f66395c3ac21 → 0.1.4-dev.bfa11ebe98c6

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

@@ -0,0 +1,829 @@
+import crypto from "node:crypto";
+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 ?? []);
+    assertStructuralFieldsUnchanged(payload, redactedPayload);
+    if (gate === "decompose_proposal") {
+        validatePostRedaction(() => validateDecomposeProposalJson(asRecord(redactedPayload["proposal_json"] ?? redactedPayload["decomposition_json"], "proposal_json")));
+    }
+    const root = artifactRootFor(config.worktreePath, config.workItemId);
+    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 publishArtifactBundleAtomic(root, [
+        { fileName: path.basename(reportPath), content: report },
+        { fileName: path.basename(artifactPath), content: verdictJson }
+    ], path.basename(artifactPath));
+    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 ?? []);
+    assertStructuralFieldsUnchanged(payload, redactedPayload);
+    if (gate === "draft_proposal") {
+        validatePostRedaction(() => validateDraftProposalJson(asRecord(redactedPayload["draft_json"], "draft_json")));
+    }
+    const root = artifactRootFor(config.worktreePath, config.workItemId);
+    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 publishArtifactBundleAtomic(root, [
+        { fileName: path.basename(reportPath), content: report },
+        { fileName: path.basename(artifactPath), content: verdictJson }
+    ], path.basename(artifactPath));
+    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 ?? []);
+    assertStructuralFieldsUnchanged(validationPayload, redactedPayload);
+    validatePostRedaction(() => {
+        validatePayloadShape(phase, redactedPayload);
+        validateOptionalWorkItemId(redactedPayload, config.workItemId);
+    });
+    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 publishArtifactBundleAtomic(path.dirname(artifactPath), [
+        { fileName: path.basename(reportPath), content: report },
+        { fileName: path.basename(artifactPath), content: artifactJson }
+    ], path.basename(artifactPath));
+    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 publishArtifactBundleAtomic(artifactRoot, [
+        { fileName: path.basename(implementationPlanPath), content: jsonText(implementationPlan) },
+        { fileName: path.basename(qaPlanPath), content: jsonText(qaPlan) },
+        { fileName: path.basename(reportPath), content: `${report.trim()}\n` },
+        { fileName: path.basename(verdictPath), content: jsonText(verdict) }
+    ], path.basename(verdictPath));
+    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 ?? []);
+    assertStructuralFieldsUnchanged(payload, redactedPayload);
+    validatePostRedaction(() => {
+        validateQaGatePayloadShape(gate, redactedPayload, status);
+        validateOptionalWorkItemId(redactedPayload, config.workItemId);
+    });
+    if (gate === "qa_manual_web") {
+        await validateQaSidecarReferences(config.worktreePath, config.workItemId, qaArray(redactedPayload, "sidecars", qaEvidenceSource(redactedPayload)), ownerFields.owner_type, ownerFields.owner_id).catch((error) => {
+            throw postRedactionValidationError(error);
+        });
+    }
+    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 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 publishArtifactBundleAtomic(artifactRoot, [
+        { fileName: path.basename(planPath), content: planJson },
+        { fileName: path.basename(evidencePath), content: evidenceJson },
+        { fileName: path.basename(findingsPath), content: findingsJson },
+        { fileName: path.basename(reportPath), content: finalReport },
+        { fileName: path.basename(verdictPath), content: verdictJson }
+    ], path.basename(verdictPath));
+    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 = [];
+    const validatedByPath = new Map();
+    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.`);
+        }
+        const canonicalPath = path.relative(worktreePath, fullPath).split(path.sep).join("/");
+        const duplicateKey = canonicalPath.toLowerCase();
+        const existing = validatedByPath.get(duplicateKey);
+        if (existing) {
+            if (existing.contentHash !== actualHash || existing.bytes !== stat.size) {
+                throw new Error(`sidecars[${index}] conflicts with another payload for ${canonicalPath}.`);
+            }
+            continue;
+        }
+        validatedByPath.set(duplicateKey, { contentHash: actualHash, bytes: stat.size });
+        validated.push({
+            ...record,
+            path: canonicalPath,
+            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
+    };
+}
+/**
+ * Stages a complete phase bundle outside the live artifact directory, then
+ * publishes its canonical verdict/marker last. Consumers treat the marker as
+ * the bundle's commit point, so they can observe either the old complete bundle
+ * or the new complete bundle, never a partially written set. A failed or
+ * cancelled publication rolls every touched file back before rejecting.
+ */
+export async function publishArtifactBundleAtomic(artifactRoot, files, commitFileName, options = {}) {
+    validateArtifactBundleFiles(files, commitFileName);
+    throwIfPublicationCancelled(options.signal);
+    const parent = path.dirname(artifactRoot);
+    const transactionId = `${process.pid}.${crypto.randomUUID()}`;
+    const stagingRoot = path.join(parent, `.${path.basename(artifactRoot)}.${transactionId}.publish`);
+    const backupRoot = path.join(stagingRoot, ".previous");
+    const orderedFiles = [
+        ...files.filter((file) => file.fileName !== commitFileName),
+        files.find((file) => file.fileName === commitFileName)
+    ];
+    const backedUp = new Set();
+    const published = new Set();
+    try {
+        await fs.mkdir(parent, { recursive: true });
+        await fs.mkdir(stagingRoot, { recursive: false });
+        for (const file of orderedFiles) {
+            throwIfPublicationCancelled(options.signal);
+            const handle = await fs.open(path.join(stagingRoot, file.fileName), "wx");
+            try {
+                await handle.writeFile(file.content, { encoding: "utf8", signal: options.signal });
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        throwIfPublicationCancelled(options.signal);
+        await fs.mkdir(artifactRoot, { recursive: true });
+        await fs.mkdir(backupRoot, { recursive: true });
+        // Hide the previous commit marker before changing any supporting file.
+        for (const fileName of [commitFileName, ...orderedFiles.map((file) => file.fileName).filter((name) => name !== commitFileName)]) {
+            const livePath = path.join(artifactRoot, fileName);
+            try {
+                await fs.rename(livePath, path.join(backupRoot, fileName));
+                backedUp.add(fileName);
+            }
+            catch (error) {
+                if (!isNodeError(error) || error.code !== "ENOENT") {
+                    throw error;
+                }
+            }
+        }
+        for (const [index, file] of orderedFiles.entries()) {
+            throwIfPublicationCancelled(options.signal);
+            await options.beforePublishFile?.(file.fileName, index);
+            await fs.rename(path.join(stagingRoot, file.fileName), path.join(artifactRoot, file.fileName));
+            published.add(file.fileName);
+        }
+    }
+    catch (error) {
+        const rollbackErrors = [];
+        for (const file of [...orderedFiles].reverse()) {
+            if (!published.has(file.fileName))
+                continue;
+            await fs.rm(path.join(artifactRoot, file.fileName), { force: true }).catch(() => {
+                rollbackErrors.push(file.fileName);
+            });
+        }
+        // Restore the previous marker last for the same observable commit boundary.
+        const restoreOrder = [
+            ...orderedFiles.filter((file) => file.fileName !== commitFileName),
+            orderedFiles.find((file) => file.fileName === commitFileName)
+        ];
+        for (const file of restoreOrder) {
+            if (!backedUp.has(file.fileName))
+                continue;
+            await fs.rename(path.join(backupRoot, file.fileName), path.join(artifactRoot, file.fileName)).catch(() => {
+                rollbackErrors.push(file.fileName);
+            });
+        }
+        if (rollbackErrors.length === 0
+            && error instanceof Error
+            && error.message.startsWith("artifact_atomic_publish_cancelled:")) {
+            throw error;
+        }
+        const suffix = rollbackErrors.length > 0 ? " Rollback did not restore every bundle file." : "";
+        throw new Error(`artifact_atomic_publish_failure: completion artifact bundle was not published.${suffix}`, { cause: error });
+    }
+    finally {
+        await fs.rm(stagingRoot, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+function validateArtifactBundleFiles(files, commitFileName) {
+    if (files.length === 0 || !files.some((file) => file.fileName === commitFileName)) {
+        throw new Error("artifact_atomic_publish_failure: bundle commit file is missing.");
+    }
+    const names = new Set();
+    for (const file of files) {
+        if (!file.fileName || path.basename(file.fileName) !== file.fileName || names.has(file.fileName)) {
+            throw new Error("artifact_atomic_publish_failure: bundle file names must be unique safe base names.");
+        }
+        names.add(file.fileName);
+    }
+}
+function throwIfPublicationCancelled(signal) {
+    if (signal?.aborted) {
+        throw new Error("artifact_atomic_publish_cancelled: completion artifact bundle publication was cancelled.");
+    }
+}
+function validatePostRedaction(validate) {
+    try {
+        validate();
+    }
+    catch (error) {
+        throw postRedactionValidationError(error);
+    }
+}
+function postRedactionValidationError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return new Error(`artifact_post_redaction_validation_failed: ${message}`, { cause: error });
+}
+function assertStructuralFieldsUnchanged(original, redacted) {
+    if (structuralFieldFingerprint(original) !== structuralFieldFingerprint(redacted)) {
+        // This stable code is intentionally safe for telemetry: it does not include
+        // the structural value or any candidate secret.
+        throw new Error("artifact_redaction_changed_structural_field: redaction changed a structural identifier; the bundle was not published.");
+    }
+}
+function structuralFieldFingerprint(value, key = "", result = []) {
+    if (Array.isArray(value)) {
+        if (isStructuralFieldKey(key) && value.every((item) => item === null || typeof item !== "object")) {
+            result.push(stableStringify(value));
+        }
+        else {
+            for (const item of value)
+                structuralFieldFingerprint(item, key, result);
+        }
+        return result.join("\n");
+    }
+    if (!value || typeof value !== "object") {
+        if (isStructuralFieldKey(key))
+            result.push(stableStringify(value));
+        return result.join("\n");
+    }
+    for (const [childKey, child] of Object.entries(value)) {
+        if (isStructuralFieldKey(childKey)) {
+            result.push(`${childKey}:${stableStringify(child)}`);
+        }
+        else {
+            structuralFieldFingerprint(child, childKey, result);
+        }
+    }
+    return result.join("\n");
+}
+function isStructuralFieldKey(key) {
+    return key === "id"
+        || key === "before"
+        || key === "after"
+        || key === "from"
+        || key === "to"
+        || key === "tasks"
+        || key === "phases"
+        || /(?:^|_)(?:id|ids)$/i.test(key)
+        || /(?:Id|Ids)$/.test(key);
+}