@friedbotstudio/create-baseline 0.2.1 → 0.4.0

package/README.md

@@ -37,11 +37,11 @@ A discipline layer for Claude Code. Hooks at every tool boundary, a workflow tha
 > [!IMPORTANT]
 > **Install in one line:** `npx @friedbotstudio/create-baseline ./your-project`
 >
-> The CLI fetches the published package, runs the install, and leaves your project with `.claude/`, `CLAUDE.md`, `docs/init/seed.md`, and `.mcp.json`. Re-run with `--merge` to bring an existing install forward; with `--dry-run` to preview without writing; with `doctor` to report drift.
+> The CLI fetches the published package, runs the install, and leaves your project with `.claude/`, `CLAUDE.md`, `docs/init/seed.md`, and `.mcp.json`. Re-run with the `upgrade` subcommand to bring an existing install forward (interactive in a TTY, batch-mode in CI). Add `--dry-run` to preview, and run `doctor` to report drift (pass `--json` for machine output).
 
 ## What this is
 
-The Claude Code Baseline is a repository overlay shipped via `npx @friedbotstudio/create-baseline ./target`. It installs **22 hooks** at Claude's tool boundaries, **36 skills** organised into nine categories, **1 subagent** for parallel work in isolated worktrees, an **11-phase workflow** from intake to commit, and **3 user-typed consent gates** that Claude cannot forge.
+The Claude Code Baseline is a repository overlay shipped via `npx @friedbotstudio/create-baseline ./target`. It installs **22 hooks** at Claude's tool boundaries, **37 skills** organised into nine categories, **1 subagent** for parallel work in isolated worktrees, an **11-phase workflow** from intake to commit, and **3 user-typed consent gates** that Claude cannot forge.
 
 Every soft engineering rule a team usually repeats every session — *don't push, don't `--amend`, don't self-approve specs, don't skip phases, don't mock internal modules* — becomes a structural guarantee because the hooks run **outside Claude's tool boundary**. Claude cannot disable a hook with a flag, cannot write a consent marker, cannot reorder the phases without an explicit exception that triage records on disk.
 
@@ -64,7 +64,7 @@ A team that installs the baseline stops typing *"don't push, don't `--amend`, do
 | **Hooks** at PreToolUse / PostToolUse / SessionStart / Stop / PreCompact / UserPromptSubmit | 22 | `.claude/hooks/` |
 | **Skills** across artifact drafting, workflow phases, phase workers, spec helpers, orchestration, memory, audit, alternate tracks, and shared globals | 36 | `.claude/skills/` |
 | **Subagent** — `swarm-worker`, executes pre-decided recipes inside isolated git worktrees | 1 | `.claude/agents/` |
-| **Workflow phases** — intake → scout → research → spec → tdd → simplify → security → integrate → document → archive → commit | 11 | enforced by `track_guard` |
+| **Workflow phases** — intake → scout → research → spec → tdd → simplify → security → integrate → document → archive → memory-flush → commit | 11 | enforced by `track_guard` |
 | **Consent gates** — `/approve-spec`, `/approve-swarm`, `/grant-commit`. User-typed; structurally un-invokable by Claude | 3 | `consent_gate_grant` UserPromptSubmit hook |
 | **MCP servers** declared in `.mcp.json` — `context7` (third-party API docs), `plantuml` (diagram render), `playwright` (cross-engine smoke) | 3 | `.mcp.json` |
 
@@ -94,12 +94,14 @@ npx @friedbotstudio/create-baseline ./your-project
 # Force-overwrite an existing install (interactive — type 'overwrite')
 npx @friedbotstudio/create-baseline ./your-project --overwrite
 
-# Three-way merge against a previously-installed baseline:
+# Upgrade an existing install against a newer baseline version.
+# In a TTY, each customised file becomes a keep-mine / take-theirs / abort
+# prompt. In CI / piped stdout, reproduces the prior --merge behaviour:
 #   - adds new baseline files
 #   - refreshes baseline files the user has not touched
 #   - preserves user-customised files (exit 3 if any)
 #   - removes baseline files the upstream removed (only if untouched locally)
