@xhulz/nina 0.28.18 → 0.28.19

package/src/commands/pipeline.mjs

@@ -1,17 +1,19 @@
 /**
  * `nina pipeline` — draws a project's agent chain: the line work moves along, the gates it passes on the
- * way, where each stage sends work back and how many rounds it may, each stage's model, effort and skills,
- * and which chain a task of each shape takes.
+ * way, the stages that run as several agents at once, where each stage sends work back and how many rounds
+ * it may, each stage's model, effort and skills with what it did over the last thirty days, and which chain
+ * a task of each shape takes. `--for` draws one shape's chain alone.
  *
  * Opening a project, the pipeline was a graph, a router, ten specs and a table in CLAUDE.md to read before
  * anyone could say which stage came after which, on which model, with which skills. Every fact here is
- * already composed, and `nina check` already holds it to the graph; this only reads it back and draws it.
+ * already composed, and `nina check` already holds it to the graph, or already measured; this only reads it
+ * back and draws it.
  */
 
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
 import { basename, join, resolve } from 'node:path';
 import { PINK, useColor } from '../banner.mjs';
-import { HARNESS } from '../paths.mjs';
+import { HARNESS, slugFor, snapshotsDir } from '../paths.mjs';
 import { TERMINALS, parseGraph } from '../graph.mjs';
 import { required } from '../tools.mjs';
 import { isLoopBack } from '../transcripts.mjs';
@@ -20,6 +22,9 @@ import { frontmatter } from './pills.mjs';
 /** A stage line under "## Stages": "- `name` — what it does". */
 const STAGE_LINE = /^- `([a-z][a-z-]*)` — (.*)$/;
 
