agentxchain 2.103.0 → 2.104.0

package/README.md

@@ -224,7 +224,7 @@ agentxchain step
 | `supervise` | Run `watch` plus optional macOS auto-nudge |
 | `claim` / `release` | Human override of legacy lock ownership |
 | `rebind` | Rebuild Cursor bindings |
-| `generate` | Regenerate VS Code agent files |
+| `generate` | Regenerate VS Code agent files; use `generate planning` to restore scaffold-owned governed planning docs |
 | `branch` | Manage Cursor branch override for launches |
 | `doctor` | Check local environment and setup |
 | `stop` | Stop watch daemon and local sessions |

package/bin/agentxchain.js

@@ -55,7 +55,7 @@ import { configCommand } from '../src/commands/config.js';
 import { updateCommand } from '../src/commands/update.js';
 import { watchCommand } from '../src/commands/watch.js';
 import { claimCommand, releaseCommand } from '../src/commands/claim.js';
-import { generateCommand } from '../src/commands/generate.js';
+import { generateCommand, generatePlanningCommand } from '../src/commands/generate.js';
 import { doctorCommand } from '../src/commands/doctor.js';
 import { superviseCommand } from '../src/commands/supervise.js';
 import { validateCommand } from '../src/commands/validate.js';
@@ -223,11 +223,19 @@ program
   .option('--unset', 'Remove override and follow the active git branch automatically')
   .action(branchCommand);
 
-program
+const generateCmd = program
   .command('generate')
-  .description('Regenerate VS Code agent files (.agent.md, hooks) from agentxchain.json')
+  .description('Regenerate VS Code agent files, or governed planning artifacts via subcommands')
   .action(generateCommand);
 
+generateCmd
+  .command('planning')
+  .description('Generate or restore scaffold-owned governed planning artifacts')
+  .option('--dry-run', 'Show which planning artifacts would be written without changing files')
+  .option('--force', 'Overwrite existing scaffold-owned planning artifacts')
+  .option('-j, --json', 'Output as JSON')
+  .action(generatePlanningCommand);
+
 program
   .command('watch')
   .description('Watch lock.json and coordinate agent turns (the referee)')

package/package.json

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

package/scripts/release-preflight.sh

@@ -9,10 +9,12 @@ CLI_DIR="${SCRIPT_DIR}/.."
 cd "$CLI_DIR"
 
 STRICT_MODE=0
