npm - @entelligentsia/forgecli - Versions diffs - 0.15.0 → 0.20.0 - Mend

@entelligentsia/forgecli 0.15.0 → 0.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1202) hide show

package/dist/extensions/forgecli/forge-init.js CHANGED Viewed

@@ -8,6 +8,19 @@
 //
 // Per INIT_PARITY_SPEC.md and PLAN.md (rev 2) phases A–G.
 //
+// ── Descriptor model (FORGE-S25-T24, B-5) ────────────────────────────────
+//
+// Phases 1–3 are driven by LlmPhaseDescriptor records (forge-init/phase-descriptors.ts).
+// The generic runLlmPhase() runner executes the shared skeleton:
+//   banner → [LLM dispatch + waitForIdle (Phases 1–2)] | [tool calls (Phase 3)]
+//         → verify → [retry steer (Phases 1–2)] → [user confirm] → postVerify → progress
+//
+// Phase 4 (11 deterministic steps) is too heterogeneous for the generic runner and is
+// extracted into forge-init/phase4-register.ts → runPhase4().
+//
+// This file is the orchestrator: flag parsing, resume detection, configCache population
+// (between Phase 1 and Phase 2), phase loop, post-init report.
+//
 // Iron Laws:
 //   - Iron Law 1: no edits to forge/ or pi-mono/
 //   - Iron Law 6: execFile with argv arrays — no shell-string interpolation
@@ -19,17 +32,44 @@
 //   #4: /forge:enhance — sentinel + advisory only; no sendUserMessage dispatch
 //   #5: Tomoshibi — runRefreshKbLinks() native TS port; no shell-out
 //   #9: Health check — runHealthCheck() direct call; NOT via sendUserMessage
-import { execFile } from "node:child_process";
+//
+// ── Async/sync contract (N-B-C) ─────────────────────────────────────────────
+//
+// `sendToAgent(text)` is SYNCHRONOUS — it wraps `pi.sendUserMessage(text, { deliverAs: "steer" })`
+// which enqueues the steer message and returns immediately. The agent does NOT start running
+// until the current handler yields (awaits).
+//
+// `await ctx.waitForIdle()` is the SOLE synchronisation primitive. It suspends the handler
+// until the agent has finished processing all pending steer messages and has reached an
+// idle state. All reads of phase deliverables (e.g. `.forge/config.json` for Phase 1,
+// KB docs for Phase 2, `.forge/workflows/` for Phase 3) MUST occur AFTER a `waitForIdle`.
+//
+// Pattern for every phase:
+//   sendToAgent(promptText);       // enqueue — synchronous
+//   await ctx.waitForIdle();       // suspend until agent completes — asynchronous
+//   const result = verifyPhaseN(); // read deliverable — synchronous
+//
+// ── Config cache boundary (B-4, N-B-A) ──────────────────────────────────────
+//
+// `.forge/config.json` is WRITTEN by the Phase-1 agent. Any read before Phase 1's
+// `waitForIdle` returns stale or absent data. `configCache` is populated once,
+// immediately after Phase 1 completes, and reused throughout Phase 2, Phase 4,
+// the post-init hook, and the report section — reducing 8 fs.readFileSync calls to 1.
+//
+// `verifyPhase1` inside `forge-init/verifiers.ts` intentionally reads config.json
+// directly rather than using `configCache` — it validates the Phase-1 deliverable
+// and must see the freshly written file.
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
-import { promisify } from "node:util";
+import { PHASE_1, PHASE_2, PHASE_3, runLlmPhase } from "./forge-init/phase-descriptors.js";
+import { runPhase4 } from "./forge-init/phase4-register.js";
+import { verifyPhase1, verifyPhase3 } from "./forge-init/verifiers.js";
 import { runHealthCheck } from "./health-check.js";
-import { buildProjectContext, computeCalibrationBaseline, discoverProjectName, validateProjectContext, writeProjectContext, } from "./init-context.js";
-import { deleteInitProgress, readInitProgress, writeInitProgress } from "./init-progress.js";
-import { getRefreshKbLinksHandler } from "./refresh-kb-links.js";
 import { emitSyntheticEvent } from "./hook-dispatcher.js";
-const execFileAsync = promisify(execFile);
+import { discoverProjectName } from "./init-context.js";
+import { deleteInitProgress, readInitProgress } from "./init-progress.js";
+import { execFileAsync } from "./lib/exec-helpers.js";
 // ── Bundle path resolution ─────────────────────────────────────────────────
 const _EXTENSION_DIR = path.dirname(fileURLToPath(import.meta.url));
 // dist/extensions/forgecli/ → dist/ → <pkg-root>/
@@ -134,260 +174,6 @@ function parseInitFlags(args) {
         invalidPhase,
     };
 }
