agentxchain 2.155.54 → 2.155.56

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "2.155.54",
+  "version": "2.155.56",
   "description": "CLI for AgentXchain — governed multi-agent software delivery",
   "type": "module",
   "bin": {

package/src/lib/dispatch-bundle.js

@@ -498,14 +498,14 @@ function renderPrompt(role, roleId, turn, state, config, root) {
   lines.push('- `files_changed`: **REQUIRED** array of **strings** (file paths only). Do NOT use `files_modified` — the field name is `files_changed`. Do NOT use objects like `{path, change_type}` — just the path string (e.g. `["src/cli.js", "tests/smoke.mjs"]`).');
   lines.push('- `proposed_next_role`: **REQUIRED**. Must be in allowed_next_roles for the current phase, or `"human"`.');
   lines.push('- `decisions[].id`: pattern `DEC-NNN` where NNN is digits only (e.g. `DEC-001`, `DEC-002`). Do NOT use `D1`, `D2`, or freeform IDs.');
-  lines.push('- `decisions[].statement`: non-empty string describing the decision. Do NOT use `decision` or `description` as the field name — the field is `statement`.');
+  lines.push('- `decisions[].statement`: non-empty string describing the decision. Do NOT use `decision`, `description`, or `summary` as the field name — the field is `statement`.');
   lines.push('- `decisions[].rationale`: REQUIRED non-empty string explaining why the decision was made. Do NOT omit this field.');
   lines.push('- `decisions[].category`: one of `implementation`, `architecture`, `scope`, `process`, `quality`, `release`');
   lines.push('- `objections[].id`: pattern `OBJ-NNN` where NNN is digits only (e.g. `OBJ-001`, `OBJ-002`). Do NOT append extra suffixes like `-M31` or use non-numeric characters after `OBJ-`.');
   lines.push('- `objections[].severity`: one of `low`, `medium`, `high`, `blocking`');
   lines.push('- `verification.status`: **REQUIRED**. One of `pass`, `fail`, `skipped`. Always include this field in the `verification` object.');
-  lines.push('- `verification.status: "pass"` is valid only when every `verification.machine_evidence[].exit_code` is `0`');
-  lines.push('- Expected-failure checks must be wrapped in a verifier that exits `0` when the failure occurs as expected; do not list raw non-zero negative-case commands on a passing turn');
+  lines.push('- `verification.status: "pass"` is valid only when every `verification.machine_evidence[].exit_code` is `0`, unless a negative-case command explicitly sets `expected_exit_code` to the same non-zero value.');
+  lines.push('- Expected-failure checks should be wrapped in a verifier that exits `0` when the failure occurs as expected. If you must record a raw non-zero negative-case command on a passing turn, set `verification.machine_evidence[].expected_exit_code` to the expected non-zero code and explain it in `evidence_summary`.');
   lines.push('- If verification commands produce side-effect files (e.g., `.tusq/plan.json`, `coverage/`, `.cache/`), declare each in `verification.produced_files` with `disposition: "ignore"` (temporary output to clean up) or `disposition: "artifact"` (output to checkpoint as a turn deliverable). Undeclared dirty files with declared verification will be auto-cleaned but declaring them is preferred.');
   lines.push('- `artifact.type`: **REQUIRED**. One of `workspace`, `patch`, `commit`, `review`.');
   lines.push('- If you make zero repo file edits, set `artifact.type` to `"review"` and `files_changed` to `[]`.');

package/src/lib/schemas/turn-result.schema.json

@@ -168,7 +168,11 @@
                 "type": "string",
                 "pattern": "\\S"
               },
-              "exit_code": { "type": "integer" }
+              "exit_code": { "type": "integer" },
+              "expected_exit_code": {
+                "type": "integer",
+                "description": "Optional expected exit code for deliberate negative-case verification commands."
+              }
             }
           }
         },

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

@@ -815,16 +815,32 @@ function validateVerification(tr) {
       if (typeof entry.exit_code !== 'number' || !Number.isInteger(entry.exit_code)) {
         errors.push(`verification.machine_evidence[${i}].exit_code must be an integer.`);
       }
+      if ('expected_exit_code' in entry && (typeof entry.expected_exit_code !== 'number' || !Number.isInteger(entry.expected_exit_code))) {
+        errors.push(`verification.machine_evidence[${i}].expected_exit_code must be an integer when provided.`);
+      }
     }
 
