conductor-board 2.1.0 → 2.3.0

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]
@@ -196,7 +338,97 @@ export async function runStatusInit(args) {
   const runId =
     (typeof flag(args, ["--run-id"]) === "string" && flag(args, ["--run-id"])) ||
     now().replace(/\.\d+Z$/, "").replace(/:/g, "-");
+  const wfName = doc.name || "workflow";
+
+  // §6.2 — every run gets a human name: {workflow}-run-{N}-{timestamp}. N is the
+  // count of archived runs + 1; the timestamp is the run id trimmed to minutes.
+  const nameSlug = String(wfName).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+  const historyDir = path.join(path.dirname(sp), "history");
+  let priorRuns = 0;
+  try {
+    priorRuns = fs.readdirSync(historyDir).filter((f) => f.endsWith(".json")).length;
+  } catch {
+    /* no history yet */
+  }
+  const tsShort = runId.replace(/-\d{2}$/, ""); // 2026-06-04T12-30-00 → 2026-06-04T12-30
+  const runName =
+    (typeof flag(args, ["--run-name"]) === "string" && flag(args, ["--run-name"])) ||
+    `${nameSlug}-run-${priorRuns + 1}-${tsShort}`;
+
+  // §6.1 — auto_improve (default on). When off, the Phase 0 self-improvement
+  // pass is fully disabled: no improvement cards injected at all.
+  const autoImprove = doc.auto_improve !== false;
+
   const steps = {};
+  let improvements = 0;
+
+  if (autoImprove) {
+    // 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`,
+        },
+      };
+    }
+
+    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] =
@@ -205,8 +437,10 @@ export async function runStatusInit(args) {
         : { status: "pending", gate: "pending", attempt: 1 };
   }
   const status = {
-    workflow: doc.name || "workflow",
+    workflow: wfName,
     run_id: runId,
+    run_name: runName,
+    auto_improve: autoImprove,
     status: "running",
     goal: (doc.description || "").trim().replace(/\s+/g, " "),
     current_step: null,
@@ -214,5 +448,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"}` : "") +
+      `)`,
+  );
 }