agentxchain 2.155.28 → 2.155.30

package/bin/agentxchain.js

@@ -707,6 +707,8 @@ program
   .option('--turn <id>', 'Target a specific active turn when multiple turns exist')
   .option('--checkpoint', 'Checkpoint the accepted turn to git immediately after acceptance')
   .option('--resolution <mode>', 'Conflict resolution mode for conflicted turns (standard, human_merge)', 'standard')
+  .option('--normalize-artifact-type <type>', 'Normalize an empty workspace artifact to a safe artifact type before acceptance (currently: review)')
+  .option('--normalize-staged-result', 'Run known-safe staged-result normalization before acceptance')
   .action(acceptTurnCommand);
 
 program

package/package.json

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

package/src/commands/accept-turn.js

@@ -22,6 +22,8 @@ export async function acceptTurnCommand(opts = {}) {
   const result = acceptGovernedTurn(root, config, {
     turnId: opts.turn,
     resolutionMode: opts.resolution || 'standard',
+    normalizeArtifactType: opts.normalizeArtifactType || null,
+    normalizeStagedResult: Boolean(opts.normalizeStagedResult),
   });
   if (!result.ok) {
     if (result.error_code === 'policy_escalation' || result.error_code === 'policy_violation') {
@@ -136,6 +138,10 @@ export async function acceptTurnCommand(opts = {}) {
     console.log(`  ${chalk.dim('Reason:')}   ${errorClass}`);
     console.log(`  ${chalk.dim('Owner:')}    human`);
     console.log(`  ${chalk.dim('Action:')}   Fix staged result and rerun agentxchain accept-turn, or reject with agentxchain reject-turn --reason "..."`);
+    if (result.validation?.errors?.some((err) => /objections\[\d+\]\.statement/.test(err))) {
+      const retainedTurnId = opts.turn || result.state?.current_turn?.turn_id || '(turn_id)';
+      console.log(`  ${chalk.dim('Recovery:')} agentxchain accept-turn --turn ${retainedTurnId} --normalize-staged-result`);
+    }
     console.log(`  ${chalk.dim('Turn:')}     retained`);
     if (result.validation?.errors?.length) {
       for (const err of result.validation.errors) {

package/src/commands/init.js

@@ -544,6 +544,9 @@ You are the **${role.title}** on this project.
 1. Read the previous turn and challenge it explicitly.
 2. Do your work according to your mandate.
 3. Write your structured turn result to the turn-scoped staging path printed by the orchestrator (\`.agentxchain/staging/<turn_id>/turn-result.json\`).
+4. If you make zero repo file edits, set \`artifact.type: "review"\` and \`files_changed: []\`.
+5. Only set \`artifact.type: "workspace"\` when you actually modified repo files and listed every changed path in \`files_changed\`.
+6. Every objection must include a non-empty \`statement\`; do not use \`summary\` or \`detail\` as a substitute.
 
 ## File Access
 

package/src/lib/continuous-run.js

@@ -728,69 +728,84 @@ export function seedFromVision(root, visionPath, options = {}) {
     };
   }
 
+  // BUG-77: Once the roadmap has no unchecked work, check whether it is
+  // exhausted while VISION still has unplanned sections before considering
+  // broad per-goal vision candidates. Otherwise accumulated projects with old
+  // generic vision candidates can bypass PM roadmap replenishment.
+  const exhaustion = detectRoadmapExhaustedVisionOpen(root, visionPath);
+  if (exhaustion.open) {
+    const sectionNames = exhaustion.unplanned_sections.join(', ');
+    const replenishmentEvent = recordEvent(root, {
+      source: 'vision_scan',
+      category: 'roadmap_exhausted_vision_open',
+      signal: {
+        description: `Roadmap exhausted (${exhaustion.total_milestones} milestones checked through ${exhaustion.latest_milestone}). VISION.md has unplanned scope: ${sectionNames}`,
+        unplanned_sections: exhaustion.unplanned_sections,
+        latest_milestone: exhaustion.latest_milestone,
+        derived: true,
+      },
+      evidence: [
+        { type: 'text', value: `All ${exhaustion.total_milestones} roadmap milestones checked. VISION sections not yet planned: ${sectionNames}` },
+      ],
+    });
+
+    if (!replenishmentEvent.ok) {
+      if (replenishmentEvent.deduplicated) {
+        return { ok: true, idle: true };
+      }
+      return { ok: false, error: `intake record failed: ${replenishmentEvent.error}` };
+    }
+
+    if (replenishmentEvent.deduplicated) {
+      return { ok: true, idle: true };
+    }
+
+    const replenishmentIntentId = replenishmentEvent.intent.intent_id;
+    const replenishmentHints = getRoadmapReplenishmentTriageHints(root);
+    const triageResult = triageIntent(root, replenishmentIntentId, {
+      priority: 'p1',
+      template: 'generic',
+      ...(replenishmentHints.preferred_role ? { preferred_role: replenishmentHints.preferred_role } : {}),
+      ...(replenishmentHints.phase_scope ? { phase_scope: replenishmentHints.phase_scope } : {}),
+      charter: `[roadmap-replenishment] Derive next bounded roadmap increment from VISION.md. Unplanned scope: ${sectionNames}. Current roadmap checked through ${exhaustion.latest_milestone}. Read .planning/VISION.md and .planning/ROADMAP.md to select the next testable milestone. Produce concrete unchecked M${exhaustion.total_milestones + 1} items. Do not re-verify previous completed milestones.`,
+      acceptance_contract: [
+        `New unchecked milestone items added to .planning/ROADMAP.md`,
+        `Milestone scope derived from VISION.md sections: ${sectionNames}`,
+        `Milestone is bounded, testable, and does not duplicate existing checked milestones`,
+      ],
+    });
+
+    if (!triageResult.ok) {
+      return { ok: false, error: `triage failed: ${triageResult.error}` };
+    }
+
+    const triageApproval = options.triageApproval || 'auto';
+    if (triageApproval === 'auto') {
+      const approveResult = approveIntent(root, replenishmentIntentId, {
+        approver: 'continuous_loop',
+        reason: 'roadmap-replenishment auto-approval (BUG-77)',
+      });
+      if (!approveResult.ok) {
+        return { ok: false, error: `approve failed: ${approveResult.error}` };
+      }
+    }
+
+    return {
+      ok: true,
+      idle: false,
+      intentId: replenishmentIntentId,
+      section: 'Roadmap replenishment',
+      goal: `Derive next increment from: ${sectionNames}`,
+      source: 'roadmap_replenishment',
+    };
+  }
+
   const result = deriveVisionCandidates(root, visionPath);
   if (!result.ok) {
     return { ok: false, error: result.error };
   }
 
   if (result.candidates.length === 0) {
-    // BUG-77: Before declaring idle, check if roadmap is exhausted but VISION
-    // has unplanned scope. If so, seed a PM roadmap-replenishment intent to
-    // derive the next bounded milestone instead of idle-exiting.
-    const exhaustion = detectRoadmapExhaustedVisionOpen(root, visionPath);
-    if (exhaustion.open) {
-      const sectionNames = exhaustion.unplanned_sections.join(', ');
-      const replenishmentEvent = recordEvent(root, {
-        source: 'vision_scan',
-        category: 'roadmap_exhausted_vision_open',
-        signal: {
-          description: `Roadmap exhausted (${exhaustion.total_milestones} milestones checked through ${exhaustion.latest_milestone}). VISION.md has unplanned scope: ${sectionNames}`,
-          unplanned_sections: exhaustion.unplanned_sections,
-          latest_milestone: exhaustion.latest_milestone,
-          derived: true,
-        },
-        evidence: [
-          { type: 'text', value: `All ${exhaustion.total_milestones} roadmap milestones checked. VISION sections not yet planned: ${sectionNames}` },
-        ],
-      });
-
-      if (replenishmentEvent.ok && !replenishmentEvent.deduplicated) {
-        const replenishmentIntentId = replenishmentEvent.intent.intent_id;
-        const replenishmentHints = getRoadmapReplenishmentTriageHints(root);
-        const triageResult = triageIntent(root, replenishmentIntentId, {
-          priority: 'p1',
-          template: 'generic',
-          ...(replenishmentHints.preferred_role ? { preferred_role: replenishmentHints.preferred_role } : {}),
-          ...(replenishmentHints.phase_scope ? { phase_scope: replenishmentHints.phase_scope } : {}),
-          charter: `[roadmap-replenishment] Derive next bounded roadmap increment from VISION.md. Unplanned scope: ${sectionNames}. Current roadmap checked through ${exhaustion.latest_milestone}. Read .planning/VISION.md and .planning/ROADMAP.md to select the next testable milestone. Produce concrete unchecked M${exhaustion.total_milestones + 1} items. Do not re-verify previous completed milestones.`,
-          acceptance_contract: [
-            `New unchecked milestone items added to .planning/ROADMAP.md`,
-            `Milestone scope derived from VISION.md sections: ${sectionNames}`,
-            `Milestone is bounded, testable, and does not duplicate existing checked milestones`,
-          ],
-        });
-
-        if (triageResult.ok) {
-          const triageApproval = options.triageApproval || 'auto';
-          if (triageApproval === 'auto') {
-            approveIntent(root, replenishmentIntentId, {
-              approver: 'continuous_loop',
-              reason: 'roadmap-replenishment auto-approval (BUG-77)',
-            });
-          }
-
-          return {
-            ok: true,
-            idle: false,
-            intentId: replenishmentIntentId,
-            section: 'Roadmap replenishment',
-            goal: `Derive next increment from: ${sectionNames}`,
-            source: 'roadmap_replenishment',
-          };
-        }
-      }
-      // If deduplicated or triage failed, fall through to idle
-    }
     return { ok: true, idle: true };
   }
 

package/src/lib/dispatch-bundle.js

@@ -500,6 +500,9 @@ function renderPrompt(role, roleId, turn, state, config, root) {
   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('- If you make zero repo file edits, set `artifact.type` to `"review"` and `files_changed` to `[]`.');
+  lines.push('- Only set `artifact.type` to `"workspace"` when you actually modified repo files and listed every changed path in `files_changed`.');
+  lines.push('- Every `objections[]` item must include a non-empty `statement`; do not use `summary` or `detail` as a substitute.');
   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)');

package/src/lib/governed-state.js

@@ -4182,6 +4182,13 @@ function _acceptGovernedTurnLocked(root, config, opts) {
       error_code: 'protocol_error',
     };
   }
+  if (opts.normalizeArtifactType && opts.normalizeArtifactType !== 'review') {
+    return {
+      ok: false,
+      error: `Unknown artifact normalization target "${opts.normalizeArtifactType}". Only "review" is supported.`,
+      error_code: 'protocol_error',
+    };
+  }
 
   if (resolutionMode === 'human_merge') {
     if (!currentTurn.conflict_state) {
@@ -4262,7 +4269,10 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     }
   }
 
-  const validation = validateStagedTurnResult(root, validationState, config, { stagingPath: resolvedStagingPath });
+  const validation = validateStagedTurnResult(root, validationState, config, {
+    stagingPath: resolvedStagingPath,
+    normalizeArtifactType: opts.normalizeArtifactType,
+  });
   if (hooksConfig.after_validation && hooksConfig.after_validation.length > 0) {
     const afterValidationPayload = {
       turn_id: currentTurn.turn_id,
@@ -4305,7 +4315,10 @@ function _acceptGovernedTurnLocked(root, config, opts) {
   }
 
   if (!validation.ok) {
-    const failError = `Validation failed at stage ${validation.stage}: ${validation.errors.join('; ')}`;
+    const recoveryHint = validation.errors.some((error) => /objections\[\d+\]\.statement/.test(error))
+      ? ` Recovery: agentxchain accept-turn --turn ${currentTurn.turn_id} --normalize-staged-result`
+      : '';
+    const failError = `Validation failed at stage ${validation.stage}: ${validation.errors.join('; ')}${recoveryHint}`;
     transitionToFailedAcceptance(root, state, currentTurn, failError, {
       error_code: 'validation_failed',
       stage: validation.stage,
@@ -4317,6 +4330,40 @@ function _acceptGovernedTurnLocked(root, config, opts) {
       validation,
     };
   }
+  const artifactTypeWasAutoNormalized = Array.isArray(validation.normalizations)
+    && validation.normalizations.some((entry) => typeof entry === 'string'
+      && entry.includes('artifact.type: auto-normalized empty workspace artifact to review'));
+  if (artifactTypeWasAutoNormalized) {
+    emitRunEvent(root, 'artifact_type_auto_normalized', {
+      run_id: state.run_id,
+      phase: state.phase,
+      status: state.status,
+      turn: { turn_id: currentTurn.turn_id, role_id: currentTurn.assigned_role },
+      intent_id: currentTurn.intake_context?.intent_id || null,
+      payload: {
+        original_artifact_type: 'workspace',
+        normalized_artifact_type: 'review',
+        reason: 'empty_files_changed_no_repo_mutation_declared',
+        staging_path: resolvedStagingPath,
+      },
+    });
+  }
+  for (const event of Array.isArray(validation.normalization_events) ? validation.normalization_events : []) {
+    emitRunEvent(root, 'staged_result_auto_normalized', {
+      run_id: state.run_id,
+      phase: state.phase,
+      status: state.status,
+      turn: { turn_id: currentTurn.turn_id, role_id: currentTurn.assigned_role },
+      intent_id: currentTurn.intake_context?.intent_id || null,
+      payload: {
+        field: event.field,
+        original_value: event.original_value,
+        normalized_value: event.normalized_value,
+        rationale: event.rationale,
+        staging_path: resolvedStagingPath,
+      },
+    });
+  }
 
   const rawTurnResult = validation.turnResult;
   const verificationProducedFiles = normalizeVerificationProducedFiles(rawTurnResult.verification);
@@ -4696,7 +4743,8 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     && (turnResult.files_changed || []).length === 0
     && (observation.files_changed || []).length === 0) {
     const emptyWsError = 'Turn declared artifact.type: "workspace" but files_changed is empty. '
-      + 'Either declare the files modified, or set artifact.type: "review" if no repo mutations were intended.';
+      + 'Either declare the files modified, or set artifact.type: "review" if no repo mutations were intended. '
+      + `Recovery: agentxchain accept-turn --turn ${currentTurn.turn_id} --normalize-artifact-type=review`;
     transitionToFailedAcceptance(root, state, currentTurn, emptyWsError, {
       error_code: 'empty_workspace_artifact',
       stage: 'artifact_validation',

package/src/lib/run-events.js

@@ -49,6 +49,8 @@ export const VALID_RUN_EVENTS = [
   'state_reconciled_operator_commits',
   'operator_commit_reconcile_refused',
   'charter_materialization_required',
+  'artifact_type_auto_normalized',
+  'staged_result_auto_normalized',
 ];
 
 /**

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

@@ -130,7 +130,7 @@
     "files_changed": {
       "type": "array",
       "items": { "type": "string" },
-      "description": "Paths of files modified during this turn. Must match observed diff for authoritative runtimes."
+      "description": "Paths of files modified during this turn. Workspace artifacts must declare a non-empty list that matches observed diff. Review artifacts must use an empty list."
     },
     "artifacts_created": {
       "type": "array",
@@ -195,7 +195,7 @@
       "properties": {
         "type": {
           "enum": ["workspace", "patch", "commit", "review"],
-          "description": "workspace = direct local changes, patch = unified diff, commit = git commit, review = no code changes"
+          "description": "workspace = direct repo file changes with non-empty files_changed, patch = unified diff, commit = git commit, review = no repo mutations with files_changed: []"
         },
         "ref": {
           "type": ["string", "null"],

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

@@ -91,7 +91,10 @@ export function validateStagedTurnResult(root, state, config, opts = {}) {
       }
     }
   }
-  const { normalized, corrections } = normalizeTurnResult(turnResult, config, normContext);
+  if (opts.normalizeArtifactType === 'review') {
+    normContext.forceReviewArtifact = true;
+  }
+  const { normalized, corrections, normalizationEvents } = normalizeTurnResult(turnResult, config, normContext);
   turnResult = normalized;
   const sidecarResult = maybeAttachIdleExpansionSidecar(
     root,
@@ -155,6 +158,8 @@ export function validateStagedTurnResult(root, state, config, opts = {}) {
     errors: [],
     warnings: allWarnings,
     turnResult,
+    normalizations: corrections,
+    normalization_events: normalizationEvents,
   };
 }
 
@@ -991,8 +996,9 @@ function validateProtocol(tr, state, config) {
  */
 export function normalizeTurnResult(tr, config, context = {}) {
   const corrections = [];
+  const normalizationEvents = [];
   if (tr === null || typeof tr !== 'object' || Array.isArray(tr)) {
-    return { normalized: tr, corrections };
+    return { normalized: tr, corrections, normalizationEvents };
   }
 
   const normalized = { ...tr };
@@ -1008,6 +1014,64 @@ export function normalizeTurnResult(tr, config, context = {}) {
   const allowedNextRoles = isKnownPhase ? (routing?.[currentPhase]?.allowed_next_roles || []) : [];
   const assignedRole = context.assignedRole || normalized.role || null;
   const isReviewOnly = context.writeAuthority === 'review_only';
+  const filesChangedIsEmpty = Array.isArray(normalized.files_changed) && normalized.files_changed.length === 0;
+  const hasExplicitNoEditLifecycleSignal = normalized.run_completion_request === true
+    || (typeof normalized.phase_transition_request === 'string' && normalized.phase_transition_request.trim().length > 0);
+
+  // ── Rule 0a: empty workspace artifact → no-edit review normalization ──
+  if (
+    normalized.artifact
+    && typeof normalized.artifact === 'object'
+    && !Array.isArray(normalized.artifact)
+    && normalized.artifact.type === 'workspace'
+    && filesChangedIsEmpty
+    && (context.forceReviewArtifact || hasExplicitNoEditLifecycleSignal)
+  ) {
+    normalized.artifact = {
+      ...normalized.artifact,
+      type: 'review',
+      ref: typeof normalized.turn_id === 'string' && normalized.turn_id.trim()
+        ? `turn:${normalized.turn_id}`
+        : normalized.artifact.ref ?? null,
+    };
+    corrections.push('artifact.type: auto-normalized empty workspace artifact to review because files_changed is empty and no repo mutation was declared');
+    normalizationEvents.push({
+      field: 'artifact.type',
+      original_value: 'workspace',
+      normalized_value: 'review',
+      rationale: 'empty_files_changed_no_repo_mutation_declared',
+    });
+  }
+
+  if (Array.isArray(normalized.objections)) {
+    normalized.objections = normalized.objections.map((objection, index) => {
+      if (objection === null || typeof objection !== 'object' || Array.isArray(objection)) {
+        return objection;
+      }
+      const statement = typeof objection.statement === 'string' ? objection.statement.trim() : '';
+      if (statement) {
+        return objection;
+      }
+      const summary = typeof objection.summary === 'string' ? objection.summary.trim() : '';
+      const detail = typeof objection.detail === 'string' ? objection.detail.trim() : '';
+      const sourceField = summary ? 'summary' : detail ? 'detail' : null;
+      const sourceValue = summary || detail;
+      if (!sourceField) {
+        return objection;
+      }
+      corrections.push(`objections[${index}].statement: copied from ${sourceField}`);
+      normalizationEvents.push({
+        field: `objections[${index}].statement`,
+        original_value: objection.statement ?? null,
+        normalized_value: sourceValue,
+        rationale: `copied_from_${sourceField}`,
+      });
+      return {
+        ...objection,
+        statement: sourceValue,
+      };
+    });
+  }
 
   const pickAllowedRoleFallback = () => {
     if (allowedNextRoles.length === 0) return null;
@@ -1212,7 +1276,7 @@ export function normalizeTurnResult(tr, config, context = {}) {
     }
   }
 
-  return { normalized, corrections };
+  return { normalized, corrections, normalizationEvents };
 }
 
 function normalizeIdleExpansionMutualExclusionSentinel(result) {