@girardmedia/bootspring 3.1.0 → 3.2.0

package/assets/claude-commands/build.md

@@ -21,6 +21,8 @@ When user invokes `/build` or says "build next", "build loop", "build done", use
 - `/build list` → `bootspring_build` with action: "list"
 - `/build current` → `bootspring_build` with action: "current"
 
+After `action: "next"` or `action: "current"`, surface the returned `visibility` contract: show a visible checklist in the host UI when available and keep `planning/BUILD_PROGRESS.md` updated after inspection, edits, verification, and completion.
+
 ## Important
 
 - "build" in Bootspring context means **task execution**, not `npm run build`

package/dist/cli/index.js

@@ -3386,7 +3386,7 @@ var init_release = __esm({
   "../../packages/shared/src/release.ts"() {
     "use strict";
     init_cjs_shims();
-    BOOTSPRING_VERSION = "3.1.0";
+    BOOTSPRING_VERSION = "3.2.0";
     BOOTSPRING_PACKAGE_NAME = "@girardmedia/bootspring";
   }
 });
@@ -56437,6 +56437,15 @@ init_cjs_shims();
 var fs51 = __toESM(require("fs"));
 var path52 = __toESM(require("path"));
 init_src();
+var BUILD_PROGRESS_ARTIFACT = path52.join("planning", "BUILD_PROGRESS.md");
+var VISIBLE_WORK_CHECKPOINTS = [
+  "Announce the active task and intended checkpoints in the chat or terminal.",
+  "Inspect the relevant files and summarize what changed before editing.",
+  "Patch the implementation and keep unrelated files untouched.",
+  "Add or update focused tests when the task changes behavior.",
+  "Run the relevant verification commands and report pass/fail output.",
+  "Update the build state with `bootspring build done` only after verification."
+];
 function getPlanningSurfaceStatus() {
   const planningDir = path52.join(process.cwd(), "planning");
   return {
@@ -56768,6 +56777,97 @@ function getTaskEntriesFromState(state) {
     estimatedTurns: task.estimatedTurns
   }));
 }
