@forwardimpact/libwiki 0.2.35 → 0.3.1

package/src/budget-gate.js

@@ -1,14 +1,14 @@
 // 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
+// outgoing tree between landing and push. It 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.
+// gate reuses the audit's budget rules by reference. It resolves the rule
+// objects named by `BUDGET_RULE_IDS`. It then 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. It never routes
+// through the `runRules` engine, which drops the numeric value and emits
+// nothing under cap. It never edits. It refuses, which keeps commits local.
 
 import path from "node:path";
 import { BUDGET_RULE_IDS, RULES } from "./audit/rules.js";
@@ -16,9 +16,10 @@ 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.
+ * Resolve `BUDGET_RULE_IDS` to their rule objects in `RULES`. Tag each one with
+ * the count axis its id implies. It throws if a named id is missing from
+ * `RULES`, so a rule rename surfaces here and does not silently drop a
+ * predicate.
  * @returns {Array<{id: string, scope: string, axis: 'words'|'lines', check: Function}>}
  */
 export function budgetRules() {
@@ -36,10 +37,10 @@ export function budgetRules() {
 }
 
 /**
- * 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.
+ * Enumerate which wiki files are budgeted. Reuse the audit's classification.
+ * Subjects carry an absolute `path`. Reduce each one to the `<file>` half of
+ * `git show <ref>:<file>`, relative to `wikiRoot`. This function reads no count
+ * off the working-dir subject. It reads 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}>}
@@ -56,12 +57,12 @@ export function budgetedFiles(ctx, wikiRoot) {
 }
 
 /**
- * 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
+ * Measure the budget predicates for the tree at `ref`. Read each budgeted
+ * file's blob through the cwd-bound `showFile`. Count it once with the audit's
+ * counters. Then, for every budget rule on that file's scope, record 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.
+ * at the ref counts as 0. This matches the audit's "missing counts as empty"
+ * posture. An unreadable ref makes `showFile` throw, and the throw 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
@@ -88,15 +89,16 @@ export async function measureRef(showFile, ref, budgeted) {
 }
 
 /**
- * Compare the outgoing tree against the two push-input baselines and return the
+ * Compare the outgoing tree against the two push-input baselines. 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.
+ * the worse (higher) of the session-base and origin-tip values. An absent
+ * measurement counts 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. The gate surfaces a
+ * `summary.*` breach on a file listed in `exemptSummaryFiles` instead of
+ * refusing it. Those files are the memo-delivery seam. A block on a delivery
+ * into deficient headroom would enforce a contradiction. The memo-headroom
+ * measures exist to resolve that contradiction.
  *
  * @param {object} args
  * @param {Map<string, Map<string, {value: number, overCap: boolean}>>} args.outgoing
@@ -137,14 +139,14 @@ export function revalidateBudgets({
 }
 
 /**
- * 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.
+ * Run the gate end to end over the outgoing tree. Build the audit context.
+ * Enumerate the budgeted files. Measure the committed `HEAD` (what publishes)
+ * and the two push-input baselines through the one `measureRef` path. Then
+ * compute 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 and the push
+ * proceeds. The gate does not fabricate 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
@@ -181,7 +183,8 @@ export async function runBudgetGate({
     }
     originTip = await measureRef(showFile, originRef, budgeted);
   } catch {
-    // Cannot prove a regression (unreadable ref) ⇒ do not refuse; fail-visible.
+    // Cannot prove a regression (unreadable ref) ⇒ do not refuse. This is the
+    // fail-visible posture.
     return { refusals: [], surfaced: [] };
   }
   return revalidateBudgets({

package/src/budget.js

@@ -1,9 +1,9 @@
 // Canonical line- and word-counters for the budgeted wiki surfaces. The audit
 // (`audit/scopes.js`) and the rotation primitive's bisecting seal
-// (`weekly-log.js`) both import this one pair so a part the seal calls
-// conforming cannot later be flagged by an audit counting differently.
+// (`weekly-log.js`) both import this one pair. So no audit that counts
+// differently can later flag a part the seal accepts as conforming.
 
-/** Count lines, not counting a trailing newline as an empty final line. */
+/** Count lines. Do not count a trailing newline as an empty final line. */
 export function countLines(text) {
   return text.split("\n").length - (text.endsWith("\n") ? 1 : 0);
 }

package/src/cli-definition.js

@@ -14,13 +14,13 @@ import { runFixCommand } from "./commands/fix.js";
 import { runLedgerCommand } from "./commands/ledger.js";
 
 /**
- * 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`.
+ * Build the `gemba-wiki` libcli definition. This module never resolves agent
+ * identity from the environment. Agent-scoped subcommands require an explicit
+ * `--agent` (`--from` for `memo`). They fail closed without it, so this module
+ * carries no ambient agent identity. libcli's `createCli` resolves the version
+ * from the bin's `packageJsonUrl`. Each subcommand carries a `handler`. A
+ * command that takes subcommands also carries `args`/`argsUsage`, so
+ * `cli.dispatch` can route to the per-command handler with a frozen `ctx`.
  *
  * @returns {object} The libcli definition.
  */
@@ -47,13 +47,13 @@ export function createDefinition() {
   };
 
   return {
-    name: "fit-wiki",
-    description: "Wiki lifecycle management for the Kata agent system",
+    name: "gemba-wiki",
+    description: "Manage the wiki lifecycle for the Kata agent system",
     commands: [
       {
         name: "boot",
         description:
-          "Print on-boot digest (priorities, claims, storyboard items) as JSON",
+          "Print the on-boot digest (priorities, claims, storyboard items) as JSON",
         handler: runBootCommand,
         options: {
           ...agentOpt,
@@ -101,9 +101,12 @@ export function createDefinition() {
           ...todayOpt,
           target: {
             type: "string",
-            description: "What is being claimed (spec id, PR id, etc.)",
+            description: "Target to claim (spec id, PR id, etc.)",
+          },
+          branch: {
+            type: "string",
+            description: "Branch that carries the work",
           },
-          branch: { type: "string", description: "Branch carrying the work" },
           pr: { type: "string", description: "Optional PR id" },
           "expires-at": {
             type: "string",
@@ -142,7 +145,7 @@ export function createDefinition() {
           },
           owner: {
             type: "string",
-            description: "Owner field when promoting (default: --agent)",
+            description: "Owner field for promote (default: --agent)",
           },
         },
       },
@@ -190,7 +193,7 @@ export function createDefinition() {
           "dry-run": {
             type: "boolean",
             description:
-              "Print the issue body and intended action without calling gh",
+              "Print the issue body and intended action. Do not call gh",
           },
         },
       },
@@ -217,7 +220,7 @@ export function createDefinition() {
           to: {
             type: "string",
             description:
-              'Target agent name, or "all" to broadcast (sender is skipped)',
+              'Target agent name, or "all" to broadcast (skips the sender)',
           },
           message: {
             type: "string",
@@ -287,7 +290,7 @@ export function createDefinition() {
             type: "string",
             multiple: true,
             description:
-              "Pathspec(s) limiting the write-set; omit to land the session's dirty set",
+              "Pathspec(s) that limit the write-set. Omit to land the session's dirty set",
           },
         },
       },
@@ -330,7 +333,7 @@ export function createDefinition() {
           gapped: {
             type: "boolean",
             description:
-              "Render double-allocation losers as a gap, not a renumber",
+              "Render double-allocation losers as a gap instead of a renumber",
           },
           issue: {
             type: "string",
@@ -348,21 +351,21 @@ export function createDefinition() {
       },
     },
     examples: [
-      "fit-wiki boot --agent staff-engineer",
-      'fit-wiki log decision --agent staff-engineer --surveyed "..." --chosen "..." --rationale "..."',
-      "fit-wiki claim --agent staff-engineer --target spec-NNNN --branch claude/...",
-      "fit-wiki release --agent staff-engineer --target spec-NNNN",
-      "fit-wiki inbox list --agent staff-engineer",
-      "fit-wiki rotate --agent staff-engineer",
-      "fit-wiki audit",
-      "fit-wiki curate",
-      "fit-wiki fix",
-      'fit-wiki memo --from staff-engineer --to security-engineer --message "audit d642ff0c"',
-      "fit-wiki refresh",
-      "fit-wiki product-mix",
-      "fit-wiki init",
-      "fit-wiki push",
-      "fit-wiki pull",
+      "gemba-wiki boot --agent staff-engineer",
+      'gemba-wiki log decision --agent staff-engineer --surveyed "..." --chosen "..." --rationale "..."',
+      "gemba-wiki claim --agent staff-engineer --target spec-NNNN --branch claude/...",
+      "gemba-wiki release --agent staff-engineer --target spec-NNNN",
+      "gemba-wiki inbox list --agent staff-engineer",
+      "gemba-wiki rotate --agent staff-engineer",
+      "gemba-wiki audit",
+      "gemba-wiki curate",
+      "gemba-wiki fix",
+      'gemba-wiki memo --from staff-engineer --to security-engineer --message "audit d642ff0c"',
+      "gemba-wiki refresh",
+      "gemba-wiki product-mix",
+      "gemba-wiki init",
+      "gemba-wiki push",
+      "gemba-wiki pull",
     ],
     documentation: [
       {

package/src/commands/audit.js

@@ -11,8 +11,8 @@ import { resolveProjectRoot } from "../util/wiki-dir.js";
 
 /**
  * Run the wiki audit and return its findings plus the resolved project root.
- * Shared by `runAuditCommand` (emits them) and `runCurateCommand` (routes
- * them to an issue) so the two cannot drift.
+ * `runAuditCommand` emits the findings. `runCurateCommand` routes them to an
+ * issue. Both share this function, so the two cannot drift.
  * @param {import("@forwardimpact/libcli").InvocationContext} ctx
  * @returns {{ findings: object[], projectRoot: string }}
  */
@@ -32,7 +32,7 @@ export function auditWiki(ctx) {
   return { findings: runRules(RULES, auditCtx, { resolveScope }), projectRoot };
 }
 
-/** Run the wiki audit and emit findings. JSON via --format json. */
+/** Run the wiki audit and emit findings. Use --format json for JSON. */
 export function runAuditCommand(ctx) {
   const { runtime } = ctx.deps;
   const options = ctx.options;

package/src/commands/boot.js

@@ -40,13 +40,13 @@ function renderMarkdown(digest) {
   return lines.join("\n");
 }
 
-/** Print the on-boot digest for the calling agent. JSON by default; --format markdown renders prose. */
+/** Print the on-boot digest for the agent that runs it. JSON by default. --format markdown renders prose. */
 export function runBootCommand(ctx) {
   const { runtime } = ctx.deps;
   const options = ctx.options;
   const resolved = requireAgentFlag(options, {
     command: "boot",
-    example: "fit-wiki boot --agent staff-engineer",
+    example: "gemba-wiki boot --agent staff-engineer",
   });
   if (!resolved.ok) return resolved;
   const agent = resolved.agent;

package/src/commands/claim.js

@@ -24,9 +24,9 @@ const NOT_PUBLISHED = {
 };
 
 // Failure reasons that, on the claim/release surfaces, are an unsafe-state
-// refusal (D7/D9 family) rather than a saved-locally success (D1): the refusal
-// fires before the local write is publishable, or leaves the tree unsafe for a
-// later whole-tree sweep, so the surface must exit non-zero.
+// refusal (D7/D9 family) rather than a saved-locally success (D1). The refusal
+// fires before the local write is publishable. Or it leaves the tree unsafe
+// for a later whole-tree sweep. So the surface must exit non-zero.
 const UNSAFE_STATE_REASONS = new Set([
   PUSH_REASONS.PRECONDITION,
   PUSH_REASONS.RESIDUE_CONFLICT,
@@ -37,7 +37,7 @@ const UNSAFE_STATE_REASONS = new Set([
 function notPublishedMessage(err) {
   return (
     `${err.message}\n` +
-    "The row was written to MEMORY.md but is NOT published — it remains an " +
+    "The row is in MEMORY.md but is NOT published. It remains an " +
     "uncommitted working-tree change.\n"
   );
 }
@@ -52,23 +52,25 @@ function memoryPath(runtime, options) {
 }
 
 /**
- * Push the claim/release MEMORY.md change and translate the honest outcome
- * (the honest-CLI contract) into a command envelope, composed with the singleton merge
- * discipline (the singleton merge discipline) and the secret/ancestry guards:
- * - landed (grounded or re-applied) ⇒ `{ ok: true }`, success message printed;
+ * Push the claim/release MEMORY.md change. Translate the honest outcome (the
+ * honest-CLI contract) into a command envelope. Compose it with the singleton
+ * merge discipline (the singleton merge discipline) and the secret/ancestry
+ * guards:
+ * - landed (grounded or re-applied) ⇒ `{ ok: true }` with a printed success
+ *   message;
  * - `rejected`/`transport` ⇒ `{ ok: true }` with a saved-locally warning (the
- *   landed-locally row is complete; the session-end push is its retry);
+ *   landed-locally row is complete, and the session-end push is its retry);
  * - `precondition`/`residue-conflict`/`conservation` ⇒ `{ ok: false, code: 1 }`
- *   (D7/D9 unsafe-state family — the row is not published and the tree may be
- *   left unsafe for a later whole-tree sweep);
+ *   (the D7/D9 unsafe-state family, where the row is not published and the
+ *   tree may be left unsafe for a later whole-tree sweep);
  * - a secret-gate refusal ⇒ `{ ok: false, code: 1 }` ({@link refusalEnvelope});
- * - an {@link AncestryRefusal} is rethrown so `pushRowOrRefuse` maps it to the
- *   not-published non-zero envelope;
+ * - this function rethrows an {@link AncestryRefusal} so `pushRowOrRefuse`
+ *   maps it to the not-published non-zero envelope;
  * - any other thrown error is a network/credential failure that degrades to
  *   "saved locally" (`{ 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.
+ * landing contends, so this command never erases a parallel writer's row.
  *
  * @param {object} wikiSync - The WikiSync collaborator (may be absent in tests).
  * @param {object} runtime - The runtime bag (for stdout/stderr).
@@ -82,37 +84,38 @@ async function pushWiki(wikiSync, runtime, message, reapply) {
   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. The
-    // `reapply` closure re-derives this row against the fresh tip if the landing
-    // contends (the singleton merge discipline), so a parallel writer's row is never erased.
+    // The claim/release contract is a 1-line MEMORY.md change. The pathspec
+    // keeps 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 (the singleton merge discipline), so this command never
+    // erases a parallel writer's row.
     result = await wikiSync.commitAndPush(message, ["MEMORY.md"], { reapply });
   } catch (err) {
-    // An ancestry-guard refusal pierces the saved-locally degradation: rethrow
-    // so pushRowOrRefuse maps it to the not-published non-zero envelope.
+    // An ancestry-guard refusal pierces the saved-locally degradation. Rethrow
+    // it so pushRowOrRefuse maps it to the not-published non-zero envelope.
     if (err instanceof AncestryRefusal) throw err;
     if (err instanceof WikiPushFailure) {
-      // D7/D9 unsafe-state family: the row is not published and the tree may be
-      // left unsafe for a later sweep — fail the command closed (non-zero).
+      // D7/D9 unsafe-state family. The row is not published, and the tree may
+      // be left unsafe for a later sweep. Fail the command closed (non-zero).
       if (UNSAFE_STATE_REASONS.has(err.reason)) {
         runtime.proc.stderr.write(`${err.message}\n`);
         return { ok: false, code: 1 };
       }
-      // rejected / transport: the local row landed; warn and keep zero exit.
+      // rejected / transport: the local row landed. Warn and keep zero exit.
       runtime.proc.stderr.write(
-        `saved locally — not yet visible to parallel sessions (${err.reason}): ${err.message}\n`,
+        `saved locally, not yet visible to parallel sessions (${err.reason}): ${err.message}\n`,
       );
       return { ok: true };
     }
-    // Any other failure: preserve fire-and-forget "saved locally" — the change
-    // is on disk and the command still succeeds.
+    // Any other failure: preserve fire-and-forget "saved locally". The change
+    // is on disk, and the command still succeeds.
     createLogger("wiki", runtime).warn(
       "claim",
       `push failed (saved locally): ${err.message}`,
     );
     return { ok: true };
   }
-  // A secret-gate refusal fails the command closed; a grounded-landed or a
+  // A secret-gate refusal fails the command closed. A grounded-landed or a
   // re-applied push reports success.
   const refusal = refusalEnvelope(runtime, result);
   if (refusal) return refusal;
@@ -123,16 +126,17 @@ async function pushWiki(wikiSync, runtime, message, reapply) {
 }
 
 /**
- * Push a written claim/release row, mapping an ancestry-guard refusal to the
- * not-published non-zero envelope and any other outcome to `pushWiki`'s
- * envelope. The row is already written to MEMORY.md; on refusal it stays as an
+ * Push a written claim/release row. Map an ancestry-guard refusal to the
+ * not-published non-zero envelope. Map any other outcome to `pushWiki`'s
+ * envelope. The row is already in MEMORY.md. On a 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 or unsafe-state refusal
-    // ({ ok: false }) fails the command closed; a clean push returns { ok: true }.
+    // ({ 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) {
@@ -143,14 +147,14 @@ async function pushRowOrRefuse(wikiSync, runtime, message, reapply) {
   }
 }
 
-/** Insert a row into MEMORY.md `## Active Claims`. Refuses if (agent, target) already present. */
+/** Insert a row into MEMORY.md `## Active Claims`. It refuses if (agent, target) is already present. */
 export async function runClaimCommand(ctx) {
   const { runtime, wikiSync } = ctx.deps;
   const options = ctx.options;
   const resolved = requireAgentFlag(options, {
     command: "claim",
     example:
-      "fit-wiki claim --agent staff-engineer --target spec-NNNN --branch claude/...",
+      "gemba-wiki claim --agent staff-engineer --target spec-NNNN --branch claude/...",
   });
   if (!resolved.ok) return resolved;
   const agent = resolved.agent;
@@ -162,8 +166,9 @@ export async function runClaimCommand(ctx) {
     };
   }
   const today = options.today || currentDayIso(runtime);
-  // 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.
+  // Default expiry is claim+1 day. A claim is a short-lived "actively shipping
+  // this now" assertion. It is 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);
@@ -220,8 +225,8 @@ export async function runReleaseCommand(ctx) {
     }
     runtime.fsSync.writeFileSync(memPath, current);
     runtime.proc.stdout.write(`released ${count} expired claim(s)\n`);
-    // Re-derive expiry against the fresh tip so a renewal landed since the stale
-    // read survives; only still-expired rows are removed.
+    // Re-derive expiry against the fresh tip so a renewal landed since the
+    // stale read survives. Remove only the rows that are still expired.
     const reapply = (fresh) => {
       const freshExpired = filterExpired(parseClaims(fresh), today).expired;
       let next = fresh;
@@ -245,7 +250,7 @@ export async function runReleaseCommand(ctx) {
 
   const resolved = requireAgentFlag(options, {
     command: "release",
-    example: "fit-wiki release --agent staff-engineer --target spec-NNNN",
+    example: "gemba-wiki release --agent staff-engineer --target spec-NNNN",
   });
   if (!resolved.ok) return resolved;
   const agent = resolved.agent;
@@ -265,8 +270,9 @@ export async function runReleaseCommand(ctx) {
     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.
+  // Re-apply the same removal against the fresh tip if the landing contends.
+  // A second removal of 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;