agentxchain 2.155.27 → 2.155.29

package/bin/agentxchain.js

@@ -707,6 +707,7 @@ 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)')
   .action(acceptTurnCommand);
 
 program

package/package.json

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

package/src/commands/accept-turn.js

@@ -22,6 +22,7 @@ export async function acceptTurnCommand(opts = {}) {
   const result = acceptGovernedTurn(root, config, {
     turnId: opts.turn,
     resolutionMode: opts.resolution || 'standard',
+    normalizeArtifactType: opts.normalizeArtifactType || null,
   });
   if (!result.ok) {
     if (result.error_code === 'policy_escalation' || result.error_code === 'policy_violation') {

package/src/commands/init.js

@@ -544,6 +544,8 @@ 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\`.
 
 ## File Access
 

package/src/lib/continuous-run.js

@@ -31,7 +31,7 @@ import {
   resolveIntent,
   buildVisionIdleExpansionSignal,
 } from './intake.js';
-import { loadProjectState } from './config.js';
+import { loadProjectContext, loadProjectState } from './config.js';
 import { safeWriteJson } from './safe-write.js';
 import { emitRunEvent } from './run-events.js';
 import { reissueTurn } from './governed-state.js';
@@ -54,6 +54,15 @@ import {
 
 const CONTINUOUS_SESSION_PATH = '.agentxchain/continuous-session.json';
 
+function getRoadmapReplenishmentTriageHints(root) {
+  const context = loadProjectContext(root);
+  const config = context?.config || null;
+  return {
+    preferred_role: config?.roles?.pm ? 'pm' : null,
+    phase_scope: config?.routing?.planning ? 'planning' : null,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Session state
 // ---------------------------------------------------------------------------
@@ -719,66 +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 triageResult = triageIntent(root, replenishmentIntentId, {
-          priority: 'p1',
-          template: 'generic',
-          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,8 @@ 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('- `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,
@@ -4317,6 +4327,24 @@ 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,
+      },
+    });
+  }
 
   const rawTurnResult = validation.turnResult;
   const verificationProducedFiles = normalizeVerificationProducedFiles(rawTurnResult.verification);
@@ -4696,7 +4724,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,7 @@ export const VALID_RUN_EVENTS = [
   'state_reconciled_operator_commits',
   'operator_commit_reconcile_refused',
   'charter_materialization_required',
+  'artifact_type_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,6 +91,9 @@ export function validateStagedTurnResult(root, state, config, opts = {}) {
       }
     }
   }
+  if (opts.normalizeArtifactType === 'review') {
+    normContext.forceReviewArtifact = true;
+  }
   const { normalized, corrections } = normalizeTurnResult(turnResult, config, normContext);
   turnResult = normalized;
   const sidecarResult = maybeAttachIdleExpansionSidecar(
@@ -155,6 +158,7 @@ export function validateStagedTurnResult(root, state, config, opts = {}) {
     errors: [],
     warnings: allWarnings,
     turnResult,
+    normalizations: corrections,
   };
 }
 
@@ -1008,6 +1012,28 @@ 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 || isReviewOnly || 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');
+  }
 
   const pickAllowedRoleFallback = () => {
     if (allowedNextRoles.length === 0) return null;