@loucompanion/forge-bridge 0.1.1-dev.c5b751411a2b → 0.1.1-dev.cada6731ecc7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -54,6 +54,8 @@ const qaBlockerReasons = new Set([
54
54
  "missing_worktree",
55
55
  "runner_failure"
56
56
  ]);
57
+ const resolvedFindingStatusValues = ["resolved", "disputed", "not_reproduced"];
58
+ const resolvedFindingStatuses = new Set(resolvedFindingStatusValues);
57
59
  const qaFindingSeverities = new Set(["critical", "major", "minor"]);
58
60
  const qaFindingScopes = new Set(["in_scope", "out_of_scope", "unclear"]);
59
61
  const qaCandidateBugActions = new Set(["create_bug", "create_follow_up", "accept_risk", "attach_to_current_item"]);
@@ -186,14 +188,20 @@ export function expectedDebugCompletionToolName(gate) {
186
188
  export function artifactRootFor(worktreePath, workItemId) {
187
189
  return path.join(worktreePath, ".forge", "work-items", safePathSegment(workItemId, "work item id"), "artifacts");
188
190
  }
189
- function artifactRootForOwner(worktreePath, ownerType, ownerId) {
191
+ export function artifactRootForOwner(worktreePath, ownerType, ownerId) {
190
192
  return path.join(worktreePath, ".forge", artifactOwnerDirectory(ownerType), safePathSegment(ownerId, "owner id"), "artifacts");
191
193
  }
192
- export function completionArtifactJsonPath(worktreePath, workItemId, phase) {
193
- return path.join(artifactRootFor(worktreePath, workItemId), phaseFiles[phase].jsonFileName);
194
+ export function completionArtifactJsonPath(worktreePath, workItemId, phase, ownerType, ownerId) {
195
+ const artifactRoot = ownerType && ownerId
196
+ ? artifactRootForOwner(worktreePath, ownerType, ownerId)
197
+ : artifactRootFor(worktreePath, workItemId);
198
+ return path.join(artifactRoot, phaseFiles[phase].jsonFileName);
194
199
  }
195
- export function completionArtifactReportPath(worktreePath, workItemId, phase) {
196
- return path.join(artifactRootFor(worktreePath, workItemId), phaseFiles[phase].reportFileName);
200
+ export function completionArtifactReportPath(worktreePath, workItemId, phase, ownerType, ownerId) {
201
+ const artifactRoot = ownerType && ownerId
202
+ ? artifactRootForOwner(worktreePath, ownerType, ownerId)
203
+ : artifactRootFor(worktreePath, workItemId);
204
+ return path.join(artifactRoot, phaseFiles[phase].reportFileName);
197
205
  }
198
206
  export async function prepareCompletionToolRuntime(options) {
199
207
  const phase = options.phase ?? completionPhaseFromDispatch(options.dispatch);
@@ -290,6 +298,9 @@ Forge will mirror only the tool-written QA artifacts; reporting QA completion in
290
298
  return `Forge completion tools are available through the MCP server named \`${toolServerName}\`.
291
299
  Do not write Architect artifacts by hand. When the plan is complete, call \`${toolName}(...)\`${alias ? ` (or \`${alias}\` if your client shows unqualified MCP tool names)` : ""} with the full structured Architect planning payload.
292
300
  That tool writes \`.forge/work-items/{workItemId}/artifacts/implementation.plan.json\`, \`qa.plan.json\`, \`${artifactName}\`, and \`architect.report.md\`.
301
+ The payload must put \`phases\`, \`tasks\`, \`dependencies\`, and \`phase_gates\` as top-level fields inside \`implementation_plan\`, for example:
302
+ \`{ "status": "pass", "summary": "...", "implementation_plan": { "schema_version": 1, "plan_id": "plan-...", "phases": [{ "id": "phase-1", "tasks": ["task-1"], "gate": "gate-1" }], "tasks": [{ "id": "task-1", "tests": [{ "command": "npm test" }] }], "dependencies": [], "phase_gates": [{ "id": "gate-1", "phase": "phase-1" }] }, "qa_plan": { "schema_version": 1, "final_qa": [{ "id": "qa-1", "coverage": "..." }] }, "report_markdown": "# Architect Report" }\`.
303
+ Dependency entries use canonical \`before\` and \`after\` task ids, for example \`{ "before": "task-1", "after": "task-2" }\`. Forge accepts \`from\`/\`to\` only as aliases and normalizes them before writing artifacts.
293
304
  Use \`status: "pass"\` for a valid pending-approval plan, \`needs_revision\` when story/design input must change, or \`blocked\` with a concrete blocker.
294
305
  Forge will mirror only the tool-written Architect artifacts; reporting the plan in prose is not enough.`;
295
306
  }
@@ -835,9 +846,9 @@ async function validateQaSidecarReferences(worktreePath, workItemId, sidecars, o
835
846
  }
836
847
  return validated;
837
848
  }
838
- export async function readCompletionArtifact(worktreePath, workItemId, phase) {
839
- const artifactPath = completionArtifactJsonPath(worktreePath, workItemId, phase);
840
- const reportPath = completionArtifactReportPath(worktreePath, workItemId, phase);
849
+ export async function readCompletionArtifact(worktreePath, workItemId, phase, ownerType, ownerId) {
850
+ const artifactPath = completionArtifactJsonPath(worktreePath, workItemId, phase, ownerType, ownerId);
851
+ const reportPath = completionArtifactReportPath(worktreePath, workItemId, phase, ownerType, ownerId);
841
852
  const verdictJson = await readOptionalFile(artifactPath);
842
853
  if (verdictJson === null) {
843
854
  return null;
@@ -1169,6 +1180,9 @@ function toolDescription(phase, qaGate = null) {
1169
1180
  if (phase === "qa") {
1170
1181
  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.";
1171
1182
  }
1183
+ if (phase === "architect") {
1184
+ 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.";
1185
+ }
1172
1186
  return "Complete Forge validation by writing validation.verdict.json with command, build/test/lint/design, drift, acceptance-criteria, and ready-for-dev-test evidence.";
1173
1187
  }
1174
1188
  function toolInputSchema(phase, qaGate = null) {
@@ -1218,7 +1232,7 @@ function toolInputSchema(phase, qaGate = null) {
1218
1232
  },
1219
1233
  tests_added_or_updated: {
1220
1234
  type: "array",
1221
- description: "Required for pass. Use an object explaining why no tests were needed for docs/config-only work if empty would be ambiguous.",
1235
+ description: "Required for pass. Use an object explaining why no tests were needed for documentation/config-only work if empty would be ambiguous.",
1222
1236
  items: evidenceObjectSchema(["path", "summary"], {
1223
1237
  path: { type: "string" },
1224
1238
  summary: { type: "string" }
@@ -1249,6 +1263,11 @@ function toolInputSchema(phase, qaGate = null) {
1249
1263
  },
1250
1264
  next_phase_context: {
1251
1265
  description: "Required for pass. Context the self-review phase should carry forward."
1266
+ },
1267
+ resolved_findings: {
1268
+ type: "array",
1269
+ description: "Required for QA rework. Each entry must use status resolved, disputed, or not_reproduced.",
1270
+ items: resolvedFindingSchema()
1252
1271
  }
1253
1272
  }, ["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.");
1254
1273
  }
@@ -1384,6 +1403,83 @@ function toolInputSchema(phase, qaGate = null) {
1384
1403
  }
1385
1404
  }, ["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.");
1386
1405
  }
1406
+ if (phase === "architect") {
1407
+ return objectToolSchema({
1408
+ status: {
1409
+ type: "string",
1410
+ enum: ["pass", "needs_revision", "blocked"],
1411
+ 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."
1412
+ },
1413
+ summary: { type: "string", description: "Concise Architect plan verdict summary." },
1414
+ implementation_plan: {
1415
+ type: "object",
1416
+ description: "Required for pass. Top-level fields inside this object must include schema_version, plan_id, phases, tasks, dependencies, and phase_gates.",
1417
+ additionalProperties: true,
1418
+ properties: {
1419
+ schema_version: { type: "number", enum: [1] },
1420
+ plan_id: { type: "string" },
1421
+ phases: {
1422
+ type: "array",
1423
+ description: "Required top-level implementation_plan.phases array.",
1424
+ items: { type: "object", additionalProperties: true }
1425
+ },
1426
+ tasks: {
1427
+ type: "array",
1428
+ description: "Required task list. Each task must include id and a non-empty tests array.",
1429
+ items: { type: "object", additionalProperties: true }
1430
+ },
1431
+ dependencies: {
1432
+ type: "array",
1433
+ 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.",
1434
+ items: {
1435
+ type: "object",
1436
+ additionalProperties: true,
1437
+ properties: {
1438
+ id: { type: "string" },
1439
+ before: { type: "string", description: "Task id that must complete first." },
1440
+ after: { type: "string", description: "Task id that depends on before." },
1441
+ from: { type: "string", description: "Alias for before." },
1442
+ to: { type: "string", description: "Alias for after." },
1443
+ type: { type: "string" },
1444
+ rationale: { type: "string" }
1445
+ }
1446
+ }
1447
+ },
1448
+ phase_gates: {
1449
+ type: "array",
1450
+ description: "Required non-empty phase gate array.",
1451
+ items: { type: "object", additionalProperties: true }
1452
+ }
1453
+ }
1454
+ },
1455
+ qa_plan: {
1456
+ type: "object",
1457
+ description: "Required for pass. Must include schema_version: 1 and non-empty final_qa coverage.",
1458
+ additionalProperties: true,
1459
+ properties: {
1460
+ schema_version: { type: "number", enum: [1] },
1461
+ final_qa: {
1462
+ type: "array",
1463
+ description: "Required non-empty final QA coverage array.",
1464
+ items: { type: "object", additionalProperties: true }
1465
+ }
1466
+ }
1467
+ },
1468
+ report_markdown: { type: "string", description: "Human-readable Architect report. Use report as an alias only when the client cannot send report_markdown." },
1469
+ report: { type: "string", description: "Alias for report_markdown." },
1470
+ blockers: baseProperties.blockers,
1471
+ revision_questions: {
1472
+ type: "array",
1473
+ description: "Required for needs_revision when blockers are not used.",
1474
+ items: { type: "string" }
1475
+ },
1476
+ revision_reasons: {
1477
+ type: "array",
1478
+ description: "Concrete reasons that prevent pass status.",
1479
+ items: { type: "string" }
1480
+ }
1481
+ }, ["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.");
1482
+ }
1387
1483
  return objectToolSchema({
1388
1484
  ...baseProperties,
1389
1485
  commands: {
@@ -1463,8 +1559,8 @@ function debugToolInputSchema(phase, baseProperties) {
1463
1559
  },
1464
1560
  resolved_findings: {
1465
1561
  type: "array",
1466
- description: "Required for QA rework. Entries should include qa_id, status, summary, evidence, changed_files, tests_added_or_updated, and regression_evidence.",
1467
- items: { type: "object", additionalProperties: true }
1562
+ description: "Required for QA rework. Each entry must use status resolved, disputed, or not_reproduced.",
1563
+ items: resolvedFindingSchema()
1468
1564
  }
1469
1565
  }, ["status", "summary"], "For status pass, include changed_files, tests_added_or_updated, and remaining_risks.");
1470
1566
  }
@@ -1571,6 +1667,29 @@ function commandEvidenceSchema() {
1571
1667
  summary: { type: "string" }
1572
1668
  });
1573
1669
  }
1670
+ function resolvedFindingSchema() {
1671
+ return evidenceObjectSchema([
1672
+ "qa_id",
1673
+ "status",
1674
+ "summary",
1675
+ "evidence",
1676
+ "changed_files",
1677
+ "tests_added_or_updated",
1678
+ "regression_evidence"
1679
+ ], {
1680
+ qa_id: { type: "string" },
1681
+ status: {
1682
+ type: "string",
1683
+ enum: [...resolvedFindingStatusValues],
1684
+ description: "Use resolved when fixed, disputed when the QA finding is incorrect/out-of-scope, or not_reproduced when retesting cannot reproduce it."
1685
+ },
1686
+ summary: { type: "string" },
1687
+ evidence: { description: "Concrete evidence for the resolution." },
1688
+ changed_files: { type: "array", description: "Required and non-empty when status is resolved." },
1689
+ tests_added_or_updated: { type: "array", description: "Required and non-empty when status is resolved." },
1690
+ regression_evidence: { description: "Concrete regression evidence for this QA finding." }
1691
+ });
1692
+ }
1574
1693
  function acceptanceCriteriaSchema() {
1575
1694
  return {
1576
1695
  type: "array",
@@ -1662,6 +1781,7 @@ function validatePayloadShape(phase, payload) {
1662
1781
  requireField(payload, "next_phase_context");
1663
1782
  requireImplementationEvidence(payload);
1664
1783
  requireSatisfiedAcceptanceCriteria(payload);
1784
+ validateResolvedFindings(payload);
1665
1785
  return;
1666
1786
  }
1667
1787
  if (phase === "self_review") {
@@ -1715,6 +1835,7 @@ function validateDebugPayloadShape(phase, payload) {
1715
1835
  if (arrayLength(payload, "tests_added_or_updated") === 0 && arrayLength(payload, "remaining_risks") === 0) {
1716
1836
  throw new Error("tests_added_or_updated is empty; remaining_risks must explain why no regression coverage changed.");
1717
1837
  }
1838
+ validateResolvedFindings(payload);
1718
1839
  return;
1719
1840
  }
1720
1841
  requireArray(payload, "commands");
@@ -1771,34 +1892,158 @@ function validateQaGatePayloadShape(gate, payload, status) {
1771
1892
  }
1772
1893
  function validateArchitectPayloadShape(payload, status) {
1773
1894
  if (status !== "pass") {
1774
- requireNonPassEvidence(payload);
1895
+ requireArchitectNonPassEvidence(payload);
1775
1896
  return;
1776
1897
  }
1777
1898
  const implementationPlan = requiredRecord(payload, "implementation_plan");
1778
1899
  const qaPlan = requiredRecord(payload, "qa_plan");
1779
- requireArray(implementationPlan, "phases");
1780
- requireArray(implementationPlan, "tasks");
1781
- requireArray(implementationPlan, "dependencies");
1782
- requireArray(implementationPlan, "phase_gates");
1900
+ requireNumericOne(implementationPlan, "schema_version", "implementation_plan.schema_version");
1901
+ requireNonEmptyStringRecord(implementationPlan, "plan_id", "implementation_plan.");
1902
+ requireArchitectArray(implementationPlan, "phases", payload);
1903
+ requireArchitectArray(implementationPlan, "tasks", payload);
1904
+ requireArchitectArray(implementationPlan, "dependencies", payload, { allowEmpty: true });
1905
+ requireArchitectArray(implementationPlan, "phase_gates", payload);
1783
1906
  if (arrayLength(implementationPlan, "tasks") === 0) {
1784
- throw new Error("implementation_plan.tasks must contain at least one task.");
1907
+ throw new Error("implementation_plan.tasks: expected non-empty array; correction: include at least one task with id and tests.");
1785
1908
  }
1909
+ const taskIds = new Set();
1786
1910
  for (const task of implementationPlan.tasks) {
1787
1911
  if (!task || typeof task !== "object" || Array.isArray(task)) {
1788
- throw new Error("implementation_plan.tasks entries must be objects.");
1912
+ throw new Error("implementation_plan.tasks[]: expected object entries; correction: each task must be an object with id and tests.");
1789
1913
  }
1790
1914
  const taskRecord = task;
1791
- requireField(taskRecord, "id");
1792
- requireArray(taskRecord, "tests");
1915
+ requireNonEmptyStringRecord(taskRecord, "id", "implementation_plan.tasks[].");
1916
+ const taskId = optionalString(taskRecord, "id") ?? "";
1917
+ if (taskIds.has(taskId)) {
1918
+ throw new Error(`implementation_plan.tasks: duplicate task id '${taskId}'.`);
1919
+ }
1920
+ taskIds.add(taskId);
1921
+ requireArchitectArray(taskRecord, "tests", payload, { path: `implementation_plan.tasks[${optionalString(taskRecord, "id") ?? "?"}].tests` });
1793
1922
  if (arrayLength(taskRecord, "tests") === 0) {
1794
- throw new Error("implementation_plan task tests must not be empty.");
1923
+ throw new Error(`implementation_plan.tasks[${optionalString(taskRecord, "id") ?? "?"}].tests: expected non-empty array; correction: include task-specific verification.`);
1795
1924
  }
1796
1925
  }
1797
- requireArray(qaPlan, "final_qa");
1926
+ validateAndNormalizeArchitectDependencies(implementationPlan, taskIds);
1927
+ requireNumericOne(qaPlan, "schema_version", "qa_plan.schema_version");
1928
+ requireArchitectArray(qaPlan, "final_qa", payload, { path: "qa_plan.final_qa" });
1798
1929
  if (arrayLength(qaPlan, "final_qa") === 0) {
1799
- throw new Error("qa_plan.final_qa must contain at least one coverage item.");
1930
+ throw new Error("qa_plan.final_qa: expected non-empty array; correction: include final QA coverage for the completed plan.");
1931
+ }
1932
+ }
1933
+ function validateAndNormalizeArchitectDependencies(implementationPlan, taskIds) {
1934
+ const dependencies = implementationPlan.dependencies;
1935
+ const edges = new Map();
1936
+ for (const taskId of taskIds) {
1937
+ edges.set(taskId, []);
1938
+ }
1939
+ const normalizedDependencies = [];
1940
+ for (const [index, dependency] of dependencies.entries()) {
1941
+ if (!dependency || typeof dependency !== "object" || Array.isArray(dependency)) {
1942
+ throw new Error("implementation_plan.dependencies[]: expected object entries; correction: each dependency must be an object with before and after task ids.");
1943
+ }
1944
+ const record = dependency;
1945
+ const before = architectDependencyEndpoint(record, index, "before", "from");
1946
+ const after = architectDependencyEndpoint(record, index, "after", "to");
1947
+ if (!taskIds.has(before) || !taskIds.has(after)) {
1948
+ throw new Error("implementation_plan.dependencies: dependency references an unknown task id.");
1949
+ }
1950
+ const normalized = stripUndefined({
1951
+ ...record,
1952
+ before,
1953
+ after,
1954
+ from: undefined,
1955
+ to: undefined
1956
+ });
1957
+ normalizedDependencies.push(normalized);
1958
+ edges.get(before)?.push(after);
1959
+ }
1960
+ implementationPlan.dependencies = normalizedDependencies;
1961
+ if (hasArchitectDependencyCycle(edges)) {
1962
+ throw new Error("implementation_plan.dependencies: expected acyclic graph; correction: remove or revise cyclic task dependencies.");
1800
1963
  }
1801
1964
  }
1965
+ function architectDependencyEndpoint(dependency, index, canonicalKey, aliasKey) {
1966
+ const canonical = optionalString(dependency, canonicalKey);
1967
+ const alias = optionalString(dependency, aliasKey);
1968
+ if (canonical && alias && canonical !== alias) {
1969
+ throw new Error(`implementation_plan.dependencies[${index}].${canonicalKey}: conflicts with ${aliasKey}; correction: use one task id for ${canonicalKey}.`);
1970
+ }
1971
+ const value = canonical ?? alias;
1972
+ if (!value) {
1973
+ throw new Error(`implementation_plan.dependencies[${index}].${canonicalKey}: expected string; correction: use before and after task ids for each dependency.`);
1974
+ }
1975
+ return value;
1976
+ }
1977
+ function hasArchitectDependencyCycle(edges) {
1978
+ const visiting = new Set();
1979
+ const visited = new Set();
1980
+ const visit = (node) => {
1981
+ if (visited.has(node)) {
1982
+ return false;
1983
+ }
1984
+ if (visiting.has(node)) {
1985
+ return true;
1986
+ }
1987
+ visiting.add(node);
1988
+ for (const next of edges.get(node) ?? []) {
1989
+ if (visit(next)) {
1990
+ return true;
1991
+ }
1992
+ }
1993
+ visiting.delete(node);
1994
+ visited.add(node);
1995
+ return false;
1996
+ };
1997
+ for (const node of edges.keys()) {
1998
+ if (visit(node)) {
1999
+ return true;
2000
+ }
2001
+ }
2002
+ return false;
2003
+ }
2004
+ function requireArchitectNonPassEvidence(payload) {
2005
+ const evidenceKeys = ["blockers", "revision_questions", "revision_reasons", "known_gaps", "findings", "remaining_risks", "failures"];
2006
+ const hasEvidence = evidenceKeys.some((key) => {
2007
+ const value = payload[key];
2008
+ if (typeof value === "string") {
2009
+ return value.trim().length > 0;
2010
+ }
2011
+ if (Array.isArray(value)) {
2012
+ return value.length > 0;
2013
+ }
2014
+ return Boolean(value && typeof value === "object");
2015
+ });
2016
+ if (!hasEvidence) {
2017
+ 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.");
2018
+ }
2019
+ }
2020
+ function requireArchitectArray(source, key, rootPayload, options = {}) {
2021
+ const pathLabel = options.path ?? `implementation_plan.${key}`;
2022
+ if (!Array.isArray(source[key])) {
2023
+ const nestedHint = architectNestedArrayHint(rootPayload, key);
2024
+ 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"}.`}`);
2025
+ }
2026
+ if (!options.allowEmpty && arrayLength(source, key) === 0) {
2027
+ throw new Error(`${pathLabel}: expected non-empty array; correction: include at least one entry.`);
2028
+ }
2029
+ }
2030
+ function architectNestedArrayHint(rootPayload, key) {
2031
+ if (Array.isArray(rootPayload[key])) {
2032
+ return `move top-level ${key} into implementation_plan.${key}.`;
2033
+ }
2034
+ const implementationPlan = rootPayload.implementation_plan;
2035
+ if (!implementationPlan || typeof implementationPlan !== "object" || Array.isArray(implementationPlan)) {
2036
+ return null;
2037
+ }
2038
+ const plan = implementationPlan;
2039
+ for (const container of ["plan", "dag", "implementation_dag", "implementationPlan", "implementation_plan"]) {
2040
+ const nested = plan[container];
2041
+ if (nested && typeof nested === "object" && !Array.isArray(nested) && Array.isArray(nested[key])) {
2042
+ return `move implementation_plan.${container}.${key} to implementation_plan.${key}.`;
2043
+ }
2044
+ }
2045
+ return null;
2046
+ }
1802
2047
  function validateQaPayloadShape(payload, status) {
1803
2048
  const evidenceSource = qaEvidenceSource(payload);
1804
2049
  const commands = qaArray(payload, "commands", evidenceSource);
@@ -2204,6 +2449,11 @@ function requireBoolean(payload, key) {
2204
2449
  throw new Error(`${key} must be a boolean.`);
2205
2450
  }
2206
2451
  }
2452
+ function requireNumericOne(payload, key, pathLabel) {
2453
+ if (payload[key] !== 1) {
2454
+ throw new Error(`${pathLabel}: expected numeric 1; correction: set ${pathLabel} to 1.`);
2455
+ }
2456
+ }
2207
2457
  function requireSatisfiedAcceptanceCriteria(payload) {
2208
2458
  const criteria = payload.acceptance_criteria;
2209
2459
  if (!Array.isArray(criteria)) {
@@ -2221,6 +2471,37 @@ function requireSatisfiedAcceptanceCriteria(payload) {
2221
2471
  }
2222
2472
  }
2223
2473
  }
2474
+ function validateResolvedFindings(payload) {
2475
+ const resolvedFindings = payload.resolved_findings;
2476
+ if (resolvedFindings === undefined || resolvedFindings === null) {
2477
+ return;
2478
+ }
2479
+ if (!Array.isArray(resolvedFindings)) {
2480
+ throw new Error("resolved_findings must be an array.");
2481
+ }
2482
+ for (const [index, finding] of resolvedFindings.entries()) {
2483
+ const prefix = `resolved_findings[${index}].`;
2484
+ if (!finding || typeof finding !== "object" || Array.isArray(finding)) {
2485
+ throw new Error(`resolved_findings[${index}] must be an object.`);
2486
+ }
2487
+ const record = finding;
2488
+ requireNonEmptyStringRecord(record, "qa_id", prefix);
2489
+ requireKnownStringRecord(record, "status", resolvedFindingStatuses, prefix);
2490
+ requireNonEmptyStringRecord(record, "summary", prefix);
2491
+ requireSubstantiveValueRecord(record, "evidence", prefix);
2492
+ requireArrayRecord(record, "changed_files", prefix);
2493
+ requireArrayRecord(record, "tests_added_or_updated", prefix);
2494
+ requireSubstantiveValueRecord(record, "regression_evidence", prefix);
2495
+ if (normalizedString(record.status) === "resolved") {
2496
+ if (record.changed_files.length === 0) {
2497
+ throw new Error(`${prefix}changed_files must include at least one changed file for resolved QA findings.`);
2498
+ }
2499
+ if (record.tests_added_or_updated.length === 0) {
2500
+ throw new Error(`${prefix}tests_added_or_updated must include at least one regression test for resolved QA findings.`);
2501
+ }
2502
+ }
2503
+ }
2504
+ }
2224
2505
  function qaEvidenceSource(payload) {
2225
2506
  const evidence = payload.evidence;
2226
2507
  return evidence && typeof evidence === "object" && !Array.isArray(evidence)
@@ -2270,6 +2551,11 @@ function requireNonEmptyStringRecord(source, key, prefix = "") {
2270
2551
  throw new Error(`${prefix}${key} is required.`);
2271
2552
  }
2272
2553
  }
2554
+ function requireArrayRecord(source, key, prefix = "") {
2555
+ if (!Array.isArray(source[key])) {
2556
+ throw new Error(`${prefix}${key} must be an array.`);
2557
+ }
2558
+ }
2273
2559
  function requireKnownStringRecord(source, key, allowed, prefix = "") {
2274
2560
  const value = normalizedString(optionalString(source, key));
2275
2561
  if (!allowed.has(value)) {
@@ -2287,6 +2573,11 @@ function requireNonEmptyStringArrayRecord(source, key, prefix = "") {
2287
2573
  }
2288
2574
  }
2289
2575
  }
2576
+ function requireSubstantiveValueRecord(source, key, prefix = "") {
2577
+ if (!hasSubstantiveJsonValue(source[key])) {
2578
+ throw new Error(`${prefix}${key} must include at least one concrete evidence reference or summary.`);
2579
+ }
2580
+ }
2290
2581
  function requireSubstantiveEvidenceRecord(source, prefix = "") {
2291
2582
  const evidence = source.evidence;
2292
2583
  if (!evidence || typeof evidence !== "object" || Array.isArray(evidence)) {
@@ -1,7 +1,8 @@
1
- import type { ProviderCliRunContext, ProviderCliRunResult } from "./provider-cli.types.js";
1
+ import type { ProviderCliDraftContext, ProviderCliRunContext, ProviderCliRunResult } from "./provider-cli.types.js";
2
2
  export interface ProviderCliService {
3
3
  runImplementation(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
4
4
  runArchitect(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
5
5
  runConflictResolve(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
6
6
  runQa(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
7
+ runDraft(context: ProviderCliDraftContext): Promise<ProviderCliRunResult>;
7
8
  }
@@ -1,7 +1,7 @@
1
1
  import { GitClient } from "../../shared/git/git.js";
2
2
  import { type CompletionToolRuntime } from "../phase-completion.js";
3
3
  import type { ProviderCliService } from "./provider-cli.base.js";
4
- import type { ProviderCliRunContext, ProviderCliRunResult } from "./provider-cli.types.js";
4
+ import type { ProviderCliDraftContext, ProviderCliRunContext, ProviderCliRunResult } from "./provider-cli.types.js";
5
5
  import type { RunOnceDispatchPacket } from "../session.types.js";
6
6
  export interface ProviderCliCommand {
7
7
  readonly command: string;
@@ -33,11 +33,13 @@ export declare class RoutingProviderCliService implements ProviderCliService {
33
33
  runArchitect(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
34
34
  runConflictResolve(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
35
35
  runQa(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
36
+ runDraft(context: ProviderCliDraftContext): Promise<ProviderCliRunResult>;
36
37
  }
37
38
  export declare class ProcessBackedProviderCliService implements ProviderCliService {
38
39
  private readonly processRunner;
39
40
  private readonly git;
40
41
  constructor(processRunner?: ProviderProcessRunner, git?: GitClient);
42
+ runDraft(context: ProviderCliDraftContext): Promise<ProviderCliRunResult>;
41
43
  runImplementation(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
42
44
  runArchitect(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
43
45
  runQa(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
@@ -46,6 +48,7 @@ export declare class ProcessBackedProviderCliService implements ProviderCliServi
46
48
  export declare class DeterministicProviderCliService implements ProviderCliService {
47
49
  private readonly git;
48
50
  constructor(git?: GitClient);
51
+ runDraft(context: ProviderCliDraftContext): Promise<ProviderCliRunResult>;
49
52
  runImplementation(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
50
53
  runArchitect(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
51
54
  runQa(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
@@ -61,4 +64,6 @@ export declare function buildProviderCliCommand(dispatch: RunOnceDispatchPacket,
61
64
  readonly prompt?: string;
62
65
  readonly worktreePath?: string;
63
66
  readonly completionTools?: CompletionToolRuntime;
67
+ readonly skipGitRepoCheck?: boolean;
64
68
  }): ProviderCliCommand;
69
+ export declare function codexSandboxModeForPlatform(platform?: NodeJS.Platform): "workspace-write" | "danger-full-access";