agentxchain 2.17.0 → 2.18.0

package/README.md

@@ -59,7 +59,7 @@ agentxchain status
 agentxchain step --role pm
 ```
 
-The default governed dev runtime is `claude --print` with stdin prompt delivery. If your local coding agent uses a different launch contract, set it during scaffold creation:
+The default governed dev runtime is `claude --print --dangerously-skip-permissions` with stdin prompt delivery. The non-interactive governed path needs write access, so do not pretend bare `claude --print` is sufficient for unattended implementation turns. If your local coding agent uses a different launch contract, set it during scaffold creation:
 
 ```bash
 npx agentxchain init --governed --dir my-agentxchain-project --dev-command ./scripts/dev-agent.sh --dev-prompt-transport dispatch_bundle_only -y

package/package.json

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

package/src/commands/init.js

@@ -96,7 +96,7 @@ const GOVERNED_ROLES = {
 
 const DEFAULT_GOVERNED_LOCAL_DEV_RUNTIME = Object.freeze({
   type: 'local_cli',
-  command: ['claude', '--print'],
+  command: ['claude', '--print', '--dangerously-skip-permissions'],
   cwd: '.',
   prompt_transport: 'stdin',
 });
@@ -221,6 +221,8 @@ You are the Developer. Your mandate: **${role.mandate}**
 You must run verification commands and report them honestly:
 - \`verification.status\` must be \`"pass"\` only if all commands exited with code 0
 - \`verification.machine_evidence\` must list every command you ran with its actual exit code
+- Expected-failure checks must be wrapped in a test harness or shell assertion that exits 0 only when the failure occurs as expected
+- Do not mix raw non-zero negative-case commands into a passing turn; put them behind \`npm test\`, \`node --test\`, or an equivalent zero-exit verifier
 - Do NOT claim \`"pass"\` if you did not run the tests
 
 ## Phase Transition
@@ -246,7 +248,7 @@ You are QA. Your mandate: **${role.mandate}**
 1. **Read the previous turn, the ROADMAP, and the acceptance matrix.** Understand what was built and what the acceptance criteria are.
 2. **Challenge the implementation.** You MUST raise at least one objection — this is a protocol requirement for review_only roles. If the code is perfect, challenge the test coverage, the edge cases, or the documentation.
 3. **Evaluate against acceptance criteria.** Go through each criterion and determine pass/fail.
-4. **Create review artifacts:**
+4. **Produce a review outcome:**
    - \`.planning/acceptance-matrix.md\` — updated with pass/fail verdicts per criterion
    - \`.planning/ship-verdict.md\` — your overall ship/no-ship recommendation
    - \`.planning/RELEASE_NOTES.md\` — user-facing release notes with impact and verification summary
@@ -255,6 +257,12 @@ You are QA. Your mandate: **${role.mandate}**
 
 You have \`review_only\` write authority. You may NOT modify product files. You may only create/modify files under \`.planning/\` and \`.agentxchain/reviews/\`. Your artifact type must be \`review\`.
 
+## Runtime Truth
+
+- If your runtime is **manual** or another writable review path, you may update the QA-owned planning files directly.
+- If your runtime is **api_proxy**, you cannot write repo files directly. Do **not** claim you created \`.planning/*\` files unless a writable/manual step actually changed them.
+- For \`api_proxy\` review turns, the orchestrator will materialize a review artifact under \`.agentxchain/reviews/<turn_id>-<role>-review.md\` from your structured result.
+
 ## Objection Requirement
 
 You MUST raise at least one objection in your turn result. An empty \`objections\` array is a protocol violation and will be rejected by the validator. If the work is genuinely excellent, raise a low-severity observation about test coverage, documentation, or future risk.
@@ -275,9 +283,8 @@ Each objection must have:
 ## Ship Verdict & Run Completion
 
 When you are satisfied the work meets acceptance criteria:
-1. Create \`.planning/ship-verdict.md\` with your verdict
-2. Create/update \`.planning/acceptance-matrix.md\` with all criteria checked
-3. Create/update \`.planning/RELEASE_NOTES.md\` with \`## User Impact\` and \`## Verification Summary\`
+1. If you are on a writable/manual review path, create/update the QA-owned planning artifacts with your verdict
+2. If you are on \`api_proxy\`, put the verdict and rationale in the structured turn result and review artifact instead of claiming repo writes you did not make
 4. Set \`run_completion_request: true\` in your turn result
 
 **Only set \`run_completion_request: true\` when:**
@@ -535,7 +542,7 @@ export function scaffoldGoverned(dir, projectName, projectId, templateId = 'gene
   }
 
   // Planning artifacts
-  writeFileSync(join(dir, '.planning', 'PM_SIGNOFF.md'), `# PM Signoff — ${projectName}\n\nApproved: NO\n\n## Discovery Checklist\n- [ ] Target user defined\n- [ ] Core pain point defined\n- [ ] Core workflow defined\n- [ ] MVP scope defined\n- [ ] Out-of-scope list defined\n- [ ] Success metric defined\n\n## Notes for team\n(PM and human add final kickoff notes here.)\n`);
+  writeFileSync(join(dir, '.planning', 'PM_SIGNOFF.md'), `# PM Signoff — ${projectName}\n\nApproved: NO\n\n> This scaffold starts blocked on purpose. Change this to \`Approved: YES\` only after a human reviews the planning artifacts and is ready to open the planning gate.\n\n## Discovery Checklist\n- [ ] Target user defined\n- [ ] Core pain point defined\n- [ ] Core workflow defined\n- [ ] MVP scope defined\n- [ ] Out-of-scope list defined\n- [ ] Success metric defined\n\n## Notes for team\n(PM and human add final kickoff notes here.)\n`);
   writeFileSync(join(dir, '.planning', 'ROADMAP.md'), `# Roadmap — ${projectName}\n\n## Phases\n\n| Phase | Goal | Status |\n|-------|------|--------|\n| Planning | Align scope, requirements, acceptance criteria | In progress |\n| Implementation | Build and verify | Pending |\n| QA | Challenge correctness and ship readiness | Pending |\n`);
   writeFileSync(join(dir, '.planning', 'SYSTEM_SPEC.md'), buildSystemSpecContent(projectName, template.system_spec_overlay));
   writeFileSync(join(dir, '.planning', 'IMPLEMENTATION_NOTES.md'), `# Implementation Notes — ${projectName}\n\n## Changes\n\n(Dev fills this during implementation)\n\n## Verification\n\n(Dev fills this during implementation)\n\n## Unresolved Follow-ups\n\n(Dev lists any known gaps, tech debt, or follow-up items here.)\n`);
@@ -907,7 +914,7 @@ export async function initCommand(opts) {
   writeFileSync(join(dir, '.planning', 'REQUIREMENTS.md'), `# Requirements — ${project}\n\n## v1 (MVP)\n\n(PM fills this: numbered list of requirements. Each requirement has one-sentence acceptance criteria.)\n\n| # | Requirement | Acceptance criteria | Phase | Status |\n|---|-------------|-------------------|-------|--------|\n| 1 | | | | Pending |\n\n## v2 (Future)\n\n(Out of scope for MVP. Captured here so they don't creep in.)\n\n## Out of scope\n\n(Explicitly not building.)\n`);
 
   writeFileSync(join(dir, '.planning', 'ROADMAP.md'), `# Roadmap — ${project}\n\n## Waves\n\n| Wave | Goal | Status |\n|------|------|--------|\n| Wave 1 | Discovery, planning, and phase setup | In progress |\n\n## Phases\n\n| Phase | Description | Status | Requirements |\n|-------|-------------|--------|-------------|\n| 1 | Discovery + setup | In progress | — |\n\n(PM updates this as phases are planned and completed.)\n`);
-  writeFileSync(join(dir, '.planning', 'PM_SIGNOFF.md'), `# PM Signoff — ${project}\n\nApproved: NO\n\n## Discovery Checklist\n- [ ] Target user defined\n- [ ] Core pain point defined\n- [ ] Core workflow defined\n- [ ] MVP scope defined\n- [ ] Out-of-scope list defined\n- [ ] Success metric defined\n\n## Notes for team\n(PM and human add final kickoff notes here.)\n`);
+  writeFileSync(join(dir, '.planning', 'PM_SIGNOFF.md'), `# PM Signoff — ${project}\n\nApproved: NO\n\n> This scaffold starts blocked on purpose. Change this to \`Approved: YES\` only after a human reviews the planning artifacts and is ready to open the planning gate.\n\n## Discovery Checklist\n- [ ] Target user defined\n- [ ] Core pain point defined\n- [ ] Core workflow defined\n- [ ] MVP scope defined\n- [ ] Out-of-scope list defined\n- [ ] Success metric defined\n\n## Notes for team\n(PM and human add final kickoff notes here.)\n`);
 
   // QA structure
   mkdirSync(join(dir, '.planning', 'phases', 'phase-1'), { recursive: true });

package/src/commands/start.js

@@ -40,7 +40,8 @@ export async function startCommand(opts) {
         console.log(chalk.dim(`   - ${e}`));
       }
       console.log('');
-      console.log(chalk.dim('  Suggested next step: complete .planning/PM_SIGNOFF.md and roadmap waves/phases, then run:'));
+      console.log(chalk.dim('  Suggested next step: complete .planning/PM_SIGNOFF.md and roadmap waves/phases.'));
+      console.log(chalk.dim('  Fresh governed scaffolds start at `Approved: NO`; flip that line to `Approved: YES` only after human kickoff approval, then run:'));
       console.log(chalk.bold('    agentxchain validate --mode kickoff'));
       console.log('');
       process.exit(1);

package/src/lib/context-section-parser.js

@@ -7,6 +7,7 @@ const SECTION_DEFINITIONS = [
   { id: 'last_turn_summary', header: null, required: false },
   { id: 'last_turn_decisions', header: null, required: false },
   { id: 'last_turn_objections', header: null, required: false },
+  { id: 'last_turn_verification', header: null, required: false },
   { id: 'blockers', header: 'Blockers', required: true },
   { id: 'escalation', header: 'Escalation', required: true },
   { id: 'gate_required_files', header: 'Gate Required Files', required: false },
@@ -48,12 +49,14 @@ export function parseContextSections(contextMd) {
       summaryLines,
       decisionsLines,
       objectionsLines,
+      verificationLines,
     } = splitLastAcceptedTurn(lastAcceptedTurnBody);
 
     pushSection(parsedSections, 'last_turn_header', headerLines);
     pushSection(parsedSections, 'last_turn_summary', summaryLines);
     pushSection(parsedSections, 'last_turn_decisions', decisionsLines);
     pushSection(parsedSections, 'last_turn_objections', objectionsLines);
+    pushSection(parsedSections, 'last_turn_verification', verificationLines);
   }
 
   for (const [header, id] of HEADER_TO_ID.entries()) {
@@ -80,6 +83,7 @@ export function renderContextSections(sections) {
     sectionMap.get('last_turn_summary')?.content,
     sectionMap.get('last_turn_decisions')?.content,
     sectionMap.get('last_turn_objections')?.content,
+    sectionMap.get('last_turn_verification')?.content,
   ]);
 
   appendTopLevelSection(lines, 'Blockers', [sectionMap.get('blockers')?.content]);
@@ -91,11 +95,20 @@ export function renderContextSections(sections) {
 }
 
 function appendTopLevelSection(lines, header, fragments) {
-  const content = fragments
-    .filter((fragment) => typeof fragment === 'string' && fragment.length > 0)
-    .join('\n');
+  const validFragments = fragments
+    .filter((fragment) => typeof fragment === 'string' && fragment.length > 0);
 
-  if (!content) return;
+  if (validFragments.length === 0) return;
+
+  // Join fragments with a blank-line separator before sub-headings (###)
+  const contentParts = [];
+  for (const fragment of validFragments) {
+    if (contentParts.length > 0 && fragment.startsWith('###')) {
+      contentParts.push('');
+    }
+    contentParts.push(fragment);
+  }
+  const content = contentParts.join('\n');
 
   lines.push(`## ${header}`);
   lines.push('');
@@ -106,9 +119,13 @@ function appendTopLevelSection(lines, header, fragments) {
 function splitTopLevelSections(contextMd) {
   const lines = normalizeNewlines(contextMd).split('\n');
   const sectionStarts = [];
+  let inCodeBlock = false;
 
   for (let index = 0; index < lines.length; index += 1) {
-    if (lines[index].startsWith('## ')) {
+    if (lines[index].startsWith('```')) {
+      inCodeBlock = !inCodeBlock;
+    }
+    if (!inCodeBlock && lines[index].startsWith('## ')) {
       sectionStarts.push(index);
     }
   }
@@ -130,10 +147,30 @@ function splitLastAcceptedTurn(lines) {
   let summaryLines = [];
   let decisionsLines = [];
   let objectionsLines = [];
+  let verificationLines = [];
+
+  let inVerification = false;
 
   for (let index = 0; index < lines.length; index += 1) {
     const line = lines[index];
 
+    if (line.startsWith('### Verification')) {
+      inVerification = true;
+      verificationLines.push(line);
+      continue;
+    }
+
+    if (inVerification) {
+      // A new heading at level 2 or 3 ends the verification block
+      if (line.startsWith('## ') || (line.startsWith('### ') && !line.startsWith('### Verification'))) {
+        inVerification = false;
+        headerLines.push(line);
+        continue;
+      }
+      verificationLines.push(line);
+      continue;
+    }
+
     if (SUMMARY_LINE_PATTERN.test(line)) {
       summaryLines = [line];
       continue;
@@ -161,6 +198,7 @@ function splitLastAcceptedTurn(lines) {
     summaryLines: trimBlankLines(summaryLines),
     decisionsLines: trimBlankLines(decisionsLines),
     objectionsLines: trimBlankLines(objectionsLines),
+    verificationLines: trimBlankLines(verificationLines),
   };
 }
 

package/src/lib/dispatch-bundle.js

@@ -21,12 +21,19 @@ import {
   DISPATCH_INDEX_PATH,
   getDispatchAssignmentPath,
   getDispatchContextPath,
+  getDispatchLogPath,
   getDispatchPromptPath,
+  getReviewArtifactPath,
   getDispatchTurnDir,
   getTurnStagingResultPath,
 } from './turn-paths.js';
 
 const HISTORY_PATH = '.agentxchain/history.jsonl';
+const FILE_PREVIEW_MAX_FILES = 5;
+const FILE_PREVIEW_MAX_LINES = 120;
+const GATE_FILE_PREVIEW_MAX_LINES = 60;
+const DISPATCH_LOG_MAX_LINES = 50;
+const DISPATCH_LOG_MAX_LINE_BYTES = 8192;
 
 // Reserved paths that agents must never modify
 const RESERVED_PATHS = [
@@ -125,7 +132,7 @@ export function writeDispatchBundle(root, state, config, opts = {}) {
   writeFileSync(join(root, getDispatchPromptPath(turn.turn_id)), prompt.content);
 
   // 3. CONTEXT.md
-  const context = renderContext(state, config, root);
+  const context = renderContext(state, config, root, turn, role);
   warnings.push(...context.warnings);
   writeFileSync(join(root, getDispatchContextPath(turn.turn_id)), context.content);
 
@@ -143,6 +150,8 @@ function renderPrompt(role, roleId, turn, state, config, root) {
   const routing = config.routing?.[phase];
   const exitGate = routing?.exit_gate;
   const gateConfig = exitGate ? config.gates?.[exitGate] : null;
+  const runtime = config.runtimes?.[turn.runtime_id];
+  const runtimeType = runtime?.type || 'manual';
   const warnings = [];
 
   // Load custom prompt template from disk (best-effort)
@@ -200,6 +209,13 @@ function renderPrompt(role, roleId, turn, state, config, root) {
     lines.push('- You may create/modify files under `.planning/` and `.agentxchain/reviews/`.');
     lines.push('- Your artifact type must be `review`.');
     lines.push('- You MUST raise at least one objection (even if minor).');
+    if (runtimeType === 'api_proxy') {
+      const reviewArtifactPath = getReviewArtifactPath(turn.turn_id, roleId);
+      lines.push('- **This runtime cannot write repo files directly.** Do NOT claim `.planning/*` or `.agentxchain/reviews/*` changes you did not actually make.');
+      lines.push(`- The orchestrator will materialize your accepted review at \`${reviewArtifactPath}\`.`);
+      lines.push('- Use `summary`, `decisions`, `objections`, and `verification.evidence_summary` to communicate the review content.');
+      lines.push('- Gate file contents and semantic status are shown in CONTEXT.md under "Gate Required Files". Check them before requesting run completion.');
+    }
     lines.push('');
   } else if (role.write_authority === 'authoritative') {
     lines.push('### Write Authority: authoritative');
@@ -320,14 +336,51 @@ function renderPrompt(role, roleId, turn, state, config, root) {
   lines.push('- `objections[].id`: pattern `OBJ-NNN`');
   lines.push('- `objections[].severity`: one of `low`, `medium`, `high`, `blocking`');
   lines.push('- `verification.status`: one of `pass`, `fail`, `skipped`');
+  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('- `artifact.type`: one of `workspace`, `patch`, `commit`, `review`');
   lines.push('- `proposed_next_role`: must be in allowed_next_roles for current phase, or `human`');
   if (role.write_authority === 'review_only') {
     lines.push('- `objections`: **must be non-empty** (challenge requirement for review_only roles)');
   }
-  lines.push('- `phase_transition_request`: set to next phase name when gate requirements are met, or `null`');
+  // List valid phase names explicitly to prevent gate-name confusion
+  const phaseNames = config.routing ? Object.keys(config.routing) : [];
+  if (phaseNames.length > 0) {
+    lines.push(`- \`phase_transition_request\`: set to a **phase name** when gate requirements are met, or \`null\`. Valid phases: ${phaseNames.map((p) => `\`"${p}"\``).join(', ')}`);
+    lines.push('- **Do NOT use exit gate names** (e.g., `planning_signoff`, `implementation_complete`, `qa_ship_verdict`) as `phase_transition_request` values — those are gate identifiers, not phase names');
+  } else {
+    lines.push('- `phase_transition_request`: set to next phase name when gate requirements are met, or `null`');
+  }
   lines.push('- `run_completion_request`: set to `true` only in the final phase when ready to ship, or `null`');
   lines.push('- `phase_transition_request` and `run_completion_request` are **mutually exclusive**');
+  // Phase-specific guidance for authoritative roles
+  if (role.write_authority === 'authoritative' && phaseNames.length > 0) {
+    const currentPhase = state?.phase;
+    const phaseIdx = currentPhase ? phaseNames.indexOf(currentPhase) : -1;
+    if (phaseIdx >= 0 && phaseIdx < phaseNames.length - 1) {
+      const nextPhase = phaseNames[phaseIdx + 1];
+      const currentGate = config.routing?.[currentPhase]?.exit_gate;
+      const gateClause = currentGate ? ` and the exit gate (\`${currentGate}\`) is satisfied` : '';
+      lines.push(`- **You are in the \`${currentPhase}\` phase.** When your work is complete${gateClause}, set \`phase_transition_request: "${nextPhase}"\` to advance to the next phase.`);
+    } else if (phaseIdx === phaseNames.length - 1) {
+      lines.push(`- **You are in the \`${currentPhase}\` phase (final phase).** When ready to ship, set \`run_completion_request: true\` and \`phase_transition_request: null\`.`);
+    }
+  }
+  // Phase-specific guidance for review_only roles (terminal phase ship readiness)
+  if (role.write_authority === 'review_only' && phaseNames.length > 0) {
+    const currentPhase = state?.phase;
+    const isTerminal = currentPhase && phaseNames.indexOf(currentPhase) === phaseNames.length - 1;
+    if (isTerminal) {
+      lines.push(`- **You are in the \`${currentPhase}\` phase (final phase).**`);
+      lines.push('- **If your review verdict is ship-ready (no blocking issues):** set `run_completion_request: true` and `status: "completed"`. This triggers the human approval gate — it does NOT bypass human review.');
+      lines.push('- **If you found genuine blocking issues that prevent shipping:** set `status: "needs_human"` and explain the blockers in `needs_human_reason`.');
+      lines.push('- Do NOT use `status: "needs_human"` to mean "human should approve the release." That is what `run_completion_request: true` is for.');
+      lines.push('- Do NOT set `phase_transition_request` to the exit gate name.');
+      if (runtimeType === 'api_proxy') {
+        lines.push('- `run_completion_request: true` does **not** mean this runtime wrote `.planning/acceptance-matrix.md`, `.planning/ship-verdict.md`, or `.planning/RELEASE_NOTES.md` for you.');
+      }
+    }
+  }
   lines.push('');
 
   return {
@@ -338,7 +391,7 @@ function renderPrompt(role, roleId, turn, state, config, root) {
 
 // ── Context Rendering ───────────────────────────────────────────────────────
 
-function renderContext(state, config, root) {
+function renderContext(state, config, root, turn, role) {
   const warnings = [];
   const lines = [];
 
@@ -382,6 +435,105 @@ function renderContext(state, config, root) {
         }
       }
       lines.push('');
+
+      // Files changed by the previous turn
+      const filesChanged = lastTurn.files_changed;
+      if (Array.isArray(filesChanged) && filesChanged.length > 0) {
+        lines.push('### Files Changed');
+        lines.push('');
+        for (const f of filesChanged) {
+          lines.push(`- \`${f}\``);
+        }
+        lines.push('');
+      }
+
+      const filePreviews = role?.write_authority === 'review_only'
+        ? buildChangedFilePreviews(root, filesChanged)
+        : [];
+      if (filePreviews.length > 0) {
+        lines.push('### Changed File Previews');
+        lines.push('');
+        for (const preview of filePreviews) {
+          lines.push(`#### \`${preview.path}\``);
+          lines.push('');
+          lines.push('```');
+          lines.push(preview.content);
+          lines.push('```');
+          if (preview.truncated) {
+            lines.push('');
+            lines.push(`_Preview truncated after ${FILE_PREVIEW_MAX_LINES} lines._`);
+          }
+          lines.push('');
+        }
+      }
+
+      // Verification evidence from the previous turn
+      // Use raw verification (has commands, machine_evidence, evidence_summary)
+      // and supplement with normalized_verification status when available
+      const v = lastTurn.verification;
+      if (v && typeof v === 'object' && Object.keys(v).length > 0) {
+        lines.push('### Verification');
+        lines.push('');
+        if (v.status) {
+          lines.push(`- **Status:** ${v.status}`);
+        }
+        const nv = lastTurn.normalized_verification;
+        if (nv?.status && nv.status !== v.status) {
+          lines.push(`- **Normalized status:** ${nv.status} — ${nv.reason || ''}`);
+        }
+        if (Array.isArray(v.commands) && v.commands.length > 0) {
+          lines.push('- **Commands:**');
+          for (const cmd of v.commands) {
+            lines.push(`  - \`${cmd}\``);
+          }
+        }
+        if (v.evidence_summary) {
+          lines.push(`- **Evidence summary:** ${v.evidence_summary}`);
+        }
+        if (Array.isArray(v.machine_evidence) && v.machine_evidence.length > 0) {
+          lines.push('- **Machine evidence:**');
+          lines.push('');
+          lines.push('  | Command | Exit Code |');
+          lines.push('  |---------|-----------|');
+          for (const me of v.machine_evidence) {
+            lines.push(`  | \`${me.command || '(unknown)'}\` | ${me.exit_code ?? '?'} |`);
+          }
+        }
+        lines.push('');
+      }
+
+      // Dispatch log excerpt for review-only turns
+      if (role?.write_authority === 'review_only' && lastTurn.turn_id) {
+        const logExcerpt = buildDispatchLogExcerpt(root, lastTurn.turn_id);
+        if (logExcerpt) {
+          lines.push('### Dispatch Log Excerpt');
+          lines.push('');
+          if (logExcerpt.truncated) {
+            lines.push(`_Log truncated — showing last ${DISPATCH_LOG_MAX_LINES} lines of ${logExcerpt.totalLines} total._`);
+            lines.push('');
+          }
+          lines.push('```');
+          lines.push(logExcerpt.content);
+          lines.push('```');
+          lines.push('');
+        }
+      }
+
+      // Observed artifact from the previous turn
+      const obs = lastTurn.observed_artifact;
+      if (obs && typeof obs === 'object') {
+        const obsFiles = obs.files_changed;
+        if (Array.isArray(obsFiles) && obsFiles.length > 0) {
+          lines.push('### Observed Artifact');
+          lines.push('');
+          lines.push(`- **Files observed:** ${obsFiles.length}`);
+          if (typeof obs.lines_added === 'number' || typeof obs.lines_removed === 'number') {
+            lines.push(`- **Lines added:** ${obs.lines_added ?? 0}`);
+            lines.push(`- **Lines removed:** ${obs.lines_removed ?? 0}`);
+          }
+          lines.push('');
+        }
+      }
     }
   }
 
@@ -410,9 +562,35 @@ function renderContext(state, config, root) {
   if (gateConfig?.requires_files) {
     lines.push('## Gate Required Files');
     lines.push('');
+    const isReviewRole = role?.write_authority === 'review_only';
     for (const f of gateConfig.requires_files) {
-      const exists = existsSync(join(root, f));
-      lines.push(`- \`${f}\` — ${exists ? 'exists' : 'MISSING'}`);
+      const absPath = join(root, f);
+      const exists = existsSync(absPath);
+      if (isReviewRole) {
+        lines.push(`### \`${f}\` — ${exists ? 'exists' : 'MISSING'}`);
+        lines.push('');
+        if (exists) {
+          const gatePreview = buildGateFilePreview(absPath);
+          if (gatePreview) {
+            // Semantic annotations for known gate files
+            const semantic = extractGateFileSemantic(f, gatePreview.raw);
+            if (semantic) {
+              lines.push(`**Gate semantic: ${semantic}**`);
+              lines.push('');
+            }
+            lines.push('```');
+            lines.push(gatePreview.content);
+            lines.push('```');
+            if (gatePreview.truncated) {
+              lines.push('');
+              lines.push(`_Preview truncated after ${GATE_FILE_PREVIEW_MAX_LINES} lines._`);
+            }
+            lines.push('');
+          }
+        }
+      } else {
+        lines.push(`- \`${f}\` — ${exists ? 'exists' : 'MISSING'}`);
+      }
     }
     lines.push('');
   }
@@ -433,6 +611,126 @@ function renderContext(state, config, root) {
   };
 }
 
+function buildGateFilePreview(absPath) {
+  let raw;
+  try {
+    raw = readFileSync(absPath, 'utf8');
+  } catch {
+    return null;
+  }
+  const lines = raw.replace(/\r\n/g, '\n').split('\n');
+  const truncated = lines.length > GATE_FILE_PREVIEW_MAX_LINES;
+  const previewLines = truncated ? lines.slice(0, GATE_FILE_PREVIEW_MAX_LINES) : lines;
+  return {
+    raw,
+    content: previewLines.join('\n').trimEnd(),
+    truncated,
+  };
+}
+
+function extractGateFileSemantic(relPath, raw) {
+  const lower = relPath.toLowerCase();
+  if (lower.endsWith('pm_signoff.md')) {
+    const match = raw.match(/^Approved:\s*(YES|NO|PENDING)/im);
+    if (match && match[1].toUpperCase() === 'YES') {
+      return 'Approved: YES';
+    }
+    return 'approval not found';
+  }
+  if (lower.endsWith('ship-verdict.md')) {
+    const match = raw.match(/^##\s*Verdict:\s*(YES|SHIP|SHIP IT|NO|PENDING)/im);
+    if (match) {
+      const val = match[1].toUpperCase();
+      if (val === 'YES' || val === 'SHIP' || val === 'SHIP IT') {
+        return `Verdict: ${match[1]}`;
+      }
+      return 'verdict not affirmative';
+    }
+    return 'verdict not affirmative';
+  }
+  return null;
+}
+
+function buildChangedFilePreviews(root, filesChanged) {
+  if (!Array.isArray(filesChanged) || filesChanged.length === 0) {
+    return [];
+  }
+
+  const previews = [];
+  for (const relPath of filesChanged.slice(0, FILE_PREVIEW_MAX_FILES)) {
+    const absPath = join(root, relPath);
+    if (!existsSync(absPath)) {
+      continue;
+    }
+
+    let raw;
+    try {
+      raw = readFileSync(absPath, 'utf8');
+    } catch {
+      continue;
+    }
+
+    const lines = raw.replace(/\r\n/g, '\n').split('\n');
+    const truncated = lines.length > FILE_PREVIEW_MAX_LINES;
+    const previewLines = truncated ? lines.slice(0, FILE_PREVIEW_MAX_LINES) : lines;
+    previews.push({
+      path: relPath,
+      content: previewLines.join('\n').trimEnd(),
+      truncated,
+    });
+  }
+
+  return previews;
+}
+
+function buildDispatchLogExcerpt(root, turnId) {
+  const logPath = join(root, getDispatchLogPath(turnId));
+  if (!existsSync(logPath)) {
+    return null;
+  }
+
+  let raw;
+  try {
+    raw = readFileSync(logPath, 'utf8');
+  } catch {
+    return null;
+  }
+
+  if (!raw || raw.trim().length === 0) {
+    return null;
+  }
+
+  const allLines = raw.replace(/\r\n/g, '\n').split('\n');
+  // Remove trailing empty line from split
+  if (allLines.length > 0 && allLines[allLines.length - 1] === '') {
+    allLines.pop();
+  }
+
+  const totalLines = allLines.length;
+  if (totalLines === 0) {
+    return null;
+  }
+
+  const truncated = totalLines > DISPATCH_LOG_MAX_LINES;
+  const selectedLines = truncated
+    ? allLines.slice(totalLines - DISPATCH_LOG_MAX_LINES)
+    : allLines;
+
+  // Per-line byte cap
+  const cappedLines = selectedLines.map((line) => {
+    if (Buffer.byteLength(line, 'utf8') > DISPATCH_LOG_MAX_LINE_BYTES) {
+      return line.slice(0, DISPATCH_LOG_MAX_LINE_BYTES) + '…';
+    }
+    return line;
+  });
+
+  return {
+    content: cappedLines.join('\n').trimEnd(),
+    truncated,
+    totalLines,
+  };
+}
+
 // ── Helpers ─────────────────────────────────────────────────────────────────
 
 function resolveTargetTurn(state, turnId) {

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

@@ -92,12 +92,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);
@@ -135,6 +141,8 @@ export function observeChanges(root, baseline) {
     files_changed: actorFiles.sort(),
     head_ref: currentHead,
     diff_summary: diffSummary,
+    observation_available: true,
+    kind: 'git_observed',
   };
 }
 
@@ -322,11 +330,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 +346,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 +366,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 };

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 = []) {