forgedock 1.0.22 → 1.1.2

package/bin/journey.mjs

@@ -0,0 +1,841 @@
+/**
+ * bin/journey.mjs — The five-act onboarding journey for ForgeDock.
+ *
+ * Acts (added across Tasks 4–8):
+ *   preflight() → forge() → read() → review() → celebrate()
+ *
+ * This file owns forge.yaml generation (single source of truth, driven from
+ * detection values) and orchestrates the existing modules:
+ *   init-detect.mjs, init-enrich-api.mjs, tui.annotatedReviewScreen, registry.mjs
+ */
+
+import { existsSync, readFileSync, writeFileSync, renameSync, unlinkSync } from "fs";
+import { join, basename } from "path";
+
+// ---------------------------------------------------------------------------
+// forge.yaml generation (Task 4)
+// ---------------------------------------------------------------------------
+
+const esc = (s) => String(s).replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\r/g, "\\r").replace(/\n/g, "\\n");
+
+/** Append the TODO flag for a low-confidence field. */
+function todo(key, low) {
+  return low.includes(key) ? `  # TODO(forgedock:${key}) — verify this value` : "";
+}
+
+/**
+ * Write forge.yaml from reviewed values.
+ * @param {{owner:string,repo:string,name:string,description:string,root:string,
+ *          worktreeBase:string,defaultBranch:string,stagingBranch:string}} v
+ *   Exactly the object annotatedReviewScreen resolves with.
+ * @param {string[]} lowConfidenceKeys - keys to flag with # TODO comments.
+ * @param {string} outputPath
+ * @returns {{ todoCount: number }}
+ */
+export function writeForgeYaml(v, lowConfidenceKeys, outputPath) {
+  const low = lowConfidenceKeys;
+  const content = `# forge.yaml — ForgeDock Configuration
+#
+# Auto-generated by: npx forgedock
+# Fields marked with TODO comments below were guessed — verify them.
+#
+# Required sections: project, paths, branches
+# Optional sections: repos, project_board, services, review, verification
+#
+# See docs/CONFIG.md for full reference.
+
+# =============================================================================
+# PROJECT (REQUIRED)
+# =============================================================================
+
+project:
+  name: "${esc(v.name)}"${todo("name", low)}
+  owner: "${esc(v.owner)}"${todo("owner", low)}
+  repo: "${esc(v.repo)}"${todo("repo", low)}
+  description: "${esc(v.description)}"${todo("description", low)}
+
+# =============================================================================
+# PATHS (REQUIRED)
+# =============================================================================
+
+paths:
+  root: "${esc(v.root)}"${todo("root", low)}
+  worktree_base: "${esc(v.worktreeBase)}"${todo("worktreeBase", low)}
+
+# =============================================================================
+# BRANCHES (REQUIRED)
+# =============================================================================
+
+branches:
+  default: "${esc(v.defaultBranch)}"${todo("defaultBranch", low)}
+  staging: "${esc(v.stagingBranch)}"${todo("stagingBranch", low)}
+  feature_pattern: "milestone/{slug}"
+
+# =============================================================================
+# REPOS (OPTIONAL) — multi-repo configuration. Remove the # to enable.
+# =============================================================================
+
+# repos:
+#   default:
+#     repo: "${esc(v.owner)}/${esc(v.repo)}"
+#     staging_branch: "${esc(v.stagingBranch)}"
+#   satellites:
+#     - prefix: "mcp"
+#       repo: "${esc(v.owner)}/your-satellite-repo"
+#       staging_branch: "main"
+
+# =============================================================================
+# PROJECT BOARD (OPTIONAL) — GitHub Projects v2 integration.
+# To find IDs: gh project list --owner ${esc(v.owner)}
+# =============================================================================
+
+# project_board:
+#   owner: "${esc(v.owner)}"
+#   project_number: 1
+#   project_id: "PVT_kwHOxxxxxxxxxxxxxxxx"
+#   field_ids:
+#     status: "PVTSSF_xxxxxxxxxxxxxxxxxxxxxxxx"
+
+# =============================================================================
+# REVIEW (OPTIONAL) — context injected into review agent prompts.
+# =============================================================================
+
+# review:
+#   tech_stack: "Node.js, TypeScript, PostgreSQL"
+#   context: |
+#     Describe your repo structure and any unusual conventions here.
+
+# =============================================================================
+# VERIFICATION (OPTIONAL) — health checks for quality gate / validate.
+# =============================================================================
+
+# verification:
+#   health_endpoint: "https://api.example.com/health"
+#   health_patterns:
+#     - '"status": "ok"'
+`;
+  // Atomic write: write to a temp file first, then rename into place.
+  // If the write fails (e.g. ENOSPC), the original file is untouched and
+  // any partial .tmp is cleaned up — no corrupt or missing forge.yaml.
+  const tmpPath = outputPath + ".tmp";
+  try {
+    writeFileSync(tmpPath, content, "utf-8");
+    renameSync(tmpPath, outputPath);
+  } catch (err) {
+    try { unlinkSync(tmpPath); } catch { /* best-effort cleanup */ }
+    throw err;
+  }
+  const todoCount = (content.match(/# TODO\(forgedock:/g) || []).length;
+  return { todoCount };
+}
+
+/** Maps manual-flow value keys to their location in a ConfigDraft. */
+const DRAFT_KEY_PATHS = {
+  owner: ["project", "owner"],
+  repo: ["project", "repo"],
+  name: ["project", "name"],
+  root: ["paths", "root"],
+  worktreeBase: ["paths", "worktreeBase"],
+  defaultBranch: ["branches", "default"],
+  stagingBranch: ["branches", "staging"],
+};
+
+/**
+ * Compute which fields accepted in the `--manual` init flow should be flagged
+ * low-confidence (and so get a `# TODO(forgedock:<field>)` comment).
+ *
+ * A field counts as low-confidence when detection scored it "low" AND the
+ * user accepted the detected value unchanged (didn't type over the default).
+ * `description` is special-cased: it has no draft entry, so it counts as low
+ * when detection found nothing (empty) and the user also left it empty.
+ *
+ * Pure — no I/O, safe to unit test directly.
+ *
+ * @param {import('./init-detect.mjs').ConfigDraft} draft
+ * @param {{ value: string, source: string }} description
+ * @param {{owner:string,repo:string,name:string,description:string,root:string,
+ *          worktreeBase:string,defaultBranch:string,stagingBranch:string}} values
+ *   The values accepted from the manual prompts.
+ * @returns {string[]}
+ */
+export function manualLowConfidenceKeys(draft, description, values) {
+  const keys = [];
+  for (const [key, path] of Object.entries(DRAFT_KEY_PATHS)) {
+    const field = path.reduce(
+      (node, k) => (node && typeof node === "object" ? node[k] : undefined),
+      draft,
+    );
+    if (field && field.confidence === "low" && values[key] === field.value) {
+      keys.push(key);
+    }
+  }
+  if (!description.value && !values.description) {
+    keys.push("description");
+  }
+  return keys;
+}
+
+/**
+ * Back up an existing file to <name>.bak (timestamped if .bak exists).
+ * @returns {{ backupName: string } | null} null when the file didn't exist.
+ */
+export function backupExisting(outputPath) {
+  if (!existsSync(outputPath)) return null;
+  const baseBak = outputPath + ".bak";
+  const backupPath = existsSync(baseBak)
+    ? `${baseBak}.${new Date().toISOString().replace(/[:.]/g, "-")}`
+    : baseBak;
+  renameSync(outputPath, backupPath);
+  return { backupName: basename(backupPath) };
+}
+
+// ---------------------------------------------------------------------------
+// Description detection (moved from forgedock.mjs init(), Task 4)
+// ---------------------------------------------------------------------------
+
+function firstParagraph(content) {
+  const lines = content.split("\n");
+  let started = false;
+  const out = [];
+  for (const line of lines) {
+    if (!started && line.match(/^#/)) continue;
+    if (!started && line.trim() === "") continue;
+    if (!started && line.match(/^[!<\[`|]/)) continue;
+    if (!started && line.match(/^---/)) continue;
+    if (!started) started = true;
+    if (line.trim() === "") break;
+    out.push(line.trim());
+  }
+  if (out.length === 0) return "";
+  return out
+    .join(" ")
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
+    .replace(/\*\*([^*]+)\*\*/g, "$1")
+    .replace(/`([^`]+)`/g, "$1")
+    .slice(0, 200)
+    .trim();
+}
+
+/**
+ * Detect a project description from README.md, falling back to CLAUDE.md.
+ * @returns {{ value: string, source: 'README.md'|'CLAUDE.md'|'' }}
+ */
+export function detectDescription(cwd) {
+  for (const file of ["README.md", "CLAUDE.md"]) {
+    try {
+      const p = join(cwd, file);
+      if (!existsSync(p)) continue;
+      const value = firstParagraph(readFileSync(p, "utf-8").slice(0, 2048));
+      if (value) return { value, source: file };
+    } catch {
+      // best-effort only
+    }
+  }
+  return { value: "", source: "" };
+}
+
+// ---------------------------------------------------------------------------
+// Journey context (Task 5)
+// ---------------------------------------------------------------------------
+
+import { execFileSync } from "child_process";
+import os from "os";
+import {
+  renderMark, ember, shimmer, revealRows, moltenBar, fixCard,
+  colorMode, motionEnabled, CHROME_STOPS, HERO_MARK, COMPACT_MARK, sleep,
+} from "./cinema.mjs";
+
+/**
+ * Build the shared journey context. Every act takes this as its first arg.
+ * All process-touching values are injectable for tests.
+ */
+export function makeCtx(overrides = {}) {
+  const env = overrides.env ?? process.env;
+  const stdout = overrides.stdout ?? process.stdout;
+  const argv = overrides.argv ?? process.argv.slice(2);
+  const nodeVersion = overrides.nodeVersion ?? process.versions.node;
+  const enrichFn = overrides.enrichFn ?? enrich;
+  return {
+    cwd: process.cwd(),
+    home: env.HOME || env.USERPROFILE || os.homedir(),
+    forgeHome: "",
+    argv,
+    env,
+    stdout,
+    mode: colorMode(env, stdout),
+    motion: motionEnabled(argv, env, stdout),
+    nodeVersion,
+    linkStrategy: "symlink",
+    enrichFn,
+    exec: (cmd, args) =>
+      execFileSync(cmd, args, {
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+        timeout: 10000,
+      }).trim(),
+    startedAt: Date.now(),
+    ...overrides,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Act I — Ignition: hero mark + preflight checks (Task 5)
+// ---------------------------------------------------------------------------
+
+const dimLine = (ctx, s) => (ctx.mode === "none" ? s : `\x1b[2m${s}\x1b[22m`);
+
+/**
+ * Render the hero banner and run preflight checks. Failures render fix cards
+ * and the journey continues — advisory, never fatal.
+ * @returns {Promise<{ checks: Array<{name, ok, detail, fix?}>, ghReady: boolean }>}
+ */
+export async function preflight(ctx) {
+  const { stdout: w } = ctx;
+  w.write("\n");
+  await shimmer(HERO_MARK, CHROME_STOPS, { mode: ctx.mode, motion: ctx.motion, writer: w });
+  w.write("\n  " + ember("F O R G E D O C K", ctx.mode) + "\n");
+  w.write("  " + dimLine(ctx, "──── lighting the forge ────────────────────") + "\n\n");
+
+  const rows = [
+    {
+      label: "Node",
+      run: async () => {
+        const major = Number(ctx.nodeVersion.split(".")[0]);
+        return major >= 18
+          ? { ok: true, detail: `v${ctx.nodeVersion}` }
+          : { ok: false, detail: `v${ctx.nodeVersion} — need ≥18`, fix: ["Upgrade Node: https://nodejs.org/"] };
+      },
+    },
+    {
+      label: "git",
+      run: async () => {
+        try {
+          const v = ctx.exec("git", ["--version"]);
+          return { ok: true, detail: v.replace(/^git version\s*/, "") };
+        } catch {
+          return { ok: false, detail: "not found", fix: ["Install git: https://git-scm.com/downloads"] };
+        }
+      },
+    },
+    {
+      label: "Claude Code",
+      run: async () => {
+        const claudeDir = join(ctx.home, ".claude");
+        return existsSync(claudeDir)
+          ? { ok: true, detail: "~/.claude found" }
+          : { ok: false, detail: "~/.claude not found", fix: ["Install Claude Code: https://claude.com/claude-code"] };
+      },
+    },
+    {
+      label: "GitHub CLI",
+      run: async () => {
+        try {
+          ctx.exec("gh", ["--version"]);
+        } catch {
+          return {
+            ok: false,
+            detail: "not found",
+            fix: ["Install gh: https://cli.github.com/", "Windows: winget install GitHub.cli"],
+          };
+        }
+        try {
+          ctx.exec("gh", ["auth", "status"]);
+          return { ok: true, detail: "authenticated" };
+        } catch {
+          return { ok: false, detail: "not authenticated", fix: ["Run: gh auth login"] };
+        }
+      },
+    },
+  ];
+
+  const results = await revealRows(rows, { mode: ctx.mode, motion: ctx.motion, writer: w });
+  const named = rows.map((r, i) => ({ name: r.label, ...results[i] }));
+  return { checks: named, ghReady: named[3].ok };
+}
+
+// ---------------------------------------------------------------------------
+// Act II — Forging: command symlinks + SessionStart hook (Task 6)
+// ---------------------------------------------------------------------------
+
+import { mkdir, symlink, readlink, lstat, readdir, rename, copyFile, readFile, writeFile, unlink } from "fs/promises";
+import { relative, dirname as pathDirname } from "path";
+import {
+  installSessionStartHook,
+  installSubagentStopHook,
+  installPreToolUseHook,
+  removeSubagentStopEnforceHook,
+} from "./settings-hook.mjs";
+
+/**
+ * Parse the `install:` tier from a command spec's YAML frontmatter block.
+ *
+ * Reads the first 512 bytes of the file synchronously (large enough to reach
+ * any realistic frontmatter block without loading the full spec into memory).
+ * Strips a leading UTF-8 BOM if present — BOM-prefixed files would cause the
+ * frontmatter regex to miss the leading `---` delimiter.
+ *
+ * Tier values:
+ *   'core'     — install for all users (default when key is absent or on any error)
+ *   'extras'   — opt-in, not installed by default; use `npx forgedock install --extras` (#1257)
+ *   'internal' — ForgeDock development only; never installed to user machines
+ *
+ * Fail-open: any read error, malformed frontmatter, or unrecognised value falls
+ * back to `'core'` so the command is installed rather than silently excluded.
+ *
+ * @param {string} filePath - Absolute path to the .md command spec.
+ * @returns {'core' | 'extras' | 'internal'}
+ */
+export function parseInstallTier(filePath) {
+  try {
+    // Read the file as UTF-8. readFileSync is already imported from "fs" at the
+    // top of this module — no require() needed in this ESM file. For large specs
+    // only the first 512 bytes are relevant (frontmatter fits comfortably within
+    // that budget), but readFileSync is simpler and safe for the file sizes here.
+    let content = readFileSync(filePath, "utf-8");
+    // Strip BOM — a BOM-prefixed file would shift the leading `---` off the
+    // start of the string and cause the frontmatter regex to miss it entirely.
+    // (Ref: review-finding #657 — parseFrontmatter silently falls back on BOM files)
+    content = content.replace(/^\uFEFF/, "");
+
+    // Match YAML frontmatter block: must start at position 0.
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!match) return "core";
+
+    const raw = match[1];
+    for (const line of raw.split(/\r?\n/)) {
+      const colonIdx = line.indexOf(":");
+      if (colonIdx === -1) continue;
+      const key = line.slice(0, colonIdx).trim();
+      if (key !== "install") continue;
+      const val = line.slice(colonIdx + 1).trim().replace(/^["']|["']$/g, "");
+      if (val === "internal" || val === "extras" || val === "core") return val;
+      return "core"; // unrecognised value → default
+    }
+    return "core"; // key absent
+  } catch {
+    return "core"; // any read/parse error → fail-open
+  }
+}
+
+/** Recursively find installable .md files, sorted (moved from forgedock.mjs).
+ *
+ * Files with `install: internal` in their YAML frontmatter are excluded — they
+ * are ForgeDock-development-only specs that must never reach user machines.
+ * Files with `install: core` (or no `install:` key) are included. Files with
+ * `install: extras` are excluded from the default install surface; they are
+ * available via `npx forgedock install --extras` (implemented in #1257).
+ *
+ * @param {string} dir - Directory to search recursively.
+ * @param {{ includeExtras?: boolean }} [opts] - Options.
+ *   includeExtras: when true, also include `install: extras` specs (opt-in tier).
+ */
+export async function findMarkdownFiles(dir, opts = {}) {
+  const { includeExtras = false } = opts;
+  const results = [];
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...(await findMarkdownFiles(full, opts)));
+    } else if (entry.name.endsWith(".md")) {
+      const tier = parseInstallTier(full);
+      if (tier === "core" || (includeExtras && tier === "extras")) {
+        results.push(full);
+      }
+      // 'internal' is always excluded from the install surface
+    }
+  }
+  return results.sort();
+}
+
+/** Load the copied-commands ownership manifest (missing/corrupt → empty). */
+async function loadCopiedManifest(manifestPath) {
+  try {
+    const parsed = JSON.parse(await readFile(manifestPath, "utf-8"));
+    if (parsed && typeof parsed === "object" && parsed.files && typeof parsed.files === "object") {
+      return { version: 1, files: parsed.files };
+    }
+  } catch {
+    // missing or corrupt → start fresh
+  }
+  return { version: 1, files: {} };
+}
+
+/** Save the manifest atomically (mkdir recursive + .tmp+rename). */
+async function saveCopiedManifest(manifestPath, manifest) {
+  await mkdir(pathDirname(manifestPath), { recursive: true });
+  await writeFile(manifestPath + ".tmp", JSON.stringify(manifest, null, 2) + "\n", "utf-8");
+  await rename(manifestPath + ".tmp", manifestPath);
+}
+
+const isLinkPermissionError = (err) => err.code === "EPERM" || err.code === "EACCES";
+
+/**
+ * Act II: link commands into ~/.claude/commands with a molten progress line,
+ * then register the SessionStart hook.
+ * Symlink semantics preserved verbatim from the original install():
+ * regular files are skipped with a warning; changed links updated atomically.
+ * On Windows without Developer Mode (symlink → EPERM/EACCES) each command is
+ * copied instead, and recorded in a manifest so re-runs can tell ForgeDock's
+ * own copies apart from user-owned files. ctx.linkStrategy ("symlink" default)
+ * can be set to "copy" to skip all symlink attempts (deterministic tests).
+ */
+export async function forge(ctx) {
+  const { stdout: w } = ctx;
+  const commandsDir = join(ctx.forgeHome, "commands");
+  const targetDir = join(ctx.home, ".claude", "commands");
+  const manifestPath = join(ctx.home, ".claude", "forgedock", "copied-commands.json");
+  const wantSymlink = ctx.linkStrategy !== "copy";
+
+  w.write("\n  " + ember("Forging commands", ctx.mode) + " " + dimLine(ctx, `into ${targetDir}`) + "\n\n");
+  await mkdir(targetDir, { recursive: true });
+
+  const manifest = await loadCopiedManifest(manifestPath);
+  let manifestChanged = false;
+
+  const files = await findMarkdownFiles(commandsDir, { includeExtras: !!ctx.includeExtras });
+  let installed = 0, updated = 0, skipped = 0, copied = 0;
+  const barWidth = 24;
+  let barShown = false;
+
+  const recordCopy = (rel) => {
+    if (!manifest.files[rel]) {
+      manifest.files[rel] = true;
+      manifestChanged = true;
+    }
+  };
+
+  for (let i = 0; i < files.length; i++) {
+    const file = files[i];
+    const rel = relative(commandsDir, file);
+    const target = join(targetDir, rel);
+    await mkdir(pathDirname(target), { recursive: true });
+
+    try {
+      const stats = await lstat(target);
+      if (stats.isSymbolicLink()) {
+        const current = await readlink(target);
+        if (current === file) {
+          skipped++;
+        } else {
+          let relinked = false;
+          if (wantSymlink) {
+            try {
+              await symlink(file, target + ".tmp");
+              try {
+                await rename(target + ".tmp", target);
+              } catch (renameErr) {
+                await unlink(target + ".tmp").catch(() => {});
+                throw renameErr;
+              }
+              updated++;
+              relinked = true;
+            } catch (linkErr) {
+              if (!isLinkPermissionError(linkErr)) throw linkErr;
+            }
+          }
+          if (!relinked) {
+            // Can't (or shouldn't) re-link — replace the managed link with a copy.
+            // unlink first: copyFile onto a symlink writes THROUGH the link.
+            await unlink(target);
+            await copyFile(file, target);
+            updated++; // replaces an existing managed entry
+            recordCopy(rel);
+          }
+        }
+      } else if (manifest.files[rel]) {
+        // A regular file we copied on a previous run — ours to manage.
+        // First try upgrading it to a symlink (Developer Mode enabled since).
+        let upgraded = false;
+        if (wantSymlink) {
+          try {
+            await symlink(file, target + ".tmp");
+            try {
+              await rename(target + ".tmp", target); // rename replaces existing files on Windows
+            } catch (renameErr) {
+              await unlink(target + ".tmp").catch(() => {});
+              throw renameErr;
+            }
+            updated++;
+            delete manifest.files[rel];
+            manifestChanged = true;
+            upgraded = true;
+          } catch (linkErr) {
+            if (!isLinkPermissionError(linkErr)) throw linkErr;
+          }
+        }
+        if (!upgraded) {
+          const [src, dst] = await Promise.all([readFile(file), readFile(target)]);
+          if (src.equals(dst)) {
+            skipped++;
+          } else {
+            await copyFile(file, target);
+            updated++;
+          }
+        }
+      } else {
+        if (barShown) { w.write("\x1b[1A\x1b[2K"); barShown = false; }
+        w.write(`  WARNING: ${rel} is a regular file — skipping (remove it manually to let ForgeDock manage it)\n`);
+        skipped++;
+      }
+    } catch (err) {
+      if (err.code !== "ENOENT") throw err;
+      let linked = false;
+      if (wantSymlink) {
+        try {
+          await symlink(file, target);
+          installed++;
+          linked = true;
+          if (manifest.files[rel]) {
+            // Symlinks work now and the old copy is gone — drop the stale record.
+            delete manifest.files[rel];
+            manifestChanged = true;
+          }
+        } catch (linkErr) {
+          if (!isLinkPermissionError(linkErr)) throw linkErr;
+        }
+      }
+      if (!linked) {
+        // Windows without Developer Mode/admin — fall back to a copy.
+        await copyFile(file, target);
+        copied++;
+        recordCopy(rel);
+      }
+    }
+
+    if (ctx.motion) {
+      if (barShown) w.write("\x1b[1A\x1b[2K");
+      w.write(`  ${moltenBar(i + 1, files.length, { width: barWidth, mode: ctx.mode })}  ${i + 1}/${files.length}  ${dimLine(ctx, "/" + rel.replace(/\.md$/, ""))}\n`);
+      barShown = true;
+    }
+  }
+  if (barShown) w.write("\x1b[1A\x1b[2K");
+
+  const hookScript = join(ctx.forgeHome, "bin", "hooks", "session-start.mjs");
+  const settingsPath = join(ctx.home, ".claude", "settings.json");
+  const { status: hookStatus } = installSessionStartHook(settingsPath, hookScript);
+
+  // Install enforcement hooks (#1250): PreToolUse (branch/label validation)
+  // and SubagentStop interactive engine adapter. Both are idempotent and
+  // always installed (fail-open if settings.json is malformed, same
+  // contract as SessionStart hook).
+  const preToolUseScript = join(ctx.forgeHome, "bin", "hooks", "pre-tool-use.mjs");
+  const subagentStopScript = join(ctx.forgeHome, "bin", "hooks", "interactive-engine.mjs");
+  const { status: preToolUseStatus } = installPreToolUseHook(settingsPath, preToolUseScript);
+  installSubagentStopHook(settingsPath, subagentStopScript);
+
+  // SubagentStop annotation-verifier hook (#1250) is NOT installed: its
+  // trigger condition (a `FORGE:PHASE_START` marker in the transcript) is
+  // never emitted anywhere in the pipeline, so it always exits 0 with zero
+  // enforcement effect while still spawning a process + reading the
+  // transcript on every SubagentStop (forge#1527). Actively clean up any
+  // prior installation instead of installing it.
+  const { status: subagentStopEnforceStatus } = removeSubagentStopEnforceHook(settingsPath);
+
+  // Housekeeping — must never abort the receipt or the hook.
+  let manifestSaveFailed = false;
+  if (manifestChanged) {
+    try {
+      await saveCopiedManifest(manifestPath, manifest);
+    } catch {
+      manifestSaveFailed = true;
+    }
+  }
+
+  const glyph = (ok) => (ctx.mode === "none" ? (ok ? "✔" : "!") : `\x1b[38;2;255;179;71m${ok ? "✔" : "!"}\x1b[0m`);
+  const headlineVerb = copied > 0 ? "installed" : "linked";
+  const headlineDetail = copied > 0
+    ? `(new ${installed}, copied ${copied}, updated ${updated}, unchanged ${skipped})`
+    : `(new ${installed}, updated ${updated}, unchanged ${skipped})`;
+  w.write(`  ${glyph(true)} ${files.length} slash commands ${headlineVerb} ${dimLine(ctx, headlineDetail)}\n`);
+  if (copied > 0) {
+    w.write(`  ${glyph(false)} ${copied} copied (not linked) ${dimLine(ctx, "— enable Windows Developer Mode for live-updating links")}\n`);
+  }
+  if (manifestSaveFailed) {
+    w.write("  " + dimLine(ctx, "manifest not saved — re-runs may warn about copied files") + "\n");
+  }
+  if (hookStatus === "skipped-malformed") {
+    w.write(`  ${glyph(false)} SessionStart hook NOT registered — ${settingsPath} is not valid JSON\n`);
+    w.write(fixCard([`Fix the JSON in ${settingsPath}, then re-run: npx forgedock install`], ctx.mode) + "\n");
+  } else {
+    w.write(`  ${glyph(true)} SessionStart hook ${hookStatus === "already" ? "active" : "registered"} ${dimLine(ctx, settingsPath)}\n`);
+  }
+
+  // Report enforcement hook status.
+  if (preToolUseStatus !== null) {
+    w.write(`  ${glyph(true)} PreToolUse enforcement hook ${preToolUseStatus === "already" ? "active" : "registered"} ${dimLine(ctx, "(branch/label enforcement)")}\n`);
+  } else {
+    w.write("  " + dimLine(ctx, "PreToolUse hook skipped — requires Claude Code v2.1.163+") + "\n");
+  }
+  // "skipped-malformed" and "absent" are intentionally silent here:
+  // - skipped-malformed: installSessionStartHook() above reads the same
+  //   settingsPath and already prints the malformed-JSON fix-card, so a
+  //   second message would just repeat the same signal.
+  // - absent: the expected steady state (nothing to remove) — this
+  //   function only reports state *changes*, not no-ops.
+  if (subagentStopEnforceStatus === "removed") {
+    w.write(`  ${glyph(true)} SubagentStop enforcement hook removed ${dimLine(ctx, "(non-functional — see forge#1527)")}\n`);
+  }
+
+  return { installed, updated, skipped, copied, total: files.length, hookStatus, preToolUseStatus, subagentStopEnforceStatus };
+}
+
+// ---------------------------------------------------------------------------
+// Act III — Reading your repository (Task 8)
+// ---------------------------------------------------------------------------
+
+import { detectConfig } from "./init-detect.mjs";
+import { enrich } from "./init-enrich-api.mjs";
+import { annotatedReviewScreen, box } from "./tui.mjs";
+
+const badgeOf = (field) => field.confidence;
+
+/**
+ * Act III: detect the repo, show each field as a reveal row with its
+ * confidence badge, optionally AI-enrich. Detection runs first (it is fast);
+ * rows are display pacing, not fake latency.
+ */
+export async function read(ctx) {
+  const { stdout: w } = ctx;
+  w.write("\n  " + ember("Reading your repository", ctx.mode) + "\n\n");
+
+  let draft = await detectConfig(ctx.cwd);
+  const description = detectDescription(ctx.cwd);
+
+  const rows = [
+    { label: "owner/repo", run: async () => ({ ok: true, detail: `${draft.project.owner.value}/${draft.project.repo.value}`, badge: badgeOf(draft.project.owner) }) },
+    { label: "default branch", run: async () => ({ ok: true, detail: draft.branches.default.value, badge: badgeOf(draft.branches.default) }) },
+    { label: "staging branch", run: async () => ({ ok: true, detail: draft.branches.staging.value, badge: badgeOf(draft.branches.staging) }) },
+    { label: "project name", run: async () => ({ ok: true, detail: draft.project.name.value, badge: badgeOf(draft.project.name) }) },
+    {
+      label: "description",
+      run: async () => description.value
+        ? { ok: true, detail: `"${description.value.slice(0, 40)}${description.value.length > 40 ? "…" : ""}"`, badge: "medium" }
+        : { ok: true, detail: "none found", badge: "low" },
+    },
+  ];
+  await revealRows(rows, { mode: ctx.mode, motion: ctx.motion, writer: w });
+
+  if (ctx.env.ANTHROPIC_API_KEY) {
+    try {
+      w.write("  " + dimLine(ctx, "✦ enriching with AI…") + "\n");
+      const enriched = await ctx.enrichFn(draft);
+      if (enriched && typeof enriched === "object") draft = enriched;
+    } catch {
+      w.write("  " + dimLine(ctx, "✦ AI enrichment unavailable — continuing with detection only") + "\n");
+    }
+  } else {
+    w.write("  " + dimLine(ctx, "✦ no ANTHROPIC_API_KEY — skipping AI enrichment") + "\n");
+  }
+
+  return { draft, description };
+}
+
+// ---------------------------------------------------------------------------
+// Act IV — The Review (Task 8)
+// ---------------------------------------------------------------------------
+
+/**
+ * Act IV: the single interaction. Non-TTY + existing config aborts to protect
+ * the file; non-TTY + fresh config writes detection values with TODO flags
+ * (annotatedReviewScreen's non-TTY path returns them directly).
+ */
+export async function review(ctx, draft, description) {
+  const { stdout: w } = ctx;
+  const outputPath = join(ctx.cwd, "forge.yaml");
+  const hasExisting = existsSync(outputPath);
+
+  if (hasExisting && process.stdin.isTTY !== true) {
+    w.write("\n  forge.yaml already exists — non-interactive run, aborting to protect it.\n");
+    w.write("  " + dimLine(ctx, "Run interactively (or delete forge.yaml) to regenerate.") + "\n");
+    return { written: false, todoCount: 0, backupName: null, aborted: true };
+  }
+
+  const extraFields = description.value
+    ? { description: { value: description.value, confidence: "medium", source: description.source, why: `First paragraph of ${description.source}` } }
+    : {};
+
+  const accepted = await annotatedReviewScreen(draft, {
+    hasExistingConfig: hasExisting,
+    showSources: ctx.argv.includes("--verbose"),
+    extraFields,
+  });
+
+  const backup = backupExisting(outputPath);
+  if (backup) w.write(`  Backed up: forge.yaml → ${backup.backupName}\n`);
+
+  const { todoCount } = writeForgeYaml(accepted, accepted.lowConfidenceKeys, outputPath);
+  return { written: true, todoCount, backupName: backup ? backup.backupName : null, aborted: false };
+}
+
+// ---------------------------------------------------------------------------
+// Act V — Forged (Task 8)
+// ---------------------------------------------------------------------------
+
+/**
+ * Act V: quench flash on the compact mark, receipt with real elapsed time,
+ * next-steps box.
+ */
+export function celebrate(ctx, summary) {
+  const { stdout: w } = ctx;
+  const elapsed = Math.round((Date.now() - ctx.startedAt) / 1000);
+  const mark = renderMark("compact", ctx.mode);
+
+  w.write("\n");
+  w.write(mark[0] + "\n");
+  w.write(mark[1] + "   " + ember("Forged.", ctx.mode) + " " + dimLine(ctx, `install → config in ${elapsed}s`) + "\n");
+  w.write(mark[2] + "\n");
+  w.write(mark[3] + "\n\n");
+
+  const glyph = ctx.mode === "none" ? "✔" : "\x1b[38;2;255;179;71m✔\x1b[0m";
+  if (summary.written) {
+    const todoNote = summary.todoCount > 0 ? `${summary.todoCount} field${summary.todoCount === 1 ? "" : "s"} flagged # TODO` : "all fields detected";
+    w.write(`  ${glyph} forge.yaml written          ${dimLine(ctx, todoNote)}\n`);
+  }
+  if (summary.total !== undefined) {
+    const hookNote = summary.hookStatus === "skipped-malformed" ? "hook NOT active — see fix above" : "Claude Code knows this repo";
+    w.write(`  ${glyph} ${summary.total} commands · hook ${summary.hookStatus === "skipped-malformed" ? "skipped" : "active"}   ${dimLine(ctx, hookNote)}\n`);
+  }
+  w.write("\n");
+  if (summary.isMinimal) {
+    w.write("  " + dimLine(ctx, "see docs/CONFIG.md for optional sections") + "\n");
+  }
+  w.write(
+    box(
+      [
+        `  1. run npx forgedock labels setup — bootstrap GitHub labels`,
+        `  2. run npx forgedock doctor     — verify the install is green`,
+        `  3. open claude in this repo`,
+        `  4. run /issue <title> then /work-on <number>`,
+      ],
+      { title: "what's next" },
+    ),
+  );
+  w.write("  " + dimLine(ctx, "docs: github.com/RapierCraftStudios/ForgeDock · ⭐ a star is the whole marketing budget") + "\n\n");
+}
+
+// ---------------------------------------------------------------------------
+// The full journey (Task 8)
+// ---------------------------------------------------------------------------
+
+/**
+ * Acts I→V. Returns the process exit code.
+ * SIGINT: restore cursor, summarize partial state, exit 130.
+ */
+export async function runJourney(ctx) {
+  const onSigint = () => {
+    ctx.stdout.write("\x1b[0m\x1b[?25h\n  Interrupted. Partial state: commands may be installed; config not written.\n  Finish anytime with: npx forgedock init\n");
+    process.exit(130);
+  };
+  process.on("SIGINT", onSigint);
+  try {
+    await preflight(ctx);
+    const forged = await forge(ctx);
+    const { draft, description } = await read(ctx);
+    const reviewed = await review(ctx, draft, description);
+    celebrate(ctx, { ...reviewed, total: forged.total, hookStatus: forged.hookStatus });
+    return reviewed.aborted ? 1 : 0;
+  } finally {
+    process.removeListener("SIGINT", onSigint);
+  }
+}