agentxchain 2.14.0 → 2.16.0

package/src/lib/workflow-gate-semantics.js

@@ -2,9 +2,14 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 
 export const PM_SIGNOFF_PATH = '.planning/PM_SIGNOFF.md';
+export const SYSTEM_SPEC_PATH = '.planning/SYSTEM_SPEC.md';
+export const IMPLEMENTATION_NOTES_PATH = '.planning/IMPLEMENTATION_NOTES.md';
+export const ACCEPTANCE_MATRIX_PATH = '.planning/acceptance-matrix.md';
 export const SHIP_VERDICT_PATH = '.planning/ship-verdict.md';
+export const RELEASE_NOTES_PATH = '.planning/RELEASE_NOTES.md';
 
 const AFFIRMATIVE_SHIP_VERDICTS = new Set(['YES', 'SHIP', 'SHIP IT']);
+const AFFIRMATIVE_ACCEPTANCE_STATUSES = new Set(['PASS', 'PASSED', 'OK', 'YES']);
 
 function normalizeToken(value) {
   return value.trim().replace(/\s+/g, ' ').toUpperCase();
@@ -42,6 +47,194 @@ function evaluatePmSignoff(content) {
   return { ok: true };
 }
 
+function evaluateSystemSpec(content) {
+  const requiredSections = ['## Purpose', '## Interface', '## Acceptance Tests'];
+  const missingSections = requiredSections.filter((section) => !content.includes(section));
+
+  if (missingSections.length > 0) {
+    return {
+      ok: false,
+      reason: `.planning/SYSTEM_SPEC.md must define ${missingSections.join(', ')} before planning can exit.`,
+    };
+  }
+
+  return { ok: true };
+}
+
+function isMarkdownSeparatorRow(cells) {
+  return cells.length > 0 && cells.every((cell) => /^:?-{3,}:?$/.test(cell));
+}
+
+function evaluateAcceptanceMatrix(content) {
+  const lines = content.split(/\r?\n/);
+  const headerIndex = lines.findIndex((line) => /^\|\s*Req\s*#\s*\|/i.test(line));
+
+  if (headerIndex === -1) {
+    return {
+      ok: false,
+      reason: 'Acceptance matrix must preserve the `| Req # |` requirement table header in .planning/acceptance-matrix.md.',
+    };
+  }
+
+  const rows = [];
+  let sawTable = false;
+
+  for (let index = headerIndex + 1; index < lines.length; index++) {
+    const line = lines[index];
+    if (!line.trim()) {
+      if (sawTable) break;
+      continue;
+    }
+
+    if (!line.trim().startsWith('|')) {
+      if (sawTable) break;
+      continue;
+    }
+
+    sawTable = true;
+    const cells = line
+      .trim()
+      .split('|')
+      .slice(1, -1)
+      .map((cell) => cell.trim());
+
+    if (cells.length === 0 || isMarkdownSeparatorRow(cells)) {
+      continue;
+    }
+
+    rows.push(cells);
+  }
+
+  const requirementRows = rows.filter((cells) => {
+    const reqId = cells[0] || '';
+    return reqId && !/^\(QA fills this from ROADMAP\.md\)$/i.test(reqId);
+  });
+
+  if (requirementRows.length === 0) {
+    return {
+      ok: false,
+      reason: 'Acceptance matrix has no real requirement verdict rows. Replace the scaffold placeholder with QA-owned requirement results before requesting ship approval.',
+    };
+  }
+
+  const failingRows = [];
+  for (const cells of requirementRows) {
+    const reqId = cells[0] || '<unknown>';
+    const status = cells[cells.length - 1] || '';
+    const normalizedStatus = status ? normalizeToken(status) : '';
+    if (!AFFIRMATIVE_ACCEPTANCE_STATUSES.has(normalizedStatus)) {
+      failingRows.push(`${reqId}=${status || 'missing'}`);
+    }
+  }
+
+  if (failingRows.length > 0) {
+    return {
+      ok: false,
+      reason: `Acceptance matrix still has non-passing requirement rows in .planning/acceptance-matrix.md: ${failingRows.join(', ')}. Mark every requirement row with a passing Status before requesting ship approval.`,
+    };
+  }
+
+  return { ok: true };
+}
+
+const IMPLEMENTATION_NOTES_PLACEHOLDER = /^\(Dev fills this during implementation\)$/i;
+
+function hasSectionContent(content, sectionHeader) {
+  const lines = content.split(/\r?\n/);
+  const headerIndex = lines.findIndex((line) => line.trim().startsWith(sectionHeader));
+  if (headerIndex === -1) {
+    return { found: false, hasContent: false };
+  }
+
+  for (let i = headerIndex + 1; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (line.startsWith('## ')) break;
+    if (!line) continue;
+    if (IMPLEMENTATION_NOTES_PLACEHOLDER.test(line)) continue;
+    return { found: true, hasContent: true };
+  }
+
+  return { found: true, hasContent: false };
+}
+
+function evaluateImplementationNotes(content) {
+  const changes = hasSectionContent(content, '## Changes');
+  const verification = hasSectionContent(content, '## Verification');
+
+  const missingSections = [];
+  if (!changes.found) missingSections.push('## Changes');
+  if (!verification.found) missingSections.push('## Verification');
+
+  if (missingSections.length > 0) {
+    return {
+      ok: false,
+      reason: `.planning/IMPLEMENTATION_NOTES.md must define ${missingSections.join(' and ')} before implementation can exit.`,
+    };
+  }
+
+  const emptySections = [];
+  if (!changes.hasContent) emptySections.push('## Changes');
+  if (!verification.hasContent) emptySections.push('## Verification');
+
+  if (emptySections.length > 0) {
+    return {
+      ok: false,
+      reason: `${emptySections.join(' and ')} in .planning/IMPLEMENTATION_NOTES.md still contains only placeholder text. Dev must replace placeholder content with real implementation notes.`,
+    };
+  }
+
+  return { ok: true };
+}
+
+const RELEASE_NOTES_PLACEHOLDER = /^\(QA fills this during the QA phase\)$/i;
+
+function hasReleaseNotesSectionContent(content, sectionHeader) {
+  const lines = content.split(/\r?\n/);
+  const headerIndex = lines.findIndex((line) => line.trim().startsWith(sectionHeader));
+  if (headerIndex === -1) {
+    return { found: false, hasContent: false };
+  }
+
+  for (let i = headerIndex + 1; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (line.startsWith('## ')) break;
+    if (!line) continue;
+    if (RELEASE_NOTES_PLACEHOLDER.test(line)) continue;
+    return { found: true, hasContent: true };
+  }
+
+  return { found: true, hasContent: false };
+}
+
+function evaluateReleaseNotes(content) {
+  const userImpact = hasReleaseNotesSectionContent(content, '## User Impact');
+  const verificationSummary = hasReleaseNotesSectionContent(content, '## Verification Summary');
+
+  const missingSections = [];
+  if (!userImpact.found) missingSections.push('## User Impact');
+  if (!verificationSummary.found) missingSections.push('## Verification Summary');
+
+  if (missingSections.length > 0) {
+    return {
+      ok: false,
+      reason: `.planning/RELEASE_NOTES.md must define ${missingSections.join(' and ')} before ship approval can be requested.`,
+    };
+  }
+
+  const emptySections = [];
+  if (!userImpact.hasContent) emptySections.push('## User Impact');
+  if (!verificationSummary.hasContent) emptySections.push('## Verification Summary');
+
+  if (emptySections.length > 0) {
+    return {
+      ok: false,
+      reason: `${emptySections.join(' and ')} in .planning/RELEASE_NOTES.md still contains only placeholder text. QA must replace placeholder content with real release notes.`,
+    };
+  }
+
+  return { ok: true };
+}
+
 function evaluateShipVerdict(content) {
   const verdict = parseLineValue(content, /^##\s+Verdict\s*:\s*(.+)$/im);
   if (!verdict) {
@@ -71,9 +264,25 @@ export function evaluateWorkflowGateSemantics(root, relPath) {
     return evaluatePmSignoff(content);
   }
 
+  if (relPath === SYSTEM_SPEC_PATH) {
+    return evaluateSystemSpec(content);
+  }
+
+  if (relPath === IMPLEMENTATION_NOTES_PATH) {
+    return evaluateImplementationNotes(content);
+  }
+
+  if (relPath === ACCEPTANCE_MATRIX_PATH) {
+    return evaluateAcceptanceMatrix(content);
+  }
+
   if (relPath === SHIP_VERDICT_PATH) {
     return evaluateShipVerdict(content);
   }
 
+  if (relPath === RELEASE_NOTES_PATH) {
+    return evaluateReleaseNotes(content);
+  }
+
   return null;
 }

package/src/templates/governed/api-service.json

@@ -27,5 +27,12 @@
     "API contract reviewed and endpoints listed",
     "Error cases enumerated with recovery expectations",
     "Verification command covers automated tests or smoke checks"
-  ]
+  ],
+  "system_spec_overlay": {
+    "purpose_guidance": "Describe the API service, its consumers, and the problem it solves. Include the primary use case and why this service exists as a separate boundary.",
+    "interface_guidance": "List the endpoints (method, path, auth), request/response schemas, and backward-compatibility commitments. Reference api-contract.md for the full surface.",
+    "behavior_guidance": "Describe the expected runtime behavior: request lifecycle, caching, rate limiting, and any async processing. Include latency and throughput expectations.",
+    "error_cases_guidance": "List HTTP error responses, upstream dependency failures, auth rejection behavior, and rate-limit enforcement. Reference error-budget.md for failure thresholds.",
+    "acceptance_tests_guidance": "- [ ] API contract endpoints return expected status codes and shapes\n- [ ] Error responses match documented error contract\n- [ ] Auth rejection returns 401/403 with correct body\n- [ ] Operational readiness checklist items verified"
+  }
 }

package/src/templates/governed/cli-tool.json

@@ -26,5 +26,12 @@
     "Command help audited for every user-facing command touched",
     "Install or invocation path checked on the intended runtime",
     "Failure-mode UX reviewed for invalid flags or missing inputs"
-  ]
+  ],
+  "system_spec_overlay": {
+    "purpose_guidance": "Describe the CLI tool, its primary users, and the workflow it enables. Include the core commands and why this tool exists.",
+    "interface_guidance": "List the user-facing commands, flags, and options. Reference command-surface.md for the full command table. Include stdin/stdout/stderr contracts.",
+    "behavior_guidance": "Describe the expected behavior for each primary command, including exit codes, output format (human vs JSON), and safe retry semantics.",
+    "error_cases_guidance": "List invalid-flag handling, missing-input behavior, permission errors, and network failure UX. Include expected error messages and help fallback behavior.",
+    "acceptance_tests_guidance": "- [ ] Primary commands produce expected output and exit codes\n- [ ] Help text is accurate for every user-facing command\n- [ ] Invalid flags and missing inputs produce clear error messages\n- [ ] Install and invocation paths verified on target platforms"
+  }
 }

