@forwardimpact/libwiki 0.2.25 → 0.2.26

package/src/audit/scopes.js

@@ -7,6 +7,8 @@ import {
   WEEKLY_LOG_NAME_RE,
   WEEKLY_LOG_PART_NAME_RE,
 } from "../constants.js";
+import { listAdmissionPaths } from "./admission.js";
+import { classifyPath, rootSummaryStem } from "./grammar.js";
 
 // Capture the agent-title group so the same regex both classifies a file
 // (`.test`) and yields the title for the agent-prefix audit (`.match[1]`).
@@ -33,6 +35,34 @@ function listMdFiles(wikiRoot, fs) {
     .map((e) => path.join(wikiRoot, e));
 }
 
+// Recursively collect every *.csv under `<wikiRoot>/metrics/`. The real layout
+// is `metrics/<skill>/<year>.csv` (two levels), so the walk recurses rather
+// than assuming a fixed depth. Uses readdirSync + statSync (rather than
+// `withFileTypes` Dirents) so it runs unchanged under the in-memory mock fs.
+function listCsvFiles(wikiRoot, fs) {
+  const metricsRoot = path.join(wikiRoot, "metrics");
+  if (!fs.existsSync(metricsRoot)) return [];
+  const found = [];
+  const walk = (dir) => {
+    for (const name of fs.readdirSync(dir)) {
+      const full = path.join(dir, name);
+      if (fs.statSync(full).isDirectory()) walk(full);
+      else if (name.endsWith(".csv")) found.push(full);
+    }
+  };
+  walk(metricsRoot);
+  return found;
+}
+
+// Load a metrics CSV as an audit subject: `rows` is the array of line strings,
+// so a rule indexes `rows[i]` (a string) and `i + 1` is its line number.
+function loadCsv(filePath, fs) {
+  return {
+    path: filePath,
+    rows: fs.readFileSync(filePath, "utf-8").split("\n"),
+  };
+}
+
 function loadFile(filePath, fs) {
   const text = fs.readFileSync(filePath, "utf-8");
   const fileLines = text.split("\n");
@@ -177,6 +207,7 @@ const SCOPE_RESOLVERS = {
   summary: (ctx) => ctx.subjects.summary,
   "weekly-log-main": (ctx) => ctx.subjects["weekly-log-main"],
   "weekly-log-part": (ctx) => ctx.subjects["weekly-log-part"],
+  "metrics-csv": (ctx) => ctx.subjects["metrics-csv"],
   memory: (ctx) => [ctx.memory],
   "claims-row": (ctx) =>
     parseClaims(ctx.memory.text).map((c) => ({ ...c, path: ctx.memory.path })),
@@ -191,8 +222,54 @@ const SCOPE_RESOLVERS = {
       ...r,
       path: ctx.status.path,
     })),
+  "conflict-scan": (ctx) => conflictScanSubjects(ctx),
+  admission: (ctx) =>
+    ctx.admission.paths
+      .filter((p) => classifyPath(p, ctx.admission) === "rejected")
+      .map((relPath) => ({
+        path: path.join(ctx.wikiRoot, relPath),
+        relPath,
+      })),
 };
 
