agentxchain 2.17.0 → 2.19.0

package/src/lib/governed-state.js

@@ -32,7 +32,7 @@ import {
   checkCleanBaseline,
 } from './repo-observer.js';
 import { getMaxConcurrentTurns } from './normalized-config.js';
-import { getTurnStagingResultPath, getTurnStagingDir, getDispatchTurnDir } from './turn-paths.js';
+import { getTurnStagingResultPath, getTurnStagingDir, getDispatchTurnDir, getReviewArtifactPath } from './turn-paths.js';
 import { runHooks } from './hook-runner.js';
 import { emitNotifications } from './notification-runner.js';
 
@@ -77,6 +77,84 @@ function emitPendingLifecycleNotification(root, config, state, eventType, payloa
   emitNotifications(root, config, state, eventType, payload, turn);
 }
 
+function normalizeDerivedReviewPath(turnResult) {
+  const requestedPath = typeof turnResult?.artifact?.ref === 'string' ? turnResult.artifact.ref.trim() : '';
+  if (requestedPath.startsWith('.agentxchain/reviews/')) {
+    return requestedPath;
+  }
+  return getReviewArtifactPath(turnResult.turn_id, turnResult.role);
+}
+
+function renderDerivedReviewArtifact(turnResult, state) {
+  const lines = [];
+  lines.push(`# Review Artifact — ${turnResult.role}`);
+  lines.push('');
+  lines.push(`- **Run:** ${turnResult.run_id}`);
+  lines.push(`- **Turn:** ${turnResult.turn_id}`);
+  lines.push(`- **Phase:** ${state.phase}`);
+  lines.push(`- **Status:** ${turnResult.status}`);
+  lines.push(`- **Proposed next role:** ${turnResult.proposed_next_role || 'human'}`);
+  lines.push('');
+  lines.push('## Summary');
+  lines.push('');
+  lines.push(turnResult.summary || 'No summary provided.');
+  lines.push('');
+  lines.push('## Decisions');
+  lines.push('');
+  if (Array.isArray(turnResult.decisions) && turnResult.decisions.length > 0) {
+    for (const decision of turnResult.decisions) {
+      lines.push(`- **${decision.id}** (${decision.category}): ${decision.statement}`);
+      if (decision.rationale) {
+        lines.push(`  - Rationale: ${decision.rationale}`);
+      }
+    }
+  } else {
+    lines.push('- None.');
+  }
+  lines.push('');
+  lines.push('## Objections');
+  lines.push('');
+  if (Array.isArray(turnResult.objections) && turnResult.objections.length > 0) {
+    for (const objection of turnResult.objections) {
+      lines.push(`- **${objection.id}** (${objection.severity}): ${objection.statement}`);
+      if (objection.status) {
+        lines.push(`  - Status: ${objection.status}`);
+      }
+    }
+  } else {
+    lines.push('- None.');
+  }
+  lines.push('');
+  lines.push('## Verification');
+  lines.push('');
+  lines.push(`- **Status:** ${turnResult.verification?.status || 'skipped'}`);
+  if (turnResult.verification?.evidence_summary) {
+    lines.push(`- **Summary:** ${turnResult.verification.evidence_summary}`);
+  }
+  if (turnResult.needs_human_reason) {
+    lines.push(`- **Needs human reason:** ${turnResult.needs_human_reason}`);
+  }
+  lines.push('');
+  return lines.join('\n') + '\n';
+}
+
+function materializeDerivedReviewArtifact(root, turnResult, state, runtimeType, baseline = null) {
+  if (turnResult?.artifact?.type !== 'review' || runtimeType !== 'api_proxy') {
+    return null;
+  }
+
+  const reviewPath = normalizeDerivedReviewPath(turnResult);
+  const absReviewPath = join(root, reviewPath);
+  mkdirSync(dirname(absReviewPath), { recursive: true });
+
+  if (!existsSync(absReviewPath)) {
+    writeFileSync(absReviewPath, renderDerivedReviewArtifact(turnResult, state));
+  }
+
+  turnResult.artifact = { ...(turnResult.artifact || {}), ref: reviewPath };
+  return reviewPath;
+}
+
 function normalizeActiveTurns(activeTurns) {
   if (!activeTurns || typeof activeTurns !== 'object' || Array.isArray(activeTurns)) {
     return {};
@@ -1503,11 +1581,13 @@ function _acceptGovernedTurnLocked(root, config, opts) {
   const runtimeId = turnResult.runtime_id;
   const runtime = config.runtimes?.[runtimeId];
   const runtimeType = runtime?.type || 'manual';
+  materializeDerivedReviewArtifact(root, turnResult, state, runtimeType, baseline);
   const writeAuthority = role?.write_authority || 'review_only';
   const diffComparison = compareDeclaredVsObserved(
     turnResult.files_changed || [],
     observation.files_changed,
     writeAuthority,
+    { observation_available: observation.observation_available },
   );
   if (diffComparison.errors.length > 0) {
     return {

package/src/lib/repo-observer.js

@@ -39,6 +39,15 @@ const ORCHESTRATOR_STATE_FILES = [
   '.agentxchain/lock.json',
   '.agentxchain/hook-audit.jsonl',
   '.agentxchain/hook-annotations.jsonl',
+  'TALK.md',
+];
+
+// Evidence paths may legitimately remain dirty across turns without blocking the
+// next code-writing assignment. They still remain actor-observable so review
+// accountability is preserved during acceptance.
+const BASELINE_EXEMPT_PATH_PREFIXES = [
+  '.agentxchain/reviews/',
+  '.agentxchain/reports/',
 ];
 
 /**
@@ -50,6 +59,11 @@ export function isOperationalPath(filePath) {
     || ORCHESTRATOR_STATE_FILES.includes(filePath);
 }
 
+function isBaselineExemptPath(filePath) {
+  return isOperationalPath(filePath)
+    || BASELINE_EXEMPT_PATH_PREFIXES.some(prefix => filePath.startsWith(prefix));
+}
+
 // ── Baseline Capture ────────────────────────────────────────────────────────
 
 /**
@@ -57,6 +71,10 @@ export function isOperationalPath(filePath) {
  * This gives acceptance a stable "before" view.
  *
  * @param {string} root — project root directory
+ * clean is actor-facing baseline cleanliness, not literal `git status` emptiness.
+ * dirty_snapshot may still contain baseline-exempt evidence paths so later
+ * observation can filter unchanged pre-existing dirt.
+ *
  * @returns {{ kind: string, head_ref: string|null, clean: boolean, captured_at: string }}
  */
 export function captureBaseline(root) {
@@ -73,14 +91,15 @@ export function captureBaseline(root) {
   }
 
   const headRef = getHeadRef(root);
-  const clean = isWorkingTreeClean(root);
+  const dirtyFiles = getWorkingTreeChanges(root);
+  const clean = dirtyFiles.filter((filePath) => !isBaselineExemptPath(filePath)).length === 0;
 
   return {
     kind: 'git_worktree',
     head_ref: headRef,
     clean,
     captured_at: now,
-    dirty_snapshot: clean ? {} : captureDirtyWorkspaceSnapshot(root),
+    dirty_snapshot: dirtyFiles.length === 0 ? {} : captureDirtyWorkspaceSnapshot(root),
   };
 }
 
@@ -92,12 +111,18 @@ export function captureBaseline(root) {
  *
  * @param {string} root — project root directory
  * @param {object} baseline — the baseline captured at assignment time
- * @returns {{ files_changed: string[], head_ref: string|null, diff_summary: string|null }}
+ * @returns {{ files_changed: string[], head_ref: string|null, diff_summary: string|null, observation_available: boolean, kind: string }}
  */
 export function observeChanges(root, baseline) {
   if (!isGitRepo(root) || (baseline && baseline.kind === 'no_git')) {
     // Non-git project — no observation possible
-    return { files_changed: [], head_ref: null, diff_summary: null };
+    return {
+      files_changed: [],
+      head_ref: null,
+      diff_summary: null,
+      observation_available: false,
+      kind: 'no_git',
+    };
   }
 
   const currentHead = getHeadRef(root);
@@ -111,7 +136,6 @@ export function observeChanges(root, baseline) {
   if (baseline?.head_ref && baseline.head_ref === currentHead) {
     // Same commit — changes are in working tree / staging area
     changedFiles = getWorkingTreeChanges(root);
-    changedFiles = filterBaselineDirtyFiles(root, changedFiles, baseline);
     diffSummary = buildObservedDiffSummary(getWorkingTreeDiffSummary(root), untrackedFiles);
   } else if (baseline?.head_ref) {
     // New commits exist — get files changed since baseline ref
@@ -128,6 +152,8 @@ export function observeChanges(root, baseline) {
     diffSummary = buildObservedDiffSummary(getWorkingTreeDiffSummary(root), untrackedFiles);
   }
 
+  changedFiles = filterBaselineDirtyFiles(root, changedFiles, baseline);
+
   // Filter out orchestrator-owned operational paths (Session #19 freeze)
   const actorFiles = changedFiles.filter(f => !isOperationalPath(f));
 
@@ -135,6 +161,8 @@ export function observeChanges(root, baseline) {
     files_changed: actorFiles.sort(),
     head_ref: currentHead,
     diff_summary: diffSummary,
+    observation_available: true,
+    kind: 'git_observed',
   };
 }
 
@@ -322,11 +350,13 @@ export function normalizeVerification(verification, runtimeType) {
  * @param {string[]} declared — files_changed from the turn result
  * @param {string[]} observed — files_changed from observeChanges()
  * @param {string} writeAuthority — 'authoritative' | 'proposed' | 'review_only'
+ * @param {{ observation_available?: boolean }} [options]
  * @returns {{ errors: string[], warnings: string[] }}
  */
-export function compareDeclaredVsObserved(declared, observed, writeAuthority) {
+export function compareDeclaredVsObserved(declared, observed, writeAuthority, options = {}) {
   const errors = [];
   const warnings = [];
+  const observationAvailable = options.observation_available !== false;
 
   const declaredSet = new Set(declared || []);
   const observedSet = new Set(observed || []);
@@ -336,6 +366,11 @@ export function compareDeclaredVsObserved(declared, observed, writeAuthority) {
   // Files the agent declared but didn't actually change
   const phantom = [...declaredSet].filter(f => !observedSet.has(f));
 
+  if (!observationAvailable) {
+    warnings.push('Artifact observation unavailable; diff-based declared-vs-observed checks were skipped.');
+    return { errors, warnings };
+  }
+
   if (writeAuthority === 'authoritative') {
     if (undeclared.length > 0) {
       errors.push(`Undeclared file changes detected (observed but not in files_changed): ${undeclared.join(', ')}`);
@@ -351,6 +386,9 @@ export function compareDeclaredVsObserved(declared, observed, writeAuthority) {
     if (productFileChanges.length > 0) {
       errors.push(`review_only role modified product files (observed in actual diff): ${productFileChanges.join(', ')}`);
     }
+    if (phantom.length > 0) {
+      errors.push(`review_only role declared file changes that were not observed in the actual diff: ${phantom.join(', ')}`);
+    }
   }
 
   return { errors, warnings };
@@ -407,10 +445,10 @@ export function checkCleanBaseline(root, writeAuthority) {
     return { clean: true };
   }
 
-  // Check if all dirty files are orchestrator-owned operational paths.
-  // If only operational paths are dirty, the baseline is still clean for actor purposes.
+  // Check if all dirty files are baseline-exempt evidence or orchestrator-owned state.
+  // If only those paths are dirty, the baseline is still clean for actor purposes.
   const dirtyFiles = getWorkingTreeChanges(root);
-  const actorDirtyFiles = dirtyFiles.filter(f => !isOperationalPath(f));
+  const actorDirtyFiles = dirtyFiles.filter(f => !isBaselineExemptPath(f));
 
   if (actorDirtyFiles.length === 0) return { clean: true };
 

package/src/lib/turn-paths.js

@@ -2,6 +2,7 @@ const DISPATCH_ROOT = '.agentxchain/dispatch';
 const DISPATCH_INDEX_PATH = `${DISPATCH_ROOT}/index.json`;
 const DISPATCH_TURNS_DIR = `${DISPATCH_ROOT}/turns`;
 const STAGING_ROOT = '.agentxchain/staging';
+const REVIEW_ROOT = '.agentxchain/reviews';
 
 export function getDispatchTurnDir(turnId) {
   return `${DISPATCH_TURNS_DIR}/${turnId}`;
@@ -59,9 +60,14 @@ export function getTurnRetryTracePath(turnId) {
   return `${getTurnStagingDir(turnId)}/retry-trace.json`;
 }
 
+export function getReviewArtifactPath(turnId, roleId = 'review') {
+  return `${REVIEW_ROOT}/${turnId}-${roleId}-review.md`;
+}
+
 export {
   DISPATCH_ROOT,
   DISPATCH_INDEX_PATH,
   DISPATCH_TURNS_DIR,
+  REVIEW_ROOT,
   STAGING_ROOT,
 };

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

@@ -69,6 +69,25 @@ export function validateStagedTurnResult(root, state, config, opts = {}) {
     return result('schema', 'schema_error', [`Invalid JSON in ${stagingRel}: ${err.message}`]);
   }
 
+  // ── Pre-validation normalization ───────────────────────────────────────
+  // Build context for role/phase-aware normalization rules
+  const normContext = {};
+  if (state) {
+    normContext.phase = state.phase;
+    // Support both active_turns (v2+) and legacy current_turn formats
+    const activeTurn = getActiveTurn(state) || state.current_turn;
+    if (activeTurn) {
+      const roleKey = activeTurn.assigned_role || activeTurn.role;
+      const roleConfig = config?.roles?.[roleKey];
+      if (roleConfig) {
+        normContext.writeAuthority = roleConfig.write_authority;
+      }
+    }
+  }
+  const { normalized, corrections } = normalizeTurnResult(turnResult, config, normContext);
+  turnResult = normalized;
+  const normWarnings = corrections.map((c) => `[normalized] ${c}`);
+
   // ── Stage A: Schema Validation ─────────────────────────────────────────
   const schemaErrors = validateSchema(turnResult);
   if (schemaErrors.length > 0) {
@@ -101,6 +120,7 @@ export function validateStagedTurnResult(root, state, config, opts = {}) {
 
   // ── All stages passed ──────────────────────────────────────────────────
   const allWarnings = [
+    ...normWarnings,
     ...artifactResult.warnings,
     ...verificationResult.warnings,
     ...protocolResult.warnings,
@@ -417,7 +437,7 @@ function validateVerification(tr) {
       const failedCommands = v.machine_evidence.filter(e => typeof e.exit_code === 'number' && e.exit_code !== 0);
       if (failedCommands.length > 0) {
         errors.push(
-          `verification.status is "pass" but ${failedCommands.length} command(s) have non-zero exit codes.`
+          `verification.status is "pass" but ${failedCommands.length} command(s) have non-zero exit codes. Wrap expected-failure checks in a verifier that exits 0 only when the failure occurs as expected, or do not report "pass".`
         );
       }
     }
@@ -480,6 +500,134 @@ function validateProtocol(tr, state, config) {
   return { errors, warnings };
 }
 
+// ── Normalization ───────────────────────────────────────────────────────────
+
+/**
+ * Best-effort normalization of predictable model-output drift patterns.
+ * Returns a shallow-cloned turn result with corrections applied plus an
+ * array of human-readable correction strings for logging.
+ *
+ * This runs BEFORE schema validation. It does not bypass validation —
+ * it only fixes patterns that are unambiguously recoverable.
+ */
+export function normalizeTurnResult(tr, config, context = {}) {
+  const corrections = [];
+  if (tr === null || typeof tr !== 'object' || Array.isArray(tr)) {
+    return { normalized: tr, corrections };
+  }
+
+  const normalized = { ...tr };
+
+  // ── Rule 0: infer missing status only when intent is unambiguous ──────
+  if (!('status' in normalized)) {
+    const hasNeedsHumanReason = typeof normalized.needs_human_reason === 'string'
+      && normalized.needs_human_reason.trim().length > 0;
+    const hasPhaseTransitionRequest = typeof normalized.phase_transition_request === 'string'
+      && normalized.phase_transition_request.trim().length > 0;
+    const hasRunCompletionRequest = normalized.run_completion_request === true;
+
+    if (hasNeedsHumanReason) {
+      normalized.status = 'needs_human';
+      corrections.push('status: inferred "needs_human" from needs_human_reason');
+    } else if (hasPhaseTransitionRequest) {
+      normalized.status = 'completed';
+      corrections.push(`status: inferred "completed" from phase_transition_request "${normalized.phase_transition_request}"`);
+    } else if (hasRunCompletionRequest) {
+      normalized.status = 'completed';
+      corrections.push('status: inferred "completed" from run_completion_request: true');
+    }
+  }
+
+  // ── Rule 1: artifacts_created object coercion ─────────────────────────
+  if (Array.isArray(normalized.artifacts_created)) {
+    const coerced = [];
+    for (let i = 0; i < normalized.artifacts_created.length; i++) {
+      const item = normalized.artifacts_created[i];
+      if (typeof item === 'string') {
+        coerced.push(item);
+      } else if (item !== null && typeof item === 'object') {
+        const str = typeof item.path === 'string' ? item.path
+          : typeof item.name === 'string' ? item.name
+          : JSON.stringify(item);
+        corrections.push(`artifacts_created[${i}]: coerced object to string "${str}"`);
+        coerced.push(str);
+      } else {
+        coerced.push(item); // let validator catch non-string/non-object
+      }
+    }
+    normalized.artifacts_created = coerced;
+  }
+
+  // ── Rule 2: exit-gate-as-phase auto-correction ────────────────────────
+  const routing = config?.routing;
+  const gates = config?.gates;
+  if (
+    typeof normalized.phase_transition_request === 'string' &&
+    routing && gates &&
+    !normalized.run_completion_request // don't touch if both are set — let mutual-exclusivity validator catch it
+  ) {
+    const requested = normalized.phase_transition_request;
+    const isValidPhase = requested in routing;
+    const isGateName = requested in gates;
+
+    if (!isValidPhase && isGateName) {
+      // Find which phase owns this gate
+      const phaseNames = Object.keys(routing);
+      const ownerPhaseIndex = phaseNames.findIndex(
+        (p) => routing[p].exit_gate === requested
+      );
+
+      if (ownerPhaseIndex >= 0) {
+        const nextPhaseIndex = ownerPhaseIndex + 1;
+        if (nextPhaseIndex < phaseNames.length) {
+          // Non-terminal phase: correct to the next phase name
+          const nextPhase = phaseNames[nextPhaseIndex];
+          corrections.push(
+            `phase_transition_request: corrected gate name "${requested}" to phase "${nextPhase}"`
+          );
+          normalized.phase_transition_request = nextPhase;
+        } else {
+          // Terminal phase: the agent meant run_completion_request
+          corrections.push(
+            `phase_transition_request: corrected terminal gate name "${requested}" to run_completion_request: true`
+          );
+          normalized.phase_transition_request = null;
+          normalized.run_completion_request = true;
+        }
+      }
+    }
+  }
+
+  // ── Rule 3: review_only terminal needs_human → run_completion_request ──
+  if (
+    context.writeAuthority === 'review_only' &&
+    context.phase &&
+    routing &&
+    normalized.status === 'needs_human' &&
+    normalized.run_completion_request !== false
+  ) {
+    const phaseNames = Object.keys(routing);
+    const isTerminal = phaseNames.indexOf(context.phase) === phaseNames.length - 1;
+    if (isTerminal && typeof normalized.needs_human_reason === 'string') {
+      const reason = normalized.needs_human_reason.toLowerCase();
+      const affirmativeSignals = /\b(approv|ship|release|sign.?off|no.?block|ready|pass|good|accept|green.?light)\b/i;
+      const blockerSignals = /\b(critical|security|fail|block|cannot|must.?fix|regression|vulnerab|reject|unsafe|broken)\b/i;
+      const isAffirmative = affirmativeSignals.test(reason);
+      const isBlocker = blockerSignals.test(reason);
+      if (isAffirmative && !isBlocker) {
+        corrections.push(
+          `status: corrected review_only terminal "needs_human" to run_completion_request — reason indicated ship readiness ("${normalized.needs_human_reason.slice(0, 80)}"), not a genuine blocker`
+        );
+        normalized.status = 'completed';
+        normalized.run_completion_request = true;
+        delete normalized.needs_human_reason;
+      }
+    }
+  }
+
+  return { normalized, corrections };
+}
+
 // ── Helpers ──────────────────────────────────────────────────────────────────
 
 function result(stage, errorClass, errors, warnings = []) {