+/** How far back the history beside each stage looks, unless `--since` says. */
+const HISTORY_DAYS = 30;
+
 /**
  * What each stage does, in the graph's own words: shorter than a spec's `description:`, which is written
  * for Claude Code to choose an agent by.
@@ -48,7 +53,8 @@ export function stageWords(text) {
  * - The gates: a stage off the line that a line stage sends work to on a condition, and that hands it on
  *   to the next stage of the line.
  * - The ends: where the line's last stage sends work on a condition, followed forward to a terminal.
- * - The loop-backs: every edge on a verdict that sends work back, to a stage or to the owner.
+ * - The loop-backs: every edge on a verdict that sends work back, to a stage or to the owner, grouped by
+ *   the stage that sends it.
  *
  * @param {{stages: Set<string>, edges: object[]}} graph - A parsed graph.
  * @returns {{line: string[], gates: object[], ends: object[], back: object[]}}
@@ -81,17 +87,18 @@ export function shapeOf(graph) {
       }
       return { path, when: e.when };
     });
-  // Grouped by the stage that sends the work back, in the order the stages are listed.
   const back = graph.edges.filter((e) => isLoopBack(e.token)).sort((a, b) => order.indexOf(a.from) - order.indexOf(b.from));
   return { line, gates, ends, back };
 }
 
 /**
  * The rows of the "Required chain by task shape" table in a composed CLAUDE.md: the shape, and the chain it
- * takes — the part the table sets in bold, where it does.
+ * takes — the part the table sets in bold, where it does. A row whose chain runs stage → stage, or is
+ * "none", is a chain of its own; any other (`+ dba before reviewer`) is an add-on to whichever chain the
+ * task takes.
  *
  * @param {string} text - The composed CLAUDE.md.
- * @returns {{shape: string, chain: string}[]}
+ * @returns {{shape: string, chain: string, addOn: boolean}[]}
  */
 export function chainsByShape(text) {
   const at = text.indexOf('| Task shape |');
@@ -102,27 +109,116 @@ export function chainsByShape(text) {
     const [shape = '', chain = ''] = row.split('|').slice(1).map((c) => c.trim());
     const bold = /\*\*(.+?)\*\*/.exec(chain)?.[1];
     const plain = (s) => s.replace(/\*\*/g, '').replace(/`/g, '').trim();
-    rows.push({ shape: plain(shape), chain: plain(bold ?? chain) });
+    const taken = plain(bold ?? chain);
+    rows.push({ shape: plain(shape), chain: taken, addOn: !taken.includes('→') && !/^none\b/i.test(taken) });
   }
   return rows;
 }
 
+/**
+ * The task shapes a `--for` names: by its number in the list, or by every word it gives.
+ *
+ * @param {{shape: string}[]} shapes - The chain table's rows.
+ * @param {string} query - A number, or words.
+ * @returns {object[]}
+ */
+export function pickShape(shapes, query) {
+  if (/^\d+$/.test(query.trim())) {
+    const row = shapes[Number(query) - 1];
+    return row ? [row] : [];
+  }
+  const words = query.toLowerCase().split(/\s+/).filter(Boolean);
+  if (words.length === 0) return [];
+  return shapes.filter((r) => words.every((w) => r.shape.toLowerCase().includes(w)));
+}
+
+/**
+ * What each stage did since a date, from the measurement store: its runs, the verdicts that could be read,
+ * and how many of those sent work back. A run a hook denied never ran, and is not counted.
+ *
+ * @param {object[]} records - The project's records.
+ * @param {string} since - An ISO date.
+ * @returns {Map<string, {runs: number, read: number, back: number}>}
+ */
+export function historyOf(records, since) {
+  const byRole = new Map();
+  for (const r of records) {
+    if (!r.role || r.status === 'denied' || String(r.ts ?? '') < since) continue;
+    const s = byRole.get(r.role) ?? { runs: 0, read: 0, back: 0 };
+    s.runs += 1;
+    if (r.verdict && r.verdict !== 'UNCLEAR' && r.verdict !== 'NONE') {
+      s.read += 1;
+      if (isLoopBack(r.verdict)) s.back += 1;
+    }
+    byRole.set(r.role, s);
+  }
+  return byRole;
+}
+
+/**
+ * The project's records in the measurement store, under the name Claude Code gives its directory — as
+ * given, or with its links resolved, since either may be the one the sessions ran in.
+ *
+ * @param {string} dir - The project.
+ * @returns {object[]|null} Null when the store has nothing for it.
+ */
+function storedRuns(dir) {
+  const names = new Set([slugFor(dir)]);
+  try {
+    names.add(slugFor(realpathSync(dir)));
+  } catch {
+    // A directory that cannot be resolved is looked up as given.
+  }
+  for (const name of names) {
+    const file = join(snapshotsDir(), `${name}.jsonl`);
+    if (!existsSync(file)) continue;
+    return readFileSync(file, 'utf8')
+      .split('\n')
+      .filter(Boolean)
+      .flatMap((l) => {
+        try {
+          return [JSON.parse(l)];
+        } catch {
+          return [];
+        }
+      });
+  }
+  return null;
+}
+
 /**
  * Runs the command.
  *
- * @param {string[]} argv - `[--project <dir>]`.
+ * @param {string[]} argv - `[--project <dir>] [--for <number or words>] [--since <YYYY-MM-DD>]`.
  * @returns {Promise<number>} Process exit code.
  */
 export async function pipeline(argv) {
-  const dir = resolve(argv.includes('--project') ? argv[argv.indexOf('--project') + 1] : process.cwd());
+  const arg = (flag) => (argv.includes(flag) ? argv[argv.indexOf(flag) + 1] ?? '' : null);
+  const dir = resolve(arg('--project') ?? process.cwd());
   const graphPath = join(dir, '.claude', 'graph.md');
   if (!existsSync(graphPath)) {
     console.error(`  no .claude/graph.md in ${dir} — this draws a composed pipeline: \`nina compose\` writes one`);
     return 1;
   }
-  const graph = parseGraph(readFileSync(graphPath, 'utf8'));
-  const words = stageWords(readFileSync(graphPath, 'utf8'));
-  const { line, gates, ends, back } = shapeOf(graph);
+  const graphText = readFileSync(graphPath, 'utf8');
+  const graph = parseGraph(graphText);
+  const words = stageWords(graphText);
+  const shape = shapeOf(graph);
+  const claude = join(dir, 'CLAUDE.md');
+  const shapes = existsSync(claude) ? chainsByShape(readFileSync(claude, 'utf8')) : [];
+
+  // `--for`: one shape's chain, and only the stages on it.
+  const query = arg('--for');
+  let chosen = null;
+  if (query !== null) {
+    const picked = pickShape(shapes, query);
+    if (picked.length !== 1) {
+      console.error(picked.length === 0 ? `  no task shape matches "${query}" — by number or by words:` : `  "${query}" matches ${picked.length} task shapes — narrow it, or give the number:`);
+      for (const [i, r] of shapes.entries()) if (picked.length === 0 || picked.includes(r)) console.error(`    ${String(i + 1).padStart(2)}  ${r.shape}`);
+      return 1;
+    }
+    chosen = picked[0];
+  }
 
   const color = useColor();
   const name = (s) => (color && !TERMINALS.has(s) ? `\x1b[38;2;${PINK.join(';')}m${s}\x1b[0m` : s);
@@ -130,6 +226,12 @@ export async function pipeline(argv) {
   const width = Math.max(80, Math.min(process.stdout.columns ?? 110, 140));
   const fit = (s, room) => (s.length > room ? `${s.slice(0, Math.max(room - 1, 1))}…` : s);
   const arrow = ' ─▶ ';
+  const many = graph.many ?? new Map();
+  // A stage that may run as several agents at once carries ×n wherever the line draws it. Alignment is
+  // counted on the plain text, and the names are painted after.
+  const plainStage = (s) => `${s}${many.has(s) ? ' ×n' : ''}`;
+  const shownStage = (s) => `${name(s)}${many.has(s) ? ' ×n' : ''}`;
+  const padName = (s, n) => `${name(s)}${' '.repeat(Math.max(n - s.length, 1))}`;
 
   let profile = {};
   try {
@@ -138,32 +240,54 @@ export async function pipeline(argv) {
     // A pipeline composed by hand draws all the same; only the header has less to say.
   }
   const surfaces = (profile.surfaces ?? []).slice().sort();
-  console.log(`  pipeline · ${basename(dir)}${profile.core ? ` · core ${profile.core}` : ''}${surfaces.length ? ` · surfaces ${surfaces.join(', ')}` : ''}\n`);
+  console.log(`  pipeline · ${basename(dir)}${profile.core ? ` · core ${profile.core}` : ''}${surfaces.length ? ` · surfaces ${surfaces.join(', ')}` : ''}`);
 
-  // Alignment is counted on the plain text, and the names are painted after.
-  const padName = (s, n) => `${name(s)}${' '.repeat(Math.max(n - s.length, 1))}`;
+  // The stages this drawing covers: all of them, or those the chosen shape's chain names.
+  const onChain = chosen ? (chosen.chain.match(/[a-z][a-z-]*/g) ?? []).filter((w) => graph.stages.has(w)) : null;
+  const covered = new Set(onChain ?? graph.stages);
 
-  // The line, and where its last stage sends work.
-  const plainHead = `  ${line.join(arrow)}`;
-  const head = `  ${line.map(name).join(arrow)}`;
-  if (ends.length === 0) console.log(head);
-  const lead = ' '.repeat(plainHead.length + 1);
-  const joint = (i) => (ends.length === 1 ? '──▶ ' : i === 0 ? '─┬─▶ ' : i === ends.length - 1 ? ' └─▶ ' : ' ├─▶ ');
-  const endCol = Math.max(0, ...ends.map((end, i) => `${lead}${joint(i)}${end.path.join(arrow)}`.length)) + 3;
-  ends.forEach((end, i) => {
-    const plain = `${lead}${joint(i)}${end.path.join(arrow)}`;
-    console.log(`${i === 0 ? `${head} ` : lead}${joint(i)}${end.path.map(name).join(arrow)}${' '.repeat(endCol - plain.length)}${dim(fit(end.when, width - endCol))}`);
-  });
+  if (chosen) {
+    console.log(`  for: ${chosen.shape}\n`);
+    if (onChain.length === 0) console.log(`  ${chosen.chain}`);
+    else console.log(`  ${onChain.map(shownStage).join(arrow)}`);
+    const addOns = shapes.filter((r) => r.addOn && r !== chosen);
+    if (addOns.length > 0 && onChain.length > 0) {
+      console.log(`\n  ${dim('and, when the change calls for them')}`);
+      const col = Math.min(Math.max(...addOns.map((r) => r.chain.length)), 44) + 4;
+      for (const r of addOns) console.log(`    ${fit(r.chain, col - 4).padEnd(col)}${dim(fit(r.shape, width - col - 6))}`);
+    }
+  } else {
+    console.log('');
+    // The line, and where its last stage sends work.
+    const plainHead = `  ${shape.line.map(plainStage).join(arrow)}`;
+    const head = `  ${shape.line.map(shownStage).join(arrow)}`;
+    if (shape.ends.length === 0) console.log(head);
+    const lead = ' '.repeat(plainHead.length + 1);
+    const joint = (i) => (shape.ends.length === 1 ? '──▶ ' : i === 0 ? '─┬─▶ ' : i === shape.ends.length - 1 ? ' └─▶ ' : ' ├─▶ ');
+    const endCol = Math.max(0, ...shape.ends.map((end, i) => `${lead}${joint(i)}${end.path.join(arrow)}`.length)) + 3;
+    shape.ends.forEach((end, i) => {
+      const plain = `${lead}${joint(i)}${end.path.join(arrow)}`;
+      console.log(`${i === 0 ? `${head} ` : lead}${joint(i)}${end.path.map(name).join(arrow)}${' '.repeat(endCol - plain.length)}${dim(fit(end.when, width - endCol))}`);
+    });
 
-  if (gates.length > 0) {
-    console.log(`\n  ${dim('gates on the way, when the diff calls for them')}`);
-    const chain = (g) => `${g.from}${arrow}${g.gate}${arrow}${g.to}`;
-    const col = Math.max(...gates.map((g) => chain(g).length)) + 4;
-    for (const g of gates) {
-      console.log(`    ${name(g.from)}${arrow}${name(g.gate)}${arrow}${name(g.to)}${' '.repeat(col - chain(g).length)}${dim(fit(g.when, width - col - 6))}`);
+    if (shape.gates.length > 0) {
+      console.log(`\n  ${dim('gates on the way, when the diff calls for them')}`);
+      const chain = (g) => `${g.from}${arrow}${g.gate}${arrow}${g.to}`;
+      const col = Math.max(...shape.gates.map((g) => chain(g).length)) + 4;
+      for (const g of shape.gates) {
+        console.log(`    ${name(g.from)}${arrow}${name(g.gate)}${arrow}${name(g.to)}${' '.repeat(col - chain(g).length)}${dim(fit(g.when, width - col - 6))}`);
+      }
     }
   }
 
+  const drawnMany = [...many].filter(([s]) => covered.has(s));
+  if (drawnMany.length > 0) {
+    console.log(`\n  ${dim('×n  runs as several agents at once, each on its own share of the work')}`);
+    const col = Math.max(...drawnMany.map(([s]) => s.length)) + 3;
+    for (const [s, { when }] of drawnMany) console.log(`      ${padName(s, col)}${dim(fit(when, width - col - 8))}`);
+  }
+
+  const back = shape.back.filter((e) => covered.has(e.from) && (covered.has(e.to) || TERMINALS.has(e.to)));
   if (back.length > 0) {
     console.log(`\n  ${dim('sent back: to whom, on which verdict, and how many rounds per issue')}`);
     const fromCol = Math.max(...back.map((e) => e.from.length)) + 2;
@@ -180,20 +304,30 @@ export async function pipeline(argv) {
     }
   }
 
-  // Each stage: what it does, on which model and effort, with which skills.
+  // Each stage: what it does, on which model and effort, with which skills, and what it did lately.
   const agentsDir = join(dir, '.claude', 'agents');
   const specs = new Map();
   for (const file of existsSync(agentsDir) ? readdirSync(agentsDir).filter((f) => f.endsWith('.md')).sort() : []) {
     specs.set(file.replace(/\.md$/, ''), readFileSync(join(agentsDir, file), 'utf8'));
   }
-  const stages = [...graph.stages];
+  const since = arg('--since') || new Date(Date.now() - HISTORY_DAYS * 86_400_000).toISOString().slice(0, 10);
+  const runs = storedRuns(dir);
+  const history = runs ? historyOf(runs, since) : null;
+  const stages = [...graph.stages].filter((s) => covered.has(s));
   const col = Math.max(...stages.map((s) => s.length), 10) + 2;
-  console.log(`\n  ${dim('stages')}`);
+  console.log(`\n  ${dim(history ? `stages · what each ran since ${since}, from the measured history` : 'stages · no measured history for this project yet')}`);
   for (const stage of stages) {
     const spec = specs.get(stage) ?? '';
     const front = frontmatter(spec) ?? {};
-    const runs = [front.model, front.effort].filter(Boolean).join(' · ') || 'no spec';
-    console.log(`    ${padName(stage, col)}${runs.padEnd(26)}${dim(fit(words.get(stage) ?? '', width - col - 32))}`);
+    const on = [front.model, front.effort].filter(Boolean).join(' · ') || 'no spec';
+    console.log(`    ${padName(stage, col)}${on.padEnd(26)}${dim(fit(words.get(stage) ?? '', width - col - 32))}`);
+    if (history) {
+      const h = history.get(stage);
+      const said = !h
+        ? 'no run'
+        : `${h.runs} run(s)${h.read === 0 ? ', no verdict read' : `, sent back ${h.back} of ${h.read} (${Math.round((100 * h.back) / h.read)}%)`}`;
+      console.log(`    ${' '.repeat(col)}${dim('ran     ')}${said}`);
+    }
     const skills = [...required(spec).skills].sort();
     if (skills.length > 0) {
       const lines = [];
@@ -210,22 +344,23 @@ export async function pipeline(argv) {
     }
   }
 
-  // An agent the project wrote for itself is not a stage, and the graph does not route to it.
-  const own = [...specs.keys()].filter((role) => !graph.stages.has(role));
-  if (own.length > 0) {
-    console.log(`\n  ${dim("the project's own agents, outside the pipeline")}`);
-    for (const role of own) {
-      const front = frontmatter(specs.get(role)) ?? {};
-      console.log(`    ${role}${' '.repeat(Math.max(col - role.length, 2))}${dim(fit(front.description ?? '', width - col - 6))}`);
+  if (!chosen) {
+    // An agent the project wrote for itself is not a stage, and the graph does not route to it.
+    const own = [...specs.keys()].filter((role) => !graph.stages.has(role));
+    if (own.length > 0) {
+      console.log(`\n  ${dim("the project's own agents, outside the pipeline")}`);
+      for (const role of own) {
+        const front = frontmatter(specs.get(role)) ?? {};
+        console.log(`    ${role}${' '.repeat(Math.max(col - role.length, 2))}${dim(fit(front.description ?? '', width - col - 6))}`);
+      }
+    }
+    if (shapes.length > 0) {
+      console.log(`\n  ${dim('which chain a task takes, by its shape (CLAUDE.md) — `nina pipeline --for <number or words>` draws one')}`);
+      const shapeCol = Math.min(Math.max(...shapes.map((r) => r.shape.length)), 56) + 2;
+      for (const [i, r] of shapes.entries()) {
+        console.log(`    ${String(i + 1).padStart(2)}  ${fit(r.shape, shapeCol - 2).padEnd(shapeCol)}${fit(r.chain, width - shapeCol - 10)}`);
+      }
     }
-  }
-
-  const claude = join(dir, 'CLAUDE.md');
-  const shapes = existsSync(claude) ? chainsByShape(readFileSync(claude, 'utf8')) : [];
-  if (shapes.length > 0) {
-    console.log(`\n  ${dim('which chain a task takes, by its shape (CLAUDE.md)')}`);
-    const shapeCol = Math.min(Math.max(...shapes.map((r) => r.shape.length)), 58) + 2;
-    for (const r of shapes) console.log(`    ${fit(r.shape, shapeCol - 2).padEnd(shapeCol)}${fit(r.chain, width - shapeCol - 6)}`);
   }
   console.log('');
   return 0;

package/src/graph.mjs

@@ -24,6 +24,13 @@ const STAGE = /^- `([a-z][a-z-]*)` — /;
  */
 const EDGE = /^- `([a-z][a-z-]*)` → `([a-z][a-z-]*)` on `([A-Z][A-Z-]*)`(?: — (.*?))?(?: · max (\d+))?\s*$/;
 
+/**
+ * A line under "## Concurrency" naming a stage that may run as several agents at once, each on a share of
+ * the work: "- `name` × many — when". Declared rather than left to the prose, so a drawing of the pipeline
+ * can show it and `check` can hold it to the stages.
+ */
+const MANY = /^- `([a-z][a-z-]*)` × many — (.*)$/;
+
 /** Where work may end: finished, or handed to the owner. Neither needs a spec. */
 export const TERMINALS = new Set(['done', 'human']);
 
@@ -40,6 +47,8 @@ export function parseGraph(text) {
   const stages = new Set();
   const edges = [];
   const stray = [];
+  /** @type {Map<string, {when: string, line: number}>} */
+  const many = new Map();
   const sections = new Set();
   const twice = [];
   let section = '';
@@ -61,9 +70,12 @@ export function parseGraph(text) {
         return;
       }
       edges.push({ from: m[1], to: m[2], token: m[3], when: m[4] ?? '', max: m[5] ? Number(m[5]) : null, line: i + 1 });
+    } else if (section === 'concurrency') {
+      const m = MANY.exec(line);
+      if (m) many.set(m[1], { when: m[2].trim(), line: i + 1 });
     }
   });
-  return { stages, edges, stray, sections, twice };
+  return { stages, edges, stray, sections, twice, many };
 }
 
 /**
@@ -122,6 +134,9 @@ export function validateGraph(graph, specs, roles = new Set()) {
   for (const s of graph.twice ?? []) problems.push(`stage \`${s}\` is listed more than once`);
 
   for (const s of stray) problems.push(`graph.md:${s.line} is under "## Edges" but is not an edge: ${s.text}`);
+  for (const [s, { line }] of graph.many ?? []) {
+    if (!stages.has(s)) problems.push(`graph.md:${line} says \`${s}\` runs as several agents, and it is not a stage here`);
+  }
 
   // Every stage is a spec on disk and every spec on disk is a stage — the profile decides both, so
   // a mismatch means a layer named a stage the profile does not compose, or composed one no edge