@loucompanion/forge-bridge 0.1.3-dev.f66395c3ac21 → 0.1.3-dev.fbe15023cdfe

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

@@ -0,0 +1,812 @@
+import { decomposeGateFileNames, isDebugCompletionPhase, phaseFiles, qaBlockerReasons, qaGateFileNames, qaScopeAuthorities, qaScopeConfidence, qaScopeEvidence, qaScopeSources, qaScopeSurfaces, resolvedFindingStatusValues } from "./phase-completion.js";
+export function toolDescription(phase, qaGate = null, decomposeGate = null) {
+    if (qaGate) {
+        return qaGate === "qa_verdict"
+            ? "Complete the final Forge QA verdict by writing the canonical QA bundle with pass, needs_rework, or blocked evidence."
+            : `Complete the ${qaGate.replace(/_/g, " ")} QA gate by writing ${qaGateFileNames[qaGate]} before continuing to the next QA gate.`;
+    }
+    if (decomposeGate) {
+        return decomposeGate === "decompose_proposal"
+            ? "Complete the Forge Decompose proposal by writing decompose.proposal.json with candidate child items and optional structured QA scopes."
+            : `Complete the ${decomposeGate.replace(/_/g, " ")} Decompose gate by writing ${decomposeGateFileNames[decomposeGate]} before continuing.`;
+    }
+    if (isDebugCompletionPhase(phase)) {
+        return `Complete the ${phase.replace(/_/g, " ")} Debug gate by writing ${phaseFiles[phase].jsonFileName} with structured bug-fix evidence before continuing.`;
+    }
+    if (phase === "implementation") {
+        return "Complete Forge implementation by writing implementation.completeness.json with scoped changed-file, verification, acceptance-criteria, gap, and next-phase evidence.";
+    }
+    if (phase === "ci_repair") {
+        return "Complete Forge CI repair by writing ci-repair.handoff.json with failed-check, root-cause, scoped-change, workflow-equivalence, validation, provider-state, and push-readiness evidence.";
+    }
+    if (phase === "self_review") {
+        return "Complete Forge self-review by writing self-review.report.json with diff review, findings, security, edge-case, design, deterministic-comparison, fixes, and remaining-risk evidence.";
+    }
+    if (phase === "qa") {
+        return "Complete Forge QA by writing qa.plan.json, qa.evidence.json, qa.findings.json, qa.verdict.json, and qa.report.md with structured pass, needs-rework, or blocked evidence.";
+    }
+    if (phase === "architect") {
+        return "Complete Forge Architect planning by writing implementation.plan.json, qa.plan.json, architect.verdict.json, and architect.report.md with a pending-approval plan or explicit revision/blocker reasons.";
+    }
+    return "Complete Forge validation by writing validation.verdict.json with command, build/test/lint/design, drift, acceptance-criteria, and ready-for-dev-test evidence.";
+}
+export function toolInputSchema(phase, qaGate = null, decomposeGate = null) {
+    const baseProperties = {
+        status: {
+            type: "string",
+            enum: ["pass", "needs_rework", "fail", "failed"],
+            description: "Use pass only when the phase evidence satisfies Forge's gate. Use needs_rework/fail/failed with explicit blockers or findings otherwise."
+        },
+        summary: { type: "string", description: "Concise phase summary." },
+        report_markdown: { type: "string", description: "Optional human-readable report. Forge will generate a fallback report if omitted." },
+        blockers: {
+            type: "array",
+            description: "Required for non-pass status unless findings, failures, known_gaps, remaining_risks, or commands provide explicit evidence.",
+            items: evidenceObjectSchema(["reason"], {
+                reason: { type: "string" },
+                owner: { type: "string" },
+                next_step: { type: "string" }
+            })
+        }
+    };
+    if (qaGate && qaGate !== "qa_verdict") {
+        return qaGateToolInputSchema(qaGate);
+    }
+    if (decomposeGate) {
+        return decomposeGateToolInputSchema(decomposeGate, baseProperties);
+    }
+    if (isDebugCompletionPhase(phase)) {
+        return debugToolInputSchema(phase, baseProperties);
+    }
+    if (phase === "ci_repair") {
+        return objectToolSchema({
+            ...baseProperties,
+            failed_checks: {
+                type: "array",
+                description: "Required and non-empty for pass. Provider check/job/step evidence inspected before repair.",
+                items: evidenceObjectSchema(["name", "provider_state"], {
+                    name: { type: "string" },
+                    provider_state: { type: "string" },
+                    workflow: { type: "string" },
+                    job: { type: "string" },
+                    step: { type: "string" },
+                    details_url: { type: "string" },
+                    evidence: { type: "string" }
+                })
+            },
+            root_cause: {
+                type: "object",
+                description: "Required for pass. Include classification, summary, and concrete evidence.",
+                additionalProperties: true,
+                properties: {
+                    classification: { type: "string" },
+                    summary: { type: "string" },
+                    evidence: { type: "array", items: { type: "string" } }
+                }
+            },
+            changed_files: {
+                type: "array",
+                description: "Files changed by the repair. May be empty only when no_code_action explains the provider-only action or blocker.",
+                items: evidenceObjectSchema(["path", "summary"], {
+                    path: { type: "string" },
+                    summary: { type: "string" }
+                })
+            },
+            no_code_action: {
+                type: "object",
+                description: "Required when changed_files is empty. Describe the evidence-backed provider action or blocker.",
+                additionalProperties: true,
+                properties: {
+                    action: { type: "string" },
+                    reason: { type: "string" },
+                    evidence: { type: "string" }
+                }
+            },
+            narrow_validation: {
+                type: "array",
+                description: "Required and non-empty for pass. The focused failing command or evidence-backed substitute.",
+                items: commandEvidenceSchema()
+            },
+            workflow_validation: {
+                type: "array",
+                description: "Required and non-empty for pass. Each failed-job guard/test/drift step with local equivalence supported, substitute, or provider_only.",
+                items: evidenceObjectSchema(["step", "equivalence", "status"], {
+                    step: { type: "string" },
+                    equivalence: { type: "string", enum: ["supported", "substitute", "provider_only"] },
+                    command: { type: "string" },
+                    exit_code: { type: "number" },
+                    status: { type: "string" },
+                    summary: { type: "string" },
+                    reason: { type: "string" },
+                    substitute: { type: "string" }
+                })
+            },
+            broader_validation: {
+                type: "array",
+                description: "Required and non-empty for pass. Normal validation covering every touched compiled/tested surface.",
+                items: commandEvidenceSchema()
+            },
+            remaining_risks: {
+                type: "array",
+                description: "Required for pass, even when empty.",
+                items: evidenceObjectSchema(["summary"], {
+                    summary: { type: "string" },
+                    mitigation: { type: "string" },
+                    owner: { type: "string" }
+                })
+            },
+            provider_state: {
+                type: "string",
+                enum: ["ready_for_rerun", "rerun_requested", "checks_pending", "still_failing", "blocked_by_provider"],
+                description: "Provider state after local validation and before Forge-owned publication."
+            },
+            ready_for_push: {
+                type: "boolean",
+                description: "Required for pass and must be true. Forge Bridge performs the commit/push only after this gate passes."
+            }
+        }, ["status", "summary"], "For status pass, include failed_checks, root_cause, changed_files or no_code_action, narrow_validation, workflow_validation, broader_validation, remaining_risks, provider_state, and ready_for_push: true.");
+    }
+    if (phase === "implementation") {
+        return objectToolSchema({
+            ...baseProperties,
+            plan: {
+                type: "array",
+                description: "Required for pass. Ordered implementation steps with status.",
+                items: evidenceObjectSchema(["step", "status"], {
+                    step: { type: "string" },
+                    status: { type: "string" },
+                    evidence: { type: "string" }
+                })
+            },
+            changed_files: {
+                type: "array",
+                description: "Required for pass. Must be non-empty unless known_gaps explains why.",
+                items: evidenceObjectSchema(["path", "summary"], {
+                    path: { type: "string" },
+                    summary: { type: "string" }
+                })
+            },
+            tests_added_or_updated: {
+                type: "array",
+                description: "Required for pass. Use an object explaining why no tests were needed for documentation/config-only work if empty would be ambiguous.",
+                items: evidenceObjectSchema(["path", "summary"], {
+                    path: { type: "string" },
+                    summary: { type: "string" }
+                })
+            },
+            docs_added_or_updated: {
+                type: "array",
+                description: "Required for pass. Use an object explaining why no docs changed when appropriate.",
+                items: evidenceObjectSchema(["path", "summary"], {
+                    path: { type: "string" },
+                    summary: { type: "string" }
+                })
+            },
+            verification: {
+                type: "array",
+                description: "Implementation verification evidence. Objects should include command, exit_code, status, and summary when command-based.",
+                items: commandEvidenceSchema()
+            },
+            acceptance_criteria: acceptanceCriteriaSchema(),
+            known_gaps: {
+                type: "array",
+                description: "Required for pass, even when empty. If changed_files/tests/docs arrays are empty, explain why here.",
+                items: evidenceObjectSchema(["summary"], {
+                    summary: { type: "string" },
+                    impact: { type: "string" },
+                    follow_up: { type: "string" }
+                })
+            },
+            next_phase_context: {
+                description: "Required for pass. Context the self-review phase should carry forward."
+            },
+            resolved_findings: {
+                type: "array",
+                description: "Required for QA rework. Each entry must use status resolved, disputed, or not_reproduced.",
+                items: resolvedFindingSchema()
+            }
+        }, ["status", "summary"], "For status pass, include plan, changed_files, tests_added_or_updated, docs_added_or_updated, acceptance_criteria, known_gaps, and next_phase_context. Acceptance criteria entries must use status: satisfied plus evidence.");
+    }
+    if (phase === "self_review") {
+        return objectToolSchema({
+            ...baseProperties,
+            reviewed_diff: { type: "boolean", description: "Required for pass. True after reviewing the implementation diff." },
+            findings: {
+                type: "array",
+                description: "Required for pass, even when empty. Include finding objects for issues discovered during review.",
+                items: evidenceObjectSchema(["severity", "summary", "status"], {
+                    severity: { type: "string" },
+                    summary: { type: "string" },
+                    status: { type: "string" },
+                    file: { type: "string" }
+                })
+            },
+            security_review: reviewSectionSchema(),
+            edge_case_review: reviewSectionSchema(),
+            design_review: {
+                ...reviewSectionSchema(),
+                properties: {
+                    ...reviewSectionProperties(),
+                    screenshots: { type: "array", items: evidenceObjectSchema(["path"], { path: { type: "string" }, summary: { type: "string" } }) }
+                }
+            },
+            deterministic_comparison: {
+                type: "object",
+                description: "Required for pass. Evidence that the reviewed diff matches the intended deterministic change.",
+                additionalProperties: true,
+                properties: {
+                    status: { type: "string" },
+                    command_or_tool: { type: "string" },
+                    notes: { type: "string" }
+                }
+            },
+            fixes_applied: {
+                type: "array",
+                description: "Required for pass, even when empty.",
+                items: evidenceObjectSchema(["summary"], { summary: { type: "string" }, path: { type: "string" } })
+            },
+            remaining_risks: {
+                type: "array",
+                description: "Required for pass, even when empty.",
+                items: evidenceObjectSchema(["summary"], { summary: { type: "string" }, mitigation: { type: "string" } })
+            }
+        }, ["status", "summary"], "For status pass, include reviewed_diff, findings, security_review, edge_case_review, design_review, deterministic_comparison, fixes_applied, and remaining_risks.");
+    }
+    if (phase === "qa") {
+        return objectToolSchema({
+            ...baseProperties,
+            status: {
+                type: "string",
+                enum: ["pass", "needs_rework", "blocked"],
+                description: "Use pass only when QA evidence satisfies acceptance criteria, needs_rework for actionable in-scope defects, or blocked for an inconclusive QA blocker."
+            },
+            checklist: {
+                type: "array",
+                description: "QA plan/checklist. Forge writes this to qa.plan.json; a default checklist is generated if omitted.",
+                items: { type: "string" }
+            },
+            tested_acceptance_criteria: {
+                type: "array",
+                description: "Required and non-empty for pass/needs_rework. Criteria actually tested by QA.",
+                items: { type: "string" }
+            },
+            commands: {
+                type: "array",
+                description: "Command evidence written to qa.evidence.json.",
+                items: commandEvidenceSchema()
+            },
+            browser_checks: {
+                type: "array",
+                description: "Browser/manual UI checks with URL or route, action, observed result, screenshot/trace references, console/network notes, and status.",
+                items: evidenceObjectSchema(["summary", "status"], {
+                    summary: { type: "string" },
+                    url: { type: "string" },
+                    route: { type: "string" },
+                    status: { type: "string" },
+                    screenshot: { type: "string" },
+                    trace: { type: "string" }
+                })
+            },
+            sidecars: {
+                type: "array",
+                description: "Optional QA sidecar files already written under the dispatch-provided QA artifacts path with path/content_hash/bytes metadata.",
+                items: evidenceObjectSchema(["path", "content_hash", "bytes"], {
+                    path: { type: "string" },
+                    content_hash: { type: "string" },
+                    bytes: { type: "number" }
+                })
+            },
+            notes: { type: "string", description: "Additional QA evidence notes." },
+            evidence: {
+                type: "object",
+                description: "Optional wrapper containing commands, browser_checks, and notes when a client prefers nested evidence."
+            },
+            findings: {
+                type: "array",
+                description: "QA findings. needs_rework requires at least one actionable in_scope finding.",
+                items: evidenceObjectSchema(["id", "severity", "scope", "title"], {
+                    id: { type: "string" },
+                    severity: { type: "string", enum: ["critical", "major", "minor"] },
+                    scope: { type: "string", enum: ["in_scope", "out_of_scope", "unclear"] },
+                    title: { type: "string" },
+                    acceptance_criteria: { type: "array", items: { type: "string" } },
+                    repro_steps: { type: "array", items: { type: "string" } },
+                    expected: { type: "string" },
+                    actual: { type: "string" },
+                    evidence: { type: "object" },
+                    likely_area: { type: "array", items: { type: "string" } },
+                    required_fix: { type: "string" },
+                    required_regression: { type: "string" }
+                })
+            },
+            candidate_bugs: {
+                type: "array",
+                description: "Out-of-scope/follow-up bug candidates. They do not block the current item unless attached as in-scope findings.",
+                items: evidenceObjectSchema(["id", "title", "suggested_action"], {
+                    id: { type: "string" },
+                    title: { type: "string" },
+                    severity: { type: "string" },
+                    scope_reason: { type: "string" },
+                    repro_steps: { type: "array", items: { type: "string" } },
+                    evidence: { type: "object" },
+                    suggested_action: { type: "string", enum: ["create_bug", "create_follow_up", "accept_risk", "attach_to_current_item"] }
+                })
+            },
+            policy_warnings: {
+                type: "array",
+                description: "Non-blocking Forge policy or scope warnings surfaced with the QA verdict.",
+                items: evidenceObjectSchema(["code", "message"], {
+                    code: { type: "string" },
+                    message: { type: "string" },
+                    severity: { type: "string" },
+                    evidence: { type: "object" }
+                })
+            },
+            blocker_reason: {
+                type: "string",
+                enum: [...qaBlockerReasons],
+                description: "Required when status is blocked."
+            }
+        }, ["status", "summary"], "For pass, include tested_acceptance_criteria plus concrete command/browser/note evidence. For needs_rework, include at least one actionable in_scope finding. For blocked, include blocker_reason.");
+    }
+    if (phase === "architect") {
+        return objectToolSchema({
+            status: {
+                type: "string",
+                enum: ["pass", "needs_revision", "blocked"],
+                description: "Use pass only for a complete pending-approval Architect plan. Use needs_revision for fixable story/design/repo gaps, or blocked for missing required context or decisions."
+            },
+            summary: { type: "string", description: "Concise Architect plan verdict summary." },
+            implementation_plan: {
+                type: "object",
+                description: "Required for pass. Top-level fields inside this object must include schema_version, plan_id, phases, tasks, dependencies, and phase_gates.",
+                additionalProperties: true,
+                properties: {
+                    schema_version: { type: "number", enum: [1] },
+                    plan_id: { type: "string" },
+                    phases: {
+                        type: "array",
+                        description: "Required top-level implementation_plan.phases array.",
+                        items: { type: "object", additionalProperties: true }
+                    },
+                    tasks: {
+                        type: "array",
+                        description: "Required Develop child task list. Each task must include id, a non-empty tests array, and should include verification_scope for task-level QA evidence. Do not put parent-story QA/sign-off, child-count/materialization inventory, parent plan artifact checks, or final acceptance proof here; those belong in qa_plan.final_qa.",
+                        items: {
+                            type: "object",
+                            additionalProperties: true,
+                            properties: {
+                                id: { type: "string" },
+                                title: { type: "string" },
+                                verification_scope: qaScopeSchema("Task-level QA/verification scope for the materialized child task."),
+                                tests: {
+                                    type: "array",
+                                    items: { type: "object", additionalProperties: true }
+                                }
+                            }
+                        }
+                    },
+                    dependencies: {
+                        type: "array",
+                        description: "Required dependency edge array. Use [] when no task dependencies exist. Each edge should use before and after task ids; from/to are accepted only as aliases and normalized before writing artifacts.",
+                        items: {
+                            type: "object",
+                            additionalProperties: true,
+                            properties: {
+                                id: { type: "string" },
+                                before: { type: "string", description: "Task id that must complete first." },
+                                after: { type: "string", description: "Task id that depends on before." },
+                                from: { type: "string", description: "Alias for before." },
+                                to: { type: "string", description: "Alias for after." },
+                                type: { type: "string" },
+                                rationale: { type: "string" }
+                            }
+                        }
+                    },
+                    phase_gates: {
+                        type: "array",
+                        description: "Required non-empty phase gate array.",
+                        items: { type: "object", additionalProperties: true }
+                    }
+                }
+            },
+            qa_plan: {
+                type: "object",
+                description: "Required for pass. Must include schema_version: 1 and non-empty final_qa coverage.",
+                additionalProperties: true,
+                properties: {
+                    schema_version: { type: "number", enum: [1] },
+                    final_qa: {
+                        type: "array",
+                        description: "Required non-empty final QA coverage array.",
+                        items: { type: "object", additionalProperties: true }
+                    }
+                }
+            },
+            report_markdown: { type: "string", description: "Human-readable Architect report. Use report as an alias only when the client cannot send report_markdown." },
+            report: { type: "string", description: "Alias for report_markdown." },
+            blockers: baseProperties.blockers,
+            revision_questions: {
+                type: "array",
+                description: "Required for needs_revision when blockers are not used.",
+                items: { type: "string" }
+            },
+            revision_reasons: {
+                type: "array",
+                description: "Concrete reasons that prevent pass status.",
+                items: { type: "string" }
+            }
+        }, ["status", "summary"], "For status pass, include implementation_plan and qa_plan at the top level of the MCP tool arguments. implementation_plan.phases must be a top-level array inside implementation_plan, not nested under another object.");
+    }
+    return objectToolSchema({
+        ...baseProperties,
+        commands: {
+            type: "array",
+            description: "Required for pass. Include at least one deterministic validation command with exit_code: 0 and status: pass.",
+            items: commandEvidenceSchema()
+        },
+        acceptance_criteria: acceptanceCriteriaSchema(),
+        build_status: { type: "string", description: "Required for pass and must be pass." },
+        test_status: { type: "string", description: "Required for pass and must be pass." },
+        lint_status: { type: "string", description: "Required for pass. pass/fail/needs_rework/not_applicable." },
+        design_status: { type: "string", description: "Required for pass. pass/fail/needs_rework/not_applicable." },
+        drift_checks: {
+            type: "array",
+            description: "Required for pass. Deterministic checks for unintended drift.",
+            items: evidenceObjectSchema(["command_or_tool", "status", "summary"], {
+                command_or_tool: { type: "string" },
+                status: { type: "string" },
+                summary: { type: "string" }
+            })
+        },
+        ready_for_dev_test: { type: "boolean", description: "Required for pass and must be true." }
+    }, ["status", "summary"], "For status pass, commands must include at least one passing deterministic command, acceptance criteria entries must use status: satisfied plus evidence, and ready_for_dev_test must be true.");
+}
+function decomposeGateToolInputSchema(gate, baseProperties) {
+    if (gate !== "decompose_proposal") {
+        return objectToolSchema({
+            ...baseProperties,
+            findings: {
+                type: "array",
+                description: "Optional issues, constraints, or risks discovered in this Decompose gate.",
+                items: { type: "object", additionalProperties: true }
+            }
+        }, ["status", "summary"], `Record the ${gate.replace(/_/g, " ")} Decompose gate before continuing.`);
+    }
+    const candidateSchema = {
+        type: "object",
+        additionalProperties: true,
+        properties: {
+            origin: { type: "string" },
+            key: { type: "string" },
+            title: { type: "string" },
+            summary: { type: "string" },
+            description: { type: "string" },
+            acceptanceCriteria: { type: "string" },
+            planningPacket: { type: "string" },
+            sortOrder: { type: "number" },
+            scheduleIndex: { type: "number", description: "Feature-to-Story total schedule order for dependency-safe execution." },
+            schedule_index: { type: "number", description: "Snake_case alias for scheduleIndex." },
+            waveIndex: { type: "number", description: "Feature-to-Story parallel wave number." },
+            wave_index: { type: "number", description: "Snake_case alias for waveIndex." },
+            featureScheduleIndex: { type: "number", description: "Optional ordering within the Feature." },
+            feature_schedule_index: { type: "number", description: "Snake_case alias for featureScheduleIndex." },
+            expectedOutput: { type: "string", description: "Durable output this Story should produce for dependents." },
+            expected_output: { type: "string", description: "Snake_case alias for expectedOutput." },
+            handoffSummary: { type: "string", description: "How dependent Stories should consume this Story output." },
+            handoff_summary: { type: "string", description: "Snake_case alias for handoffSummary." },
+            dependencyReason: { type: "string", description: "Why this Story depends on its dependsOn predecessors." },
+            dependency_reason: { type: "string", description: "Snake_case alias for dependencyReason." },
+            points: { type: "number" },
+            dependsOn: { type: "array", items: { type: "string" } },
+            estimatedQaScope: qaScopeSchema("Work Order-to-Feature planning QA estimate. This is not dispatch-authoritative QA scope."),
+            estimated_qa_scope: qaScopeSchema("Work Order-to-Feature planning QA estimate. Snake_case alias for estimatedQaScope."),
+            qaScope: qaScopeSchema("Feature-to-Story QA scope that becomes Story-level QA scope after proposal approval."),
+            qa_scope: qaScopeSchema("Feature-to-Story QA scope. Snake_case alias for qaScope."),
+            designerRefCandidates: designerRefCandidatesSchema("Designer packet refs that justify this candidate. Omit to inherit all parent refs unchanged."),
+            designer_ref_candidates: designerRefCandidatesSchema("Snake_case alias for designerRefCandidates.")
+        }
+    };
+    const proposalSchema = {
+        type: "object",
+        additionalProperties: true,
+        description: "Final Decompose proposal JSON. Must include candidates, and may include blockedReason.",
+        properties: {
+            summary: { type: "string" },
+            blockedReason: { type: "string" },
+            blocked_reason: { type: "string" },
+            candidates: {
+                type: "array",
+                items: candidateSchema
+            }
+        }
+    };
+    return objectToolSchema({
+        ...baseProperties,
+        status: {
+            type: "string",
+            enum: ["pass", "needs_rework", "blocked"],
+            description: "Use pass only when the Decompose proposal is ready for user sign-off."
+        },
+        proposal_json: proposalSchema,
+        decomposition_json: {
+            ...proposalSchema,
+            description: "Alias for proposal_json when a client cannot send proposal_json."
+        }
+    }, ["status", "summary"], "For the final Decompose proposal, include proposal_json with a candidates array. Work Order-to-Feature candidates may include estimatedQaScope/estimated_qa_scope; Feature-to-Story candidates may include qaScope/qa_scope. Both levels may include designerRefCandidates/designer_ref_candidates.");
+}
+function designerRefCandidatesSchema(description) {
+    return {
+        type: "array",
+        description,
+        items: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                designerRefId: { type: "string" },
+                designer_ref_id: { type: "string" },
+                refKey: { type: "string" },
+                ref_key: { type: "string" },
+                path: { type: "string" },
+                anchor: { type: "string" },
+                reason: { type: "string" },
+                required: { type: "boolean" }
+            }
+        }
+    };
+}
+function debugToolInputSchema(phase, baseProperties) {
+    if (phase === "debug_repro") {
+        return objectToolSchema({
+            ...baseProperties,
+            repro_steps: {
+                type: "array",
+                description: "Required for pass. Minimal reproduction or characterization steps.",
+                items: { type: "string" }
+            },
+            observed: { type: "string", description: "Observed failure behavior." },
+            expected: { type: "string", description: "Expected behavior." },
+            evidence: {
+                type: "array",
+                description: "Required for pass. Concrete logs, commands, screenshots, file refs, or characterization notes.",
+                items: { type: "object", additionalProperties: true }
+            }
+        }, ["status", "summary"], "For status pass, include repro_steps, observed, expected, and evidence.");
+    }
+    if (phase === "debug_root_cause") {
+        return objectToolSchema({
+            ...baseProperties,
+            root_cause: { type: "string", description: "Likely root cause tied to code or config evidence." },
+            evidence: {
+                type: "array",
+                description: "Required for pass. Concrete code/log/test evidence supporting the root cause.",
+                items: { type: "object", additionalProperties: true }
+            },
+            eliminated_alternatives: {
+                type: "array",
+                description: "Required for pass. Plausible alternatives checked or ruled out.",
+                items: { type: "object", additionalProperties: true }
+            },
+            risk_area: { type: "string", description: "Subsystem or behavior most at risk from the fix." }
+        }, ["status", "summary"], "For status pass, include root_cause, evidence, eliminated_alternatives, and risk_area.");
+    }
+    if (phase === "debug_fix") {
+        return objectToolSchema({
+            ...baseProperties,
+            changed_files: {
+                type: "array",
+                description: "Required for pass. Files changed by the bug fix.",
+                items: evidenceObjectSchema(["path", "summary"], { path: { type: "string" }, summary: { type: "string" } })
+            },
+            tests_added_or_updated: {
+                type: "array",
+                description: "Required for pass. Regression tests or checks added/updated, or justify omission in remaining_risks.",
+                items: evidenceObjectSchema(["path", "summary"], { path: { type: "string" }, summary: { type: "string" } })
+            },
+            remaining_risks: {
+                type: "array",
+                description: "Required for pass, even when empty. Include why no regression coverage changed when tests_added_or_updated is empty.",
+                items: evidenceObjectSchema(["summary"], { summary: { type: "string" }, mitigation: { type: "string" } })
+            },
+            resolved_findings: {
+                type: "array",
+                description: "Required for QA rework. Each entry must use status resolved, disputed, or not_reproduced.",
+                items: resolvedFindingSchema()
+            }
+        }, ["status", "summary"], "For status pass, include changed_files, tests_added_or_updated, and remaining_risks.");
+    }
+    return objectToolSchema({
+        ...baseProperties,
+        commands: {
+            type: "array",
+            description: "Required for pass. Targeted regression/repro-negative commands with exit_code: 0 and status: pass.",
+            items: commandEvidenceSchema()
+        },
+        required_regressions: {
+            type: "array",
+            description: "Required for pass. Repro-negative and regression coverage checklist.",
+            items: { type: "string" }
+        },
+        build_status: { type: "string", description: "Required for pass. pass or not_applicable." },
+        test_status: { type: "string", description: "Required for pass. pass or not_applicable." },
+        repro_negative: { type: "boolean", description: "Required for pass and must be true after the original repro no longer fails." },
+        qa_ready: { type: "boolean", description: "Required for pass and must be true." }
+    }, ["status", "summary"], "For status pass, commands must include at least one passing deterministic debug regression check, repro_negative must be true, and qa_ready must be true.");
+}
+function qaGateToolInputSchema(gate) {
+    const baseProperties = {
+        status: {
+            type: "string",
+            enum: ["pass", "skipped", "blocked"],
+            description: "Use pass when this QA gate produced evidence, skipped when not applicable, or blocked when a prerequisite prevents this gate."
+        },
+        summary: { type: "string", description: "Concise QA gate summary." },
+        reason: { type: "string", description: "Required for skipped or blocked gates." },
+        blocker_reason: {
+            type: "string",
+            enum: [...qaBlockerReasons],
+            description: "Required when status is blocked."
+        }
+    };
+    if (gate === "qa_plan") {
+        return objectToolSchema({
+            ...baseProperties,
+            checklist: {
+                type: "array",
+                description: "Required for pass. QA checklist entries planned for this work item.",
+                items: { type: "string" }
+            },
+            acceptance_criteria: {
+                type: "array",
+                description: "Acceptance criteria selected for QA.",
+                items: { type: "string" }
+            }
+        }, ["status", "summary"], "Record the QA plan gate. Pass requires a non-empty checklist.");
+    }
+    if (gate === "qa_findings") {
+        return objectToolSchema({
+            ...baseProperties,
+            findings: {
+                type: "array",
+                description: "Normalized in-scope and out-of-scope QA findings.",
+                items: { type: "object", additionalProperties: true }
+            },
+            candidate_bugs: {
+                type: "array",
+                description: "Out-of-scope or follow-up candidates.",
+                items: { type: "object", additionalProperties: true }
+            }
+        }, ["status", "summary"], "Record normalized QA findings. Pass or skipped requires findings and candidate_bugs arrays, even when empty.");
+    }
+    return objectToolSchema({
+        ...baseProperties,
+        commands: {
+            type: "array",
+            description: "Command evidence for this gate when applicable.",
+            items: commandEvidenceSchema()
+        },
+        browser_checks: {
+            type: "array",
+            description: "Browser/manual evidence for this gate when applicable.",
+            items: { type: "object", additionalProperties: true }
+        },
+        notes: { type: "string", description: "Evidence notes for this gate." }
+    }, ["status", "summary"], "Record this QA evidence gate. Use skipped with a reason when the gate is not applicable.");
+}
+function objectToolSchema(properties, required, description) {
+    return {
+        type: "object",
+        additionalProperties: true,
+        description,
+        properties,
+        required: [...required]
+    };
+}
+function evidenceObjectSchema(required, properties) {
+    return {
+        type: "object",
+        additionalProperties: true,
+        properties,
+        required: [...required]
+    };
+}
+function qaScopeSchema(description) {
+    return {
+        type: "object",
+        additionalProperties: false,
+        description,
+        properties: {
+            schema_version: { type: "number", enum: [1] },
+            surface: { type: "array", items: { type: "string", enum: [...qaScopeSurfaces] } },
+            required_evidence: { type: "array", items: { type: "string", enum: [...qaScopeEvidence] } },
+            not_applicable: { type: "array", items: { type: "string", enum: [...qaScopeEvidence] } },
+            browser_required: { type: "boolean" },
+            api_required: { type: "boolean" },
+            source: { type: "string", enum: [...qaScopeSources] },
+            authority: { type: "string", enum: [...qaScopeAuthorities] },
+            confidence: { type: "string", enum: [...qaScopeConfidence] },
+            confirmed_by_user: { type: "boolean" },
+            locked: { type: "boolean" },
+            derived_from: {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                    work_item_id: { type: "string" },
+                    mode: { type: "string" }
+                }
+            },
+            rationale: { type: "string" }
+        },
+        required: ["schema_version", "required_evidence", "not_applicable"]
+    };
+}
+function commandEvidenceSchema() {
+    return evidenceObjectSchema(["command", "exit_code", "status", "summary"], {
+        command: { type: "string" },
+        managed_command_id: { type: "string", description: "Receipt ID returned by forge.start_managed_command and completed through one forge.wait_managed_command call for managed-host evidence." },
+        exit_code: { type: ["number", "null"], description: "Process exit code, or null when the managed runner timed out or could not launch the process." },
+        status: { type: "string" },
+        summary: { type: "string" },
+        classification: {
+            type: "string",
+            enum: ["out_of_scope_failure", "baseline_failure"],
+            description: "Only for a verified non-blocking failure in a passing QA regression gate. Never use for an in-scope or unexplained failure."
+        },
+        candidate_bug_id: { type: "string", description: "Required for a classified non-blocking failure; links the preserved failure to candidate_bugs." },
+        scope_evidence: { type: "string", description: "Required proof that the failing surface is outside the current acceptance criteria and changed-file scope." },
+        acceptance_criteria_independent: { type: "boolean", description: "Required and true only when the current item can be judged independently of this failure." },
+        repro_command: { type: "string", description: "Required for out_of_scope_failure; focused command that reproduced the unrelated failure." },
+        repro_exit_code: { type: "number", description: "Required non-zero focused repro exit code for out_of_scope_failure." },
+        baseline_ref: { type: "string", description: "Required for baseline_failure; immutable ref where the same failure was observed." },
+        baseline_exit_code: { type: "number", description: "Required non-zero baseline command exit code for baseline_failure." },
+        failure_signature_match: { type: "boolean", description: "Required and true for baseline_failure after matching failing test/error signatures." }
+    });
+}
+function resolvedFindingSchema() {
+    return evidenceObjectSchema([
+        "qa_id",
+        "status",
+        "summary",
+        "evidence",
+        "changed_files",
+        "tests_added_or_updated",
+        "regression_evidence"
+    ], {
+        qa_id: { type: "string" },
+        status: {
+            type: "string",
+            enum: [...resolvedFindingStatusValues],
+            description: "Use resolved when fixed, disputed when the QA finding is incorrect/out-of-scope, or not_reproduced when retesting cannot reproduce it."
+        },
+        summary: { type: "string" },
+        evidence: { description: "Concrete evidence for the resolution." },
+        changed_files: { type: "array", description: "Required and non-empty when status is resolved." },
+        tests_added_or_updated: { type: "array", description: "Required and non-empty when status is resolved." },
+        regression_evidence: { description: "Concrete regression evidence for this QA finding." }
+    });
+}
+function acceptanceCriteriaSchema() {
+    return {
+        type: "array",
+        description: "Required for pass. Every entry must be an object with status: satisfied and non-empty evidence.",
+        items: evidenceObjectSchema(["criterion", "evidence", "status"], {
+            criterion: { type: "string" },
+            evidence: { type: "string" },
+            status: { type: "string", enum: ["satisfied"] }
+        })
+    };
+}
+function reviewSectionSchema() {
+    return {
+        type: "object",
+        description: "Required for pass. Use status pass/fail/needs_rework/not_applicable plus notes.",
+        additionalProperties: true,
+        properties: reviewSectionProperties()
+    };
+}
+function reviewSectionProperties() {
+    return {
+        status: { type: "string" },
+        notes: { type: "string" }
+    };
+}