@dougharness/cli 1.0.1 → 1.1.0

package/node_modules/@dougharness/flow/scripts/board.mjs

@@ -1,11 +1,17 @@
 #!/usr/bin/env node
-// CLI for the development board, used by the /doug-next and /core-next skills. Deterministic; no agents.
-//   board.mjs next [dir] [--track flow|hand] [--tag <tag>]
+// CLI for the development board, used by the /doug-next and doug-hand skills. Deterministic; no agents.
+//   board.mjs next [dir] [--track flow|hand|any] [--tag <tag>]
 //                                                 the first Ready card on that track (default flow) whose deps are
 //                                                 Done, as JSON (exit 1 if none); --tag filters to cards carrying it
-//   board.mjs next --batch <n> [dir] [--track flow|hand] [--tag <tag>]
+//   board.mjs next --batch <n> [dir] [--track flow|hand|any] [--tag <tag>]
 //                                                 the first n runnable Ready cards, in board order, as a JSON array
-//                                                 (exit 1 if none): the cards /doug-next plans together
+//                                                 (exit 1 if none): the cards /doug-next plans together; stderr also
+//                                                 carries a `wall cap: <m> min` line (the cards' budgets from the size x class table)
+//   board.mjs budgets [dir] [--from <live-runs file>]
+//                                                 without --from, the shipped wall budget table as `table: <JSON>`;
+//                                                 with --from, recomputes it (p80 per size/class cell) from the file's
+//                                                 Wall clock rows joined to the board, one line per cell and a final
+//                                                 `table:` line; writes nothing (replace WALL_BUDGET_MIN by hand)
 //   board.mjs card <id> [dir]                     one card as JSON
 //   board.mjs reorder <id> [dir] --before <other> | --after <other> | --top | --bottom
 //                                                 reorder a card within its column
@@ -21,7 +27,7 @@
 //                                                 flow, or named by .doug/plan.json (each with --force removes it
 //                                                 and prints a warning to stderr); prints the removed card as JSON
 //                                                 to stdout so a mistaken removal can be re-added by hand
-//   board.mjs record <id> <report.json> [dir] [--cost <usd>] [--codex-cost <usd>] [--shared-cost <usd>] [--wall <text>] [--commit <sha>] [--adversary "<id>=<class>[: <reason>]"]... [--note <text>] [--rehearsal <scenario>]
+//   board.mjs record <id> <report.json> [dir] [--cost <usd>] [--codex-cost <usd>] [--shared-cost <usd>] [--wall <text>] [--commit <sha>] [--adversary "<id>=<class>[: <reason>]"]... [--note <text>] [--rehearsal <scenario>] [--run <run-id>] [--claude-dir <dir>]
 //                                                 append a run entry for the card to docs/live-runs.md; every adversary block
 //                                                 in the report is classified real, marginal, or false (repeat the flag per block).
 //                                                 When .doug/plan.json lists the card among its `cards` (a batch), the entry
@@ -34,13 +40,14 @@
 //   Either record form also promotes .doug/.state/research/<id>.md to docs/research/<id>.md when that note
 //   exists and differs from the docs copy, copying it and printing one line saying so; a card with no note, or
 //   whose docs copy is already byte-identical, is untouched, silently.
-//   board.mjs summary <report.json> [--cost <usd>] [--codex-cost <usd>] [--wall <text>] [--commit <sha>] [--card <id>]
+//   board.mjs summary <report.json> [--cost <usd>] [--codex-cost <usd>] [--wall <text>] [--commit <sha>] [--card <id>] [--run <run-id>] [--claude-dir <dir>]
 //                                                 the three-line chat summary of a report (--card: that card's tasks only)
 
 import { readFileSync } from "node:fs";
 import { relative, resolve } from "node:path";
-import { loadBoard, saveBoard, findCard, nextReadyCard, nextReadyCards, moveCard, editCard, removeCard, reorderCard, runEntry, handEntry, runSummary, boardPath, parseAdversaryClasses, filterReportForCard, recordLanding } from "../lib/board.mjs";
-import { loadPlan, unwrapReport } from "../lib/plan.mjs";
+import { loadBoard, saveBoard, findCard, nextReadyCard, nextReadyCards, moveCard, editCard, removeCard, reorderCard, readyCapWarning, wallCapMinutes, WALL_BUDGET_MIN, WALL_BUDGET_MIN_N, parseLiveRunWalls, wallBudgetTable, runEntry, handEntry, runSummary, boardPath, parseAdversaryClasses, filterReportForCard, recordLanding } from "../lib/board.mjs";
+import { loadPlan, unwrapReport, DEFAULT_BUDGET } from "../lib/plan.mjs";
+import { wallForRun } from "../lib/cost.mjs";
 
 const EDIT_FIELD_ORDER = ["title", "goal", "size", "component", "track", "class", "tags", "deps", "source"];
 const EDIT_USAGE = "usage: board.mjs edit <id> [dir] [--title <t>] [--goal <g> | --goal-file <path>] [--size S|M|L] [--component <c>] [--track flow|hand] [--class <c>] [--tag a,b] [--deps a,b] [--source <s>] [--force]";