-// ── Tool invocation helpers ────────────────────────────────────────────────
-async function runTool(toolPath, argv, cwd, timeout = 30000) {
-    try {
-        await execFileAsync("node", [toolPath, ...argv], {
-            cwd,
-            timeout,
-            encoding: "utf8",
-        });
-    }
-    catch (err) {
-        const e = err;
-        throw new Error(`Tool ${path.basename(toolPath)} failed: ${e.stderr?.trim() || e.message || "unknown error"}`);
-    }
-}
-async function runToolAdvisory(toolPath, argv, cwd, ctx, label, timeout = 30000) {
-    try {
-        await runTool(toolPath, argv, cwd, timeout);
-        return true;
-    }
-    catch (err) {
-        const e = err;
-        ctx.ui.notify(`△ ${label}: ${e.message ?? "failed"} — proceeding.`, "warning");
-        return false;
-    }
-}
-function verifyPhase1(cwd) {
-    const configPath = path.join(cwd, ".forge", "config.json");
-    if (!fs.existsSync(configPath)) {
-        return { ok: false, missing: [".forge/config.json"], reason: "config file not written" };
-    }
-    let cfg;
-    try {
-        cfg = JSON.parse(fs.readFileSync(configPath, "utf8"));
-    }
-    catch (err) {
-        const e = err;
-        return { ok: false, missing: [".forge/config.json"], reason: `JSON parse failed: ${e.message ?? "?"}` };
-    }
-    const missing = [];
-    if (!cfg.version)
-        missing.push("version");
-    const proj = cfg.project;
-    if (!proj?.name)
-        missing.push("project.name");
-    if (!proj?.prefix)
-        missing.push("project.prefix");
-    if (!cfg.stack)
-        missing.push("stack");
-    if (!cfg.commands)
-        missing.push("commands");
-    const paths = cfg.paths;
-    if (!paths?.engineering)
-        missing.push("paths.engineering");
-    if (!paths?.store)
-        missing.push("paths.store");
-    if (!paths?.workflows)
-        missing.push("paths.workflows");
-    return { ok: missing.length === 0, missing };
-}
-function verifyPhase2(cwd, kbPath) {
-    const archDocs = ["stack", "processes", "database", "routing", "deployment", "entity-model", "stack-checklist"];
-    const missing = [];
-    for (const d of archDocs) {
-        if (!fs.existsSync(path.join(cwd, kbPath, "architecture", `${d}.md`))) {
-            missing.push(`${kbPath}/architecture/${d}.md`);
-        }
-    }
-    return { ok: missing.length === 0, missing };
-}
-function verifyPhase3(cwd) {
-    const dirs = ["workflows", "personas", "skills", "templates"];
-    const missing = [];
-    for (const d of dirs) {
-        const dir = path.join(cwd, ".forge", d);
-        let count = 0;
-        try {
-            count = fs.readdirSync(dir).filter((f) => f.endsWith(".md") || f.endsWith(".json")).length;
-        }
-        catch {
-            count = 0;
-        }
-        if (count === 0)
-            missing.push(`.forge/${d}/ (empty)`);
-    }
-    return { ok: missing.length === 0, missing };
-}
-// ── Discovery prompt text ──────────────────────────────────────────────────
-function buildPhase1PromptText(bundleRoot, projectName) {
-    const discoveryDir = path.join(bundleRoot, ".init", "discovery");
-    const topics = ["stack", "processes", "database", "routing", "testing"];
-    const topicLines = topics.map((t) => `  • ${path.join(discoveryDir, `discover-${t}.md`)}`).join("\n");
-    return `## /forge:init Phase 1 — Collect: 5 parallel discovery scans
-Project: ${projectName}
-Run 5 discovery scans concurrently. In a single response, issue 5 parallel tool
-calls — one per discovery topic — using whatever read/search tools you have
-available (Read, Glob, Grep, Bash). If a \`subagent\` tool is exposed in your
-toolset, you MAY dispatch via it (mode: "parallel"); otherwise execute the
-scans inline. Do NOT preface with "I don't have a subagent tool" — either path
-is acceptable, what matters is concurrency and the resulting deliverable.
-For each topic:
-1. Read the discovery prompt file at its assigned path (shown below)
-2. Analyze the current project codebase
-3. Capture structured findings
-Discovery prompt files:
-${topicLines}
-After all 5 complete, synthesize the findings into a unified config and write .forge/config.json.
-Required .forge/config.json structure:
-{
-  "version": "1",
-  "project": { "name": "${projectName}", "prefix": "<UPPERCASE_ABBREV>" },
-  "stack": { "primary": [...], "test": <framework>, "build": <tool>, "lint": <tool> },
-  "commands": { "test": "<test cmd>", "build": "<build cmd>", "lint": "<lint cmd>" },
-  "paths": {
-    "engineering": "engineering",
-    "store": ".forge/store",
-    "workflows": ".forge/workflows",
-    "commands": ".claude/commands/forge",
-    "templates": ".forge/templates"
-  }
-}
-Write the config with: node "${path.join(bundleRoot, "tools/manage-config.cjs")}" set <key> <value>
-Or write .forge/config.json directly as valid JSON.`;
-}
-function buildPhase2PromptText(bundleRoot, kbPath, projectName) {
-    const generateKbDocPath = path.join(bundleRoot, ".init", "generation", "generate-kb-doc.md");
-    const docs = ["stack", "processes", "database", "routing", "deployment", "entity-model", "stack-checklist"];
-    const docLines = docs.map((d) => `  • ${kbPath}/architecture/${d}.md`).join("\n");
-    return `## /forge:init Phase 2 — Discover: 7 parallel KB doc generation
-Project: ${projectName}
-KB path: ${kbPath}/
-Rulebook: ${generateKbDocPath}
-Generate 7 knowledge-base documents concurrently. In a single response, issue
-7 parallel tool calls — one per document — using whatever read/search/write
-tools you have available (Read, Glob, Grep, Bash, Write). If a \`subagent\`
-tool is exposed in your toolset, you MAY dispatch via it (mode: "parallel");
-otherwise execute the generation inline. Do NOT preface with "I don't have a
-subagent tool" — either path is acceptable, what matters is concurrency and
-the 7 output files.
-For each document:
-1. Read the rulebook at: ${generateKbDocPath}
-2. Analyze the project codebase for its assigned topic
-3. Write the resulting document to its assigned output file
-Documents to generate:
-${docLines}
-After all complete, check for any that returned "FAILED:" in their output — retry those once.
-Also create these index files after generation:
-- ${kbPath}/architecture/INDEX.md
-- ${kbPath}/business-domain/INDEX.md
-- ${kbPath}/MASTER_INDEX.md (scaffold)`;
-}
-// ── Phase 4 helper — .gitignore update ────────────────────────────────────
-function updateGitignore(cwd, ctx) {
-    const gitignorePath = path.join(cwd, ".gitignore");
-    if (!fs.existsSync(gitignorePath)) {
-        // No gitignore — skip
-        return;
-    }
-    let content;
-    try {
-        content = fs.readFileSync(gitignorePath, "utf8");
-    }
-    catch {
-        return;
-    }
-    const IGNORE_PATTERNS = [".forge/store/events/", ".forge/store/events", ".forge/store/", ".forge/"];
-    const lines = content.split("\n");
-    const alreadyIgnored = lines.some((line) => {
-        const trimmed = line.trim();
-        if (!trimmed || trimmed.startsWith("#"))
-            return false;
-        return IGNORE_PATTERNS.some((pat) => trimmed.includes(pat));
-    });
-    if (alreadyIgnored) {
-        ctx.ui.notify("〇 .forge/store/events/ already gitignored — skipped.", "info");
-        return;
-    }
-    const toAppend = "\n# Forge — transient agent event logs (one file per phase, do not commit)\n.forge/store/events/\n";
-    try {
-        fs.appendFileSync(gitignorePath, toAppend, "utf8");
-        ctx.ui.notify("〇 Appended .forge/store/events/ to .gitignore.", "info");
-    }
-    catch {
-        ctx.ui.notify("△ Could not update .gitignore — update manually.", "warning");
-    }
-}
-// ── Phase 4 helper — agent instruction file linking ────────────────────────
-async function linkAgentInstructionFile(cwd, kbPath, projectName, ctx) {
-    const INSTRUCTION_FILES = ["CLAUDE.md", "AGENTS.md", "CLAUDE.local.md", ".cursorrules"];
-    const existing = INSTRUCTION_FILES.filter((f) => fs.existsSync(path.join(cwd, f)));
-    if (existing.length > 0) {
-        // Already exists — do NOT modify (per spec step 4-11: avoid KB-link bloat)
-        return;
-    }
-    // None exist — prompt to create minimal CLAUDE.md (G4: bypassed in non-interactive mode)
-    const ok = isNonInteractive()
-        ? true
-        : await ctx.ui.confirm("Create CLAUDE.md?", `No agent instruction file found at project root.\nCreate a minimal CLAUDE.md with links to the Forge knowledge base? [Y/n]`);
-    if (!ok) {
-        ctx.ui.notify("〇 KB not linked — run /forge:refresh-kb-links after creating CLAUDE.md.", "info");
-        return;
-    }
-    const claudeMdPath = path.join(cwd, "CLAUDE.md");
-    const content = [
-        `# ${projectName}`,
-        ``,
-        `## Forge Knowledge Base`,
-        ``,
-        `| Index | Contents |`,
-        `|-------|----------|`,
-        `| [MASTER_INDEX](${kbPath}/MASTER_INDEX.md) | All sprints, tasks, bugs, and features |`,
-        `| [Architecture](${kbPath}/architecture/INDEX.md) | Stack, processes, database, routing, deployment |`,
-        `| [Business Domain](${kbPath}/business-domain/INDEX.md) | Entity model and domain concepts |`,
-        ``,
-        `## Forge Workflows`,
-        ``,
-        `| Workflow | Purpose |`,
-        `|----------|---------|`,
-        `| /forge:plan | Research codebase, produce implementation plan |`,
-        `| /forge:implement | Execute approved plan, make code changes |`,
-        `| /forge:validate | Validate task implementation against acceptance criteria |`,
-        `| /forge:approve | Final architect approval gate |`,
-        `| /forge:commit | Stage and commit completed task artifacts |`,
-        `| /forge:fix-bug | Triage, diagnose, and fix a bug |`,
-        `| /forge:run-task | Full plan-implement-review-commit pipeline |`,
-        `| /forge:run-sprint | Execute all tasks in a sprint |`,
-        `| /forge:sprint-plan | Decompose sprint requirements into tasks |`,
-        `| /forge:sprint-intake | Elicit and structure requirements for a new sprint |`,
-        ``,
-        `---`,
-        `_Generated by /forge:init. Run /forge:refresh-kb-links to update._`,
-        ``,
-    ].join("\n");
-    try {
-        fs.writeFileSync(claudeMdPath, content, "utf8");
-        ctx.ui.notify("〇 Created CLAUDE.md with KB links.", "info");
-    }
-    catch (err) {
-        const e = err;
-        ctx.ui.notify(`△ Could not create CLAUDE.md: ${e.message ?? "unknown"}`, "warning");
-    }
-}
 // ── Main command registration ──────────────────────────────────────────────
 export function registerForgeInit(pi) {
     // Capture pi.sendUserMessage in closure — ExtensionCommandContext does not
@@ -431,9 +217,7 @@ export function registerForgeInit(pi) {
                 const resumeBanner = `〇 Previous init detected — last completed phase: ${lastPhase} of 4\n` +
                     `Resume from Phase ${nextPhase}?`;
                 // G1: in non-interactive mode, default to not resuming (start fresh)
-                const shouldResume = isNonInteractive()
-                    ? false
-                    : await ctx.ui.confirm("Resume /forge:init?", resumeBanner);
+                const shouldResume = isNonInteractive() ? false : await ctx.ui.confirm("Resume /forge:init?", resumeBanner);
                 if (shouldResume) {
                     startPhase = nextPhase;
                     // Skip hero banner on resume (session-scoped gate)
@@ -494,483 +278,63 @@ export function registerForgeInit(pi) {
                     }
                 }
             }
-            // ── Phase 1 — Collect ─────────────────────────────────────────────
-            if (startPhase <= 1) {
-                ctx.ui.setStatus?.("forge:init", "Phase 1/4: Collect");
-                const bannersTool = path.join(toolsRoot, "banners.cjs");
-                if (fs.existsSync(bannersTool)) {
-                    await execFileAsync("node", [bannersTool, "--phase", "1", "4", "Collect", "north"], {
-                        cwd,
-                        timeout: 5000,
-                    }).catch(() => {
-                        /* non-fatal */
-                    });
-                }
-                ctx.ui.notify("Running 5 discovery scans in parallel...", "info");
-                // Dispatch 5 discovery subagents via sendUserMessage instruction.
-                // If the agent doesn't have a `subagent` tool, it must fall back to
-                // running the 5 scans inline — Phase 1's deliverable is non-negotiable.
-                const phase1Prompt = buildPhase1PromptText(bundleRoot, projectName);
-                sendToAgent(phase1Prompt);
-                await ctx.waitForIdle();
-                // Verify deliverable. If missing, retry once with a corrective steer;
-                // if still missing, prompt the user to abort or continue with partial.
-                let phase1 = verifyPhase1(cwd);
-                if (!phase1.ok) {
-                    ctx.ui.notify(`△ Phase 1 deliverable missing: ${phase1.missing.join(", ")} — retrying with corrective steer.`, "warning");
-                    sendToAgent(`Phase 1 verification failed. .forge/config.json is missing the following required fields: ${phase1.missing.join(", ")}.\n\n` +
-                        `Write a complete .forge/config.json now using the \`write\` tool. Do NOT call subagents — analyze the project codebase yourself if needed. ` +
-                        `Use the schema from the original Phase 1 prompt: version, project.{name,prefix}, stack, commands, and paths.{engineering,store,workflows,commands,templates} are all required.`);
-                    await ctx.waitForIdle();
-                    phase1 = verifyPhase1(cwd);
-                }
-                if (!phase1.ok) {
-                    if (isNonInteractive()) {
-                        ctx.ui.notify(`× Phase 1 failed: ${phase1.missing.join(", ")}. Aborting init in non-interactive mode.`, "error");
-                        return;
-                    }
-                    const proceed = await ctx.ui.confirm("Phase 1 failed twice — continue with partial init?", `.forge/config.json is still missing: ${phase1.missing.join(", ")}.\n\n` +
-                        `Yes = continue (you'll need to /forge:regenerate later).\n` +
-                        `No  = abort. Inspect the file manually and re-run /forge:init.`);
-                    if (!proceed) {
-                        ctx.ui.notify("× /forge:init aborted at Phase 1 verify.", "error");
-                        return;
-                    }
-                    ctx.ui.notify("△ Continuing with partial Phase 1 — downstream phases may fail.", "warning");
-                }
-                // KB folder prompt (spec §7, F2) — G3: skipped in non-interactive mode (default: "engineering")
-                // Phrasing chosen so the default-Yes affirmative ("use engineering/") is the
-                // safe path. Pi's ctx.ui.confirm has no defaultValue option, so the question
-                // has to align with the highlighted default — earlier "does this conflict?"
-                // phrasing made the unsafe answer the default.
-                if (!isNonInteractive()) {
-                    const kbDescription = `Forge will create a folder for architecture docs, sprints, bugs, and features.\n\n` +
-                        `Use "engineering" as the folder name?  (Pick No only if your project already has an "engineering/" folder you don't want Forge to touch.)`;
-                    const useDefault = await ctx.ui.confirm("Engineering folder name?", kbDescription);
-                    if (!useDefault) {
-                        const customName = await ctx.ui.input("Engineering folder name? Enter preferred folder name", "e.g. ai-docs, .forge-kb, docs/ai");
-                        if (customName && customName.trim()) {
-                            const manageConfigToolEarly = path.join(toolsRoot, "manage-config.cjs");
-                            if (fs.existsSync(manageConfigToolEarly)) {
-                                await runToolAdvisory(manageConfigToolEarly, ["set", "paths.engineering", customName.trim()], cwd, ctx, "manage-config paths.engineering");
-                            }
-                        }
-                    }
-                }
-                // Marketplace skills advisory (sub-decision #1)
-                ctx.ui.notify("〇 Marketplace skills auto-recommendation is Claude-Code-only. " +
-                    "Pi users install extensions manually. Writing installedSkills: []", "info");
-                // Write installedSkills: []
-                const manageConfigTool = path.join(toolsRoot, "manage-config.cjs");
-                if (fs.existsSync(manageConfigTool)) {
-                    await runToolAdvisory(manageConfigTool, ["set", "installedSkills", "[]"], cwd, ctx, "manage-config installedSkills");
-                    // Write mode = "full"
-                    await runToolAdvisory(manageConfigTool, ["set", "mode", "full"], cwd, ctx, "manage-config mode");
-                }
-                writeInitProgress(cwd, 1);
-                ctx.ui.notify("〇 Phase 1 complete.", "info");
+            // ── Config cache (B-4, N-B-A) ─────────────────────────────────────
+            // Populated unconditionally before the loop so that resume paths
+            // (startPhase > 1) read the config.json that Phase 1 wrote in a prior
+            // session. Falls back to {} when config.json does not exist yet (first-run
+            // Phase 1 will create it). Refreshed after Phase 1 completes in the loop
+            // to pick up values the Phase-1 agent just wrote. See file-header comment
+            // §Config cache boundary for the full rationale.
+            let configCache = {};
+            try {
+                configCache = JSON.parse(fs.readFileSync(path.join(cwd, ".forge", "config.json"), "utf8"));
             }
-            // ── Phase 2 — Discover ────────────────────────────────────────────
-            if (startPhase <= 2) {
-                ctx.ui.setStatus?.("forge:init", "Phase 2/4: Discover");
-                const bannersTool = path.join(toolsRoot, "banners.cjs");
-                if (fs.existsSync(bannersTool)) {
-                    await execFileAsync("node", [bannersTool, "--phase", "2", "4", "Discover", "oracle"], {
-                        cwd,
-                        timeout: 5000,
-                    }).catch(() => {
-                        /* non-fatal */
-                    });
-                }
-                // Read KB_PATH from config
-                let kbPath = "engineering";
-                try {
-                    const configRaw = fs.readFileSync(path.join(cwd, ".forge", "config.json"), "utf8");
-                    const config = JSON.parse(configRaw);
-                    const paths = config.paths;
-                    if (paths && typeof paths.engineering === "string" && paths.engineering) {
-                        kbPath = paths.engineering;
-                    }
-                }
-                catch {
-                    // Use default
-                }
-                // Directory scaffolding
-                const dirs = [
-                    path.join(cwd, kbPath),
-                    path.join(cwd, kbPath, "architecture"),
-                    path.join(cwd, kbPath, "business-domain"),
-                    path.join(cwd, kbPath, "sprints"),
-                    path.join(cwd, ".forge", "store"),
-                    path.join(cwd, ".forge", "cache"),
-                ];
-                for (const dir of dirs) {
-                    try {
-                        fs.mkdirSync(dir, { recursive: true });
-                        // Write .gitkeep for empty dirs
-                        const keepPath = path.join(dir, ".gitkeep");
-                        if (!fs.existsSync(keepPath)) {
-                            fs.writeFileSync(keepPath, "", "utf8");
-                        }
-                    }
-                    catch {
-                        // Non-fatal
-                    }
-                }
-                // Dispatch 7 parallel KB doc subagents
-                const phase2Prompt = buildPhase2PromptText(bundleRoot, kbPath, projectName);
-                sendToAgent(phase2Prompt);
-                await ctx.waitForIdle();
-                // Verify Phase 2 deliverables.
-                let phase2 = verifyPhase2(cwd, kbPath);
-                if (!phase2.ok) {
-                    ctx.ui.notify(`△ Phase 2 deliverable incomplete: ${phase2.missing.length} doc(s) missing — retrying.`, "warning");
-                    sendToAgent(`Phase 2 verification failed. The following architecture docs are missing:\n${phase2.missing.map((m) => `  - ${m}`).join("\n")}\n\n` +
-                        `Write the missing files now using the \`write\` tool. Do NOT call subagents — analyze the project codebase yourself. ` +
-                        `Use the rulebook at ${path.join(bundleRoot, ".init", "generation", "generate-kb-doc.md")} for the per-doc shape and confidence-header format.`);
-                    await ctx.waitForIdle();
-                    phase2 = verifyPhase2(cwd, kbPath);
-                }
-                if (!phase2.ok) {
-                    if (isNonInteractive()) {
-                        ctx.ui.notify(`× Phase 2 failed: ${phase2.missing.length} doc(s) still missing. Aborting init in non-interactive mode.`, "error");
-                        return;
-                    }
-                    const proceed = await ctx.ui.confirm("Phase 2 failed twice — continue with partial init?", `Missing docs:\n${phase2.missing.map((m) => `  - ${m}`).join("\n")}\n\n` +
-                        `Yes = continue (you'll need to fill these manually).\n` +
-                        `No  = abort. Inspect the project and re-run /forge:init.`);
-                    if (!proceed) {
-                        ctx.ui.notify("× /forge:init aborted at Phase 2 verify.", "error");
-                        return;
-                    }
-                    ctx.ui.notify("△ Continuing with partial Phase 2.", "warning");
-                }
-                // Construct project-context.json
-                let kbPathResolved = kbPath;
-                let prefix = "";
-                try {
-                    const configRaw = fs.readFileSync(path.join(cwd, ".forge", "config.json"), "utf8");
-                    const config = JSON.parse(configRaw);
-                    const proj = config.project;
-                    if (proj && typeof proj.prefix === "string")
-                        prefix = proj.prefix;
-                    const paths = config.paths;
-                    if (paths && typeof paths.engineering === "string")
-                        kbPathResolved = paths.engineering;
-                }
-                catch {
-                    // Use defaults
-                }
-                // Read config for full project context construction
-                let configForContext = {};
-                try {
-                    const raw = fs.readFileSync(path.join(cwd, ".forge", "config.json"), "utf8");
-                    configForContext = JSON.parse(raw);
-                }
-                catch {
-                    // empty config
-                }
-                const projectCtx = buildProjectContext({
-                    projectName: configForContext.project?.name ?? projectName,
-                    prefix,
-                    kbPath: kbPathResolved,
-                }, configForContext);
-                try {
-                    validateProjectContext(projectCtx);
-                    writeProjectContext(cwd, projectCtx);
-                    ctx.ui.notify("〇 project-context.json written.", "info");
-                }
-                catch (err) {
-                    const e = err;
-                    ctx.ui.notify(`△ project-context.json validation failed: ${e.message ?? "unknown"} — proceeding.`, "warning");
-                }
-                // Calibration baseline
-                const baseline = computeCalibrationBaseline(cwd, kbPathResolved, bundledVersion);
-                const manageConfigTool = path.join(toolsRoot, "manage-config.cjs");
-                if (fs.existsSync(manageConfigTool)) {
-                    await runToolAdvisory(manageConfigTool, ["set", "calibrationBaseline", JSON.stringify(baseline)], cwd, ctx, "manage-config calibrationBaseline");
-                }
-                writeInitProgress(cwd, 2);
-                ctx.ui.notify("〇 Phase 2 complete.", "info");
+            catch {
+                // File not yet present — Phase 1 will create it
             }
-            // ── Phase 3 — Materialize ─────────────────────────────────────────
-            if (startPhase <= 3) {
-                ctx.ui.setStatus?.("forge:init", "Phase 3/4: Materialize");
-                const bannersTool = path.join(toolsRoot, "banners.cjs");
-                if (fs.existsSync(bannersTool)) {
-                    await execFileAsync("node", [bannersTool, "--phase", "3", "4", "Materialize", "supervisor"], {
-                        cwd,
-                        timeout: 5000,
-                    }).catch(() => {
-                        /* non-fatal */
-                    });
-                }
-                const buildInitContextTool = path.join(toolsRoot, "build-init-context.cjs");
-                const substituteTool = path.join(toolsRoot, "substitute-placeholders.cjs");
-                const buildOverlayTool = path.join(toolsRoot, "build-overlay.cjs");
-                const basePackDir = path.join(bundleRoot, ".base-pack");
-                // 3a: build-init-context.cjs first build
-                if (fs.existsSync(buildInitContextTool)) {
-                    await runToolAdvisory(buildInitContextTool, [
-                        "--config",
-                        path.join(cwd, ".forge", "config.json"),
-                        "--personas",
-                        path.join(cwd, ".forge", "personas"),
-                        "--templates",
-                        path.join(cwd, ".forge", "templates"),
-                        "--kb",
-                        cwd,
-                        "--out",
-                        path.join(cwd, ".forge", "init-context.md"),
-                        "--json-out",
-                        path.join(cwd, ".forge", "init-context.json"),
-                    ], cwd, ctx, "build-init-context", 30000);
-                }
-                // 3b: substitute-placeholders.cjs — base-pack materialisation
-                if (fs.existsSync(substituteTool) && fs.existsSync(basePackDir)) {
-                    await runToolAdvisory(substituteTool, [
-                        "--forge-root",
-                        bundleRoot,
-                        "--base-pack",
-                        basePackDir,
-                        "--config",
-                        path.join(cwd, ".forge", "config.json"),
-                        "--context",
-                        path.join(cwd, ".forge", "init-context.json"),
-                        "--out",
-                        cwd,
-                    ], cwd, ctx, "substitute-placeholders", 60000);
-                }
-                // 3c: build-overlay.cjs smoke test (exit 1 is advisory)
-                if (fs.existsSync(buildOverlayTool)) {
-                    await runToolAdvisory(buildOverlayTool, ["--task", "INIT-SMOKE-TEST", "--format", "json"], cwd, ctx, "build-overlay smoke (advisory)", 15000);
-                }
-                // Verify Phase 3 deliverables. substitute-placeholders.cjs is invoked
-                // via runToolAdvisory, so a missing/invalid config produces zero
-                // output and no exception. Hard-fail here.
-                const phase3 = verifyPhase3(cwd);
-                if (!phase3.ok) {
-                    ctx.ui.notify(`× Phase 3 failed: ${phase3.missing.join(", ")}. ` +
-                        `This usually means substitute-placeholders.cjs ran against an incomplete config. ` +
-                        `Fix .forge/config.json and run /forge:regenerate, or restart /forge:init from scratch (delete .forge/init-progress.json).`, "error");
+            // ── Phases 1–3: descriptor-driven loop ──────────────────────────────
+            // Each phase is described by an LlmPhaseDescriptor (forge-init/phase-descriptors.ts).
+            // The generic runLlmPhase() runner handles: banner, LLM dispatch / deterministic
+            // tool execution, verify, retry steer, user confirm, postVerify, writeInitProgress.
+            const PHASES = [PHASE_1, PHASE_2, PHASE_3];
+            for (const desc of PHASES) {
+                if (startPhase > desc.phaseNum) {
+                    // Resume path: skip phases already completed
+                    continue;
+                }
+                const phaseResult = await runLlmPhase(desc, ctx, cwd, bundleRoot, toolsRoot, projectName, configCache, sendToAgent, () => ctx.waitForIdle(), isNonInteractive);
+                if (phaseResult === "abort") {
                     return;
                 }
-                writeInitProgress(cwd, 3);
-                ctx.ui.notify("〇 Phase 3 complete.", "info");
-            }
-            // ── Phase 4 — Register ────────────────────────────────────────────
-            if (startPhase <= 4) {
-                ctx.ui.setStatus?.("forge:init", "Phase 4/4: Register");
-                const bannersTool = path.join(toolsRoot, "banners.cjs");
-                if (fs.existsSync(bannersTool)) {
-                    await execFileAsync("node", [bannersTool, "--phase", "4", "4", "Register", "forge"], {
-                        cwd,
-                        timeout: 5000,
-                    }).catch(() => {
-                        /* non-fatal */
-                    });
-                }
-                const manageConfigTool = path.join(toolsRoot, "manage-config.cjs");
-                const manageVersionsTool = path.join(toolsRoot, "manage-versions.cjs");
-                const generationManifestTool = path.join(toolsRoot, "generation-manifest.cjs");
-                const buildPersonaPackTool = path.join(toolsRoot, "build-persona-pack.cjs");
-                const buildContextPackTool = path.join(toolsRoot, "build-context-pack.cjs");
-                const buildInitContextTool = path.join(toolsRoot, "build-init-context.cjs");
-                const seedStoreTool = path.join(toolsRoot, "seed-store.cjs");
-                // Step 4-1: write paths.forgeRoot + copy schemas
-                // Stamp paths.forgeRoot to the bundle root (dist/forge-payload/) so
-                // that the canonical Forge convention "$FORGE_ROOT/tools/<tool>.cjs"
-                // resolves correctly. The bundled tools live at
-                // dist/forge-payload/tools/ (renamed from .tools/ — the dot prefix
-                // broke the convention and forced consumers/workflows to special-case
-                // the layout).
-                if (fs.existsSync(manageConfigTool)) {
-                    // Validate that store-cli.cjs is present in the bundled tools dir
-                    // before stamping. Guards against half-built dist trees.
-                    let forgeRootToStamp;
-                    if (isPiRuntime()) {
-                        const toolsRoot = getBundledToolsRoot();
-                        const storeCli = path.join(toolsRoot, "store-cli.cjs");
-                        if (!fs.existsSync(storeCli)) {
-                            ctx.ui.notify(`× step 4-1 paths.forgeRoot: store-cli.cjs missing from bundled tools (expected: ${storeCli}). ` +
-                                "Run 'npm run build' to populate dist/forge-payload/tools/. Aborting Phase 4.", "error");
-                            return;
-                        }
-                        forgeRootToStamp = bundleRoot;
-                    }
-                    else {
-                        // Claude Code path (not active today — preserved for future use)
-                        forgeRootToStamp = bundleRoot;
-                    }
-                    await runToolAdvisory(manageConfigTool, ["set", "paths.forgeRoot", forgeRootToStamp], cwd, ctx, "step 4-1 paths.forgeRoot");
-                }
-                const schemasSrc = path.join(bundleRoot, ".schemas");
-                const schemasDest = path.join(cwd, ".forge", "schemas");
-                fs.mkdirSync(schemasDest, { recursive: true });
-                if (fs.existsSync(schemasSrc)) {
-                    const schemaFiles = fs.readdirSync(schemasSrc).filter((f) => f.endsWith(".json"));
-                    for (const f of schemaFiles) {
-                        try {
-                            fs.copyFileSync(path.join(schemasSrc, f), path.join(schemasDest, f));
-                        }
-                        catch {
-                            // non-fatal
-                        }
-                    }
-                    ctx.ui.notify(`〇 Copied ${schemaFiles.length} schema files to .forge/schemas/.`, "info");
-                }
-                // Step 4-1b: enhancement substrate
-                const enhancementsDir = path.join(cwd, ".forge", "enhancements");
-                fs.mkdirSync(enhancementsDir, { recursive: true });
-                const overlaySchemaPath = path.join(schemasSrc, "project-overlay.schema.json");
-                if (fs.existsSync(overlaySchemaPath)) {
+                // Refresh configCache after Phase 1 writes .forge/config.json so
+                // Phase 2, Phase 4, and the post-init report see the values the
+                // Phase-1 agent just produced.
+                if (desc.phaseNum === 1) {
                     try {
-                        fs.copyFileSync(overlaySchemaPath, path.join(schemasDest, "project-overlay.schema.json"));
+                        configCache = JSON.parse(fs.readFileSync(path.join(cwd, ".forge", "config.json"), "utf8"));
                     }
                     catch {
-                        // non-fatal
-                    }
-                }
-                // Step 4-2: manage-versions init
-                if (fs.existsSync(manageVersionsTool)) {
-                    await runToolAdvisory(manageVersionsTool, ["init"], cwd, ctx, "step 4-2 manage-versions");
-                }
-                // Step 4-3: generation-manifest record-all
-                if (fs.existsSync(generationManifestTool)) {
-                    await runToolAdvisory(generationManifestTool, ["record-all"], cwd, ctx, "step 4-3 generation-manifest", 30000);
-                }
-                // Step 4-4: build-persona-pack
-                if (fs.existsSync(buildPersonaPackTool)) {
-                    await runToolAdvisory(buildPersonaPackTool, ["--out", path.join(cwd, ".forge", "cache", "persona-pack.json")], cwd, ctx, "step 4-4 build-persona-pack", 30000);
-                }
-                // Step 4-5: build-context-pack
-                try {
-                    const raw = fs.readFileSync(path.join(cwd, ".forge", "config.json"), "utf8");
-                    const cfg = JSON.parse(raw);
-                    const p = cfg.paths;
-                    if (p && typeof p.engineering === "string")
-                        kbPathFinal = p.engineering;
-                }
-                catch {
-                    // use default "engineering"
-                }
-                if (fs.existsSync(buildContextPackTool)) {
-                    await runToolAdvisory(buildContextPackTool, [
-                        "--arch-dir",
-                        path.join(cwd, kbPathFinal, "architecture"),
-                        "--out-md",
-                        path.join(cwd, ".forge", "cache", "context-pack.md"),
-                        "--out-json",
-                        path.join(cwd, ".forge", "cache", "context-pack.json"),
-                    ], cwd, ctx, "step 4-5 build-context-pack", 30000);
-                }
-                // Step 4-6: build-init-context final rebuild
-                if (fs.existsSync(buildInitContextTool)) {
-                    await runToolAdvisory(buildInitContextTool, [
-                        "--config",
-                        path.join(cwd, ".forge", "config.json"),
-                        "--personas",
-                        path.join(cwd, ".forge", "personas"),
-                        "--templates",
-                        path.join(cwd, ".forge", "templates"),
-                        "--kb",
-                        cwd,
-                        "--out",
-                        path.join(cwd, ".forge", "init-context.md"),
-                        "--json-out",
-                        path.join(cwd, ".forge", "init-context.json"),
-                    ], cwd, ctx, "step 4-6 build-init-context final", 30000);
-                }
-                // Step 4-7: seed-store
-                if (fs.existsSync(seedStoreTool)) {
-                    await runToolAdvisory(seedStoreTool, [], cwd, ctx, "step 4-7 seed-store", 30000);
-                }
-                // Step 4-8: update-check cache baseline
-                const updateCachePath = path.join(cwd, ".forge", "update-check-cache.json");
-                try {
-                    const pluginPath = path.join(bundleRoot, ".claude-plugin", "plugin.json");
-                    const pluginRaw = fs.readFileSync(pluginPath, "utf8");
-                    const plugin = JSON.parse(pluginRaw);
-                    const cache = {
-                        lastChecked: new Date().toISOString(),
-                        installedVersion: plugin.version ?? bundledVersion,
-                        latestVersion: plugin.version ?? bundledVersion,
-                        upToDate: true,
-                    };
-                    fs.writeFileSync(updateCachePath, JSON.stringify(cache, null, 2) + "\n", "utf8");
-                    ctx.ui.notify("〇 Update-check cache baseline written.", "info");
-                }
-                catch {
-                    ctx.ui.notify("△ Could not write update-check cache — non-fatal.", "warning");
-                }
-                // Step 4-9: Tomoshibi — invoke refresh-kb-links handler directly
-                try {
-                    const refreshHandler = getRefreshKbLinksHandler();
-                    const refreshResult = await refreshHandler(cwd);
-                    for (const msg of refreshResult.messages) {
-                        ctx.ui.notify(msg, "info");
-                    }
-                    if (refreshResult.filesUpdated === 0) {
-                        ctx.ui.notify("△ Run /forge:refresh-kb-links manually after init completes " +
-                            "(no agent instruction files found).", "info");
+                        // Fall back to existing cache — all downstream reads have their own defaults
                     }
                 }
-                catch (err) {
-                    const e = err;
-                    ctx.ui.notify(`△ Tomoshibi (refresh-kb-links) failed: ${e.message ?? "unknown"} — ` +
-                        "Run /forge:refresh-kb-links manually after init completes.", "warning");
-                }
-                // Step 4-10: .gitignore update
-                updateGitignore(cwd, ctx);
-                // Step 4-10b: BUG-025 fix — remove Claude-Code-only .claude/commands/ artifact.
-                // substitute-placeholders.cjs (Phase 3) unconditionally writes command .md files
-                // to .claude/commands/<prefix>/ regardless of runtime. Under pi runtime pi never
-                // scans .claude/commands/ (commands are discovered via programmatic registerCommand
-                // in registerAllForgeCommands). Delete the directory so it does not pollute the
-                // project root. This runs in Phase 4 so it handles both same-session and resumed
-                // inits (where Phase 3 ran in a prior session).
-                if (isPiRuntime()) {
-                    let commandsPrefix = "forge";
-                    try {
-                        const cfgRaw = fs.readFileSync(path.join(cwd, ".forge", "config.json"), "utf8");
-                        const cfg = JSON.parse(cfgRaw);
-                        const proj = cfg.project;
-                        if (proj && typeof proj.prefix === "string" && proj.prefix) {
-                            commandsPrefix = proj.prefix.toLowerCase();
-                        }
-                    }
-                    catch {
-                        // fall back to "forge"
-                    }
-                    const claudeCommandsDir = path.join(cwd, ".claude", "commands", commandsPrefix);
-                    if (fs.existsSync(claudeCommandsDir)) {
-                        try {
-                            fs.rmSync(claudeCommandsDir, { recursive: true, force: true });
-                            // Remove empty ancestor dirs best-effort
-                            const parentDir = path.join(cwd, ".claude", "commands");
-                            try {
-                                if (fs.readdirSync(parentDir).length === 0) {
-                                    fs.rmdirSync(parentDir);
-                                    const grandparent = path.join(cwd, ".claude");
-                                    if (fs.readdirSync(grandparent).length === 0)
-                                        fs.rmdirSync(grandparent);
-                                }
-                            }
-                            catch {
-                                // best-effort
-                            }
-                        }
-                        catch (err) {
-                            const e = err;
-                            ctx.ui.notify(`△ Could not remove .claude/commands/${commandsPrefix}/: ${e.message ?? "unknown"} — non-fatal.`, "warning");
-                        }
-                    }
+            }
+            // ── Phase 4 — Register (runPhase4) ────────────────────────────────
+            if (startPhase <= 4) {
+                const phase4Result = await runPhase4({
+                    cwd,
+                    bundleRoot,
+                    toolsRoot,
+                    projectName,
+                    configCache,
+                    ctx,
+                    isPiRuntime,
+                    getBundledToolsRoot,
+                });
+                if (phase4Result === "abort") {
+                    return;
                 }
-                // Step 4-11: agent instruction file linking
-                await linkAgentInstructionFile(cwd, kbPathFinal, projectName, ctx);
-                // Completion — delete init-progress
-                deleteInitProgress(cwd);
-                ctx.ui.notify("〇 Phase 4 complete — /forge:init done.", "info");
+                // phase4Result.kbPathFinal is used in the post-init report below
+                kbPathFinal = phase4Result.kbPathFinal;
             }
             // ── Post-Phase-4: health check ────────────────────────────────────
             ctx.ui.setStatus?.("forge:init", "Post-init: health check");
@@ -990,36 +354,28 @@ export function registerForgeInit(pi) {
             // materialization-marker checks, audience gates, and dispatch.
             // Errors inside hooks are caught by emitSyntheticEvent — fail-open.
             {
+                // Use configCache — valid for both full-run and resumed-init paths.
+                // configCache is populated once (after Phase 1 completes or from pre-existing
+                // config.json for resumed inits). Non-fatal if cache is empty (empty prefix
+                // causes hook to write sentinel under post-init-fired-.json).
                 let projectPrefixForHook = "";
-                try {
-                    const cfgRaw = fs.readFileSync(path.join(cwd, ".forge", "config.json"), "utf8");
-                    const cfg = JSON.parse(cfgRaw);
-                    const proj = cfg.project;
-                    if (proj && typeof proj.prefix === "string")
-                        projectPrefixForHook = proj.prefix;
-                }
-                catch {
-                    // Non-fatal: if config read fails, emit with empty prefix
-                    // (hook will write sentinel under post-init-fired-.json)
+                const projForHook = configCache.project;
+                if (projForHook && typeof projForHook.prefix === "string") {
+                    projectPrefixForHook = projForHook.prefix;
                 }
                 await emitSyntheticEvent({ type: "init-complete", projectPrefix: projectPrefixForHook, cwd }, ctx);
             }
             // ── Report ────────────────────────────────────────────────────────
-            // FIX BUG-020: read kbPathFinal from config.json at report time so
-            // a custom KB folder chosen in Phase 1 is reflected here. kbPathFinal
-            // is only updated inside the Phase-4 block, so if init was resumed
-            // from Phase 1-3 we still get the right value.
-            try {
-                const cfgRaw = fs.readFileSync(path.join(cwd, ".forge", "config.json"), "utf8");
-                const cfg = JSON.parse(cfgRaw);
-                const p = cfg.paths;
+            // FIX BUG-020: use configCache here (populated from config.json after Phase 1
+            // or from pre-existing config.json for resumed inits starting at Phase 2+).
+            // kbPathFinal is updated inside the Phase-4 block; for Phase-1-3 resumes
+            // configCache captures the correct value that Phase 4 would have stamped.
+            {
+                const p = configCache.paths;
                 if (p && typeof p.engineering === "string" && p.engineering) {
                     kbPathFinal = p.engineering;
                 }
             }
-            catch {
-                // use default "engineering" already set
-            }
             ctx.ui.setStatus?.("forge:init", undefined);
             const kbPath_ = kbPathFinal;
             // FIX BUG-022 (product call): surface gap details in Report.