agentxchain 2.14.0 → 2.16.0

package/README.md

@@ -100,10 +100,10 @@ For initiatives spanning multiple governed repos, use the coordinator to add cro
 npx agentxchain init --governed --template api-service --dir repos/backend -y
 npx agentxchain init --governed --template web-app --dir repos/frontend -y
 agentxchain multi init
-agentxchain multi step --repo backend --role pm
+agentxchain multi step --json
 ```
 
-See the [multi-repo quickstart](https://agentxchain.dev/docs/quickstart#multi-repo-cold-start) for the full cold-start walkthrough.
+If the coordinator enters `blocked`, fix the cause and run `agentxchain multi resume` before continuing with `multi step` or `multi approve-gate`. See the [multi-repo quickstart](https://agentxchain.dev/docs/quickstart#multi-repo-cold-start) for the full cold-start walkthrough.
 
 ### Migrate a legacy project
 
@@ -132,7 +132,10 @@ agentxchain step
 | `template validate` | Prove the template registry, workflow-kit scaffold contract, and planning artifact completeness (`--json` exposes a `workflow_kit` block) |
 | `verify protocol` | Run the shipped protocol conformance suite against a target implementation |
 | `dashboard` | Open the local governance dashboard in your browser for repo-local runs or multi-repo coordinator initiatives, including pending gate approvals |
-| `plugin install|list|remove` | Install, inspect, or remove governed hook plugins backed by `agentxchain-plugin.json` manifests |
+| `multi init\|status\|step\|resume\|approve-gate\|resync` | Run the multi-repo coordinator lifecycle, including blocked-state recovery via `multi resume` |
+| `intake record\|triage\|approve\|plan\|start\|scan\|resolve` | Continuous-delivery intake: turn delivery signals into governed work items |
+| `intake handoff` | Bridge a planned intake intent to a coordinator workstream for multi-repo execution |
+| `plugin install\|list\|remove` | Install, inspect, or remove governed hook plugins backed by `agentxchain-plugin.json` manifests |
 
 ### Shared utilities
 
@@ -191,12 +194,15 @@ 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
 
 - `manual`: implemented
 - `local_cli`: implemented
+- `mcp`: implemented for stdio and streamable HTTP tool-contract dispatch
 - `api_proxy`: implemented for synchronous review-only turns and stages a provider-backed result during `step`
 
 ## Legacy IDE Mode

package/bin/agentxchain.js

@@ -88,6 +88,7 @@ import {
   multiInitCommand,
   multiStatusCommand,
   multiStepCommand,
+  multiResumeCommand,
   multiApproveGateCommand,
   multiResyncCommand,
 } from '../src/commands/multi.js';
@@ -96,6 +97,7 @@ import { intakeTriageCommand } from '../src/commands/intake-triage.js';
 import { intakeApproveCommand } from '../src/commands/intake-approve.js';
 import { intakePlanCommand } from '../src/commands/intake-plan.js';
 import { intakeStartCommand } from '../src/commands/intake-start.js';
+import { intakeHandoffCommand } from '../src/commands/intake-handoff.js';
 import { intakeScanCommand } from '../src/commands/intake-scan.js';
 import { intakeResolveCommand } from '../src/commands/intake-resolve.js';
 import { intakeStatusCommand } from '../src/commands/intake-status.js';
@@ -319,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
@@ -415,6 +418,12 @@ multiCmd
   .option('-j, --json', 'Output as JSON')
   .action(multiStepCommand);
 
+multiCmd
+  .command('resume')
+  .description('Clear a blocked coordinator state after operator recovery')
+  .option('-j, --json', 'Output as JSON')
+  .action(multiResumeCommand);
+
 multiCmd
   .command('approve-gate')
   .description('Approve a pending phase transition or completion gate')
@@ -449,7 +458,7 @@ intakeCmd
 intakeCmd
   .command('triage')
   .description('Triage a detected intent — set priority, template, charter, and acceptance')
-  .requiredOption('--intent <id>', 'Intent ID to triage')
+  .option('--intent <id>', 'Intent ID to triage')
   .option('--priority <level>', 'Priority level (p0, p1, p2, p3)')
   .option('--template <id>', 'Governed template (generic, api-service, cli-tool, library, web-app)')
   .option('--charter <text>', 'Delivery charter text')
@@ -486,10 +495,19 @@ intakeCmd
   .option('-j, --json', 'Output as JSON')
   .action(intakeStartCommand);
 
+intakeCmd
+  .command('handoff')
+  .description('Hand off a planned intent to a coordinator workstream')
+  .option('--intent <id>', 'Intent ID to hand off')
+  .option('--coordinator-root <path>', 'Path to the coordinator workspace root')
+  .option('--workstream <id>', 'Coordinator workstream ID')
+  .option('-j, --json', 'Output as JSON')
+  .action(intakeHandoffCommand);
+
 intakeCmd
   .command('scan')
   .description('Scan a structured source snapshot into intake events')
-  .requiredOption('--source <id>', 'Source type: ci_failure, git_ref_change, schedule')
+  .option('--source <id>', 'Source type: ci_failure, git_ref_change, schedule')
   .option('--file <path>', 'Path to snapshot JSON file')
   .option('--stdin', 'Read snapshot from stdin')
   .option('-j, --json', 'Output as JSON')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "2.14.0",
+  "version": "2.16.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-downstream-truth.sh

@@ -47,7 +47,7 @@ if [[ -z "$TARGET_VERSION" ]]; then
 fi
 
 PACKAGE_NAME="$(node -e "console.log(JSON.parse(require('fs').readFileSync('package.json', 'utf8')).name)")"
-HOMEBREW_FORMULA="${REPO_ROOT}/cli/homebrew/agentxchain.rb"
+CANONICAL_HOMEBREW_FORMULA_URL="${AGENTXCHAIN_DOWNSTREAM_FORMULA_URL:-https://raw.githubusercontent.com/shivamtiwari93/homebrew-tap/main/Formula/agentxchain.rb}"
 
 PASS=0
 FAIL=0
@@ -57,7 +57,7 @@ fail() { FAIL=$((FAIL + 1)); echo "  FAIL: $1"; }
 
 echo "AgentXchain v${TARGET_VERSION} Downstream Release Truth"
 echo "====================================="
-echo "Checks downstream surfaces after publish: GitHub release, Homebrew tap."
+echo "Checks downstream surfaces after publish: GitHub release, canonical Homebrew tap."
 echo ""
 
 # --- Check 1: GitHub Release ---
@@ -85,38 +85,39 @@ else
 fi
 
 # --- Get registry tarball URL and compute SHA ---
-echo "[2/3] Homebrew tap SHA matches registry tarball"
+echo "[2/3] Canonical Homebrew tap SHA matches registry tarball"
 REGISTRY_TARBALL_URL="$(npm view "${PACKAGE_NAME}@${TARGET_VERSION}" dist.tarball 2>/dev/null || true)"
+FORMULA_CONTENT="$(curl -fsSL "$CANONICAL_HOMEBREW_FORMULA_URL" 2>/dev/null || true)"
 if [[ -z "$REGISTRY_TARBALL_URL" ]]; then
   fail "cannot fetch registry tarball URL for ${PACKAGE_NAME}@${TARGET_VERSION}"
+elif [[ -z "$FORMULA_CONTENT" ]]; then
+  fail "cannot fetch canonical Homebrew formula from ${CANONICAL_HOMEBREW_FORMULA_URL}"
 else
   REGISTRY_SHA="$(curl -sL "$REGISTRY_TARBALL_URL" | shasum -a 256 | awk '{print $1}')"
   if [[ -z "$REGISTRY_SHA" ]]; then
     fail "cannot compute SHA256 of registry tarball"
-  elif [[ ! -f "$HOMEBREW_FORMULA" ]]; then
-    fail "Homebrew formula not found at ${HOMEBREW_FORMULA}"
   else
-    FORMULA_SHA="$(grep -E '^\s*sha256\s+"' "$HOMEBREW_FORMULA" | sed 's/.*sha256 *"\([a-f0-9]*\)".*/\1/')"
+    FORMULA_SHA="$(printf '%s\n' "$FORMULA_CONTENT" | grep -E '^\s*sha256\s+"' | sed 's/.*sha256 *"\([a-f0-9]*\)".*/\1/')"
     if [[ "$REGISTRY_SHA" == "$FORMULA_SHA" ]]; then
-      pass "Homebrew formula SHA256 matches registry tarball (${REGISTRY_SHA:0:16}...)"
+      pass "canonical Homebrew formula SHA256 matches registry tarball (${REGISTRY_SHA:0:16}...)"
     else
-      fail "Homebrew formula SHA256 mismatch: formula=${FORMULA_SHA:0:16}... registry=${REGISTRY_SHA:0:16}..."
+      fail "canonical Homebrew formula SHA256 mismatch: formula=${FORMULA_SHA:0:16}... registry=${REGISTRY_SHA:0:16}..."
     fi
   fi
 fi
 
 # --- Check 3: Homebrew tap URL matches registry tarball URL ---
-echo "[3/3] Homebrew tap URL matches registry tarball"
+echo "[3/3] Canonical Homebrew tap URL matches registry tarball"
 if [[ -z "$REGISTRY_TARBALL_URL" ]]; then
   fail "cannot verify URL — registry tarball URL unavailable"
-elif [[ ! -f "$HOMEBREW_FORMULA" ]]; then
-  fail "Homebrew formula not found at ${HOMEBREW_FORMULA}"
+elif [[ -z "$FORMULA_CONTENT" ]]; then
+  fail "cannot verify URL — canonical Homebrew formula unavailable"
 else
-  FORMULA_URL="$(grep -E '^\s*url\s+"' "$HOMEBREW_FORMULA" | sed 's/.*url *"\([^"]*\)".*/\1/')"
+  FORMULA_URL="$(printf '%s\n' "$FORMULA_CONTENT" | grep -E '^\s*url\s+"' | sed 's/.*url *"\([^"]*\)".*/\1/')"
   if [[ "$FORMULA_URL" == "$REGISTRY_TARBALL_URL" ]]; then
-    pass "Homebrew formula URL matches registry tarball"
+    pass "canonical Homebrew formula URL matches registry tarball"
   else
-    fail "Homebrew formula URL mismatch: formula=${FORMULA_URL} registry=${REGISTRY_TARBALL_URL}"
+    fail "canonical Homebrew formula URL mismatch: formula=${FORMULA_URL} registry=${REGISTRY_TARBALL_URL}"
   fi
 fi
 

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/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/intake-approve.js

@@ -1,17 +1,9 @@
 import chalk from 'chalk';
-import { findProjectRoot } from '../lib/config.js';
 import { approveIntent } from '../lib/intake.js';
+import { requireIntakeWorkspaceOrExit } from './intake-workspace.js';
 
 export async function intakeApproveCommand(opts) {
-  const root = findProjectRoot(process.cwd());
-  if (!root) {
-    if (opts.json) {
-      console.log(JSON.stringify({ ok: false, error: 'agentxchain.json not found' }, null, 2));
-    } else {
-      console.log(chalk.red('agentxchain.json not found'));
-    }
-    process.exit(2);
-  }
+  const root = requireIntakeWorkspaceOrExit(opts);
 
   if (!opts.intent) {
     const msg = '--intent <id> is required';