-npx @friedbotstudio/create-baseline ./your-project --merge
+npx @friedbotstudio/create-baseline upgrade ./your-project
 
 # Preview without writing anything
 npx @friedbotstudio/create-baseline ./your-project --dry-run
@@ -124,6 +126,10 @@ npx @friedbotstudio/create-baseline doctor ./your-project
 # Strict mode — print TAMPERED: shipped vs observed sha256 for every
 # customised file and exit 1 on any drift.
 npx @friedbotstudio/create-baseline doctor ./your-project --strict
+
+# JSON mode — emit the structured report on stdout for CI parsers.
+# Same exit codes; honours --strict.
+npx @friedbotstudio/create-baseline doctor ./your-project --json
 ```
 
 ## Quickstart
@@ -148,13 +154,17 @@ cd ./your-project
 /harness
 ```
 
-The three consent gates pause the workflow until you type the corresponding command:
+The three workflow-phase consent gates pause the workflow until you type the corresponding command:
 
 - **`/approve-spec <slug>`** — after the spec phase, before any code is written
 - **`/approve-swarm <slug>`** — after `/swarm-plan`, before parallel dispatch
 - **`/grant-commit`** — after `/archive`, before the commit lands
 
-Each gate writes a short-lived consent marker via a UserPromptSubmit hook that runs *before* Claude is invoked on the body. Claude cannot forge the marker; the corresponding write-boundary guard validates it on disk before allowing the approval token through.
+A fourth consent gate sits outside the phase pipeline:
+
+- **`/grant-push`** — opens a 5-minute window for `git push` on a protected branch (per `project.json → git.protected_branches`). Pushes on non-protected branches need no consent.
+
+Each gate writes a short-lived consent marker via a UserPromptSubmit hook that runs *before* Claude is invoked on the body. Claude cannot forge the marker; the write-boundary guard validates it on disk before allowing the approval token through.
 
 ## How the enforcement works
 

package/bin/cli.js

@@ -2,7 +2,7 @@
 import { parseArgs } from 'node:util';
 import { fileURLToPath } from 'node:url';
 import { dirname, join, resolve } from 'node:path';
