@forwardimpact/libwiki 0.1.3 → 0.2.0

package/src/commands/audit.js

@@ -0,0 +1,354 @@
+import { readFileSync, readdirSync, statSync, existsSync } from "node:fs";
+import fsAsync from "node:fs/promises";
+import path from "node:path";
+import { Finder } from "@forwardimpact/libutil";
+import {
+  ACTIVE_CLAIMS_HEADING,
+  ACTIVE_CLAIMS_TABLE_HEADER,
+  CUTOVER_ISO_WEEK,
+  DECISION_HEADING,
+  MEMO_INBOX_MARKER,
+  PRIORITY_INDEX_HEADING,
+  SUMMARY_LINE_BUDGET,
+  WEEKLY_LOG_LINE_BUDGET,
+} from "../constants.js";
+import { parseClaims, filterExpired } from "../active-claims.js";
+
+const SUMMARY_H1_RE = /^# [A-Z].* — Summary$/;
+const WEEKLY_LOG_NAME_RE = /^[a-z-]+-(\d{4})-W(\d{2})\.md$/;
+const WEEKLY_LOG_PART_NAME_RE = /^[a-z-]+-(\d{4})-W(\d{2})-part\d+\.md$/;
+const WEEKLY_LOG_H1_RE = /^# .* — \d{4}-W\d{2}(?: \(part \d+ of \d+\))?$/;
+const ENTRY_RE = /^## \d{4}-\d{2}-\d{2}(?:[\s(].*)?$/;
+
+const EXCLUDED_SUMMARY_BASES = new Set(["MEMORY.md", "Home.md", "STATUS.md"]);
+const NON_SUMMARY_PREFIXES = [
+  "storyboard-",
+  "downstream-",
+  "memory-protocol-",
+  "kata-interview-",
+  "fit-trace-",
+];
+
+function hasNonSummaryPrefix(base) {
+  return NON_SUMMARY_PREFIXES.some((p) => base.startsWith(p));
+}
+
+function isSummaryFile(wikiRoot, filePath) {
+  const rel = path.relative(wikiRoot, filePath);
+  if (rel.includes(path.sep) || !rel.endsWith(".md")) return false;
+  const base = path.basename(rel);
+  if (EXCLUDED_SUMMARY_BASES.has(base)) return false;
+  if (hasNonSummaryPrefix(base)) return false;
+  if (WEEKLY_LOG_NAME_RE.test(base) || WEEKLY_LOG_PART_NAME_RE.test(base)) {
+    return false;
+  }
+  try {
+    const text = readFileSync(filePath, "utf-8");
+    const firstLine = text.split("\n").find((l) => l.trim() !== "");
+    return Boolean(firstLine && SUMMARY_H1_RE.test(firstLine));
+  } catch {
+    return false;
+  }
+}
+
+function listMdFiles(wikiRoot) {
+  if (!existsSync(wikiRoot)) return [];
+  return readdirSync(wikiRoot)
+    .filter((e) => e.endsWith(".md"))
+    .map((e) => path.join(wikiRoot, e))
+    .filter((f) => {
+      try {
+        return statSync(f).isFile();
+      } catch {
+        return false;
+      }
+    });
+}
+
+function countLines(text) {
+  return text.split("\n").length - (text.endsWith("\n") ? 1 : 0);
+}
+
+function compareIsoWeek(a, b) {
+  return a.localeCompare(b);
+}
+
+function isoWeekForFile(base) {
+  const match =
+    base.match(WEEKLY_LOG_NAME_RE) || base.match(WEEKLY_LOG_PART_NAME_RE);
+  if (!match) return null;
+  return `${match[1]}-W${match[2]}`;
+}
+
+function pushFail(findings, level, message) {
+  findings.push({ level, message });
+}
+
+function inGraceWindow(graceUntil, today) {
+  return Boolean(graceUntil && graceUntil >= today);
+}
+
+function checkSummaryStructure(f, text, fileLines, h2s, findings) {
+  const firstLine = fileLines.find((l) => l.trim() !== "");
+  if (!firstLine || !SUMMARY_H1_RE.test(firstLine)) {
+    pushFail(findings, "fail", `sections: ${f} missing H1 '# ... — Summary'`);
+  }
+  if (!/^\*\*Last run\*\*:/m.test(text)) {
+    pushFail(findings, "fail", `sections: ${f} missing '**Last run**:' line`);
+  }
+  if (h2s.length > 0 && h2s[0] !== "Message Inbox") {
+    pushFail(
+      findings,
+      "fail",
+      `sections: ${f} first H2 is '${h2s[0]}', expected 'Message Inbox'`,
+    );
+  }
+  if (h2s.indexOf("Message Inbox") !== -1) {
+    const markerIdx = fileLines.findIndex(
+      (l) => l.trim() === MEMO_INBOX_MARKER,
+    );
+    if (markerIdx === -1) {
+      pushFail(
+        findings,
+        "fail",
+        `sections: ${f} missing <!-- memo:inbox --> marker`,
+      );
+    }
+  }
+}
+
+function checkSummaryOrdering(f, h2s, findings) {
+  let seenBlockers = false;
+  for (const h of h2s) {
+    if (h === "Open Blockers") {
+      seenBlockers = true;
+      continue;
+    }
+    if (seenBlockers) {
+      pushFail(
+        findings,
+        "fail",
+        `sections: ${f} '${h}' appears after 'Open Blockers'`,
+      );
+    }
+  }
+}
+
+function checkSummaryFile(f, findings, grace) {
+  const text = readFileSync(f, "utf-8");
+  const lines = countLines(text);
+  if (lines > SUMMARY_LINE_BUDGET) {
+    pushFail(
+      findings,
+      grace ? "warn" : "fail",
+      `budget: ${f} has ${lines} lines (limit ${SUMMARY_LINE_BUDGET})`,
+    );
+  }
+  const fileLines = text.split("\n");
+  const h2s = [];
+  for (const line of fileLines) {
+    const m = line.match(/^## (.+)$/);
+    if (m) h2s.push(m[1].trim());
+  }
+  checkSummaryStructure(f, text, fileLines, h2s, findings);
+  checkSummaryOrdering(f, h2s, findings);
+}
+
+function checkSummaries(wikiRoot, files, findings, options) {
+  const grace = inGraceWindow(options.graceUntil, options.today);
+  for (const f of files) {
+    if (!isSummaryFile(wikiRoot, f)) continue;
+    checkSummaryFile(f, findings, grace);
+  }
+}
+
+function entryHasDecision(allLines, startIdx) {
+  let nonBlankSeen = 0;
+  for (let j = startIdx + 1; j < allLines.length && nonBlankSeen < 5; j++) {
+    const ln = allLines[j];
+    if (ln.trim() === "") continue;
+    nonBlankSeen++;
+    if (ln.trim() === DECISION_HEADING) return true;
+    if (/^##\s/.test(ln)) return false;
+  }
+  return false;
+}
+
+function checkDecisionBlocks(f, text, findings, grace) {
+  const allLines = text.split("\n");
+  for (let i = 0; i < allLines.length; i++) {
+    if (!ENTRY_RE.test(allLines[i])) continue;
+    if (entryHasDecision(allLines, i)) continue;
+    pushFail(
+      findings,
+      grace ? "warn" : "fail",
+      `decision-block: ${f}:${i + 1} entry lacks leading '### Decision'`,
+    );
+  }
+}
+
+function checkWeeklyLogFile(f, base, findings, grace) {
+  const isMain = WEEKLY_LOG_NAME_RE.test(base);
+  const isPart = WEEKLY_LOG_PART_NAME_RE.test(base);
+  if (!isMain && !isPart) return;
+  const text = readFileSync(f, "utf-8");
+  const firstLine = text.split("\n").find((l) => l.trim() !== "");
+  if (!firstLine || !WEEKLY_LOG_H1_RE.test(firstLine)) {
+    pushFail(findings, "fail", `weekly-log: ${f} missing valid H1 heading`);
+  }
+  const week = isoWeekForFile(base);
+  const postCutover = week && compareIsoWeek(week, CUTOVER_ISO_WEEK) >= 0;
+  const lines = countLines(text);
+  if (postCutover && lines > WEEKLY_LOG_LINE_BUDGET) {
+    pushFail(
+      findings,
+      "fail",
+      `weekly-log: ${f} has ${lines} lines (limit ${WEEKLY_LOG_LINE_BUDGET}, post-cutover)`,
+    );
+  }
+  if (isMain && postCutover) {
+    checkDecisionBlocks(f, text, findings, grace);
+  }
+}
+
+function checkWeeklyLogs(_wikiRoot, files, findings, options) {
+  const grace = inGraceWindow(options.graceUntil, options.today);
+  for (const f of files) {
+    checkWeeklyLogFile(f, path.basename(f), findings, grace);
+  }
+}
+
+function checkPriorityIndex(wikiRoot, findings) {
+  const memPath = path.join(wikiRoot, "MEMORY.md");
+  if (!existsSync(memPath)) {
+    pushFail(findings, "fail", `memory: ${memPath} not found`);
+    return;
+  }
+  const text = readFileSync(memPath, "utf-8");
+  if (!new RegExp(`^${PRIORITY_INDEX_HEADING}$`, "m").test(text)) {
+    pushFail(
+      findings,
+      "fail",
+      "memory: missing '## Cross-Cutting Priorities' heading",
+    );
+  }
+  const headerRe =
+    /^\|\s*Item\s*\|\s*Agents\s*\|\s*Owner\s*\|\s*Status\s*\|\s*Added\s*\|/m;
+  if (!headerRe.test(text)) {
+    pushFail(findings, "fail", "memory: missing priority table header row");
+  }
+}
+
+function findActiveClaimsHeader(lines, headingIdx) {
+  for (let i = headingIdx + 1; i < lines.length; i++) {
+    if (/^## /.test(lines[i])) return -1;
+    if (lines[i].startsWith("|") && /agent/.test(lines[i])) return i;
+  }
+  return -1;
+}
+
+function checkActiveClaimsRows(claims, findings, today) {
+  for (const c of claims) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(c.expires_at)) {
+      pushFail(
+        findings,
+        "fail",
+        `active-claims: bad expires_at '${c.expires_at}' for ${c.agent}/${c.target}`,
+      );
+    }
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(c.claimed_at)) {
+      pushFail(
+        findings,
+        "fail",
+        `active-claims: bad claimed_at '${c.claimed_at}' for ${c.agent}/${c.target}`,
+      );
+    }
+  }
+  const { expired } = filterExpired(claims, today);
+  for (const c of expired) {
+    pushFail(
+      findings,
+      "warn",
+      `expired-claim: ${c.agent}/${c.target} expired ${c.expires_at}`,
+    );
+  }
+}
+
+function checkActiveClaims(wikiRoot, findings, options) {
+  const memPath = path.join(wikiRoot, "MEMORY.md");
+  if (!existsSync(memPath)) return;
+  const text = readFileSync(memPath, "utf-8");
+  if (!new RegExp(`^${ACTIVE_CLAIMS_HEADING}$`, "m").test(text)) return;
+  const lines = text.split("\n");
+  const headingIdx = lines.findIndex((l) => l.trim() === ACTIVE_CLAIMS_HEADING);
+  const headerIdx = findActiveClaimsHeader(lines, headingIdx);
+  if (
+    headerIdx === -1 ||
+    lines[headerIdx].trim() !== ACTIVE_CLAIMS_TABLE_HEADER
+  ) {
+    pushFail(
+      findings,
+      "fail",
+      `active-claims: header mismatch (expected ${ACTIVE_CLAIMS_TABLE_HEADER})`,
+    );
+  }
+  checkActiveClaimsRows(parseClaims(text), findings, options.today);
+}
+
+function emitText(failures, warnings) {
+  for (const w of warnings) process.stdout.write(`WARN ${w.message}\n`);
+  for (const f of failures) process.stdout.write(`FAIL ${f.message}\n`);
+  if (failures.length === 0) {
+    process.stdout.write("RESULT: pass\n");
+  } else {
+    process.stdout.write(`RESULT: fail (${failures.length} checks failed)\n`);
+  }
+}
+
+function emitJson(failures, warnings, graceUntil, today) {
+  process.stdout.write(
+    JSON.stringify(
+      {
+        result: failures.length === 0 ? "pass" : "fail",
+        failures,
+        warnings,
+        grace_active: inGraceWindow(graceUntil, today),
+        grace_until: graceUntil,
+      },
+      null,
+      2,
+    ) + "\n",
+  );
+}
+
+/** Run the wiki audit and emit findings. JSON via --format json. */
+export function runAuditCommand(values, _args, _cli) {
+  const logger = { debug() {} };
+  const finder = new Finder(fsAsync, logger, process);
+  const projectRoot = finder.findProjectRoot(process.cwd());
+  const wikiRoot = values["wiki-root"] || path.join(projectRoot, "wiki");
+  const today = values.today || new Date().toISOString().slice(0, 10);
+  const graceUntil = process.env.FIT_WIKI_AUDIT_GRACE_UNTIL || null;
+  const legacyOnly = !!values["legacy-only"];
+
+  const findings = [];
+  const files = listMdFiles(wikiRoot);
+
+  checkSummaries(wikiRoot, files, findings, { graceUntil, today });
+  checkWeeklyLogs(wikiRoot, files, findings, { graceUntil, today });
+  checkPriorityIndex(wikiRoot, findings);
+  if (!legacyOnly) {
+    checkActiveClaims(wikiRoot, findings, { today });
+  }
+
+  const failures = findings.filter((f) => f.level === "fail");
+  const warnings = findings.filter((f) => f.level === "warn");
+
+  if ((values.format || "text") === "json") {
+    emitJson(failures, warnings, graceUntil, today);
+  } else {
+    emitText(failures, warnings);
+  }
+
+  if (failures.length > 0) process.exit(1);
+}

