conductor-board 2.1.0 → 2.3.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 [