@open-tomato/rafa 0.7.1

package/dist/index-zjxrphjq.js

@@ -0,0 +1,1755 @@
+// @bun
+import {
+  STORE_BACKENDS,
+  activeOutput,
+  activeOutputMode,
+  createTextOutput,
+  describeValue,
+  isMapping,
+  messageOf,
+  readRafaBlocks
+} from "./index-akz06erg.js";
+
+// src/effort/store.ts
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync
+} from "fs";
+import { dirname, join } from "path";
+var EFFORT_STORE_DIR = join(".rafa", "effort");
+var STORE_FILE_NAMES = {
+  sessions: "sessions.ndjson",
+  commits: "commits.ndjson"
+};
+function asObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
+}
+function normaliseKey(key) {
+  return typeof key === "string" && key.length > 0 ? key : null;
+}
+function effortStorePath(repoRoot, kind) {
+  return join(repoRoot, EFFORT_STORE_DIR, STORE_FILE_NAMES[kind]);
+}
+function readStoreText(path) {
+  return existsSync(path) ? readFileSync(path, "utf8") : null;
+}
+function parseStoreText(text) {
+  const rows = [];
+  if (text === null || text.length === 0) {
+    return { rows, lineCount: 0, unparsedLineCount: 0 };
+  }
+  const lines = text.split(/\r?\n/);
+  if (lines[lines.length - 1] === "")
+    lines.pop();
+  let unparsedLineCount = 0;
+  for (const line of lines) {
+    const record = parseRow(line);
+    if (record === null) {
+      unparsedLineCount += 1;
+      continue;
+    }
+    rows.push(record);
+  }
+  return { rows, lineCount: lines.length, unparsedLineCount };
+}
+function parseRow(line) {
+  if (line.trim().length === 0)
+    return null;
+  try {
+    return asObject(JSON.parse(line));
+  } catch {
+    return null;
+  }
+}
+function readStoreRows(path) {
+  return parseStoreText(readStoreText(path));
+}
+function keysOfRows(rows, keyOf) {
+  const keys = new Set;
+  for (const row of rows) {
+    const key = normaliseKey(keyOf(row));
+    if (key !== null)
+      keys.add(key);
+  }
+  return keys;
+}
+function collectedKeys(path, keyOf) {
+  return keysOfRows(readStoreRows(path).rows, keyOf);
+}
+function appendRows(path, rows, keyOf) {
+  const keys = rows.map((row) => normaliseKey(keyOf(row)));
+  const keylessAt = keys.indexOf(null);
+  if (keylessAt !== -1) {
+    const at = `row ${keylessAt} of ${rows.length}`;
+    throw new Error(`effort store: ${at} carries no key; batch refused`);
+  }
+  const text = readStoreText(path);
+  const held = keysOfRows(parseStoreText(text).rows, keyOf);
+  const lines = [];
+  let skipped = 0;
+  for (const [index, row] of rows.entries()) {
+    const key = keys[index] ?? null;
+    if (key === null || held.has(key)) {
+      skipped += 1;
+      continue;
+    }
+    held.add(key);
+    lines.push(JSON.stringify(row));
+  }
+  if (lines.length === 0) {
+    return { path, appended: 0, skipped, separatedPartialLine: false };
+  }
+  const separatedPartialLine = text !== null && text.length > 0 && !text.endsWith(`
+`);
+  const lead = separatedPartialLine ? `
+` : "";
+  mkdirSync(dirname(path), { recursive: true });
+  appendFileSync(path, `${lead}${lines.join(`
+`)}
+`, "utf8");
+  return {
+    path,
+    appended: lines.length,
+    skipped,
+    separatedPartialLine
+  };
+}
+
+// src/effort/store/types.ts
+function keyOrNull(value) {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+var EFFORT_KEY_PROJECTIONS = {
+  sessions: (row) => keyOrNull(row.sessionId),
+  commits: (row) => keyOrNull(row.sha)
+};
+
+// src/effort/store/ndjson.ts
+function readKind(repoRoot, kind) {
+  return readStoreRows(effortStorePath(repoRoot, kind));
+}
+function keysOfKind(repoRoot, kind) {
+  const path = effortStorePath(repoRoot, kind);
+  return collectedKeys(path, EFFORT_KEY_PROJECTIONS[kind]);
+}
+function appendKind(repoRoot, kind, rows) {
+  const path = effortStorePath(repoRoot, kind);
+  return appendRows(path, rows, EFFORT_KEY_PROJECTIONS[kind]);
+}
+function openNdjsonStore(repoRoot) {
+  return {
+    append: (kind, rows) => appendKind(repoRoot, kind, rows),
+    keys: (kind) => keysOfKind(repoRoot, kind),
+    read: (kind) => readKind(repoRoot, kind).rows,
+    path: (kind) => effortStorePath(repoRoot, kind),
+    readRows: (kind) => readKind(repoRoot, kind)
+  };
+}
+
+// src/effort/store/sqlite.ts
+import { existsSync as existsSync2, mkdirSync as mkdirSync2 } from "fs";
+import { dirname as dirname2, join as join2 } from "path";
+import { Database } from "bun:sqlite";
+var STORE_FILE_NAME = "effort.sqlite";
+function sqliteStorePath(repoRoot) {
+  return join2(repoRoot, EFFORT_STORE_DIR, STORE_FILE_NAME);
+}
+var SQLITE_MIGRATIONS = [
+  `
+  CREATE TABLE sessions (
+    seq        INTEGER PRIMARY KEY,
+    session_id TEXT NOT NULL UNIQUE CHECK (session_id <> ''),
+    row_json   TEXT NOT NULL
+  );
+
+  CREATE TABLE commits (
+    seq      INTEGER PRIMARY KEY,
+    sha      TEXT NOT NULL UNIQUE CHECK (sha <> ''),
+    row_json TEXT NOT NULL
+  );
+  `,
+  `
+  CREATE TABLE findings (
+    seq          INTEGER PRIMARY KEY,
+    id           TEXT NOT NULL UNIQUE CHECK (id <> ''),
+    session_id   TEXT NOT NULL CHECK (session_id <> ''),
+    plan_stub    TEXT,
+    task_line    TEXT NOT NULL,
+    kind         TEXT
+      CHECK (kind IN ('gotcha', 'pattern', 'location', 'skill-suggestion')),
+    trigger      TEXT CHECK (trigger <> ''),
+    what         TEXT CHECK (what <> ''),
+    cause        TEXT,
+    resolution   TEXT,
+    artifact     TEXT CHECK (artifact <> ''),
+    signal       TEXT CHECK (signal IN ('loud', 'silent')),
+    outcome      TEXT NOT NULL,
+    tracker_ref  TEXT,
+    collected_at TEXT NOT NULL,
+    CHECK (artifact IS NOT NULL OR (trigger IS NOT NULL AND what IS NOT NULL))
+  );
+
+  CREATE UNIQUE INDEX findings_by_artifact
+    ON findings (session_id, artifact)
+    WHERE artifact IS NOT NULL;
+
+  CREATE UNIQUE INDEX findings_by_trigger_what
+    ON findings (session_id, trigger, what)
+    WHERE artifact IS NULL;
+  `,
+  `
+  CREATE TABLE blockers (
+    seq          INTEGER PRIMARY KEY,
+    id           TEXT NOT NULL UNIQUE CHECK (id <> ''),
+    session_id   TEXT NOT NULL CHECK (session_id <> ''),
+    plan_stub    TEXT,
+    task_line    TEXT NOT NULL,
+    what         TEXT NOT NULL CHECK (what <> ''),
+    artifact     TEXT CHECK (artifact <> ''),
+    outcome      TEXT NOT NULL,
+    collected_at TEXT NOT NULL
+  );
+
+  CREATE UNIQUE INDEX blockers_by_entry
+    ON blockers (session_id, what, ifnull(artifact, ''));
+
+  CREATE TABLE out_of_scope_bugs (
+    seq          INTEGER PRIMARY KEY,
+    id           TEXT NOT NULL UNIQUE CHECK (id <> ''),
+    session_id   TEXT NOT NULL CHECK (session_id <> ''),
+    plan_stub    TEXT,
+    task_line    TEXT NOT NULL,
+    what         TEXT NOT NULL CHECK (what <> ''),
+    artifact     TEXT CHECK (artifact <> ''),
+    security     INTEGER CHECK (security IN (0, 1)),
+    outcome      TEXT NOT NULL,
+    collected_at TEXT NOT NULL
+  );
+
+  CREATE UNIQUE INDEX out_of_scope_bugs_by_entry
+    ON out_of_scope_bugs (session_id, what, ifnull(artifact, ''), ifnull(security, -1));
+  `,
+  `
+  CREATE TABLE report_absences (
+    seq          INTEGER PRIMARY KEY,
+    id           TEXT NOT NULL UNIQUE CHECK (id <> ''),
+    session_id   TEXT NOT NULL UNIQUE CHECK (session_id <> ''),
+    plan_stub    TEXT,
+    task_line    TEXT NOT NULL,
+    reason       TEXT NOT NULL CHECK (reason <> ''),
+    detail       TEXT NOT NULL CHECK (detail <> ''),
+    block_body   TEXT,
+    outcome      TEXT NOT NULL,
+    collected_at TEXT NOT NULL
+  );
+  `,
+  `
+  CREATE TABLE task_reports (
+    seq          INTEGER PRIMARY KEY,
+    id           TEXT NOT NULL UNIQUE CHECK (id <> ''),
+    session_id   TEXT NOT NULL UNIQUE CHECK (session_id <> ''),
+    plan_stub    TEXT,
+    task_line    TEXT NOT NULL,
+    status       TEXT CHECK (status IN ('done', 'blocked')),
+    outcome      TEXT NOT NULL,
+    collected_at TEXT NOT NULL
+  );
+  `,
+  `
+  CREATE TABLE preflight (
+    seq          INTEGER PRIMARY KEY,
+    run_id       TEXT NOT NULL CHECK (run_id <> ''),
+    position     INTEGER NOT NULL CHECK (typeof(position) = 'integer' AND position >= 0),
+    tier         TEXT NOT NULL CHECK (tier IN ('required', 'optional')),
+    kind         TEXT NOT NULL CHECK (kind <> ''),
+    item         TEXT NOT NULL CHECK (item <> ''),
+    probe        TEXT CHECK (probe <> ''),
+    outcome      TEXT NOT NULL CHECK (outcome IN ('pass', 'fail', 'timeout')),
+    duration_ms  INTEGER NOT NULL CHECK (typeof(duration_ms) = 'integer' AND duration_ms >= 0),
+    failure      TEXT CHECK (failure <> ''),
+    collected_at TEXT NOT NULL,
+    UNIQUE (run_id, position),
+    CHECK ((outcome = 'pass') = (failure IS NULL))
+  );
+  `,
+  `
+  CREATE TABLE dispatches (
+    seq          INTEGER PRIMARY KEY,
+    session_id   TEXT NOT NULL UNIQUE CHECK (session_id <> ''),
+    plan_stub    TEXT,
+    task_line    TEXT NOT NULL,
+    declaration  TEXT CHECK (declaration <> ''),
+    agent        TEXT CHECK (agent <> ''),
+    model        TEXT CHECK (model <> ''),
+    effort       TEXT CHECK (effort <> ''),
+    budget_usd   REAL CHECK (budget_usd IS NULL OR (typeof(budget_usd) IN ('integer', 'real') AND budget_usd > 0)),
+    tools        TEXT CHECK (tools <> ''),
+    flags        TEXT NOT NULL,
+    collected_at TEXT NOT NULL
+  );
+  `,
+  `
+  CREATE TABLE changes (
+    seq          INTEGER PRIMARY KEY,
+    id           TEXT NOT NULL UNIQUE CHECK (id <> ''),
+    session_id   TEXT NOT NULL CHECK (session_id <> ''),
+    plan_stub    TEXT,
+    task_line    TEXT NOT NULL,
+    level        TEXT NOT NULL
+      CHECK (level IN ('patch', 'minor', 'major', 'none')),
+    area         TEXT CHECK (area <> ''),
+    summary      TEXT NOT NULL CHECK (summary <> ''),
+    collected_at TEXT NOT NULL
+  );
+
+  CREATE UNIQUE INDEX changes_by_entry
+    ON changes (session_id, level, ifnull(area, ''), summary);
+  `,
+  `
+  ALTER TABLE out_of_scope_bugs
+    ADD COLUMN scope TEXT CHECK (scope IN ('machine', 'rafa'));
+  `
+];
+var SQLITE_SCHEMA_VERSION = SQLITE_MIGRATIONS.length;
+var KIND_TABLES = {
+  sessions: { name: "sessions", keyColumn: "session_id" },
+  commits: { name: "commits", keyColumn: "sha" }
+};
+var LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+function hasKey(entry) {
+  return entry.key !== null;
+}
+function refused(index, length, reason) {
+  return new Error(`effort store: row ${index} of ${length} ${reason}; batch refused`);
+}
+function batchEntries(kind, rows) {
+  const keyOf = EFFORT_KEY_PROJECTIONS[kind];
+  const projected = rows.map((row) => ({ key: keyOf(row), row }));
+  const keyed = projected.filter(hasKey);
+  if (keyed.length < projected.length) {
+    const keylessAt = projected.findIndex((entry) => !hasKey(entry));
+    throw refused(keylessAt, rows.length, "carries no key");
+  }
+  const unholdableAt = keyed.findIndex(({ key }) => LONE_SURROGATE.test(key));
+  if (unholdableAt !== -1) {
+    const reason = "carries a key with a lone UTF-16 surrogate," + " which SQLite text cannot hold";
+    throw refused(unholdableAt, rows.length, reason);
+  }
+  return keyed.map(({ key, row }) => ({ key, body: JSON.stringify(row) }));
+}
+function userVersion(db) {
+  const row = db.query("PRAGMA user_version").get();
+  return row?.user_version ?? 0;
+}
+function checkedVersion(db, path, latest) {
+  const version = userVersion(db);
+  if (version > latest) {
+    throw new Error(`effort store: ${path} is at schema version ${version}, past the` + ` ${latest} this rafa knows; refusing to read or write it`);
+  }
+  return version;
+}
+function migrateSchema(db, path, migrations = SQLITE_MIGRATIONS) {
+  const latest = migrations.length;
+  if (checkedVersion(db, path, latest) === latest)
+    return;
+  const applyPending = db.transaction(() => {
+    const from = checkedVersion(db, path, latest);
+    for (const sql of migrations.slice(from))
+      db.run(sql);
+    db.run(`PRAGMA user_version = ${latest}`);
+  });
+  applyPending.immediate();
+}
+function withSqliteStore(path, create, use) {
+  if (create)
+    mkdirSync2(dirname2(path), { recursive: true });
+  const db = new Database(path, { readwrite: true, create });
+  try {
+    migrateSchema(db, path);
+    return use(db);
+  } finally {
+    db.close();
+  }
+}
+function insertBatch(db, table, entries) {
+  const insert = db.query(`INSERT INTO ${table.name} (${table.keyColumn}, row_json) VALUES (?, ?)` + ` ON CONFLICT (${table.keyColumn}) DO NOTHING`);
+  const insertAll = db.transaction(() => entries.reduce((appended, { key, body }) => appended + insert.run(key, body).changes, 0));
+  return insertAll.immediate();
+}
+function writeSqliteStore(path, rowCount, empty, insert) {
+  const exists = existsSync2(path);
+  if (rowCount > 0)
+    return withSqliteStore(path, !exists, insert);
+  if (exists)
+    withSqliteStore(path, false, () => {
+      return;
+    });
+  return empty;
+}
+function appendKind2(path, kind, rows) {
+  const entries = batchEntries(kind, rows);
+  const table = KIND_TABLES[kind];
+  const appended = writeSqliteStore(path, entries.length, 0, (db) => insertBatch(db, table, entries));
+  return { path, appended, skipped: entries.length - appended };
+}
+function keysOfKind2(path, kind) {
+  if (!existsSync2(path))
+    return new Set;
+  const { name, keyColumn } = KIND_TABLES[kind];
+  const keys = withSqliteStore(path, false, (db) => db.query(`SELECT ${keyColumn} AS key FROM ${name} ORDER BY seq`).all());
+  return new Set(keys.map(({ key }) => key));
+}
+function parsedObject(body) {
+  try {
+    const value = JSON.parse(body);
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+function rowOf(body, where) {
+  const value = parsedObject(body);
+  if (value === null) {
+    throw new Error(`effort store: ${where} does not hold a JSON object;` + " no append writes one");
+  }
+  return value;
+}
+function readKind2(path, kind) {
+  if (!existsSync2(path))
+    return [];
+  const { name } = KIND_TABLES[kind];
+  const stored = withSqliteStore(path, false, (db) => db.query(`SELECT seq, row_json AS body FROM ${name} ORDER BY seq`).all());
+  return stored.map(({ seq, body }) => rowOf(body, `${path}: ${name} row ${seq}`));
+}
+function openSqliteStore(repoRoot) {
+  const path = sqliteStorePath(repoRoot);
+  return {
+    append: (kind, rows) => appendKind2(path, kind, rows),
+    keys: (kind) => keysOfKind2(path, kind),
+    read: (kind) => readKind2(path, kind),
+    path: () => path
+  };
+}
+
+// src/adapters/learning/local.ts
+import { appendFile, mkdir, readFile } from "fs/promises";
+import { join as join3 } from "path";
+var PREFIX = "local learning";
+var INSTINCTS_FILE = "instincts.ndjson";
+var FLAGS_FILE = "flags.ndjson";
+var MIN_CONFIDENCE = 0.3;
+var MAX_CONFIDENCE = 0.9;
+var SIGNALS = ["loud", "silent"];
+var STATUSES = ["active", "flagged"];
+function isString(value) {
+  return typeof value === "string";
+}
+function isNonEmptyString(value) {
+  return typeof value === "string" && value !== "";
+}
+function oneOf(members) {
+  return (value) => typeof value === "string" && members.includes(value);
+}
+var INSTINCT_CHECKS = {
+  id: [isNonEmptyString, "a non-empty string"],
+  trigger: [isString, "a string"],
+  action: [isString, "a string"],
+  action_hash: [isString, "a string"],
+  confidence: [
+    (value) => typeof value === "number" && value >= MIN_CONFIDENCE && value <= MAX_CONFIDENCE,
+    `a number from ${MIN_CONFIDENCE} to ${MAX_CONFIDENCE}`
+  ],
+  usage_count: [
+    (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0,
+    "a whole number from 0"
+  ],
+  artifact: [(value) => value === undefined || typeof value === "string", "a string when present"],
+  signal: [oneOf(SIGNALS), `one of: ${SIGNALS.join(", ")}`],
+  status: [oneOf(STATUSES), `one of: ${STATUSES.join(", ")}`],
+  created_at: [isString, "a string"],
+  updated_at: [isString, "a string"]
+};
+var PAYLOAD_CHECKS = {
+  source_id: [isNonEmptyString, "a non-empty string"],
+  instincts: [Array.isArray, "a list"]
+};
+var HELD_INSTINCT_CHECKS = {
+  source_id: [isNonEmptyString, "a non-empty string"],
+  instinct: [isMapping, "a mapping"]
+};
+var FLAG_CHECKS = {
+  id: [isNonEmptyString, "a non-empty string"],
+  reason: [isString, "a string"],
+  flagged_at: [isString, "a string"]
+};
+function fieldsProblem(value, checks, at) {
+  if (!isMapping(value)) {
+    return `${at} is ${describeValue(value)}, expected a mapping`;
+  }
+  for (const [key, [accepts, expected]] of Object.entries(checks)) {
+    if (!accepts(value[key])) {
+      return `${key} is ${describeValue(value[key])} in ${at}, expected ${expected}`;
+    }
+  }
+  return null;
+}
+function payloadProblem(payload) {
+  const problem = fieldsProblem(payload, PAYLOAD_CHECKS, "the payload");
+  if (problem !== null)
+    return problem;
+  const { instincts } = payload;
+  return instincts.map((record, index) => fieldsProblem(record, INSTINCT_CHECKS, `instincts[${index}]`)).find((found) => found !== null) ?? null;
+}
+function heldInstinctProblem(value) {
+  return fieldsProblem(value, HELD_INSTINCT_CHECKS, "the line") ?? fieldsProblem(value.instinct, INSTINCT_CHECKS, "the instinct");
+}
+function flagProblem(value) {
+  return fieldsProblem(value, FLAG_CHECKS, "the flag");
+}
+function copyInstinct(record) {
+  const { artifact } = record;
+  return {
+    id: record.id,
+    trigger: record.trigger,
+    action: record.action,
+    action_hash: record.action_hash,
+    confidence: record.confidence,
+    usage_count: record.usage_count,
+    ...artifact === undefined ? {} : { artifact },
+    signal: record.signal,
+    status: record.status,
+    created_at: record.created_at,
+    updated_at: record.updated_at
+  };
+}
+function hasCode(error, code) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === code;
+}
+async function readIfPresent(path) {
+  try {
+    return await readFile(path, "utf8");
+  } catch (error) {
+    if (hasCode(error, "ENOENT"))
+      return "";
+    throw error;
+  }
+}
+async function appendLines(path, lines) {
+  const held = await readIfPresent(path);
+  const lead = held === "" || held.endsWith(`
+`) ? "" : `
+`;
+  await appendFile(path, `${lead}${lines.join(`
+`)}
+`, "utf8");
+}
+function numberedLines(contents) {
+  return contents.split(`
+`).flatMap((line, index) => line === "" ? [] : [[index + 1, line]]);
+}
+function readLine(line, problemOf) {
+  let value;
+  try {
+    value = JSON.parse(line);
+  } catch (error) {
+    return { ok: false, problem: `it is not JSON (${messageOf(error)})` };
+  }
+  const problem = problemOf(value);
+  return problem === null ? { ok: true, value } : { ok: false, problem };
+}
+function warnThroughActiveOutput(message) {
+  activeOutput().warn(message);
+}
+function localInstinctsDir(repoRoot) {
+  return join3(repoRoot, ".rafa", "instincts");
+}
+function createLocalLearning(options) {
+  const { instinctsDir } = options;
+  const now = options.now ?? (() => new Date().toISOString());
+  const warn = options.warn ?? warnThroughActiveOutput;
+  const instinctsPath = join3(instinctsDir, INSTINCTS_FILE);
+  const flagsPath = join3(instinctsDir, FLAGS_FILE);
+  async function heldInstincts() {
+    const lines = numberedLines(await readIfPresent(instinctsPath));
+    return lines.flatMap(([number, line]) => {
+      const reading = readLine(line, heldInstinctProblem);
+      if (reading.ok)
+        return [copyInstinct(reading.value.instinct)];
+      warn(`${PREFIX}: line ${number} of ${instinctsPath} is not a held instinct, so it was skipped: ${reading.problem}`);
+      return [];
+    });
+  }
+  async function flaggedIds() {
+    const lines = numberedLines(await readIfPresent(flagsPath));
+    return new Set(lines.map(([number, line]) => {
+      const reading = readLine(line, flagProblem);
+      if (reading.ok)
+        return reading.value.id;
+      throw new Error(`${PREFIX}: line ${number} of ${flagsPath} is not a flag,` + ` and a bundle skipping it could hold an instinct it flags: ${reading.problem}`);
+    }));
+  }
+  const learning = {
+    push: async (payload) => {
+      const problem = payloadProblem(payload);
+      if (problem !== null) {
+        throw new TypeError(`${PREFIX}: refused to store a push: ${problem}`);
+      }
+      const decisions = payload.instincts.map((incoming) => ({
+        incoming,
+        rule: "new-trigger",
+        produced: [copyInstinct(incoming)]
+      }));
+      const lines = decisions.flatMap(({ produced }) => produced.map((instinct) => JSON.stringify({
+        source_id: payload.source_id,
+        instinct
+      })));
+      if (lines.length > 0) {
+        await mkdir(instinctsDir, { recursive: true });
+        await appendLines(instinctsPath, lines);
+      }
+      return { decisions, discarded: [] };
+    },
+    pullBlessed: async () => {
+      const flagged = await flaggedIds();
+      const instincts = (await heldInstincts()).filter((instinct) => instinct.status === "active" && !flagged.has(instinct.id));
+      return { version: now(), instincts };
+    },
+    flag: async (id, reason) => {
+      const flag = { id, reason, flagged_at: now() };
+      const problem = flagProblem(flag);
+      if (problem !== null) {
+        throw new TypeError(`${PREFIX}: refused to write an invalid flag: ${problem}`);
+      }
+      const held = await heldInstincts();
+      if (!held.some((instinct) => instinct.id === id)) {
+        throw new Error(`${PREFIX}: no instinct ${describeValue(id)} is held under ${instinctsDir}`);
+      }
+      await appendLines(flagsPath, [JSON.stringify(flag)]);
+    }
+  };
+  return Object.freeze(learning);
+}
+
+// src/adapters/output/json.ts
+var SECOND_RESULT_REFUSAL = "json output: refused a second terminal result event; a command emits exactly one";
+function createJsonOutput({
+  stream,
+  now = () => new Date
+}) {
+  let resultWritten = false;
+  const writeEvent = (event) => {
+    const isResult = event.type === "result";
+    if (isResult && resultWritten)
+      throw new Error(SECOND_RESULT_REFUSAL);
+    stream.write(`${JSON.stringify(event)}
+`);
+    if (isResult)
+      resultWritten = true;
+  };
+  const logAt = (level, message) => {
+    writeEvent({ type: "log", level, message, ts: now().toISOString() });
+  };
+  const debug = (message) => {
+    logAt("debug", message);
+  };
+  const info = (message) => {
+    logAt("info", message);
+  };
+  const warn = (message) => {
+    logAt("warn", message);
+  };
+  const error = (message) => {
+    logAt("error", message);
+  };
+  const emit = (event) => {
+    writeEvent(event);
+  };
+  const result = (payload) => {
+    writeEvent({ type: "result", ok: true, data: payload, ts: now().toISOString() });
+  };
+  return Object.freeze({ info, warn, error, debug, emit, result });
+}
+
+// src/adapters/planner/claude.ts
+import { existsSync as existsSync3 } from "fs";
+import { mkdir as mkdir2, readFile as readFile2 } from "fs/promises";
+import { posix, resolve } from "path";
+
+// src/board/spec-review.ts
+var SPEC_REVIEW_KIND = "spec-review";
+var SPEC_REVIEW_VERDICTS = ["ready", "not-ready"];
+var REVIEW_HEADING = "the review";
+var MISSING_REVIEW_GAP = {
+  heading: REVIEW_HEADING,
+  what: "the review block was not returned"
+};
+var UNNAMED_GAP = {
+  heading: REVIEW_HEADING,
+  what: "the review block judged the spec not ready without naming a gap"
+};
+var VERDICT_BREAK = /[\s_]+/gu;
+function isMapping2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function describeValue2(value) {
+  if (typeof value === "string")
+    return JSON.stringify(value);
+  if (value === null)
+    return "nothing";
+  if (Array.isArray(value))
+    return "a list";
+  if (typeof value === "object")
+    return "a mapping";
+  return `the ${typeof value} ${String(value)}`;
+}
+function messageOf2(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function counted(count, noun) {
+  return count === 1 ? `1 ${noun}` : `${String(count)} ${noun}s`;
+}
+function valueAt(mapping, key) {
+  return Object.hasOwn(mapping, key) ? mapping[key] ?? null : null;
+}
+function stringAt(mapping, key) {
+  const value = valueAt(mapping, key);
+  if (typeof value !== "string" || value.trim() === "")
+    return null;
+  return value;
+}
+function verdictOf(value) {
+  if (typeof value !== "string")
+    return null;
+  const spelled = value.trim().toLowerCase();
+  const word = spelled.replace(VERDICT_BREAK, "-");
+  return SPEC_REVIEW_VERDICTS.includes(word) ? word : null;
+}
+function issueAt(field, text) {
+  return { field, text };
+}
+function readGap(item, field, issues) {
+  if (!isMapping2(item)) {
+    const text = `${field} is ${describeValue2(item)}, not a mapping of heading and what; dropped`;
+    issues.push(issueAt(field, text));
+    return null;
+  }
+  const what = stringAt(item, "what");
+  if (what === null) {
+    const text = `${field}.what is ${describeValue2(valueAt(item, "what"))}, ` + "not a sentence; the gap is dropped";
+    issues.push(issueAt(`${field}.what`, text));
+    return null;
+  }
+  const heading = stringAt(item, "heading");
+  if (heading === null) {
+    const text = `${field}.heading is ${describeValue2(valueAt(item, "heading"))}, ` + `not a heading; the gap is filed under ${REVIEW_HEADING}`;
+    issues.push(issueAt(`${field}.heading`, text));
+  }
+  return { heading: heading ?? REVIEW_HEADING, what };
+}
+function readGaps(document, issues) {
+  const value = valueAt(document, "gaps");
+  if (value === null)
+    return [];
+  if (!Array.isArray(value)) {
+    const text = `gaps is ${describeValue2(value)}, not a list; no gap is read from it`;
+    issues.push(issueAt("gaps", text));
+    return [];
+  }
+  const items = value;
+  const gaps = [];
+  for (const [index, item] of items.entries()) {
+    const gap = readGap(item, `gaps[${String(index)}]`, issues);
+    if (gap !== null)
+      gaps.push(gap);
+  }
+  return gaps;
+}
+function unreadable(answer, block, text) {
+  return { answer, ready: false, gaps: [MISSING_REVIEW_GAP], block, text, issues: [] };
+}
+function judged(verdict, gaps, block, issues) {
+  const line = String(block.span.first);
+  if (verdict === "ready") {
+    return {
+      answer: "ready",
+      ready: true,
+      gaps,
+      block,
+      text: `the rafa:spec-review block at line ${line} judged the spec ready`,
+      issues
+    };
+  }
+  const named = gaps.length === 0 ? [UNNAMED_GAP] : gaps;
+  return {
+    answer: "not-ready",
+    ready: false,
+    gaps: named,
+    block,
+    text: `the rafa:spec-review block at line ${line} judged the spec not ready, ` + `naming ${counted(named.length, "gap")}`,
+    issues
+  };
+}
+function parseSpecReview(output) {
+  const reviews = readRafaBlocks(output).filter((found) => found.kind === SPEC_REVIEW_KIND);
+  const block = reviews.at(-1);
+  if (block === undefined) {
+    return unreadable("absent", null, "the session output holds no rafa:spec-review block");
+  }
+  const line = String(block.span.first);
+  if (!block.closed) {
+    return unreadable("malformed", block, `the rafa:spec-review block at line ${line} is never closed, so its body may have been ` + "cut short and is not read");
+  }
+  let document;
+  try {
+    document = Bun.YAML.parse(block.body);
+  } catch (error) {
+    const text = `the rafa:spec-review block at line ${line} is not valid YAML ` + `(${messageOf2(error)})`;
+    return unreadable("malformed", block, text);
+  }
+  if (!isMapping2(document)) {
+    const text = `the rafa:spec-review block at line ${line} holds ${describeValue2(document)}, ` + "not a mapping of verdict and gaps";
+    return unreadable("malformed", block, text);
+  }
+  const verdict = verdictOf(valueAt(document, "verdict"));
+  if (verdict === null) {
+    const text = `the rafa:spec-review block at line ${line} has a verdict of ` + `${describeValue2(valueAt(document, "verdict"))}, ` + `not one of ${SPEC_REVIEW_VERDICTS.join(", ")}`;
+    return unreadable("malformed", block, text);
+  }
+  const issues = [];
+  return judged(verdict, readGaps(document, issues), block, issues);
+}
+
+// src/utils/claude.ts
+async function getClaudeUsagePercent() {
+  const envPct = process.env["CLAUDE_USAGE_PERCENT"];
+  if (envPct !== undefined) {
+    const pct = Number(envPct);
+    return Number.isFinite(pct) ? Math.max(0, Math.min(100, pct)) : null;
+  }
+  return null;
+}
+async function checkUsage(context) {
+  const pct = await getClaudeUsagePercent();
+  if (pct === null)
+    return false;
+  if (context === "task" && pct >= 90) {
+    activeOutput().warn(`
+Claude usage at ${pct.toFixed(0)}% (>=90%). Pausing after current task to avoid hitting the limit.`);
+    return true;
+  }
+  if (pct >= 80) {
+    activeOutput().warn(`
+Claude usage at ${pct.toFixed(0)}% (>=80%). Monitor closely \u2014 tasks may be interrupted.`);
+  } else if (context === "issue" && pct >= 70) {
+    activeOutput().warn(`
+Claude usage at ${pct.toFixed(0)}% (>=70%). Consider whether to start the next issue.`);
+  } else {
+    activeOutput().info(`
+Claude usage: ${pct.toFixed(0)}%`);
+  }
+  return false;
+}
+var CLAUDE_BIN = "claude";
+var CLAUDE_BASE_ARGS = [
+  "-p",
+  "--dangerously-skip-permissions"
+];
+var SETTING_SOURCES_FLAG = "--setting-sources";
+function claudeArgs(settingSources, flags = []) {
+  return [...CLAUDE_BASE_ARGS, SETTING_SOURCES_FLAG, settingSources.join(","), ...flags];
+}
+var liveSessions = new Set;
+function interruptClaudeSessions() {
+  for (const session of liveSessions)
+    session.kill("SIGINT");
+  return liveSessions.size;
+}
+function claudeSessionEnv() {
+  return {
+    ...process.env,
+    CLAUDE_CODE_ENTRYPOINT: "cli"
+  };
+}
+async function spawnClaude(args, prompt) {
+  if (activeOutputMode() === "json") {
+    const { exitCode } = await spawnClaudeCaptured(args, prompt);
+    return exitCode;
+  }
+  const proc = Bun.spawn([CLAUDE_BIN, ...args], {
+    stdin: new TextEncoder().encode(prompt),
+    stdout: "inherit",
+    stderr: "inherit",
+    env: claudeSessionEnv()
+  });
+  liveSessions.add(proc);
+  try {
+    return await proc.exited ?? 1;
+  } finally {
+    liveSessions.delete(proc);
+  }
+}
+function runClaude(prompt, settingSources, flags = [], spawn = spawnClaude) {
+  return spawn(claudeArgs(settingSources, flags), prompt);
+}
+function writeWholeLines(text, write) {
+  const lines = text.split(`
+`);
+  const rest = lines.pop() ?? "";
+  for (const line of lines)
+    write(line);
+  return rest;
+}
+async function teeToOperator(stream) {
+  const decoder = new TextDecoder;
+  const jsonOutput = activeOutputMode() === "json" ? activeOutput() : null;
+  const writeLine = (line) => {
+    jsonOutput?.info(line);
+  };
+  let text = "";
+  let pending = "";
+  for await (const chunk of stream) {
+    if (jsonOutput === null)
+      process.stdout.write(chunk);
+    const decoded = decoder.decode(chunk, { stream: true });
+    text += decoded;
+    if (jsonOutput !== null)
+      pending = writeWholeLines(pending + decoded, writeLine);
+  }
+  const tail = decoder.decode();
+  if (jsonOutput !== null) {
+    const rest = writeWholeLines(pending + tail, writeLine);
+    if (rest !== "")
+      writeLine(rest);
+  }
+  return text + tail;
+}
+async function spawnClaudeCaptured(args, prompt) {
+  const proc = Bun.spawn([CLAUDE_BIN, ...args], {
+    stdin: new TextEncoder().encode(prompt),
+    stdout: "pipe",
+    stderr: "inherit",
+    env: claudeSessionEnv()
+  });
+  liveSessions.add(proc);
+  let stdout;
+  try {
+    stdout = await teeToOperator(proc.stdout);
+  } finally {
+    await proc.exited;
+    liveSessions.delete(proc);
+  }
+  return { exitCode: await proc.exited, stdout };
+}
+function runClaudeCaptured(prompt, settingSources, flags = [], spawn = spawnClaudeCaptured) {
+  return spawn(claudeArgs(settingSources, flags), prompt);
+}
+
+// src/adapters/planner/claude.ts
+var FAILURE_EXIT_CODE = 1;
+function planFilePath(planDir, fileName) {
+  return posix.join(planDir, fileName);
+}
+
+class ClaudePlannerError extends Error {
+  exitCode;
+  review;
+  constructor(message, exitCode, review = null) {
+    super(message);
+    this.name = "ClaudePlannerError";
+    this.exitCode = exitCode;
+    this.review = review;
+  }
+}
+function createClaudePlanner(options) {
+  const { repoRoot, planDir, settingSources, buildPrompt, spawn = spawnClaudeCaptured } = options;
+  const create = async ({ specPath, stub }) => {
+    const planPath = planFilePath(planDir, `PLAN-${stub}.md`);
+    const prerequisitesPath = planFilePath(planDir, `PREREQUISITES-${stub}.md`);
+    const isWritten = (path) => existsSync3(resolve(repoRoot, path));
+    if (isWritten(planPath)) {
+      throw new ClaudePlannerError(`${planPath} already exists`, FAILURE_EXIT_CODE);
+    }
+    const specContent = await readFile2(resolve(repoRoot, specPath), "utf8");
+    await mkdir2(resolve(repoRoot, planDir), { recursive: true });
+    const session = await runClaudeCaptured(buildPrompt(specContent, stub), settingSources, [], spawn);
+    const review = parseSpecReview(session.stdout);
+    const { exitCode } = session;
+    if (exitCode !== 0) {
+      throw new ClaudePlannerError(`Plan generation failed (exit ${exitCode}).`, exitCode, review);
+    }
+    if (!isWritten(planPath)) {
+      throw new ClaudePlannerError(`The session finished but ${planPath} was not created \u2014 inspect the output above.`, FAILURE_EXIT_CODE, review);
+    }
+    return {
+      planPath,
+      prerequisitesPath: isWritten(prerequisitesPath) ? prerequisitesPath : null,
+      review
+    };
+  };
+  return Object.freeze({ create });
+}
+
+// src/adapters/tracker/issue-values.ts
+var TYPE_MEMBERS = {
+  code: true,
+  bug: true,
+  spike: true,
+  adr: true,
+  chore: true,
+  "package-api": true
+};
+var PRIORITY_MEMBERS = {
+  urgent: true,
+  high: true,
+  medium: true,
+  low: true
+};
+var STATE_MEMBERS = {
+  backlog: true,
+  todo: true,
+  "in-progress": true,
+  "in-review": true,
+  done: true,
+  released: true,
+  cancelled: true
+};
+var ISSUE_TYPES = Object.freeze(Object.keys(TYPE_MEMBERS));
+var ISSUE_PRIORITIES = Object.freeze(Object.keys(PRIORITY_MEMBERS));
+var ISSUE_STATES = Object.freeze(Object.keys(STATE_MEMBERS));
+
+// src/adapters/tracker/github.ts
+var PREFIX2 = "github tracker";
+var GITHUB_LABELS = Object.freeze({
+  modulePrefix: "module:",
+  typePrefix: "type:",
+  priorityPrefix: "priority:",
+  needsTriage: "needs-triage",
+  blockedByPrefix: "blocked-by:OPT-"
+});
+var VIEW_FIELDS = "number,title,body,state,stateReason,labels,url";
+var LIST_FIELDS = "number,url,labels";
+var DEFAULT_FIND_LIMIT = 30;
+var NOT_PLANNED = "NOT_PLANNED";
+var ISSUE_NUMBER = /^[1-9]\d*$/;
+var REPO_PART = /^[\w.-]+$/;
+var CREATED_ISSUE_URL = /^https:\/\/[^\s/]+\/[\w.-]+\/[\w.-]+\/issues\/([1-9]\d*)$/;
+var REST_STATES = {
+  backlog: "open",
+  todo: "open",
+  "in-progress": "open",
+  "in-review": "open",
+  done: "closed",
+  released: "closed",
+  cancelled: "closed"
+};
+function createGhRunner(options) {
+  const { cwd, command = "gh" } = options;
+  return async (args) => {
+    try {
+      const proc = Bun.spawn([command, ...args], {
+        cwd,
+        stdin: "ignore",
+        stdout: "pipe",
+        stderr: "pipe"
+      });
+      const [stdout, stderr, exitCode] = await Promise.all([
+        new Response(proc.stdout).text(),
+        new Response(proc.stderr).text(),
+        proc.exited
+      ]);
+      return { ok: exitCode === 0, stdout, stderr };
+    } catch (error) {
+      return { ok: false, stdout: "", stderr: `could not run ${command} in ${cwd}: ${messageOf(error)}` };
+    }
+  };
+}
+function isOneOf(members, value) {
+  return typeof value === "string" && members.includes(value);
+}
+function isIssueNumber(value) {
+  return typeof value === "string" && ISSUE_NUMBER.test(value) && Number.isSafeInteger(Number(value));
+}
+function isRepoName(value) {
+  if (typeof value !== "string")
+    return false;
+  const parts = value.split("/");
+  return parts.length === 2 && parts.every((part) => REPO_PART.test(part) && part !== "." && part !== "..");
+}
+function isLabelPart(value) {
+  return typeof value === "string" && !value.includes(",");
+}
+function optionalFlag(name, value) {
+  return value === undefined ? [] : [name, value];
+}
+function detailOf(result) {
+  return result.stderr.trim() || result.stdout.trim() || "it exited non-zero and wrote nothing";
+}
+var DRAFT_CHECKS = [
+  ["opt", (value) => typeof value === "number" && Number.isFinite(value), "a number"],
+  ["title", (value) => typeof value === "string", "a string"],
+  ["body", (value) => typeof value === "string", "a string"],
+  ["type", (value) => isOneOf(ISSUE_TYPES, value), `one of: ${ISSUE_TYPES.join(", ")}`],
+  ["module", isLabelPart, "a string holding no comma"],
+  [
+    "priority",
+    (value) => value === null || isOneOf(ISSUE_PRIORITIES, value),
+    `null or one of: ${ISSUE_PRIORITIES.join(", ")}`
+  ],
+  ["project", (value) => value === null || typeof value === "string", "a string or null"],
+  [
+    "blockedBy",
+    (value) => Array.isArray(value) && value.every((item) => Number.isSafeInteger(item) && item > 0),
+    "a list of positive whole numbers"
+  ]
+];
+function draftProblem(draft) {
+  if (!isMapping(draft))
+    return `the draft is ${describeValue(draft)}, expected a mapping`;
+  const failed = DRAFT_CHECKS.find(([key, accepts]) => !accepts(draft[key]));
+  return failed === undefined ? null : `${failed[0]} is ${describeValue(draft[failed[0]])}, expected ${failed[2]}`;
+}
+function labelsFor(draft) {
+  const priority = draft.priority === null ? GITHUB_LABELS.needsTriage : `${GITHUB_LABELS.priorityPrefix}${draft.priority}`;
+  return [
+    `${GITHUB_LABELS.modulePrefix}${draft.module}`,
+    `${GITHUB_LABELS.typePrefix}${draft.type}`,
+    ...draft.blockedBy.map((opt) => `${GITHUB_LABELS.blockedByPrefix}${opt}`),
+    priority
+  ];
+}
+function issueNumberOfRef(ref) {
+  if (ref.kind !== "github") {
+    throw new Error(`${PREFIX2}: refused a ref of kind ${describeValue(ref.kind)}; this tracker reads github refs only`);
+  }
+  if (!isIssueNumber(ref.externalId)) {
+    throw new Error(`${PREFIX2}: externalId ${describeValue(ref.externalId)} is not a GitHub issue number,` + " expected a positive whole number with no leading zero");
+  }
+  if (ref.repo !== undefined && !isRepoName(ref.repo)) {
+    throw new Error(`${PREFIX2}: repo ${describeValue(ref.repo)} is not a repository, expected owner/name`);
+  }
+  return ref.externalId;
+}
+function parseJson(stdout, command) {
+  try {
+    return JSON.parse(stdout);
+  } catch (error) {
+    throw new Error(`${PREFIX2}: ${command} wrote output that is not JSON: ${messageOf(error)}`, {
+      cause: error
+    });
+  }
+}
+function labelNames(value) {
+  if (!Array.isArray(value))
+    return null;
+  const names = value.map((label) => isMapping(label) && typeof label["name"] === "string" ? label["name"] : null);
+  return names.every((name) => name !== null) ? names : null;
+}
+function viewProblem(payload, number) {
+  if (!isMapping(payload))
+    return `${describeValue(payload)}, expected a mapping`;
+  const { title, body, state, stateReason, labels, url } = payload;
+  if (typeof url !== "string" || !url.endsWith(`/issues/${number}`)) {
+    return `url ${describeValue(url)}, expected an issue URL ending /issues/${number},` + ` where a pull request URL ends /pull/${number}`;
+  }
+  if (typeof title !== "string")
+    return `title ${describeValue(title)}, expected a string`;
+  if (typeof body !== "string")
+    return `body ${describeValue(body)}, expected a string`;
+  if (state !== "OPEN" && state !== "CLOSED")
+    return `state ${describeValue(state)}, expected "OPEN" or "CLOSED"`;
+  if (stateReason !== null && typeof stateReason !== "string") {
+    return `stateReason ${describeValue(stateReason)}, expected a string or null`;
+  }
+  return labelNames(labels) === null ? "labels that are not a list of named labels" : null;
+}
+function viewedIssue(stdout, number) {
+  const command = `gh issue view ${number}`;
+  const payload = parseJson(stdout, command);
+  const problem = viewProblem(payload, number);
+  if (problem !== null)
+    throw new Error(`${PREFIX2}: ${command} answered ${problem}`);
+  const checked = payload;
+  return { ...checked, labels: labelNames(checked.labels) ?? [] };
+}
+function listedIssues(stdout) {
+  const command = "gh issue list";
+  const payload = parseJson(stdout, command);
+  if (!Array.isArray(payload)) {
+    throw new Error(`${PREFIX2}: ${command} answered ${describeValue(payload)}, expected a list`);
+  }
+  return payload.map((row, index) => {
+    const refuse = (problem) => new Error(`${PREFIX2}: ${command} answered row ${index} ${problem}`);
+    if (!isMapping(row))
+      throw refuse(`${describeValue(row)}, expected a mapping`);
+    const { number, url } = row;
+    const labels = labelNames(row["labels"]);
+    if (typeof number !== "number" || !isIssueNumber(String(number))) {
+      throw refuse(`with number ${describeValue(number)}, expected an issue number`);
+    }
+    if (typeof url !== "string")
+      throw refuse(`with url ${describeValue(url)}, expected a string`);
+    if (labels === null)
+      throw refuse("with labels that are not a list of named labels");
+    return { number, url, labels };
+  });
+}
+function labelValue(labels, prefix) {
+  return labels.find((label) => label.startsWith(prefix))?.slice(prefix.length);
+}
+function stateOf(viewed) {
+  if (viewed.state === "OPEN")
+    return "todo";
+  return viewed.stateReason === NOT_PLANNED ? "cancelled" : "done";
+}
+function issueOf(ref, viewed) {
+  const type = labelValue(viewed.labels, GITHUB_LABELS.typePrefix);
+  const priority = labelValue(viewed.labels, GITHUB_LABELS.priorityPrefix);
+  return {
+    opt: ref.opt,
+    title: viewed.title,
+    body: viewed.body,
+    type: isOneOf(ISSUE_TYPES, type) ? type : "code",
+    module: labelValue(viewed.labels, GITHUB_LABELS.modulePrefix) ?? "unassigned",
+    priority: isOneOf(ISSUE_PRIORITIES, priority) ? priority : null,
+    project: null,
+    blockedBy: viewed.labels.map((label) => label.startsWith(GITHUB_LABELS.blockedByPrefix) ? label.slice(GITHUB_LABELS.blockedByPrefix.length) : "").filter(isIssueNumber).map(Number),
+    ref: { ...ref, url: viewed.url },
+    state: stateOf(viewed)
+  };
+}
+function readBackState(state) {
+  if (REST_STATES[state] === "open")
+    return "todo";
+  return state === "cancelled" ? "cancelled" : "done";
+}
+function stateQueryRefusal(state) {
+  const bucket = REST_STATES[state];
+  const siblings = ISSUE_STATES.filter((other) => other !== state && REST_STATES[other] === bucket);
+  return `${PREFIX2}: find cannot narrow by state ${describeValue(state)}: GitHub holds an issue open or` + ` closed, and ${state} shares ${bucket} with ${siblings.join(", ")}, so a result would include` + " those too. Search without a state, then read each issue with get.";
+}
+function createGithubTracker(options) {
+  const { gh } = options;
+  let knownLabels = new Set;
+  async function run(args, command) {
+    const result = await gh(args);
+    if (!result.ok)
+      throw new Error(`${PREFIX2}: ${command} failed: ${detailOf(result)}`);
+    return result.stdout;
+  }
+  async function ensureLabels(names) {
+    const missing = [...new Set(names)].filter((name) => !knownLabels.has(name));
+    for (const name of missing) {
+      await run(["label", "create", name, "--force"], `gh label create ${describeValue(name)}`);
+    }
+    knownLabels = new Set([...knownLabels, ...missing]);
+  }
+  const tracker = {
+    kind: "github",
+    capabilities: () => ({
+      projects: false,
+      customFields: false,
+      issueTypes: false
+    }),
+    preflight: async () => {
+      try {
+        const auth = await gh(["auth", "status"]);
+        if (!auth.ok)
+          return { ok: false, reason: `gh auth status: ${detailOf(auth)}` };
+        const repo = await gh(["repo", "view", "--json", "nameWithOwner"]);
+        if (!repo.ok)
+          return { ok: false, reason: `gh repo view: ${detailOf(repo)}` };
+        return { ok: true };
+      } catch (error) {
+        return { ok: false, reason: `gh could not be run: ${messageOf(error)}` };
+      }
+    },
+    create: async (draft) => {
+      const problem = draftProblem(draft);
+      if (problem !== null)
+        throw new TypeError(`${PREFIX2}: refused to file an invalid draft: ${problem}`);
+      const labels = labelsFor(draft);
+      await ensureLabels(labels);
+      const stdout = await run([
+        "issue",
+        "create",
+        "--title",
+        draft.title,
+        "--body",
+        draft.body,
+        ...labels.flatMap((label) => ["--label", label])
+      ], "gh issue create");
+      const url = stdout.trim().split(`
+`).at(-1) ?? "";
+      const number = CREATED_ISSUE_URL.exec(url)?.[1];
+      if (number === undefined) {
+        throw new Error(`${PREFIX2}: gh issue create exited 0 and printed no issue URL, so the issue may exist` + ` unrecorded; it wrote ${describeValue(stdout)}`);
+      }
+      return { opt: draft.opt, kind: "github", externalId: number, url, module: draft.module };
+    },
+    get: async (ref) => {
+      const number = issueNumberOfRef(ref);
+      const stdout = await run(["issue", "view", number, ...optionalFlag("--repo", ref.repo), "--json", VIEW_FIELDS], `gh issue view ${number}`);
+      return issueOf(ref, viewedIssue(stdout, number));
+    },
+    find: async (query) => {
+      if (query.state !== undefined)
+        throw new Error(stateQueryRefusal(query.state));
+      if (query.module !== undefined && !isLabelPart(query.module)) {
+        throw new TypeError(`${PREFIX2}: find refused module ${describeValue(query.module)}, expected a string holding no comma`);
+      }
+      const moduleLabel = query.module === undefined ? undefined : `${GITHUB_LABELS.modulePrefix}${query.module}`;
+      const typeLabel = query.type === undefined ? undefined : `${GITHUB_LABELS.typePrefix}${query.type}`;
+      const stdout = await run([
+        "issue",
+        "list",
+        "--state",
+        "all",
+        "--json",
+        LIST_FIELDS,
+        "--limit",
+        String(query.limit ?? DEFAULT_FIND_LIMIT),
+        ...optionalFlag("--label", moduleLabel),
+        ...optionalFlag("--label", typeLabel),
+        ...optionalFlag("--search", query.text)
+      ], "gh issue list");
+      return listedIssues(stdout).map((row) => {
+        const module = labelValue(row.labels, GITHUB_LABELS.modulePrefix);
+        const ref = { opt: 0, kind: "github", externalId: String(row.number), url: row.url };
+        return module === undefined ? ref : { ...ref, module };
+      });
+    },
+    comment: async (ref, body) => {
+      const number = issueNumberOfRef(ref);
+      if (typeof body !== "string") {
+        throw new TypeError(`${PREFIX2}: refused a comment body ${describeValue(body)}, expected a string`);
+      }
+      await run(["issue", "comment", number, ...optionalFlag("--repo", ref.repo), "--body", body], `gh issue comment ${number}`);
+    },
+    transition: async (ref, state) => {
+      const number = issueNumberOfRef(ref);
+      if (!isOneOf(ISSUE_STATES, state)) {
+        throw new TypeError(`${PREFIX2}: refused state ${describeValue(state)}, expected one of: ${ISSUE_STATES.join(", ")}`);
+      }
+      if (REST_STATES[state] === "closed") {
+        const path = `repos/${ref.repo ?? "{owner}/{repo}"}/issues/${number}`;
+        const reason = state === "cancelled" ? "not_planned" : "completed";
+        await run(["api", path, "-X", "PATCH", "-f", "state=closed", "-f", `state_reason=${reason}`], `gh api PATCH ${path}`);
+      } else {
+        await run(["issue", "reopen", number, ...optionalFlag("--repo", ref.repo)], `gh issue reopen ${number}`);
+      }
+      const readBack = readBackState(state);
+      if (readBack === state)
+        return {};
+      return {
+        warning: `issue #${number} is now ${REST_STATES[state]}, but GitHub Issues without a board` + ` holds no ${state} state, so get reads it back as ${readBack}`
+      };
+    }
+  };
+  return Object.freeze(tracker);
+}
+
+// src/adapters/tracker/local.ts
+import { mkdir as mkdir3, readdir, readFile as readFile3, writeFile } from "fs/promises";
+import { join as join4 } from "path";
+var PREFIX3 = "local tracker";
+var FRONTMATTER = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/;
+var ISSUE_NUMBER2 = /^[1-9]\d*$/;
+var ISSUE_EXTENSION = ".md";
+function isString2(value) {
+  return typeof value === "string";
+}
+function isFiniteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value);
+}
+function oneOf2(members) {
+  return (value) => typeof value === "string" && members.includes(value);
+}
+function orNull(accepts) {
+  return (value) => value === null || accepts(value);
+}
+function listOf(accepts) {
+  return (value) => Array.isArray(value) && value.every(accepts);
+}
+var FIELD_CHECKS = {
+  opt: [isFiniteNumber, "a number"],
+  type: [oneOf2(ISSUE_TYPES), `one of: ${ISSUE_TYPES.join(", ")}`],
+  module: [isString2, "a string"],
+  priority: [orNull(oneOf2(ISSUE_PRIORITIES)), `null or one of: ${ISSUE_PRIORITIES.join(", ")}`],
+  project: [orNull(isString2), "a string or null"],
+  title: [isString2, "a string"],
+  blockedBy: [listOf(isFiniteNumber), "a list of numbers"],
+  state: [oneOf2(ISSUE_STATES), `one of: ${ISSUE_STATES.join(", ")}`],
+  fallbackReason: [orNull(isString2), "a string or null"],
+  capturedAt: [isString2, "a string"],
+  comments: [listOf(isString2), "a list of strings"]
+};
+function frontmatterProblem(value) {
+  if (!isMapping(value)) {
+    return `the frontmatter is ${describeValue(value)}, expected a mapping`;
+  }
+  for (const [key, [accepts, expected]] of Object.entries(FIELD_CHECKS)) {
+    if (!accepts(value[key])) {
+      return `${key} is ${describeValue(value[key])}, expected ${expected}`;
+    }
+  }
+  return null;
+}
+function hasCode2(error, code) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === code;
+}
+function parseIssueNumber(text) {
+  if (!ISSUE_NUMBER2.test(text))
+    return null;
+  const number = Number(text);
+  return Number.isSafeInteger(number) ? number : null;
+}
+function issueNumberOfFile(name) {
+  return name.endsWith(ISSUE_EXTENSION) ? parseIssueNumber(name.slice(0, -ISSUE_EXTENSION.length)) : null;
+}
+function issuePath(issuesDir, number) {
+  return join4(issuesDir, `${number}${ISSUE_EXTENSION}`);
+}
+async function issueNumbers(issuesDir) {
+  let names;
+  try {
+    names = await readdir(issuesDir);
+  } catch (error) {
+    if (hasCode2(error, "ENOENT"))
+      return [];
+    throw error;
+  }
+  return names.map(issueNumberOfFile).filter((number) => number !== null).sort((a, b) => a - b);
+}
+function localIssuesDir(repoRoot) {
+  return join4(repoRoot, ".rafa", "issues");
+}
+function renderLocalIssue(record) {
+  const { draft } = record;
+  const frontmatter = {
+    opt: draft.opt,
+    type: draft.type,
+    module: draft.module,
+    priority: draft.priority,
+    project: draft.project,
+    title: draft.title,
+    blockedBy: draft.blockedBy,
+    state: record.state,
+    fallbackReason: record.fallbackReason,
+    capturedAt: record.capturedAt,
+    comments: record.comments
+  };
+  const problem = frontmatterProblem(frontmatter) ?? (typeof draft.body === "string" ? null : `body is ${describeValue(draft.body)}, expected a string`);
+  if (problem !== null) {
+    throw new TypeError(`${PREFIX3}: refused to write an invalid issue: ${problem}`);
+  }
+  return `---
+${Bun.YAML.stringify(frontmatter, null, 2)}
+---
+${draft.body}`;
+}
+function parseLocalIssue(contents, sourcePath) {
+  const at = sourcePath === undefined ? "" : ` at ${sourcePath}`;
+  const match = FRONTMATTER.exec(contents);
+  if (match === null) {
+    throw new Error(`${PREFIX3}: the issue${at} has no YAML frontmatter block`);
+  }
+  const [, block = "", body = ""] = match;
+  let meta;
+  try {
+    meta = Bun.YAML.parse(block);
+  } catch (error) {
+    throw new Error(`${PREFIX3}: invalid issue${at}: ${messageOf(error)}`, { cause: error });
+  }
+  const problem = frontmatterProblem(meta);
+  if (problem !== null) {
+    throw new Error(`${PREFIX3}: invalid issue${at}: ${problem}`);
+  }
+  const fields = meta;
+  return {
+    draft: {
+      opt: fields.opt,
+      title: fields.title,
+      body,
+      type: fields.type,
+      module: fields.module,
+      priority: fields.priority,
+      project: fields.project,
+      blockedBy: fields.blockedBy
+    },
+    fallbackReason: fields.fallbackReason,
+    capturedAt: fields.capturedAt,
+    state: fields.state,
+    comments: fields.comments
+  };
+}
+function warnThroughActiveOutput2(message) {
+  activeOutput().warn(message);
+}
+async function listLocalIssues(issuesDir, warn = warnThroughActiveOutput2) {
+  const numbers = await issueNumbers(issuesDir);
+  const settled = await Promise.allSettled(numbers.map(async (number) => {
+    const path = issuePath(issuesDir, number);
+    let contents;
+    try {
+      contents = await readFile3(path, "utf8");
+    } catch (error) {
+      throw new Error(`${PREFIX3}: could not read ${path}: ${messageOf(error)}`, { cause: error });
+    }
+    return { number, path, record: parseLocalIssue(contents, path) };
+  }));
+  return settled.flatMap((result) => {
+    if (result.status === "fulfilled")
+      return [result.value];
+    warn(`${messageOf(result.reason)}; find skipped it`);
+    return [];
+  });
+}
+function matchesQuery(record, query) {
+  const { draft } = record;
+  if (query.module !== undefined && draft.module !== query.module)
+    return false;
+  if (query.type !== undefined && draft.type !== query.type)
+    return false;
+  if (query.state !== undefined && record.state !== query.state)
+    return false;
+  if (query.text === undefined)
+    return true;
+  return `${draft.title}
+${draft.body}`.toLowerCase().includes(query.text.toLowerCase());
+}
+function refFor(number, opt) {
+  return { opt, kind: "local", externalId: String(number), url: null };
+}
+function issueNumberOfRef2(ref) {
+  if (ref.kind !== "local") {
+    throw new Error(`${PREFIX3}: refused a ref of kind ${describeValue(ref.kind)}; this tracker reads local refs only`);
+  }
+  const number = typeof ref.externalId === "string" ? parseIssueNumber(ref.externalId) : null;
+  if (number === null) {
+    throw new Error(`${PREFIX3}: externalId ${describeValue(ref.externalId)} is not a local issue number,` + " expected a positive whole number with no leading zero");
+  }
+  return number;
+}
+function createLocalTracker(options) {
+  const { issuesDir, fallbackReason } = options;
+  const now = options.now ?? (() => new Date().toISOString());
+  const warn = options.warn ?? warnThroughActiveOutput2;
+  async function read(ref) {
+    const number = issueNumberOfRef2(ref);
+    const path = issuePath(issuesDir, number);
+    let contents;
+    try {
+      contents = await readFile3(path, "utf8");
+    } catch (cause) {
+      throw new Error(`${PREFIX3}: no issue ${number} under ${issuesDir}`, { cause });
+    }
+    return { number, record: parseLocalIssue(contents, path) };
+  }
+  async function rewrite(number, record) {
+    const contents = renderLocalIssue(record);
+    await writeFile(issuePath(issuesDir, number), contents, "utf8");
+  }
+  const tracker = {
+    kind: "local",
+    capabilities: () => ({
+      projects: false,
+      customFields: false,
+      issueTypes: false
+    }),
+    preflight: async () => ({ ok: true }),
+    create: async (draft) => {
+      const contents = renderLocalIssue({
+        draft,
+        fallbackReason,
+        capturedAt: now(),
+        state: "todo",
+        comments: []
+      });
+      await mkdir3(issuesDir, { recursive: true });
+      const held = await issueNumbers(issuesDir);
+      for (let number = (held.at(-1) ?? 0) + 1;Number.isSafeInteger(number); number += 1) {
+        try {
+          await writeFile(issuePath(issuesDir, number), contents, { encoding: "utf8", flag: "wx" });
+          return refFor(number, draft.opt);
+        } catch (error) {
+          if (!hasCode2(error, "EEXIST"))
+            throw error;
+        }
+      }
+      throw new Error(`${PREFIX3}: no issue number is left under ${issuesDir}`);
+    },
+    get: async (ref) => {
+      const { record } = await read(ref);
+      return { ...record.draft, ref, state: record.state };
+    },
+    find: async (query) => {
+      const matched = (await listLocalIssues(issuesDir, warn)).filter(({ record }) => matchesQuery(record, query));
+      return matched.slice(0, query.limit ?? matched.length).map(({ number, record }) => refFor(number, record.draft.opt));
+    },
+    comment: async (ref, body) => {
+      const { number, record } = await read(ref);
+      await rewrite(number, { ...record, comments: [...record.comments, `${now()}: ${body}`] });
+    },
+    transition: async (ref, state) => {
+      const { number, record } = await read(ref);
+      await rewrite(number, { ...record, state });
+      return {};
+    }
+  };
+  return Object.freeze(tracker);
+}
+
+// src/adapters/registry.ts
+var REFUSAL = "adapter registry";
+var PORT_VERSIONS = Object.freeze({
+  tracker: 1,
+  store: 1,
+  learning: 1,
+  output: 1,
+  planner: 1
+});
+var SERVED_VERSIONS = new Map(Object.entries(PORT_VERSIONS));
+var PORT_TYPE_LIST = [...SERVED_VERSIONS.keys()].join(", ");
+function checkPortType(port) {
+  if (!SERVED_VERSIONS.has(port)) {
+    throw new TypeError(`${REFUSAL}: port is ${describeValue(port)}, expected one of: ${PORT_TYPE_LIST}`);
+  }
+}
+function accept(adapter, held) {
+  if (typeof adapter !== "object" || adapter === null) {
+    throw new TypeError(`${REFUSAL}: an adapter is ${describeValue(adapter)}, expected a mapping`);
+  }
+  const { port, kind, portVersion, create } = adapter;
+  checkPortType(port);
+  if (typeof kind !== "string" || kind === "") {
+    throw new TypeError(`${REFUSAL}: a ${port} adapter has kind ${describeValue(kind)}, expected a non-empty name`);
+  }
+  const key = `${port}/${kind}`;
+  if (typeof create !== "function") {
+    throw new TypeError(`${REFUSAL}: ${key} has create ${describeValue(create)}, expected a function`);
+  }
+  const served = SERVED_VERSIONS.get(port);
+  if (portVersion !== served) {
+    throw new Error(`${REFUSAL}: ${key} implements ${port} port version ${describeValue(portVersion)},` + ` and core serves ${port} port version ${served}`);
+  }
+  if (held.some((other) => other.port === port && other.kind === kind)) {
+    throw new Error(`${REFUSAL}: ${key} is already registered`);
+  }
+  return Object.freeze({ port, kind, portVersion, create });
+}
+function indexByPort(adapters) {
+  const only = (port) => new Map(adapters.filter((adapter) => adapter.port === port).map((adapter) => [adapter.kind, adapter]));
+  return {
+    tracker: only("tracker"),
+    store: only("store"),
+    learning: only("learning"),
+    output: only("output"),
+    planner: only("planner")
+  };
+}
+function createAdapterRegistry(adapters = []) {
+  const held = adapters.reduce((accepted, adapter) => [...accepted, accept(adapter, accepted)], []);
+  const byPort = indexByPort(held);
+  const registry = {
+    register: (adapter) => createAdapterRegistry([...held, adapter]),
+    find: (port, kind) => SERVED_VERSIONS.has(port) ? byPort[port].get(kind) : undefined,
+    resolve: (port, kind) => {
+      checkPortType(port);
+      const adapter = byPort[port].get(kind);
+      if (adapter !== undefined)
+        return adapter;
+      const registered = [...byPort[port].keys()];
+      const listed = registered.length === 0 ? "none" : registered.join(", ");
+      throw new Error(`${REFUSAL}: no ${port} adapter is registered as ${describeValue(kind)};` + ` registered: ${listed}`);
+    },
+    kinds: (port) => {
+      checkPortType(port);
+      return [...byPort[port].keys()];
+    }
+  };
+  return Object.freeze(registry);
+}
+var STORE_OPENERS = {
+  sqlite: openSqliteStore,
+  ndjson: openNdjsonStore
+};
+var CORE_ADAPTERS = [
+  ...STORE_BACKENDS.map((backend) => ({
+    port: "store",
+    kind: backend,
+    portVersion: PORT_VERSIONS.store,
+    create: ({ repoRoot }) => STORE_OPENERS[backend](repoRoot)
+  })),
+  {
+    port: "output",
+    kind: "text",
+    portVersion: PORT_VERSIONS.output,
+    create: ({ stream = process.stdout, verbosity = 0 }) => createTextOutput({ verbosity, stream })
+  },
+  {
+    port: "output",
+    kind: "json",
+    portVersion: PORT_VERSIONS.output,
+    create: ({ stream = process.stdout }) => createJsonOutput({ stream })
+  },
+  {
+    port: "tracker",
+    kind: "local",
+    portVersion: PORT_VERSIONS.tracker,
+    create: ({ repoRoot, fallbackReason = null }) => createLocalTracker({
+      issuesDir: localIssuesDir(repoRoot),
+      fallbackReason
+    })
+  },
+  {
+    port: "tracker",
+    kind: "github",
+    portVersion: PORT_VERSIONS.tracker,
+    create: ({ repoRoot, gh }) => createGithubTracker({ gh: gh ?? createGhRunner({ cwd: repoRoot }) })
+  },
+  {
+    port: "learning",
+    kind: "local",
+    portVersion: PORT_VERSIONS.learning,
+    create: ({ repoRoot }) => createLocalLearning({ instinctsDir: localInstinctsDir(repoRoot) })
+  },
+  {
+    port: "planner",
+    kind: "claude",
+    portVersion: PORT_VERSIONS.planner,
+    create: ({ repoRoot, settingSources, planPrompt, planDir, claude }) => {
+      if (!Array.isArray(settingSources)) {
+        throw new TypeError(`${REFUSAL}: planner/claude has settingSources ${describeValue(settingSources)} in its context,` + " expected a list of setting sources");
+      }
+      if (typeof planPrompt !== "function") {
+        throw new TypeError(`${REFUSAL}: planner/claude has planPrompt ${describeValue(planPrompt)} in its context,` + " expected a function");
+      }
+      if (typeof planDir !== "string") {
+        throw new TypeError(`${REFUSAL}: planner/claude has planDir ${describeValue(planDir)} in its context,` + " expected a directory path");
+      }
+      return createClaudePlanner({ repoRoot, planDir, settingSources, buildPrompt: planPrompt, spawn: claude });
+    }
+  }
+];
+var CORE_ADAPTER_REGISTRY = createAdapterRegistry(CORE_ADAPTERS);
+
+// src/effort/store/index.ts
+function describeValue3(value) {
+  if (typeof value === "string")
+    return JSON.stringify(value);
+  if (typeof value === "object" && value !== null)
+    return "an object";
+  return String(value);
+}
+function selectEffortStore(repoRoot, config) {
+  const adapter = CORE_ADAPTER_REGISTRY.find("store", config.store);
+  if (adapter === undefined) {
+    const expected = CORE_ADAPTER_REGISTRY.kinds("store").join(", ");
+    throw new TypeError(`effort store: store is ${describeValue3(config.store)},` + ` expected one of: ${expected}`);
+  }
+  return adapter.create({ repoRoot });
+}
+
+export { EFFORT_KEY_PROJECTIONS, openNdjsonStore, sqliteStorePath, LONE_SURROGATE, withSqliteStore, writeSqliteStore, openSqliteStore, getClaudeUsagePercent, checkUsage, interruptClaudeSessions, runClaude, runClaudeCaptured, planFilePath, ClaudePlannerError, createGhRunner, createLocalTracker, PORT_VERSIONS, createAdapterRegistry, CORE_ADAPTER_REGISTRY, selectEffortStore };