-    // If status is pass but any command has non-zero exit code, that's suspicious
+    // If status is pass but any command has non-zero exit code, that is only
+    // valid for explicitly declared expected negative checks.
     if (v.status === 'pass') {
-      const failedCommands = v.machine_evidence.filter(e => typeof e.exit_code === 'number' && e.exit_code !== 0);
+      const failedCommands = v.machine_evidence.filter((entry) => (
+        typeof entry?.exit_code === 'number'
+        && entry.exit_code !== 0
+        && !isExpectedNonZeroMachineEvidence(entry, v.evidence_summary)
+      ));
       if (failedCommands.length > 0) {
         errors.push(
-          `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".`
+          `verification.status is "pass" but ${failedCommands.length} command(s) have non-zero exit codes that are not explicitly declared as expected failures. Set verification.machine_evidence[].expected_exit_code to the expected non-zero code, wrap expected-failure checks in a verifier that exits 0 only when the failure occurs as expected, or do not report "pass".`
         );
       }
+      const expectedNonZeroCommands = v.machine_evidence.filter((entry) => (
+        typeof entry?.exit_code === 'number'
+        && entry.exit_code !== 0
+        && isExpectedNonZeroMachineEvidence(entry, v.evidence_summary)
+      ));
+      if (expectedNonZeroCommands.length > 0) {
+        warnings.push(`verification.status is "pass" with ${expectedNonZeroCommands.length} expected non-zero command(s).`);
+      }
     }
   }
 
@@ -865,6 +881,57 @@ function validateVerification(tr) {
   return { errors, warnings };
 }
 
+function isExpectedNonZeroMachineEvidence(entry, evidenceSummary) {
+  if (!entry || typeof entry !== 'object') {
+    return false;
+  }
+  if (!Number.isInteger(entry.exit_code) || entry.exit_code === 0) {
+    return false;
+  }
+  if (Number.isInteger(entry.expected_exit_code)) {
+    return entry.expected_exit_code === entry.exit_code;
+  }
+  return evidenceSummaryDeclaresExpectedExit(evidenceSummary, entry.command, entry.exit_code);
+}
+
+function evidenceSummaryDeclaresExpectedExit(evidenceSummary, command, exitCode) {
+  if (typeof evidenceSummary !== 'string' || typeof command !== 'string') {
+    return false;
+  }
+  const summary = normalizeEvidenceText(evidenceSummary);
+  const snippets = expectedExitCommandSnippets(command).map(normalizeEvidenceText).filter(Boolean);
+  for (const snippet of snippets) {
+    const index = summary.indexOf(snippet);
+    if (index === -1) {
+      continue;
+    }
+    const window = summary.slice(index, index + snippet.length + 160);
+    if (mentionsExitCode(window, exitCode)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function expectedExitCommandSnippets(command) {
+  const normalized = normalizeEvidenceText(command);
+  const snippets = [normalized];
+  const firstTypeMatch = normalized.match(/(--first-type)\s+([^&|;`\n\r ]+)/i);
+  if (firstTypeMatch) {
+    snippets.push(`${firstTypeMatch[1]} ${firstTypeMatch[2]}`);
+  }
+  return [...new Set(snippets)];
+}
+
+function mentionsExitCode(text, exitCode) {
+  const code = String(exitCode).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(`\\b(?:exit(?:s|ed)?(?:\\s+(?:code|with\\s+code))?|returns?|returned)\\s*${code}\\b`, 'i').test(text);
+}
+
+function normalizeEvidenceText(value) {
+  return String(value).replace(/\s+/g, ' ').trim();
+}
+
 // ── Stage E: Protocol Compliance ─────────────────────────────────────────────
 
 function validateProtocol(tr, state, config) {
@@ -1213,13 +1280,15 @@ export function normalizeTurnResult(tr, config, context = {}) {
         patched = { ...patched, id: normalizedDecId };
       }
 
-      // Normalize missing statement from decision/description field
+      // Normalize missing statement from unambiguous decision text fields.
       const stmt = typeof patched.statement === 'string' ? patched.statement.trim() : '';
       if (!stmt) {
         const alt = typeof patched.decision === 'string' ? patched.decision.trim()
-          : typeof patched.description === 'string' ? patched.description.trim() : '';
+          : typeof patched.description === 'string' ? patched.description.trim()
+            : typeof patched.summary === 'string' ? patched.summary.trim() : '';
         if (alt) {
-          const srcField = typeof patched.decision === 'string' && patched.decision.trim() ? 'decision' : 'description';
+          const srcField = typeof patched.decision === 'string' && patched.decision.trim() ? 'decision'
+            : typeof patched.description === 'string' && patched.description.trim() ? 'description' : 'summary';
           corrections.push(`decisions[${index}].statement: copied from ${srcField}`);
           normalizationEvents.push({
             field: `decisions[${index}].statement`,