agentxchain 2.155.72 → 2.156.0

package/src/lib/turn-result-validator.js

@@ -138,7 +138,7 @@ export function validateStagedTurnResult(root, state, config, opts = {}) {
   }
 
   // ── Stage C: Artifact Validation ───────────────────────────────────────
-  const artifactResult = validateArtifact(turnResult, config);
+  const artifactResult = validateArtifact(turnResult, config, state);
   if (artifactResult.errors.length > 0) {
     return result('artifact', 'artifact_error', artifactResult.errors, artifactResult.warnings);
   }
@@ -670,7 +670,7 @@ function validateAssignment(tr, state) {
 
 // ── Stage C: Artifact Validation ─────────────────────────────────────────────
 
-function validateArtifact(tr, config) {
+function validateArtifact(tr, config, state = null) {
   const errors = [];
   const warnings = [];
 
@@ -699,6 +699,11 @@ function validateArtifact(tr, config) {
         `Artifact type "workspace" requires authoritative write authority, but role "${tr.role}" has "${writeAuthority}".`
       );
     }
+    if ((tr.files_changed || []).length === 0 && !hasCheckpointableProducedFiles(tr)) {
+      errors.push(
+        'artifact.type: "workspace" but files_changed is empty. Use artifact type "review" for no-edit turns, or declare checkpointable verification.produced_files entries with disposition "artifact".'
+      );
+    }
   }
 
   // Check for reserved path modifications
@@ -722,9 +727,17 @@ function validateArtifact(tr, config) {
     }
   }
 