@@ -58,10 +65,11 @@ const SUBCOMMAND_FLAGS = {
   edit: ["title", "goal", "goal-file", "size", "component", "track", "class", "deps", "tag", "source", "force"],
   remove: ["force"],
   reorder: ["before", "after", "top", "bottom"],
-  summary: ["cost", "codex-cost", "wall", "commit", "card"],
+  budgets: ["from"],
+  summary: ["cost", "codex-cost", "wall", "commit", "card", "run", "claude-dir"],
 };
 const RECORD_HAND_FLAGS = ["hand", "commit", "wall", "gate", "note", "rehearsal"];
-const RECORD_REPORT_FLAGS = ["cost", "codex-cost", "wall", "commit", "adversary", "shared-cost", "note", "rehearsal"];
+const RECORD_REPORT_FLAGS = ["cost", "codex-cost", "wall", "commit", "adversary", "shared-cost", "note", "rehearsal", "run", "claude-dir"];
 const opts = {};
 const positional = [];
 for (let i = 0; i < argv.length; i++) {
@@ -86,16 +94,17 @@ function fail(msg, code = 1) {
 }
 
 const USAGE_FOR = {
-  next: "usage: board.mjs next [dir] [--track flow|hand] [--batch <n>] [--tag <tag>]",
+  next: "usage: board.mjs next [dir] [--track flow|hand|any] [--batch <n>] [--tag <tag>]",
   card: "usage: board.mjs card <id> [dir]",
   move: "usage: board.mjs move <id> <column> [dir] [--source <text>]",
   edit: EDIT_USAGE,
   remove: "usage: board.mjs remove <id> [dir] [--force]",
   reorder: "usage: board.mjs reorder <id> [dir] --before <other> | --after <other> | --top | --bottom",
-  summary: "usage: board.mjs summary <report.json> [--cost <usd>] [--codex-cost <usd>] [--wall <text>] [--commit <sha>] [--card <id>]",
+  budgets: "usage: board.mjs budgets [dir] [--from <live-runs file>]",
+  summary: "usage: board.mjs summary <report.json> [--cost <usd>] [--codex-cost <usd>] [--wall <text>] [--commit <sha>] [--card <id>] [--run <run-id>] [--claude-dir <dir>]",
 };
 const RECORD_HAND_USAGE = "usage: board.mjs record <id> --hand [dir] [--commit <sha>] [--wall <text>] [--gate <text>] [--note <text>] [--rehearsal <scenario>]";
-const RECORD_REPORT_USAGE = "usage: board.mjs record <id> <report.json> [dir] [--cost <usd>] [--codex-cost <usd>] [--shared-cost <usd>] [--wall <text>] [--commit <sha>] [--adversary \"<id>=<class>[: <reason>]\"]... [--note <text>] [--rehearsal <scenario>]";
+const RECORD_REPORT_USAGE = "usage: board.mjs record <id> <report.json> [dir] [--cost <usd>] [--codex-cost <usd>] [--shared-cost <usd>] [--wall <text>] [--commit <sha>] [--adversary \"<id>=<class>[: <reason>]\"]... [--note <text>] [--rehearsal <scenario>] [--run <run-id>] [--claude-dir <dir>]";
 
 // An unknown --flag for the given subcommand: exit 2, name the flag and the subcommand's usage.
 // Runs on flag names only (parse order doesn't matter), before any work or write.
@@ -123,18 +132,45 @@ try {
   switch (cmd) {
     case "next": {
       const dir = dirFrom(rest, 0);
-      const track = opts.track === "hand" ? "hand" : "flow";
-      if (opts.track !== undefined && opts.track !== "flow" && opts.track !== "hand") fail(`unknown track "${opts.track}"; tracks are flow, hand`, 2);
+      const track = opts.track === "hand" ? "hand" : opts.track === "any" ? "any" : "flow";
+      if (opts.track !== undefined && opts.track !== "flow" && opts.track !== "hand" && opts.track !== "any") fail(`unknown track "${opts.track}"; tracks are flow, hand, any`, 2);
       const batch = opts.batch !== undefined ? Number(opts.batch) : null;
       if (batch !== null && !(Number.isInteger(batch) && batch > 0)) fail(`--batch must be a positive integer, got ${JSON.stringify(opts.batch)}`, 2);
       if (opts.tag !== undefined && opts.tag.includes(",")) fail(`--tag takes one tag here; got "${opts.tag}"`, 2);
       const board = loadBoard(dir);
       const { card, cards, skipped } = batch === null ? nextReadyCard(board, { track, tag: opts.tag }) : nextReadyCards(board, { track, batch, tag: opts.tag });
-      for (const s of skipped) process.stderr.write(s.hand ? `skipping ${s.id}: hand track (built by hand with /core-next, not by doug-next)\n` : s.flow ? `skipping ${s.id}: flow track (run it with /doug-next)\n` : `skipping ${s.id}: waiting on ${s.waitingOn.join(", ")}\n`);
+      for (const s of skipped) process.stderr.write(s.hand ? `skipping ${s.id}: hand track (a by-hand card; /doug-next ${s.id} takes it)\n` : s.flow ? `skipping ${s.id}: flow track (run it with /doug-next)\n` : `skipping ${s.id}: waiting on ${s.waitingOn.join(", ")}\n`);
+      const capLine = readyCapWarning(board);
+      if (capLine) process.stderr.write(capLine);
       if (batch === null ? !card : !cards.length) fail(track === "hand" ? "No Ready hand-track card whose dependencies are Done." : "No Ready card whose dependencies are Done.");
+      if (batch !== null) process.stderr.write(`wall cap: ${wallCapMinutes(cards)} min (size x class table at p80, board.mjs budgets; no size counts as M)\n`);
       process.stdout.write(JSON.stringify(batch === null ? card : cards, null, 2) + "\n");
       break;
     }
+    case "budgets": {
+      if (opts.from === undefined) {
+        process.stdout.write(`table: ${JSON.stringify(WALL_BUDGET_MIN)}\n`);
+        break;
+      }
+      const dir = dirFrom(rest, 0);
+      let text;
+      try {
+        text = readFileSync(resolve(opts.from), "utf8");
+      } catch (e) {
+        fail(`cannot read --from file ${opts.from}: ${e.message}`, 2);
+      }
+      const { table, cells } = wallBudgetTable(parseLiveRunWalls(text), loadBoard(dir));
+      const out = [];
+      for (const size of ["S", "M", "L"]) {
+        for (const c of cells.filter((x) => x.size === size)) {
+          if (c.cls === "all") out.push(c.n === 0 ? `${size}/all n=0 (no landings; keeps the shipped ${WALL_BUDGET_MIN[size].all})` : `${size}/all n=${c.n} p80 ${c.p80}`);
+          else out.push(`${size}/${c.cls} n=${c.n} p80 ${c.p80}${c.n < WALL_BUDGET_MIN_N ? ` (fewer than ${WALL_BUDGET_MIN_N}; falls back to ${size}/all ${table[size].all})` : ""}`);
+        }
+      }
+      out.push(`table: ${JSON.stringify(table)}`);
+      process.stdout.write(out.join("\n") + "\n");
+      break;
+    }
     case "card": {
       const dir = dirFrom(rest, 1);
       process.stdout.write(JSON.stringify(findCard(loadBoard(dir), rest[0]), null, 2) + "\n");
@@ -226,7 +262,7 @@ try {
         break;
       }
       const [id, reportFile] = rest;
-      if (!id || !reportFile) fail("usage: board.mjs record <id> <report.json> [dir] [--cost <usd>] [--codex-cost <usd>] [--shared-cost <usd>] [--wall <text>] [--commit <sha>] [--adversary \"<id>=<class>[: <reason>]\"]... [--note <text>] [--rehearsal <scenario>]", 2);
+      if (!id || !reportFile) fail("usage: board.mjs record <id> <report.json> [dir] [--cost <usd>] [--codex-cost <usd>] [--shared-cost <usd>] [--wall <text>] [--commit <sha>] [--adversary \"<id>=<class>[: <reason>]\"]... [--note <text>] [--rehearsal <scenario>] [--run <run-id>] [--claude-dir <dir>]", 2);
       const dir = dirFrom(rest, 2);
       const card = findCard(loadBoard(dir), id);
       const report = unwrapReport(JSON.parse(readFileSync(resolve(reportFile), "utf8")));
@@ -234,7 +270,8 @@ try {
       const plan = loadPlan(dir);
       const batch = plan && Array.isArray(plan.cards) && plan.cards.includes(id) ? plan.cards : null;
       const taskIds = batch ? plan.tasks.filter((t) => t.card === id).map((t) => t.id) : [];
-      const entry = runEntry({ card, report, cost: opts.cost !== undefined ? Number(opts.cost) : null, codexCost: opts["codex-cost"] !== undefined ? Number(opts["codex-cost"]) : null, wallClock: opts.wall ?? null, mergeCommit: opts.commit ?? null, record: relative(dir, boardPath(dir)), adversary: parseAdversaryClasses(opts.adversary || []), batch, taskIds, sharedCost: opts["shared-cost"] !== undefined ? Number(opts["shared-cost"]) : null, note: opts.note ?? null, rehearsal: opts.rehearsal ?? null });
+      const wall = opts.run ? wallForRun({ runId: opts.run, claudeDir: opts["claude-dir"], projectDir: dir, wallMinutes: report.budget?.wallMinutes ?? DEFAULT_BUDGET.wallMinutes }) : null;
+      const entry = runEntry({ card, report, wall, cost: opts.cost !== undefined ? Number(opts.cost) : null, codexCost: opts["codex-cost"] !== undefined ? Number(opts["codex-cost"]) : null, wallClock: opts.wall ?? null, mergeCommit: opts.commit ?? null, record: relative(dir, boardPath(dir)), adversary: parseAdversaryClasses(opts.adversary || []), batch, taskIds, sharedCost: opts["shared-cost"] !== undefined ? Number(opts["shared-cost"]) : null, note: opts.note ?? null, rehearsal: opts.rehearsal ?? null });
       const { file, promoted } = recordLanding(dir, id, entry);
       if (promoted) process.stdout.write(`Promoted the research note for ${id} to ${promoted}.\n`);
       process.stdout.write(`Appended a run entry for ${id} to ${file}.\n`);
@@ -242,14 +279,17 @@ try {
     }
     case "summary": {
       const [reportFile] = rest;
-      if (!reportFile) fail("usage: board.mjs summary <report.json> [--cost <usd>] [--codex-cost <usd>] [--wall <text>] [--commit <sha>] [--card <id>]", 2);
+      if (!reportFile) fail("usage: board.mjs summary <report.json> [--cost <usd>] [--codex-cost <usd>] [--wall <text>] [--commit <sha>] [--card <id>] [--run <run-id>] [--claude-dir <dir>]", 2);
       let report = unwrapReport(JSON.parse(readFileSync(resolve(reportFile), "utf8")));
       if (opts.card !== undefined) {
         // With the plan at hand the filter also covers a report whose tasks carry no card.
         const plan = loadPlan(dirFrom(rest, 1));
         report = filterReportForCard(report, opts.card, plan && Array.isArray(plan.tasks) ? plan.tasks.filter((t) => t.card === opts.card).map((t) => t.id) : []);
       }
-      process.stdout.write(runSummary({ report, cost: opts.cost !== undefined ? Number(opts.cost) : null, codexCost: opts["codex-cost"] !== undefined ? Number(opts["codex-cost"]) : null, wallClock: opts.wall ?? null, mergeCommit: opts.commit ?? null }));
+      const wall = opts.run ? wallForRun({ runId: opts.run, claudeDir: opts["claude-dir"], projectDir: process.cwd(), wallMinutes: report.budget?.wallMinutes ?? DEFAULT_BUDGET.wallMinutes }) : null;
+      const sumPlan = opts.card !== undefined ? loadPlan(dirFrom(rest, 1)) : null;
+      const sumBatch = sumPlan && Array.isArray(sumPlan.cards) && sumPlan.cards.includes(opts.card) ? sumPlan.cards : null;
+      process.stdout.write(runSummary({ report, wall, batch: sumBatch, card: opts.card ?? null, cost: opts.cost !== undefined ? Number(opts.cost) : null, codexCost: opts["codex-cost"] !== undefined ? Number(opts["codex-cost"]) : null, wallClock: opts.wall ?? null, mergeCommit: opts.commit ?? null }));
       break;
     }
     default:

package/node_modules/@dougharness/flow/scripts/context.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+// The lead's own context percentage (card autopilot-unlimited), read from the session transcript.
+//   context.mjs [dir] [--session <id|latest>] [--claude-dir <path>]
+//     dir         the project directory (default cwd); <dir>/.doug/config.json supplies autopilot.contextThreshold
+//     --session   a session id or latest (default latest), as cost.mjs --session
+//     --claude-dir where ~/.claude lives (tests point it at a fixture)
+// Prints one line and exits 0; exits 1 with a stderr message when there is no transcript or no usage line.
+import { readFileSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { sessionTranscriptPath } from "../lib/cost.mjs";
+import { atThreshold, contextReading, contextThreshold } from "../lib/context.mjs";
+
+const argv = process.argv.slice(2);
+const opts = {};
+const positional = [];
+for (let i = 0; i < argv.length; i++) {
+  if (!argv[i].startsWith("--")) {
+    positional.push(argv[i]);
+    continue;
+  }
+  opts[argv[i].slice(2)] = argv[i + 1] ?? "";
+  i++;
+}
+
+const dir = resolve(positional[0] || process.cwd());
+let config = {};
+try {
+  config = JSON.parse(readFileSync(join(dir, ".doug/config.json"), "utf8"));
+} catch {
+  // absent or unreadable: defaults
+}
+const threshold = contextThreshold(config, (m) => process.stderr.write(`[doug] ${m}\n`));
+
+let file;
+try {
+  file = sessionTranscriptPath({ session: opts.session || "latest", ...(opts["claude-dir"] ? { claudeDir: resolve(opts["claude-dir"]) } : {}), projectDir: dir });
+} catch (err) {
+  process.stderr.write(`context: ${err.message}\n`);
+  process.exit(1);
+}
+const r = contextReading(file);
+if (!r) {
+  process.stderr.write(`context: no usage line in ${file}\n`);
+  process.exit(1);
+}
+process.stdout.write(
+  `context: ${r.pct}% (${r.tokens} of ${r.window} tokens, ${r.model}); threshold ${threshold}% (autopilot.contextThreshold) -> ${atThreshold(r.pct, threshold) ? "stop" : "continue"}\n`,
+);

package/node_modules/@dougharness/flow/scripts/cost.mjs

@@ -1,5 +1,8 @@
 #!/usr/bin/env node
 // Real cost of one doug-implement run from the local Claude Code transcripts; no network, nothing estimated.
+//   cost.mjs --session <id|latest> [dir] [--json] [--claude-dir <path>]
+//     --session           price one Claude Code session: its transcript plus every subagent transcript under it
+//                         (latest = the most recently modified one in the project); exit 1 when none is found
 //   cost.mjs <run-id> [dir] [--json] [--claude-dir <path>]
 //     <run-id>            the Workflow run id (wf_...)
 //     [dir]               the project directory whose ~/.claude/projects slug is searched first (default cwd)
@@ -15,7 +18,7 @@
 // with the run total and any unpriced agent. An unreadable/invalid default report is ignored, not a usage error.
 import { readFileSync } from "node:fs";
 import { resolve, join } from "node:path";
-import { costRun, renderCost, costByCard, renderCostByCard } from "../lib/cost.mjs";
+import { costRun, costSession, renderSession, renderCost, costByCard, renderCostByCard } from "../lib/cost.mjs";
 import { loadPlan, REPORT_RELPATH, unwrapReport } from "../lib/plan.mjs";
 
 const argv = process.argv.slice(2);
@@ -35,13 +38,22 @@ for (let i = 0; i < argv.length; i++) {
   opts[name] = argv[i + 1] ?? "";
   i++;
 }
-const [runId, dirArg] = positional;
-if (!runId) {
+const [runId, dirArg] = opts.session !== undefined ? [null, positional[0]] : positional;
+if (opts.session === "") {
+  process.stderr.write("usage: cost.mjs --session <id|latest> [dir] [--json] [--claude-dir <path>]\n");
+  process.exit(2);
+}
+if (!runId && opts.session === undefined) {
   process.stderr.write("usage: cost.mjs <run-id> [dir] [--json] [--claude-dir <path>]\n");
   process.exit(2);
 }
 try {
   const projectDir = resolve(process.env.CLAUDE_PROJECT_DIR || dirArg || process.cwd());
+  if (opts.session !== undefined) {
+    const result = costSession({ session: opts.session, projectDir, claudeDir: opts["claude-dir"] ? resolve(opts["claude-dir"]) : undefined });
+    process.stdout.write(opts.json ? JSON.stringify(result, null, 2) + "\n" : renderSession(result));
+    process.exit(0);
+  }
   let reportPath = opts.report ? resolve(opts.report) : join(projectDir, REPORT_RELPATH);
   let report = null;
   if (opts.report) {

package/node_modules/@dougharness/flow/scripts/memory.mjs

@@ -60,14 +60,24 @@
 //   memory.mjs lesson unstale <id> [dir] [--json]
 //                                                 clear a lesson's stale mark (set by recall's citation
 //                                                 re-check) so it is a candidate again; refuses on an unknown id
+//   memory.mjs brief-lessons <card-id> [dir] [--k <n>] [--json]
+//                                                 (card memory-every-session) recall for a hand-track card's
+//                                                 briefs: query = the card's title and goal, k 8. Prints the
+//                                                 workflow's lessons header, the rendered `- [id] ...` lines
+//                                                 (capped at 2000 chars like plan.mjs), then `memoryUsed: <ids>`;
+//                                                 writes .doug/.state/reports/<card-id>/lessons.json. No database
+//                                                 -> "No lessons recalled for <id>." (database not created);
+//                                                 a database or provider error -> one stderr line, exit 0;
+//                                                 unknown card -> exit 1
 //   memory.mjs recall <query> [dir] [--files <glob,glob>] [--k <n>] [--json]
-//                                                 hybrid recall (card memory-recall): BM25 over FTS5 fused by
-//                                                 reciprocal rank fusion with cosine over stored vectors when a
-//                                                 provider is configured and vectors exist for it, recency-
-//                                                 weighted, scope-boosted by --files, each returned lesson's
-//                                                 citation re-checked against [dir] only when [dir] is a real
-//                                                 project root (contains .doug); keyword-only, and says so, when
-//                                                 no provider is configured or no vectors match it
+//                                                 dense recall (card memory-recall): with a provider and
+//                                                 stored vectors, every live lesson is ranked by cosine x
+//                                                 recency weight x scope boost (--files), ties by lesson id,
+//                                                 then BM25 hits with no vector are appended in BM25 order;
+//                                                 without a provider or vectors the ranking is BM25 x recency
+//                                                 x scope, a keyword-only fallback that says so. Each returned
+//                                                 lesson's citation is re-checked against [dir] only when
+//                                                 [dir] is a real project root (contains .doug)
 //   memory.mjs reflect <report.json> [dir] [--run <wf-id>] [--card <id>] [--commit <sha>]
 //                       [--adversary "<id>=<class>[: <reason>]"]... [--claude-bin <path>] [--claude-dir <path>]
 //                       [--model <name>] [--max-usd <n>] [--dry-run] [--json]
@@ -82,10 +92,17 @@
 //                                                 helpful instead of appending); idempotent on the report's
 //                                                 sha256 (a second reflect on the same report is a no-op, exit
 //                                                 0); --dry-run applies nothing but still runs the LLM pass and
-//                                                 prints what would happen; --hand is refused, since a hand
-//                                                 landing has no report. Cost is measured from the same local
+//                                                 prints what would happen. Cost is measured from the same local
 //                                                 transcripts cost.mjs reads, falling back to the CLI's own
 //                                                 cost estimate. Needs Node >=22.16 (node:sqlite).
+//   memory.mjs reflect --hand <card-id> [dir] --commit <sha> [--rounds <n>] [--review "R1=<class>[: <reason>]"]...
+//                       [--note <text>] [--claude-bin <path>] [--model <name>] [--max-usd <n>] [--dry-run] [--json]
+//                                                 (card memory-every-session) the same pass for a hand landing:
+//                                                 assembles .doug/.state/reports/<card-id>/hand-report.json from
+//                                                 the saved briefs/, reviews/ and lessons.json (memoryUsed = its
+//                                                 ids; verified true; passes = --rounds, default 1; one fixed
+//                                                 blocker ledger entry per --review id), then reflects on it
+//                                                 exactly as above. --commit is required (exit 2). No schema change.
 //   memory.mjs doctor [dir] [--json]
 //                                                 probe the configured embedding provider (memory.embeddings in
 //                                                 .doug/config.json), or a local Ollama at localhost:11434 when
@@ -128,8 +145,9 @@
 //                                                 path; keyword-only, and says so, with no provider or no vectors
 //   memory.mjs embed-check [dir] [--pairs <file>] [--json]
 //                                                 cosine sanity check (card memory-measure): embeds the dozen
-//                                                 paraphrase and dozen unrelated lesson pairs in evals/memory/
-//                                                 pairs.json (or --pairs) against the configured provider and
+//                                                 paraphrase and dozen unrelated lesson pairs in
+//                                                 plugins/doug-flow/lib/data/pairs.json (or --pairs) against the
+//                                                 configured provider and
 //                                                 confirms paraphrases score higher than unrelated pairs by the
 //                                                 file's stated margin; exit 0 ok, 1 on a failed check or an
 //                                                 unreachable/unconfigured provider, 2 on usage; refuses when
@@ -164,7 +182,7 @@
 // lesson add and import embed only the row(s) they just wrote, best-effort, when a provider is configured: a
 // provider failure prints one stderr line and never turns into a nonzero exit for that add/import. A pending
 // row from an earlier add is left alone until `reembed` (or a later add/import) picks it up.
-import { readFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { readFileSync, existsSync, mkdirSync, writeFileSync, readdirSync } from "node:fs";
 import { resolve, join, dirname } from "node:path";
 import { createHash } from "node:crypto";
 import { spawnSync } from "node:child_process";
@@ -186,7 +204,7 @@ import {
 
 const argv = process.argv.slice(2);
 const FLAGS = new Set(["json", "all", "hand", "dry-run", "check", "no-check"]);
-const REPEATABLE = new Set(["adversary"]);
+const REPEATABLE = new Set(["adversary", "review"]);
 const opts = {};
 const positional = [];
 for (let i = 0; i < argv.length; i++) {
@@ -469,8 +487,8 @@ function printProposalResult(result, jsonOut) {
 }
 
 // `index build`'s own pairs loader: an explicit --pairs that is missing fails clearly (same as loadPairsOrFail,
-// same exit code), but with no --pairs given at all, a missing default file (a standalone-published copy of
-// this plugin outside this checkout - DEFAULT_SANITY_PAIRS lives at the repo root) is not a hard failure: build
+// same exit code), but with no --pairs given at all, a missing default file (DEFAULT_SANITY_PAIRS lives inside
+// plugins/doug-flow/lib/data, so this only happens if that file was removed) is not a hard failure: build
 // still runs, and buildIndex itself reports a check failure only if a model/dims pair actually new to the code
 // index shows up needing one.
 function loadIndexPairs(opts) {
@@ -595,26 +613,88 @@ try {
     case "reflect": {
       const usage =
         'usage: memory.mjs reflect <report.json> [dir] [--run <wf-id>] [--card <id>] [--commit <sha>] [--adversary "<id>=<class>[: <reason>]"]... [--claude-bin <path>] [--claude-dir <path>] [--model <name>] [--max-usd <n>] [--dry-run] [--json]';
-      if (opts.hand) fail(`${usage}\n--hand is not accepted: a hand landing has no report.`, 2);
-      const [reportFile] = rest;
-      if (!reportFile) fail(usage, 2);
-      const dir = dirFrom(rest, 1);
-      const reportPath = resolve(reportFile);
-      if (!existsSync(reportPath)) fail(`no such report file: ${reportPath}`);
+      let dir;
+      let reportPath;
       let reportText;
-      try {
-        reportText = readFileSync(reportPath, "utf8");
-      } catch (err) {
-        fail(`cannot read report file ${reportPath}: ${err.message}`);
-      }
       let report;
-      try {
-        report = unwrapReport(JSON.parse(reportText));
-      } catch (err) {
-        fail(`cannot parse report file ${reportPath} as JSON: ${err.message}`);
+      let classes;
+      let handCard = null;
+      if (opts.hand) {
+        const handUsage =
+          'usage: memory.mjs reflect --hand <card-id> [dir] --commit <sha> [--rounds <n>] [--review "R1=<real|marginal|false>[: <reason>]"]... [--note <text>] [--claude-bin <path>] [--model <name>] [--max-usd <n>] [--dry-run] [--json]';
+        const [id] = rest;
+        if (!id || !opts.commit) fail(handUsage, 2);
+        handCard = id;
+        dir = dirFrom(rest, 1);
+        let rounds = 1;
+        if (opts.rounds !== undefined) {
+          rounds = Number(opts.rounds);
+          if (!Number.isInteger(rounds) || rounds < 1) fail(`${handUsage}\n--rounds must be a positive integer, got ${JSON.stringify(opts.rounds)}.`, 2);
+        }
+        try {
+          classes = parseAdversaryClasses(opts.review || []);
+        } catch (err) {
+          fail(`${handUsage}\n${err.message}`, 2);
+        }
+        const base = join(dir, ".doug", ".state", "reports", id);
+        const readDirFiles = (sub) => {
+          const d = join(base, sub);
+          if (!existsSync(d)) return [];
+          return readdirSync(d)
+            .filter((n) => !n.startsWith("."))
+            .sort()
+            .map((name) => {
+              try {
+                return { name, text: readFileSync(join(d, name), "utf8") };
+              } catch {
+                return null;
+              }
+            })
+            .filter(Boolean);
+        };
+        let memoryUsed = [];
+        try {
+          const saved = JSON.parse(readFileSync(join(base, "lessons.json"), "utf8"));
+          if (saved && Array.isArray(saved.ids)) memoryUsed = saved.ids.filter((x) => typeof x === "string");
+        } catch {
+          memoryUsed = [];
+        }
+        const ledger = classes.map((c) => {
+          return { id: c.id, stage: "adversary", seat: "reviewer", severity: "blocker", status: "fixed", description: c.reason || `reviewer finding ${c.id}` };
+        });
+        const sortKeys = (v) =>
+          Array.isArray(v) ? v.map(sortKeys) : v && typeof v === "object" ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, sortKeys(v[k])])) : v;
+        const handReport = sortKeys({
+          track: "hand",
+          card: id,
+          commit: opts.commit,
+          levels: [{ index: 0, tasks: [{ id, card: id, commit: opts.commit, verified: true, passes: rounds, stopReason: null, memoryUsed, ledger }] }],
+          hand: { briefs: readDirFiles("briefs"), reviews: readDirFiles("reviews"), note: textOrNull(opts.note) },
+        });
+        reportText = JSON.stringify(handReport, null, 2) + "\n";
+        reportPath = join(base, "hand-report.json");
+        mkdirSync(base, { recursive: true });
+        writeFileSync(reportPath, reportText, "utf8");
+        report = handReport;
+      } else {
+        const [reportFile] = rest;
+        if (!reportFile) fail(usage, 2);
+        dir = dirFrom(rest, 1);
+        reportPath = resolve(reportFile);
+        if (!existsSync(reportPath)) fail(`no such report file: ${reportPath}`);
+        try {
+          reportText = readFileSync(reportPath, "utf8");
+        } catch (err) {
+          fail(`cannot read report file ${reportPath}: ${err.message}`);
+        }
+        try {
+          report = unwrapReport(JSON.parse(reportText));
+        } catch (err) {
+          fail(`cannot parse report file ${reportPath} as JSON: ${err.message}`);
+        }
+        classes = parseAdversaryClasses(opts.adversary || []);
       }
       const reportHash = createHash("sha256").update(reportText).digest("hex");
-      const classes = parseAdversaryClasses(opts.adversary || []);
       const plan = loadPlan(dir);
       const models = loadModels(dir);
       const model = textOrNull(opts.model) || (models.tiers.cheap && models.tiers.cheap.model) || "haiku";
@@ -639,7 +719,7 @@ try {
           classes,
           plan,
           run: opts.run ?? null,
-          card: opts.card ?? null,
+          card: handCard ?? opts.card ?? null,
           commit: opts.commit ?? null,
           model,
           claudeDir,
@@ -817,7 +897,7 @@ try {
         process.stdout.write(JSON.stringify(result, null, 2) + "\n");
       } else {
         process.stdout.write(
-          `Imported ${result.added + result.updated} lesson(s) from ${result.dir}: ${result.added} added, ${result.updated} updated (old row superseded), ${result.unchanged} unchanged, ${result.skipped} skipped (empty).\n`
+          `Imported ${result.added + result.updated} lesson(s) from ${result.dir}: ${result.added} added, ${result.updated} updated (old row superseded), ${result.unchanged} unchanged, ${result.skipped} skipped (empty), ${result.retired} retired (file deleted).\n`
         );
       }
       break;
@@ -842,14 +922,18 @@ try {
       }
       const provider = createProvider(readMemoryConfig(dir));
       const staleDays = readMemoryStaleDays(dir);
-      const { openMemory, recallLessons } = await import("../lib/memory.mjs");
+      const { openMemory, recallLessons, degradedWarning, detectLocalProvider } = await import("../lib/memory.mjs");
+      // Probed once, and only when no provider is configured; a failed probe is just "not detected".
+      const detectedProvider = provider ? null : await detectLocalProvider();
       const m = openMemory(dir);
       let result;
       try {
-        result = await recallLessons(m, query, { files, k, provider, checkoutDir: dir, staleDays });
+        result = await recallLessons(m, query, { files, k, provider, checkoutDir: dir, staleDays, detectedProvider });
       } finally {
         m.close();
       }
+      const recallWarning = degradedWarning(result, { what: "memory recall", detectedProvider });
+      if (recallWarning) process.stderr.write(recallWarning + "\n");
       if (opts.json) {
         process.stdout.write(JSON.stringify(result, null, 2) + "\n");
       } else {
@@ -862,6 +946,67 @@ try {
       }
       break;
     }
+    case "brief-lessons": {
+      const usage = "usage: memory.mjs brief-lessons <card-id> [dir] [--k <n>] [--json]";
+      const [id, ...extra] = rest;
+      if (!id) fail(usage, 2);
+      const dir = dirFrom(extra, 0);
+      let k = 8;
+      if (opts.k !== undefined) {
+        k = Number(opts.k);
+        if (!Number.isInteger(k) || k < 1) fail(`${usage}\n--k must be an integer >= 1, got ${JSON.stringify(opts.k)}.`, 2);
+      }
+      let card;
+      try {
+        card = findCard(loadBoard(dir), id);
+      } catch (err) {
+        fail(`no card ${id}: ${err.message}`);
+      }
+      const query = `${card.title}\n${card.goal ?? ""}`;
+      const header = "Lessons from earlier runs on this repository (memory; each cites where it was learned):";
+      const saved = { card: id, query, mode: null, reason: null, ids: [], text: null, recalledAt: new Date().toISOString() };
+      let error = null;
+      if (existsSync(join(dir, ".doug", ".state", "memory", "memory.db"))) {
+        try {
+          const provider = createProvider(readMemoryConfig(dir));
+          const staleDays = readMemoryStaleDays(dir);
+          const { openMemory, recallLessons, degradedWarning, degradedReason, detectLocalProvider, renderLessons } = await import("../lib/memory.mjs");
+          const detectedProvider = provider ? null : await detectLocalProvider();
+          const m = openMemory(dir);
+          try {
+            const result = await recallLessons(m, query, { k, checkoutDir: dir, provider, staleDays, detectedProvider });
+            const warning = degradedWarning(result, { what: "memory recall", detectedProvider });
+            if (warning) process.stderr.write(warning + "\n");
+            const rendered = renderLessons(result.lessons);
+            saved.mode = result.mode;
+            saved.reason = result.degraded ? degradedReason(result, detectedProvider) : null;
+            saved.ids = rendered.ids;
+            saved.text = rendered.text === null ? null : result.degraded ? `(recall was keyword-only: ${saved.reason})\n${rendered.text}` : rendered.text;
+          } finally {
+            m.close();
+          }
+        } catch (err) {
+          error = err.message;
+          saved.mode = null;
+          saved.reason = null;
+          saved.ids = [];
+          saved.text = null;
+          saved.error = error;
+          process.stderr.write(`[doug] memory recall skipped: ${error}\n`);
+        }
+      }
+      const reportDir = join(dir, ".doug", ".state", "reports", id);
+      mkdirSync(reportDir, { recursive: true });
+      writeFileSync(join(reportDir, "lessons.json"), JSON.stringify(saved, null, 2) + "\n", "utf8");
+      if (opts.json) {
+        process.stdout.write(JSON.stringify(saved, null, 2) + "\n");
+      } else if (saved.ids.length) {
+        process.stdout.write([header, saved.text, `memoryUsed: ${saved.ids.join(", ")}`].join("\n") + "\n");
+      } else {
+        process.stdout.write(`No lessons recalled for ${id}.\n`);
+      }
+      break;
+    }
     case "doctor": {
       const dir = dirFrom(rest, 0);
       const cfg = readMemoryConfig(dir);
@@ -918,10 +1063,12 @@ try {
       if (opts.check && opts["no-check"]) {
         fail(`${usage}\n--check and --no-check are mutually exclusive.`, 2);
       }
-      const { openMemory, embedLessons } = await import("../lib/memory.mjs");
+      const { openMemory, embedLessons, lessonsNeedingEmbedding } = await import("../lib/memory.mjs");
       const m = openMemory(dir);
       let result;
       let checkStatus;
+      let stillMissing = 0;
+      let liveTotal = 0;
       try {
         if (opts["no-check"]) {
           process.stderr.write("embed-check: skipped (--no-check)\n");
@@ -943,6 +1090,8 @@ try {
           batch,
           onProgress: ({ embedded, total }) => process.stderr.write(`embedded ${embedded}/${total}\n`),
         });
+        stillMissing = lessonsNeedingEmbedding(m, { model: provider.model, dims: provider.dims }).length;
+        liveTotal = m.prepare("SELECT COUNT(*) AS n FROM lessons WHERE superseded_by IS NULL AND stale IS NULL").get().n;
       } finally {
         m.close();
       }
@@ -953,6 +1102,11 @@ try {
           `Embedded ${result.embedded}/${result.total} lesson(s) with ${provider.model}/${provider.dims} (${result.failed} failed).\n`
         );
       }
+      if (stillMissing > 0) {
+        process.stderr.write(
+          `WARNING: ${stillMissing} of ${liveTotal} lessons still have no vector for ${provider.model}/${provider.dims}; retry with memory.mjs reembed --batch 4\n`
+        );
+      }
       break;
     }
     case "index": {
@@ -1075,15 +1229,18 @@ try {
           }
         }
         const provider = createProvider(readMemoryConfig(dir));
-        const { openMemory } = await import("../lib/memory.mjs");
+        const { openMemory, degradedWarning, detectLocalProvider } = await import("../lib/memory.mjs");
         const { searchIndex } = await import("../lib/code-index.mjs");
+        const detectedProvider = provider ? null : await detectLocalProvider();
         const m = openMemory(dir);
         let result;
         try {
-          result = await searchIndex(m, query, { k, files, provider });
+          result = await searchIndex(m, query, { k, files, provider, detectedProvider });
         } finally {
           m.close();
         }
+        const searchWarning = degradedWarning(result, { what: "code index search", code: true, detectedProvider });
+        if (searchWarning) process.stderr.write(searchWarning + "\n");
         if (opts.json) {
           process.stdout.write(JSON.stringify(result, null, 2) + "\n");
         } else {
@@ -1267,7 +1424,7 @@ try {
       break;
     }
     default:
-      fail("usage: memory.mjs <record|reflect|outcomes|lessons|lesson|import|recall|doctor|reembed|embed-check|index|condition|decision|rule|claude-md> ...", 2);
+      fail("usage: memory.mjs <record|reflect|outcomes|lessons|lesson|import|recall|brief-lessons|doctor|reembed|embed-check|index|condition|decision|rule|claude-md> ...", 2);
   }
 } catch (err) {
   fail(err.message);