conductor-board 2.1.0 → 2.2.0

package/bin/cli.js

@@ -44,7 +44,9 @@ const HELP = `
     gate <id> <state>        checking | passed | failed
     heartbeat <id> "note"    Append a heartbeat (--iteration, --insight-type,
                              --insight-seed, --final, --to <step>)
-    suggest "title"          Add a post-run suggestion (--type, --step, --rationale)
+    suggest "title" --scope SC    Append a learning to the conductor's knowledge:
+    knowledge [--min N]      List knowledge / gate on captured-learnings count
+    loop-scope <loop> <item...>   Frontload every iteration as pending (scope beat)
     loop <loop> <item> <sub> <state>   Update a loop sub-step
     complete <step>[::iter::sub] [--attest-soft]   Run hard gates, then advance
 
@@ -52,8 +54,8 @@ const HELP = `
     --path, -p <file>        Path to status.json   (default: .conductor/status.json)
     --conductor, -c <file>   Path to the conductor  (default: auto-discovered)
     --port <n>               Port to serve on        (default: 3042)
-                             (the board always opens your browser — set
-                             CONDUCTOR_NO_OPEN=1 to suppress in CI/headless)
+    --headless               Don't open a browser (CI / cloud / no display).
+                             Same as CONDUCTOR_HEADLESS=1. Default: opens.
 
   init options
     --name, -n <name>        Workflow name (skips the prompts)
@@ -111,15 +113,17 @@ if (command === "clean") {
 }
 
 // status-writer commands (for agents — keep the board live as you work)