package/src/commands/boot.js

@@ -0,0 +1,66 @@
+import fsAsync from "node:fs/promises";
+import path from "node:path";
+import { Finder } from "@forwardimpact/libutil";
+import { buildDigest } from "../boot.js";
+
+function renderMarkdown(digest) {
+  const lines = [];
+  lines.push("# Boot Digest");
+  lines.push("");
+  lines.push(`**Summary:** ${digest.summary || "(none)"}`);
+  lines.push("");
+  lines.push("## Owned priorities");
+  if (digest.owned_priorities.length === 0) lines.push("- (none)");
+  for (const p of digest.owned_priorities) {
+    lines.push(`- ${p.item} — ${p.status} (added ${p.added})`);
+  }
+  lines.push("");
+  lines.push("## Cross-cutting priorities");
+  if (digest.cross_cutting.length === 0) lines.push("- (none)");
+  for (const p of digest.cross_cutting) {
+    lines.push(`- ${p.item} — ${p.status} (added ${p.added})`);
+  }
+  lines.push("");
+  lines.push("## Active claims");
+  if (digest.claims.length === 0) lines.push("- (none)");
+  for (const c of digest.claims) {
+    lines.push(
+      `- ${c.agent}: ${c.target} (branch ${c.branch}, expires ${c.expires_at})`,
+    );
+  }
+  lines.push("");
+  lines.push("## Storyboard items");
+  if (digest.storyboard_items.length === 0) lines.push("- (none)");
+  for (const s of digest.storyboard_items) {
+    lines.push(`- ${s.threshold}`);
+  }
+  lines.push("");
+  lines.push(`**Inbox count:** ${digest.inbox_count}`);
+  lines.push(`**Storyboard path:** ${digest.storyboard_path || "(none)"}`);
+  return lines.join("\n");
+}
+
+/** Print the on-boot digest for the calling agent. JSON by default; --format markdown renders prose. */
+export function runBootCommand(values, _args, cli) {
+  const agent = values.agent || process.env.LIBEVAL_AGENT_PROFILE;
+  if (!agent) {
+    cli.usageError(
+      "boot requires --agent <name> or LIBEVAL_AGENT_PROFILE env var",
+    );
+    process.exit(2);
+  }
+
+  const logger = { debug() {} };
+  const finder = new Finder(fsAsync, logger, process);
+  const projectRoot = finder.findProjectRoot(process.cwd());
+  const wikiRoot = values["wiki-root"] || path.join(projectRoot, "wiki");
+  const today = values.today || new Date().toISOString().slice(0, 10);
+
+  const digest = buildDigest({ wikiRoot, agent, today });
+
+  if ((values.format || "json") === "markdown") {
+    process.stdout.write(renderMarkdown(digest) + "\n");
+  } else {
+    process.stdout.write(JSON.stringify(digest, null, 2) + "\n");
+  }
+}