package/src/templates/governed/library.json

@@ -27,5 +27,12 @@
     "Public API surface reviewed and intentionally versioned",
     "Compatibility or migration expectations documented for consumers",
     "Install/import or package-consumer smoke path verified"
-  ]
+  ],
+  "system_spec_overlay": {
+    "purpose_guidance": "Describe the library, its consumers, and the capability it provides. Include the primary export surface and why this is a separate package.",
+    "interface_guidance": "List the public exports, import paths, and stable vs experimental surface. Reference public-api.md for the full consumer contract.",
+    "behavior_guidance": "Describe the expected behavior of the public API: input/output contracts, side effects, thread safety, and performance characteristics.",
+    "error_cases_guidance": "List invalid-input handling, type errors at the consumer boundary, and breaking-change scenarios. Reference compatibility-policy.md for deprecation paths.",
+    "acceptance_tests_guidance": "- [ ] Public API exports match documented surface\n- [ ] Consumer install and import smoke check passes\n- [ ] Breaking changes have deprecation path documented\n- [ ] Supported runtime versions verified"
+  }
 }

package/src/templates/governed/web-app.json

@@ -26,5 +26,12 @@
     "Primary user flow reviewed end to end",
     "Mobile and desktop behavior checked explicitly",
     "Accessibility or copy regressions noted before ship request"
-  ]
+  ],
+  "system_spec_overlay": {
+    "purpose_guidance": "Describe the web application, its target users, and the primary user flow it enables. Include the core screens and why this product exists.",
+    "interface_guidance": "List the user-facing screens, routes, and interactive elements. Reference user-flows.md for the full flow map. Include auth and navigation contracts.",
+    "behavior_guidance": "Describe the expected behavior of primary user flows: page load sequence, state management, real-time updates, and responsive breakpoints.",
+    "error_cases_guidance": "List network failure UX, form validation errors, auth expiry handling, and empty-state rendering. Reference ui-acceptance.md for visual acceptance criteria.",
+    "acceptance_tests_guidance": "- [ ] Primary user flow completes end to end\n- [ ] Mobile and desktop layouts render correctly\n- [ ] Error states and empty states display correctly\n- [ ] Accessibility smoke checks pass (keyboard nav, contrast)"
+  }
 }