-if (["step", "gate", "heartbeat", "loop", "status-init", "suggest"].includes(command)) {
+if (["step", "gate", "heartbeat", "loop", "loop-scope", "status-init", "suggest", "knowledge"].includes(command)) {
   const w = await import("../cli/writer.js");
   const fn = {
     step: w.runStep,
     gate: w.runGate,
     heartbeat: w.runHeartbeat,
     loop: w.runLoop,
+    "loop-scope": w.runLoopScope,
     "status-init": w.runStatusInit,
     suggest: w.runSuggest,
+    knowledge: w.runKnowledge,
   }[command];
   process.exit((await fn(rest)) ? 0 : 1);
 }
@@ -139,9 +143,10 @@ const statusPath = String(flag(["--path", "-p"], ".conductor/status.json"));
 const conductorArg = flag(["--conductor", "-c"], null);
 const conductorPath = conductorArg ? path.resolve(process.cwd(), String(conductorArg)) : null;
 const wantedPort = Number(flag(["--port"], 3042)) || 3042;
-// The board always opens the browser — it's meant to be seen. CI/headless can
-// suppress at the OS level via the CONDUCTOR_NO_OPEN env var (no --no-open flag).
-const noOpen = process.env.CONDUCTOR_NO_OPEN === "1";
+// The board always opens the browser — it's meant to be seen. --headless (or
+// CONDUCTOR_HEADLESS=1) suppresses it for CI / cloud / no-display environments.
+// The name signals "I have no display", not "I don't want to look".
+const headless = argv.includes("--headless") || process.env.CONDUCTOR_HEADLESS === "1";
 
 function openBrowser(url) {
   const cmd =
@@ -210,6 +215,23 @@ function pidAlive(pid) {
   }
 }
 
+// Probe a recorded board's /health endpoint — distinguishes a live, serving
+// board (reuse it) from a wedged pid that holds the port but isn't responding.
+async function boardHealthy(url) {
+  if (!url) return false;
+  try {
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), 1200);
+    const r = await fetch(`${url}/health`, { signal: ctrl.signal });
+    clearTimeout(t);
+    if (!r.ok) return false;
+    const body = await r.json().catch(() => null);
+    return !!body && body.status === "ok";
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Before binding a port, look for a board already serving this project.
  *
@@ -246,12 +268,22 @@ async function preflightStaleBoard(serverJsonPath) {
     return null;
   }
 
-  const reuse = {
-    reuse: true,
-    pid,
-    url: info.url || `http://localhost:${info.port ?? "?"}`,
-    when: info.started_at ? ago(info.started_at) : "",
-  };
+  const url = info.url || `http://localhost:${info.port ?? "?"}`;
+  const reuse = { reuse: true, pid, url, when: info.started_at ? ago(info.started_at) : "" };
+
+  // Alive but unhealthy (wedged — holds the port but /health doesn't answer):
+  // kill it and start fresh, so a hung board can't block a clean restart (§4.6).
+  if (!(await boardHealthy(url))) {
+    try {
+      process.kill(pid, "SIGTERM");
+    } catch {
+      /* may have just exited */
+    }
+    await new Promise((r) => setTimeout(r, 600));
+    clear();
+    console.log(amber(`\n  ⚠ board pid ${pid} was unresponsive — stopped it and starting fresh.`));
+    return null;
+  }
 
   // Non-interactive (an agent, a script): never duplicate — reuse silently.
   if (!process.stdin.isTTY) return reuse;
@@ -310,7 +342,24 @@ if (resolvedConductor) {
 console.log(`  ${dim("press ctrl+c to stop")}`);
 console.log("");
 
-if (!noOpen) openBrowser(url);
+if (!headless) openBrowser(url);
+
+// Subdirectory convention (§4.7): warn if a flat .conductor/status.json is in
+// use. One workflow per .conductor/<name>/ keeps history and insights separate.
+try {
+  const flat = path.resolve(process.cwd(), ".conductor", "status.json");
+  if (path.resolve(absStatus) === flat && fs.existsSync(flat)) {
+    console.log(
+      amber("  ⚠ flat .conductor/status.json detected") +
+        dim(" — the convention is .conductor/<workflow-name>/. It still works,") +
+        "\n" +
+        dim("    but subdirectories keep each workflow's history + insights separate."),
+    );
+    console.log("");
+  }
+} catch {
+  /* advisory only */
+}
 
 function shutdown() {
   try {
@@ -324,3 +373,4 @@ function shutdown() {
 
 process.on("SIGINT", shutdown);
 process.on("SIGTERM", shutdown);
+process.on("SIGQUIT", shutdown);

package/cli/complete.js

@@ -41,13 +41,24 @@ function discoverConductor(statusPath, explicit) {
  * with gate_detail tagging each criterion 🔒 verified (CLI ran it) or ✋ attested.
  */
 export async function runComplete(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log(
+      "usage: conductor-board complete <step-id> [--attest-soft]\n" +
+        "       conductor-board complete <loop-id>::<iteration>::<sub-step> [--attest-soft]\n\n" +
+        "  Runs the step's HARD gates independently (you can't fake them — the board\n" +
+        "  shows 🔒 verified vs ✋ attested) and only advances when they pass.\n" +
+        "  The :: form resolves a loop sub-step inside the conductor's loop definition.\n" +
+        "  --attest-soft: mark the soft gates as attested once you've verified them.",
+    );
+    return true;
+  }
   const p = flag(args, ["--path", "-p"]);
   const statusPath = path.resolve(process.cwd(), typeof p === "string" ? p : ".conductor/status.json");
   const stepId = args.find((a) => !a.startsWith("-"));
   const attestSoft = args.includes("--attest-soft");
 
   if (!stepId) {
-    console.error(red("usage: conductor-board complete <step-id> [--attest-soft]"));
+    console.error(red("usage: conductor-board complete <step-id>[::iter::sub] [--attest-soft]"));
     return false;
   }
 

package/cli/knowledge.js

@@ -0,0 +1,109 @@
+import fs from "node:fs";
+import path from "node:path";
+import yaml from "js-yaml";
+import { validateConductor } from "./validate.js";
+
+export const SCOPES = ["this-conductor", "upstream", "template", "tooling", "corpus"];
+
+/** Find the conductor file paired with a status.json. */
+export function discoverConductor(statusPath, explicit) {
+  if (explicit) {
+    const p = path.resolve(process.cwd(), explicit);
+    return fs.existsSync(p) ? p : null;
+  }
+  const dir = path.dirname(statusPath);
+  for (const c of ["conductor.yaml", "conductor.yml"]) {
+    const p = path.join(dir, c);
+    if (fs.existsSync(p)) return p;
+  }
+  if (fs.existsSync(dir)) {
+    const y = fs.readdirSync(dir).find((f) => f.endsWith(".yaml") || f.endsWith(".yml"));
+    if (y) return path.join(dir, y);
+  }
+  for (const c of ["conductor.yaml", "conductor.yml"]) {
+    const p = path.resolve(process.cwd(), c);
+    if (fs.existsSync(p)) return p;
+  }
+  return null;
+}
+
+const norm = (s) => String(s || "").trim().toLowerCase().replace(/\s+/g, " ");
+
+/**
+ * The status a knowledge entry should hold given its evidence (§10.3):
+ *   1 observation → emerging · 3+ → proven (this-conductor) · applied is sticky.
+ * Cross-cutting scopes can't be auto-applied, so they sit at `open`.
+ */
+export function statusFor(entry) {
+  if (entry.status === "applied") return "applied";
+  if (entry.scope && entry.scope !== "this-conductor") return "open";
+  return (entry.observed || 1) >= 3 ? "proven" : "emerging";
+}
+
+/** Merge one learning into a conductor doc's knowledge array (in place). */
+export function mergeKnowledge(doc, entry) {
+  doc.knowledge = Array.isArray(doc.knowledge) ? doc.knowledge : [];
+  const existing = doc.knowledge.find(
+    (k) => k && typeof k === "object" && norm(k.title) === norm(entry.title),
+  );
+  if (existing) {
+    existing.observed = (existing.observed || 1) + 1;
+    if (entry.scope) existing.scope = entry.scope;
+    if (entry.step) existing.step = entry.step;
+    if (entry.type) existing.type = entry.type;
+    if (entry.current) existing.current = entry.current;
+    if (entry.proposed) existing.proposed = entry.proposed;
+    if (entry.note) existing.note = entry.note;
+    existing.status = statusFor(existing);
+    return existing;
+  }
+  const fresh = {
+    title: entry.title,
+    scope: entry.scope || "this-conductor",
+    observed: entry.observed || 1,
+    ...(entry.step ? { step: entry.step } : {}),
+    ...(entry.type ? { type: entry.type } : {}),
+    ...(entry.current ? { current: entry.current } : {}),
+    ...(entry.proposed ? { proposed: entry.proposed } : {}),
+    ...(entry.note ? { note: entry.note } : {}),
+  };
+  fresh.status = statusFor(fresh);
+  doc.knowledge.push(fresh);
+  return fresh;
+}
+
+/** Read + parse a conductor file. Throws on parse error. */
+export function loadConductor(conductorPath) {
+  return yaml.load(fs.readFileSync(conductorPath, "utf8")) || {};
+}
+
+/**
+ * Write a conductor doc back, with a single rolling backup and a re-validation.
+ * Returns { ok, error } — never throws.
+ */
+export function saveConductor(conductorPath, doc) {
+  const errors = validateConductor(doc);
+  if (errors.length) return { ok: false, error: `would be invalid: ${errors[0]}` };
+  try {
+    fs.writeFileSync(`${conductorPath}.bak`, fs.readFileSync(conductorPath, "utf8"));
+  } catch {
+    /* backup is best-effort */
+  }
+  try {
+    fs.writeFileSync(conductorPath, yaml.dump(doc, { lineWidth: 100 }));
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+}
+
+/** Count knowledge entries (optionally filtered by status/scope). */
+export function knowledgeCount(doc, { status, scope } = {}) {
+  const k = Array.isArray(doc.knowledge) ? doc.knowledge : [];
+  return k.filter(
+    (e) =>
+      e &&
+      (!status || (e.status || "emerging") === status) &&
+      (!scope || (e.scope || "this-conductor") === scope),
+  ).length;
+}

package/cli/setup.js

@@ -28,8 +28,8 @@ steps:
   - id: start-board
     instruction: |
       Start the board server ONCE in the background and leave it running for the
-      whole run. It opens the browser automatically — do NOT pass --no-open here,
-      that defeats the live view.
+      whole run. It opens the browser automatically — do NOT pass --headless here,
+      that defeats the live view (--headless is only for CI / no-display runs).
         npx conductor-board >/tmp/conductor-board.log 2>&1 &
       Wait ~3 seconds for it to initialize. It auto-detects a free port if 3042
       is taken and records the chosen port in .conductor/server.json. Do NOT run
@@ -77,7 +77,12 @@ steps:
   - id: execute-workflow
     instruction: |
       Execute the generated conductor workflow.
-      Create .conductor/status.json with all steps pending and a timestamp run_id.
+      Initialize the board with: conductor-board status-init .conductor/conductor.yaml
+      This also auto-injects a Phase 0 "improvement" pass — if the conductor's
+      knowledge section holds any PROVEN this-conductor insights with current/
+      proposed text, apply each (rewrite the named step), then validate, before
+      step 1. Structural changes (add/remove/reorder a step) wait for human
+      Approve on the board. If nothing is proven, Phase 0 is empty — start the work.
       Set the top-level "goal" from the conductor's description, and refresh
       "current_step_goal" each time current_step changes.
       Walk each step in order, updating status.json after EVERY transition
@@ -97,19 +102,23 @@ steps:
       iteration finishes — don't wait until the loop ends.
       At the START of the run, read .conductor/insights.md (if it exists) to carry
       forward what past runs learned — don't repeat insights already recorded there.
-      Tag heartbeats with an "insight" object when you spot a way to improve the
-      workflow. Before setting status to "done", review your insight-tagged
-      heartbeats and write 3-5 optimization "suggestions" to status.json — the board
-      merges them into the persistent .conductor/insights.md ledger for next time.
-      Set the top-level status to "done" when the last step completes.
+      At run end, before setting status "done", write what you learned into the
+      conductor's knowledge section — the conductor IS the knowledge base. Use:
+        conductor-board suggest "title" --scope <scope> [--step S --current X --proposed Y]
+      --scope is REQUIRED (this-conductor | upstream | template | tooling | corpus).
+      A repeat sighting escalates emerging -> proven (3x); proven this-conductor
+      insights auto-apply in the next run's Phase 0. Browse them on the board's
+      ✨ Insights page. Set the top-level status to "done" when the last step
+      completes.
     requires: [convert-to-conductor]
     gate:
       - name: "Status file exists"
         check: "test -f .conductor/status.json"
       - name: "Workflow completed successfully"
         check: "node -p \\"JSON.parse(require('fs').readFileSync('.conductor/status.json','utf8')).status\\" | grep done"
-      - name: "At least 3 suggestions written"
-        check: "node -e \\"process.exit((JSON.parse(require('fs').readFileSync('.conductor/status.json','utf8')).suggestions||[]).length>=3?0:1)\\""
+      - name: "Captured cross-cutting learnings (≥1 insight, ≥2 scopes)"
+        check: "npx conductor-board knowledge --min 1 --min-scopes 2"
+      - "Answered: what did I learn that does NOT fit a step of this workflow? (upstream, template, tooling, or corpus insights logged with scope tags)"
 `;
 
 export async function runSetup(args) {

package/cli/validate.js

@@ -143,6 +143,8 @@ export function validateConductor(doc) {
       if (!Array.isArray(s.steps) || s.steps.length === 0)
         errors.push(`Loop "${s.id}" has no sub-steps`);
       else validateSubSteps(s, errors);
+      if (s.parallel !== undefined && s.parallel !== true && s.parallel !== false && s.parallel !== "auto")
+        errors.push(`Loop "${s.id}" has invalid "parallel" (use true, false, or auto)`);
     }
 
     for (const [field, val] of [

package/cli/writer.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import yaml from "js-yaml";
+import { discoverConductor, loadConductor, mergeKnowledge, saveConductor, SCOPES } from "./knowledge.js";
 
 const green = (s) => `\x1b[32m${s}\x1b[0m`;
 const red = (s) => `\x1b[31m${s}\x1b[0m`;
@@ -96,7 +97,13 @@ export async function runGate(args) {
   return ok(`${id} gate → ${gate}`);
 }
 
-// conductor-board heartbeat <id> "note" [--iteration X --insight-type T --insight-seed S --final --to STEP]
+// conductor-board heartbeat <id> "note" [--iteration X --sub Y --insight-type T
+//   --insight-seed S --insight-scope SC --final --to STEP]
+//
+// For a loop sub-step (--iteration AND --sub), the beat is written to the
+// sub-step cell AND bubbled up to the loop parent's heartbeat array (tagged with
+// iteration + sub) so the monitor and freeball banner — which read top-level
+// arrays — see every level of activity without the agent beating twice.
 export async function runHeartbeat(args) {
   const sp = statusPathOf(args);
   const [id, note] = positionals(args);
@@ -104,15 +111,19 @@ export async function runHeartbeat(args) {
   const s = load(sp);
   if (!s) return fail("no status.json — run status-init first");
   const step = (s.steps[id] = s.steps[id] || { attempt: 1 });
+
   const entry = { at: now(), note };
   const it = flag(args, ["--iteration"]);
   if (typeof it === "string") entry.iteration = it;
+  const sub = flag(args, ["--sub"]);
+  if (typeof sub === "string") entry.sub = sub;
   const itype = flag(args, ["--insight-type"]);
   if (typeof itype === "string") {
     entry.insight = {
       type: itype,
       seed: typeof flag(args, ["--insight-seed"]) === "string" ? flag(args, ["--insight-seed"]) : note,
       step: id,
+      scope: typeof flag(args, ["--insight-scope"]) === "string" ? flag(args, ["--insight-scope"]) : "this-conductor",
       confidence: typeof flag(args, ["--insight-confidence"]) === "string" ? flag(args, ["--insight-confidence"]) : "medium",
     };
   }
@@ -121,9 +132,55 @@ export async function runHeartbeat(args) {
     const to = flag(args, ["--to"]);
     if (typeof to === "string") entry.handoff = { to };
   }
-  (step.heartbeat = step.heartbeat || []).push(entry);
+
+  if (typeof it === "string" && typeof sub === "string") {
+    // Sub-step beat bubbled to the loop parent's array (tagged iteration + sub).
+    // The board reads top-level arrays for the monitor and the freeball banner,
+    // and the iteration cards filter this array by iteration/sub — so one write
+    // lights up every level. (We write to the parent only, never also the cell,
+    // to avoid double-counting since the readers aggregate the whole tree.)
+    step.type = "loop";
+    step.iterations = step.iterations || {};
+    const iter = (step.iterations[it] = step.iterations[it] || {});
+    iter[sub] = iter[sub] || { attempt: 1 };
+    (step.heartbeat = step.heartbeat || []).push(entry);
+  } else {
+    (step.heartbeat = step.heartbeat || []).push(entry);
+  }
+  save(sp, s);
+  return ok(`${id}${typeof sub === "string" ? `/${it}/${sub}` : ""} ♥ ${note.length > 50 ? note.slice(0, 50) + "…" : note}`);
+}
+
+// conductor-board loop-scope <loopId> <item...> [--note "..."]
+//
+// Frontload a loop's whole iteration list as pending the moment it's determined
+// (§6.2): writes every item into the iterations map and sets total, so the board
+// shows the full plan before any card moves. Also appends a "scope beat" naming
+// the items, unless --note is given.
+export async function runLoopScope(args) {
+  const sp = statusPathOf(args);
+  const [loopId, ...items] = positionals(args);
+  if (!loopId || items.length === 0)
+    return fail("usage: conductor-board loop-scope <loopId> <item1> <item2> … [--note \"...\"]");
+  const s = load(sp);
+  if (!s) return fail("no status.json — run status-init first");
+  const lp = (s.steps[loopId] = s.steps[loopId] || { type: "loop", iterations: {} });
+  lp.type = "loop";
+  lp.iterations = lp.iterations || {};
+  for (const item of items) {
+    lp.iterations[item] = lp.iterations[item] || {}; // sub-steps materialize as work begins
+  }
+  lp.total = items.length;
+  lp.completed = lp.completed || 0;
+  if (lp.status !== "running") lp.status = lp.status || "pending";
+  const noteFlag = flag(args, ["--note"]);
+  const note =
+    typeof noteFlag === "string"
+      ? noteFlag
+      : `${items.length} scoped: ${items.join(", ")}. All pending.`;
+  (lp.heartbeat = lp.heartbeat || []).push({ at: now(), note });
   save(sp, s);
-  return ok(`${id} ♥ ${note.length > 50 ? note.slice(0, 50) + "…" : note}`);
+  return ok(`${loopId} scoped — ${items.length} iterations frontloaded`);
 }
 
 // conductor-board loop <loopId> <item> <subId> <status>
@@ -155,31 +212,116 @@ export async function runLoop(args) {
   return ok(`${loopId}/${item}/${subId} → ${status}`);
 }
 
-// conductor-board suggest "title" --type T --step S --confidence C --rationale R [--current X --proposed Y]
+// conductor-board suggest "title" --scope SC [--type T --step S --current X
+//   --proposed Y --note Z --conductor <file>]
+//
+// Writes the learning straight into the conductor file's knowledge: section —
+// the conductor IS the knowledge base (§10.5). --scope is REQUIRED and routes
+// the insight: this-conductor (auto-appliable in Phase 0) | upstream | template |
+// tooling | corpus. A repeat sighting bumps `observed` and escalates the status
+// (emerging → proven at 3×). Structural types (new_step/remove_step/reorder)
+// need human approval, so they never auto-apply.
 export async function runSuggest(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log(
+      'usage: conductor-board suggest "title" --scope <scope> [--type <kind>] [--step <id>]\n' +
+        "         [--current X] [--proposed Y] [--note Z] [--conductor <file>]\n" +
+        `  --scope (required): ${SCOPES.join(" | ")}\n` +
+        "  Appends to the conductor's knowledge: section. this-conductor insights with\n" +
+        "  current/proposed auto-apply once proven; structural types need approval.",
+    );
+    return true;
+  }
   const sp = statusPathOf(args);
   const [title] = positionals(args);
-  if (!title) return fail('usage: conductor-board suggest "title" --type instruction --step <id>');
-  const s = load(sp);
-  if (!s) return fail("no status.json — run status-init first");
+  if (!title) return fail('usage: conductor-board suggest "title" --scope this-conductor');
   const str = (names, def) => {
     const v = flag(args, names);
     return typeof v === "string" ? v : def;
   };
-  s.suggestions = Array.isArray(s.suggestions) ? s.suggestions : [];
-  s.suggestions.push({
-    id: `sg-${s.suggestions.length + 1}`,
+  const scope = str(["--scope"], undefined);
+  if (!scope) return fail("--scope is required (this-conductor | upstream | template | tooling | corpus)");
+  if (!SCOPES.includes(scope)) return fail(`--scope must be one of: ${SCOPES.join(", ")}`);
+
+  const conductorPath = discoverConductor(sp, str(["--conductor", "-c"], undefined));
+  if (!conductorPath) return fail("no conductor file found next to status.json or in cwd");
+  let doc;
+  try {
+    doc = loadConductor(conductorPath);
+  } catch (e) {
+    return fail(`could not parse conductor: ${e.message}`);
+  }
+  const merged = mergeKnowledge(doc, {
     title,
-    type: str(["--type"], "instruction"),
+    scope,
     step: str(["--step"], undefined),
-    confidence: str(["--confidence"], "medium"),
-    rationale: str(["--rationale"], undefined),
+    type: str(["--type"], undefined),
     current: str(["--current"], undefined),
     proposed: str(["--proposed"], undefined),
-    source_heartbeat: now(),
+    note: str(["--note"], undefined),
   });
-  save(sp, s);
-  return ok(`suggestion #${s.suggestions.length}: ${title.length > 50 ? title.slice(0, 50) + "…" : title}`);
+  const res = saveConductor(conductorPath, doc);
+  if (!res.ok) return fail(`knowledge not written — ${res.error}`);
+  return ok(
+    `knowledge [${scope}] "${title.length > 46 ? title.slice(0, 46) + "…" : title}" — ${merged.status} (observed ${merged.observed}×)`,
+  );
+}
+
+// conductor-board knowledge [list] [--min N] [--scope SC] [--status ST] [--conductor file]
+//
+// With --min, exits 0 when the conductor holds at least N knowledge entries
+// (use as the final-step "captured learnings" gate). With `list`, prints them.
+export async function runKnowledge(args) {
+  const sp = statusPathOf(args);
+  const str = (names) => {
+    const v = flag(args, names);
+    return typeof v === "string" ? v : undefined;
+  };
+  const conductorPath = discoverConductor(sp, str(["--conductor", "-c"]));
+  if (!conductorPath) return fail("no conductor file found");
+  let doc;
+  try {
+    doc = loadConductor(conductorPath);
+  } catch (e) {
+    return fail(`could not parse conductor: ${e.message}`);
+  }
+  const all = (Array.isArray(doc.knowledge) ? doc.knowledge : []).filter(
+    (k) => k && typeof k === "object" && k.title,
+  );
+  const scope = str(["--scope"]);
+  const st = str(["--status"]);
+  const filtered = all.filter(
+    (k) =>
+      (!scope || (k.scope || "this-conductor") === scope) &&
+      (!st || (k.status || "emerging") === st),
+  );
+  // Quality gate (§3.5): enforce captured learnings by VALUE, not count.
+  //   --min N         at least N knowledge entries
+  //   --min-scopes M  entries span at least M distinct scopes (forces the
+  //                   cross-cutting reflection — the highest-leverage insights)
+  const min = str(["--min"]);
+  const minScopes = str(["--min-scopes"]);
+  if (min !== undefined || minScopes !== undefined) {
+    const n = min !== undefined ? Number(min) || 0 : 0;
+    const distinctScopes = new Set(filtered.map((k) => k.scope || "this-conductor")).size;
+    const m = minScopes !== undefined ? Number(minScopes) || 0 : 0;
+    const countOk = filtered.length >= n;
+    const scopesOk = distinctScopes >= m;
+    if (countOk && scopesOk)
+      return ok(`knowledge: ${filtered.length} entr${filtered.length === 1 ? "y" : "ies"}, ${distinctScopes} scope${distinctScopes === 1 ? "" : "s"} (ok)`);
+    const why = [];
+    if (!countOk) why.push(`need ≥ ${n} entries (have ${filtered.length})`);
+    if (!scopesOk) why.push(`need ≥ ${m} scopes (have ${distinctScopes})`);
+    return fail(
+      `knowledge gate: ${why.join(", ")} — capture what you learned, including cross-cutting:\n` +
+        '    conductor-board suggest "…" --scope upstream|template|tooling|corpus',
+    );
+  }
+  if (filtered.length === 0) console.log(dim("  (no knowledge yet)"));
+  for (const k of filtered) {
+    console.log(`  ${k.status || "emerging"} · ${k.scope || "this-conductor"} · ${k.observed || 1}× — ${k.title}`);
+  }
+  return true;
 }
 
 // conductor-board status-init <conductor.yaml> [--run-id ID]
@@ -197,6 +339,73 @@ export async function runStatusInit(args) {
     (typeof flag(args, ["--run-id"]) === "string" && flag(args, ["--run-id"])) ||
     now().replace(/\.\d+Z$/, "").replace(/:/g, "-");
   const steps = {};
+
+  // Phase 0 (§10.2): auto-inject improvement cards from PROVEN this-conductor
+  // knowledge BEFORE the workflow steps. Entries with current/proposed apply
+  // automatically; structural ones (new_step/remove_step/reorder) are flagged
+  // for human approval. A _validate card closes the phase.
+  const STRUCTURAL = new Set(["new_step", "remove_step", "reorder"]);
+  const knowledge = (Array.isArray(doc.knowledge) ? doc.knowledge : []).filter(
+    (k) => k && typeof k === "object" && k.title,
+  );
+  const slug = (t) => String(t).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 40);
+  const seen = new Set();
+
+  // _improve::read-knowledge leads the phase: read + categorize the knowledge.
+  if (knowledge.length > 0) {
+    const cat = (s) => knowledge.filter((k) => (k.status || "emerging") === s).length;
+    const cross = knowledge.filter((k) => (k.scope || "this-conductor") !== "this-conductor").length;
+    steps["_improve::read-knowledge"] = {
+      status: "pending",
+      gate: "pending",
+      attempt: 1,
+      improve: {
+        title: "Read knowledge",
+        kind: "read-knowledge",
+        note:
+          `${cat("proven")} proven · ${cat("emerging")} emerging · ${cat("applied")} applied · ` +
+          `${cross} cross-cutting`,
+      },
+    };
+  }
+
+  let improvements = 0;
+  for (const k of knowledge) {
+    if ((k.status || "emerging") !== "proven") continue;
+    if ((k.scope || "this-conductor") !== "this-conductor") continue;
+    const structural = STRUCTURAL.has(k.type);
+    const textChange = k.current && k.proposed;
+    if (!structural && !textChange) continue; // proven but nothing actionable
+    let id = `_improve::${slug(k.title)}`;
+    while (seen.has(id)) id += "-x";
+    seen.add(id);
+    steps[id] = {
+      status: "pending",
+      gate: "pending",
+      attempt: 1,
+      improve: {
+        step: k.step,
+        title: k.title,
+        current: k.current,
+        proposed: k.proposed,
+        note: k.note,
+        observed: k.observed || 1,
+        scope: k.scope || "this-conductor",
+        structural,
+        kind: k.type || "instruction",
+      },
+    };
+    improvements += 1;
+  }
+  if (improvements > 0) {
+    steps["_improve::validate"] = {
+      status: "pending",
+      gate: "pending",
+      attempt: 1,
+      improve: { title: "Validate conductor", kind: "validate" },
+    };
+  }
+
   for (const st of doc.steps || []) {
     if (!st || !st.id) continue;
     steps[st.id] =
@@ -214,5 +423,10 @@ export async function runStatusInit(args) {
     steps,
   };
   save(sp, status);
-  return ok(`status.json initialized at ${path.relative(process.cwd(), sp)} (${Object.keys(steps).length} steps)`);
+  const workflowCount = (doc.steps || []).filter((s) => s && s.id).length;
+  return ok(
+    `status.json initialized (${workflowCount} steps` +
+      (improvements ? `, ${improvements} Phase 0 improvement${improvements === 1 ? "" : "s"}` : "") +
+      `)`,
+  );
 }