package/src/commands/claim.js

@@ -0,0 +1,107 @@
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import fsAsync from "node:fs/promises";
+import path from "node:path";
+import { Finder } from "@forwardimpact/libutil";
+import {
+  appendClaim,
+  removeClaim,
+  parseClaims,
+  filterExpired,
+} from "../active-claims.js";
+
+function projectRoot() {
+  const logger = { debug() {} };
+  const finder = new Finder(fsAsync, logger, process);
+  return finder.findProjectRoot(process.cwd());
+}
+
+function memoryPath(values) {
+  const root = projectRoot();
+  const wikiRoot = values["wiki-root"] || path.join(root, "wiki");
+  return path.join(wikiRoot, "MEMORY.md");
+}
+
+function readMemory(memPath) {
+  if (!existsSync(memPath)) return "";
+  return readFileSync(memPath, "utf-8");
+}
+
+function addDays(today, n) {
+  const d = new Date(today);
+  d.setUTCDate(d.getUTCDate() + n);
+  return d.toISOString().slice(0, 10);
+}
+
+/** Insert a row into MEMORY.md `## Active Claims`. Refuses if (agent, target) already present. */
+export function runClaimCommand(values, _args, cli) {
+  const agent = values.agent || process.env.LIBEVAL_AGENT_PROFILE;
+  if (!agent) {
+    cli.usageError("claim requires --agent or LIBEVAL_AGENT_PROFILE");
+    process.exit(2);
+  }
+  if (!values.target || !values.branch) {
+    cli.usageError("claim requires --target and --branch");
+    process.exit(2);
+  }
+  const today = values.today || new Date().toISOString().slice(0, 10);
+  const expires = values["expires-at"] || addDays(today, 7);
+  const memPath = memoryPath(values);
+  const text = readMemory(memPath);
+  const result = appendClaim(text, {
+    agent,
+    target: values.target,
+    branch: values.branch,
+    pr: values.pr || null,
+    claimed_at: today,
+    expires_at: expires,
+  });
+  if (!result.inserted) {
+    process.stderr.write(
+      `claim already exists for ${agent}/${values.target}\n`,
+    );
+    process.exit(2);
+  }
+  writeFileSync(memPath, result.text);
+  process.stdout.write(`claimed ${values.target} (expires ${expires})\n`);
+}
+
+/** Remove a claim row. `--expired` cleans every row past expires_at. */
+export function runReleaseCommand(values, _args, cli) {
+  const memPath = memoryPath(values);
+  const text = readMemory(memPath);
+
+  if (values.expired) {
+    const today = values.today || new Date().toISOString().slice(0, 10);
+    const claims = parseClaims(text);
+    const { expired } = filterExpired(claims, today);
+    let current = text;
+    let count = 0;
+    for (const c of expired) {
+      const result = removeClaim(current, { agent: c.agent, target: c.target });
+      if (result.removed) {
+        current = result.text;
+        count++;
+      }
+    }
+    writeFileSync(memPath, current);
+    process.stdout.write(`released ${count} expired claim(s)\n`);
+    return;
+  }
+
+  const agent = values.agent || process.env.LIBEVAL_AGENT_PROFILE;
+  if (!agent) {
+    cli.usageError("release requires --agent or --expired");
+    process.exit(2);
+  }
+  if (!values.target) {
+    cli.usageError("release requires --target (or --expired)");
+    process.exit(2);
+  }
+  const result = removeClaim(text, { agent, target: values.target });
+  writeFileSync(memPath, result.text);
+  if (!result.removed) {
+    process.stdout.write(`no matching claim for ${agent}/${values.target}\n`);
+  } else {
+    process.stdout.write(`released ${values.target}\n`);
+  }
+}

