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

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

@@ -0,0 +1,918 @@
+import { qaBlockerReasons, qaCandidateBugActions, qaFindingScopes, qaFindingSeverities, qaGateToolNames, qaScopeAuthorities, qaScopeCapabilities, qaScopeConfidence, qaScopeEvidence, qaScopeFields, qaScopeSources, qaScopeSurfaces } from "./phase-completion.js";
+export 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;
+    }
+    if (phase === "architect") {
+        const canonical = normalized === "needsrevision" ? "needs_revision" : normalized;
+        if (canonical !== "pass" && canonical !== "needs_revision" && canonical !== "blocked") {
+            throw new Error("Architect status must be pass, needs_revision, or blocked.");
+        }
+        return canonical;
+    }
+    const canonical = normalized === "blocked" || normalized === "needsrework"
+        ? "needs_rework"
+        : normalized === "failed"
+            ? "fail"
+            : normalized;
+    if (canonical !== "pass" && canonical !== "fail" && canonical !== "needs_rework") {
+        throw new Error("status must be pass, fail, or needs_rework.");
+    }
+    return canonical;
+}
+export function normalizeQaGateStatus(value) {
+    const normalized = value.trim().toLowerCase().replace(/-/g, "_");
+    if (normalized !== "pass" && normalized !== "skipped" && normalized !== "blocked") {
+        throw new Error("QA gate status must be pass, skipped, or blocked.");
+    }
+    return normalized;
+}
+export function validatePayloadShape(phase, payload) {
+    const status = normalizeCompletionStatus(requiredString(payload, "status"), phase);
+    if (!status) {
+        throw new Error("status is required.");
+    }
+    requireField(payload, "summary");
+    if (phase === "qa") {
+        validateQaPayloadShape(payload, status);
+        return;
+    }
+    if (phase === "architect") {
+        validateArchitectPayloadShape(payload, status);
+        return;
+    }
+    const pass = status === "pass";
+    if (!pass) {
+        requireNonPassEvidence(payload);
+        return;
+    }
+    if (phase === "ci_repair") {
+        validateCiRepairPayloadShape(payload);
+        return;
+    }
+    if (phase === "comment_repair") {
+        validateCommentRepairPayloadShape(payload);
+        return;
+    }
+    if (isDebugCompletionPhase(phase)) {
+        validateDebugPayloadShape(phase, payload);
+        return;
+    }
+    if (phase === "implementation") {
+        requireArray(payload, "plan");
+        requireArray(payload, "changed_files");
+        requireArray(payload, "tests_added_or_updated");
+        requireArray(payload, "docs_added_or_updated");
+        requireArray(payload, "acceptance_criteria");
+        requireArray(payload, "known_gaps");
+        requireField(payload, "next_phase_context");
+        requireImplementationEvidence(payload);
+        requireSatisfiedAcceptanceCriteria(payload);
+        validateResolvedFindings(payload);
+        return;
+    }
+    if (phase === "self_review") {
+        requireBoolean(payload, "reviewed_diff");
+        requireArray(payload, "findings");
+        requireObject(payload, "security_review");
+        requireObject(payload, "edge_case_review");
+        requireObject(payload, "design_review");
+        requireObject(payload, "deterministic_comparison");
+        requireArray(payload, "fixes_applied");
+        requireArray(payload, "remaining_risks");
+        return;
+    }
+    requireArray(payload, "commands");
+    requireArray(payload, "acceptance_criteria");
+    requireField(payload, "build_status");
+    requireField(payload, "test_status");
+    requireField(payload, "lint_status");
+    requireField(payload, "design_status");
+    requireAllowedStatus(payload, "build_status", ["pass"]);
+    requireAllowedStatus(payload, "test_status", ["pass"]);
+    requireAllowedStatus(payload, "lint_status", ["pass", "not_applicable"]);
+    requireAllowedStatus(payload, "design_status", ["pass", "not_applicable"]);
+    requireArray(payload, "drift_checks");
+    requireBoolean(payload, "ready_for_dev_test");
+    if (payload.ready_for_dev_test !== true) {
+        throw new Error("validation pass requires ready_for_dev_test: true.");
+    }
+    requirePassingCommands(payload);
+    requireSatisfiedAcceptanceCriteria(payload);
+}
+export function validateCommentRepairPayloadShape(payload) {
+    requireNonEmptyStringRecord(payload, "repair_head_sha", "");
+    requireNonEmptyStringRecord(payload, "repair_issue_key", "");
+    requireArray(payload, "dispositions");
+    requireNonEmptyArray(payload, "dispositions");
+    const seen = new Set();
+    let hasFixed = false;
+    for (const [index, entry] of payload.dispositions.entries()) {
+        requireEvidenceRecord(entry, `dispositions[${index}]`);
+        const record = entry;
+        for (const key of ["claim_id", "kind", "body_sha256", "disposition", "evidence"]) {
+            requireNonEmptyStringRecord(record, key, `dispositions[${index}].`);
+        }
+        requireKnownStringRecord(record, "kind", new Set(["review_thread", "review_body", "issue_comment"]), `dispositions[${index}].`);
+        requireKnownStringRecord(record, "disposition", new Set(["fixed", "rejected", "already_addressed", "needs_decision", "accepted_transfer", "owned_elsewhere"]), `dispositions[${index}].`);
+        if (record.disposition === "owned_elsewhere") {
+            const receipt = record.owned_elsewhere;
+            if (!receipt || typeof receipt !== "object" || Array.isArray(receipt))
+                throw new Error("owned_elsewhere requires the owning Story and its quoted obligation; server verification remains mandatory.");
+            const owner = receipt;
+            if (typeof owner.target_work_item_id !== "string" || !owner.target_work_item_id.trim())
+                throw new Error("owned_elsewhere.target_work_item_id is required.");
+            if (typeof owner.quoted_obligation !== "string" || owner.quoted_obligation.trim().length < 40)
+                throw new Error("owned_elsewhere.quoted_obligation must quote at least 40 characters of the owning Story's acceptance criteria.");
+        }
+        if (record.disposition === "accepted_transfer") {
+            const receipt = record.accepted_transfer;
+            if (!receipt || typeof receipt !== "object" || Array.isArray(receipt))
+                throw new Error("accepted_transfer requires an approved amendment receipt; server verification remains mandatory.");
+            const transfer = receipt;
+            for (const key of ["amendment_id", "content_hash", "target_work_item_id", "obligation_reference"]) {
+                if (typeof transfer[key] !== "string" || !transfer[key].trim())
+                    throw new Error(`accepted_transfer.${key} is required.`);
+            }
+            if (!Number.isInteger(transfer.version) || Number(transfer.version) < 1)
+                throw new Error("accepted_transfer.version must be positive.");
+        }
+        const identity = `${normalizedString(optionalString(record, "kind"))}:${optionalString(record, "claim_id")}:${normalizedString(optionalString(record, "body_sha256"))}`;
+        if (seen.has(identity))
+            throw new Error(`dispositions[${index}] duplicates finding ${identity}.`);
+        seen.add(identity);
+        hasFixed ||= normalizedString(optionalString(record, "disposition")) === "fixed";
+    }
+    requireArray(payload, "changed_files");
+    requireArray(payload, "validation");
+    for (const [index, changedFile] of payload.changed_files.entries()) {
+        requireEvidenceRecord(changedFile, `changed_files[${index}]`);
+        const record = changedFile;
+        requireNonEmptyStringRecord(record, "path", `changed_files[${index}].`);
+        requireNonEmptyStringRecord(record, "summary", `changed_files[${index}].`);
+    }
+    if (hasFixed && arrayLength(payload, "changed_files") === 0) {
+        throw new Error("fixed comment dispositions require changed_files evidence.");
+    }
+    if (arrayLength(payload, "changed_files") > 0) {
+        requireNonEmptyArray(payload, "validation");
+        validateQaGatePassingCommands(payload.validation);
+    }
+}
+export function validateCiRepairPayloadShape(payload) {
+    requireArray(payload, "failed_checks");
+    requireNonEmptyArray(payload, "failed_checks");
+    for (const [index, failedCheck] of payload.failed_checks.entries()) {
+        requireEvidenceRecord(failedCheck, `failed_checks[${index}]`);
+        const record = failedCheck;
+        requireNonEmptyStringRecord(record, "name", `failed_checks[${index}].`);
+        requireNonEmptyStringRecord(record, "provider_state", `failed_checks[${index}].`);
+    }
+    requireObject(payload, "root_cause");
+    const rootCause = requiredRecord(payload, "root_cause");
+    requireNonEmptyStringRecord(rootCause, "classification", "root_cause.");
+    requireNonEmptyStringRecord(rootCause, "summary", "root_cause.");
+    requireNonEmptyStringArrayRecord(rootCause, "evidence", "root_cause.");
+    requireArray(payload, "changed_files");
+    if (arrayLength(payload, "changed_files") === 0) {
+        requireObject(payload, "no_code_action");
+        const noCodeAction = requiredRecord(payload, "no_code_action");
+        requireNonEmptyStringRecord(noCodeAction, "action", "no_code_action.");
+        requireNonEmptyStringRecord(noCodeAction, "reason", "no_code_action.");
+    }
+    else {
+        for (const [index, changedFile] of payload.changed_files.entries()) {
+            requireEvidenceRecord(changedFile, `changed_files[${index}]`);
+            const record = changedFile;
+            requireNonEmptyStringRecord(record, "path", `changed_files[${index}].`);
+            requireNonEmptyStringRecord(record, "summary", `changed_files[${index}].`);
+        }
+    }
+    for (const key of ["narrow_validation", "broader_validation"]) {
+        requireArray(payload, key);
+        requireNonEmptyArray(payload, key);
+        validateQaGatePassingCommands(payload[key]);
+    }
+    requireArray(payload, "workflow_validation");
+    requireNonEmptyArray(payload, "workflow_validation");
+    for (const [index, entry] of payload.workflow_validation.entries()) {
+        requireEvidenceRecord(entry, `workflow_validation[${index}]`);
+        const record = entry;
+        requireNonEmptyStringRecord(record, "step", `workflow_validation[${index}].`);
+        requireKnownStringRecord(record, "equivalence", new Set(["supported", "substitute", "provider_only"]), `workflow_validation[${index}].`);
+        requireNonEmptyStringRecord(record, "status", `workflow_validation[${index}].`);
+        const equivalence = normalizedString(optionalString(record, "equivalence"));
+        if (equivalence === "provider_only") {
+            requireNonEmptyStringRecord(record, "reason", `workflow_validation[${index}].`);
+            continue;
+        }
+        requireNonEmptyStringRecord(record, "command", `workflow_validation[${index}].`);
+        requireNonEmptyStringRecord(record, "summary", `workflow_validation[${index}].`);
+        if (typeof record.exit_code !== "number" || !Number.isFinite(record.exit_code)) {
+            throw new Error(`workflow_validation[${index}].exit_code is required for ${equivalence} evidence.`);
+        }
+        if (record.exit_code !== 0 || normalizedString(optionalString(record, "status")) !== "pass") {
+            throw new Error(`workflow_validation[${index}] must pass locally when equivalence is ${equivalence}.`);
+        }
+        if (equivalence === "substitute") {
+            requireNonEmptyStringRecord(record, "substitute", `workflow_validation[${index}].`);
+        }
+    }
+    requireArray(payload, "remaining_risks");
+    requireAllowedStatus(payload, "provider_state", ["ready_for_rerun", "rerun_requested", "checks_pending"]);
+    requireBoolean(payload, "ready_for_push");
+    if (payload.ready_for_push !== true) {
+        throw new Error("ci_repair pass requires ready_for_push: true.");
+    }
+}
+export function validateDebugPayloadShape(phase, payload) {
+    if (phase === "debug_repro") {
+        requireArray(payload, "repro_steps");
+        requireField(payload, "observed");
+        requireField(payload, "expected");
+        requireArray(payload, "evidence");
+        requireNonEmptyArray(payload, "repro_steps");
+        requireNonEmptyArray(payload, "evidence");
+        return;
+    }
+    if (phase === "debug_root_cause") {
+        requireField(payload, "root_cause");
+        requireArray(payload, "evidence");
+        requireArray(payload, "eliminated_alternatives");
+        requireField(payload, "risk_area");
+        requireNonEmptyArray(payload, "evidence");
+        return;
+    }
+    if (phase === "debug_fix") {
+        requireArray(payload, "changed_files");
+        requireArray(payload, "tests_added_or_updated");
+        requireArray(payload, "remaining_risks");
+        requireNonEmptyArray(payload, "changed_files");
+        if (arrayLength(payload, "tests_added_or_updated") === 0 && arrayLength(payload, "remaining_risks") === 0) {
+            throw new Error("tests_added_or_updated is empty; remaining_risks must explain why no regression coverage changed.");
+        }
+        validateResolvedFindings(payload);
+        return;
+    }
+    requireArray(payload, "commands");
+    requireArray(payload, "required_regressions");
+    requireField(payload, "build_status");
+    requireField(payload, "test_status");
+    requireBoolean(payload, "repro_negative");
+    requireBoolean(payload, "qa_ready");
+    if (payload.repro_negative !== true) {
+        throw new Error("debug_regression pass requires repro_negative: true.");
+    }
+    if (payload.qa_ready !== true) {
+        throw new Error("debug_regression pass requires qa_ready: true.");
+    }
+    requireAllowedStatus(payload, "build_status", ["pass", "not_applicable"]);
+    requireAllowedStatus(payload, "test_status", ["pass", "not_applicable"]);
+    requireNonEmptyArray(payload, "required_regressions");
+    requirePassingCommands(payload);
+}
+export function validateQaGatePayloadShape(gate, payload, status) {
+    requireField(payload, "summary");
+    if (status === "skipped") {
+        requireField(payload, "reason");
+    }
+    if (status === "blocked") {
+        const reason = normalizedString(optionalString(payload, "blocker_reason"));
+        if (!qaBlockerReasons.has(reason)) {
+            throw new Error("QA gate blocked requires blocker_reason to be one of missing_app_launch_target, inconclusive, environment_failure, missing_validation_evidence, missing_worktree, or runner_failure.");
+        }
+    }
+    if (gate === "qa_plan" && status === "pass") {
+        const checklist = qaStringArray(payload, "checklist");
+        if (checklist.length === 0) {
+            throw new Error("complete_qa_plan pass requires checklist with at least one entry.");
+        }
+    }
+    if (gate === "qa_findings" && status !== "blocked") {
+        qaObjectArray(payload, "findings");
+        qaObjectArray(payload, "candidate_bugs");
+    }
+    if ((gate === "qa_regression" || gate === "qa_api") && status === "pass") {
+        const commands = qaArray(payload, "commands");
+        if (commands.length === 0) {
+            throw new Error(`${qaGateToolNames[gate]} pass requires commands with at least one entry.`);
+        }
+        validateQaGatePassingCommands(commands, {
+            allowClassifiedNonBlockingFailures: gate === "qa_regression"
+        });
+    }
+    if (gate === "qa_manual_web" && status === "pass") {
+        const browserChecks = qaArray(payload, "browser_checks");
+        const notes = optionalString(payload, "notes");
+        if (browserChecks.length === 0 && !notes) {
+            throw new Error(`${qaGateToolNames[gate]} pass requires browser_checks or notes.`);
+        }
+    }
+}
+export function validateQaGatePassingCommands(commands, options = {}) {
+    const issues = [];
+    for (const [index, command] of commands.entries()) {
+        if (!command || typeof command !== "object" || Array.isArray(command)) {
+            issues.push(`commands[${index}] must be an object.`);
+            continue;
+        }
+        const record = command;
+        if (!optionalString(record, "command"))
+            issues.push(`commands[${index}].command is required.`);
+        if (!optionalString(record, "status"))
+            issues.push(`commands[${index}].status is required.`);
+        if (!optionalString(record, "summary"))
+            issues.push(`commands[${index}].summary is required.`);
+        if (typeof record.exit_code !== "number" || !Number.isFinite(record.exit_code)) {
+            issues.push(`commands[${index}].exit_code is required.`);
+            continue;
+        }
+        const passed = record.exit_code === 0 && normalizedString(record.status) === "pass";
+        if (!passed
+            && options.allowClassifiedNonBlockingFailures
+            && optionalString(record, "classification")) {
+            try {
+                validateClassifiedNonBlockingQaFailure(record, index);
+            }
+            catch (error) {
+                issues.push(error instanceof Error ? error.message : String(error));
+            }
+            continue;
+        }
+        if (record.exit_code !== 0) {
+            issues.push(`commands[${index}].exit_code must be 0 when QA gate status is pass.`);
+        }
+        if (normalizedString(record.status) !== "pass") {
+            issues.push(`commands[${index}].status must be pass when QA gate status is pass.`);
+        }
+    }
+    throwCompletionPayloadIssues(issues);
+}
+function validateClassifiedNonBlockingQaFailure(record, index) {
+    const classification = normalizedString(optionalString(record, "classification"));
+    if (classification !== "out_of_scope_failure" && classification !== "baseline_failure") {
+        throw new Error(`commands[${index}] is non-passing; QA regression pass requires classification out_of_scope_failure or baseline_failure with corroborating evidence.`);
+    }
+    requireNonEmptyStringRecord(record, "candidate_bug_id", `commands[${index}].`);
+    requireNonEmptyStringRecord(record, "scope_evidence", `commands[${index}].`);
+    if (record.acceptance_criteria_independent !== true) {
+        throw new Error(`commands[${index}].acceptance_criteria_independent must be true for a non-blocking QA regression failure.`);
+    }
+    if (classification === "out_of_scope_failure") {
+        requireNonEmptyStringRecord(record, "repro_command", `commands[${index}].`);
+        if (typeof record.repro_exit_code !== "number" || !Number.isFinite(record.repro_exit_code) || record.repro_exit_code === 0) {
+            throw new Error(`commands[${index}].repro_exit_code must be a non-zero number for an out-of-scope failure.`);
+        }
+        return;
+    }
+    requireNonEmptyStringRecord(record, "baseline_ref", `commands[${index}].`);
+    if (typeof record.baseline_exit_code !== "number" || !Number.isFinite(record.baseline_exit_code) || record.baseline_exit_code === 0) {
+        throw new Error(`commands[${index}].baseline_exit_code must be a non-zero number for a baseline failure.`);
+    }
+    if (record.failure_signature_match !== true) {
+        throw new Error(`commands[${index}].failure_signature_match must be true for a baseline failure.`);
+    }
+}
+export function validateArchitectPayloadShape(payload, status) {
+    if (status !== "pass") {
+        requireArchitectNonPassEvidence(payload);
+        return;
+    }
+    const implementationPlan = requiredRecord(payload, "implementation_plan");
+    const qaPlan = requiredRecord(payload, "qa_plan");
+    requireNumericOne(implementationPlan, "schema_version", "implementation_plan.schema_version");
+    requireNonEmptyStringRecord(implementationPlan, "plan_id", "implementation_plan.");
+    requireArchitectArray(implementationPlan, "phases", payload);
+    requireArchitectArray(implementationPlan, "tasks", payload);
+    requireArchitectArray(implementationPlan, "dependencies", payload, { allowEmpty: true });
+    requireArchitectArray(implementationPlan, "phase_gates", payload);
+    if (arrayLength(implementationPlan, "tasks") === 0) {
+        throw new Error("implementation_plan.tasks: expected non-empty array; correction: include at least one task with id and tests.");
+    }
+    const taskIds = new Set();
+    const taskIndexById = new Map();
+    for (const [taskIndex, task] of implementationPlan.tasks.entries()) {
+        if (!task || typeof task !== "object" || Array.isArray(task)) {
+            throw new Error("implementation_plan.tasks[]: expected object entries; correction: each task must be an object with id and tests.");
+        }
+        const taskRecord = task;
+        requireNonEmptyStringRecord(taskRecord, "id", "implementation_plan.tasks[].");
+        const taskId = optionalString(taskRecord, "id") ?? "";
+        const firstTaskIndex = taskIndexById.get(taskId);
+        if (firstTaskIndex !== undefined) {
+            throw new Error(`implementation_plan.tasks[${taskIndex}].id duplicates implementation_plan.tasks[${firstTaskIndex}].id '${taskId}'; correction: assign the duplicate a unique stable task id, update every phase/dependency reference to that task, and resubmit forge.complete_architect_plan.`);
+        }
+        taskIds.add(taskId);
+        taskIndexById.set(taskId, taskIndex);
+        validateArchitectTaskDevelopScope(taskRecord, taskId);
+        requireNonEmptyStringArrayRecord(taskRecord, "acceptance_criteria", `implementation_plan.tasks[${taskId}].`);
+        validateArchitectVerificationScope(taskRecord, taskId);
+        requireArchitectArray(taskRecord, "tests", payload, { path: `implementation_plan.tasks[${optionalString(taskRecord, "id") ?? "?"}].tests` });
+        if (arrayLength(taskRecord, "tests") === 0) {
+            throw new Error(`implementation_plan.tasks[${optionalString(taskRecord, "id") ?? "?"}].tests: expected non-empty array; correction: include task-specific verification.`);
+        }
+    }
+    validateAndNormalizeArchitectDependencies(implementationPlan, taskIds);
+    requireNumericOne(qaPlan, "schema_version", "qa_plan.schema_version");
+    requireArchitectArray(qaPlan, "final_qa", payload, { path: "qa_plan.final_qa" });
+    if (arrayLength(qaPlan, "final_qa") === 0) {
+        throw new Error("qa_plan.final_qa: expected non-empty array; correction: include final QA coverage for the completed plan.");
+    }
+}
+export function validateArchitectTaskDevelopScope(task, taskId) {
+    const explicitScope = firstOptionalString(task, ["execution_scope", "scope", "task_scope", "task_type", "lane", "kind", "type"]);
+    if (isStoryQaScope(explicitScope)) {
+        throw new Error(`implementation_plan.tasks[${taskId}]: story QA/sign-off work must not be materialized as a Develop child task; correction: move this coverage to qa_plan.final_qa and keep implementation_plan.tasks limited to repo/product changes.`);
+    }
+    if (looksLikeStoryLevelVerificationTask(architectTaskScopeText(task))) {
+        throw new Error(`implementation_plan.tasks[${taskId}]: parent-story materialization or sign-off verification belongs in qa_plan.final_qa, not implementation_plan.tasks; correction: keep child tasks focused on implementation work and put child-count/parent-plan artifact checks in final QA coverage.`);
+    }
+}
+export function validateArchitectVerificationScope(task, taskId) {
+    const value = task.verification_scope;
+    if (value === undefined || value === null) {
+        return;
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`implementation_plan.tasks[${taskId}].verification_scope: expected object when present.`);
+    }
+    validateQaScopeRecord(value, `implementation_plan.tasks[${taskId}].verification_scope`);
+}
+export function validateQaScopeRecord(scope, pathLabel) {
+    for (const key of Object.keys(scope)) {
+        if (!qaScopeFields.has(key)) {
+            throw new Error(`${pathLabel}.${key}: unsupported QA scope field.`);
+        }
+    }
+    if (scope.schema_version !== 1) {
+        throw new Error(`${pathLabel}.schema_version must be numeric 1.`);
+    }
+    const surface = qaScopeStringArray(scope, "surface", pathLabel, qaScopeSurfaces);
+    const requiredEvidence = qaScopeStringArray(scope, "required_evidence", pathLabel, qaScopeEvidence);
+    qaScopeStringArray(scope, "required_capabilities", pathLabel, qaScopeCapabilities);
+    const notApplicable = qaScopeStringArray(scope, "not_applicable", pathLabel, qaScopeEvidence);
+    const requiredSet = new Set(requiredEvidence);
+    for (const evidence of notApplicable) {
+        if (requiredSet.has(evidence)) {
+            throw new Error(`${pathLabel}: '${evidence}' cannot be both required and not applicable.`);
+        }
+    }
+    const browserRequired = requiredSet.has("browser_manual");
+    const apiRequired = requiredSet.has("api_http");
+    validateOptionalBoolean(scope, "browser_required", pathLabel, browserRequired);
+    validateOptionalBoolean(scope, "api_required", pathLabel, apiRequired);
+    validateOptionalBoolean(scope, "confirmed_by_user", pathLabel);
+    validateOptionalBoolean(scope, "locked", pathLabel);
+    if (surface.includes("ui_browser") && !browserRequired) {
+        throw new Error(`${pathLabel}.surface ui_browser requires browser_manual evidence.`);
+    }
+    if (surface.includes("api_route") && !apiRequired) {
+        throw new Error(`${pathLabel}.surface api_route requires api_http evidence.`);
+    }
+    validateOptionalKnownString(scope, "source", pathLabel, qaScopeSources);
+    validateOptionalKnownString(scope, "authority", pathLabel, qaScopeAuthorities);
+    validateOptionalKnownString(scope, "confidence", pathLabel, qaScopeConfidence);
+    if (scope.rationale !== undefined && scope.rationale !== null && typeof scope.rationale !== "string") {
+        throw new Error(`${pathLabel}.rationale must be a string.`);
+    }
+    validateOptionalQaScopeDerivedFrom(scope, pathLabel);
+}
+export function qaScopeStringArray(scope, key, pathLabel, allowed) {
+    const value = scope[key];
+    if (value === undefined || value === null) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new Error(`${pathLabel}.${key} must be an array.`);
+    }
+    const normalized = [];
+    for (const [index, entry] of value.entries()) {
+        if (typeof entry !== "string" || entry.trim().length === 0) {
+            throw new Error(`${pathLabel}.${key}[${index}] must be a non-empty string.`);
+        }
+        const candidate = entry.trim().toLowerCase();
+        if (!allowed.has(candidate)) {
+            throw new Error(`${pathLabel}.${key}[${index}] value '${candidate}' is unsupported.`);
+        }
+        if (!normalized.includes(candidate)) {
+            normalized.push(candidate);
+        }
+    }
+    return normalized;
+}
+export function validateOptionalBoolean(scope, key, pathLabel, expected) {
+    const value = scope[key];
+    if (value === undefined || value === null) {
+        return;
+    }
+    if (typeof value !== "boolean") {
+        throw new Error(`${pathLabel}.${key} must be boolean.`);
+    }
+    if (expected !== undefined && value !== expected) {
+        throw new Error(`${pathLabel}.${key} must match required_evidence.`);
+    }
+}
+export function validateOptionalKnownString(scope, key, pathLabel, allowed) {
+    const value = scope[key];
+    if (value === undefined || value === null) {
+        return;
+    }
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`${pathLabel}.${key} must be a non-empty string.`);
+    }
+    const normalized = value.trim().toLowerCase();
+    if (!allowed.has(normalized)) {
+        throw new Error(`${pathLabel}.${key} value '${normalized}' is unsupported.`);
+    }
+}
+export function validateOptionalQaScopeDerivedFrom(scope, pathLabel) {
+    const value = scope.derived_from;
+    if (value === undefined || value === null) {
+        return;
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${pathLabel}.derived_from must be an object.`);
+    }
+    const derivedFrom = value;
+    for (const key of Object.keys(derivedFrom)) {
+        if (key !== "work_item_id" && key !== "mode") {
+            throw new Error(`${pathLabel}.derived_from.${key}: unsupported QA scope provenance field.`);
+        }
+    }
+    if (derivedFrom.work_item_id !== undefined && derivedFrom.work_item_id !== null && typeof derivedFrom.work_item_id !== "string") {
+        throw new Error(`${pathLabel}.derived_from.work_item_id must be a string.`);
+    }
+    if (derivedFrom.mode !== undefined && derivedFrom.mode !== null && typeof derivedFrom.mode !== "string") {
+        throw new Error(`${pathLabel}.derived_from.mode must be a string.`);
+    }
+}
+export function firstOptionalString(record, keys) {
+    for (const key of keys) {
+        const value = optionalString(record, key);
+        if (value) {
+            return value;
+        }
+    }
+    return null;
+}
+export function isStoryQaScope(value) {
+    if (!value) {
+        return false;
+    }
+    const normalized = value.trim().toLowerCase().replace(/[\s-]+/g, "_");
+    return [
+        "qa",
+        "story_qa",
+        "final_qa",
+        "sign_off",
+        "signoff",
+        "story_sign_off",
+        "story_verification",
+        "story_validation"
+    ].includes(normalized);
+}
+export function architectTaskScopeText(task) {
+    const parts = [];
+    for (const key of ["id", "title", "summary", "phase", "phase_id"]) {
+        appendOptionalString(parts, task, key);
+    }
+    for (const key of ["acceptance_criteria", "expected_paths", "touched_surfaces", "implementation_notes"]) {
+        appendOptionalStringArray(parts, task, key);
+    }
+    const tests = task.tests;
+    if (Array.isArray(tests)) {
+        for (const test of tests) {
+            if (!test || typeof test !== "object" || Array.isArray(test)) {
+                continue;
+            }
+            const record = test;
+            for (const key of ["id", "command", "purpose", "target", "expected"]) {
+                appendOptionalString(parts, record, key);
+            }
+            appendOptionalStringArray(parts, record, "steps");
+        }
+    }
+    return parts.join(" ");
+}
+export function appendOptionalString(parts, record, key) {
+    const value = optionalString(record, key);
+    if (value) {
+        parts.push(value);
+    }
+}
+export function appendOptionalStringArray(parts, record, key) {
+    const value = record[key];
+    if (!Array.isArray(value)) {
+        return;
+    }
+    for (const entry of value) {
+        if (typeof entry === "string" && entry.trim().length > 0) {
+            parts.push(entry.trim());
+        }
+    }
+}
+export function looksLikeStoryLevelVerificationTask(text) {
+    if (!text.trim()) {
+        return false;
+    }
+    const normalized = text.toLowerCase();
+    const verificationWords = [
+        "verify",
+        "verification",
+        "validate",
+        "validation",
+        "inspect",
+        "audit",
+        "check",
+        "confirm",
+        "prove",
+        "evidence",
+        "sign-off",
+        "sign off"
+    ];
+    if (!verificationWords.some((word) => normalized.includes(word))) {
+        return false;
+    }
+    return [
+        "materialization",
+        "materialized child",
+        "child inventory",
+        "child work-item",
+        "child work item",
+        "created task count",
+        "created_task_count",
+        "parent plan",
+        "parent story",
+        "story sign-off",
+        "story sign off",
+        ".forge/work-items",
+        ".forge\\work-items",
+        ".forge/stories",
+        ".forge\\stories",
+        "implementation.plan.json",
+        "qa.plan.json",
+        "architect plan artifact",
+        "child spec"
+    ].some((needle) => normalized.includes(needle));
+}
+export function validateAndNormalizeArchitectDependencies(implementationPlan, taskIds) {
+    const dependencies = implementationPlan.dependencies;
+    const edges = new Map();
+    for (const taskId of taskIds) {
+        edges.set(taskId, []);
+    }
+    const normalizedDependencies = [];
+    for (const [index, dependency] of dependencies.entries()) {
+        if (!dependency || typeof dependency !== "object" || Array.isArray(dependency)) {
+            throw new Error("implementation_plan.dependencies[]: expected object entries; correction: each dependency must be an object with before and after task ids.");
+        }
+        const record = dependency;
+        const before = architectDependencyEndpoint(record, index, "before", "from");
+        const after = architectDependencyEndpoint(record, index, "after", "to");
+        if (!taskIds.has(before) || !taskIds.has(after)) {
+            throw new Error("implementation_plan.dependencies: dependency references an unknown task id.");
+        }
+        const normalized = stripUndefined({
+            ...record,
+            before,
+            after,
+            from: undefined,
+            to: undefined
+        });
+        normalizedDependencies.push(normalized);
+        edges.get(before)?.push(after);
+    }
+    implementationPlan.dependencies = normalizedDependencies;
+    if (hasArchitectDependencyCycle(edges)) {
+        throw new Error("implementation_plan.dependencies: expected acyclic graph; correction: remove or revise cyclic task dependencies.");
+    }
+}
+export function architectDependencyEndpoint(dependency, index, canonicalKey, aliasKey) {
+    const canonical = optionalString(dependency, canonicalKey);
+    const alias = optionalString(dependency, aliasKey);
+    if (canonical && alias && canonical !== alias) {
+        throw new Error(`implementation_plan.dependencies[${index}].${canonicalKey}: conflicts with ${aliasKey}; correction: use one task id for ${canonicalKey}.`);
+    }
+    const value = canonical ?? alias;
+    if (!value) {
+        throw new Error(`implementation_plan.dependencies[${index}].${canonicalKey}: expected string; correction: use before and after task ids for each dependency.`);
+    }
+    return value;
+}
+export function hasArchitectDependencyCycle(edges) {
+    const visiting = new Set();
+    const visited = new Set();
+    const visit = (node) => {
+        if (visited.has(node)) {
+            return false;
+        }
+        if (visiting.has(node)) {
+            return true;
+        }
+        visiting.add(node);
+        for (const next of edges.get(node) ?? []) {
+            if (visit(next)) {
+                return true;
+            }
+        }
+        visiting.delete(node);
+        visited.add(node);
+        return false;
+    };
+    for (const node of edges.keys()) {
+        if (visit(node)) {
+            return true;
+        }
+    }
+    return false;
+}
+export function requireArchitectNonPassEvidence(payload) {
+    const evidenceKeys = ["blockers", "revision_questions", "revision_reasons", "known_gaps", "findings", "remaining_risks", "failures"];
+    const hasEvidence = evidenceKeys.some((key) => {
+        const value = payload[key];
+        if (typeof value === "string") {
+            return value.trim().length > 0;
+        }
+        if (Array.isArray(value)) {
+            return value.length > 0;
+        }
+        return Boolean(value && typeof value === "object");
+    });
+    if (!hasEvidence) {
+        throw new Error("status: non-pass Architect completion requires blockers, revision_questions, revision_reasons, findings, failures, or known_gaps; correction: explain why the plan cannot pass.");
+    }
+}
+export function requireArchitectArray(source, key, rootPayload, options = {}) {
+    const pathLabel = options.path ?? `implementation_plan.${key}`;
+    if (!Array.isArray(source[key])) {
+        const nestedHint = architectNestedArrayHint(rootPayload, key);
+        throw new Error(`${pathLabel}: expected array${key === "phases" ? " as a top-level field inside implementation_plan" : ""}; correction: ${nestedHint ?? `set ${pathLabel} to an array${options.allowEmpty ? " (use [] when none exist)" : " with at least one entry"}.`}`);
+    }
+    if (!options.allowEmpty && arrayLength(source, key) === 0) {
+        throw new Error(`${pathLabel}: expected non-empty array; correction: include at least one entry.`);
+    }
+}
+export function architectNestedArrayHint(rootPayload, key) {
+    if (Array.isArray(rootPayload[key])) {
+        return `move top-level ${key} into implementation_plan.${key}.`;
+    }
+    const implementationPlan = rootPayload.implementation_plan;
+    if (!implementationPlan || typeof implementationPlan !== "object" || Array.isArray(implementationPlan)) {
+        return null;
+    }
+    const plan = implementationPlan;
+    for (const container of ["plan", "dag", "implementation_dag", "implementationPlan", "implementation_plan"]) {
+        const nested = plan[container];
+        if (nested && typeof nested === "object" && !Array.isArray(nested) && Array.isArray(nested[key])) {
+            return `move implementation_plan.${container}.${key} to implementation_plan.${key}.`;
+        }
+    }
+    return null;
+}
+export function validateQaPayloadShape(payload, status) {
+    const evidenceSource = qaEvidenceSource(payload);
+    const commands = qaArray(payload, "commands", evidenceSource);
+    const browserChecks = qaArray(payload, "browser_checks", evidenceSource);
+    const sidecars = qaArray(payload, "sidecars", 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");
+    qaPolicyWarnings(payload);
+    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.");
+        }
+    }
+    const commandIssues = [];
+    for (const [index, command] of commands.entries()) {
+        if (!command || typeof command !== "object" || Array.isArray(command)) {
+            commandIssues.push(`commands[${index}] must be an object.`);
+            continue;
+        }
+        const record = command;
+        if (!optionalString(record, "command"))
+            commandIssues.push(`commands[${index}].command is required.`);
+        if (!optionalString(record, "status"))
+            commandIssues.push(`commands[${index}].status is required.`);
+        if (!optionalString(record, "summary"))
+            commandIssues.push(`commands[${index}].summary is required.`);
+        if (typeof record.exit_code !== "number" || !Number.isFinite(record.exit_code)) {
+            commandIssues.push(`commands[${index}].exit_code is required.`);
+        }
+        else if (status === "pass" && record.exit_code !== 0) {
+            commandIssues.push(`commands[${index}].exit_code must be 0 when QA status is pass.`);
+        }
+        if (status === "pass" && normalizedString(record.status) !== "pass") {
+            commandIssues.push(`commands[${index}].status must be pass when QA status is pass.`);
+        }
+    }
+    throwCompletionPayloadIssues(commandIssues);
+    for (const [index, browserCheck] of browserChecks.entries()) {
+        requireEvidenceRecord(browserCheck, `browser_checks[${index}]`);
+        const record = browserCheck;
+        requireNonEmptyStringRecord(record, "summary", `browser_checks[${index}].`);
+        requireNonEmptyStringRecord(record, "status", `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.`);
+        }
+        if (!optionalString(record, "url") && !optionalString(record, "route")) {
+            throw new Error(`browser_checks[${index}] must include url or route.`);
+        }
+    }
+    for (const [index, sidecar] of sidecars.entries()) {
+        requireEvidenceRecord(sidecar, `sidecars[${index}]`);
+        const record = sidecar;
+        requireNonEmptyStringRecord(record, "path", `sidecars[${index}].`);
+        requireNonEmptyStringRecord(record, "content_hash", `sidecars[${index}].`);
+        if (typeof record.bytes !== "number" || !Number.isFinite(record.bytes) || record.bytes <= 0) {
+            throw new Error(`sidecars[${index}].bytes must be greater than 0.`);
+        }
+    }
+    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.");
+        }
+    }
+}
+export 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);
+}
+export function validateOptionalWorkItemId(payload, expectedWorkItemId) {
+    const actual = optionalString(payload, "work_item_id") ?? optionalString(payload, "workItemId");
+    if (actual && actual !== expectedWorkItemId) {
+        throw new Error(`completion payload work item ${actual} does not match dispatch work item ${expectedWorkItemId}.`);
+    }
+}
+import { requireField, requireNonPassEvidence, requireImplementationEvidence, requirePassingCommands, requireArray, requireNonEmptyArray, arrayLength, requireAllowedStatus, requireObject, requiredRecord, requireBoolean, requireNumericOne, requireSatisfiedAcceptanceCriteria, validateResolvedFindings, isDebugCompletionPhase, qaEvidenceSource, qaArray, qaObjectArray, qaPolicyWarnings, qaStringArray, requireEvidenceRecord, requireNonEmptyStringRecord, requireKnownStringRecord, requireNonEmptyStringArrayRecord, requireSubstantiveEvidenceRecord, normalizedString, requiredString, optionalString, stripUndefined, throwCompletionPayloadIssues, } from "./phase-completion.helpers.js";
+export * from "./phase-completion.helpers.js";