@forwardimpact/libwiki 0.2.29 → 0.2.31

package/README.md

@@ -61,7 +61,8 @@ npx fit-wiki release --expired
 ```
 
 Maintains the `## Active Claims` table in `MEMORY.md`. Duplicates refused;
-row absent means settled.
+row absent means settled. `expires_at` defaults to `claimed_at + 1 day` — a
+claim is a short-lived "shipping this now" assertion, not a lease.
 
 ### `inbox` — triage memos
 
@@ -119,7 +120,9 @@ npx fit-wiki refresh [storyboard-path]
 
 Re-renders `<!-- xmr:metric:csv-path -->` and `<!-- obstacles:open[:Nd] -->`
 marker blocks inside a storyboard from their backing CSV / GitHub state.
-Default path: `wiki/storyboard-YYYY-MMM.md` for the current month.
+Default path: `wiki/storyboard-YYYY-MMM.md` for the current month. Also sweeps
+every expired row from `MEMORY.md ## Active Claims` as part of the same
+deterministic refresh.
 
 ### `init` / `push` / `pull` — wiki working tree
 

package/bin/fit-wiki.js

@@ -4,6 +4,7 @@ import "@forwardimpact/libpreflight/node22";
 
 import { createDefaultRuntime } from "@forwardimpact/libutil/runtime";
 import { GitClient } from "@forwardimpact/libutil/git-client";
+import { GhClient } from "@forwardimpact/libutil/gh-client";
 import { createScriptConfig } from "@forwardimpact/libconfig";
 import { createCli } from "@forwardimpact/libcli";
 import { createLogger } from "@forwardimpact/libtelemetry";
@@ -19,6 +20,10 @@ import { createDefinition } from "../src/cli-definition.js";
 // (and its config-backed token resolver); the rest run against the local tree.
 const NEEDS_WIKI_SYNC = new Set(["claim", "release", "push", "pull", "init"]);
 
+// The ledger command reads and writes the allocation-anchor surface (the
+// obstacle issue's comments) over the GitHub API, so it needs a GhClient.
+const NEEDS_GH_CLIENT = new Set(["ledger"]);
+
 async function main() {
   const runtime = createDefaultRuntime();
   const definition = createDefinition();
@@ -72,8 +77,13 @@ async function main() {
     });
   }
 
+  let ghClient;
+  if (NEEDS_GH_CLIENT.has(command)) {
+    ghClient = new GhClient({ runtime });
+  }
+
   const result = await cli.dispatch(parsed, {
-    deps: { runtime, wikiSync, gitClient },
+    deps: { runtime, wikiSync, gitClient, ghClient },
   });
 
   const envelope = result ?? { ok: true };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/libwiki",
