agentxchain 2.15.0 → 2.17.0

package/README.md

@@ -194,6 +194,8 @@ agentxchain.json
 .agentxchain/staging/<turn_id>/turn-result.json
 TALK.md
 .planning/
+
+The first-party governed workflow kit includes `.planning/SYSTEM_SPEC.md` alongside `PM_SIGNOFF.md`, `ROADMAP.md`, `acceptance-matrix.md`, and `ship-verdict.md`. `template validate --json` exposes this under the `workflow_kit` block.
 ```
 
 ### Runtime support today

package/bin/agentxchain.js

@@ -321,6 +321,7 @@ program
   .option('--auto-approve', 'Auto-approve all gates (non-interactive mode)')
   .option('--verbose', 'Stream adapter subprocess output')
   .option('--dry-run', 'Print what would be dispatched without executing')
+  .option('--no-report', 'Suppress automatic governance report after run completes')
   .action(runCommand);
 
 program

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "2.15.0",
+  "version": "2.17.0",
   "description": "CLI for AgentXchain — governed multi-agent software delivery",
   "type": "module",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "exports": {
     ".": "./bin/agentxchain.js",
+    "./adapter-interface": "./src/lib/adapter-interface.js",
     "./runner-interface": "./src/lib/runner-interface.js",
     "./run-loop": "./src/lib/run-loop.js"
   },
@@ -27,6 +28,7 @@
     "preflight:release:strict": "bash scripts/release-preflight.sh --strict",
     "postflight:release": "bash scripts/release-postflight.sh",
     "postflight:downstream": "bash scripts/release-downstream-truth.sh",
+    "sync:homebrew": "bash scripts/sync-homebrew.sh",
     "build:macos": "bun build bin/agentxchain.js --compile --target=bun-darwin-arm64 --outfile=dist/agentxchain-macos-arm64",
     "build:linux": "bun build bin/agentxchain.js --compile --target=bun-linux-x64 --outfile=dist/agentxchain-linux-x64",
     "publish:npm": "bash scripts/publish-npm.sh"

package/scripts/release-postflight.sh

@@ -78,6 +78,7 @@ REGISTRY_CHECKSUM=""
 PACKAGE_NAME="$(node -e "console.log(JSON.parse(require('fs').readFileSync('package.json', 'utf8')).name)")"
 PACKAGE_BIN_NAME="$(node -e "const pkg = JSON.parse(require('fs').readFileSync('package.json', 'utf8')); if (typeof pkg.bin === 'string') { console.log(pkg.name); process.exit(0); } const names = Object.keys(pkg.bin || {}); if (names.length !== 1) { console.error('package.json bin must declare exactly one entry'); process.exit(1); } console.log(names[0]);")"
 RUNNER_INTERFACE_VERSION_EXPECTED="$(node --input-type=module -e "import('./src/lib/runner-interface.js').then((mod) => { console.log(mod.RUNNER_INTERFACE_VERSION); }).catch((error) => { console.error(error.message); process.exit(1); });")"
+ADAPTER_INTERFACE_VERSION_EXPECTED="$(node --input-type=module -e "import('./src/lib/adapter-interface.js').then((mod) => { console.log(mod.ADAPTER_INTERFACE_VERSION); }).catch((error) => { console.error(error.message); process.exit(1); });")"
 
 pass() { PASS=$((PASS + 1)); echo "  PASS: $1"; }
 fail() { FAIL=$((FAIL + 1)); echo "  FAIL: $1"; }
@@ -178,17 +179,25 @@ EOF
 
   cat > "${consumer_root}/runner-export-smoke.mjs" <<'EOF'
 import { RUNNER_INTERFACE_VERSION, loadContext } from 'agentxchain/runner-interface';
+import { ADAPTER_INTERFACE_VERSION, dispatchLocalCli } from 'agentxchain/adapter-interface';
 import { runLoop } from 'agentxchain/run-loop';
 
 if (typeof loadContext !== 'function') {
   throw new Error('loadContext export missing');
 }
 
+if (typeof dispatchLocalCli !== 'function') {
+  throw new Error('dispatchLocalCli export missing');
+}
+
 if (typeof runLoop !== 'function') {
   throw new Error('runLoop export missing');
 }
 
-console.log(RUNNER_INTERFACE_VERSION);
+console.log(JSON.stringify({
+  runner_interface_version: RUNNER_INTERFACE_VERSION,
+  adapter_interface_version: ADAPTER_INTERFACE_VERSION
+}));
 EOF
 
   local runner_output
@@ -252,7 +261,7 @@ run_with_retry() {
 
 echo "AgentXchain v${TARGET_VERSION} Release Postflight"
 echo "====================================="
-echo "Checks release truth after publish: tag, registry visibility, metadata, CLI install smoke, and runner export smoke."
+echo "Checks release truth after publish: tag, registry visibility, metadata, CLI install smoke, and package export smoke."
 echo ""
 
 echo "[1/6] Git tag"
@@ -316,16 +325,23 @@ else
   printf '%s\n' "$EXEC_OUTPUT" | tail -20
 fi
 
-echo "[6/6] Runner export smoke"
+echo "[6/6] Package export smoke"
 if run_with_retry RUNNER_EXPORT_OUTPUT "runner export smoke" nonempty "" run_runner_export_smoke; then
-  RUNNER_EXPORT_VERSION="$(trim_last_line "$RUNNER_EXPORT_OUTPUT")"
+  RUNNER_EXPORT_JSON="$(trim_last_line "$RUNNER_EXPORT_OUTPUT")"
+  RUNNER_EXPORT_VERSION="$(printf '%s' "$RUNNER_EXPORT_JSON" | node --input-type=module -e "process.stdin.setEncoding('utf8'); let raw=''; process.stdin.on('data', (chunk) => raw += chunk); process.stdin.on('end', () => { const parsed = JSON.parse(raw); console.log(parsed.runner_interface_version || ''); });")"
+  ADAPTER_EXPORT_VERSION="$(printf '%s' "$RUNNER_EXPORT_JSON" | node --input-type=module -e "process.stdin.setEncoding('utf8'); let raw=''; process.stdin.on('data', (chunk) => raw += chunk); process.stdin.on('end', () => { const parsed = JSON.parse(raw); console.log(parsed.adapter_interface_version || ''); });")"
   if [[ "$RUNNER_EXPORT_VERSION" == "$RUNNER_INTERFACE_VERSION_EXPECTED" ]]; then
     pass "published runner exports import with interface ${RUNNER_INTERFACE_VERSION_EXPECTED}"
   else
     fail "published runner exports reported interface '${RUNNER_EXPORT_VERSION}', expected '${RUNNER_INTERFACE_VERSION_EXPECTED}'"
   fi
+  if [[ "$ADAPTER_EXPORT_VERSION" == "$ADAPTER_INTERFACE_VERSION_EXPECTED" ]]; then
+    pass "published adapter exports import with interface ${ADAPTER_INTERFACE_VERSION_EXPECTED}"
+  else
+    fail "published adapter exports reported interface '${ADAPTER_EXPORT_VERSION}', expected '${ADAPTER_INTERFACE_VERSION_EXPECTED}'"
+  fi
 else
-  fail "published runner exports install smoke failed"
+  fail "published runner/adapter exports install smoke failed"
   printf '%s\n' "$RUNNER_EXPORT_OUTPUT" | tail -20
 fi
 

package/scripts/release-preflight.sh

@@ -107,7 +107,7 @@ for example_dir in "${CLI_DIR}/../examples/mcp-echo-agent" "${CLI_DIR}/../exampl
     (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 npm test; then
+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=$?

package/scripts/sync-homebrew.sh

@@ -0,0 +1,225 @@
+#!/usr/bin/env bash
+# Sync Homebrew formula from live npm registry metadata.
+# Updates both the repo mirror (cli/homebrew/) and optionally the canonical tap.
+# Usage: bash scripts/sync-homebrew.sh --target-version <semver> [--push-tap] [--dry-run]
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+CLI_DIR="${SCRIPT_DIR}/.."
+REPO_ROOT="${CLI_DIR}/.."
+
+TARGET_VERSION=""
+PUSH_TAP=false
+DRY_RUN=false
+
+FORMULA_PATH="${CLI_DIR}/homebrew/agentxchain.rb"
+README_PATH="${CLI_DIR}/homebrew/README.md"
+CANONICAL_TAP_REPO="shivamtiwari93/homebrew-tap"
+PACKAGE_NAME="agentxchain"
+
+formula_url() {
+  local formula_path="$1"
+  grep -E '^\s*url\s+"' "$formula_path" | sed 's/.*url *"\([^"]*\)".*/\1/' || true
+}
+
+formula_sha() {
+  local formula_path="$1"
+  grep -E '^\s*sha256\s+"' "$formula_path" | sed 's/.*sha256 *"\([a-f0-9]*\)".*/\1/' || true
+}
+
+usage() {
+  echo "Usage: bash scripts/sync-homebrew.sh --target-version <semver> [--push-tap] [--dry-run]" >&2
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --target-version)
+      if [[ -z "${2:-}" ]]; then
+        echo "Error: --target-version requires a semver argument" >&2
+        usage
+        exit 1
+      fi
+      if ! [[ "$2" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+        echo "Invalid semver: $2" >&2
+        usage
+        exit 1
+      fi
+      TARGET_VERSION="$2"
+      shift 2
+      ;;
+    --push-tap)
+      PUSH_TAP=true
+      shift
+      ;;
+    --dry-run)
+      DRY_RUN=true
+      shift
+      ;;
+    *)
+      usage
+      exit 1
+      ;;
+  esac
+done
+
+if [[ -z "$TARGET_VERSION" ]]; then
+  echo "Error: --target-version is required" >&2
+  usage
+  exit 1
+fi
+
+echo "Homebrew Sync — ${PACKAGE_NAME}@${TARGET_VERSION}"
+echo "====================================="
+
+# --- Step 1: Fetch tarball URL from npm ---
+echo "[1/5] Fetching tarball URL from npm registry..."
+TARBALL_URL="$(npm view "${PACKAGE_NAME}@${TARGET_VERSION}" dist.tarball 2>/dev/null || true)"
+if [[ -z "$TARBALL_URL" ]]; then
+  echo "FAIL: npm registry does not serve ${PACKAGE_NAME}@${TARGET_VERSION}" >&2
+  exit 1
+fi
+echo "  tarball: ${TARBALL_URL}"
+
+# --- Step 2: Download tarball and compute SHA256 ---
+echo "[2/5] Computing SHA256 from registry tarball..."
+TARBALL_SHA="$(curl -sL "$TARBALL_URL" | shasum -a 256 | awk '{print $1}')"
+if [[ -z "$TARBALL_SHA" ]] || [[ ${#TARBALL_SHA} -ne 64 ]]; then
+  echo "FAIL: could not compute valid SHA256 from tarball" >&2
+  exit 1
+fi
+echo "  sha256: ${TARBALL_SHA}"
+
+# --- Step 3: Check if already in sync ---
+echo "[3/5] Checking repo mirror..."
+MIRROR_IN_SYNC=false
+if [[ -f "$FORMULA_PATH" ]]; then
+  CURRENT_URL="$(formula_url "$FORMULA_PATH")"
+  CURRENT_SHA="$(formula_sha "$FORMULA_PATH")"
+  if [[ "$CURRENT_URL" == "$TARBALL_URL" && "$CURRENT_SHA" == "$TARBALL_SHA" ]]; then
+    MIRROR_IN_SYNC=true
+    echo "  Repo mirror already matches npm registry."
+    if ! $PUSH_TAP; then
+      echo "====================================="
+      echo "SYNC COMPLETE — repo mirror already up to date."
+      exit 0
+    fi
+    echo "  Repo mirror is current, but canonical tap verification is still required."
+  fi
+  if ! $MIRROR_IN_SYNC; then
+    echo "  Current URL: ${CURRENT_URL}"
+    echo "  Current SHA: ${CURRENT_SHA}"
+    echo "  Updating to match registry..."
+  fi
+else
+  echo "  Formula not found at ${FORMULA_PATH} — will create."
+fi
+
+if $DRY_RUN; then
+  echo ""
+  echo "[DRY RUN] Would update:"
+  if $MIRROR_IN_SYNC; then
+    echo "  Repo mirror already matches:"
+    echo "    url -> ${TARBALL_URL}"
+    echo "    sha256 -> ${TARBALL_SHA}"
+  else
+    echo "  ${FORMULA_PATH}:"
+    echo "    url -> ${TARBALL_URL}"
+    echo "    sha256 -> ${TARBALL_SHA}"
+    echo "  ${README_PATH}:"
+    echo "    version -> ${TARGET_VERSION}"
+    echo "    tarball -> ${TARBALL_URL}"
+  fi
+  if $PUSH_TAP; then
+    echo "  Canonical tap ${CANONICAL_TAP_REPO}:"
+    echo "    Formula/agentxchain.rb -> ${TARBALL_URL}"
+    echo "    Formula/agentxchain.rb sha256 -> ${TARBALL_SHA}"
+  fi
+  echo "====================================="
+  echo "DRY RUN COMPLETE — no files modified."
+  exit 0
+fi
+
+# --- Step 4: Update repo mirror ---
+echo "[4/5] Updating repo mirror..."
+
+if $MIRROR_IN_SYNC; then
+  echo "  Repo mirror already in sync — no local file changes needed."
+else
+  # Update formula
+  ESCAPED_URL="$(printf '%s' "$TARBALL_URL" | sed 's/[&/\]/\\&/g')"
+  ESCAPED_SHA="$(printf '%s' "$TARBALL_SHA" | sed 's/[&/\]/\\&/g')"
+  sed -i.bak -E "s|^([[:space:]]*url \").*(\")|\1${ESCAPED_URL}\2|" "$FORMULA_PATH"
+  sed -i.bak -E "s|^([[:space:]]*sha256 \").*(\")|\1${ESCAPED_SHA}\2|" "$FORMULA_PATH"
+  rm -f "${FORMULA_PATH}.bak"
+
+  # Update README version and tarball lines
+  if [[ -f "$README_PATH" ]]; then
+    # Update version line: "- version: `X.Y.Z`"
+    sed -i.bak -E "s|^(- version: \`).*(\`)|\1${TARGET_VERSION}\2|" "$README_PATH"
+    # Update tarball line: "- source tarball: `URL`"
+    sed -i.bak -E "s|^(- source tarball: \`).*(\`)|\1${TARBALL_URL}\2|" "$README_PATH"
+    rm -f "${README_PATH}.bak"
+  fi
+
+  echo "  Updated ${FORMULA_PATH}"
+  echo "  Updated ${README_PATH}"
+fi
+
+# --- Step 5: Push to canonical tap (optional) ---
+if $PUSH_TAP; then
+  echo "[5/5] Pushing to canonical tap ${CANONICAL_TAP_REPO}..."
+  TAP_TMPDIR="$(mktemp -d "${TMPDIR:-/tmp}/homebrew-tap-sync.XXXXXX")"
+  TAP_REMOTE_URL="https://github.com/${CANONICAL_TAP_REPO}.git"
+  if [[ -n "${HOMEBREW_TAP_TOKEN:-}" ]]; then
+    TAP_REMOTE_URL="https://x-access-token:${HOMEBREW_TAP_TOKEN}@github.com/${CANONICAL_TAP_REPO}.git"
+  fi
+
+  if ! git clone "$TAP_REMOTE_URL" "$TAP_TMPDIR" 2>/dev/null; then
+    echo "FAIL: could not clone ${CANONICAL_TAP_REPO}" >&2
+    rm -rf "$TAP_TMPDIR"
+    exit 1
+  fi
+
+  TAP_FORMULA="${TAP_TMPDIR}/Formula/agentxchain.rb"
+  if [[ ! -f "$TAP_FORMULA" ]]; then
+    mkdir -p "${TAP_TMPDIR}/Formula"
+  fi
+
+  TAP_CURRENT_URL=""
+  TAP_CURRENT_SHA=""
+  if [[ -f "$TAP_FORMULA" ]]; then
+    TAP_CURRENT_URL="$(formula_url "$TAP_FORMULA")"
+    TAP_CURRENT_SHA="$(formula_sha "$TAP_FORMULA")"
+  fi
+
+  (
+    cd "$TAP_TMPDIR" || exit 1
+    if [[ "$TAP_CURRENT_URL" == "$TARBALL_URL" && "$TAP_CURRENT_SHA" == "$TARBALL_SHA" ]]; then
+      echo "  Canonical tap already in sync — no push needed."
+    else
+      cp "$FORMULA_PATH" "$TAP_FORMULA"
+      if ! git config user.name >/dev/null; then
+        git config user.name "${HOMEBREW_TAP_GIT_NAME:-github-actions[bot]}"
+      fi
+      if ! git config user.email >/dev/null; then
+        git config user.email "${HOMEBREW_TAP_GIT_EMAIL:-github-actions[bot]@users.noreply.github.com}"
+      fi
+      git add Formula/agentxchain.rb
+      git commit -m "agentxchain ${TARGET_VERSION}"
+      if ! git push origin HEAD:main; then
+        echo "FAIL: could not push to ${CANONICAL_TAP_REPO}" >&2
+        exit 1
+      fi
+      echo "  Pushed to ${CANONICAL_TAP_REPO}"
+    fi
+  )
+
+  rm -rf "$TAP_TMPDIR"
+else
+  echo "[5/5] Skipping tap push (--push-tap not set)."
+fi
+
+echo ""
+echo "====================================="
+echo "SYNC COMPLETE — Homebrew formula updated to ${PACKAGE_NAME}@${TARGET_VERSION}."
+exit 0

package/src/commands/init.js

@@ -5,7 +5,7 @@ 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 { loadGovernedTemplate, VALID_GOVERNED_TEMPLATE_IDS } from '../lib/governed-templates.js';
+import { loadGovernedTemplate, VALID_GOVERNED_TEMPLATE_IDS, buildSystemSpecContent } from '../lib/governed-templates.js';
 import { VALID_PROMPT_TRANSPORTS } from '../lib/normalized-config.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -128,14 +128,15 @@ const GOVERNED_ROUTING = {
 
 const GOVERNED_GATES = {
   planning_signoff: {
-    requires_files: ['.planning/PM_SIGNOFF.md', '.planning/ROADMAP.md'],
+    requires_files: ['.planning/PM_SIGNOFF.md', '.planning/ROADMAP.md', '.planning/SYSTEM_SPEC.md'],
     requires_human_approval: true
   },
   implementation_complete: {
+    requires_files: ['.planning/IMPLEMENTATION_NOTES.md'],
     requires_verification_pass: true
   },
   qa_ship_verdict: {
-    requires_files: ['.planning/acceptance-matrix.md', '.planning/ship-verdict.md'],
+    requires_files: ['.planning/acceptance-matrix.md', '.planning/ship-verdict.md', '.planning/RELEASE_NOTES.md'],
     requires_human_approval: true
   }
 };
@@ -166,6 +167,7 @@ You are the Product Manager. Your mandate: **${role.mandate}**
 2. **Challenge it.** Even if the work looks correct, identify at least one risk, scope gap, or assumption worth questioning. Rubber-stamping violates the protocol.
 3. **Create or refine planning artifacts:**
    - \`.planning/ROADMAP.md\` — what will be built, in what order, with acceptance criteria
+   - \`.planning/SYSTEM_SPEC.md\` — the baseline subsystem contract implementation will follow
    - \`.planning/PM_SIGNOFF.md\` — your formal sign-off when planning is complete
    - \`.planning/acceptance-matrix.md\` — the acceptance criteria checklist for QA
 4. **Propose the next role.** Typically \`dev\` after planning is complete, or \`eng_director\` if there's a technical deadlock.
@@ -175,6 +177,7 @@ You are the Product Manager. Your mandate: **${role.mandate}**
 To exit the planning phase, you must:
 - Ensure \`.planning/PM_SIGNOFF.md\` exists with your explicit sign-off
 - Ensure \`.planning/ROADMAP.md\` exists with clear acceptance criteria
+- Ensure \`.planning/SYSTEM_SPEC.md\` defines \`## Purpose\`, \`## Interface\`, and \`## Acceptance Tests\`
 - Set \`phase_transition_request: "implementation"\` in your turn result
 
 The orchestrator will evaluate the gate and may require human approval.
@@ -246,6 +249,7 @@ You are QA. Your mandate: **${role.mandate}**
 4. **Create review artifacts:**
    - \`.planning/acceptance-matrix.md\` — updated with pass/fail verdicts per criterion
    - \`.planning/ship-verdict.md\` — your overall ship/no-ship recommendation
+   - \`.planning/RELEASE_NOTES.md\` — user-facing release notes with impact and verification summary
 
 ## You Cannot Modify Code
 
@@ -273,12 +277,14 @@ Each objection must have:
 When you are satisfied the work meets acceptance criteria:
 1. Create \`.planning/ship-verdict.md\` with your verdict
 2. Create/update \`.planning/acceptance-matrix.md\` with all criteria checked
-3. Set \`run_completion_request: true\` in your turn result
+3. Create/update \`.planning/RELEASE_NOTES.md\` with \`## User Impact\` and \`## Verification Summary\`
+4. Set \`run_completion_request: true\` in your turn result
 
 **Only set \`run_completion_request: true\` when:**
 - All blocking objections from prior turns are resolved
 - The acceptance matrix shows all critical criteria passing
 - \`.planning/ship-verdict.md\` exists with an affirmative verdict
+- \`.planning/RELEASE_NOTES.md\` exists with real \`## User Impact\` and \`## Verification Summary\` content
 
 **Do NOT set \`run_completion_request: true\` if:**
 - You have unresolved blocking objections
@@ -531,12 +537,15 @@ 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## 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| Phase | Goal | Status |\n|-------|------|--------|\n| Planning | Align scope, requirements, acceptance criteria | In progress |\n| Implementation | Build and verify | Pending |\n| QA | Challenge correctness and ship readiness | Pending |\n`);
+  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),
@@ -658,8 +667,9 @@ async function initGoverned(opts) {
   console.log(`    ${chalk.dim('│')}    ${chalk.dim('├──')} reviews/`);
   console.log(`    ${chalk.dim('│')}    ${chalk.dim('└──')} dispatch/`);
   console.log(`    ${chalk.dim('├──')} .planning/`);
-  console.log(`    ${chalk.dim('│')}    ${chalk.dim('├──')} PM_SIGNOFF.md / ROADMAP.md`);
-  console.log(`    ${chalk.dim('│')}    ${chalk.dim('└──')} acceptance-matrix.md / ship-verdict.md`);
+  console.log(`    ${chalk.dim('│')}    ${chalk.dim('├──')} PM_SIGNOFF.md / ROADMAP.md / SYSTEM_SPEC.md`);
+  console.log(`    ${chalk.dim('│')}    ${chalk.dim('├──')} acceptance-matrix.md / ship-verdict.md`);
+  console.log(`    ${chalk.dim('│')}    ${chalk.dim('└──')} RELEASE_NOTES.md`);
   console.log(`    ${chalk.dim('└──')} TALK.md`);
   console.log('');
   console.log(`  ${chalk.dim('Roles:')} pm, dev, qa, eng_director`);

package/src/commands/migrate.js

@@ -165,14 +165,15 @@ export async function migrateCommand(opts) {
     routing,
     gates: {
       planning_signoff: {
-        requires_files: ['.planning/PM_SIGNOFF.md', '.planning/ROADMAP.md'],
+        requires_files: ['.planning/PM_SIGNOFF.md', '.planning/ROADMAP.md', '.planning/SYSTEM_SPEC.md'],
         requires_human_approval: true
       },
       implementation_complete: {
+        requires_files: ['.planning/IMPLEMENTATION_NOTES.md'],
         requires_verification_pass: true
       },
       qa_ship_verdict: {
-        requires_files: ['.planning/acceptance-matrix.md', '.planning/ship-verdict.md'],
+        requires_files: ['.planning/acceptance-matrix.md', '.planning/ship-verdict.md', '.planning/RELEASE_NOTES.md'],
         requires_human_approval: true
       }
     },
@@ -311,8 +312,11 @@ ${report.requires_human_review.map((r, i) => `${i + 1}. ${r}`).join('\n')}
   const planningFiles = {
     'PM_SIGNOFF.md': `# PM Signoff — ${projectName}\n\nApproved: NO\n`,
     'ROADMAP.md': `# Roadmap — ${projectName}\n\n(Migrated from v3. Review and update.)\n`,
+    'SYSTEM_SPEC.md': `# System Spec — ${projectName}\n\n## Purpose\n\n(Describe the migrated subsystem purpose.)\n\n## Interface\n\n(List the commands, files, APIs, or contracts this repo owns.)\n\n## Behavior\n\n(Describe the expected runtime behavior.)\n\n## Error Cases\n\n(List the important failure modes.)\n\n## Acceptance Tests\n\n- [ ] Name the executable checks required before implementation resumes.\n\n## Open Questions\n\n- (Capture migration-specific gaps here.)\n`,
+    '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`,
     'acceptance-matrix.md': `# Acceptance Matrix — ${projectName}\n\n(QA fills this.)\n`,
-    'ship-verdict.md': `# Ship Verdict — ${projectName}\n\n## Verdict: PENDING\n`
+    'ship-verdict.md': `# Ship Verdict — ${projectName}\n\n## Verdict: PENDING\n`,
+    '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 [file, content] of Object.entries(planningFiles)) {
     const path = join(root, '.planning', file);

package/src/commands/multi.js

@@ -40,6 +40,7 @@ import {
   buildEscalationPayload,
 } from '../lib/coordinator-hooks.js';
 import { computeContextInvalidations } from '../lib/cross-repo-context.js';
+import { scaffoldRecoveryReport } from '../lib/workflow-gate-semantics.js';
 
 // ── multi init ─────────────────────────────────────────────────────────────
 
@@ -601,5 +602,6 @@ function blockCoordinator(workspacePath, state, blockedReason) {
     blocked_reason: blockedReason,
   };
   saveCoordinatorState(workspacePath, blockedState);
+  scaffoldRecoveryReport(workspacePath, blockedReason);
   return blockedState;
 }

package/src/commands/run.js

@@ -14,10 +14,12 @@
 
 import chalk from 'chalk';
 import { createInterface } from 'readline';
-import { readFileSync, existsSync } from 'fs';
+import { readFileSync, existsSync, mkdirSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { loadProjectContext, loadProjectState } from '../lib/config.js';
 import { runLoop } from '../lib/run-loop.js';
+import { buildRunExport } from '../lib/export.js';
+import { buildGovernanceReport, formatGovernanceReportMarkdown } from '../lib/report.js';
 import { dispatchApiProxy } from '../lib/adapters/api-proxy-adapter.js';
 import {
   dispatchLocalCli,
@@ -328,6 +330,32 @@ export async function runCommand(opts) {
     }
   }
 
+  // ── Auto governance report ──────────────────────────────────────────────
+  if (opts.report !== false && result.state) {
+    try {
+      const reportsDir = join(root, '.agentxchain', 'reports');
+      mkdirSync(reportsDir, { recursive: true });
+
+      const exportResult = buildRunExport(root);
+      if (exportResult.ok) {
+        const runId = result.state.run_id || 'unknown';
+        const exportPath = join(reportsDir, `export-${runId}.json`);
+        writeFileSync(exportPath, JSON.stringify(exportResult.export, null, 2));
+
+        const reportResult = buildGovernanceReport(exportResult.export, { input: exportPath });
+        const reportPath = join(reportsDir, `report-${runId}.md`);
+        writeFileSync(reportPath, formatGovernanceReportMarkdown(reportResult.report));
+
+        console.log('');
+        console.log(chalk.dim(`  Governance report: .agentxchain/reports/report-${runId}.md`));
+      } else {
+        console.log(chalk.dim(`  Governance report skipped: ${exportResult.error}`));
+      }
+    } catch (err) {
+      console.log(chalk.dim(`  Governance report failed: ${err.message}`));
+    }
+  }
+
   // ── Exit code ───────────────────────────────────────────────────────────
   const successReasons = new Set(['completed', 'gate_held', 'caller_stopped', 'max_turns_reached']);
   if (result.ok || successReasons.has(result.stop_reason)) {

package/src/commands/template-set.js

@@ -2,7 +2,7 @@ import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import chalk from 'chalk';
 import { CONFIG_FILE } from '../lib/config.js';
-import { loadGovernedTemplate, VALID_GOVERNED_TEMPLATE_IDS } from '../lib/governed-templates.js';
+import { loadGovernedTemplate, VALID_GOVERNED_TEMPLATE_IDS, SYSTEM_SPEC_OVERLAY_SEPARATOR } from '../lib/governed-templates.js';
 
 const LEDGER_PATH = '.agentxchain/decision-ledger.jsonl';
 const PROMPT_OVERRIDE_SEPARATOR = '## Project-Type-Specific Guidance';
@@ -76,6 +76,7 @@ export async function templateSetCommand(templateId, opts) {
     prompts_missing_paths: [],
     prompts_missing_files: [],
     acceptance_hints_status: 'none',
+    system_spec_overlay_status: 'none',
   };
 
   // Planning artifacts
@@ -127,6 +128,22 @@ export async function templateSetCommand(templateId, opts) {
     }
   }
 
+  // System spec overlay
+  const systemSpecOverlay = manifest.system_spec_overlay;
+  const systemSpecPath = join(root, '.planning', 'SYSTEM_SPEC.md');
+  if (systemSpecOverlay && Object.keys(systemSpecOverlay).length > 0) {
+    if (!existsSync(systemSpecPath)) {
+      plan.system_spec_overlay_status = 'missing_file';
+    } else {
+      const specContent = readFileSync(systemSpecPath, 'utf8');
+      if (specContent.includes(SYSTEM_SPEC_OVERLAY_SEPARATOR)) {
+        plan.system_spec_overlay_status = 'existing_guidance';
+      } else {
+        plan.system_spec_overlay_status = 'append';
+      }
+    }
+  }
+
   // ── Dry run: print plan and exit ──────────────────────────────────────
   if (opts.dryRun) {
     console.log(chalk.bold(`\n  Template: ${previousTemplate} → ${templateId}\n`));
@@ -175,6 +192,16 @@ export async function templateSetCommand(templateId, opts) {
     } else {
       console.log(`    ${chalk.dim('(none)')}`);
     }
+    console.log('\n  System spec overlay:');
+    if (plan.system_spec_overlay_status === 'append') {
+      console.log(`    .planning/SYSTEM_SPEC.md: ${chalk.green('WILL APPEND template guidance')}`);
+    } else if (plan.system_spec_overlay_status === 'existing_guidance') {
+      console.log(`    .planning/SYSTEM_SPEC.md: ${chalk.dim('ALREADY HAS guidance (skip)')}`);
+    } else if (plan.system_spec_overlay_status === 'missing_file') {
+      console.log(`    .planning/SYSTEM_SPEC.md: ${chalk.yellow('MISSING FILE (skip)')}`);
+    } else {
+      console.log(`    ${chalk.dim('(none)')}`);
+    }
     console.log(chalk.dim('\n  No changes written. Use without --dry-run to apply.\n'));
     process.exit(0);
   }
@@ -242,7 +269,24 @@ export async function templateSetCommand(templateId, opts) {
     console.log(chalk.yellow('  Warning: .planning/acceptance-matrix.md not found. Skipping template guidance hints.'));
   }
 
-  // 5. Decision ledger
+  // 5. Append system spec overlay
+  if (plan.system_spec_overlay_status === 'append' && existsSync(systemSpecPath)) {
+    const specContent = readFileSync(systemSpecPath, 'utf8');
+    const guidanceLines = [];
+    if (systemSpecOverlay.purpose_guidance) guidanceLines.push(`**Purpose:** ${systemSpecOverlay.purpose_guidance}`);
+    if (systemSpecOverlay.interface_guidance) guidanceLines.push(`**Interface:** ${systemSpecOverlay.interface_guidance}`);
+    if (systemSpecOverlay.behavior_guidance) guidanceLines.push(`**Behavior:** ${systemSpecOverlay.behavior_guidance}`);
+    if (systemSpecOverlay.error_cases_guidance) guidanceLines.push(`**Error Cases:** ${systemSpecOverlay.error_cases_guidance}`);
+    if (systemSpecOverlay.acceptance_tests_guidance) guidanceLines.push(`**Acceptance Tests:**\n${systemSpecOverlay.acceptance_tests_guidance}`);
+    if (systemSpecOverlay.extra_sections) guidanceLines.push(systemSpecOverlay.extra_sections);
+    const guidanceBlock = guidanceLines.join('\n\n');
+    const appended = `${specContent}\n\n${SYSTEM_SPEC_OVERLAY_SEPARATOR}\n\n${guidanceBlock}\n`;
+    writeFileSync(systemSpecPath, appended);
+  } else if (plan.system_spec_overlay_status === 'missing_file') {
+    console.log(chalk.yellow('  Warning: .planning/SYSTEM_SPEC.md not found. Skipping template spec overlay.'));
+  }
+
+  // 6. Decision ledger
   const ledgerEntry = {
     type: 'template_set',
     timestamp: new Date().toISOString(),
@@ -260,6 +304,8 @@ export async function templateSetCommand(templateId, opts) {
     prompt_missing_files: plan.prompts_missing_files,
     acceptance_hints_appended: plan.acceptance_hints_status === 'append',
     acceptance_hints_skipped_reason: plan.acceptance_hints_status === 'append' ? null : plan.acceptance_hints_status,
+    system_spec_overlay_appended: plan.system_spec_overlay_status === 'append',
+    system_spec_overlay_skipped_reason: plan.system_spec_overlay_status === 'append' ? null : plan.system_spec_overlay_status,
     operator: 'human',
   };
   appendJsonl(root, LEDGER_PATH, ledgerEntry);
@@ -275,5 +321,8 @@ export async function templateSetCommand(templateId, opts) {
   if (plan.acceptance_hints_status === 'append') {
     console.log(`  Appended template guidance to acceptance-matrix.md`);
   }
+  if (plan.system_spec_overlay_status === 'append') {
+    console.log(`  Appended template-specific guidance to SYSTEM_SPEC.md`);
+  }
   console.log('');
 }