+PUBLISH_GATE=0
 TARGET_VERSION="2.0.0"
 
 usage() {
-  echo "Usage: bash scripts/release-preflight.sh [--strict] [--target-version <semver>]" >&2
+  echo "Usage: bash scripts/release-preflight.sh [--strict] [--publish-gate] [--target-version <semver>]" >&2
+  echo "  --publish-gate  Run only release-critical checks (no full test suite). Use in CI publish workflows." >&2
 }
 
 while [[ $# -gt 0 ]]; do
@@ -21,6 +23,11 @@ while [[ $# -gt 0 ]]; do
       STRICT_MODE=1
       shift
       ;;
+    --publish-gate)
+      PUBLISH_GATE=1
+      STRICT_MODE=1
+      shift
+      ;;
     --target-version)
       if [[ -z "${2:-}" ]]; then
         echo "Error: --target-version requires a semver argument" >&2
@@ -99,49 +106,86 @@ else
 fi
 
 # 3. Tests
-echo "[3/6] Test suite"
-# Install MCP example deps — tests start example servers as subprocesses
-for example_dir in "${CLI_DIR}/../examples/mcp-echo-agent" "${CLI_DIR}/../examples/mcp-http-echo-agent"; do
-  if [[ -f "${example_dir}/package.json" && ! -d "${example_dir}/node_modules" ]]; then
-    echo "  Installing deps for $(basename "$example_dir")..."
-    (cd "$example_dir" && env -u NODE_AUTH_TOKEN -u NPM_CONFIG_USERCONFIG npm install --ignore-scripts --userconfig /dev/null 2>&1) || true
+if [[ "$PUBLISH_GATE" -eq 1 ]]; then
+  echo "[3/6] Release-gate tests (targeted subset)"
+  # In publish-gate mode, run only release-critical tests to avoid CI hangs.
+  # The full test suite is a pre-tag responsibility, not a publish-time gate.
+  GATE_TESTS=(
+    test/release-preflight.test.js
+    test/release-docs-content.test.js
+    test/release-notes-gate.test.js
+    test/release-identity-hardening.test.js
+    test/normalized-config.test.js
+    test/conformance.test.js
+  )
+  GATE_TEST_ARGS=()
+  for t in "${GATE_TESTS[@]}"; do
+    if [[ -f "$t" ]]; then
+      GATE_TEST_ARGS+=("$t")
+    fi
+  done
+  if [[ ${#GATE_TEST_ARGS[@]} -eq 0 ]]; then
+    fail "No release-gate test files found"
+  else
+    if run_and_capture TEST_OUTPUT env AGENTXCHAIN_RELEASE_TARGET_VERSION="${TARGET_VERSION}" AGENTXCHAIN_RELEASE_PREFLIGHT=1 node --test "${GATE_TEST_ARGS[@]}"; then
+      TEST_STATUS=0
+    else
+      TEST_STATUS=$?
+    fi
+    NODE_PASS="$(printf '%s\n' "$TEST_OUTPUT" | awk '/^ℹ tests / { print $3; exit }')"
+    NODE_FAIL="$(printf '%s\n' "$TEST_OUTPUT" | awk '/^ℹ fail / { print $3; exit }')"
+    if [ "$TEST_STATUS" -eq 0 ] && [ "${NODE_FAIL:-0}" = "0" ]; then
+      pass "${NODE_PASS:-?} release-gate tests passed, 0 failures"
+    else
+      fail "Release-gate tests failed"
+      printf '%s\n' "$TEST_OUTPUT" | tail -20
+    fi
   fi
-done
-if run_and_capture TEST_OUTPUT env AGENTXCHAIN_RELEASE_TARGET_VERSION="${TARGET_VERSION}" AGENTXCHAIN_RELEASE_PREFLIGHT=1 npm test; then
-  TEST_STATUS=0
 else
-  TEST_STATUS=$?
-fi
-TEST_PASS="$(printf '%s\n' "$TEST_OUTPUT" | awk '/^# pass / { print $3 }')"
-TEST_FAIL="$(printf '%s\n' "$TEST_OUTPUT" | awk '/^# fail / { print $3 }')"
-if [ -z "${TEST_PASS:-}" ]; then
-  VITEST_PASS="$(printf '%s\n' "$TEST_OUTPUT" | awk '/^[[:space:]]*Tests[[:space:]]+[0-9]+[[:space:]]+passed/ { for (i = 1; i <= NF; i++) if ($i ~ /^[0-9]+$/) { print $i; exit } }')"
-  NODE_PASS="$(printf '%s\n' "$TEST_OUTPUT" | awk '/^ℹ tests / { print $3; exit }')"
-  if [ -n "${VITEST_PASS:-}" ] && [ -n "${NODE_PASS:-}" ]; then
-    TEST_PASS="$((VITEST_PASS + NODE_PASS))"
-  elif [ -n "${NODE_PASS:-}" ]; then
-    TEST_PASS="${NODE_PASS}"
-  elif [ -n "${VITEST_PASS:-}" ]; then
-    TEST_PASS="${VITEST_PASS}"
+  echo "[3/6] Test suite"
+  # Install MCP example deps — tests start example servers as subprocesses
+  for example_dir in "${CLI_DIR}/../examples/mcp-echo-agent" "${CLI_DIR}/../examples/mcp-http-echo-agent"; do
+    if [[ -f "${example_dir}/package.json" && ! -d "${example_dir}/node_modules" ]]; then
+      echo "  Installing deps for $(basename "$example_dir")..."
+      (cd "$example_dir" && env -u NODE_AUTH_TOKEN -u NPM_CONFIG_USERCONFIG npm install --ignore-scripts --userconfig /dev/null 2>&1) || true
+    fi
+  done
+  if run_and_capture TEST_OUTPUT env AGENTXCHAIN_RELEASE_TARGET_VERSION="${TARGET_VERSION}" AGENTXCHAIN_RELEASE_PREFLIGHT=1 npm test; then
+    TEST_STATUS=0
+  else
+    TEST_STATUS=$?
   fi
-fi
-if [ -z "${TEST_FAIL:-}" ]; then
-  NODE_FAIL="$(printf '%s\n' "$TEST_OUTPUT" | awk '/^ℹ fail / { print $3; exit }')"
-  if [ -n "${NODE_FAIL:-}" ]; then
-    TEST_FAIL="${NODE_FAIL}"
-  elif printf '%s\n' "$TEST_OUTPUT" | grep -Eq '^[[:space:]]*Tests[[:space:]]+[0-9]+[[:space:]]+passed'; then
-    TEST_FAIL=0
+  TEST_PASS="$(printf '%s\n' "$TEST_OUTPUT" | awk '/^# pass / { print $3 }')"
+  TEST_FAIL="$(printf '%s\n' "$TEST_OUTPUT" | awk '/^# fail / { print $3 }')"
+  if [ -z "${TEST_PASS:-}" ]; then
+    VITEST_PASS="$(printf '%s\n' "$TEST_OUTPUT" | awk '/^[[:space:]]*Tests[[:space:]]+[0-9]+[[:space:]]+passed/ { for (i = 1; i <= NF; i++) if ($i ~ /^[0-9]+$/) { print $i; exit } }')"
+    NODE_PASS="$(printf '%s\n' "$TEST_OUTPUT" | awk '/^ℹ tests / { print $3; exit }')"
+    if [ -n "${VITEST_PASS:-}" ] && [ -n "${NODE_PASS:-}" ]; then
+      TEST_PASS="$((VITEST_PASS + NODE_PASS))"
+    elif [ -n "${NODE_PASS:-}" ]; then
+      TEST_PASS="${NODE_PASS}"
+    elif [ -n "${VITEST_PASS:-}" ]; then
+      TEST_PASS="${VITEST_PASS}"
+    fi
   fi
-fi
-if [ "$TEST_STATUS" -eq 0 ] && [ "${TEST_FAIL:-0}" = "0" ]; then
-  if [ -n "${TEST_PASS:-}" ]; then
-    pass "${TEST_PASS} tests passed, 0 failures"
+  if [ -z "${TEST_FAIL:-}" ]; then
+    NODE_FAIL="$(printf '%s\n' "$TEST_OUTPUT" | awk '/^ℹ fail / { print $3; exit }')"
+    if [ -n "${NODE_FAIL:-}" ]; then
+      TEST_FAIL="${NODE_FAIL}"
+    elif printf '%s\n' "$TEST_OUTPUT" | grep -Eq '^[[:space:]]*Tests[[:space:]]+[0-9]+[[:space:]]+passed'; then
+      TEST_FAIL=0
+    fi
+  fi
+  if [ "$TEST_STATUS" -eq 0 ] && [ "${TEST_FAIL:-0}" = "0" ]; then
+    if [ -n "${TEST_PASS:-}" ]; then
+      pass "${TEST_PASS} tests passed, 0 failures"
+    else
+      pass "npm test passed, 0 failures"
+    fi
   else
-    pass "npm test passed, 0 failures"
+    fail "npm test failed"
+    printf '%s\n' "$TEST_OUTPUT" | tail -20
   fi
-else
-  fail "npm test failed"
-  printf '%s\n' "$TEST_OUTPUT" | tail -20
 fi
 
 # 4. CHANGELOG has target version

package/src/commands/generate.js

@@ -1,6 +1,10 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
 import chalk from 'chalk';
-import { loadConfig } from '../lib/config.js';
+import { loadConfig, loadProjectContext } from '../lib/config.js';
 import { generateVSCodeFiles } from '../lib/generate-vscode.js';
+import { loadGovernedTemplate } from '../lib/governed-templates.js';
+import { buildGovernedPlanningArtifacts } from '../lib/planning-artifacts.js';
 
 export async function generateCommand() {
   const result = loadConfig();
@@ -42,3 +46,124 @@ export async function generateCommand() {
   console.log(chalk.dim('  Select an agent from the Chat dropdown to start a turn.'));
   console.log('');
 }
+
+function failPlanningGenerate(message, opts = {}) {
+  if (opts.json) {
+    console.log(JSON.stringify({ ok: false, error: message }, null, 2));
+  } else {
+    console.log(chalk.red(`  ${message}`));
+  }
+  process.exit(1);
+}
+
+export async function generatePlanningCommand(opts = {}) {
+  const context = loadProjectContext();
+  if (!context) {
+    failPlanningGenerate('No valid agentxchain.json found. Run `agentxchain init --governed` first.', opts);
+  }
+
+  if (context.version !== 4) {
+    failPlanningGenerate('`generate planning` only works in governed repos.', opts);
+  }
+
+  const templateId = context.rawConfig.template || 'generic';
+  let template;
+  try {
+    template = loadGovernedTemplate(templateId);
+  } catch (err) {
+    failPlanningGenerate(err.message, opts);
+  }
+
+  const projectName = context.config?.project?.name || context.rawConfig?.project?.name || 'AgentXchain Project';
+  const artifacts = buildGovernedPlanningArtifacts({
+    projectName,
+    routing: context.config.routing || {},
+    roles: context.config.roles || {},
+    template,
+    workflowKitConfig: context.config.workflow_kit || null,
+  });
+
+  const created = [];
+  const overwritten = [];
+  const skippedExisting = [];
+
+  for (const artifact of artifacts) {
+    const absPath = join(context.root, artifact.path);
+    if (existsSync(absPath)) {
+      if (opts.force) {
+        overwritten.push(artifact.path);
+      } else {
+        skippedExisting.push(artifact.path);
+        continue;
+      }
+    } else {
+      created.push(artifact.path);
+    }
+
+    if (opts.dryRun) {
+      continue;
+    }
+
+    const parentDir = dirname(absPath);
+    if (!existsSync(parentDir)) {
+      mkdirSync(parentDir, { recursive: true });
+    }
+    writeFileSync(absPath, artifact.content);
+  }
+
+  const payload = {
+    ok: true,
+    mode: 'planning',
+    dry_run: Boolean(opts.dryRun),
+    force: Boolean(opts.force),
+    template: template.id,
+    project: projectName,
+    total_artifacts: artifacts.length,
+    created,
+    overwritten,
+    skipped_existing: skippedExisting,
+  };
+
+  if (opts.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  console.log('');
+  console.log(chalk.bold('  Generating governed planning artifacts...'));
+  console.log(chalk.dim(`  Project: ${projectName}`));
+  console.log(chalk.dim(`  Template: ${template.id}`));
+  console.log('');
+
+  if (created.length > 0) {
+    console.log(chalk.green(`  ${opts.dryRun ? 'Would create' : 'Created'} ${created.length} artifact${created.length === 1 ? '' : 's'}:`));
+    for (const path of created) {
+      console.log(chalk.green(`    ${path}`));
+    }
+  }
+
+  if (overwritten.length > 0) {
+    console.log(chalk.yellow(`  ${opts.dryRun ? 'Would overwrite' : 'Overwrote'} ${overwritten.length} artifact${overwritten.length === 1 ? '' : 's'}:`));
+    for (const path of overwritten) {
+      console.log(chalk.yellow(`    ${path}`));
+    }
+  }
+
+  if (skippedExisting.length > 0) {
+    console.log(chalk.dim(`  Preserved ${skippedExisting.length} existing artifact${skippedExisting.length === 1 ? '' : 's'}:`));
+    for (const path of skippedExisting) {
+      console.log(chalk.dim(`    ${path}`));
+    }
+  }
+
+  if (created.length === 0 && overwritten.length === 0) {
+    console.log(chalk.dim(`  ${opts.force ? 'Nothing to overwrite.' : 'All scaffold-owned planning artifacts already exist.'}`));
+  }
+
+  if (opts.dryRun) {
+    console.log('');
+    console.log(chalk.dim('  No files were written. Re-run without `--dry-run` to apply.'));
+  }
+
+  console.log('');
+}

package/src/commands/init.js

@@ -5,8 +5,9 @@ import chalk from 'chalk';
 import inquirer from 'inquirer';
 import { CONFIG_FILE, LOCK_FILE, STATE_FILE } from '../lib/config.js';
 import { generateVSCodeFiles } from '../lib/generate-vscode.js';
-import { loadAllGovernedTemplates, loadGovernedTemplate, VALID_GOVERNED_TEMPLATE_IDS, buildSystemSpecContent } from '../lib/governed-templates.js';
+import { loadAllGovernedTemplates, loadGovernedTemplate, VALID_GOVERNED_TEMPLATE_IDS } from '../lib/governed-templates.js';
 import { normalizeWorkflowKit, VALID_PROMPT_TRANSPORTS } from '../lib/normalized-config.js';
+import { buildGovernedPlanningArtifacts, interpolateTemplateContent } from '../lib/planning-artifacts.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_DIR = join(__dirname, '../templates');
@@ -47,24 +48,11 @@ function loadTemplates() {
   return templates;
 }
 
-function interpolateTemplateContent(contentTemplate, projectName) {
-  return contentTemplate.replaceAll('{{project_name}}', projectName);
-}
-
 function appendPromptOverride(basePrompt, override) {
   if (!override || !override.trim()) return basePrompt;
   return `${basePrompt}\n\n---\n\n## Project-Type-Specific Guidance\n\n${override.trim()}\n`;
 }
 
-function appendAcceptanceHints(baseMatrix, acceptanceHints) {
-  if (!Array.isArray(acceptanceHints) || acceptanceHints.length === 0) {
-    return baseMatrix;
-  }
-
-  const hintLines = acceptanceHints.map((hint) => `- [ ] ${hint}`).join('\n');
-  return `${baseMatrix}\n\n## Template Guidance\n${hintLines}\n`;
-}
-
 function findGitRoot(startDir) {
   let current = resolve(startDir);
   while (true) {
@@ -598,20 +586,6 @@ export async function resolveGovernedInitAnswers(opts, prompt = (questions) => i
   };
 }
 
-function generateWorkflowKitPlaceholder(artifact, projectName) {
-  const filename = basename(artifact.path);
-  const title = filename.replace(/\.[^.]+$/, '').replace(/[-_]/g, ' ');
-
-  if (artifact.semantics === 'section_check' && artifact.semantics_config?.required_sections?.length) {
-    const sections = artifact.semantics_config.required_sections
-      .map(s => `${s}\n\n(Content here.)\n`)
-      .join('\n');
-    return `# ${title} — ${projectName}\n\n${sections}`;
-  }
-
-  return `# ${title} — ${projectName}\n\n(Operator fills this in.)\n`;
-}
-
 function cloneJsonCompatible(value) {
   return value == null ? value : JSON.parse(JSON.stringify(value));
 }
@@ -653,29 +627,6 @@ function buildScaffoldConfigFromTemplate(template, localDevRuntime, workflowKitC
   };
 }
 
-const PHASE_DISPLAY_NAMES = Object.freeze({
-  qa: 'QA',
-});
-
-function formatPhaseDisplayName(phaseKey) {
-  if (PHASE_DISPLAY_NAMES[phaseKey]) {
-    return PHASE_DISPLAY_NAMES[phaseKey];
-  }
-  return phaseKey.replace(/_/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
-}
-
-function buildRoadmapPhaseTable(routing, roles) {
-  const rows = Object.entries(routing).map(([phaseKey, phaseConfig]) => {
-    const phaseName = formatPhaseDisplayName(phaseKey);
-    const entryRole = phaseConfig.entry_role;
-    const role = roles[entryRole];
-    const goal = role?.mandate || phaseName;
-    const status = phaseKey === Object.keys(routing)[0] ? 'In progress' : 'Pending';
-    return `| ${phaseName} | ${goal} | ${status} |`;
-  });
-  return `| Phase | Goal | Status |\n|-------|------|--------|\n${rows.join('\n')}\n`;
-}
-
 function buildPlanningSummaryLines(template, workflowKitConfig) {
   const lines = [
     'PM_SIGNOFF.md / ROADMAP.md / SYSTEM_SPEC.md',
@@ -821,53 +772,20 @@ 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> 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${buildRoadmapPhaseTable(routing, roles)}`);
-  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`);
-  const baseAcceptanceMatrix = `# Acceptance Matrix — ${projectName}\n\n| Req # | Requirement | Acceptance criteria | Test status | Last tested | Status |\n|-------|-------------|-------------------|-------------|-------------|--------|\n| (QA fills this from ROADMAP.md) | | | | | |\n`;
-  writeFileSync(
-    join(dir, '.planning', 'acceptance-matrix.md'),
-    appendAcceptanceHints(baseAcceptanceMatrix, template.acceptance_hints)
-  );
-  writeFileSync(join(dir, '.planning', 'ship-verdict.md'), `# Ship Verdict — ${projectName}\n\n## Verdict: PENDING\n\n## QA Summary\n\n(QA writes the final ship/no-ship assessment here.)\n\n## Open Blockers\n\n(List any blocking issues.)\n\n## Conditions\n\n(List any conditions for shipping.)\n`);
-  writeFileSync(join(dir, '.planning', 'RELEASE_NOTES.md'), `# Release Notes — ${projectName}\n\n## User Impact\n\n(QA fills this during the QA phase)\n\n## Verification Summary\n\n(QA fills this during the QA phase)\n\n## Upgrade Notes\n\n(QA fills this during the QA phase)\n\n## Known Issues\n\n(QA fills this during the QA phase)\n`);
-  for (const artifact of template.planning_artifacts) {
-    writeFileSync(
-      join(dir, '.planning', artifact.filename),
-      interpolateTemplateContent(artifact.content_template, projectName)
-    );
-  }
-
-  // Workflow-kit custom artifacts — only scaffold files from explicit workflow_kit config
-  // that are not already handled by the default scaffold above
-  if (scaffoldWorkflowKitConfig && scaffoldWorkflowKitConfig.phases && typeof scaffoldWorkflowKitConfig.phases === 'object') {
-    const defaultScaffoldPaths = new Set([
-      '.planning/PM_SIGNOFF.md',
-      '.planning/ROADMAP.md',
-      '.planning/SYSTEM_SPEC.md',
-      '.planning/IMPLEMENTATION_NOTES.md',
-      '.planning/acceptance-matrix.md',
-      '.planning/ship-verdict.md',
-      '.planning/RELEASE_NOTES.md',
-    ]);
-
-    for (const phaseConfig of Object.values(scaffoldWorkflowKitConfig.phases)) {
-      if (!Array.isArray(phaseConfig.artifacts)) continue;
-      for (const artifact of phaseConfig.artifacts) {
-        if (!artifact.path || defaultScaffoldPaths.has(artifact.path)) continue;
-        const absPath = join(dir, artifact.path);
-        if (existsSync(absPath)) continue;
-
-        // Ensure parent directory exists
-        const parentDir = dirname(absPath);
-        if (!existsSync(parentDir)) mkdirSync(parentDir, { recursive: true });
-
-        // Generate placeholder content based on semantics type
-        const content = generateWorkflowKitPlaceholder(artifact, projectName);
-        writeFileSync(absPath, content);
-      }
+  for (const artifact of buildGovernedPlanningArtifacts({
+    projectName,
+    routing,
+    roles,
+    template,
+    workflowKitConfig: scaffoldWorkflowKitConfig,
+  })) {
+    const absPath = join(dir, artifact.path);
+    if (artifact.source === 'workflow_kit' && existsSync(absPath)) {
+      continue;
     }
+    const parentDir = dirname(absPath);
+    if (!existsSync(parentDir)) mkdirSync(parentDir, { recursive: true });
+    writeFileSync(absPath, artifact.content);
   }
 
   // TALK.md

package/src/lib/planning-artifacts.js

@@ -0,0 +1,131 @@
+import { basename } from 'node:path';
+import { buildSystemSpecContent } from './governed-templates.js';
+
+export const GOVERNED_BASELINE_PLANNING_PATHS = Object.freeze([
+  '.planning/PM_SIGNOFF.md',
+  '.planning/ROADMAP.md',
+  '.planning/SYSTEM_SPEC.md',
+  '.planning/IMPLEMENTATION_NOTES.md',
+  '.planning/acceptance-matrix.md',
+  '.planning/ship-verdict.md',
+  '.planning/RELEASE_NOTES.md',
+]);
+
+const PHASE_DISPLAY_NAMES = Object.freeze({
+  qa: 'QA',
+});
+
+function formatPhaseDisplayName(phaseKey) {
+  if (PHASE_DISPLAY_NAMES[phaseKey]) {
+    return PHASE_DISPLAY_NAMES[phaseKey];
+  }
+  return phaseKey.replace(/_/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+function buildRoadmapPhaseTable(routing, roles) {
+  const rows = Object.entries(routing).map(([phaseKey, phaseConfig]) => {
+    const phaseName = formatPhaseDisplayName(phaseKey);
+    const entryRole = phaseConfig.entry_role;
+    const role = roles[entryRole];
+    const goal = role?.mandate || phaseName;
+    const status = phaseKey === Object.keys(routing)[0] ? 'In progress' : 'Pending';
+    return `| ${phaseName} | ${goal} | ${status} |`;
+  });
+  return `| Phase | Goal | Status |\n|-------|------|--------|\n${rows.join('\n')}\n`;
+}
+
+export function interpolateTemplateContent(contentTemplate, projectName) {
+  return contentTemplate.replaceAll('{{project_name}}', projectName);
+}
+
+export function appendAcceptanceHints(baseMatrix, acceptanceHints) {
+  if (!Array.isArray(acceptanceHints) || acceptanceHints.length === 0) {
+    return baseMatrix;
+  }
+
+  const hintLines = acceptanceHints.map((hint) => `- [ ] ${hint}`).join('\n');
+  return `${baseMatrix}\n\n## Template Guidance\n${hintLines}\n`;
+}
+
+export function generateWorkflowKitPlaceholder(artifact, projectName) {
+  const filename = basename(artifact.path);
+  const title = filename.replace(/\.[^.]+$/, '').replace(/[-_]/g, ' ');
+
+  if (artifact.semantics === 'section_check' && artifact.semantics_config?.required_sections?.length) {
+    const sections = artifact.semantics_config.required_sections
+      .map((section) => `${section}\n\n(Content here.)\n`)
+      .join('\n');
+    return `# ${title} — ${projectName}\n\n${sections}`;
+  }
+
+  return `# ${title} — ${projectName}\n\n(Operator fills this in.)\n`;
+}
+
+export function buildGovernedPlanningArtifacts({ projectName, routing, roles, template, workflowKitConfig }) {
+  const artifacts = [
+    {
+      path: '.planning/PM_SIGNOFF.md',
+      source: 'core',
+      content: `# 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`,
+    },
+    {
+      path: '.planning/ROADMAP.md',
+      source: 'core',
+      content: `# Roadmap — ${projectName}\n\n## Phases\n\n${buildRoadmapPhaseTable(routing, roles)}`,
+    },
+    {
+      path: '.planning/SYSTEM_SPEC.md',
+      source: 'core',
+      content: buildSystemSpecContent(projectName, template?.system_spec_overlay),
+    },
+    {
+      path: '.planning/IMPLEMENTATION_NOTES.md',
+      source: 'core',
+      content: `# 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`,
+    },
+    {
+      path: '.planning/acceptance-matrix.md',
+      source: 'core',
+      content: appendAcceptanceHints(
+        `# Acceptance Matrix — ${projectName}\n\n| Req # | Requirement | Acceptance criteria | Test status | Last tested | Status |\n|-------|-------------|-------------------|-------------|-------------|--------|\n| (QA fills this from ROADMAP.md) | | | | | |\n`,
+        template?.acceptance_hints,
+      ),
+    },
+    {
+      path: '.planning/ship-verdict.md',
+      source: 'core',
+      content: `# Ship Verdict — ${projectName}\n\n## Verdict: PENDING\n\n## QA Summary\n\n(QA writes the final ship/no-ship assessment here.)\n\n## Open Blockers\n\n(List any blocking issues.)\n\n## Conditions\n\n(List any conditions for shipping.)\n`,
+    },
+    {
+      path: '.planning/RELEASE_NOTES.md',
+      source: 'core',
+      content: `# Release Notes — ${projectName}\n\n## User Impact\n\n(QA fills this during the QA phase)\n\n## Verification Summary\n\n(QA fills this during the QA phase)\n\n## Upgrade Notes\n\n(QA fills this during the QA phase)\n\n## Known Issues\n\n(QA fills this during the QA phase)\n`,
+    },
+  ];
+
+  for (const artifact of template?.planning_artifacts || []) {
+    artifacts.push({
+      path: `.planning/${artifact.filename}`,
+      source: 'template',
+      content: interpolateTemplateContent(artifact.content_template, projectName),
+    });
+  }
+
+  const seenPaths = new Set(GOVERNED_BASELINE_PLANNING_PATHS);
+  if (workflowKitConfig?.phases && typeof workflowKitConfig.phases === 'object') {
+    for (const phaseConfig of Object.values(workflowKitConfig.phases)) {
+      if (!Array.isArray(phaseConfig.artifacts)) continue;
+      for (const artifact of phaseConfig.artifacts) {
+        if (!artifact.path || seenPaths.has(artifact.path)) continue;
+        seenPaths.add(artifact.path);
+        artifacts.push({
+          path: artifact.path,
+          source: 'workflow_kit',
+          content: generateWorkflowKitPlaceholder(artifact, projectName),
+        });
+      }
+    }
+  }
+
+  return artifacts;
+}