agentxchain 2.29.0 → 2.31.0

package/package.json

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

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

@@ -10,6 +10,7 @@ const SECTION_DEFINITIONS = [
   { id: 'last_turn_verification', header: null, required: false },
   { id: 'blockers', header: 'Blockers', required: true },
   { id: 'escalation', header: 'Escalation', required: true },
+  { id: 'workflow_artifacts', header: 'Workflow Artifacts', required: false },
   { id: 'gate_required_files', header: 'Gate Required Files', required: false },
   { id: 'phase_gate_status', header: 'Phase Gate Status', required: false },
 ];
@@ -88,6 +89,7 @@ export function renderContextSections(sections) {
 
   appendTopLevelSection(lines, 'Blockers', [sectionMap.get('blockers')?.content]);
   appendTopLevelSection(lines, 'Escalation', [sectionMap.get('escalation')?.content]);
+  appendTopLevelSection(lines, 'Workflow Artifacts', [sectionMap.get('workflow_artifacts')?.content]);
   appendTopLevelSection(lines, 'Gate Required Files', [sectionMap.get('gate_required_files')?.content]);
   appendTopLevelSection(lines, 'Phase Gate Status', [sectionMap.get('phase_gate_status')?.content]);
 

package/src/lib/dispatch-bundle.js

@@ -248,6 +248,31 @@ function renderPrompt(role, roleId, turn, state, config, root) {
     lines.push('');
   }
 
+  const workflowResponsibilities = getWorkflowPromptResponsibilities(config, phase, roleId, root);
+  if (workflowResponsibilities.length > 0) {
+    const isReviewOnlyOwner = role.write_authority === 'review_only';
+    lines.push('## Workflow-Kit Responsibilities');
+    lines.push('');
+    if (isReviewOnlyOwner) {
+      lines.push(`You are accountable for reviewing and attesting to these workflow-kit artifacts in phase \`${phase}\`:`);
+    } else {
+      lines.push(`You are accountable for producing these workflow-kit artifacts in phase \`${phase}\`:`);
+    }
+    lines.push('');
+    for (const artifact of workflowResponsibilities) {
+      const requiredLabel = artifact.required ? 'required' : 'optional';
+      const semanticsLabel = artifact.semantics ? `\`${artifact.semantics}\`` : '—';
+      lines.push(`- \`${artifact.path}\` — ${requiredLabel}; semantics: ${semanticsLabel}; status: ${artifact.status}`);
+    }
+    lines.push('');
+    if (isReviewOnlyOwner) {
+      lines.push('You cannot write repo files directly. Your accountability means you must confirm these artifacts exist, meet quality standards, and satisfy their semantic requirements. If a required artifact you own is missing, escalate to the producing role — do not request phase transition.');
+    } else {
+      lines.push('Do not request phase transition or run completion while a required workflow-kit artifact you own is missing or incomplete.');
+    }
+    lines.push('');
+  }
+
   // Gate requirements
   if (gateConfig) {
     lines.push('## Phase Exit Gate');
@@ -421,6 +446,47 @@ function renderPrompt(role, roleId, turn, state, config, root) {
   };
 }
 
+function getWorkflowPromptResponsibilities(config, phase, roleId, root) {
+  const artifacts = config?.workflow_kit?.phases?.[phase]?.artifacts;
+  if (!Array.isArray(artifacts) || artifacts.length === 0) {
+    return [];
+  }
+
+  const entryRole = config?.routing?.[phase]?.entry_role || null;
+  const responsibilities = [];
+
+  for (const artifact of artifacts) {
+    if (!artifact?.path) {
+      continue;
+    }
+
+    const owner = typeof artifact.owned_by === 'string' && artifact.owned_by
+      ? artifact.owned_by
+      : null;
+    const responsibleRole = owner || entryRole;
+    if (responsibleRole !== roleId) {
+      continue;
+    }
+
+    const absPath = join(root, artifact.path);
+    let exists = false;
+    try {
+      exists = existsSync(absPath);
+    } catch {
+      exists = false;
+    }
+
+    responsibilities.push({
+      path: artifact.path,
+      required: artifact.required !== false,
+      semantics: artifact.semantics || null,
+      status: exists ? 'exists' : 'MISSING',
+    });
+  }
+
+  return responsibilities;
+}
+
 // ── Context Rendering ───────────────────────────────────────────────────────
 
 function renderContext(state, config, root, turn, role) {
@@ -621,8 +687,59 @@ function renderContext(state, config, root, turn, role) {
     lines.push('');
   }
 
-  // Phase gate requirements
+  // Workflow-kit artifacts for the current phase
   const phase = state.phase;
+  const wkArtifacts = config?.workflow_kit?.phases?.[phase]?.artifacts;
+  if (Array.isArray(wkArtifacts) && wkArtifacts.length > 0) {
+    lines.push('## Workflow Artifacts');
+    lines.push('');
+    lines.push(`Current phase **${phase}** declares the following artifacts:`);
+    lines.push('');
+    lines.push('| Artifact | Required | Semantics | Owner | Status |');
+    lines.push('|----------|----------|-----------|-------|--------|');
+    const isReviewRole = role?.write_authority === 'review_only';
+    const reviewPreviews = [];
+    for (const art of wkArtifacts) {
+      if (!art?.path) continue;
+      const absPath = join(root, art.path);
+      let exists = false;
+      try { exists = existsSync(absPath); } catch { /* treat as missing */ }
+      const req = art.required !== false ? 'yes' : 'no';
+      const owner = art.owned_by || '—';
+      const status = exists ? 'exists' : 'MISSING';
+      const semCol = art.semantics ? `\`${art.semantics}\`` : '—';
+      lines.push(`| \`${art.path}\` | ${req} | ${semCol} | ${owner} | ${status} |`);
+      if (isReviewRole && exists) {
+        reviewPreviews.push(art);
+      }
+    }
+    lines.push('');
+    if (reviewPreviews.length > 0) {
+      for (const art of reviewPreviews) {
+        const absPath = join(root, art.path);
+        const preview = buildGateFilePreview(absPath);
+        if (preview) {
+          lines.push(`### \`${art.path}\``);
+          lines.push('');
+          const semantic = extractGateFileSemantic(art.path, preview.raw);
+          if (semantic) {
+            lines.push(`**Semantic: ${semantic}**`);
+            lines.push('');
+          }
+          lines.push('```');
+          lines.push(preview.content);
+          lines.push('```');
+          if (preview.truncated) {
+            lines.push('');
+            lines.push(`_Preview truncated after ${GATE_FILE_PREVIEW_MAX_LINES} lines._`);
+          }
+          lines.push('');
+        }
+      }
+    }
+  }
+
+  // Phase gate requirements
   const routing = config.routing?.[phase];
   const exitGate = routing?.exit_gate;
   const gateConfig = exitGate ? config.gates?.[exitGate] : null;

package/src/lib/export.js

@@ -31,6 +31,7 @@ const INCLUDED_ROOTS = [
   '.agentxchain/transactions/accept',
   '.agentxchain/intake',
   '.agentxchain/multirepo',
+  '.planning',
 ];
 
 function sha256(buffer) {

package/src/lib/normalized-config.js

@@ -628,6 +628,25 @@ export function validateWorkflowKitConfig(wk, routing, roles) {
             errors.push(`${prefix} owned_by "${artifact.owned_by}" is not a valid role ID (must be lowercase alphanumeric with hyphens/underscores)`);
           } else if (roles && typeof roles === 'object' && !roles[artifact.owned_by]) {
             errors.push(`${prefix} owned_by "${artifact.owned_by}" does not reference a defined role`);
+          } else if (
+            artifact.required !== false &&
+            roles && typeof roles === 'object' &&
+            roles[artifact.owned_by]?.write_authority === 'review_only'
+          ) {
+            // Check if any authoritative/proposed role exists in this phase's routing
+            const phaseRouting = routing?.[phase];
+            const phaseRoles = new Set([
+              ...(phaseRouting?.allowed_next_roles || []),
+              ...(phaseRouting?.entry_role ? [phaseRouting.entry_role] : []),
+            ]);
+            const hasWriter = [...phaseRoles].some(rid =>
+              roles[rid]?.write_authority === 'authoritative' || roles[rid]?.write_authority === 'proposed',
+            );
+            if (!hasWriter) {
+              warnings.push(
+                `${prefix} owned_by "${artifact.owned_by}" is a review_only role in phase "${phase}" with no authoritative or proposed role — nobody can write this required artifact`,
+              );
+            }
           }
         }
       }

package/src/lib/report.js

@@ -471,6 +471,38 @@ function deriveRepoStatusCounts(repoStatuses) {
   return counts;
 }
 
+export function extractWorkflowKitArtifacts(artifact) {
+  const config = artifact.config;
+  if (!config || typeof config !== 'object' || !config.workflow_kit) return null;
+
+  const phase = artifact.summary?.phase || artifact.state?.phase;
+  if (!phase) return null;
+
+  const phaseConfig = config.workflow_kit.phases?.[phase];
+  if (!phaseConfig) return [];
+
+  const artifacts = Array.isArray(phaseConfig.artifacts) ? phaseConfig.artifacts : [];
+  if (artifacts.length === 0) return [];
+
+  const entryRole = config.routing?.[phase]?.entry_role || null;
+  const fileKeys = new Set(Object.keys(artifact.files || {}));
+
+  return artifacts
+    .filter((a) => a && typeof a.path === 'string')
+    .map((a) => {
+      const hasExplicitOwner = typeof a.owned_by === 'string' && a.owned_by.length > 0;
+      return {
+        path: a.path,
+        required: a.required !== false,
+        semantics: a.semantics || null,
+        owned_by: hasExplicitOwner ? a.owned_by : entryRole,
+        owner_resolution: hasExplicitOwner ? 'explicit' : 'entry_role',
+        exists: fileKeys.has(a.path),
+      };
+    })
+    .sort((a, b) => a.path.localeCompare(b.path, 'en'));
+}
+
 function buildRunSubject(artifact) {
   const activeTurns = artifact.summary?.active_turn_ids || [];
   const retainedTurns = artifact.summary?.retained_turn_ids || [];
@@ -518,6 +550,7 @@ function buildRunSubject(artifact) {
       gate_summary: gateSummary,
       intake_links: intakeLinks,
       recovery_summary: recoverySummary,
+      workflow_kit_artifacts: extractWorkflowKitArtifacts(artifact),
     },
     artifacts: {
       history_entries: artifact.summary?.history_entries || 0,
@@ -810,6 +843,17 @@ export function formatGovernanceReportText(report) {
       lines.push(`  Turn retained: ${run.recovery_summary.turn_retained == null ? 'n/a' : yesNo(run.recovery_summary.turn_retained)}`);
     }
 
+    if (Array.isArray(run.workflow_kit_artifacts) && run.workflow_kit_artifacts.length > 0) {
+      lines.push('', `Workflow Artifacts (${run.phase || 'unknown'} phase):`);
+      for (const art of run.workflow_kit_artifacts) {
+        const req = art.required ? 'required' : 'optional';
+        const sem = art.semantics || 'none';
+        const owner = art.owned_by ? `${art.owned_by} (${art.owner_resolution})` : 'none';
+        const status = art.exists ? 'exists' : 'missing';
+        lines.push(`  ${art.path} | ${req} | ${sem} | owner: ${owner} | ${status}`);
+      }
+    }
+
     return lines.join('\n');
   }
 
@@ -1066,6 +1110,19 @@ export function formatGovernanceReportMarkdown(report) {
       lines.push(`- Turn retained: \`${run.recovery_summary.turn_retained == null ? 'n/a' : yesNo(run.recovery_summary.turn_retained)}\``);
     }
 
+    if (Array.isArray(run.workflow_kit_artifacts) && run.workflow_kit_artifacts.length > 0) {
+      lines.push('', '## Workflow Artifacts', '');
+      lines.push(`Phase: \`${run.phase || 'unknown'}\``, '');
+      lines.push('| Artifact | Required | Semantics | Owner | Resolution | Status |', '|----------|----------|-----------|-------|------------|--------|');
+      for (const art of run.workflow_kit_artifacts) {
+        const req = art.required ? 'yes' : 'no';
+        const sem = art.semantics ? `\`${art.semantics}\`` : 'none';
+        const owner = art.owned_by ? `\`${art.owned_by}\`` : 'none';
+        const status = art.exists ? 'exists' : '**missing**';
+        lines.push(`| \`${art.path}\` | ${req} | ${sem} | ${owner} | ${art.owner_resolution} | ${status} |`);
+      }
+    }
+
     return lines.join('\n');
   }