agentxchain 0.8.7 → 2.1.1

package/src/lib/validation.js

@@ -1,5 +1,24 @@
 import { existsSync, readFileSync, readdirSync } from 'fs';
 import { join } from 'path';
+import { validateStagedTurnResult, STAGING_PATH } from './turn-result-validator.js';
+import { getActiveTurn } from './governed-state.js';
+
+const DEFAULT_REQUIRED_FILES = [
+  '.planning/PROJECT.md',
+  '.planning/REQUIREMENTS.md',
+  '.planning/ROADMAP.md',
+  '.planning/PM_SIGNOFF.md',
+  '.planning/qa/TEST-COVERAGE.md',
+  '.planning/qa/BUGS.md',
+  '.planning/qa/UX-AUDIT.md',
+  '.planning/qa/ACCEPTANCE-MATRIX.md',
+  '.planning/qa/REGRESSION-LOG.md',
+];
+
+const PROTOCOL_FILES = [
+  'lock.json',
+  'state.json'
+];
 
 export function validateProject(root, config, opts = {}) {
   const mode = opts.mode || 'full';
@@ -9,23 +28,17 @@ export function validateProject(root, config, opts = {}) {
   const errors = [];
   const warnings = [];
 
-  const mustExist = [
-    '.planning/PROJECT.md',
-    '.planning/REQUIREMENTS.md',
-    '.planning/ROADMAP.md',
-    '.planning/PM_SIGNOFF.md',
-    '.planning/qa/TEST-COVERAGE.md',
-    '.planning/qa/BUGS.md',
-    '.planning/qa/UX-AUDIT.md',
-    '.planning/qa/ACCEPTANCE-MATRIX.md',
-    '.planning/qa/REGRESSION-LOG.md',
+  const customRequired = config.rules?.required_files;
+  const planningFiles = Array.isArray(customRequired) ? customRequired : DEFAULT_REQUIRED_FILES;
+
+  const dynamicFiles = [
     talkFile,
-    'state.md',
-    'history.jsonl',
-    'lock.json',
-    'state.json'
+    config.state_file || 'state.md',
+    config.history_file || 'history.jsonl',
   ];
 
+  const mustExist = [...planningFiles, ...dynamicFiles, ...PROTOCOL_FILES];
+
   for (const rel of mustExist) {
     if (!existsSync(join(root, rel))) {
       errors.push(`Missing required file: ${rel}`);
@@ -68,6 +81,108 @@ export function validateProject(root, config, opts = {}) {
   return { ok: errors.length === 0, mode, errors, warnings };
 }
 
+export function validateGovernedProject(root, rawConfig, config, opts = {}) {
+  const mode = opts.mode || 'full';
+  const expectedRole = opts.expectedAgent || null;
+  const errors = [];
+  const warnings = [];
+
+  const mustExist = [
+    config.files?.state || '.agentxchain/state.json',
+    config.files?.history || '.agentxchain/history.jsonl',
+  ];
+
+  for (const rel of mustExist) {
+    if (!existsSync(join(root, rel))) {
+      errors.push(`Missing required file: ${rel}`);
+    }
+  }
+
+  const prompts = rawConfig?.prompts && typeof rawConfig.prompts === 'object' ? rawConfig.prompts : {};
+  for (const [roleId, rel] of Object.entries(prompts)) {
+    if (typeof rel !== 'string' || !rel.trim()) {
+      errors.push(`Prompt path for role "${roleId}" must be a non-empty string.`);
+      continue;
+    }
+    if (!existsSync(join(root, rel))) {
+      errors.push(`Missing prompt file for role "${roleId}": ${rel}`);
+    }
+  }
+
+  for (const [gateId, gate] of Object.entries(config.gates || {})) {
+    for (const rel of gate.requires_files || []) {
+      if (!existsSync(join(root, rel))) {
+        errors.push(`Gate "${gateId}" requires missing file: ${rel}`);
+      }
+    }
+  }
+
+  const statePath = join(root, config.files?.state || '.agentxchain/state.json');
+  const state = readJson(statePath);
+  if (!state) {
+    errors.push(`Unable to parse ${config.files?.state || '.agentxchain/state.json'}.`);
+  } else {
+    if (state.phase && config.routing && !config.routing[state.phase]) {
+      errors.push(`State phase "${state.phase}" is not defined in routing.`);
+    }
+
+    if (state.phase_gate_status && typeof state.phase_gate_status === 'object') {
+      for (const gateId of Object.keys(state.phase_gate_status)) {
+        if (!config.gates?.[gateId]) {
+          errors.push(`state.phase_gate_status references unknown gate "${gateId}".`);
+        }
+      }
+    }
+
+    if (mode === 'turn') {
+      const activeTurn = getActiveTurn(state) || state.current_turn;
+      if (!activeTurn) {
+        errors.push('Governed turn validation requires an active turn.');
+      } else if (expectedRole && activeTurn.assigned_role !== expectedRole) {
+        errors.push(`Current turn role "${activeTurn.assigned_role}" does not match expected "${expectedRole}".`);
+      }
+    }
+
+    if (!getActiveTurn(state) && !state.current_turn) {
+      warnings.push('No active turn present in governed state. The run may be idle or paused.');
+    }
+  }
+
+  const historyPath = join(root, config.files?.history || '.agentxchain/history.jsonl');
+  const historyLines = readJsonLines(historyPath);
+  if (historyLines.error) {
+    errors.push(historyLines.error);
+  } else if (historyLines.lines.length === 0) {
+    warnings.push(`${config.files?.history || '.agentxchain/history.jsonl'} has no accepted turn entries yet.`);
+  } else {
+    const last = historyLines.lines[historyLines.lines.length - 1];
+    if (last && typeof last === 'object') {
+      if (!last.turn_id) warnings.push('Last governed history entry has no turn_id.');
+      if (!last.role) warnings.push('Last governed history entry has no role.');
+      if (!last.status) warnings.push('Last governed history entry has no status.');
+    }
+  }
+
+  // ── Staged turn-result validation (the acceptance boundary) ─────────────
+  if (mode === 'turn' && state) {
+    const stagingAbs = join(root, STAGING_PATH);
+    if (!existsSync(stagingAbs)) {
+      warnings.push(`No staged turn result found at ${STAGING_PATH}. Agent has not yet emitted a turn result.`);
+    } else {
+      const turnValidation = validateStagedTurnResult(root, state, config);
+      if (!turnValidation.ok) {
+        errors.push(
+          `Staged turn result failed at stage "${turnValidation.stage}" (${turnValidation.error_class}):`,
+          ...turnValidation.errors.map(e => `  • ${e}`)
+        );
+      }
+      warnings.push(...(turnValidation.warnings || []));
+    }
+  }
+
+  return { ok: errors.length === 0, mode, errors, warnings };
+}
+
 function validatePhaseArtifacts(root) {
   const result = { errors: [], warnings: [] };
   const phasesDir = join(root, '.planning', 'phases');
@@ -98,9 +213,9 @@ function validatePhaseArtifacts(root) {
 
 function validateHistory(root, config, opts) {
   const result = { errors: [], warnings: [] };
-  const historyPath = join(root, 'history.jsonl');
+  const historyPath = join(root, config.history_file || 'history.jsonl');
   if (!existsSync(historyPath)) {
-    result.errors.push('history.jsonl is missing.');
+    result.errors.push(`${config.history_file || 'history.jsonl'} is missing.`);
     return result;
   }
 
@@ -111,9 +226,9 @@ function validateHistory(root, config, opts) {
 
   if (lines.length === 0) {
     if (opts.requireEntry) {
-      result.errors.push('history.jsonl has no entries.');
+      result.errors.push(`${config.history_file || 'history.jsonl'} has no entries.`);
     } else {
-      result.warnings.push('history.jsonl has no entries yet.');
+      result.warnings.push(`${config.history_file || 'history.jsonl'} has no entries yet.`);
     }
     return result;
   }
@@ -123,7 +238,7 @@ function validateHistory(root, config, opts) {
   try {
     last = JSON.parse(lastRaw);
   } catch {
-    result.errors.push('Last history.jsonl entry is not valid JSON.');
+    result.errors.push(`Last ${config.history_file || 'history.jsonl'} entry is not valid JSON.`);
     return result;
   }
 
@@ -203,3 +318,36 @@ function safeReadDir(path) {
     return [];
   }
 }
+
+function readJson(path) {
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function readJsonLines(path) {
+  if (!existsSync(path)) {
+    return { lines: [], error: `${path.split('/').pop()} is missing.` };
+  }
+
+  try {
+    const raw = readFileSync(path, 'utf8');
+    const lines = raw
+      .split(/\r?\n/)
+      .map(line => line.trim())
+      .filter(Boolean)
+      .map((line, index) => {
+        try {
+          return JSON.parse(line);
+        } catch {
+          throw new Error(`Invalid JSONL entry at line ${index + 1}.`);
+        }
+      });
+    return { lines, error: null };
+  } catch (err) {
+    return { lines: [], error: err.message };
+  }
+}

package/src/lib/verify-command.js

@@ -0,0 +1,72 @@
+import { spawnSync } from 'child_process';
+
+export function parseCommandArgs(input) {
+  if (Array.isArray(input)) {
+    return input.filter(part => typeof part === 'string' && part.length > 0);
+  }
+
+  if (typeof input !== 'string' || !input.trim()) {
+    return [];
+  }
+
+  const out = [];
+  let current = '';
+  let quote = null;
+  let escape = false;
+
+  for (const char of input.trim()) {
+    if (escape) {
+      current += char;
+      escape = false;
+      continue;
+    }
+    if (char === '\\') {
+      escape = true;
+      continue;
+    }
+    if (quote) {
+      if (char === quote) {
+        quote = null;
+      } else {
+        current += char;
+      }
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      continue;
+    }
+    if (/\s/.test(char)) {
+      if (current) {
+        out.push(current);
+        current = '';
+      }
+      continue;
+    }
+    current += char;
+  }
+
+  if (current) {
+    out.push(current);
+  }
+
+  return out;
+}
+
+export function runConfiguredVerify(config, root) {
+  const args = parseCommandArgs(config?.rules?.verify_command);
+  if (args.length === 0) {
+    return { ok: true, skipped: true, command: null };
+  }
+
+  const result = spawnSync(args[0], args.slice(1), {
+    cwd: root,
+    stdio: 'inherit'
+  });
+
+  return {
+    ok: result.status === 0,
+    skipped: false,
+    command: args.join(' ')
+  };
+}

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

@@ -0,0 +1,31 @@
+{
+  "id": "api-service",
+  "display_name": "API Service",
+  "description": "Governed scaffold for backend services with explicit API, operational, and failure-budget planning.",
+  "version": "1",
+  "protocol_compatibility": ["1.0", "1.1"],
+  "planning_artifacts": [
+    {
+      "filename": "api-contract.md",
+      "content_template": "# API Contract — {{project_name}}\n\n## Consumers\n- Primary caller:\n- Authentication expectations:\n- Backward-compatibility policy:\n\n## Endpoints\n| Method | Path | Purpose | Auth | Status |\n|--------|------|---------|------|--------|\n| | | | | |\n\n## Error Cases\n| Scenario | HTTP Status | Error Shape | Recovery |\n|----------|-------------|-------------|----------|\n| | | | |\n"
+    },
+    {
+      "filename": "operational-readiness.md",
+      "content_template": "# Operational Readiness — {{project_name}}\n\n## Runtime Dependencies\n- Data stores:\n- Queues / cron jobs:\n- External APIs:\n\n## Observability\n- Required logs:\n- Metrics / alerts:\n- Smoke checks:\n\n## Recovery\n- Rollback plan:\n- On-call notes:\n- Known operational risks:\n"
+    },
+    {
+      "filename": "error-budget.md",
+      "content_template": "# Error Budget — {{project_name}}\n\n## Service Objective\n- Target availability / reliability:\n- Measurement window:\n\n## Failure Modes\n| Failure mode | User impact | Detection | Mitigation |\n|--------------|-------------|-----------|------------|\n| | | | |\n\n## Escalation Thresholds\n- Immediate ship blocker:\n- Needs mitigation before release:\n- Post-release follow-up allowed when:\n"
+    }
+  ],
+  "prompt_overrides": {
+    "pm": "Define the external contract, compatibility expectations, and operational constraints before the team treats the API as ready for implementation.",
+    "dev": "Treat schema changes, API contract drift, and migration safety as first-class implementation risks. Call out any hidden operational coupling.",
+    "qa": "Verify API contract conformance, error handling, auth failures, and rollback safety. Do not sign off without explicit coverage of unhappy paths."
+  },
+  "acceptance_hints": [
+    "API contract reviewed and endpoints listed",
+    "Error cases enumerated with recovery expectations",
+    "Verification command covers automated tests or smoke checks"
+  ]
+}

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

@@ -0,0 +1,30 @@
+{
+  "id": "cli-tool",
+  "display_name": "CLI Tool",
+  "description": "Governed scaffold for command-line tools with command-surface, platform, and distribution planning.",
+  "version": "1",
+  "protocol_compatibility": ["1.0", "1.1"],
+  "planning_artifacts": [
+    {
+      "filename": "command-surface.md",
+      "content_template": "# Command Surface — {{project_name}}\n\n## Primary Commands\n| Command | Purpose | Inputs | Output / Side Effects |\n|---------|---------|--------|------------------------|\n| | | | |\n\n## Flags And Options\n| Command | Flag | Meaning | Default |\n|---------|------|---------|---------|\n| | | | |\n\n## Failure UX\n- Expected error messages:\n- Help / usage fallback:\n- Safe retry behavior:\n"
+    },
+    {
+      "filename": "platform-support.md",
+      "content_template": "# Platform Support — {{project_name}}\n\n## Supported Environments\n- Operating systems:\n- Shells / terminals:\n- Node / runtime versions:\n\n## Compatibility Risks\n| Surface | Risk | Mitigation |\n|---------|------|------------|\n| | | |\n\n## Manual Checks\n- Install path verified on:\n- Non-interactive behavior verified on:\n- Path / permission edge cases:\n"
+    },
+    {
+      "filename": "distribution-checklist.md",
+      "content_template": "# Distribution Checklist — {{project_name}}\n\n## Packaging\n- Package metadata reviewed:\n- Published files audited:\n- Version / changelog ready:\n\n## Install Paths\n- Global install path:\n- Local invocation path:\n- Upgrade / rollback path:\n\n## Release Risks\n- Breaking command changes:\n- Shell completion / docs gaps:\n- Known install blockers:\n"
+    }
+  ],
+  "prompt_overrides": {
+    "dev": "Treat help text, error messaging, shell compatibility, and safe invocation paths as product behavior, not polish.",
+    "qa": "Audit command UX, help output, failure messages, install or invocation paths, and shell/platform compatibility before sign-off."
+  },
+  "acceptance_hints": [
+    "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"
+  ]
+}

package/src/templates/governed/generic.json

@@ -0,0 +1,10 @@
+{
+  "id": "generic",
+  "display_name": "Generic",
+  "description": "Default governed scaffold with the baseline planning artifacts and no project-type-specific guidance.",
+  "version": "1",
+  "protocol_compatibility": ["1.0", "1.1"],
+  "planning_artifacts": [],
+  "prompt_overrides": {},
+  "acceptance_hints": []
+}

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

@@ -0,0 +1,30 @@
+{
+  "id": "web-app",
+  "display_name": "Web App",
+  "description": "Governed scaffold for web products with user-flow, UI, and browser-support planning artifacts.",
+  "version": "1",
+  "protocol_compatibility": ["1.0", "1.1"],
+  "planning_artifacts": [
+    {
+      "filename": "user-flows.md",
+      "content_template": "# User Flows — {{project_name}}\n\n## Primary Flows\n| Flow | User goal | Entry point | Success state |\n|------|-----------|-------------|---------------|\n| | | | |\n\n## Failure And Recovery\n| Flow | Failure state | Recovery path |\n|------|---------------|---------------|\n| | | |\n"
+    },
+    {
+      "filename": "ui-acceptance.md",
+      "content_template": "# UI Acceptance — {{project_name}}\n\n## Screens / States\n| Surface | Happy path expectations | Empty / error states | Notes |\n|---------|-------------------------|----------------------|-------|\n| | | | |\n\n## Accessibility And Copy\n- Keyboard expectations:\n- Contrast / readability notes:\n- Copy review focus:\n"
+    },
+    {
+      "filename": "browser-support.md",
+      "content_template": "# Browser Support — {{project_name}}\n\n## Target Environments\n- Desktop browsers:\n- Mobile browsers:\n- Minimum viewport assumptions:\n\n## Compatibility Risks\n| Browser / device | Risk | Mitigation |\n|------------------|------|------------|\n| | | |\n\n## Smoke Checklist\n- Primary flow works on desktop:\n- Primary flow works on mobile:\n- Known degraded experiences:\n"
+    }
+  ],
+  "prompt_overrides": {
+    "pm": "Define the primary user flows and the minimum browser or device support up front. Vague UX scope will cause downstream churn.",
+    "qa": "Verify primary user flows, responsive behavior, accessibility smoke checks, and copy regressions. Do not treat visual breakage as a minor issue."
+  },
+  "acceptance_hints": [
+    "Primary user flow reviewed end to end",
+    "Mobile and desktop behavior checked explicitly",
+    "Accessibility or copy regressions noted before ship request"
+  ]
+}