conductor-board 2.0.0 → 2.2.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,6 +212,118 @@ export async function runLoop(args) {
   return ok(`${loopId}/${item}/${subId} → ${status}`);
 }
 
+// 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" --scope this-conductor');
+  const str = (names, def) => {
+    const v = flag(args, names);
+    return typeof v === "string" ? v : def;
+  };
+  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,
+    scope,
+    step: str(["--step"], undefined),
+    type: str(["--type"], undefined),
+    current: str(["--current"], undefined),
+    proposed: str(["--proposed"], undefined),
+    note: str(["--note"], undefined),
+  });
+  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]
 export async function runStatusInit(args) {
   const [conductorPath] = positionals(args);
@@ -170,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] =
@@ -187,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"}` : "") +
+      `)`,
+  );
 }