-  "version": "0.2.29",
+  "version": "0.2.31",
   "description": "Wiki lifecycle primitives — stable memory for agent teams so coordination persists across sessions.",
   "keywords": [
     "wiki",
@@ -47,7 +47,7 @@
   "dependencies": {
     "@forwardimpact/libcli": "^0.1.0",
     "@forwardimpact/libconfig": "^0.1.77",
-    "@forwardimpact/libeval": "^0.1.49",
+    "@forwardimpact/libharness": "^1.0.0",
     "@forwardimpact/libpreflight": "^0.1.0",
     "@forwardimpact/libtelemetry": "^0.1.47",
     "@forwardimpact/libutil": "^0.1.0",

package/src/audit/rules.js

@@ -8,6 +8,8 @@ import {
   ISSUE_CLOSE_RE,
   ISSUE_OPEN_RE,
   MEMO_INBOX_MARKER,
+  MEMORY_LINE_BUDGET,
+  MEMORY_WORD_BUDGET,
   PRIORITY_INDEX_HEADING,
   STORYBOARD_LINE_BUDGET,
   STORYBOARD_WORD_BUDGET,
@@ -53,6 +55,19 @@ import {
 } from "./rule-builders.js";
 import { STATUS_ROW_RULES } from "./status-row.js";
 
+// The budget predicates the post-landing pre-push gate re-runs over the
+// outgoing tree. Naming the ids here keeps the gate selecting rules by
+// membership of this set, so a future predicate change to any of these
+// rules flows through the gate with no gate-code change.
+export const BUDGET_RULE_IDS = new Set([
+  "summary.line-budget",
+  "summary.word-budget",
+  "weekly-log.line-budget",
+  "weekly-log.word-budget",
+  "weekly-log-part.line-budget",
+  "weekly-log-part.word-budget",
+]);
+
 export const RULES = [
   // -- Summary files --
 
@@ -260,6 +275,24 @@ export const RULES = [
     message: () => "MEMORY.md not found",
     hint: "run `bunx fit-wiki init` to scaffold the canonical sections",
   },
+  {
+    id: "memory.line-budget",
+    scope: "memory",
+    severity: "fail",
+    when: memoryExists,
+    check: lineBudget(MEMORY_LINE_BUDGET),
+    message: (_s, r) => `${r.value} lines (limit ${MEMORY_LINE_BUDGET})`,
+    hint: "MEMORY.md holds settled cross-cutting state, not history; release settled claims, prune stale priority rows, and move event-by-event detail to the relevant ledger page or weekly log",
+  },
+  {
+    id: "memory.word-budget",
+    scope: "memory",
+    severity: "fail",
+    when: memoryExists,
+    check: wordBudget(MEMORY_WORD_BUDGET),
+    message: (_s, r) => `${r.value} words (limit ${MEMORY_WORD_BUDGET})`,
+    hint: "MEMORY.md holds settled cross-cutting state, not history; release settled claims, prune stale priority rows, and move event-by-event detail to the relevant ledger page or weekly log",
+  },
   {
     id: "memory.priority-heading",
     scope: "memory",
@@ -338,7 +371,7 @@ export const RULES = [
     severity: "warn",
     check: expired,
     message: (s) => `${s.agent}/${s.target} expired ${s.expires_at}`,
-    hint: "run `bunx fit-wiki release --expired` to clear expired claims",
+    hint: "run `bunx fit-wiki refresh` (or `release --expired`) to clear expired claims",
   },
 
   // -- Storyboards --

package/src/audit/scopes.js

@@ -137,6 +137,18 @@ function readOptional(filePath, fs) {
   };
 }
 
+// MEMORY.md carries the same line/word budget rules as the prose surfaces, so
+// its subject needs the `lines`/`words` counters those check builders read.
+// Counted off the canonical budget.js pair, like every other budgeted surface.
+function loadMemory(filePath, fs) {
+  const base = readOptional(filePath, fs);
+  return {
+    ...base,
+    lines: countLines(base.text),
+    words: countWords(base.text),
+  };
+}
+
 /**
  * Parse the rows inside STATUS.md's fenced block into audit subjects. Lines
  * outside the ``` fence (header prose) and blank lines are skipped. Each row
@@ -354,7 +366,7 @@ export function buildContext({ wikiRoot, today, fs, subprocess }) {
     wikiRoot,
     today,
     subjects,
-    memory: readOptional(path.join(wikiRoot, "MEMORY.md"), fs),
+    memory: loadMemory(path.join(wikiRoot, "MEMORY.md"), fs),
     status: readOptional(path.join(wikiRoot, "STATUS.md"), fs),
     storyboard: loadStoryboard(wikiRoot, today, fs),
     admission: buildAdmission(wikiRoot, fs, subprocess),

package/src/budget-gate.js

@@ -0,0 +1,193 @@
+// Post-landing, pre-push budget re-validation on the size (word/line) axis.
+//
+// The wiki landing flow re-runs the audit's budget predicates over the
+// outgoing tree between landing and push, and refuses a push that introduces
+// or deepens a per-file budget breach this writer's push would publish. The
+// gate reuses the audit's budget rules by reference: it resolves the rule
+// objects named by `BUDGET_RULE_IDS` and calls each rule's own `check` (the
+// over-cap predicate) plus the same `countWords` / `countLines` the audit
+// builds its subjects from. It never re-defines a budget, never routes through
+// the `runRules` engine (which drops the numeric value and emits nothing under
+// cap), and never edits — it refuses, keeping commits local.
+
+import path from "node:path";
+import { BUDGET_RULE_IDS, RULES } from "./audit/rules.js";
+import { buildContext, resolveScope } from "./audit/scopes.js";
+import { countLines, countWords } from "./budget.js";
+
+/**
+ * Resolve `BUDGET_RULE_IDS` to their rule objects in `RULES`, tagging each with
+ * the count axis its id implies. Throws if a named id is missing from `RULES`,
+ * so a rule rename surfaces here rather than silently dropping a predicate.
+ * @returns {Array<{id: string, scope: string, axis: 'words'|'lines', check: Function}>}
+ */
+export function budgetRules() {
+  const byId = new Map(RULES.map((r) => [r.id, r]));
+  return [...BUDGET_RULE_IDS].map((id) => {
+    const rule = byId.get(id);
+    if (!rule) throw new Error(`budget-gate: unknown budget rule id '${id}'`);
+    return {
+      id,
+      scope: rule.scope,
+      axis: id.endsWith("word-budget") ? "words" : "lines",
+      check: rule.check,
+    };
+  });
+}
+
+/**
+ * Enumerate which wiki files are budgeted, by reusing the audit's
+ * classification. Subjects carry an absolute `path`, so each is reduced to the
+ * `<file>` half of `git show <ref>:<file>` relative to `wikiRoot`. No count is
+ * read off the working-dir subject — only the file identity and its scope.
+ * @param {object} ctx - An audit context from `buildContext`.
+ * @param {string} wikiRoot - The wiki clone directory the paths are relative to.
+ * @returns {Array<{relPath: string, scope: string}>}
+ */
+export function budgetedFiles(ctx, wikiRoot) {
+  const scopes = new Set(budgetRules().map((r) => r.scope));
+  const files = [];
+  for (const scope of scopes) {
+    for (const subject of resolveScope(scope, ctx)) {
+      files.push({ relPath: path.relative(wikiRoot, subject.path), scope });
+    }
+  }
+  return files;
+}
+
+/**
+ * Measure the budget predicates for the tree at `ref`. Reads each budgeted
+ * file's blob via the cwd-bound `showFile`, counts it once with the audit's
+ * counters, then for every budget rule on that file's scope records the axis
+ * value and whether the rule's own `check` flags it over cap. An absent path
+ * at the ref counts as 0 (matching the audit's "missing counts as empty"
+ * posture); an unreadable ref makes `showFile` throw, which propagates.
+ * @param {(ref: string, file: string) => Promise<string|null>} showFile
+ * @param {string} ref - The tree-ish to measure (e.g. "HEAD", a SHA).
+ * @param {Array<{relPath: string, scope: string}>} budgeted
+ * @returns {Promise<Map<string, Map<string, {value: number, overCap: boolean}>>>}
+ *   relPath → ruleId → { value, overCap }.
+ */
+export async function measureRef(showFile, ref, budgeted) {
+  const rules = budgetRules();
+  const result = new Map();
+  for (const { relPath, scope } of budgeted) {
+    const text = (await showFile(ref, relPath)) ?? "";
+    const counts = { words: countWords(text), lines: countLines(text) };
+    const perRule = new Map();
+    for (const rule of rules) {
+      if (rule.scope !== scope) continue;
+      perRule.set(rule.id, {
+        value: counts[rule.axis],
+        overCap: rule.check(counts) != null,
+      });
+    }
+    result.set(relPath, perRule);
+  }
+  return result;
+}
+
+/**
+ * Compare the outgoing tree against the two push-input baselines and return the
+ * per-file/per-predicate refusal delta. For each (file, rule) the baseline is
+ * the worse (higher) of the session-base and origin-tip values, treating an
+ * absent measurement as 0. A predicate refuses iff the outgoing value is over
+ * cap AND strictly exceeds that baseline — so equal-or-better states pass, and
+ * a foreign breach the writer did not worsen passes. A `summary.*` breach on a
+ * file listed in `exemptSummaryFiles` is surfaced instead of refused — the
+ * memo-delivery seam, where blocking a delivery into deficient headroom would
+ * enforce a contradiction the memo-headroom measures exist to resolve.
+ *
+ * @param {object} args
+ * @param {Map<string, Map<string, {value: number, overCap: boolean}>>} args.outgoing
+ * @param {Map<string, Map<string, {value: number}>>|null} args.sessionBase - null when unborn.
+ * @param {Map<string, Map<string, {value: number}>>|null} args.originTip
+ * @param {string[]} [args.exemptSummaryFiles]
+ * @returns {{refusals: Array<object>, surfaced: Array<object>}}
+ *   Each entry: { file, ruleId, baseline, value }.
+ */
+export function revalidateBudgets({
+  outgoing,
+  sessionBase,
+  originTip,
+  exemptSummaryFiles = [],
+}) {
+  const exempt = new Set(exemptSummaryFiles);
+  const refusals = [];
+  const surfaced = [];
+  const baselineValue = (ref, relPath, ruleId) =>
+    ref?.get(relPath)?.get(ruleId)?.value ?? 0;
+  for (const [relPath, perRule] of outgoing) {
+    for (const [ruleId, { value, overCap }] of perRule) {
+      if (!overCap) continue;
+      const baseline = Math.max(
+        baselineValue(sessionBase, relPath, ruleId),
+        baselineValue(originTip, relPath, ruleId),
+      );
+      if (value <= baseline) continue;
+      const entry = { file: relPath, ruleId, baseline, value };
+      if (ruleId.startsWith("summary.") && exempt.has(relPath)) {
+        surfaced.push(entry);
+      } else {
+        refusals.push(entry);
+      }
+    }
+  }
+  return { refusals, surfaced };
+}
+
+/**
+ * Run the gate end to end over the outgoing tree. Builds the audit context,
+ * enumerates the budgeted files, measures the committed `HEAD` (what publishes)
+ * and the two push-input baselines through the one `measureRef` path, then
+ * computes the per-file/per-predicate delta. An unreadable baseline ref makes
+ * `showFile` throw, which aborts the gate WITHOUT refusing — the gate only
+ * refuses a regression it can prove, so a read failure surfaces (the push
+ * proceeds) rather than fabricating a value-0 baseline that would wrongly block
+ * a foreign pre-existing breach.
+ *
+ * @param {object} args
+ * @param {(ref: string, file: string) => Promise<string|null>} args.showFile
+ * @param {string} args.wikiRoot - The wiki clone directory.
+ * @param {string} args.today - ISO day for the audit context (weekly-log scope).
+ * @param {object} args.fs - Sync fs the audit context reads with.
+ * @param {string} args.headRef - The outgoing tree-ish (e.g. "HEAD").
+ * @param {string} args.originRef - The landed origin tip ref.
+ * @param {string} [args.sessionBaseSha] - Pre-fetch session base, or "" when unborn.
+ * @param {string[]} [args.exemptSummaryFiles] - Memo-delivery seam set.
+ * @returns {Promise<{refusals: Array<object>, surfaced: Array<object>}>}
+ */
+export async function runBudgetGate({
+  showFile,
+  wikiRoot,
+  today,
+  fs,
+  headRef,
+  originRef,
+  sessionBaseSha,
+  exemptSummaryFiles = [],
+}) {
+  const budgeted = budgetedFiles(
+    buildContext({ wikiRoot, today, fs }),
+    wikiRoot,
+  );
+  let outgoing;
+  let sessionBase = null;
+  let originTip = null;
+  try {
+    outgoing = await measureRef(showFile, headRef, budgeted);
+    if (sessionBaseSha) {
+      sessionBase = await measureRef(showFile, sessionBaseSha, budgeted);
+    }
+    originTip = await measureRef(showFile, originRef, budgeted);
+  } catch {
+    // Cannot prove a regression (unreadable ref) ⇒ do not refuse; fail-visible.
+    return { refusals: [], surfaced: [] };
+  }
+  return revalidateBudgets({
+    outgoing,
+    sessionBase,
+    originTip,
+    exemptSummaryFiles,
+  });
+}

package/src/cli-definition.js

@@ -10,6 +10,7 @@ import { runInboxCommand } from "./commands/inbox.js";
 import { runRotateCommand } from "./commands/rotate.js";
 import { runAuditCommand } from "./commands/audit.js";
 import { runFixCommand } from "./commands/fix.js";
+import { runLedgerCommand } from "./commands/ledger.js";
 
 /**
  * Build the `fit-wiki` libcli definition. Agent identity is never resolved from
@@ -105,7 +106,7 @@ export function createDefinition() {
           pr: { type: "string", description: "Optional PR id" },
           "expires-at": {
             type: "string",
-            description: "Override expiry ISO date (default claim+7d)",
+            description: "Override expiry ISO date (default claim+1d)",
           },
         },
       },
@@ -208,7 +209,7 @@ export function createDefinition() {
       {
         name: "refresh",
         description:
-          "Regenerate XmR and obstacle/experiment marker blocks in a storyboard",
+          "Regenerate storyboard XmR/marker blocks and clear expired MEMORY.md claims",
         args: ["storyboard-path"],
         argsUsage: "[storyboard-path]",
         handler: runRefreshCommand,
@@ -260,7 +261,15 @@ export function createDefinition() {
         name: "push",
         description: "Commit and push local wiki changes to the remote",
         handler: runPushCommand,
-        options: { ...wikiRootOpt },
+        options: {
+          ...wikiRootOpt,
+          paths: {
+            type: "string",
+            multiple: true,
+            description:
+              "Pathspec(s) limiting the write-set; omit to land the session's dirty set",
+          },
+        },
       },
       {
         name: "pull",
@@ -268,6 +277,47 @@ export function createDefinition() {
         handler: runPullCommand,
         options: { ...agentOpt, ...wikiRootOpt, ...todayOpt },
       },
+      {
+        name: "ledger",
+        description:
+          "Allocate collision-ledger ids at anchors and rebuild projections",
+        args: ["subcommand"],
+        argsUsage: "<allocate|rebuild|verify>",
+        handler: runLedgerCommand,
+        options: {
+          ...wikiRootOpt,
+          kind: {
+            type: "string",
+            description: "Allocation kind: occ | nm | fold | meta",
+          },
+          count: {
+            type: "string",
+            description: "How many ids to allocate (default 1)",
+          },
+          ids: {
+            type: "string",
+            description:
+              "Comma-separated ids to backfill an anchor for (instead of --count)",
+          },
+          event: {
+            type: "string",
+            description: "Durable key for the allocation (SHA or anchor id)",
+          },
+          note: {
+            type: "string",
+            description: "Free-text note for the anchor",
+          },
+          gapped: {
+            type: "boolean",
+            description:
+              "Render double-allocation losers as a gap, not a renumber",
+          },
+          issue: {
+            type: "string",
+            description: "Anchor issue number (default obstacle issue)",
+          },
+        },
+      },
     ],
     globalOptions: {
       help: { type: "boolean", short: "h", description: "Show this help" },

package/src/commands/claim.js

@@ -162,7 +162,9 @@ export async function runClaimCommand(ctx) {
     };
   }
   const today = options.today || currentDayIso(runtime);
-  const expires = options["expires-at"] || addDays(today, 7);
+  // Default expiry is claim+1 day: a claim is a short-lived "actively shipping
+  // this now" assertion, not a long lease. A run that outlives one day re-claims.
+  const expires = options["expires-at"] || addDays(today, 1);
   const memPath = memoryPath(runtime, options);
   const text = readMemory(runtime, memPath);
   const claim = {

package/src/commands/fix.js

@@ -5,7 +5,7 @@ import {
   createAgentRunner,
   composeProfilePrompt,
   createRedactor,
-} from "@forwardimpact/libeval";
+} from "@forwardimpact/libharness";
 import { RULES } from "../audit/rules.js";
 import { buildContext, resolveScope } from "../audit/scopes.js";
 import {

package/src/commands/ledger.js

@@ -0,0 +1,208 @@
+import path from "node:path";
+import { resolveWikiRoot } from "../util/wiki-dir.js";
+import { renderAnchorBody, ANCHOR_KINDS } from "../ledger/anchor.js";
+import { readAnchors, DEFAULT_ANCHOR_ISSUE } from "../ledger/reader.js";
+import {
+  foldAnchors,
+  renderLedgerPage,
+  renderMemoryRow,
+  writeMemoryRowRegion,
+  readMemoryRowRegion,
+  extractProse,
+} from "../ledger/projection.js";
+
+const KIND_PREFIX = { occ: "#", nm: "NM", fold: "n=", meta: "M" };
+const LEDGER_FILE = "parallel-collision-ledger.md";
+const MEMORY_FILE = "MEMORY.md";
+
+/** Parse `owner/repo` from a remote URL (https or ssh form). */
+export function parseOwnerRepo(url) {
+  const m = url
+    .trim()
+    .replace(/\.wiki$/, "")
+    .match(/[/:]([^/:]+)\/([^/]+?)(?:\.wiki)?(?:\.git)?\/?$/);
+  if (!m) throw new Error(`ledger: cannot parse owner/repo from "${url}"`);
+  return { owner: m[1], repo: m[2].replace(/\.wiki$/, "") };
+}
+
+function nextFreeIds(fold, kind, count) {
+  const prefix = KIND_PREFIX[kind];
+  let max = 0;
+  for (const [label, record] of fold.assignments) {
+    if (record.anchor.kind !== kind) continue;
+    const n = Number.parseInt(label.replace(prefix, ""), 10);
+    if (Number.isFinite(n) && n > max) max = n;
+  }
+  const ids = [];
+  for (let i = 1; i <= count; i++) ids.push(`${prefix}${max + i}`);
+  return ids;
+}
+
+/** Read the ordered anchor sequence and fold it, resolving the repo slug. */
+async function loadFold({ gitClient, ghClient, wikiDir, issue }) {
+  const url = await gitClient.remoteGetUrl("origin", { cwd: wikiDir });
+  const { owner, repo } = parseOwnerRepo(url);
+  const anchors = await readAnchors(ghClient, {
+    owner,
+    repo,
+    issue,
+    cwd: wikiDir,
+  });
+  return { fold: foldAnchors(anchors), owner, repo };
+}
+
+async function allocate(env, options) {
+  const { runtime, ghClient } = env;
+  const kind = options.kind;
+  if (!ANCHOR_KINDS.has(kind)) {
+    return {
+      ok: false,
+      code: 2,
+      error: `ledger allocate: --kind must be one of ${[...ANCHOR_KINDS].join(", ")}`,
+    };
+  }
+  const event = options.event;
+  if (!event) {
+    return {
+      ok: false,
+      code: 2,
+      error: "ledger allocate: --event (SHA or anchor id) is required",
+    };
+  }
+  const { fold, owner, repo } = await loadFold(env);
+  // Backfill registers an anchor for ids that predate the anchor surface, named
+  // explicitly via --ids; their event keys already exist in history. A plain
+  // allocate mints the next free ids of the kind. The conflict detector at
+  // rebuild guards against double-registering an id that already has an anchor.
+  let ids;
+  if (options.ids) {
+    ids = options.ids
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean);
+    const already = ids.filter((id) => fold.assignments.has(id));
+    if (already.length > 0) {
+      return {
+        ok: false,
+        code: 1,
+        error: `ledger allocate --backfill: already anchored: ${already.join(", ")}`,
+      };
+    }
+  } else {
+    const count = options.count ? Number.parseInt(options.count, 10) : 1;
+    ids = nextFreeIds(fold, kind, count);
+  }
+  const body = renderAnchorBody({ kind, ids, event, note: options.note ?? "" });
+  // The anchor publication is the allocation; no projection is written here.
+  // The printed ids are provisional — a rebuild over the published sequence is
+  // authoritative and resolves any concurrent interleave first-published-wins.
+  await ghClient.apiPost(
+    `repos/${owner}/${repo}/issues/${env.issue}/comments`,
+    { body },
+    { cwd: env.wikiDir },
+  );
+  runtime.proc.stdout.write(`${ids.join(" ")}\n`);
+  return { ok: true };
+}
+
+function readFileOrEmpty(runtime, filePath) {
+  return runtime.fsSync.existsSync(filePath)
+    ? runtime.fsSync.readFileSync(filePath, "utf-8")
+    : "";
+}
+
+function readLedgerPage(runtime, wikiDir) {
+  const ledgerPath = path.join(wikiDir, LEDGER_FILE);
+  return runtime.fsSync.existsSync(ledgerPath)
+    ? runtime.fsSync.readFileSync(ledgerPath, "utf-8")
+    : "";
+}
+
+/** Project the anchor record onto the ledger-page body, preserving cited prose. */
+async function project(env, options) {
+  const { runtime, wikiDir } = env;
+  const labelMode = options.gapped ? "gapped" : "renumber";
+  const { fold } = await loadFold(env);
+  const existing = readLedgerPage(runtime, wikiDir);
+  const prose = extractProse(existing);
+  const { body, missingProse } = renderLedgerPage(fold, prose, { labelMode });
+  return { fold, body, missingProse, existing };
+}
+
+async function rebuild(env, options) {
+  const { runtime, wikiDir } = env;
+  const { fold, body, missingProse } = await project(env, options);
+  runtime.fsSync.writeFileSync(path.join(wikiDir, LEDGER_FILE), body);
+  const memoryPath = path.join(wikiDir, MEMORY_FILE);
+  const memoryBody = readFileOrEmpty(runtime, memoryPath);
+  runtime.fsSync.writeFileSync(
+    memoryPath,
+    writeMemoryRowRegion(memoryBody, fold),
+  );
+  runtime.proc.stdout.write(
+    `rebuilt: ${fold.assignments.size} ids, ${fold.conflicts.length} double-allocation(s)\n`,
+  );
+  if (missingProse.length > 0) {
+    runtime.proc.stderr.write(
+      `warning: prose cites missing anchors: ${missingProse.join(", ")}\n`,
+    );
+  }
+  return { ok: true };
+}
+
+async function verify(env, options) {
+  const { runtime, wikiDir } = env;
+  const { fold, body, missingProse, existing } = await project(env, options);
+  const problems = [];
+  if (fold.conflicts.length > 0) {
+    problems.push(`${fold.conflicts.length} double-allocation(s)`);
+  }
+  if (missingProse.length > 0) {
+    problems.push(`prose citing missing anchors: ${missingProse.join(", ")}`);
+  }
+  if (existing.trim() !== body.trim()) {
+    problems.push("ledger page diverges from the anchor record");
+  }
+  const memoryBody = readFileOrEmpty(runtime, path.join(wikiDir, MEMORY_FILE));
+  const memoryRegion = readMemoryRowRegion(memoryBody);
+  if (memoryRegion === null) {
+    problems.push("MEMORY row region absent (run rebuild)");
+  } else if (memoryRegion.trim() !== renderMemoryRow(fold).trim()) {
+    problems.push("MEMORY row diverges from the anchor record");
+  }
+  if (problems.length === 0) {
+    runtime.proc.stdout.write("verify: clean\n");
+    return { ok: true };
+  }
+  runtime.proc.stderr.write(`verify: ${problems.join("; ")}\n`);
+  return { ok: false, code: 1 };
+}
+
+const SUBS = { allocate, rebuild, verify };
+
+/**
+ * `fit-wiki ledger <allocate|rebuild|verify>` — the allocation procedure that
+ * keeps identity off the merge-contested page. Allocation publishes an anchor
+ * comment to the obstacle issue with no projection write at allocation time;
+ * rebuild and verify project the anchor record onto the ledger page and MEMORY
+ * row, preserving anchor-cited prose.
+ */
+export async function runLedgerCommand(ctx) {
+  const { runtime, gitClient, ghClient } = ctx.deps;
+  const options = ctx.options ?? {};
+  const sub = ctx.args?.subcommand;
+  const handler = SUBS[sub];
+  if (!handler) {
+    return {
+      ok: false,
+      code: 2,
+      error: "ledger requires subcommand: allocate | rebuild | verify",
+    };
+  }
+  const wikiDir = resolveWikiRoot(runtime, options);
+  const issue = options.issue
+    ? Number.parseInt(options.issue, 10)
+    : DEFAULT_ANCHOR_ISSUE;
+  const env = { runtime, gitClient, ghClient, wikiDir, issue };
+  return handler(env, options);
+}