-import { readFile } from 'node:fs/promises';
+import { readFile, readdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 
 import * as io from '../src/cli/io.js';
@@ -17,18 +17,24 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = resolve(__dirname, '..');
 
 const HELP_TEXT = `Usage:
-  create-baseline <target> [options]      install/merge the baseline
+  create-baseline <target> [options]      install the baseline
+  create-baseline upgrade [target]        three-way merge against an installed baseline
   create-baseline doctor [target]         report drift in an installed target
 
 Materializes the Claude Code baseline (.claude/, CLAUDE.md, .mcp.json,
 docs/init/seed.md, plus vendored LICENSE/NOTICE) into <target>.
 
-Modes:
+Install modes:
   (default)        Fresh install. Refuses if any sentinel path already present.
   --force          Overwrite unconditionally (requires typing 'overwrite' in TTY).
-  --merge          Three-way merge against existing .baseline-manifest.json.
-                   Prunes baseline files removed upstream that the user hadn't
-                   touched; customized stale files are preserved (exit 3).
+  --dry-run        Print intended actions without writing.
+
+Upgrade:
+  Replaces the prior --merge flag. Reads <target>/.claude/.baseline-manifest.json
+  and runs a three-way merge against the shipped template. Prunes baseline files
+  removed upstream that the user hadn't touched; customized-stale files are
+  preserved (exit 3) — or interactively resolved when stdout is a TTY (keep
+  mine / take theirs / abort).
   --dry-run        Print intended actions without writing.
 
 Doctor:
@@ -38,6 +44,8 @@ Doctor:
   --strict          Promote customized to exit 1 and prefix tampered paths
                     with "TAMPERED:" with shipped vs observed sha256. Detects
                     post-install supply-chain tampering of the baseline tree.
+  --json            Emit the structured report as JSON to stdout instead of
+                    the text renderer. Honours --strict; same exit codes.
 
 PlantUML jar (~19 MB, fetched at install time from upstream):
   --no-plantuml       Skip the jar download entirely.
@@ -54,12 +62,24 @@ Misc:
 
 Exit codes:
   0  success / clean doctor
-  1  user abort, conflict-without-force/merge, or doctor reports missing files
-  2  argv error, non-TTY where TTY required, or doctor finds no manifest
-  3  --merge had skipped customizations (or stale-customized prunes)
+  1  user abort, conflict-without-force, doctor reports missing files, or upgrade aborted
+  2  argv error, non-TTY where TTY required, doctor finds no manifest, or --merge passed
+  3  upgrade had skipped customizations (or stale-customized prunes)
   4  --require-plantuml fetch failure
 `;
 
+const OPTIONS = {
+  help: { type: 'boolean', short: 'h' },
+  version: { type: 'boolean' },
+  force: { type: 'boolean' },
+  'dry-run': { type: 'boolean' },
+  'no-plantuml': { type: 'boolean' },
+  'require-plantuml': { type: 'boolean' },
+  'with-npmrc': { type: 'boolean' },
+  strict: { type: 'boolean' },
+  json: { type: 'boolean' },
+};
+
 async function readPackageVersion() {
   try {
     const pkg = JSON.parse(await readFile(join(PKG_ROOT, 'package.json'), 'utf8'));
@@ -77,16 +97,141 @@ function getTemplateDir() {
   throw new Error(`Template directory not found at ${candidate}. Run \`npm run build\` (or rely on prepack).`);
 }
 
-function listShippedFiles(templateDir) {
-  const files = [];
-  const walk = (dir, base) => {
-    for (const entry of require('node:fs').readdirSync(dir, { withFileTypes: true })) {
-      const full = join(dir, entry.name);
-      if (entry.isDirectory()) walk(full, base);
-      else if (entry.isFile()) files.push(full.slice(base.length + 1).split(require('node:path').sep).join('/'));
+async function listShippedFiles(templateDir) {
+  const out = [];
+  await walkFiles(templateDir, templateDir, out);
+  return out;
+}
+
+async function walkFiles(dir, base, acc) {
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) await walkFiles(full, base, acc);
+    else if (entry.isFile()) acc.push(full.slice(base.length + 1).split('/').join('/'));
+  }
+}
+
+async function dispatchInstall(target, values, templateDir) {
+  const dryRun = !!values['dry-run'];
+  if (process.stdout.isTTY && !values.force && !dryRun) {
+    return await runBrandedInstall(target, values, templateDir);
+  }
+  return await runPlainInstall(target, values, templateDir);
+}
+
+async function runBrandedInstall(target, values, templateDir) {
+  const tui = await import('../src/cli/tui/install.js');
+  return tui.run({
+    target,
+    opts: {
+      templateDir,
+      noPlantuml: !!values['no-plantuml'],
+      requirePlantuml: !!values['require-plantuml'],
+      withNpmrc: !!values['with-npmrc'],
+    },
+  });
+}
+
+async function runPlainInstall(target, values, templateDir) {
+  const dryRun = !!values['dry-run'];
+  if (values.force) {
+    if (!process.stdin.isTTY) {
+      io.error('--force requires an interactive TTY for the confirmation prompt');
+      return 2;
+    }
+    if (!dryRun) {
+      const answer = await io.ask("type 'overwrite' to proceed: ");
+      if (answer.toLowerCase() !== 'overwrite') {
+        io.error('confirmation declined');
+        return 1;
+      }
     }
-  };
-  return files;
+  }
+
+  try {
+    if (values.force) {
+      if (dryRun) io.log(`Would force-install into ${target}`);
+      else await forceInstall(templateDir, target, { withNpmrc: !!values['with-npmrc'] });
+    } else {
+      if (dryRun) io.log(`Would fresh-install into ${target}`);
+      else await freshInstall(templateDir, target, { withNpmrc: !!values['with-npmrc'] });
+    }
+  } catch (err) {
+    io.error(`install failed: ${err.message}`);
+    return 1;
+  }
+
+  if (!dryRun) {
+    const plantumlExit = await fetchPlantumlPlain(target, values);
+    if (plantumlExit !== 0) return plantumlExit;
+    io.log(`Installed manifest version 1 to ${target}.`);
+    io.log(`Pin via "@friedbotstudio/create-baseline@<exact-version>" in your bootstrap docs.`);
+  }
+  return 0;
+}
+
+async function fetchPlantumlPlain(target, values) {
+  const result = await fetchPlantumlIfMissing(target, {
+    noPlantuml: values['no-plantuml'],
+    requirePlantuml: values['require-plantuml'],
+  });
+  if (result.outcome === FETCH_OUTCOMES.WARNED_NETWORK_FAILURE
+      || result.outcome === FETCH_OUTCOMES.WARNED_HASH_MISMATCH) {
+    io.warn(`PlantUML jar fetch failed (${result.reason}); install continued. Retry with --require-plantuml or set system plantuml on PATH.`);
+    return 0;
+  }
+  if (result.outcome === FETCH_OUTCOMES.ERRORED_REQUIRE_PLANTUML) {
+    io.error(`--require-plantuml: ${result.reason}`);
+    return 4;
+  }
+  return 0;
+}
+
+async function dispatchUpgrade(target, values, templateDir) {
+  const manifestPath = join(target, '.claude/.baseline-manifest.json');
+  if (!existsSync(manifestPath)) {
+    io.error(`No baseline manifest at ${manifestPath}. Run a fresh install first.`);
+    return 2;
+  }
+  if (process.stdout.isTTY) {
+    const tui = await import('../src/cli/tui/upgrade.js');
+    return tui.run({
+      target,
+      opts: { templateDir, dryRun: !!values['dry-run'] },
+    });
+  }
+  return await runPlainUpgrade(target, values, templateDir, manifestPath);
+}
+
+async function runPlainUpgrade(target, values, templateDir, manifestPath) {
+  const oldManifest = await loadManifest(manifestPath);
+  const tplFiles = await listShippedFiles(templateDir);
+  const newManifest = await buildManifestFromDir(templateDir, tplFiles);
+  if (values['dry-run']) {
+    io.log(`Would upgrade ${tplFiles.length} files into ${target}`);
+    return 0;
+  }
+  const report = await threeWayMerge(templateDir, target, oldManifest, newManifest);
+  for (const action of report.actions) {
+    io.log(`${action.kind.padEnd(24)} ${action.path}`);
+  }
+  return report.exitCode;
+}
+
+async function dispatchDoctor(positionals, values) {
+  const target = resolve(positionals[1] ?? '.');
+  const report = await runDoctor(target, { strict: !!values.strict });
+  if (values.json) {
+    io.log(JSON.stringify(report));
+    return report.exitCode;
+  }
+  if (process.stdout.isTTY) {
+    const tui = await import('../src/cli/tui/doctor.js');
+    tui.render(report);
+  } else {
+    process.stdout.write(formatReport(report));
+  }
+  return report.exitCode;
 }
 
 async function main(argv) {
@@ -94,21 +239,15 @@ async function main(argv) {
   try {
     parsed = parseArgs({
       args: argv.slice(2),
-      options: {
-        help: { type: 'boolean', short: 'h' },
-        version: { type: 'boolean' },
-        force: { type: 'boolean' },
-        merge: { type: 'boolean' },
-        'dry-run': { type: 'boolean' },
-        'no-plantuml': { type: 'boolean' },
-        'require-plantuml': { type: 'boolean' },
-        'with-npmrc': { type: 'boolean' },
-        strict: { type: 'boolean' },
-      },
+      options: OPTIONS,
       strict: true,
       allowPositionals: true,
     });
   } catch (err) {
+    if (/--merge/.test(err.message)) {
+      io.error('--merge has been removed; use `create-baseline upgrade <target>` instead.');
+      return 2;
+    }
     io.error(err.message);
     return 2;
   }
@@ -116,26 +255,42 @@ async function main(argv) {
   const { values, positionals } = parsed;
 
   if (values.help) {
-    io.log(HELP_TEXT);
+    const version = await readPackageVersion();
+    if (process.stdout.isTTY) {
+      const meta = await import('../src/cli/tui/meta.js');
+      meta.renderHelp(HELP_TEXT, version);
+    } else {
+      io.log(HELP_TEXT);
+    }
     return 0;
   }
   if (values.version) {
-    io.log(await readPackageVersion());
+    const version = await readPackageVersion();
+    if (process.stdout.isTTY) {
+      const meta = await import('../src/cli/tui/meta.js');
+      meta.renderVersion(version);
+    } else {
+      io.log(version);
+    }
     return 0;
   }
 
-  // `doctor` subcommand: read-only drift check against an installed target's manifest.
   if (positionals[0] === 'doctor') {
-    const target = resolve(positionals[1] ?? '.');
-    const report = await runDoctor(target, { strict: !!values.strict });
-    io.log(formatReport(report));
-    return report.exitCode;
+    return await dispatchDoctor(positionals, values);
   }
 
-  if (values.force && values.merge) {
-    io.error('--force and --merge are mutually exclusive');
-    return 2;
+  if (positionals[0] === 'upgrade') {
+    const target = resolve(positionals[1] ?? '.');
+    let templateDir;
+    try {
+      templateDir = getTemplateDir();
+    } catch (err) {
+      io.error(err.message);
+      return 2;
+    }
+    return await dispatchUpgrade(target, values, templateDir);
   }
+
   if (values['no-plantuml'] && values['require-plantuml']) {
     io.error('--no-plantuml and --require-plantuml are mutually exclusive');
     return 2;
@@ -151,8 +306,6 @@ async function main(argv) {
   }
 
   const target = resolve(positionals[0]);
-  const dryRun = !!values['dry-run'];
-
   let templateDir;
   try {
     templateDir = getTemplateDir();
@@ -163,88 +316,13 @@ async function main(argv) {
 
   const sentinels = await scanSentinels(target);
   const hasConflict = sentinels.length > 0;
-
-  if (hasConflict && !values.force && !values.merge) {
+  if (hasConflict && !values.force) {
     io.error(`existing baseline detected at ${target}: ${sentinels.join(', ')}`);
-    io.error('pass --force to overwrite or --merge to three-way merge');
+    io.error('pass --force to overwrite or use `create-baseline upgrade <target>` to three-way merge');
     return 1;
   }
 
-  if (values.force) {
-    if (!process.stdin.isTTY) {
-      io.error('--force requires an interactive TTY for the confirmation prompt');
-      return 2;
-    }
-    if (!dryRun) {
-      const answer = await io.ask("type 'overwrite' to proceed: ");
-      if (answer.toLowerCase() !== 'overwrite') {
-        io.error('confirmation declined');
-        return 1;
-      }
-    }
-  }
-
-  if (values.merge) {
-    if (!process.stdin.isTTY && !dryRun) {
-      io.error('--merge requires an interactive TTY for the confirmation prompt');
-      return 2;
-    }
-    if (!dryRun) {
-      const answer = await io.ask("type 'merge' to proceed: ");
-      if (answer.toLowerCase() !== 'merge') {
-        io.error('confirmation declined');
-        return 1;
-      }
-    }
-  }
-
-  let exitCode = 0;
-  try {
-    if (values.merge) {
-      const oldManifest = await loadManifest(join(target, '.claude/.baseline-manifest.json'));
-      const tplFiles = listShippedFiles(templateDir);
-      const newManifest = await buildManifestFromDir(templateDir, tplFiles);
-      if (dryRun) {
-        io.log(`Would merge ${tplFiles.length} files into ${target}`);
-      } else {
-        const report = await threeWayMerge(templateDir, target, oldManifest, newManifest);
-        for (const a of report.actions) {
-          io.log(`${a.kind.padEnd(24)} ${a.path}`);
-        }
-        exitCode = report.exitCode;
-      }
-    } else if (values.force) {
-      if (dryRun) io.log(`Would force-install into ${target}`);
-      else await forceInstall(templateDir, target, { withNpmrc: !!values['with-npmrc'] });
-    } else {
-      if (dryRun) io.log(`Would fresh-install into ${target}`);
-      else await freshInstall(templateDir, target, { withNpmrc: !!values['with-npmrc'] });
-    }
-  } catch (err) {
-    io.error(`install failed: ${err.message}`);
-    return 1;
-  }
-
-  if (!dryRun) {
-    const fetchResult = await fetchPlantumlIfMissing(target, {
-      noPlantuml: values['no-plantuml'],
-      requirePlantuml: values['require-plantuml'],
-    });
-    if (fetchResult.outcome === FETCH_OUTCOMES.WARNED_NETWORK_FAILURE
-        || fetchResult.outcome === FETCH_OUTCOMES.WARNED_HASH_MISMATCH) {
-      io.warn(`PlantUML jar fetch failed (${fetchResult.reason}); install continued. Retry with --require-plantuml or set system plantuml on PATH.`);
-    } else if (fetchResult.outcome === FETCH_OUTCOMES.ERRORED_REQUIRE_PLANTUML) {
-      io.error(`--require-plantuml: ${fetchResult.reason}`);
-      return 4;
-    }
-  }
-
-  if (!dryRun && exitCode === 0) {
-    io.log(`Installed manifest version 1 to ${target}.`);
-    io.log(`Pin via "@friedbotstudio/create-baseline@<exact-version>" in your bootstrap docs.`);
-  }
-
-  return exitCode;
+  return await dispatchInstall(target, values, templateDir);
 }
 
 main(process.argv).then((code) => { process.exit(code); }).catch((err) => {

package/obj/template/.claude/commands/grant-push.md

@@ -0,0 +1,19 @@
+---
+description: Grant consent for Claude to run `git push`. Valid for 5 minutes. Required by the Git Commit Guard hook on protected branches.
+argument-hint: "[optional note]"
+allowed-tools: Bash(mkdir:*), Bash(date:*), Bash(tee:*), Bash(git:*), Write
+disable-model-invocation: true
+---
+
+Write a consent token to `.claude/state/push_consent` so the Git Commit Guard hook allows the next `git push` on a protected branch. The token is the current UNIX epoch timestamp on line 1; any optional note goes on line 2.
+
+How this works structurally: when the user typed `/grant-push`, the `consent_gate_grant` UserPromptSubmit hook ran *before* this body was passed to Claude and wrote a short-lived consent marker at `.claude/state/.push_consent_grant`. The `git_commit_guard` PreToolUse hook (Write matcher) reads that marker and allows Claude to write the consent file because the marker is fresh. Claude cannot forge the marker — that's what makes the gate structural. The Bash-matcher leg of the same guard then enforces the consent token on the actual `git push` invocation, but only when the current branch matches `project.json → git.protected_branches`.
+
+Steps:
+
+1. **Git-repo precheck.** Run `git rev-parse --is-inside-work-tree 2>/dev/null`. If the exit status is non-zero, this project is not a git repository: refuse to write the consent token and tell the user "Not a git repository — `/grant-push` is inapplicable. Push has no meaning outside a git repo." Stop here.
+2. Run `date +%s` to get the current epoch.
+3. Write the epoch (and the optional note `$ARGUMENTS` on line 2 if non-empty) to `.claude/state/push_consent`, overwriting any prior token.
+4. Confirm to the user: "Push consent granted at <epoch>, valid for 300s (until <HH:MM:SS local>). The next `git push` on a protected branch will be allowed. Pushes on branches NOT in `project.json → git.protected_branches` do not require this consent."
+
+Do not run `git push` yourself in this command. The user asks explicitly when they want a push; this command only opens the window.

package/obj/template/.claude/commands/init-project.md

@@ -63,7 +63,9 @@ The recommender's SKILL.md instructs it to:
 
 Capture both the narrative and the JSON. Save the JSON to `.claude/state/init/<timestamp>.recommender.json`.
 
-## Step 5 — Aggregate + present
+## Step 5 — Aggregate + present (REVIEW ONLY — NOTHING WRITTEN YET)
+
+**This step is a proposal, not configuration.** Nothing has been written to disk yet: `.claude/project.json` still reads `configured: false`, no new skills/hooks/MCPs are wired, and the `swarm-worker` agent file has not been re-rendered. The user is reading a *proposal* that takes effect only when they explicitly approve in this step.
 
 Show the user one review surface before writing anything:
 
@@ -77,13 +79,32 @@ Show the user one review surface before writing anything:
 3. **Recommender additions** (from JSON `additions`): MCP servers, skills, hooks, and any `swarm_worker_skills` to preload — name + reason for each.
 4. **Gaps flagged** (from JSON `gaps`): things the baseline doesn't cover but might warrant a future spec.
 
-Use `AskUserQuestion` to confirm: "Apply these changes?" Options: `apply`, `apply with edits`, `cancel`.
+After presenting the four blocks, **explicitly tell the user the project is NOT yet configured**. Print this exact block above the confirmation prompt:
+
+```
+⚠ The baseline is still in PROJECT-AGNOSTIC MODE.
 
-If `apply with edits`: take the user's adjustments inline, re-show the surface, ask again.
+None of the proposal above has been applied. `project.json → configured`
+is still `false`. test_runner / lint_runner are still in guide mode.
+Closing this session now leaves the project unconfigured.
+
+The next prompt is an action gate. You must explicitly approve to proceed
+to Step 6 (apply) — otherwise nothing changes.
+```
+
+Use `AskUserQuestion` to confirm. The question SHALL be a full sentence that names the un-configured state explicitly — not "Apply these changes?" alone, but: **"The project is NOT yet configured. Proceed to apply this proposal and finish setup?"** Options:
+
+- `Proceed and apply` — advances to Step 6.
+- `Edit before applying` — take the user's adjustments inline, re-show the surface, ask again.
+- `Cancel — leave project unconfigured` — exit without writing; `configured` stays `false`; surface that the project remains in project-agnostic mode and `/init-project` can be re-run later.
+
+If `Edit before applying`: take the user's adjustments inline, re-show the surface, **ask the same gate again**. Do not silently apply — the gate fires after every edit cycle until the user picks `Proceed and apply` or `Cancel`.
 
 ## Step 6 — Apply
 
-Write to disk now. Do each sub-step in order; if any fails, stop and surface the error before continuing:
+Write to disk now. **This is the first step in the protocol that mutates files in the user's project** — until this step runs, `.claude/project.json` still reads `configured: false` and the baseline stays in project-agnostic mode. Reaching this step means the user explicitly picked `Proceed and apply` at Step 5's gate.
+
+Do each sub-step in order; if any fails, stop and surface the error before continuing:
 
 1. **Pre-create lazy directories**:
    ```bash
@@ -186,6 +207,7 @@ Print a final summary:
 ## Constraints
 
 - **Steps 6 + 7 + 8 are atomic for the user.** If Step 8 fails, do not declare success at Step 9.
+- **Step 5 is review, not setup.** Until the user explicitly picks `Proceed and apply` at Step 5's gate, the project remains in project-agnostic mode. Surfacing recommendations is not configuration; the gate prompt SHALL name the un-configured state in a full sentence so a skimming reader cannot mistake the proposal for a completion notice.
 - **Never write `configured: true` before Step 8 passes.** A FAIL at Step 8 means the project is in a broken state; leaving `configured: true` would lie to `setup_guard` and the welcome hook in CLAUDE.md.
 - **No silent decisions.** Every project-specific change appears in seed.md §16 so the next reader can see what diverged from baseline.
 - **Idempotent.** Re-running on the same project produces the same §16 (modulo timestamp + run number) and passes `/audit-baseline` cleanly.

package/obj/template/.claude/hooks/consent_gate_grant.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+// Consent Gate Grant — UserPromptSubmit
+//
+// JS port of consent_gate_grant.sh, adding a fourth arm for /grant-push.
+//
+// When the user types one of /approve-spec, /approve-swarm, /grant-commit,
+// /grant-push, this hook fires BEFORE Claude is invoked. It writes a
+// short-lived consent marker at .claude/state/.<gate>_grant.
+//
+// The marker is what makes the corresponding approval-token write succeed:
+// the gate-specific PreToolUse guard (spec_approval_guard, swarm_approval_guard,
+// git_commit_guard) reads the marker and allows Claude's write only if a
+// fresh, slug-matched marker is on disk.
+//
+// Why the marker is unforgeable by Claude:
+//   - This hook runs on UserPromptSubmit, OUTSIDE Claude's tool boundary.
+//   - The PreToolUse guards block Claude from writing the marker file.
+//   - Markers expire after consent.gate_marker_ttl_seconds (default 120).
+//
+// Marker shapes:
+//   .spec_approval_grant   line 1: slug · line 2: epoch · line 3: abs spec path
+//   .swarm_approval_grant  line 1: slug · line 2: epoch
+//   .commit_consent_grant  line 1: epoch · line 2: optional note
+//   .push_consent_grant    line 1: epoch · line 2: optional note   (NEW)
+
+import { join } from 'node:path';
+import {
+  readPayload,
+  payloadGet,
+  canonicalSlug,
+  writeMarkerAtomic,
+  logLine,
+  CLAUDE_PROJECT_ROOT,
+  CONSENT_MARKER_SPEC,
+  CONSENT_MARKER_SWARM,
+  CONSENT_MARKER_COMMIT,
+  CONSENT_MARKER_PUSH,
+} from './lib/common.mjs';
+
+const HOOK = 'consent_gate_grant';
+
+async function main() {
+  // Fast-path: rule out 99% of prompts before any regex parsing.
+  const payload = await readPayload();
+  const prompt = payloadGet(payload, '.prompt');
+  if (typeof prompt !== 'string' || prompt.length === 0) return;
+  if (!/\/(approve-spec|approve-swarm|grant-commit|grant-push)/.test(prompt)) return;
+
+  const firstLine = prompt.split(/\r?\n/)[0].trim();
+  const now = Math.floor(Date.now() / 1000);
+
+  let m;
+
+  m = firstLine.match(/^\/approve-spec\s+(\S+)/);
+  if (m) {
+    const arg = m[1];
+    const slug = canonicalSlug(arg);
+    let absPath;
+    if (arg.startsWith('/')) absPath = arg;
+    else if (arg.includes('/')) absPath = join(CLAUDE_PROJECT_ROOT, arg);
+    else absPath = join(CLAUDE_PROJECT_ROOT, 'docs', 'specs', `${slug}.md`);
+    if (writeMarkerAtomic(CONSENT_MARKER_SPEC, slug, String(now), absPath)) {
+      logLine(HOOK, `wrote spec_approval_grant slug=${slug} path=${absPath}`);
+    } else {
+      logLine(HOOK, `FAILED write spec_approval_grant slug=${slug}`);
+    }
+    return;
+  }
+
+  m = firstLine.match(/^\/approve-swarm\s+(\S+)/);
+  if (m) {
+    const slug = canonicalSlug(m[1]);
+    if (writeMarkerAtomic(CONSENT_MARKER_SWARM, slug, String(now))) {
+      logLine(HOOK, `wrote swarm_approval_grant slug=${slug}`);
+    } else {
+      logLine(HOOK, `FAILED write swarm_approval_grant slug=${slug}`);
+    }
+    return;
+  }
+
+  m = firstLine.match(/^\/grant-commit(\s.*)?$/);
+  if (m) {
+    const note = (m[1] || '').trim();
+    if (writeMarkerAtomic(CONSENT_MARKER_COMMIT, String(now), note)) {
+      logLine(HOOK, `wrote commit_consent_grant note=${note}`);
+    } else {
+      logLine(HOOK, `FAILED write commit_consent_grant`);
+    }
+    return;
+  }
+
+  m = firstLine.match(/^\/grant-push(\s.*)?$/);
+  if (m) {
+    const note = (m[1] || '').trim();
+    if (writeMarkerAtomic(CONSENT_MARKER_PUSH, String(now), note)) {
+      logLine(HOOK, `wrote push_consent_grant note=${note}`);
+    } else {
+      logLine(HOOK, `FAILED write push_consent_grant`);
+    }
+    return;
+  }
+}
+
+main().catch(() => {
+  // UserPromptSubmit hook must never fail loudly — silent exit on any error.
+  process.exit(0);
+});