agentxchain 2.155.9 → 2.155.11

package/bin/agentxchain.js

@@ -130,6 +130,7 @@ import { scheduleDaemonCommand, scheduleListCommand, scheduleRunDueCommand, sche
 import { chainLatestCommand, chainListCommand, chainShowCommand } from '../src/commands/chain.js';
 import { missionAttachChainCommand, missionBindCoordinatorCommand, missionListCommand, missionPlanApproveCommand, missionPlanAutopilotCommand, missionPlanCommand, missionPlanLaunchCommand, missionPlanListCommand, missionPlanShowCommand, missionShowCommand, missionStartCommand } from '../src/commands/mission.js';
 import { workflowKitDescribeCommand } from '../src/commands/workflow-kit.js';
+import { serveMcpCommand } from '../src/commands/serve-mcp.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
@@ -782,6 +783,12 @@ program
   .option('--dry-run', 'Show configured gate actions without executing approval')
   .action(approveCompletionCommand);
 
+program
+  .command('serve-mcp')
+  .description('Start an MCP server exposing governance tools (stdio transport)')
+  .option('--root <path>', 'Project root directory (default: cwd)')
+  .action(serveMcpCommand);
+
 program
   .command('dashboard')
   .description('Open the live governance dashboard for the current repo/workspace')

package/package.json

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

package/src/commands/run.js

@@ -673,7 +673,7 @@ export async function executeGovernedRun(context, opts = {}) {
         const reportsDir = join(root, '.agentxchain', 'reports');
         mkdirSync(reportsDir, { recursive: true });
 
-        const exportResult = buildRunExport(root);
+        const exportResult = buildRunExport(root, { maxJsonlEntries: 1000, maxBase64Bytes: 1024 * 1024 });
         if (exportResult.ok) {
           const runId = result.state.run_id || 'unknown';
           const exportPath = join(reportsDir, `export-${runId}.json`);

package/src/commands/serve-mcp.js

@@ -0,0 +1,40 @@
+/**
+ * agentxchain serve-mcp — start an MCP server exposing governance tools.
+ *
+ * Runs a stdio-based MCP server that lets any MCP-compatible client
+ * (Claude Code, Cursor, Windsurf, VS Code extensions, etc.) interact
+ * with a governed AgentXchain project.
+ *
+ * Usage:
+ *   agentxchain serve-mcp [--root <project-root>]
+ *
+ * The server reads JSON-RPC from stdin and writes responses to stdout,
+ * per the MCP specification.
+ */
+
+import { resolve } from 'path';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createAgentXchainMcpServer } from '../lib/mcp-server.js';
+import { findProjectRoot } from '../lib/config.js';
+
+export async function serveMcpCommand(opts) {
+  const rootHint = opts.root || process.cwd();
+  const root = findProjectRoot(resolve(rootHint));
+
+  if (!root) {
+    // Even without a governed project, start the server so MCP clients
+    // get descriptive tool errors instead of a connection-refused.
+    process.stderr.write(
+      `[agentxchain serve-mcp] Warning: no agentxchain.json found at ${rootHint}. ` +
+      `Tools will return errors until a governed project is available.\n`,
+    );
+  }
+
+  const projectRoot = root || resolve(rootHint);
+  const server = createAgentXchainMcpServer(projectRoot);
+  const transport = new StdioServerTransport();
+
+  process.stderr.write(`[agentxchain serve-mcp] Starting MCP server for ${projectRoot}\n`);
+
+  await server.connect(transport);
+}

package/src/lib/continuous-run.js

@@ -157,6 +157,32 @@ function getAcceptedIdleExpansionEntries(execution) {
   return entries.filter((entry) => entry?.turn_result?.idle_expansion_result);
 }
 
+function readIdleExpansionPrompt(root, config) {
+  const configuredPath = config?.run_loop?.continuous?.idle_expansion?.pm_prompt_path
+    ?? config?.continuous?.idle_expansion?.pm_prompt_path;
+  const promptPath = typeof configuredPath === 'string' && configuredPath.trim().length > 0
+    ? configuredPath.trim()
+    : '.agentxchain/prompts/pm-idle-expansion.md';
+
+  const absPromptPath = join(root, promptPath);
+  if (!existsSync(absPromptPath)) {
+    return { promptPath, content: '' };
+  }
+
+  try {
+    return {
+      promptPath,
+      content: readFileSync(absPromptPath, 'utf8').trim(),
+    };
+  } catch (err) {
+    return {
+      promptPath,
+      content: '',
+      warning: `Failed to load PM idle-expansion prompt "${promptPath}": ${err.message}`,
+    };
+  }
+}
+
 function ingestAcceptedIdleExpansionsFromExecution(context, session, execution, log = console.log) {
   const entries = getAcceptedIdleExpansionEntries(execution);
   if (entries.length === 0) {
@@ -750,6 +776,19 @@ async function dispatchIdleExpansion(context, session, contOpts, absVisionPath,
     .map(e => `  - ${e.path} (${e.headings.length} headings, ${e.byte_count} bytes${e.warning ? `, warning: ${e.warning}` : ''})`)
     .join('\n');
   const visionHeadings = (session.vision_headings_snapshot || []).map(h => `  - ${h}`).join('\n');
+  const idleExpansionPrompt = readIdleExpansionPrompt(root, context.config);
+  const promptBlock = idleExpansionPrompt.content
+    ? [
+      ``,
+      `PM idle-expansion prompt from ${idleExpansionPrompt.promptPath}:`,
+      idleExpansionPrompt.content,
+    ]
+    : idleExpansionPrompt.warning
+      ? [
+        ``,
+        `PM idle-expansion prompt warning: ${idleExpansionPrompt.warning}`,
+      ]
+      : [];
 
   const charter = [
     `[idle-expansion #${currentIteration}] Inspect VISION.md, ROADMAP.md, SYSTEM_SPEC.md, and current project state.`,
@@ -786,6 +825,7 @@ async function dispatchIdleExpansion(context, session, contOpts, absVisionPath,
     ``,
     `Source manifest:`,
     sourceList || '  (no sources available)',
+    ...promptBlock,
   ].join('\n');
 
   // Use a placeholder accepted_turn_id for the signal — it will be the turn assigned by intake
@@ -1072,6 +1112,10 @@ export function resolveContinuousOptions(opts, config) {
     maxExpansions: configIdleExpansion.max_expansions ?? 5,
     role: configIdleExpansion.role ?? 'pm',
     malformedRetryLimit: configIdleExpansion.malformed_retry_limit ?? 1,
+    pmPromptPath: typeof configIdleExpansion.pm_prompt_path === 'string'
+      && configIdleExpansion.pm_prompt_path.trim().length > 0
+      ? configIdleExpansion.pm_prompt_path.trim()
+      : '.agentxchain/prompts/pm-idle-expansion.md',
   } : null;
 
   return {

package/src/lib/dispatch-bundle.js

@@ -261,6 +261,14 @@ function renderPrompt(role, roleId, turn, state, config, root) {
     lines.push('- Your artifact type should be `workspace` or `commit`.');
     lines.push('- You must accurately declare all files you changed.');
     lines.push('');
+    if (phase === 'implementation') {
+      lines.push('### Implementation Phase: Code Production Required');
+      lines.push('');
+      lines.push('- Your PRIMARY deliverable in this phase is **working source code** — source files, test files, configurations, or executable scripts that change the project\'s runtime behavior.');
+      lines.push('- Planning documents (`.planning/*.md`, `IMPLEMENTATION_NOTES.md`) are supplementary evidence of what you built, not your primary output.');
+      lines.push('- A completed turn in the implementation phase MUST include actual product code changes in `files_changed`, not only documentation or planning artifacts.');
+      lines.push('');
+    }
   } else if (role.write_authority === 'proposed') {
     lines.push('### Write Authority: proposed');
     lines.push('');

package/src/lib/export.js

@@ -107,15 +107,64 @@ function parseJsonl(relPath, raw) {
     });
 }
 
-function parseFile(root, relPath) {
+function parseJsonlBuffer(relPath, buffer, maxEntries) {
+  const shouldWindow = Number.isInteger(maxEntries) && maxEntries > 0;
+  const retained = [];
+  let totalEntries = 0;
+  let physicalLine = 1;
+  let lineStart = 0;
+
+  const retainLine = (line, lineNumber) => {
+    if (!line.trim()) {
+      return;
+    }
+    totalEntries += 1;
+    if (shouldWindow && retained.length >= maxEntries) {
+      retained.shift();
+    }
+    retained.push({ line, lineNumber });
+  };
+
+  for (let i = 0; i <= buffer.length; i += 1) {
+    if (i !== buffer.length && buffer[i] !== 10) {
+      continue;
+    }
+
+    let lineEnd = i;
+    if (lineEnd > lineStart && buffer[lineEnd - 1] === 13) {
+      lineEnd -= 1;
+    }
+    retainLine(buffer.toString('utf8', lineStart, lineEnd), physicalLine);
+    lineStart = i + 1;
+    physicalLine += 1;
+  }
+
+  const entries = retained.map(({ line, lineNumber }) => {
+    try {
+      return JSON.parse(line);
+    } catch (error) {
+      throw new Error(`${relPath}: invalid JSONL at line ${lineNumber}: ${error.message}`);
+    }
+  });
+
+  return {
+    entries,
+    totalEntries,
+    truncated: shouldWindow && totalEntries > maxEntries,
+  };
+}
+
+function parseFile(root, relPath, opts = {}) {
   const absPath = join(root, relPath);
   const buffer = readFileSync(absPath);
-  const raw = buffer.toString('utf8');
 
   let format = 'text';
-  let data = raw;
+  let data = null;
+  let truncated = false;
+  let totalEntries = null;
 
   if (relPath.endsWith('.json')) {
+    const raw = buffer.toString('utf8');
     try {
       data = JSON.parse(raw);
       format = 'json';
@@ -123,17 +172,37 @@ function parseFile(root, relPath) {
       throw new Error(`${relPath}: invalid JSON: ${error.message}`);
     }
   } else if (relPath.endsWith('.jsonl')) {
-    data = parseJsonl(relPath, raw);
+    const maxEntries = opts.maxJsonlEntries;
+    const parsed = Number.isInteger(maxEntries) && maxEntries > 0
+      ? parseJsonlBuffer(relPath, buffer, maxEntries)
+      : { entries: parseJsonl(relPath, buffer.toString('utf8')), totalEntries: null, truncated: false };
     format = 'jsonl';
+    data = parsed.entries;
+    truncated = parsed.truncated;
+    totalEntries = parsed.totalEntries;
+  } else {
+    data = buffer.toString('utf8');
   }
 
-  return {
+  const skipBase64 = truncated || (opts.maxBase64Bytes && buffer.byteLength > opts.maxBase64Bytes);
+  const result = {
     format,
     bytes: buffer.byteLength,
     sha256: sha256(buffer),
-    content_base64: buffer.toString('base64'),
+    content_base64: skipBase64 ? null : buffer.toString('base64'),
     data,
   };
+
+  if (truncated) {
+    result.truncated = true;
+    result.total_entries = totalEntries;
+    result.retained_entries = data.length;
+  }
+  if (skipBase64 && !truncated) {
+    result.content_base64_skipped = true;
+  }
+
+  return result;
 }
 
 function countJsonl(files, relPath) {
@@ -366,7 +435,7 @@ export function buildRunWorkspaceMetadata(root) {
   };
 }
 
-export function buildRunExport(startDir = process.cwd()) {
+export function buildRunExport(startDir = process.cwd(), exportOpts = {}) {
   const context = loadProjectContext(startDir);
   if (!context) {
     return {
@@ -388,9 +457,17 @@ export function buildRunExport(startDir = process.cwd()) {
   const collectedPaths = [...new Set(RUN_EXPORT_INCLUDED_ROOTS.flatMap((relPath) => collectPaths(root, relPath)))]
     .sort((a, b) => a.localeCompare(b, 'en'));
 
+  const parseOpts = {};
+  if (exportOpts.maxJsonlEntries) {
+    parseOpts.maxJsonlEntries = exportOpts.maxJsonlEntries;
+  }
+  if (exportOpts.maxBase64Bytes) {
+    parseOpts.maxBase64Bytes = exportOpts.maxBase64Bytes;
+  }
+
   const files = {};
   for (const relPath of collectedPaths) {
-    files[relPath] = parseFile(root, relPath);
+    files[relPath] = parseFile(root, relPath, parseOpts);
   }
 
   const activeTurns = Object.keys(state?.active_turns || {}).sort((a, b) => a.localeCompare(b, 'en'));

package/src/lib/governed-state.js

@@ -1385,6 +1385,17 @@ function classifyAcceptanceOverlap(targetTurn, conflictFiles, historyEntries, co
   const forwardRevisionTurns = new Map();
 
   for (const entry of historyEntries) {
+    // BUG-66: skip reissued turns — they are superseded, not competing.
+    // A reissued turn's archived observation must not trigger overlap against
+    // its replacement turn (or any subsequent turn).
+    if (entry.status === 'reissued') {
+      continue;
+    }
+    // Also skip if this turn is the direct replacement for the history entry
+    if (targetTurn?.reissued_from && targetTurn.reissued_from === entry.turn_id) {
+      continue;
+    }
+
     if (targetTurn?.run_id && entry.run_id && entry.run_id !== targetTurn.run_id) {
       continue;
     }
@@ -6818,4 +6829,5 @@ export {
   LEDGER_PATH,
   STAGING_PATH,
   TALK_PATH,
+  classifyAcceptanceOverlap as _classifyAcceptanceOverlap,
 };

package/src/lib/mcp-server.js

@@ -0,0 +1,305 @@
+/**
+ * AgentXchain MCP Server — exposes governance operations as MCP tools.
+ *
+ * This module creates an MCP server that lets any MCP-compatible client
+ * (Claude Code, Cursor, Windsurf, VS Code extensions, etc.) natively
+ * query run status, approve gates, read events/history, and record
+ * intake events against a governed AgentXchain project.
+ *
+ * The existing mcp-adapter.js is the inverse: AgentXchain as an MCP client
+ * dispatching turns TO an MCP server. This module makes AgentXchain itself
+ * the server.
+ *
+ * Spec: .planning/SPEC-MCP-SERVER.md
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import * as z from 'zod/v4';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { findProjectRoot, loadProjectContext, loadProjectState } from './config.js';
+import { readRunEvents } from './run-events.js';
+import { queryRunHistory } from './run-history.js';
+import { getActiveTurns } from './governed-state.js';
+import { getOpenHumanEscalation, findCurrentHumanEscalation } from './human-escalations.js';
+import { readContinuousSession } from './continuous-run.js';
+
+const SERVER_NAME = 'agentxchain';
+const SERVER_VERSION = '1.0.0';
+
+/**
+ * Create and configure the AgentXchain MCP server.
+ *
+ * @param {string} root - Absolute path to the project root.
+ * @returns {McpServer} Configured MCP server (not yet connected to a transport).
+ */
+export function createAgentXchainMcpServer(root) {
+  const server = new McpServer(
+    { name: SERVER_NAME, version: SERVER_VERSION },
+    {
+      capabilities: {
+        tools: {},
+        resources: {},
+      },
+      instructions:
+        'AgentXchain governance server. Use tools to query governed run status, ' +
+        'read events and history, approve human gates, and record intake events.',
+    },
+  );
+
+  registerTools(server, root);
+  registerResources(server, root);
+
+  return server;
+}
+
+// ── Tools ──────────────────────────────────────────────────────────────────
+
+function registerTools(server, root) {
+  server.tool(
+    'agentxchain_status',
+    'Read current governed project and run status',
+    {},
+    () => handleStatus(root),
+  );
+
+  server.tool(
+    'agentxchain_events',
+    'Read recent events from the governed project event log',
+    { limit: z.number().optional().describe('Max events to return (default 50)') },
+    (args) => handleEvents(root, args),
+  );
+
+  server.tool(
+    'agentxchain_history',
+    'Read run history entries',
+    { limit: z.number().optional().describe('Max history entries to return (default 20)') },
+    (args) => handleHistory(root, args),
+  );
+
+  server.tool(
+    'agentxchain_approve_gate',
+    'Approve a pending human gate/escalation to unblock a governed run',
+    {
+      gate_id: z.string().describe('The escalation ID to approve (e.g. hesc_abc123)'),
+      reason: z.string().optional().describe('Optional reason for approval'),
+    },
+    (args) => handleApproveGate(root, args),
+  );
+
+  server.tool(
+    'agentxchain_intake_record',
+    'Record a new intake event for the governed project',
+    {
+      source: z.string().describe('Event source (e.g. manual, ci_failure, schedule)'),
+      title: z.string().describe('Short title for the intake event'),
+      description: z.string().optional().describe('Detailed description'),
+      priority: z.string().optional().describe('Priority level (e.g. high, medium, low)'),
+    },
+    (args) => handleIntakeRecord(root, args),
+  );
+}
+
+// ── Resources ──────────────────────────────────────────────────────────────
+
+function registerResources(server, root) {
+  server.resource(
+    'governed-state',
+    'agentxchain://state',
+    { description: 'Current .agentxchain/state.json contents', mimeType: 'application/json' },
+    () => handleReadState(root),
+  );
+
+  server.resource(
+    'continuous-session',
+    'agentxchain://session',
+    { description: 'Current .agentxchain/continuous-session.json contents', mimeType: 'application/json' },
+    () => handleReadSession(root),
+  );
+}
+
+// ── Tool handlers ──────────────────────────────────────────────────────────
+
+function handleStatus(root) {
+  const context = loadProjectContext(root);
+  if (!context) {
+    return toolResult({ ok: false, error: `No governed project found at ${root}` });
+  }
+
+  const { config } = context;
+  const state = loadProjectState(root, config);
+
+  const result = {
+    ok: true,
+    project: config.project || null,
+    protocol_mode: config.protocol_mode || null,
+    run_id: state?.run_id || null,
+    phase: state?.phase || null,
+    status: state?.status || null,
+    active_turns: state ? getActiveTurnsSummary(state) : [],
+    pending_gates: state?.blocked_reason?.type || null,
+    blocked: state?.status === 'blocked',
+    blocked_on: state?.blocked_on || null,
+  };
+
+  const session = readContinuousSession(root);
+  if (session) {
+    result.continuous = {
+      session_id: session.session_id || null,
+      status: session.status || null,
+      runs_completed: session.runs_completed || 0,
+      idle_cycles: session.idle_cycles || 0,
+    };
+  }
+
+  return toolResult(result);
+}
+
+function handleEvents(root, args) {
+  const context = loadProjectContext(root);
+  if (!context) {
+    return toolResult({ ok: false, error: `No governed project found at ${root}` });
+  }
+
+  const limit = typeof args.limit === 'number' && args.limit > 0 ? args.limit : 50;
+  const events = readRunEvents(root, { limit });
+
+  return toolResult({ ok: true, count: events.length, events });
+}
+
+function handleHistory(root, args) {
+  const context = loadProjectContext(root);
+  if (!context) {
+    return toolResult({ ok: false, error: `No governed project found at ${root}` });
+  }
+
+  const limit = typeof args.limit === 'number' && args.limit > 0 ? args.limit : 20;
+  const entries = queryRunHistory(root, { limit });
+
+  return toolResult({ ok: true, count: entries.length, entries });
+}
+
+function handleApproveGate(root, args) {
+  const context = loadProjectContext(root);
+  if (!context) {
+    return toolResult({ ok: false, error: `No governed project found at ${root}` });
+  }
+
+  const { config } = context;
+  const state = loadProjectState(root, config);
+  if (!state) {
+    return toolResult({ ok: false, error: 'No governed state found.' });
+  }
+
+  const gateId = typeof args.gate_id === 'string' ? args.gate_id.trim() : '';
+  if (!gateId) {
+    return toolResult({ ok: false, error: 'gate_id is required.' });
+  }
+
+  if (state.status !== 'blocked') {
+    return toolResult({
+      ok: false,
+      error: `Run is not blocked (status: "${state.status}"). Nothing to approve.`,
+    });
+  }
+
+  const escalation = getOpenHumanEscalation(root, gateId);
+  if (!escalation) {
+    return toolResult({ ok: false, error: `No open escalation found for ${gateId}.` });
+  }
+
+  const current = findCurrentHumanEscalation(root, state);
+  if (!current || current.escalation_id !== escalation.escalation_id) {
+    return toolResult({
+      ok: false,
+      error: `${gateId} is not the current blocker for this run.`,
+    });
+  }
+
+  // We return the gate info rather than performing the unblock directly,
+  // because unblock has side-effects (resume) that should be explicit.
+  // The caller should use the CLI `agentxchain unblock <id>` for the actual mutation.
+  return toolResult({
+    ok: true,
+    gate_id: gateId,
+    type: escalation.type,
+    detail: escalation.detail || null,
+    instruction: `Gate ${gateId} is the current blocker. Run "agentxchain unblock ${gateId}" to approve and resume.`,
+  });
+}
+
+function handleIntakeRecord(root, args) {
+  const context = loadProjectContext(root);
+  if (!context) {
+    return toolResult({ ok: false, error: `No governed project found at ${root}` });
+  }
+
+  const source = typeof args.source === 'string' ? args.source.trim() : '';
+  const title = typeof args.title === 'string' ? args.title.trim() : '';
+
+  if (!source || !title) {
+    return toolResult({ ok: false, error: 'Both source and title are required.' });
+  }
+
+  // Similar to approve_gate: we expose the information needed to record,
+  // but defer the actual mutation to the intake pipeline.
+  // Direct mutation via MCP would bypass the CLI's validation and event emission.
+  return toolResult({
+    ok: true,
+    instruction: `Use "agentxchain intake record --source ${source} --title '${title}'${args.description ? ` --description '${args.description}'` : ''}${args.priority ? ` --priority ${args.priority}` : ''}" to record this event.`,
+    source,
+    title,
+    description: args.description || null,
+    priority: args.priority || null,
+  });
+}
+
+// ── Resource handlers ──────────────────────────────────────────────────────
+
+function handleReadState(root) {
+  const statePath = join(root, '.agentxchain', 'state.json');
+  if (!existsSync(statePath)) {
+    return { contents: [{ uri: 'agentxchain://state', text: '{}', mimeType: 'application/json' }] };
+  }
+  try {
+    const text = readFileSync(statePath, 'utf8');
+    return { contents: [{ uri: 'agentxchain://state', text, mimeType: 'application/json' }] };
+  } catch {
+    return { contents: [{ uri: 'agentxchain://state', text: '{}', mimeType: 'application/json' }] };
+  }
+}
+
+function handleReadSession(root) {
+  const sessionPath = join(root, '.agentxchain', 'continuous-session.json');
+  if (!existsSync(sessionPath)) {
+    return { contents: [{ uri: 'agentxchain://session', text: '{}', mimeType: 'application/json' }] };
+  }
+  try {
+    const text = readFileSync(sessionPath, 'utf8');
+    return { contents: [{ uri: 'agentxchain://session', text, mimeType: 'application/json' }] };
+  } catch {
+    return { contents: [{ uri: 'agentxchain://session', text: '{}', mimeType: 'application/json' }] };
+  }
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function getActiveTurnsSummary(state) {
+  try {
+    const turns = getActiveTurns(state);
+    return turns.map((t) => ({
+      turn_id: t.turn_id,
+      role: t.assigned_role,
+      status: t.status,
+      phase: t.phase,
+    }));
+  } catch {
+    return [];
+  }
+}
+
+function toolResult(data) {
+  return {
+    content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+  };
+}

package/src/lib/normalized-config.js

@@ -694,6 +694,11 @@ function validateRunLoopContinuousConfig(path, continuous, errors) {
           errors.push(`${path}.idle_expansion.malformed_retry_limit must be a non-negative integer`);
         }
       }
+      if (continuous.idle_expansion.pm_prompt_path !== undefined
+          && continuous.idle_expansion.pm_prompt_path !== null
+          && typeof continuous.idle_expansion.pm_prompt_path !== 'string') {
+        errors.push(`${path}.idle_expansion.pm_prompt_path must be a string`);
+      }
     }
   }
 }
@@ -1365,9 +1370,10 @@ function normalizeIdleExpansion(raw) {
       sources: ['.planning/VISION.md', '.planning/ROADMAP.md', '.planning/SYSTEM_SPEC.md'],
       max_expansions: 5,
       role: 'pm',
-      output: 'intake_intent_or_vision_exhausted',
-      malformed_retry_limit: 1,
-    };
+    output: 'intake_intent_or_vision_exhausted',
+    malformed_retry_limit: 1,
+    pm_prompt_path: '.agentxchain/prompts/pm-idle-expansion.md',
+  };
   }
   const sources = Array.isArray(raw.sources) && raw.sources.length > 0
     ? raw.sources.filter(s => typeof s === 'string' && s.length > 0)
@@ -1379,6 +1385,9 @@ function normalizeIdleExpansion(raw) {
     output: 'intake_intent_or_vision_exhausted',
     malformed_retry_limit: Number.isInteger(raw.malformed_retry_limit) && raw.malformed_retry_limit >= 0
       ? raw.malformed_retry_limit : 1,
+    pm_prompt_path: typeof raw.pm_prompt_path === 'string' && raw.pm_prompt_path.trim().length > 0
+      ? raw.pm_prompt_path.trim()
+      : '.agentxchain/prompts/pm-idle-expansion.md',
   };
 }
 

package/src/lib/repo-observer.js

@@ -69,6 +69,12 @@ export const BASELINE_EXEMPT_PATH_PREFIXES = Object.freeze([
   '.agentxchain/proposed/',
 ]);
 
+const GENERATED_REPORT_PATH_PATTERNS = Object.freeze([
+  /^\.agentxchain\/reports\/report-[^/]+\.md$/,
+  /^\.agentxchain\/reports\/export-[^/]+\.json$/,
+  /^\.agentxchain\/reports\/chain-[^/]+\.json$/,
+]);
+
 // Continuity export/restore must stay aligned with orchestrator ownership,
 // but only for the subset that represents governed run state.
 export const RUN_CONTINUITY_STATE_FILES = Object.freeze([
@@ -93,6 +99,10 @@ function pathMatchesAnyRoot(filePath, roots) {
   return roots.some((root) => filePath === root || filePath.startsWith(`${root}/`));
 }
 
+function isGeneratedReportPath(filePath) {
+  return GENERATED_REPORT_PATH_PATTERNS.some((pattern) => pattern.test(filePath));
+}
+
 /**
  * Return the repo-owned vs framework-owned classification flags for a path.
  *
@@ -106,7 +116,8 @@ function pathMatchesAnyRoot(filePath, roots) {
  */
 export function classifyRepoPath(filePath) {
   const operational = pathMatchesAnyPrefix(filePath, OPERATIONAL_PATH_PREFIXES)
-    || ORCHESTRATOR_STATE_FILES.includes(filePath);
+    || ORCHESTRATOR_STATE_FILES.includes(filePath)
+    || isGeneratedReportPath(filePath);
   const continuityState = RUN_CONTINUITY_STATE_FILES.includes(filePath)
     || pathMatchesAnyRoot(filePath, RUN_CONTINUITY_DIRECTORY_ROOTS);
   const baselineExempt = operational

package/src/lib/schemas/agentxchain-config.schema.json

@@ -136,6 +136,10 @@
                   "type": "integer",
                   "minimum": 0,
                   "description": "Reserved retry budget for malformed idle_expansion_result outputs. Default 1."
+                },
+                "pm_prompt_path": {
+                  "type": "string",
+                  "description": "Project-relative prompt supplement loaded into PM idle-expansion charters. Default .agentxchain/prompts/pm-idle-expansion.md."
                 }
               },
               "additionalProperties": true

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

@@ -479,7 +479,15 @@ function buildIdleExpansionValidationContext(state, opts, activeTurn) {
 }
 
 function maybeAttachIdleExpansionSidecar(root, stagingRel, turnResult, context) {
-  if (context.required !== true || turnResult?.idle_expansion_result !== undefined) {
+  if (turnResult?.idle_expansion_result !== undefined) {
+    // Normalize embedded idle_expansion_result in-place (same transforms as sidecar path)
+    const normalizedResult = normalizeIdleExpansionSidecar(turnResult.idle_expansion_result, context);
+    return {
+      turnResult: { ...turnResult, idle_expansion_result: normalizedResult },
+      warnings: [],
+    };
+  }
+  if (context.required !== true) {
     return { turnResult, warnings: [] };
   }
 
@@ -525,7 +533,24 @@ function normalizeIdleExpansionSidecar(sidecar, context) {
       : context.expansionIteration,
   };
 
-  const intent = sidecar.new_intake_intent || sidecar.proposed_intent;
+  let intent = sidecar.new_intake_intent || sidecar.proposed_intent;
+  // Normalize flat new_intake_intent fields: if the PM put title/charter at the
+  // top level instead of nesting under new_intake_intent, extract them.
+  if (sidecar.kind === 'new_intake_intent' && !intent && sidecar.title && sidecar.charter) {
+    intent = {
+      title: sidecar.title,
+      charter: sidecar.charter,
+      acceptance_contract: sidecar.acceptance_contract,
+      priority: sidecar.priority,
+      template: sidecar.template,
+    };
+    // Remove flat fields from result to avoid schema pollution
+    delete result.title;
+    delete result.charter;
+    delete result.acceptance_contract;
+    delete result.priority;
+    delete result.template;
+  }
   if (sidecar.kind === 'new_intake_intent' && intent && typeof intent === 'object' && !Array.isArray(intent)) {
     result.new_intake_intent = {
       title: intent.title,

package/src/templates/governed/enterprise-app.json

@@ -53,7 +53,7 @@
       },
       "dev": {
         "title": "Developer",
-        "mandate": "Implement approved work safely and verify behavior.",
+        "mandate": "Write source code that implements approved work, then verify it passes tests.",
         "write_authority": "authoritative",
         "runtime": "local-dev"
       },

package/src/templates/governed/full-local-cli.json

@@ -24,7 +24,7 @@
       },
       "dev": {
         "title": "Developer",
-        "mandate": "Implement approved work safely and verify behavior.",
+        "mandate": "Write source code that implements approved work, then verify it passes tests.",
         "write_authority": "authoritative",
         "runtime": "local-dev"
       },

package/src/templates/governed/generic.json

@@ -14,7 +14,7 @@
       },
       "dev": {
         "title": "Developer",
-        "mandate": "Implement approved work safely and verify behavior.",
+        "mandate": "Write source code that implements approved work, then verify it passes tests.",
         "write_authority": "authoritative",
         "runtime": "manual-dev"
       },