-  // Warn if files_changed is empty for authoritative + completed turns
-  if (writeAuthority === 'authoritative' && tr.status === 'completed' && (tr.files_changed || []).length === 0) {
-    warnings.push('Authoritative role completed with no files_changed — is this intentional?');
+  // Implementation-phase completion must be backed by actual product code
+  // changes. Planning/review artifacts are supplementary and should not satisfy
+  // the implementation_complete gate by themselves.
+  if (writeAuthority === 'authoritative' && state?.phase === 'implementation' && tr.status === 'completed') {
+    const productFiles = (tr.files_changed || []).filter(f => isProductChangePath(f));
+    if (productFiles.length === 0) {
+      errors.push(
+        `Role "${tr.role}" completed an implementation turn without product code changes in files_changed. ` +
+        'Implementation-phase completion requires at least one non-planning, non-review repo path; planning artifacts alone are not sufficient.'
+      );
+    }
   }
 
   // Validate proposed_changes for proposed runtimes that cannot write repo files directly.
@@ -772,6 +785,24 @@ function isAllowedReviewPath(filePath) {
   return filePath.startsWith('.planning/') || filePath.startsWith('.agentxchain/reviews/');
 }
 
+function isProductChangePath(filePath) {
+  return typeof filePath === 'string'
+    && filePath.trim().length > 0
+    && !isAllowedReviewPath(filePath)
+    && !filePath.startsWith('.agentxchain/staging/');
+}
+
+function hasCheckpointableProducedFiles(tr) {
+  return Array.isArray(tr.verification?.produced_files)
+    && tr.verification.produced_files.some((entry) => (
+      entry
+      && typeof entry === 'object'
+      && typeof entry.path === 'string'
+      && entry.path.trim()
+      && (entry.disposition == null || entry.disposition === 'artifact')
+    ));
+}
+
 // ── Stage D: Verification Validation ─────────────────────────────────────────
 
 function validateVerification(tr) {
@@ -1488,7 +1519,17 @@ export function normalizeTurnResult(tr, config, context = {}) {
     && !Array.isArray(normalized.artifact)
     && normalized.artifact.type === 'workspace'
     && filesChangedIsEmpty
-    && (context.forceReviewArtifact || hasExplicitNoEditLifecycleSignal)
+    && !hasCheckpointableProducedFiles(normalized)
+    && (
+      context.forceReviewArtifact
+      || hasExplicitNoEditLifecycleSignal
+      // review_only roles (PM/QA) legitimately produce no-edit reviews — an empty
+      // workspace from a COMPLETED review_only turn normalizes to a review. Authoritative
+      // /code-writing roles claiming a completed workspace artifact with no files stay
+      // fail-closed, and non-completed (blocked/failed) turns never normalize (BUG-78).
+      || (isReviewOnly && normalized.status === 'completed')
+      || (normalized.status === 'needs_human' && normalized.proposed_next_role === 'human')
+    )
   ) {
     normalized.artifact = {
       ...normalized.artifact,

package/src/lib/validation.js

@@ -2,6 +2,7 @@ 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';
+import { getTurnStagingResultPath } from './turn-paths.js';
 import {
   validateGovernedProjectTemplate,
   validateGovernedTemplateRegistry,
@@ -191,11 +192,18 @@ export function validateGovernedProject(root, rawConfig, config, opts = {}) {
 
   // ── Staged turn-result validation (the acceptance boundary) ─────────────
   if (mode === 'turn' && state) {
-    const stagingAbs = join(root, STAGING_PATH);
+    // RB-12: prefer the turn-scoped staging path for the active turn; the shared
+    // legacy path is only a fallback. Reading the legacy path unconditionally
+    // made `validate --mode turn` look at the wrong file and falsely report a
+    // missing turn result for turns staged at the turn-scoped path.
+    const activeTurn = getActiveTurn(state) || state.current_turn || null;
+    const turnScoped = activeTurn?.turn_id ? getTurnStagingResultPath(activeTurn.turn_id) : null;
+    const stagingRel = (turnScoped && existsSync(join(root, turnScoped))) ? turnScoped : STAGING_PATH;
+    const stagingAbs = join(root, stagingRel);
     if (!existsSync(stagingAbs)) {
-      warnings.push(`No staged turn result found at ${STAGING_PATH}. Agent has not yet emitted a turn result.`);
+      warnings.push(`No staged turn result found at ${stagingRel}. Agent has not yet emitted a turn result.`);
     } else {
-      const turnValidation = validateStagedTurnResult(root, state, config);
+      const turnValidation = validateStagedTurnResult(root, state, config, { stagingPath: stagingRel });
       if (!turnValidation.ok) {
         errors.push(
           `Staged turn result failed at stage "${turnValidation.stage}" (${turnValidation.error_class}):`,

package/src/lib/verification-replay.js

@@ -8,7 +8,7 @@ import { isOperationalPath } from './repo-observer.js';
 
 export const DEFAULT_VERIFICATION_REPLAY_TIMEOUT_MS = 30_000;
 
-export function replayVerificationMachineEvidence({ root, verification, timeoutMs = DEFAULT_VERIFICATION_REPLAY_TIMEOUT_MS }) {
+export function replayVerificationMachineEvidence({ root, verification, timeoutMs = DEFAULT_VERIFICATION_REPLAY_TIMEOUT_MS, allowCommandExecution = false }) {
   const verifiedAt = new Date().toISOString();
   const machineEvidence = Array.isArray(verification?.machine_evidence)
     ? verification.machine_evidence
@@ -28,6 +28,27 @@ export function replayVerificationMachineEvidence({ root, verification, timeoutM
     return payload;
   }
 
+  // SECURITY (verification-replay hardening): agent-declared machine_evidence
+  // commands are UNTRUSTED. Fail-safe default — they are recorded but NOT executed
+  // unless the operator has explicitly opted in (allowCommandExecution). When
+  // executed, they never run through a shell (see replayEvidenceCommand).
+  if (!allowCommandExecution) {
+    payload.overall = 'not_executed';
+    payload.reason = 'Command replay disabled: agent-declared verification commands are not executed unless explicitly enabled by the operator.';
+    payload.commands = machineEvidence.map((entry, index) => ({
+      index,
+      command: entry?.command ?? null,
+      declared_exit_code: entry?.exit_code,
+      actual_exit_code: null,
+      matched: false,
+      executed: false,
+      timed_out: false,
+      signal: null,
+      error: null,
+    }));
+    return payload;
+  }
+
   const workspaceGuard = createReplayWorkspaceGuard(root);
   try {
     payload.commands = machineEvidence.map((entry, index) => replayEvidenceCommand(root, entry, index, timeoutMs));
@@ -41,11 +62,33 @@ export function replayVerificationMachineEvidence({ root, verification, timeoutM
   return payload;
 }
 
+// SECURITY: agent-declared commands are NEVER run through a shell. The command is
+// resolved to an argv vector and executed with shell:false, so shell metacharacters
+// (; | && $() backticks globs) cannot chain, pipe, expand, or substitute. (A single
+// declared binary still runs on the host — that is gated by the explicit
+// allowCommandExecution opt-in upstream; a future sandbox/allowlist can constrain
+// which binaries are permitted.)
 export function replayEvidenceCommand(root, entry, index, timeoutMs = DEFAULT_VERIFICATION_REPLAY_TIMEOUT_MS) {
-  const result = spawnSync(entry.command, {
+  const argv = resolveEvidenceArgv(entry);
+  if (argv.length === 0) {
+    return {
+      index,
+      command: entry?.command ?? null,
+      declared_exit_code: entry?.exit_code,
+      actual_exit_code: null,
+      matched: false,
+      executed: false,
+      timed_out: false,
+      signal: null,
+      error: 'No executable command or argv vector could be resolved for this evidence entry.',
+    };
+  }
+
+  const [file, ...args] = argv;
+  const result = spawnSync(file, args, {
     cwd: root,
     encoding: 'utf8',
-    shell: true,
+    shell: false,
     timeout: timeoutMs,
     maxBuffer: 1024 * 1024,
   });
@@ -56,16 +99,94 @@ export function replayEvidenceCommand(root, entry, index, timeoutMs = DEFAULT_VE
 
   return {
     index,
-    command: entry.command,
+    command: entry.command ?? argv.join(' '),
     declared_exit_code: entry.exit_code,
     actual_exit_code: actualExitCode,
     matched: actualExitCode === entry.exit_code,
+    executed: true,
     timed_out: timedOut,
     signal: result.signal || null,
     error: errorMessage,
   };
 }
 
+// Resolve an evidence entry to an argv vector for shell-free execution.
+// Prefers a structured `argv` string array; falls back to safe-tokenizing `command`.
+export function resolveEvidenceArgv(entry) {
+  if (Array.isArray(entry?.argv) && entry.argv.length > 0 && entry.argv.every((a) => typeof a === 'string')) {
+    return entry.argv.slice();
+  }
+  if (typeof entry?.command === 'string' && entry.command.trim()) {
+    return tokenizeCommand(entry.command.trim());
+  }
+  return [];
+}
+
+// Minimal SAFE tokenizer: splits on whitespace, honoring single and double quotes
+// and backslash escapes (so e.g. `node -e "{\"ok\":true}"` keeps its escaped quotes).
+// Performs NO shell expansion — variables, globs, pipes, chaining, and command
+// substitution are preserved as literal characters, never interpreted.
+export function tokenizeCommand(command) {
+  if (typeof command !== 'string') {
+    return [];
+  }
+  const tokens = [];
+  let current = '';
+  let hasToken = false;
+  let i = 0;
+  const n = command.length;
+  while (i < n) {
+    const ch = command[i];
+    if (ch === ' ' || ch === '\t' || ch === '\n' || ch === '\r') {
+      if (hasToken) {
+        tokens.push(current);
+        current = '';
+        hasToken = false;
+      }
+      i += 1;
+      continue;
+    }
+    hasToken = true;
+    if (ch === "'") {
+      // Single-quoted: literal run until the next single quote (no escapes, POSIX-style).
+      i += 1;
+      while (i < n && command[i] !== "'") {
+        current += command[i];
+        i += 1;
+      }
+      i += 1; // consume closing quote (or run off the end)
+      continue;
+    }
+    if (ch === '"') {
+      // Double-quoted: backslash escapes only the structural `"` and `\` characters.
+      i += 1;
+      while (i < n && command[i] !== '"') {
+        if (command[i] === '\\' && i + 1 < n && (command[i + 1] === '"' || command[i + 1] === '\\')) {
+          current += command[i + 1];
+          i += 2;
+        } else {
+          current += command[i];
+          i += 1;
+        }
+      }
+      i += 1; // consume closing quote (or run off the end)
+      continue;
+    }
+    if (ch === '\\' && i + 1 < n) {
+      // Bare backslash escape: take the next character literally.
+      current += command[i + 1];
+      i += 2;
+      continue;
+    }
+    current += ch;
+    i += 1;
+  }
+  if (hasToken) {
+    tokens.push(current);
+  }
+  return tokens;
+}
+
 export function summarizeVerificationReplay(payload) {
   if (!payload) {
     return null;

package/src/lib/vision-reader.js

@@ -15,6 +15,18 @@ import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { join, resolve as pathResolve, isAbsolute } from 'node:path';
 import { createHash } from 'node:crypto';
 
+const ROADMAP_TRACKING_ANNOTATION_PATTERN = /<!--\s*tracking\s*:[\s\S]*?-->/i;
+// RB-3: a milestone left unchecked but annotated as delivered/done/shipped is
+// already-built work — skip it so the loop derives genuinely undelivered work
+// instead of re-picking finished items. Distinct from generic comments like
+// `<!-- owner: dev -->`, which stay actionable.
+const ROADMAP_DELIVERED_ANNOTATION_PATTERN = /<!--[^>]*\b(delivered|shipped|implemented|completed|done)\b[^>]*-->/i;
+
+export function stripRoadmapTrackingAnnotations(text) {
+  if (typeof text !== 'string') return '';
+  return text.replace(ROADMAP_TRACKING_ANNOTATION_PATTERN, '').replace(/\s+/g, ' ').trim();
+}
+
 // ---------------------------------------------------------------------------
 // Parsing
 // ---------------------------------------------------------------------------
@@ -259,8 +271,10 @@ export function deriveRoadmapCandidates(root, roadmapPath = '.planning/ROADMAP.m
 
     const uncheckedMatch = line.match(/^\s*[-*]\s+\[\s\]\s+(.+?)\s*$/);
     if (!uncheckedMatch || !currentMilestone) continue;
+    if (ROADMAP_TRACKING_ANNOTATION_PATTERN.test(line) || ROADMAP_DELIVERED_ANNOTATION_PATTERN.test(line)) continue;
 
-    const goal = uncheckedMatch[1].trim();
+    const goal = stripRoadmapTrackingAnnotations(uncheckedMatch[1]);
+    if (!goal) continue;
     const combinedGoal = `${currentMilestone}: ${goal}`;
     if (isGoalAddressed(combinedGoal, allSignals) || isGoalAddressed(goal, allSignals)) {
       continue;
@@ -484,6 +498,7 @@ export function detectRoadmapExhaustedVisionOpen(root, visionPath, roadmapPath =
       continue;
     }
     if (currentMilestone && /^\s*[-*]\s+\[\s\]/.test(line)) {
+      if (ROADMAP_TRACKING_ANNOTATION_PATTERN.test(line) || ROADMAP_DELIVERED_ANNOTATION_PATTERN.test(line)) continue;
       hasUnchecked = true;
     }
   }