+// Normalize every audited surface into a uniform `{ path, text, fenceExempt }`
+// subject for the conflict-marker scan. The per-file subjects (summaries,
+// weekly logs and sealed parts, storyboard) carry `fileLines`; MEMORY.md and
+// STATUS.md carry `text` (readOptional shape). `fenceExempt` is true for prose
+// surfaces, where a fence quotes content, and false for STATUS.md, whose fenced
+// rows are data — a marker there is never legitimate (per-surface fence
+// contract). Files absent from disk (missing MEMORY/STATUS/storyboard) yield
+// empty text and produce no findings.
+function conflictScanSubjects(ctx) {
+  const subjects = [];
+  const fileScopes = ["summary", "weekly-log-main", "weekly-log-part"];
+  for (const scope of fileScopes) {
+    for (const s of ctx.subjects[scope]) {
+      subjects.push({
+        path: s.path,
+        text: s.fileLines.join("\n"),
+        fenceExempt: true,
+      });
+    }
+  }
+  subjects.push({
+    path: ctx.storyboard.path,
+    text: ctx.storyboard.text,
+    fenceExempt: true,
+  });
+  subjects.push({
+    path: ctx.memory.path,
+    text: ctx.memory.text,
+    fenceExempt: true,
+  });
+  subjects.push({
+    path: ctx.status.path,
+    text: ctx.status.text,
+    fenceExempt: false,
+  });
+  return subjects;
+}
+
 /** Resolve a scope key into the list of subjects the engine should iterate. */
 export function resolveScope(scopeKey, ctx) {
   const resolver = SCOPE_RESOLVERS[scopeKey];
@@ -200,21 +277,48 @@ export function resolveScope(scopeKey, ctx) {
   return resolver(ctx);
 }
 
+/**
+ * Build the admission slice: the tracked-file universe plus the
+ * `rootSummaryAgents` set that gates `<agent>/` sidecar directories. The agent
+ * set is derived first (a root-level summary-class file's stem) so the
+ * `admission` scope can classify sidecar directories against it.
+ *
+ * Returns the empty universe when `subprocess` is absent — callers that only
+ * read `.subjects` (the rotation pre-pass) skip the git read and the tree walk
+ * entirely, and produce no `admission` findings.
+ */
+function buildAdmission(wikiRoot, fs, subprocess) {
+  if (!subprocess) return { paths: [], rootSummaryAgents: new Set() };
+  const paths = listAdmissionPaths({ wikiRoot, fs, subprocess });
+  const rootSummaryAgents = new Set();
+  for (const p of paths) {
+    if (p.includes("/")) continue; // root-level files only
+    const stem = rootSummaryStem(p);
+    if (stem) rootSummaryAgents.add(stem);
+  }
+  return { paths, rootSummaryAgents };
+}
+
 /**
  * Build the audit context: classifies and loads every wiki file once.
- * @param {{wikiRoot: string, today: string, fs: object}} options
- *   `fs` is the sync filesystem surface (`runtime.fsSync`).
+ * @param {{wikiRoot: string, today: string, fs: object, subprocess: object}} options
+ *   `fs` is the sync filesystem surface (`runtime.fsSync`); `subprocess` is
+ *   `runtime.subprocess` (its `runSync` backs the admission scope's git read).
  */
-export function buildContext({ wikiRoot, today, fs }) {
+export function buildContext({ wikiRoot, today, fs, subprocess }) {
   const subjects = {
     summary: [],
     "weekly-log-main": [],
     "weekly-log-part": [],
+    "metrics-csv": [],
   };
   for (const file of listMdFiles(wikiRoot, fs)) {
     const classified = classifyFile(file, fs);
     if (classified) subjects[classified.kind].push(classified.subject);
   }
+  for (const file of listCsvFiles(wikiRoot, fs)) {
+    subjects["metrics-csv"].push(loadCsv(file, fs));
+  }
   return {
     wikiRoot,
     today,
@@ -222,5 +326,6 @@ export function buildContext({ wikiRoot, today, fs }) {
     memory: readOptional(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/block-renderer.js

@@ -13,10 +13,17 @@ export class BlockRenderError extends Error {
 /**
  * Render an XmR chart block for a metric by reading its CSV and producing
  * markdown lines.
- * @param {{metric: string, csvPath: string, projectRoot: string, fs: object}} options
- *   `fs` is the sync filesystem surface (`runtime.fsSync`).
+ * @param {{metric: string, csvPath: string, projectRoot: string, fs: object, priorReadAnchor?: string|null}} options
+ *   `fs` is the sync filesystem surface (`runtime.fsSync`). `priorReadAnchor`,
+ *   when supplied, stamps per-signal provenance surfaced in the Signals line.
  */
-export function renderBlock({ metric, csvPath, projectRoot, fs }) {
+export function renderBlock({
+  metric,
+  csvPath,
+  projectRoot,
+  fs,
+  priorReadAnchor,
+}) {
   const fullPath = path.resolve(projectRoot, csvPath);
   let csvText;
   try {
@@ -24,7 +31,7 @@ export function renderBlock({ metric, csvPath, projectRoot, fs }) {
   } catch {
     throw new BlockRenderError(`csv-not-found: ${csvPath}`);
   }
-  const report = analyze(csvText);
+  const report = analyze(csvText, { priorReadAnchor });
 
   const m = report.metrics.find((entry) => entry.metric === metric);
   if (!m) {
@@ -50,11 +57,18 @@ export function renderBlock({ metric, csvPath, projectRoot, fs }) {
   ];
 }
 
+// Annotate each fired rule with its records' provenance when present, so a
+// storyboard reader distinguishes recomputation-revealed signals from
+// new-point signals at the cell. Without a prior-read anchor, provenance is
+// absent and the line renders bare rule names exactly as before.
 function formatSignals(signals) {
   if (!signals) return "—";
   const fired = [];
   for (const rule of ["xRule1", "xRule2", "xRule3", "mrRule1"]) {
-    if (signals[rule]?.length > 0) fired.push(rule);
+    const recs = signals[rule];
+    if (!recs?.length) continue;
+    const tags = [...new Set(recs.map((r) => r.provenance).filter(Boolean))];
+    fired.push(tags.length ? `${rule} (${tags.join(", ")})` : rule);
   }
   return fired.length > 0 ? fired.join(", ") : "—";
 }

package/src/boot.js

@@ -1,7 +1,16 @@
 import path from "node:path";
 import { yearMonth } from "@forwardimpact/libutil";
 import { parseClaims, filterExpired } from "./active-claims.js";
-import { MEMO_INBOX_MARKER, PRIORITY_INDEX_HEADING } from "./constants.js";
+import { countLines, countWords } from "./budget.js";
+import {
+  MEMO_INBOX_MARKER,
+  PRIORITY_INDEX_HEADING,
+  SUMMARY_LINE_BUDGET,
+  SUMMARY_WORD_BUDGET,
+  WEEKLY_LOG_LINE_BUDGET,
+  WEEKLY_LOG_WORD_BUDGET,
+} from "./constants.js";
+import { weeklyLogPath } from "./weekly-log.js";
 
 function readIfExists(fs, filePath) {
   if (!fs.existsSync(filePath)) return null;
@@ -133,6 +142,24 @@ function countInbox(text) {
   return n;
 }
 
+/**
+ * Remaining budget for a budgeted surface: current value, cap, and headroom for
+ * both the line and word budget. An absent file (empty text) reports zero usage
+ * and full headroom so a writer sees the ceiling before composing.
+ */
+function headroom(text, lineCap, wordCap) {
+  const lines = countLines(text);
+  const words = countWords(text);
+  return {
+    words,
+    lines,
+    word_cap: wordCap,
+    line_cap: lineCap,
+    words_remaining: wordCap - words,
+    lines_remaining: lineCap - lines,
+  };
+}
+
 function mapPriority(r) {
   return { item: r.item, status: r.status, added: r.added, link: r.link };
 }
@@ -162,6 +189,7 @@ export function buildDigest({ wikiRoot, agent, today, fs }) {
   const summaryText = readIfExists(fs, summaryPath);
   const memoryText = readIfExists(fs, memoryPath);
   const storyboardText = readIfExists(fs, storyboardPath);
+  const weeklyLogText = readIfExists(fs, weeklyLogPath(wikiRoot, agent, today));
 
   const { active } = filterExpired(parseClaims(memoryText ?? ""), today);
   const { owned, cross } = splitPriorities(
@@ -176,6 +204,16 @@ export function buildDigest({ wikiRoot, agent, today, fs }) {
     claims: active.map(mapClaim),
     storyboard_items: parseStoryboardItems(storyboardText ?? "", agent),
     inbox_count: countInbox(summaryText),
+    summary_headroom: headroom(
+      summaryText ?? "",
+      SUMMARY_LINE_BUDGET,
+      SUMMARY_WORD_BUDGET,
+    ),
+    weekly_log_headroom: headroom(
+      weeklyLogText ?? "",
+      WEEKLY_LOG_LINE_BUDGET,
+      WEEKLY_LOG_WORD_BUDGET,
+    ),
     storyboard_path: fs.existsSync(storyboardPath)
       ? path.relative(path.dirname(wikiRoot) || ".", storyboardPath)
       : "",

package/src/cli-definition.js

@@ -11,18 +11,17 @@ import { runAuditCommand } from "./commands/audit.js";
 import { runFixCommand } from "./commands/fix.js";
 
 /**
- * Build the `fit-wiki` libcli definition. The agent/sender defaults read the
- * injected `env` rather than the ambient `process.env` so this module carries
- * no ambient dependency; the bin shim passes `runtime.proc.env`. The version is
- * resolved by libcli's `createCli` from the bin's `packageJsonUrl`. Each
- * subcommand carries a `handler` and (for subcommand-bearing commands)
- * `args`/`argsUsage` so `cli.dispatch` can route to the per-command handler
- * with a frozen `ctx`.
+ * Build the `fit-wiki` libcli definition. Agent identity is never resolved from
+ * the environment: agent-scoped subcommands require an explicit `--agent`
+ * (`--from` for `memo`) and fail closed without it, so this module carries no
+ * ambient agent identity. The version is resolved by libcli's `createCli` from
+ * the bin's `packageJsonUrl`. Each subcommand carries a `handler` and (for
+ * subcommand-bearing commands) `args`/`argsUsage` so `cli.dispatch` can route to
+ * the per-command handler with a frozen `ctx`.
  *
- * @param {Record<string, string>} env - The process env (`runtime.proc.env`).
  * @returns {object} The libcli definition.
  */
-export function createDefinition(env) {
+export function createDefinition() {
   const wikiRootOpt = {
     "wiki-root": {
       type: "string",
@@ -33,9 +32,7 @@ export function createDefinition(env) {
   const agentOpt = {
     agent: {
       type: "string",
-      description:
-        "Agent name (falls back to LIBEVAL_AGENT_PROFILE, then staff-engineer)",
-      default: env.LIBEVAL_AGENT_PROFILE || "staff-engineer",
+      description: "Agent name (required; no environment fallback)",
     },
   };
 
@@ -148,12 +145,17 @@ export function createDefinition(env) {
       },
       {
         name: "rotate",
-        description: "Force-rotate the current weekly log to a sealed part",
+        description: "Rotate the current weekly log to a sealed part",
         handler: runRotateCommand,
         options: {
           ...agentOpt,
           ...wikiRootOpt,
           ...todayOpt,
+          force: {
+            type: "boolean",
+            description:
+              "Seal even an under-budget log (the header-only floor still holds)",
+          },
         },
       },
       {
@@ -188,8 +190,7 @@ export function createDefinition(env) {
           from: {
             type: "string",
             description:
-              "Sender agent name (falls back to LIBEVAL_AGENT_PROFILE env var)",
-            default: env.LIBEVAL_AGENT_PROFILE,
+              "Sender agent name (required; no environment fallback)",
           },
           to: {
             type: "string",
@@ -239,7 +240,7 @@ export function createDefinition(env) {
         name: "pull",
         description: "Pull remote wiki changes into the local working tree",
         handler: runPullCommand,
-        options: { ...wikiRootOpt },
+        options: { ...agentOpt, ...wikiRootOpt, ...todayOpt },
       },
     ],
     globalOptions: {

package/src/commands/audit.js

@@ -17,7 +17,12 @@ export function runAuditCommand(ctx) {
   const wikiRoot = options["wiki-root"] || path.join(projectRoot, "wiki");
   const today = options.today || currentDayIso(runtime);
 
-  const auditCtx = buildContext({ wikiRoot, today, fs: runtime.fsSync });
+  const auditCtx = buildContext({
+    wikiRoot,
+    today,
+    fs: runtime.fsSync,
+    subprocess: runtime.subprocess,
+  });
   const findings = runRules(RULES, auditCtx, { resolveScope });
 
   runtime.proc.stdout.write(

package/src/commands/boot.js

@@ -1,5 +1,6 @@
 import { buildDigest } from "../boot.js";
 import { currentDayIso } from "../util/clock.js";
+import { requireAgentFlag } from "../util/agent-flag.js";
 import { resolveWikiRoot } from "../util/wiki-dir.js";
 
 function renderMarkdown(digest) {
@@ -43,8 +44,12 @@ function renderMarkdown(digest) {
 export function runBootCommand(ctx) {
   const { runtime } = ctx.deps;
   const options = ctx.options;
-  const agent =
-    options.agent || runtime.proc.env.LIBEVAL_AGENT_PROFILE || "staff-engineer";
+  const resolved = requireAgentFlag(options, {
+    command: "boot",
+    example: "fit-wiki boot --agent staff-engineer",
+  });
+  if (!resolved.ok) return resolved;
+  const agent = resolved.agent;
 
   const wikiRoot = resolveWikiRoot(runtime, options);
   const today = options.today || currentDayIso(runtime);

package/src/commands/claim.js

@@ -8,7 +8,25 @@ import {
   filterExpired,
 } from "../active-claims.js";
 import { currentDayIso } from "../util/clock.js";
+import { requireAgentFlag } from "../util/agent-flag.js";
 import { resolveWikiRoot } from "../util/wiki-dir.js";
+import { refusalEnvelope } from "../secret-gate.js";
+import { AncestryRefusal } from "../wiki-sync.js";
+
+/** Non-zero envelope returned when the ancestry guard refused publication. */
+const NOT_PUBLISHED = {
+  ok: false,
+  code: 1,
+};
+
+/** Build the not-published refusal message for the given guard refusal. */
+function notPublishedMessage(err) {
+  return (
+    `${err.message}\n` +
+    "The row was written to MEMORY.md but is NOT published — it remains an " +
+    "uncommitted working-tree change.\n"
+  );
+}
 
 function readMemory(runtime, memPath) {
   if (!runtime.fsSync.existsSync(memPath)) return "";
@@ -19,20 +37,72 @@ function memoryPath(runtime, options) {
   return path.join(resolveWikiRoot(runtime, options), "MEMORY.md");
 }
 
-async function pushWiki(wikiSync, runtime, message) {
-  if (!wikiSync) return;
+/**
+ * Push the claim/release MEMORY.md change through the secret-gated push path
+ * and translate the result into a command envelope. A secret block fails the
+ * command closed (`{ ok: false, code: 1 }`) and names the finding or the
+ * scanner absence on stderr — distinct from a *network* push failure, which
+ * still degrades to "saved locally" and succeeds (`{ ok: true }`).
+ *
+ * The `reapply` closure re-derives this row against the fresh tip if the
+ * landing contends, so a parallel writer's row is never erased. An
+ * ancestry-guard refusal ({@link AncestryRefusal}) is rethrown so the caller's
+ * `pushRowOrRefuse` can map it to the not-published non-zero envelope; every
+ * other throw is a network/credential failure that degrades to "saved locally".
+ *
+ * @param {object} wikiSync - The WikiSync collaborator (may be absent in tests).
+ * @param {object} runtime - The runtime bag (for stdout/stderr).
+ * @param {string} message - The commit message.
+ * @param {(freshText: string) => string | null} [reapply] - Re-derives the row
+ *   against the fresh tip when the landing contends.
+ * @returns {Promise<{ok: boolean, code?: number}>}
+ */
+async function pushWiki(wikiSync, runtime, message, reapply) {
+  if (!wikiSync) return { ok: true };
+  let result;
   try {
     await wikiSync.inheritIdentity();
     // claim/release contract is a 1-line MEMORY.md change; the pathspec keeps
-    // foreign uncommitted files from parallel writers out of the commit.
-    const result = await wikiSync.commitAndPush(message, ["MEMORY.md"]);
-    if (result.pushed)
-      runtime.proc.stdout.write("push: committed and pushed\n");
+    // foreign uncommitted files from parallel writers out of the commit. The
+    // `reapply` closure re-derives this row against the fresh tip if the landing
+    // contends, so a parallel writer's row is never erased.
+    result = await wikiSync.commitAndPush(message, ["MEMORY.md"], { reapply });
   } catch (err) {
+    // An ancestry-guard refusal pierces the saved-locally degradation: it must
+    // reach a non-zero exit so the session stops rather than scroll past. Every
+    // other failure is a network/credential failure: preserve fire-and-forget
+    // "saved locally" — the change is on disk and the command still succeeds.
+    if (err instanceof AncestryRefusal) throw err;
     createLogger("wiki", runtime).warn(
       "claim",
       `push failed (saved locally): ${err.message}`,
     );
+    return { ok: true };
+  }
+  const refusal = refusalEnvelope(runtime, result);
+  if (refusal) return refusal;
+  if (result.pushed) runtime.proc.stdout.write("push: committed and pushed\n");
+  return { ok: true };
+}
+
+/**
+ * Push a written claim/release row, mapping an ancestry-guard refusal to the
+ * not-published non-zero envelope and any other outcome to `{ ok: true }`. The
+ * row is already written to MEMORY.md; on refusal it stays as an uncommitted
+ * working-tree change. The `reapply` closure re-derives the same row against
+ * the fresh tip when the landing contends.
+ */
+async function pushRowOrRefuse(wikiSync, runtime, message, reapply) {
+  try {
+    // Propagate pushWiki's envelope so a secret-gate refusal ({ ok: false })
+    // fails the command closed; a clean push returns { ok: true }.
+    return await pushWiki(wikiSync, runtime, message, reapply);
+  } catch (err) {
+    if (err instanceof AncestryRefusal) {
+      runtime.proc.stderr.write(notPublishedMessage(err));
+      return NOT_PUBLISHED;
+    }
+    throw err;
   }
 }
 
@@ -40,14 +110,13 @@ async function pushWiki(wikiSync, runtime, message) {
 export async function runClaimCommand(ctx) {
   const { runtime, wikiSync } = ctx.deps;
   const options = ctx.options;
-  const agent = options.agent || runtime.proc.env.LIBEVAL_AGENT_PROFILE;
-  if (!agent) {
-    return {
-      ok: false,
-      code: 2,
-      error: "claim requires --agent or LIBEVAL_AGENT_PROFILE",
-    };
-  }
+  const resolved = requireAgentFlag(options, {
+    command: "claim",
+    example:
+      "fit-wiki claim --agent staff-engineer --target spec-NNNN --branch claude/...",
+  });
+  if (!resolved.ok) return resolved;
+  const agent = resolved.agent;
   if (!options.target || !options.branch) {
     return {
       ok: false,
@@ -59,14 +128,15 @@ export async function runClaimCommand(ctx) {
   const expires = options["expires-at"] || addDays(today, 7);
   const memPath = memoryPath(runtime, options);
   const text = readMemory(runtime, memPath);
-  const result = appendClaim(text, {
+  const claim = {
     agent,
     target: options.target,
     branch: options.branch,
     pr: options.pr || null,
     claimed_at: today,
     expires_at: expires,
-  });
+  };
+  const result = appendClaim(text, claim);
   if (!result.inserted) {
     createLogger("wiki", runtime).warn(
       "claim",
@@ -76,8 +146,17 @@ export async function runClaimCommand(ctx) {
   }
   runtime.fsSync.writeFileSync(memPath, result.text);
   runtime.proc.stdout.write(`claimed ${options.target} (expires ${expires})\n`);
-  await pushWiki(wikiSync, runtime, `wiki: claim ${options.target}`);
-  return { ok: true };
+  // Re-apply the same append against the fresh tip if the landing contends.
+  const reapply = (fresh) => {
+    const r = appendClaim(fresh, claim);
+    return r.inserted ? r.text : null;
+  };
+  return pushRowOrRefuse(
+    wikiSync,
+    runtime,
+    `wiki: claim ${options.target}`,
+    reapply,
+  );
 }
 
 /** Remove a claim row. `--expired` cleans every row past expires_at. */
@@ -102,18 +181,35 @@ export async function runReleaseCommand(ctx) {
     }
     runtime.fsSync.writeFileSync(memPath, current);
     runtime.proc.stdout.write(`released ${count} expired claim(s)\n`);
-    await pushWiki(wikiSync, runtime, "wiki: release expired claims");
-    return { ok: true };
-  }
-
-  const agent = options.agent || runtime.proc.env.LIBEVAL_AGENT_PROFILE;
-  if (!agent) {
-    return {
-      ok: false,
-      code: 2,
-      error: "release requires --agent or --expired",
+    // Re-derive expiry against the fresh tip so a renewal landed since the stale
+    // read survives; only still-expired rows are removed.
+    const reapply = (fresh) => {
+      const freshExpired = filterExpired(parseClaims(fresh), today).expired;
+      let next = fresh;
+      let anyRemoved = false;
+      for (const c of freshExpired) {
+        const r = removeClaim(next, { agent: c.agent, target: c.target });
+        if (r.removed) {
+          next = r.text;
+          anyRemoved = true;
+        }
+      }
+      return anyRemoved ? next : null;
     };
+    return pushRowOrRefuse(
+      wikiSync,
+      runtime,
+      "wiki: release expired claims",
+      reapply,
+    );
   }
+
+  const resolved = requireAgentFlag(options, {
+    command: "release",
+    example: "fit-wiki release --agent staff-engineer --target spec-NNNN",
+  });
+  if (!resolved.ok) return resolved;
+  const agent = resolved.agent;
   if (!options.target) {
     return {
       ok: false,
@@ -127,9 +223,19 @@ export async function runReleaseCommand(ctx) {
     runtime.proc.stdout.write(
       `no matching claim for ${agent}/${options.target}\n`,
     );
-  } else {
-    runtime.proc.stdout.write(`released ${options.target}\n`);
-    await pushWiki(wikiSync, runtime, `wiki: release ${options.target}`);
+    return { ok: true };
   }
-  return { ok: true };
+  runtime.proc.stdout.write(`released ${options.target}\n`);
+  // Re-apply the same removal against the fresh tip if the landing contends;
+  // re-removing an absent row is a no-op, so a re-release never resurrects it.
+  const reapply = (fresh) => {
+    const r = removeClaim(fresh, { agent, target: options.target });
+    return r.removed ? r.text : null;
+  };
+  return pushRowOrRefuse(
+    wikiSync,
+    runtime,
+    `wiki: release ${options.target}`,
+    reapply,
+  );
 }

package/src/commands/fix.js

@@ -38,14 +38,18 @@ function classOf(finding) {
  * Handing the agent the full contract for the files it edits — not just the
  * failing rules — stops it fixing one finding by breaking another (dropping
  * the `**Last run**:` line, appending a section after `## Open Blockers`, …).
+ *
+ * Only static-string hints are listed: a function hint is a per-finding
+ * resolved command (a `rotate` remediation the agent never performs), not a
+ * file invariant, so listing it would leak its source text into the prompt.
  */
 function invariantContract(findings) {
   const scopes = new Set(
     findings.map((f) => RULES.find((r) => r.id === f.id)?.scope),
   );
-  return RULES.filter((r) => scopes.has(r.scope) && r.hint).map(
-    (r) => `- ${r.id} — ${r.hint}`,
-  );
+  return RULES.filter(
+    (r) => scopes.has(r.scope) && typeof r.hint === "string",
+  ).map((r) => `- ${r.id} — ${r.hint}`);
 }
 
 /**
@@ -106,7 +110,7 @@ function sealMainLog(agent, { wikiRoot, today, projectRoot, fs, out, err }) {
       wikiRoot,
       agent,
       today,
-      0,
+      { lines: 0, words: 0 },
       { force: true },
       fs,
     );
@@ -282,7 +286,11 @@ export async function runFixCommand(ctx) {
 
   // The agent's edits change the result, so re-read and re-audit each round.
   const audit = () =>
-    runRules(RULES, buildContext({ wikiRoot, today, fs }), { resolveScope });
+    runRules(
+      RULES,
+      buildContext({ wikiRoot, today, fs, subprocess: runtime.subprocess }),
+      { resolveScope },
+    );
   // The agent only ever gets prose-judgment (`agent`-class) findings. A
   // `rotate` finding that survived the pre-pass (e.g. a prior-week log) is
   // unfixable by the agent — and trimming append-only history to satisfy a