package/src/commands/inbox.js

@@ -0,0 +1,180 @@
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import fsAsync from "node:fs/promises";
+import path from "node:path";
+import { Finder } from "@forwardimpact/libutil";
+import {
+  MEMO_INBOX_MARKER,
+  PRIORITY_INDEX_HEADING,
+  PRIORITY_INDEX_TABLE_HEADER,
+} from "../constants.js";
+
+function projectRoot() {
+  const logger = { debug() {} };
+  const finder = new Finder(fsAsync, logger, process);
+  return finder.findProjectRoot(process.cwd());
+}
+
+function paths(values) {
+  const root = projectRoot();
+  const wikiRoot = values["wiki-root"] || path.join(root, "wiki");
+  const agent = values.agent || process.env.LIBEVAL_AGENT_PROFILE;
+  if (!agent) {
+    process.stderr.write("inbox requires --agent or LIBEVAL_AGENT_PROFILE\n");
+    process.exit(2);
+  }
+  return {
+    summaryPath: path.join(wikiRoot, `${agent}.md`),
+    memoryPath: path.join(wikiRoot, "MEMORY.md"),
+    agent,
+  };
+}
+
+function readInboxBullets(text) {
+  const lines = text.split("\n");
+  const markerIdx = lines.findIndex((l) => l.trim() === MEMO_INBOX_MARKER);
+  if (markerIdx === -1)
+    return { lines, markerIdx, bullets: [], bulletIdxs: [] };
+  const bullets = [];
+  const bulletIdxs = [];
+  for (let i = markerIdx + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trim() === "") continue;
+    if (/^##\s/.test(line)) break;
+    if (!line.startsWith("-")) break;
+    if (/\*No new messages\.\*/.test(line)) continue;
+    bullets.push(line);
+    bulletIdxs.push(i);
+  }
+  return { lines, markerIdx, bullets, bulletIdxs };
+}
+
+function removeBulletAt(lines, idx) {
+  lines.splice(idx, 1);
+  return lines;
+}
+
+function listCmd(values) {
+  const { summaryPath } = paths(values);
+  if (!existsSync(summaryPath)) {
+    process.stdout.write(JSON.stringify({ bullets: [] }) + "\n");
+    return;
+  }
+  const text = readFileSync(summaryPath, "utf-8");
+  const { bullets } = readInboxBullets(text);
+  process.stdout.write(JSON.stringify({ bullets }, null, 2) + "\n");
+}
+
+function ackOrDropCmd(values, _kind) {
+  const { summaryPath } = paths(values);
+  const idx = Number.parseInt(values.index ?? "", 10);
+  if (!Number.isInteger(idx) || idx < 0) {
+    process.stderr.write("inbox requires --index <n>\n");
+    process.exit(2);
+  }
+  const text = readFileSync(summaryPath, "utf-8");
+  const { lines, bulletIdxs } = readInboxBullets(text);
+  if (idx >= bulletIdxs.length) {
+    process.stderr.write(`no bullet at index ${idx}\n`);
+    process.exit(2);
+  }
+  removeBulletAt(lines, bulletIdxs[idx]);
+  writeFileSync(summaryPath, lines.join("\n"));
+  process.stdout.write(`removed inbox bullet ${idx}\n`);
+}
+
+function appendPriorityRow(memoryText, { item, agents, owner, status, added }) {
+  const lines = memoryText.split("\n");
+  let headingIdx = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim() === PRIORITY_INDEX_HEADING) {
+      headingIdx = i;
+      break;
+    }
+  }
+  if (headingIdx === -1) {
+    const block = [
+      "",
+      PRIORITY_INDEX_HEADING,
+      "",
+      PRIORITY_INDEX_TABLE_HEADER,
+      "| --- | --- | --- | --- | --- |",
+      `| ${item} | ${agents} | ${owner} | ${status} | ${added} |`,
+      "",
+    ];
+    return memoryText.replace(/\n*$/, "") + "\n" + block.join("\n");
+  }
+  // Find last data row.
+  let sepIdx = -1;
+  for (let i = headingIdx + 1; i < lines.length; i++) {
+    if (/^\|\s*---/.test(lines[i])) {
+      sepIdx = i;
+      break;
+    }
+    if (/^## /.test(lines[i])) break;
+  }
+  if (sepIdx === -1) {
+    return memoryText;
+  }
+  let lastRowIdx = sepIdx;
+  for (let i = sepIdx + 1; i < lines.length; i++) {
+    if (!lines[i].startsWith("|")) break;
+    lastRowIdx = i;
+  }
+  lines.splice(
+    lastRowIdx + 1,
+    0,
+    `| ${item} | ${agents} | ${owner} | ${status} | ${added} |`,
+  );
+  return lines.join("\n");
+}
+
+function promoteCmd(values) {
+  const { summaryPath, memoryPath, agent } = paths(values);
+  const idx = Number.parseInt(values.index ?? "", 10);
+  if (!Number.isInteger(idx) || idx < 0) {
+    process.stderr.write("inbox promote requires --index <n>\n");
+    process.exit(2);
+  }
+  const text = readFileSync(summaryPath, "utf-8");
+  const { lines, bullets, bulletIdxs } = readInboxBullets(text);
+  if (idx >= bullets.length) {
+    process.stderr.write(`no bullet at index ${idx}\n`);
+    process.exit(2);
+  }
+  const bulletText = bullets[idx].replace(/^[-*]\s+/, "");
+  removeBulletAt(lines, bulletIdxs[idx]);
+  writeFileSync(summaryPath, lines.join("\n"));
+
+  const memText = existsSync(memoryPath)
+    ? readFileSync(memoryPath, "utf-8")
+    : "";
+  const today = values.today || new Date().toISOString().slice(0, 10);
+  const owner = values.owner || agent;
+  const promoted = appendPriorityRow(memText, {
+    item: bulletText,
+    agents: agent,
+    owner,
+    status: "active",
+    added: today,
+  });
+  writeFileSync(memoryPath, promoted);
+  process.stdout.write(`promoted inbox bullet ${idx} to priorities\n`);
+}
+
+const SUBS = {
+  list: listCmd,
+  ack: (v) => ackOrDropCmd(v, "ack"),
+  drop: (v) => ackOrDropCmd(v, "drop"),
+  promote: promoteCmd,
+};
+
+/** Dispatch `inbox {list|ack|promote|drop}` to the matching sub-handler. */
+export function runInboxCommand(values, args, cli) {
+  const sub = args[0];
+  const handler = SUBS[sub];
+  if (!handler) {
+    cli.usageError("inbox requires subcommand: list | ack | promote | drop");
+    process.exit(2);
+  }
+  handler(values);
+}