agentxchain 2.102.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.102.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/decisions.js

@@ -5,9 +5,9 @@
  */
 
 import { resolve } from 'path';
-import { existsSync } from 'fs';
+import { existsSync, readFileSync } from 'fs';
 import chalk from 'chalk';
-import { readRepoDecisions, getActiveRepoDecisions, getRepoDecisionById } from '../lib/repo-decisions.js';
+import { readRepoDecisions, getActiveRepoDecisions, getRepoDecisionById, resolveDecisionAuthority } from '../lib/repo-decisions.js';
 
 /**
  * @param {object} opts - { json?: boolean, all?: boolean, show?: string, dir?: string }
@@ -39,6 +39,18 @@ export async function decisionsCommand(opts) {
     console.log(`  Phase:       ${dec.phase || '—'}`);
     console.log(`  Run:         ${(dec.run_id || '—').slice(0, 16)}`);
     console.log(`  Turn:        ${(dec.turn_id || '—').slice(0, 16)}`);
+    console.log(`  Durability:  ${dec.durability || 'repo'}`);
+    // Show decision authority if config has it
+    const config = loadConfig(root);
+    if (config && dec.role) {
+      const auth = resolveDecisionAuthority(dec.role, config);
+      if (auth !== null && !(typeof auth === 'object' && auth.unknown)) {
+        console.log(`  Authority:   ${auth} (${dec.role})`);
+      }
+    }
+    if (dec.overrides) {
+      console.log(`  Supersedes:  ${chalk.yellow(dec.overrides)}`);
+    }
     console.log(`  Created:     ${dec.created_at || '—'}`);
     if (dec.overridden_by) {
       console.log(`  Overridden:  ${chalk.yellow(dec.overridden_by)}`);
@@ -69,7 +81,11 @@ export async function decisionsCommand(opts) {
   for (const dec of decisions) {
     const status = formatStatus(dec.status);
     const runShort = (dec.run_id || '').slice(0, 12);
-    const override = dec.overridden_by ? chalk.dim(` → ${dec.overridden_by}`) : '';
+    const override = dec.overridden_by
+      ? chalk.dim(` → ${dec.overridden_by}`)
+      : dec.overrides
+        ? chalk.dim(` ← supersedes ${dec.overrides}`)
+        : '';
     console.log(`  ${chalk.cyan(dec.id)}  ${status}  ${chalk.dim(dec.category)}  ${dec.statement}${override}`);
     console.log(`    ${chalk.dim(`by ${dec.role || '?'} in ${runShort || '?'}`)}`);
   }
@@ -92,3 +108,13 @@ function findProjectRoot(dir) {
   }
   return null;
 }
+
+function loadConfig(root) {
+  const configPath = resolve(root, 'agentxchain.json');
+  if (!existsSync(configPath)) return null;
+  try {
+    return JSON.parse(readFileSync(configPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}

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/commands/role.js

@@ -37,13 +37,19 @@ function listRoles(roles, roleIds, opts) {
   }
 
   if (opts.json) {
-    const output = roleIds.map((id) => ({
-      id,
-      title: roles[id].title,
-      mandate: roles[id].mandate,
-      write_authority: roles[id].write_authority,
-      runtime: roles[id].runtime,
-    }));
+    const output = roleIds.map((id) => {
+      const entry = {
+        id,
+        title: roles[id].title,
+        mandate: roles[id].mandate,
+        write_authority: roles[id].write_authority,
+        runtime: roles[id].runtime,
+      };
+      if (typeof roles[id].decision_authority === 'number') {
+        entry.decision_authority = roles[id].decision_authority;
+      }
+      return entry;
+    });
     console.log(JSON.stringify(output, null, 2));
     return;
   }
@@ -56,7 +62,8 @@ function listRoles(roles, roleIds, opts) {
       : r.write_authority === 'proposed'
         ? chalk.yellow(r.write_authority)
         : chalk.dim(r.write_authority);
-    console.log(`  ${chalk.cyan(id)} — ${r.title} [${authority}] → ${chalk.dim(r.runtime)}`);
+    const decAuth = typeof r.decision_authority === 'number' ? chalk.dim(` dec:${r.decision_authority}`) : '';
+    console.log(`  ${chalk.cyan(id)} — ${r.title} [${authority}${decAuth}] → ${chalk.dim(r.runtime)}`);
   }
   console.log('');
   console.log(chalk.dim('  Usage: agentxchain role show <role_id>\n'));
@@ -81,13 +88,17 @@ function showRole(roleId, roles, roleIds, opts) {
   const r = roles[roleId];
 
   if (opts.json) {
-    console.log(JSON.stringify({
+    const entry = {
       id: roleId,
       title: r.title,
       mandate: r.mandate,
       write_authority: r.write_authority,
       runtime: r.runtime,
-    }, null, 2));
+    };
+    if (typeof r.decision_authority === 'number') {
+      entry.decision_authority = r.decision_authority;
+    }
+    console.log(JSON.stringify(entry, null, 2));
     return;
   }
 
@@ -101,6 +112,9 @@ function showRole(roleId, roles, roleIds, opts) {
   console.log(`  Title:      ${r.title}`);
   console.log(`  Mandate:    ${r.mandate}`);
   console.log(`  Authority:  ${authority}`);
+  if (typeof r.decision_authority === 'number') {
+    console.log(`  Decision:   ${r.decision_authority}`);
+  }
   console.log(`  Runtime:    ${chalk.dim(r.runtime)}`);
   console.log('');
 }

package/src/lib/dispatch-bundle.js

@@ -618,7 +618,7 @@ function renderContext(state, config, root, turn, role) {
 
   // Repo-level decisions that persist across runs
   if (state.repo_decisions && state.repo_decisions.length > 0) {
-    const repoDecMd = renderRepoDecisionsMarkdown(state.repo_decisions);
+    const repoDecMd = renderRepoDecisionsMarkdown(state.repo_decisions, config);
     if (repoDecMd) {
       lines.push(repoDecMd);
     }

package/src/lib/export-verifier.js

@@ -2,6 +2,7 @@ import { createHash } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
+import { summarizeRepoDecisions } from './repo-decisions.js';
 
 const SUPPORTED_EXPORT_SCHEMA_VERSIONS = new Set(['0.2', '0.3']);
 const VALID_FILE_FORMATS = new Set(['json', 'jsonl', 'text']);
@@ -369,38 +370,18 @@ function verifyDelegationSummary(artifact, errors) {
   }
 }
 
-function buildExpectedRepoDecisionsSummary(files) {
+function buildExpectedRepoDecisionsSummary(files, config = null) {
   const repoDecisionsData = files?.['.agentxchain/repo-decisions.jsonl']?.data;
   if (!Array.isArray(repoDecisionsData) || repoDecisionsData.length === 0) {
     return null;
   }
-
-  const active = repoDecisionsData.filter((d) => d.status === 'active');
-  const overridden = repoDecisionsData.filter((d) => d.status === 'overridden');
-
-  return {
-    total: repoDecisionsData.length,
-    active_count: active.length,
-    overridden_count: overridden.length,
-    active: active.map((d) => ({
-      id: d.id,
-      category: d.category,
-      statement: d.statement,
-      role: d.role,
-      run_id: d.run_id,
-    })),
-    overridden: overridden.map((d) => ({
-      id: d.id,
-      overridden_by: d.overridden_by,
-      statement: d.statement,
-    })),
-  };
+  return summarizeRepoDecisions(repoDecisionsData, config);
 }
 
 function verifyRepoDecisionsSummary(artifact, errors) {
   const summary = artifact.summary?.repo_decisions;
   const hasFile = '.agentxchain/repo-decisions.jsonl' in (artifact.files || {});
-  const expected = buildExpectedRepoDecisionsSummary(artifact.files);
+  const expected = buildExpectedRepoDecisionsSummary(artifact.files, artifact.config || null);
 
   if (summary === null && expected === null) {
     return;

package/src/lib/export.js

@@ -8,7 +8,7 @@ import { loadCoordinatorConfig, COORDINATOR_CONFIG_FILE } from './coordinator-co
 import { loadCoordinatorState } from './coordinator-state.js';
 import { normalizeRunProvenance } from './run-provenance.js';
 import { getDashboardPid, getDashboardSession } from '../commands/dashboard.js';
-import { readRepoDecisions } from './repo-decisions.js';
+import { readRepoDecisions, summarizeRepoDecisions } from './repo-decisions.js';
 import { RUN_EVENTS_PATH } from './run-events.js';
 
 const EXPORT_SCHEMA_VERSION = '0.3';
@@ -211,18 +211,8 @@ function buildDashboardSessionSummary(root) {
   };
 }
 
-export function buildRepoDecisionsSummary(root) {
-  const all = readRepoDecisions(root);
-  if (!all || all.length === 0) return null;
-  const active = all.filter(d => d.status === 'active');
-  const overridden = all.filter(d => d.status === 'overridden');
-  return {
-    total: all.length,
-    active_count: active.length,
-    overridden_count: overridden.length,
-    active: active.map(d => ({ id: d.id, category: d.category, statement: d.statement, role: d.role, run_id: d.run_id })),
-    overridden: overridden.map(d => ({ id: d.id, overridden_by: d.overridden_by, statement: d.statement })),
-  };
+export function buildRepoDecisionsSummary(root, config = null) {
+  return summarizeRepoDecisions(readRepoDecisions(root), config);
 }
 
 export function buildDelegationSummary(files) {
@@ -471,7 +461,7 @@ export function buildRunExport(startDir = process.cwd()) {
         coordinator_present: Object.keys(files).some((path) => path.startsWith('.agentxchain/multirepo/')),
         dashboard_session: buildDashboardSessionSummary(root),
         delegation_summary: buildDelegationSummary(files),
-        repo_decisions: buildRepoDecisionsSummary(root),
+        repo_decisions: buildRepoDecisionsSummary(root, rawConfig),
       },
       workspace: buildRunWorkspaceMetadata(root),
       files,

package/src/lib/governed-state.js

@@ -2437,7 +2437,7 @@ function _acceptGovernedTurnLocked(root, config, opts) {
   if (turnResult.decisions && turnResult.decisions.length > 0) {
     for (const dec of turnResult.decisions) {
       if (dec.overrides) {
-        const overrideCheck = validateOverride(root, dec);
+        const overrideCheck = validateOverride(root, { ...dec, role: dec.role || turnResult.role }, config);
         if (!overrideCheck.ok) {
           return {
             ok: false,
@@ -3359,6 +3359,8 @@ function _acceptGovernedTurnLocked(root, config, opts) {
           category: dec.category,
           statement: dec.statement,
           rationale: dec.rationale,
+          durability: dec.durability || 'repo',
+          overrides: dec.overrides || null,
           status: 'active',
           overridden_by: null,
           created_at: now,

package/src/lib/normalized-config.js

@@ -366,6 +366,11 @@ export function validateV4Config(data, projectRoot) {
       if (!VALID_WRITE_AUTHORITIES.includes(role.write_authority)) {
         errors.push(`Role "${id}": write_authority must be one of: ${VALID_WRITE_AUTHORITIES.join(', ')}`);
       }
+      if (role.decision_authority !== undefined && role.decision_authority !== null) {
+        if (!Number.isInteger(role.decision_authority) || role.decision_authority < 0 || role.decision_authority > 99) {
+          errors.push(`Role "${id}": decision_authority must be an integer between 0 and 99`);
+        }
+      }
       if (typeof role.runtime !== 'string' || !role.runtime.trim()) errors.push(`Role "${id}": runtime required`);
     }
   }

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;
+}

package/src/lib/repo-decisions.js

@@ -37,6 +37,74 @@ export function getRepoDecisionById(root, decisionId) {
   return readRepoDecisions(root).find(d => d.id === decisionId) || null;
 }
 
+export function getDecisionAuthorityMetadata(roleId, config) {
+  const resolved = resolveDecisionAuthority(roleId, config);
+  if (resolved === null) return null;
+  if (typeof resolved === 'object' && resolved.unknown) {
+    return {
+      level: resolved.level,
+      source: 'unknown_role',
+      role: roleId || null,
+    };
+  }
+  if (roleId === 'human') {
+    const explicitHumanAuthority = typeof config?.roles?.human?.decision_authority === 'number';
+    return {
+      level: resolved,
+      source: explicitHumanAuthority ? 'configured' : 'human_default',
+      role: roleId,
+    };
+  }
+  return {
+    level: resolved,
+    source: 'configured',
+    role: roleId || null,
+  };
+}
+
+export function summarizeRepoDecisions(decisions, config) {
+  if (!Array.isArray(decisions) || decisions.length === 0) return null;
+  const active = decisions.filter((d) => d.status === 'active');
+  const overridden = decisions.filter((d) => d.status === 'overridden');
+  const addAuthority = (decision) => {
+    const authority = getDecisionAuthorityMetadata(decision.role, config);
+    return {
+      id: decision.id,
+      category: decision.category,
+      statement: decision.statement,
+      role: decision.role,
+      run_id: decision.run_id,
+      overrides: decision.overrides || null,
+      durability: decision.durability || 'repo',
+      authority_level: authority?.level ?? null,
+      authority_source: authority?.source || null,
+    };
+  };
+  return {
+    total: decisions.length,
+    active_count: active.length,
+    overridden_count: overridden.length,
+    active: active.map(addAuthority),
+    overridden: overridden.map((d) => {
+      const authority = getDecisionAuthorityMetadata(d.role, config);
+      return {
+        id: d.id,
+        overridden_by: d.overridden_by,
+        statement: d.statement,
+        overrides: d.overrides || null,
+        durability: d.durability || 'repo',
+        role: d.role || null,
+        authority_level: authority?.level ?? null,
+        authority_source: authority?.source || null,
+      };
+    }),
+  };
+}
+
+export function buildRepoDecisionsSummary(decisions) {
+  return summarizeRepoDecisions(decisions, null);
+}
+
 // ── Write ───────────────────────────────────────────────────────────────────
 
 export function appendRepoDecision(root, entry) {
@@ -62,7 +130,16 @@ export function overrideRepoDecision(root, targetId, overridingId) {
 
 // ── Validate Override ───────────────────────────────────────────────────────
 
-export function validateOverride(root, decision) {
+/**
+ * Validate that an override is allowed.
+ * @param {string} root - project root
+ * @param {object} decision - the overriding decision (must have .overrides, .id, optionally .role)
+ * @param {object} [config] - agentxchain config (used for authority enforcement)
+ * @returns {{ ok: boolean, error?: string, warning?: string }}
+ *
+ * DEC-SPEC: .planning/DECISION_AUTHORITY_SPEC.md
+ */
+export function validateOverride(root, decision, config) {
   if (!decision.overrides) return { ok: true };
   const targetId = decision.overrides;
   const target = getRepoDecisionById(root, targetId);
@@ -75,21 +152,104 @@ export function validateOverride(root, decision) {
   if (target.status !== 'active') {
     return { ok: false, error: `decisions: ${targetId} has status "${target.status}", only active repo decisions can be overridden.` };
   }
+
+  // Authority enforcement (opt-in via decision_authority on roles)
+  const authorityResult = checkOverrideAuthority(decision, target, config);
+  if (!authorityResult.ok) return authorityResult;
+
+  return authorityResult.warning ? { ok: true, warning: authorityResult.warning } : { ok: true };
+}
+
+/**
+ * Resolve the decision_authority level for a role.
+ * - 'human' defaults to 100 unless explicitly configured.
+ * - Unknown roles default to 0 (with warning).
+ * - Null means opt-out (no enforcement).
+ */
+export function resolveDecisionAuthority(roleId, config) {
+  if (!config || !config.roles) return null;
+  if (roleId === 'human') {
+    const humanRole = config.roles.human;
+    if (humanRole && typeof humanRole.decision_authority === 'number') {
+      return humanRole.decision_authority;
+    }
+    return 100; // human default
+  }
+  const role = config.roles[roleId];
+  if (!role) return { level: 0, unknown: true };
+  if (typeof role.decision_authority !== 'number') return null;
+  return role.decision_authority;
+}
+
+/**
+ * Check whether the overriding role has sufficient authority to override
+ * a decision made by the target role.
+ */
+function checkOverrideAuthority(overridingDecision, targetDecision, config) {
+  if (!config || !config.roles) return { ok: true };
+
+  const overridingRole = overridingDecision.role;
+  const targetRole = targetDecision.role;
+
+  // Same-role override is always allowed
+  if (overridingRole && targetRole && overridingRole === targetRole) return { ok: true };
+
+  const targetAuth = resolveDecisionAuthority(targetRole, config);
+  const overridingAuth = resolveDecisionAuthority(overridingRole, config);
+
+  // Handle unknown target role
+  let warning;
+  if (targetAuth && typeof targetAuth === 'object' && targetAuth.unknown) {
+    warning = `decisions: target decision role '${targetRole}' not found in current config, treating as authority 0.`;
+    // targetAuth is effectively 0, allow override
+    return { ok: true, warning };
+  }
+
+  // Opt-in: if either side is null (not configured), allow
+  if (targetAuth === null || overridingAuth === null) return { ok: true };
+
+  // Handle unknown overriding role (shouldn't normally happen, but be safe)
+  const overridingLevel = (typeof overridingAuth === 'object' && overridingAuth.unknown) ? 0 : overridingAuth;
+  const targetLevel = (typeof targetAuth === 'object') ? 0 : targetAuth;
+
+  if (overridingLevel < targetLevel) {
+    return {
+      ok: false,
+      error: `decisions: role '${overridingRole}' (authority ${overridingLevel}) cannot override ${targetDecision.id} made by '${targetRole}' (authority ${targetLevel}). Override requires authority >= ${targetLevel}.`,
+    };
+  }
+
   return { ok: true };
 }
 
 // ── Render ──────────────────────────────────────────────────────────────────
 
-export function renderRepoDecisionsMarkdown(activeDecisions) {
+export function renderRepoDecisionsMarkdown(activeDecisions, config) {
   if (!activeDecisions || activeDecisions.length === 0) return '';
+  const hasAuthorityPolicy = Object.values(config?.roles || {}).some((role) => (
+    role && typeof role.decision_authority === 'number'
+  ));
   const lines = [
     '## Active Repo Decisions',
     '',
     'These decisions persist from prior governed runs. Comply or explicitly override with rationale.',
     '',
   ];
+  if (hasAuthorityPolicy) {
+    lines.push('When both roles declare `decision_authority`, overrides require authority greater than or equal to the originating role.');
+    lines.push('');
+  }
   for (const d of activeDecisions) {
-    lines.push(`- **${d.id}** (${d.category}): ${d.statement}`);
+    const authority = getDecisionAuthorityMetadata(d.role, config);
+    const authorityText = authority
+      ? authority.source === 'human_default'
+        ? ' authority 100 (human default)'
+        : authority.source === 'unknown_role'
+          ? ' authority 0 (role no longer in config)'
+          : ` authority ${authority.level}`
+      : '';
+    const supersedes = d.overrides ? ` Supersedes ${d.overrides}.` : '';
+    lines.push(`- **${d.id}** (${d.category}, by ${d.role || 'unknown'}${authorityText}): ${d.statement}${supersedes}`);
   }
   lines.push('');
   return lines.join('\n');

package/src/lib/report.js

@@ -1320,7 +1320,13 @@ export function formatGovernanceReportText(report) {
       lines.push('', 'Repo Decisions:');
       lines.push(`  Active: ${run.repo_decisions.active_count}  Overridden: ${run.repo_decisions.overridden_count}`);
       for (const d of run.repo_decisions.active) {
-        lines.push(`  - ${d.id} (${d.category}): ${d.statement}`);
+        const supersedes = d.overrides ? ` | supersedes ${d.overrides}` : '';
+        const authority = d.authority_level == null ? '' : ` | authority ${d.authority_level}${d.authority_source === 'human_default' ? ' (human default)' : ''}`;
+        lines.push(`  - ${d.id} (${d.category}): ${d.statement}${supersedes}${authority}`);
+      }
+      for (const d of run.repo_decisions.overridden || []) {
+        const authority = d.authority_level == null ? '' : ` | authority ${d.authority_level}${d.authority_source === 'human_default' ? ' (human default)' : ''}`;
+        lines.push(`  - ${d.id} (overridden by ${d.overridden_by || 'unknown'}${authority})`);
       }
     }
 
@@ -1825,10 +1831,20 @@ export function formatGovernanceReportMarkdown(report) {
     if (run.repo_decisions?.active?.length > 0) {
       lines.push('', '## Repo Decisions', '');
       lines.push(`Active: ${run.repo_decisions.active_count} | Overridden: ${run.repo_decisions.overridden_count}`, '');
-      lines.push('| ID | Category | Statement | Role | Run |', '|----|----------|-----------|------|-----|');
+      lines.push('| ID | Category | Statement | Role | Authority | Run | Supersedes |', '|----|----------|-----------|------|-----------|-----|------------|');
       for (const d of run.repo_decisions.active) {
         const stmt = (d.statement || '').replace(/\|/g, '\\|');
-        lines.push(`| ${d.id} | ${d.category} | ${stmt} | ${d.role || '—'} | \`${(d.run_id || '').slice(0, 12)}\` |`);
+        const authority = d.authority_level == null ? '—' : `${d.authority_level}${d.authority_source === 'human_default' ? ' (human default)' : ''}`;
+        lines.push(`| ${d.id} | ${d.category} | ${stmt} | ${d.role || '—'} | ${authority} | \`${(d.run_id || '').slice(0, 12)}\` | ${d.overrides || '—'} |`);
+      }
+      if (run.repo_decisions.overridden?.length > 0) {
+        lines.push('', 'Overridden decisions:', '');
+        lines.push('| ID | Statement | Authority | Overridden By |', '|----|-----------|-----------|---------------|');
+        for (const d of run.repo_decisions.overridden) {
+          const stmt = (d.statement || '').replace(/\|/g, '\\|');
+          const authority = d.authority_level == null ? '—' : `${d.authority_level}${d.authority_source === 'human_default' ? ' (human default)' : ''}`;
+          lines.push(`| ${d.id} | ${stmt} | ${authority} | ${d.overridden_by || '—'} |`);
+        }
       }
     }
 
@@ -2453,9 +2469,28 @@ function renderRunHtml(report) {
   if (run.repo_decisions?.active?.length > 0) {
     let rdHtml = `<p>Active: ${run.repo_decisions.active_count} | Overridden: ${run.repo_decisions.overridden_count}</p>`;
     rdHtml += htmlTable(
-      ['ID', 'Category', 'Statement', 'Role', 'Run'],
-      run.repo_decisions.active.map((d) => [esc(d.id), esc(d.category), esc(d.statement || ''), esc(d.role || '\u2014'), `<code>${esc((d.run_id || '').slice(0, 12))}</code>`]),
+      ['ID', 'Category', 'Statement', 'Role', 'Authority', 'Run', 'Supersedes'],
+      run.repo_decisions.active.map((d) => [
+        esc(d.id),
+        esc(d.category),
+        esc(d.statement || ''),
+        esc(d.role || '\u2014'),
+        esc(d.authority_level == null ? '\u2014' : `${d.authority_level}${d.authority_source === 'human_default' ? ' (human default)' : ''}`),
+        `<code>${esc((d.run_id || '').slice(0, 12))}</code>`,
+        esc(d.overrides || '\u2014'),
+      ]),
     );
+    if (run.repo_decisions.overridden?.length > 0) {
+      rdHtml += htmlTable(
+        ['ID', 'Statement', 'Authority', 'Overridden By'],
+        run.repo_decisions.overridden.map((d) => [
+          esc(d.id),
+          esc(d.statement || ''),
+          esc(d.authority_level == null ? '\u2014' : `${d.authority_level}${d.authority_source === 'human_default' ? ' (human default)' : ''}`),
+          esc(d.overridden_by || '\u2014'),
+        ]),
+      );
+    }
     sections.push(`<div class="section">${htmlSection('Repo Decisions', rdHtml)}</div>`);
   }