+function getStatusCounts(tasks) {
+  const completed = tasks.filter((t) => normalizeStatus(t.status) === "completed").length;
+  const skipped = tasks.filter((t) => normalizeStatus(t.status) === "skipped").length;
+  const blocked = tasks.filter((t) => normalizeStatus(t.status) === "blocked").length;
+  const pending = tasks.filter((t) => normalizeStatus(t.status) === "pending").length;
+  const inProgress = tasks.filter((t) => normalizeStatus(t.status) === "in_progress").length;
+  const total = tasks.length;
+  const closed = completed + skipped;
+  const pct2 = total > 0 ? Math.round(closed / total * 100) : 0;
+  return { completed, skipped, blocked, pending, inProgress, total, closed, pct: pct2 };
+}
+function renderProgressBar(pct2, width = 30) {
+  const clamped = Math.max(0, Math.min(100, pct2));
+  const filled = Math.round(clamped / 100 * width);
+  return `[${"#".repeat(filled)}${".".repeat(width - filled)}] ${clamped}%`;
+}
+function getVisibleTask(task) {
+  if (!task?.id || !task?.title) return null;
+  return {
+    id: task.id,
+    title: task.title,
+    phase: task.phase,
+    complexity: task.complexity,
+    status: normalizeStatus(task.status),
+    description: task.description,
+    source: task.source,
+    sourceSection: task.sourceSection,
+    acceptanceCriteria: task.acceptanceCriteria ?? [],
+    dependencies: task.dependencies ?? [],
+    estimatedTokens: task.estimatedTokens,
+    estimatedTurns: task.estimatedTurns
+  };
+}
+function writeBuildProgressArtifact(state, task, event) {
+  const dir = path52.join(process.cwd(), "planning");
+  if (!fs51.existsSync(dir)) fs51.mkdirSync(dir, { recursive: true });
+  const tasks = getTaskEntriesFromState(state);
+  const counts = getStatusCounts(tasks);
+  const visibleTask = getVisibleTask(task) ?? tasks.find((t) => normalizeStatus(t.status) === "in_progress") ?? tasks.find((t) => normalizeStatus(t.status) === "pending") ?? null;
+  const progressPath = path52.join(process.cwd(), BUILD_PROGRESS_ARTIFACT);
+  const updated = (/* @__PURE__ */ new Date()).toISOString();
+  const artifact = [
+    "# Build Progress",
+    "",
+    `Updated: ${updated}`,
+    `Event: ${event}`,
+    `Project: ${state.projectName ?? path52.basename(process.cwd())}`,
+    `Status: ${deriveBuildStatus(state.status, counts)}`,
+    `Overall: ${counts.closed}/${counts.total} ${renderProgressBar(counts.pct)}`,
+    "",
+    "## Active Task",
+    "",
+    visibleTask ? [
+      `- ID: ${visibleTask.id}`,
+      `- Title: ${visibleTask.title}`,
+      `- Status: ${normalizeStatus(visibleTask.status)}`,
+      `- Phase: ${visibleTask.phase ?? "Unknown"}`,
+      visibleTask.description ? `- Description: ${visibleTask.description}` : null,
+      visibleTask.dependencies?.length ? `- Dependencies: ${visibleTask.dependencies.join(", ")}` : null
+    ].filter(Boolean).join("\n") : "No active or pending task.",
+    "",
+    "## Acceptance Criteria",
+    "",
+    visibleTask?.acceptanceCriteria?.length ? visibleTask.acceptanceCriteria.map((item) => `- [ ] ${item}`).join("\n") : "- [ ] No task-specific acceptance criteria recorded.",
+    "",
+    "## Visible Work Contract",
+    "",
+    VISIBLE_WORK_CHECKPOINTS.map((item) => `- [ ] ${item}`).join("\n"),
+    "",
+    "## Host Notes",
+    "",
+    "- Claude Code and Codex CLI can stream terminal output directly.",
+    "- Codex Desktop, Claude Desktop, and other MCP hosts should keep a visible plan/checklist updated while the terminal is hidden.",
+    "- Update this file after inspection, edits, verification, and completion so the workspace has a durable progress surface.",
+    ""
+  ].join("\n");
+  fs51.writeFileSync(progressPath, artifact);
+  return BUILD_PROGRESS_ARTIFACT;
+}
+function printVisibleWorkNotice(artifactPath) {
+  print.header("Visible Work");
+  print.info(`Progress artifact: ${artifactPath}`);
+  print.info("Desktop agents should keep a visible plan/checklist updated while they inspect, edit, verify, and mark the task done.");
+  print.info("This mirrors Claude Code/Codex CLI-style streaming even when the host hides terminal output.");
+}
+function deriveBuildStatus(stateStatus, counts) {
+  if (counts.total > 0 && counts.pending === 0 && counts.inProgress === 0) {
+    return counts.blocked > 0 ? "blocked" : "completed";
+  }
+  return stateStatus ?? "unknown";
+}
 function extractSupplementaryContent(queueContent) {
   const lines = queueContent.split("\n");
   const sections = [];
@@ -56941,7 +57041,8 @@ function registerBuildCommand(program3) {
   build.command("status").description("Check build progress").option("--json", "Output as JSON").action((opts) => {
     const state = loadBuildStateWithAutoSync(opts.json);
     const planningTasks = loadPlanningTasks();
-    const tasks = planningTasks.tasks.length > 0 ? planningTasks.tasks : getTaskEntriesFromState(state);
+    const stateTasks = getTaskEntriesFromState(state);
+    const tasks = stateTasks.length > 0 ? stateTasks : planningTasks.tasks;
     if (!state) {
       if (opts.json) {
         console.log(JSON.stringify({ error: "no_build_state", tasks: [] }));
@@ -56960,14 +57061,8 @@ function registerBuildCommand(program3) {
       }
       return;
     }
-    const completed = tasks.filter((t) => {
-      const s = t.status.toLowerCase();
-      return s === "completed" || s === "done";
-    }).length;
-    const pending = tasks.filter((t) => t.status.toLowerCase() === "pending").length;
-    const inProgress = tasks.filter((t) => t.status.toLowerCase() === "in_progress").length;
-    const total = tasks.length;
-    const pct2 = total > 0 ? Math.round(completed / total * 100) : 0;
+    const { completed, skipped, blocked, pending, inProgress, total, closed, pct: pct2 } = getStatusCounts(tasks);
+    const derivedStatus = deriveBuildStatus(state.status, { completed, skipped, blocked, pending, inProgress, total, closed, pct: pct2 });
     const iteration = state.loopSession?.currentIteration ?? 0;
     const maxIter = state.loopSession?.maxIterations ?? 50;
     const sessionId = state.loopSession?.sessionId ?? "N/A";
@@ -56975,12 +57070,15 @@ function registerBuildCommand(program3) {
       const currentTask2 = tasks.find((t) => t.status.toLowerCase() === "in_progress");
       console.log(JSON.stringify({
         project: state.projectName ?? "Unknown",
-        status: state.status,
+        status: derivedStatus,
         phase: formatPhaseName(state.currentPhase ?? getCurrentPhase(state.implementationQueue)),
         planningSource: formatPlanningSourceLabel(planningTasks.source ?? (state ? "BUILD_STATE.json" : null)),
         completed,
+        skipped,
+        blocked,
         pending,
         inProgress,
+        closed,
         total,
         pct: pct2,
         iteration,
@@ -56993,10 +57091,12 @@ function registerBuildCommand(program3) {
     print.header("Build Status");
     printLegacyQueueWarningIfNeeded();
     print.info(`Project: ${state.projectName ?? "Unknown"}`);
-    print.info(`Status: ${state.status}`);
+    print.info(`Status: ${derivedStatus}`);
     print.info(`Phase: ${formatPhaseName(state.currentPhase ?? getCurrentPhase(state.implementationQueue))}`);
     print.info(`Planning Source: ${formatPlanningSourceLabel(planningTasks.source ?? (state ? "BUILD_STATE.json" : null))}`);
-    print.info(`Progress: ${completed}/${total} (${pct2}%)`);
+    print.info(`Progress: ${closed}/${total} (${pct2}%)`);
+    if (skipped > 0) print.info(`Skipped: ${skipped}`);
+    if (blocked > 0) print.info(`Blocked: ${blocked}`);
     print.info(`Pending: ${pending}`);
     if (inProgress > 0) print.info(`In Progress: ${inProgress}`);
     if (iteration > maxIter) {
@@ -57013,6 +57113,40 @@ function registerBuildCommand(program3) {
     const filled = Math.round(pct2 / 100 * barWidth);
     const bar = "#".repeat(filled) + ".".repeat(barWidth - filled);
     console.log(`  [${bar}] ${pct2}%`);
+    const artifactPath = writeBuildProgressArtifact(state, currentTask, "status");
+    print.info(`Progress artifact: ${artifactPath}`);
+  });
+  build.command("progress").description("Show the visible build progress artifact for desktop/agent hosts").option("--json", "Output artifact metadata as JSON").action((opts) => {
+    const state = loadBuildStateWithAutoSync(opts.json);
+    if (!state) {
+      if (opts.json) {
+        console.log(JSON.stringify({ error: "no_build_state", artifact: null }));
+      } else {
+        print.error("No build state found");
+      }
+      return;
+    }
+    const tasks = getTaskEntriesFromState(state);
+    const currentTask = tasks.find((t) => normalizeStatus(t.status) === "in_progress") ?? tasks.find((t) => normalizeStatus(t.status) === "pending") ?? null;
+    const artifactPath = writeBuildProgressArtifact(state, currentTask, "progress");
+    if (opts.json) {
+      const counts = getStatusCounts(tasks);
+      console.log(JSON.stringify({
+        artifact: artifactPath,
+        progress: {
+          completed: counts.completed,
+          pending: counts.pending,
+          inProgress: counts.inProgress,
+          total: counts.total,
+          percent: counts.pct
+        },
+        currentTask: currentTask ? { id: currentTask.id, title: currentTask.title, status: currentTask.status } : null,
+        visibleWorkCheckpoints: VISIBLE_WORK_CHECKPOINTS
+      }, null, 2));
+      return;
+    }
+    print.header("Build Progress");
+    console.log(fs51.readFileSync(path52.join(process.cwd(), artifactPath), "utf-8"));
   });
   build.command("task").description("Show the current task").action(() => {
     printLegacyQueueWarningIfNeeded();
@@ -57096,6 +57230,8 @@ function registerBuildCommand(program3) {
     } else {
       print.success("No more pending tasks!");
     }
+    const artifactPath = writeBuildProgressArtifact(state, nextTask ?? queue[idx], nextTask ? "task_completed_next_available" : "task_completed_all_done");
+    printVisibleWorkNotice(artifactPath);
   });
   build.command("plan").description("View the full build plan").action(() => {
     printLegacyQueueWarningIfNeeded();
@@ -57167,6 +57303,8 @@ function registerBuildCommand(program3) {
     const inProgress = queue.find((t2) => t2.status === "in_progress");
     if (inProgress) {
       print.warning(`Task ${inProgress.id} is already in progress: ${inProgress.title}`);
+      const artifactPath2 = writeBuildProgressArtifact(state, inProgress, "already_in_progress");
+      printVisibleWorkNotice(artifactPath2);
       return;
     }
     const idx = queue.findIndex((t2) => t2.status === "pending");
@@ -57194,6 +57332,8 @@ function registerBuildCommand(program3) {
         console.log(`  [ ] ${ac}`);
       }
     }
+    const artifactPath = writeBuildProgressArtifact(state, t, "task_started");
+    printVisibleWorkNotice(artifactPath);
   });
   build.command("pause").description("Pause the build loop").action(() => {
     const state = loadBuildState();
@@ -61870,7 +62010,7 @@ function generateDocTemplate(docType, projectName) {
 `;
 }
 function registerGoCommand(program3) {
-  program3.command("go").description("One-command setup: detect \u2192 seed \u2192 generate \u2192 build init").option("--preset <preset>", "Document set (essential, startup, full, technical)", "startup").option("--force", "Overwrite existing files").option("--edit-first", "Stop after creating templates for manual editing").action((opts) => {
+  program3.command("go").description("One-command setup: detect \u2192 seed \u2192 generate \u2192 build init").argument("[pitch]", "Optional project pitch \u2014 uses AI to fill all context docs").option("--preset <preset>", "Document set (essential, startup, full, technical)", "startup").option("--provider <provider>", "AI provider: anthropic, openai, or gemini", "anthropic").option("--force", "Overwrite existing files").option("--edit-first", "Stop after creating templates for manual editing").action(async (pitch, opts) => {
     console.log("");
     console.log(`${COLORS.cyan}${COLORS.bold}\u26A1 Bootspring Go${COLORS.reset}`);
     console.log(`${COLORS.dim}Setting up your project in one shot...${COLORS.reset}`);
@@ -61890,26 +62030,56 @@ function registerGoCommand(program3) {
       print.dim("  No codebase detected (starting fresh)");
     }
     console.log("");
-    console.log(`${COLORS.bold}[2/5] Seed templates${COLORS.reset}`);
-    if (!fs64.existsSync(contextDir)) {
-      fs64.mkdirSync(contextDir, { recursive: true });
-    }
-    const docs = PRESETS[opts.preset] || PRESETS.startup;
-    let generated = 0;
-    let skipped = 0;
-    for (const docType of docs) {
-      const meta3 = CONTEXT_DOCS[docType];
-      if (!meta3) continue;
-      const filePath = path65.join(contextDir, meta3.name);
-      if (fs64.existsSync(filePath) && !opts.force) {
-        skipped++;
-        continue;
+    if (pitch) {
+      console.log(`${COLORS.bold}[2/5] AI Synthesize${COLORS.reset}`);
+      print.info(`  Pitch: "${pitch}"`);
+      let api;
+      try {
+        const core = await Promise.resolve().then(() => (init_src2(), src_exports2));
+        api = core.api;
+      } catch {
+        print.error("  Failed to load API client. Run `bootspring auth login` first.");
+        print.info("  Falling back to empty templates...");
+        api = null;
       }
-      fs64.writeFileSync(filePath, generateDocTemplate(docType, projectName));
-      generated++;
+      if (api) {
+        try {
+          const result = await api.request("POST", "/seed/synthesize", {
+            pitch,
+            projectName,
+            stack,
+            features,
+            preset: opts.preset,
+            provider: opts.provider
+          }, { timeout: 12e4 });
+          if (result?.documents && Object.keys(result.documents).length > 0) {
+            if (!fs64.existsSync(contextDir)) fs64.mkdirSync(contextDir, { recursive: true });
+            let written = 0;
+            for (const [key, content] of Object.entries(result.documents)) {
+              if (typeof content !== "string") continue;
+              const filePath = path65.join(contextDir, `${key}.md`);
+              if (fs64.existsSync(filePath) && !opts.force) continue;
+              fs64.writeFileSync(filePath, content);
+              written++;
+            }
+            print.success(`  Generated ${written} context doc(s) with AI (${result.metadata?.durationMs || "?"}ms)`);
+          } else {
+            print.warning("  AI returned no documents \u2014 falling back to templates");
+            generateFallbackTemplates(contextDir, opts.preset, projectName, opts.force);
+          }
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          print.warning(`  AI generation failed: ${msg}`);
+          print.info("  Falling back to templates...");
+          generateFallbackTemplates(contextDir, opts.preset, projectName, opts.force);
+        }
+      } else {
+        generateFallbackTemplates(contextDir, opts.preset, projectName, opts.force);
+      }
+    } else {
+      console.log(`${COLORS.bold}[2/5] Seed templates${COLORS.reset}`);
+      generateFallbackTemplates(contextDir, opts.preset, projectName, opts.force);
     }
-    if (generated > 0) print.success(`  Created ${generated} template(s) in ${CONTEXT_DIR}/`);
-    if (skipped > 0) print.dim(`  Skipped ${skipped} (already exist)`);
     console.log("");
     if (opts.editFirst) {
       print.info("Templates created. Edit them, then run:");
@@ -61962,13 +62132,39 @@ function registerGoCommand(program3) {
     console.log("");
     console.log(`${COLORS.green}${COLORS.bold}Setup complete!${COLORS.reset}`);
     console.log("");
-    console.log(`${COLORS.bold}Next:${COLORS.reset}`);
-    console.log("  1. Edit planning/TODO.md with your real tasks");
-    console.log("  2. bootspring build next     # Start the first task");
-    console.log("  3. bootspring build done     # Mark it complete");
+    if (pitch) {
+      console.log(`${COLORS.bold}Next:${COLORS.reset}`);
+      console.log("  1. Review .bootspring/context/ \u2014 tweak anything the AI got wrong");
+      console.log("  2. Edit planning/TODO.md with your real tasks");
+      console.log("  3. bootspring build next     # Start the first task");
+    } else {
+      console.log(`${COLORS.bold}Next:${COLORS.reset}`);
+      console.log('  1. Edit the docs in .bootspring/context/ (or run: bootspring seed synthesize "your idea")');
+      console.log("  2. bootspring seed merge     # Re-merge after edits");
+      console.log("  3. bootspring build next     # Start the first task");
+    }
     console.log("");
   });
 }
+function generateFallbackTemplates(contextDir, preset, projectName, force) {
+  if (!fs64.existsSync(contextDir)) fs64.mkdirSync(contextDir, { recursive: true });
+  const docs = PRESETS[preset] || PRESETS.startup;
+  let generated = 0;
+  let skipped = 0;
+  for (const docType of docs) {
+    const meta3 = CONTEXT_DOCS[docType];
+    if (!meta3) continue;
+    const filePath = path65.join(contextDir, meta3.name);
+    if (fs64.existsSync(filePath) && !force) {
+      skipped++;
+      continue;
+    }
+    fs64.writeFileSync(filePath, generateDocTemplate(docType, projectName));
+    generated++;
+  }
+  if (generated > 0) print.success(`  Created ${generated} template(s) in .bootspring/context/`);
+  if (skipped > 0) print.dim(`  Skipped ${skipped} (already exist)`);
+}
 
 // src/commands/seed.ts
 var CONTEXT_DOCS2 = {
@@ -62478,7 +62674,7 @@ ${COLORS.bold}Detected Features:${COLORS.reset}`);
     console.log("");
     print.info(`${generated} generated, ${skipped} skipped in ${CONTEXT_DIR2}/`);
   });
-  seed.command("merge").alias("synthesize").description("Merge context documents into planning/SEED.md").option("--output <path>", "Output file", "planning/SEED.md").option("--force", "Overwrite existing seed file").action((opts) => {
+  seed.command("merge").description("Merge context documents into planning/SEED.md").option("--output <path>", "Output file", "planning/SEED.md").option("--force", "Overwrite existing seed file").action((opts) => {
     print.header("Seed Merge");
     const cwd = process.cwd();
     const contextDir = getContextDir();
@@ -62744,10 +62940,122 @@ ${COLORS.bold}Detected Features:${COLORS.reset}`);
       print.success("Document looks good!");
     }
   });
+  seed.command("synthesize").alias("ai").description("Generate all context docs from a one-liner pitch using AI").argument("<pitch>", "Your project idea in one sentence").option("--preset <preset>", "Document set (essential, startup, full, technical)", "startup").option("--provider <provider>", "AI provider: anthropic, openai, or gemini", "anthropic").option("--force", "Overwrite existing context docs").option("--json", "Output as JSON").action(async (pitch, opts) => {
+    let api;
+    try {
+      const core = await Promise.resolve().then(() => (init_src2(), src_exports2));
+      api = core.api;
+    } catch {
+      print.error("Failed to load API client. Run `bootspring auth login` first.");
+      return;
+    }
+    const cwd = process.cwd();
+    const contextDir = path66.join(cwd, CONTEXT_DIR2);
+    const { name: projectName, stack, features } = detectStack2(cwd);
+    if (!opts.json) {
+      print.header("Seed Synthesize");
+      print.info(`Pitch: "${pitch}"`);
+      if (stack.length > 0) print.dim(`Stack: ${stack.join(", ")}`);
+      console.log("");
+    }
+    const spinner = opts.json ? null : createSpinner("Generating context docs with AI...").start();
+    try {
+      const result = await api.request("POST", "/seed/synthesize", {
+        pitch,
+        projectName,
+        stack,
+        features,
+        preset: opts.preset,
+        provider: opts.provider
+      }, { timeout: 12e4 });
+      if (!result?.documents || Object.keys(result.documents).length === 0) {
+        spinner?.fail("AI returned no documents");
+        print.error("No documents were generated. Try rephrasing your pitch.");
+        return;
+      }
+      if (!fs65.existsSync(contextDir)) {
+        fs65.mkdirSync(contextDir, { recursive: true });
+      }
+      let written = 0;
+      const writtenFiles = [];
+      for (const [key, content] of Object.entries(result.documents)) {
+        if (typeof content !== "string") continue;
+        const fileName = `${key}.md`;
+        const filePath = path66.join(contextDir, fileName);
+        if (fs65.existsSync(filePath) && !opts.force) {
+          if (!opts.json) print.dim(`  Skipped ${fileName} (exists, use --force)`);
+          continue;
+        }
+        fs65.writeFileSync(filePath, content);
+        written++;
+        writtenFiles.push(fileName);
+      }
+      spinner?.succeed(`Generated ${written} document(s) in ${result.metadata?.durationMs || "?"}ms`);
+      if (opts.json) {
+        console.log(JSON.stringify({
+          documents: result.documents,
+          files: writtenFiles,
+          metadata: result.metadata
+        }, null, 2));
+        return;
+      }
+      console.log("");
+      for (const f of writtenFiles) {
+        print.success(`  ${CONTEXT_DIR2}/${f}`);
+      }
+      if (written > 0) {
+        console.log("");
+        print.info("Merging into planning/SEED.md...");
+        const validDocs = Object.values(CONTEXT_DOCS2).map((d) => d.name);
+        const files = fs65.readdirSync(contextDir).filter((f) => f.endsWith(".md") && f !== "README.md").sort((a, b) => {
+          const ai = validDocs.indexOf(a);
+          const bi = validDocs.indexOf(b);
+          return (ai === -1 ? 999 : ai) - (bi === -1 ? 999 : bi);
+        });
+        if (files.length > 0) {
+          const sections = files.map((f) => fs65.readFileSync(path66.join(contextDir, f), "utf-8"));
+          const planningDir = path66.join(cwd, "planning");
+          if (!fs65.existsSync(planningDir)) fs65.mkdirSync(planningDir, { recursive: true });
+          fs65.writeFileSync(path66.join(planningDir, "SEED.md"), sections.join("\n\n---\n\n"));
+          print.success(`  planning/SEED.md (${files.length} docs merged)`);
+        }
+        const genFiles = runGenerate(cwd, { force: false, full: true });
+        if (genFiles.length > 0) {
+          for (const f of genFiles) {
+            print.success(`  ${f}`);
+          }
+        }
+        const buildResult = initBuildFromSeed(cwd);
+        if (buildResult.initialized) {
+          print.success(`  Build initialized with ${buildResult.taskCount} tasks`);
+        }
+      }
+      console.log("");
+      console.log(`${COLORS.green}${COLORS.bold}Done!${COLORS.reset} Your project context is ready.`);
+      console.log("");
+      console.log(`${COLORS.bold}Next:${COLORS.reset}`);
+      console.log("  1. Review the docs in .bootspring/context/");
+      console.log("  2. Edit planning/TODO.md with your real tasks");
+      console.log("  3. bootspring build next     # Start building");
+    } catch (err) {
+      spinner?.fail("AI generation failed");
+      const message = err instanceof Error ? err.message : String(err);
+      if (message.includes("Cannot connect") || message.includes("ECONNREFUSED")) {
+        print.error("Cannot reach Bootspring API. Check your internet connection.");
+      } else if (message.includes("Authentication") || message.includes("401")) {
+        print.error("Not authenticated. Run `bootspring auth login` first.");
+      } else {
+        print.error(message);
+      }
+    }
+  });
   seed.action(() => {
     seed.outputHelp();
     console.log("");
-    console.log(`${COLORS.bold}Workflow:${COLORS.reset}`);
+    console.log(`${COLORS.bold}Quick start (AI-powered):${COLORS.reset}`);
+    console.log('  bootspring seed synthesize "your project idea"   # AI fills all context docs');
+    console.log("");
+    console.log(`${COLORS.bold}Manual workflow:${COLORS.reset}`);
     console.log("  bootspring seed init         # Create .bootspring/context/ + templates");
     console.log("  (edit/drop files)            # Add your project docs");
     console.log("  bootspring seed merge        # Combine into planning/SEED.md");
@@ -73569,6 +73877,29 @@ ${COLORS.green}Task submitted:${COLORS.reset} ${res.id}`);
       handleError(error50);
     }
   });
+  cmd.command("priority <taskId> <level>").description("Update queued swarm task priority").option("--json", "Output as JSON").action(async (taskId, level, opts) => {
+    if (!requireAuth4()) return;
+    const priority = level.toLowerCase();
+    const valid = ["critical", "high", "normal", "low"];
+    if (!valid.includes(priority)) {
+      print(`${COLORS.red}Invalid priority:${COLORS.reset} ${level}. Must be one of: ${valid.join(", ")}`);
+      return;
+    }
+    try {
+      const res = await api_client_exports.request("PATCH", `/swarm/tasks/${taskId}/priority`, { priority });
+      if (opts.json) {
+        print(JSON.stringify(res, null, 2));
+        return;
+      }
+      print(`
+${COLORS.green}Task priority updated:${COLORS.reset} ${taskId}`);
+      print(`  Priority: ${priority}`);
+      print(`  Status:   ${res.task?.status ?? "queued"}
+`);
+    } catch (error50) {
+      handleError(error50);
+    }
+  });
   cmd.command("plan <goal>").description("Generate a GOAP execution plan from a goal").option("--parallel", "Enable parallel task groups").option("--json", "Output as JSON").action(async (goal, opts) => {
     if (!requireAuth4()) return;
     try {
@@ -78042,40 +78373,45 @@ var import_child_process18 = require("child_process");
 init_src2();
 var HOOK_REGISTRY = {
   SessionStart: [
-    { package: "session-intelligence", script: "packages/session-intelligence/src/features/stats/hooks/session-start.ts" },
-    { package: "session-intelligence", script: "packages/session-intelligence/src/features/suggest/hooks/session-start.ts" },
-    { package: "session-intelligence", script: "packages/session-intelligence/src/features/recall/hooks/session-start.ts" }
+    { feature: "stats", script: "packages/session-intelligence/src/features/stats/hooks/session-start.ts" },
+    { feature: "suggest", script: "packages/session-intelligence/src/features/suggest/hooks/session-start.ts" },
+    { feature: "recall", script: "packages/session-intelligence/src/features/recall/hooks/session-start.ts" }
   ],
   UserPromptSubmit: [
-    { package: "session-intelligence", script: "packages/session-intelligence/src/features/stats/hooks/user-prompt-submit.ts" },
-    { package: "session-intelligence", script: "packages/session-intelligence/src/features/suggest/hooks/user-prompt-submit.ts" },
-    { package: "session-intelligence", script: "packages/session-intelligence/src/features/recall/hooks/prompt-submit.ts" }
+    { feature: "stats", script: "packages/session-intelligence/src/features/stats/hooks/user-prompt-submit.ts" },
+    { feature: "suggest", script: "packages/session-intelligence/src/features/suggest/hooks/user-prompt-submit.ts" },
+    { feature: "recall", script: "packages/session-intelligence/src/features/recall/hooks/prompt-submit.ts" }
   ],
   PreToolUse: [
-    { package: "session-intelligence", script: "packages/session-intelligence/src/features/suggest/hooks/pre-tool-use.ts" },
-    { package: "session-intelligence", script: "packages/session-intelligence/src/features/recall/hooks/pre-tool-use.ts" }
+    { feature: "suggest", script: "packages/session-intelligence/src/features/suggest/hooks/pre-tool-use.ts" },
+    { feature: "recall", script: "packages/session-intelligence/src/features/recall/hooks/pre-tool-use.ts" }
   ],
   PostToolUse: [
-    { package: "session-intelligence", script: "packages/session-intelligence/src/features/stats/hooks/post-tool-use.ts" },
-    { package: "session-intelligence", script: "packages/session-intelligence/src/features/suggest/hooks/post-tool-use.ts" }
+    { feature: "stats", script: "packages/session-intelligence/src/features/stats/hooks/post-tool-use.ts" },
+    { feature: "suggest", script: "packages/session-intelligence/src/features/suggest/hooks/post-tool-use.ts" }
   ],
   PreCompact: [
-    { package: "session-intelligence", script: "packages/session-intelligence/src/features/stats/hooks/pre-compact.ts" }
+    { feature: "stats", script: "packages/session-intelligence/src/features/stats/hooks/pre-compact.ts" }
   ],
   SubagentStart: [
-    { package: "session-intelligence", script: "packages/session-intelligence/src/features/stats/hooks/subagent-start.ts" }
+    { feature: "stats", script: "packages/session-intelligence/src/features/stats/hooks/subagent-start.ts" }
   ],
   SubagentStop: [
-    { package: "session-intelligence", script: "packages/session-intelligence/src/features/stats/hooks/subagent-stop.ts" }
+    { feature: "stats", script: "packages/session-intelligence/src/features/stats/hooks/subagent-stop.ts" }
   ],
   SessionEnd: [
-    { package: "session-intelligence", script: "packages/session-intelligence/src/features/stats/hooks/session-end.ts" },
-    { package: "session-intelligence", script: "packages/session-intelligence/src/features/suggest/hooks/session-end.ts" },
-    { package: "session-intelligence", script: "packages/session-intelligence/src/features/recall/hooks/stop.ts" }
+    { feature: "stats", script: "packages/session-intelligence/src/features/stats/hooks/session-end.ts" },
+    { feature: "suggest", script: "packages/session-intelligence/src/features/suggest/hooks/session-end.ts" },
+    { feature: "recall", script: "packages/session-intelligence/src/features/recall/hooks/stop.ts" }
   ]
 };
 var ALL_EVENTS = Object.keys(HOOK_REGISTRY);
-var SETTINGS_FILE = ".claude/settings.local.json";
+var CLAUDE_SETTINGS_FILE = ".claude/settings.local.json";
+var CODEX_HOOKS_FILE = ".codex/hooks.json";
+var HOOK_TARGETS = [
+  { id: "claude", label: "Claude", file: CLAUDE_SETTINGS_FILE },
+  { id: "codex", label: "Codex", file: CODEX_HOOKS_FILE }
+];
 function findMonorepoRoot(cwd) {
   let dir = cwd;
   for (let i = 0; i < 10; i++) {
@@ -78086,19 +78422,27 @@ function findMonorepoRoot(cwd) {
   }
   return null;
 }
-function readSettings(cwd) {
-  const settingsPath = path107.join(cwd, SETTINGS_FILE);
-  if (!fs106.existsSync(settingsPath)) return {};
+function readJsonFile(cwd, relPath) {
+  const filePath = path107.join(cwd, relPath);
+  if (!fs106.existsSync(filePath)) return {};
   try {
-    return JSON.parse(fs106.readFileSync(settingsPath, "utf8"));
+    return JSON.parse(fs106.readFileSync(filePath, "utf8"));
   } catch {
     return {};
   }
 }
-function writeSettings(cwd, settings) {
-  const dir = path107.join(cwd, ".claude");
+function writeJsonFile(cwd, relPath, data) {
+  const dir = path107.dirname(path107.join(cwd, relPath));
   if (!fs106.existsSync(dir)) fs106.mkdirSync(dir, { recursive: true });
-  fs106.writeFileSync(path107.join(cwd, SETTINGS_FILE), JSON.stringify(settings, null, 2) + "\n");
+  fs106.writeFileSync(path107.join(cwd, relPath), JSON.stringify(data, null, 2) + "\n");
+}
+function installHooksForTarget(cwd, relPath, hooksConfig) {
+  const settings = readJsonFile(cwd, relPath);
+  settings.hooks = hooksConfig;
+  writeJsonFile(cwd, relPath, settings);
+}
+function hookEntriesUseDispatcher(entries) {
+  return JSON.stringify(entries || "").includes("hook dispatch");
 }
 function buildDispatcherCommand(monorepoRoot) {
   const cliEntry = path107.join(monorepoRoot, "monorepo/apps/cli/bin/bootspring.js");
@@ -78152,7 +78496,7 @@ async function dispatchEvent(event) {
       });
     } catch (err) {
       const msg = err.stderr?.toString?.().slice(0, 200) || err.message || "unknown error";
-      process.stderr.write(`[hook-dispatcher] ${handler.package}/${path107.basename(handler.script)} failed: ${msg}
+      process.stderr.write(`[hook-dispatcher] ${handler.feature}/${path107.basename(handler.script)} failed: ${msg}
 `);
     }
   }
@@ -78181,8 +78525,8 @@ function readStdinPayload() {
   });
 }
 function registerHookCommand(program3) {
-  const hook = program3.command("hook").description("Manage Claude Code hook dispatcher (observer \u2192 autopilot \u2192 memory)");
-  hook.command("install").description("Write deterministic hook config to .claude/settings.local.json").option("--dry-run", "Show what would be written without modifying files").action((opts) => {
+  const hook = program3.command("hook").description("Manage Bootspring hook dispatcher for Claude Code and Codex (stats \u2192 suggest \u2192 recall)");
+  hook.command("install").description("Write deterministic hook config to Claude and Codex settings").option("--dry-run", "Show what would be written without modifying files").action((opts) => {
     const cwd = process.cwd();
     const monorepoRoot = findMonorepoRoot(cwd);
     if (!monorepoRoot) {
@@ -78196,17 +78540,19 @@ function registerHookCommand(program3) {
       console.log(`
 ${COLORS.bold}Hook config (dry run):${COLORS.reset}
 `);
-      console.log(JSON.stringify({ hooks: hooksConfig }, null, 2));
+      console.log(JSON.stringify(Object.fromEntries(
+        HOOK_TARGETS.map((target) => [target.file, { hooks: hooksConfig }])
+      ), null, 2));
       console.log(`
-${COLORS.dim}${ALL_EVENTS.length} events, ${totalHandlers} handlers, ordering: observer \u2192 autopilot \u2192 memory${COLORS.reset}
+${COLORS.dim}${ALL_EVENTS.length} events, ${totalHandlers} handlers, ordering: stats \u2192 suggest \u2192 recall${COLORS.reset}
 `);
       return;
     }
-    const settings = readSettings(monorepoRoot);
-    settings.hooks = hooksConfig;
-    writeSettings(monorepoRoot, settings);
-    print.success(`Wrote ${ALL_EVENTS.length} hook events (${totalHandlers} handlers) to ${SETTINGS_FILE}`);
-    console.log(`  ${COLORS.dim}Ordering: observer \u2192 autopilot \u2192 memory (deterministic)${COLORS.reset}`);
+    for (const target of HOOK_TARGETS) {
+      installHooksForTarget(monorepoRoot, target.file, hooksConfig);
+    }
+    print.success(`Wrote ${ALL_EVENTS.length} hook events (${totalHandlers} handlers) to ${HOOK_TARGETS.map((t) => t.file).join(" and ")}`);
+    console.log(`  ${COLORS.dim}Ordering: stats \u2192 suggest \u2192 recall (deterministic)${COLORS.reset}`);
     console.log(`  ${COLORS.dim}Error isolation: each handler runs in its own subprocess${COLORS.reset}`);
     console.log(`  ${COLORS.dim}Events: ${ALL_EVENTS.join(", ")}${COLORS.reset}
 `);
@@ -78214,45 +78560,54 @@ ${COLORS.dim}${ALL_EVENTS.length} events, ${totalHandlers} handlers, ordering: o
   hook.command("status").description("Show installed hook configuration").action(() => {
     const cwd = process.cwd();
     const monorepoRoot = findMonorepoRoot(cwd) || cwd;
-    const settings = readSettings(monorepoRoot);
-    const hooks = settings.hooks || {};
+    const targetStates = HOOK_TARGETS.map((target) => ({
+      ...target,
+      hooks: readJsonFile(monorepoRoot, target.file).hooks || {}
+    }));
     console.log(`
 ${COLORS.bold}Hook Status${COLORS.reset}
 `);
-    if (Object.keys(hooks).length === 0) {
-      print.warning("No hooks configured in .claude/settings.local.json");
+    if (targetStates.every((target) => Object.keys(target.hooks).length === 0)) {
+      print.warning(`No hooks configured in ${HOOK_TARGETS.map((t) => t.file).join(" or ")}`);
       print.dim('Run "bootspring hook install" to set up the deterministic dispatcher.');
       console.log();
       return;
     }
-    const isDispatcher = JSON.stringify(hooks).includes("hook dispatch");
     for (const event of ALL_EVENTS) {
-      const entries = hooks[event];
+      const installedTargets = targetStates.filter((target) => hookEntriesUseDispatcher(target.hooks[event]));
       const registry4 = HOOK_REGISTRY[event];
-      const mark = entries ? `${COLORS.green}\u2713${COLORS.reset}` : `${COLORS.dim}\xB7${COLORS.reset}`;
-      const handlers = registry4.map((h) => `${COLORS.cyan}${h.package}${COLORS.reset}`).join(" \u2192 ");
-      console.log(`  ${mark} ${COLORS.bold}${event.padEnd(20)}${COLORS.reset} ${handlers}`);
+      const mark = installedTargets.length === HOOK_TARGETS.length ? `${COLORS.green}\u2713${COLORS.reset}` : `${COLORS.yellow}!${COLORS.reset}`;
+      const handlers = registry4.map((h) => `${COLORS.cyan}${h.feature}${COLORS.reset}`).join(" \u2192 ");
+      const targetLabels = installedTargets.map((t) => t.label).join(", ") || "none";
+      console.log(`  ${mark} ${COLORS.bold}${event.padEnd(20)}${COLORS.reset} ${handlers} ${COLORS.dim}(${targetLabels})${COLORS.reset}`);
     }
     console.log();
-    if (isDispatcher) {
-      print.success("Using centralized dispatcher with deterministic ordering.");
-    } else {
-      print.warning("Hooks are configured but not using the centralized dispatcher.");
-      print.dim('Run "bootspring hook install" to switch to the deterministic dispatcher.');
+    for (const target of targetStates) {
+      const isDispatcher = ALL_EVENTS.every((event) => hookEntriesUseDispatcher(target.hooks[event]));
+      if (isDispatcher) {
+        print.success(`${target.label}: using centralized dispatcher (${target.file}).`);
+      } else {
+        print.warning(`${target.label}: hooks are missing or not using the centralized dispatcher (${target.file}).`);
+      }
     }
     console.log();
   });
-  hook.command("uninstall").description("Remove all hook entries from .claude/settings.local.json").action(() => {
+  hook.command("uninstall").description("Remove all hook entries from Claude and Codex settings").action(() => {
     const cwd = process.cwd();
     const monorepoRoot = findMonorepoRoot(cwd) || cwd;
-    const settings = readSettings(monorepoRoot);
-    if (!settings.hooks) {
+    let removed = 0;
+    for (const target of HOOK_TARGETS) {
+      const settings = readJsonFile(monorepoRoot, target.file);
+      if (!settings.hooks) continue;
+      delete settings.hooks;
+      writeJsonFile(monorepoRoot, target.file, settings);
+      removed++;
+    }
+    if (removed === 0) {
       print.info("No hooks configured \u2014 nothing to remove.");
       return;
     }
-    delete settings.hooks;
-    writeSettings(monorepoRoot, settings);
-    print.success("Removed all hook entries from .claude/settings.local.json");
+    print.success(`Removed hook entries from ${removed} assistant config file(s).`);
   });
   hook.command("dispatch <event>").description("(internal) Dispatch a hook event to handlers in order").action(async (event) => {
     await dispatchEvent(event);
@@ -78272,6 +78627,7 @@ var SUBCOMMANDS = {
   auth: ["login", "logout", "whoami", "status", "clear", "register", "switch", "reauth"],
   build: [
     "status",
+    "progress",
     "task",
     "done",
     "plan",

package/dist/core/index.d.ts

@@ -477,7 +477,7 @@ interface InstallContext {
     scriptPath: string;
 }
 declare const PACKAGE_NAME = "@girardmedia/bootspring";
-declare const CURRENT_VERSION = "3.1.0";
+declare const CURRENT_VERSION = "3.2.0";
 declare const DEFAULT_INTERVAL_MS: number;
 declare const STATE_PATH: string;
 declare function compareVersions(a: string, b: string): number;

package/dist/core.js

@@ -379,7 +379,7 @@ var init_release = __esm({
   "../../packages/shared/src/release.ts"() {
     "use strict";
     init_cjs_shims();
-    BOOTSPRING_VERSION = "3.1.0";
+    BOOTSPRING_VERSION = "3.2.0";
     BOOTSPRING_PACKAGE_NAME = "@girardmedia/bootspring";
   }
 });
@@ -21643,7 +21643,7 @@ ${COLORS2.dim}Run "bootspring mcp" for server options${COLORS2.reset}
       console.log(`${COLORS2.dim}Run "bootspring mcp" for setup instructions.${COLORS2.reset}
 `);
     }
-    var BOOTSPRING_VERSION2 = "3.1.0";
+    var BOOTSPRING_VERSION2 = "3.2.0";
     var BOOTSPRING_PACKAGE_NAME2 = "@girardmedia/bootspring";
     var REDACTED2 = "[REDACTED]";
     var SENSITIVE_KEY_PATTERN2 = /(?:^|[_-])(api[_-]?key|token|refresh[_-]?token|authorization|x[_-]?api[_-]?key|project[_-]?id)$/i;
@@ -21691,7 +21691,7 @@ var require_package = __commonJS({
   "../../../package.json"(exports2, module2) {
     module2.exports = {
       name: "bootspring-workspace",
-      version: "3.1.0",
+      version: "3.2.0",
       private: true,
       description: "Workspace tooling for the Bootspring monorepo",
       keywords: [

package/dist/mcp-server.js

@@ -31464,7 +31464,7 @@ var init_release = __esm({
   "../../packages/shared/src/release.ts"() {
     "use strict";
     init_cjs_shims();
-    BOOTSPRING_VERSION = "3.1.0";
+    BOOTSPRING_VERSION = "3.2.0";
     BOOTSPRING_PACKAGE_NAME = "@girardmedia/bootspring";
   }
 });
@@ -52365,7 +52365,7 @@ var require_package = __commonJS({
   "../../../package.json"(exports2, module2) {
     module2.exports = {
       name: "bootspring-workspace",
-      version: "3.1.0",
+      version: "3.2.0",
       private: true,
       description: "Workspace tooling for the Bootspring monorepo",
       keywords: [
@@ -52503,6 +52503,15 @@ var core = require_dist2();
 var api2 = core.api;
 var auth2 = core.auth;
 var VERSION = require_package().version;
+var BUILD_PROGRESS_ARTIFACT = "planning/BUILD_PROGRESS.md";
+var VISIBLE_WORK_CHECKPOINTS = [
+  "Announce the active task and intended checkpoints in the chat or terminal.",
+  "Inspect the relevant files and summarize what changed before editing.",
+  "Patch the implementation and keep unrelated files untouched.",
+  "Add or update focused tests when the task changes behavior.",
+  "Run the relevant verification commands and report pass/fail output.",
+  "Update the build state with action=done only after verification."
+];
 function getProjectRoot() {
   return process.cwd();
 }
@@ -52579,6 +52588,70 @@ function formatBuildTask(task) {
     dependencies: task.dependencies || []
   };
 }
+function renderVisibleProgressBar(percent, width = 30) {
+  const clamped = Math.max(0, Math.min(100, Math.round(percent || 0)));
+  const filled = Math.round(clamped / 100 * width);
+  return `[${"#".repeat(filled)}${".".repeat(width - filled)}] ${clamped}%`;
+}
+function writeVisibleProgressArtifact(task, stats, event) {
+  const fs3 = require("fs");
+  const path3 = require("path");
+  const artifactPath = path3.join(getProjectRoot(), BUILD_PROGRESS_ARTIFACT);
+  const progress = {
+    completed: stats?.completed || 0,
+    pending: stats?.pending || 0,
+    inProgress: stats?.inProgress || 0,
+    total: stats?.total || 0,
+    percent: stats?.percent || 0
+  };
+  const taskData = formatBuildTask(task);
+  fs3.mkdirSync(path3.dirname(artifactPath), { recursive: true });
+  fs3.writeFileSync(artifactPath, [
+    "# Build Progress",
+    "",
+    `Updated: ${(/* @__PURE__ */ new Date()).toISOString()}`,
+    `Event: ${event}`,
+    `Overall: ${progress.completed}/${progress.total} ${renderVisibleProgressBar(progress.percent)}`,
+    "",
+    "## Active Task",
+    "",
+    taskData ? [
+      `- ID: ${taskData.id}`,
+      `- Title: ${taskData.title}`,
+      `- Phase: ${taskData.phase || "Unknown"}`,
+      taskData.description ? `- Description: ${taskData.description}` : null,
+      taskData.dependencies?.length ? `- Dependencies: ${taskData.dependencies.join(", ")}` : null
+    ].filter(Boolean).join("\n") : "No active or pending task.",
+    "",
+    "## Acceptance Criteria",
+    "",
+    taskData?.acceptanceCriteria?.length ? taskData.acceptanceCriteria.map((item) => `- [ ] ${item}`).join("\n") : "- [ ] No task-specific acceptance criteria recorded.",
+    "",
+    "## Visible Work Contract",
+    "",
+    VISIBLE_WORK_CHECKPOINTS.map((item) => `- [ ] ${item}`).join("\n"),
+    "",
+    "## Host Notes",
+    "",
+    "- Claude Code and Codex CLI can stream terminal output directly.",
+    "- Codex Desktop, Claude Desktop, and other MCP hosts should keep a visible plan/checklist updated while the terminal is hidden.",
+    "- Update this file after inspection, edits, verification, and completion so the workspace has a durable progress surface.",
+    ""
+  ].join("\n"));
+  return BUILD_PROGRESS_ARTIFACT;
+}
+function buildVisibilityContract(task, stats, event) {
+  const artifact = writeVisibleProgressArtifact(task, stats, event);
+  return {
+    artifact,
+    checkpoints: VISIBLE_WORK_CHECKPOINTS,
+    hostInstructions: [
+      "Immediately show the active task and a short visible checklist to the user.",
+      "Post visible updates after inspection, implementation, verification, and completion.",
+      `Keep ${artifact} current when the host hides terminal output.`
+    ]
+  };
+}
 function autoCommitTask(taskId, taskTitle) {
   try {
     const { execSync } = require("child_process");
@@ -52685,6 +52758,7 @@ async function executeLocalBuild(args) {
         status: state.status,
         progress: { completed: stats.completed, pending: stats.pending, inProgress: stats.inProgress, total: stats.total, percent: stats.percent },
         currentTask: currentTask ? { id: currentTask.id, title: currentTask.title } : null,
+        visibility: buildVisibilityContract(currentTask, stats, "status"),
         nextAction: currentTask ? "Complete the current task, then use action=done" : "Use action=next to get the next task"
       }, null, 2) }] };
     }
@@ -52698,6 +52772,7 @@ async function executeLocalBuild(args) {
           message: "Task already in progress",
           state: "in_progress",
           task: formatBuildTask(inProgress),
+          visibility: buildVisibilityContract(inProgress, buildGetStats(state), "already_in_progress"),
           hint: "Complete this task with action=done, or use action=skip to skip it"
         }, null, 2) }] };
       }
@@ -52714,6 +52789,7 @@ async function executeLocalBuild(args) {
         state: "task_ready",
         file: "planning/TODO.md",
         progress: { completed: stats.completed, total: stats.total, percent: stats.percent },
+        visibility: buildVisibilityContract(nextTask, stats, "task_ready"),
         instructions: [
           `Find ${nextTask.id} in planning/TODO.md for full details`,
           "Implement the task in the codebase",
@@ -52734,6 +52810,7 @@ async function executeLocalBuild(args) {
       }
       return { content: [{ type: "text", text: JSON.stringify({
         task: formatBuildTask(currentTask),
+        visibility: buildVisibilityContract(currentTask, buildGetStats(state), "current"),
         instructions: ["Implement this task in the codebase", "Run quality checks (lint, test)", "Commit your changes", "Use action=done to mark complete"]
       }, null, 2) }] };
     }
@@ -52762,6 +52839,7 @@ async function executeLocalBuild(args) {
         nextTask: nextTask ? { ...formatBuildTask(nextTask), file: "planning/TODO.md" } : null,
         allComplete: !nextTask,
         state: nextTask ? "advanced" : "all_complete",
+        visibility: buildVisibilityContract(nextTask, stats, nextTask ? "advanced" : "all_complete"),
         message: nextTask ? `Done! Committed ${inProgress.id}. Next: ${nextTask.id} \u2014 ${nextTask.title}` : "Build complete! All tasks finished."
       }, null, 2) }] };
     }
@@ -52782,6 +52860,7 @@ async function executeLocalBuild(args) {
       return { content: [{ type: "text", text: JSON.stringify({
         skipped: { id: inProgress.id, title: inProgress.title, reason: args?.reason || "Skipped" },
         nextTask: nextTask ? formatBuildTask(nextTask) : null,
+        visibility: buildVisibilityContract(nextTask, buildGetStats(state), nextTask ? "skipped_next_ready" : "skipped_all_done"),
         message: nextTask ? `Skipped. Next: ${nextTask.title}` : "No more tasks available"
       }, null, 2) }] };
     }
@@ -52807,13 +52886,14 @@ async function executeLocalBuild(args) {
               const nextTask2 = buildGetNextTask(state);
               if (nextTask2) buildUpdateTaskStatus(state, nextTask2.id, "in_progress");
               saveBuildState(state);
-              const stats = buildGetStats(state);
+              const stats2 = buildGetStats(state);
               return { content: [{ type: "text", text: JSON.stringify({
                 state: nextTask2 ? "advanced" : "all_complete",
                 autoCompleted: true,
                 completed: { id: activeTask.id, title: activeTask.title },
                 nextTask: nextTask2 ? formatBuildTask(nextTask2) : null,
-                progress: { completed: stats.completed, total: stats.total, percent: stats.percent }
+                progress: { completed: stats2.completed, total: stats2.total, percent: stats2.percent },
+                visibility: buildVisibilityContract(nextTask2, stats2, nextTask2 ? "advanced" : "all_complete")
               }, null, 2) }] };
             }
           } catch {
@@ -52822,20 +52902,23 @@ async function executeLocalBuild(args) {
         return { content: [{ type: "text", text: JSON.stringify({
           state: "in_progress",
           task: formatBuildTask(activeTask),
+          visibility: buildVisibilityContract(activeTask, buildGetStats(state), "in_progress"),
           hint: "Finish implementation and use action=done, or call action=advance with autoDone=true after commit"
         }, null, 2) }] };
       }
       const nextTask = buildGetNextTask(state);
       if (!nextTask) {
-        const stats = buildGetStats(state);
-        return { content: [{ type: "text", text: JSON.stringify({ state: "all_complete", message: "All tasks complete!", progress: { completed: stats.completed, total: stats.total, percent: stats.percent } }, null, 2) }] };
+        const stats2 = buildGetStats(state);
+        return { content: [{ type: "text", text: JSON.stringify({ state: "all_complete", message: "All tasks complete!", progress: { completed: stats2.completed, total: stats2.total, percent: stats2.percent }, visibility: buildVisibilityContract(null, stats2, "all_complete") }, null, 2) }] };
       }
       buildUpdateTaskStatus(state, nextTask.id, "in_progress");
       saveBuildState(state);
+      const stats = buildGetStats(state);
       return { content: [{ type: "text", text: JSON.stringify({
         state: "task_ready",
         task: formatBuildTask(nextTask),
         file: "planning/TODO.md",
+        visibility: buildVisibilityContract(nextTask, stats, "task_ready"),
         hint: "Implement task, then call action=advance (or action=done) to continue loop"
       }, null, 2) }] };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@girardmedia/bootspring",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Thin client for Bootspring cloud MCP, hosted agents, and paywalled workflow intelligence",
   "keywords": [
     "ai",