@forwardimpact/libwiki 0.3.0 → 0.3.2

package/README.md

@@ -8,11 +8,11 @@ parallel work.
 
 <!-- END:description -->
 
-A wiki under `wiki/` holds each agent's running state: per-agent summaries,
+A wiki under `wiki/` holds each agent's current state: per-agent summaries,
 weekly logs, shared memory (priorities and active claims), and monthly
-storyboards. `libwiki` keeps that wiki coherent across sessions — agents boot
-from it, write decisions back, send memos to each other, and audit the
-result against a declarative rule set.
+storyboards. `libwiki` keeps that wiki coherent across sessions. Agents boot
+from it. They write decisions back. They send memos to each other. They audit
+the result against a declarative rule set.
 
 The primary interface is the `gemba-wiki` CLI. The library also exposes a few
 helpers for programmatic use.
@@ -29,7 +29,7 @@ npx gemba-wiki audit
 
 Every command accepts `--wiki-root` (default `wiki/`) and `--today` (default
 today, ISO date). Agent-scoped commands require an explicit `--agent <name>`
-(`--from` for `memo`) and fail closed without it — there is no environment
+(`--from` for `memo`). They fail closed without it. There is no environment
 fallback. The only exception is `release --expired`, a cross-agent cleanup
 sweep that runs without `--agent`.
 
@@ -50,8 +50,8 @@ npx gemba-wiki log note     --agent X --field "PR Status" --body "merged"
 npx gemba-wiki log done     --agent X
 ```
 
-Appends to `wiki/<agent>-YYYY-WVV.md`. Auto-rotates to `*-partN.md` when the
-line budget would be exceeded.
+`log` appends to `wiki/<agent>-YYYY-WVV.md`. It auto-rotates to `*-partN.md`
+when the log would exceed the line budget.
 
 ### `claim` / `release` — coordinate work
 
@@ -61,9 +61,10 @@ npx gemba-wiki release --agent X --target spec-NNNN
 npx gemba-wiki release --expired
 ```
 
-Maintains the `## Active Claims` table in `MEMORY.md`. Duplicates refused;
-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.
+These commands maintain the `## Active Claims` table in `MEMORY.md`. They
+refuse duplicates. An absent row means the claim is settled. `expires_at`
+defaults to `claimed_at + 1 day`. A claim is a short-lived "shipping this
+now" assertion. It is not a lease.
 
 ### `inbox` — triage memos
 
@@ -74,8 +75,8 @@ npx gemba-wiki inbox promote --agent X --index 0 [--owner X]
 npx gemba-wiki inbox drop    --agent X --index 0
 ```
 
-Reads bullets under the `<!-- memo:inbox -->` marker in the agent's summary.
-`promote` moves a bullet into the cross-cutting priorities table.
+`inbox` reads bullets under the `<!-- memo:inbox -->` marker in the agent's
+summary. `promote` moves a bullet into the cross-cutting priorities table.
 
 ### `memo` — cross-team coordination
 
@@ -84,7 +85,7 @@ npx gemba-wiki memo --from X --to Y   --message "audit d642ff0c"
 npx gemba-wiki memo --from X --to all --message "new XmR baseline"
 ```
 
-Inserts a bullet `- YYYY-MM-DD from **X**: ...` after the recipient's
+`memo` inserts a bullet `- YYYY-MM-DD from **X**: ...` after the recipient's
 `<!-- memo:inbox -->` marker.
 
 ### `audit` — verify wiki state
@@ -93,16 +94,16 @@ Inserts a bullet `- YYYY-MM-DD from **X**: ...` after the recipient's
 npx gemba-wiki audit [--format text|json]
 ```
 
-Runs a declarative catalogue of rules across the wiki. Exits 0 on pass, 1
-on any failure. Text output: `WARN ...` and `FAIL ...` lines plus a
+`audit` runs a declarative catalogue of rules across the wiki. It exits 0 on
+pass and 1 on any failure. Text output: `WARN ...` and `FAIL ...` lines plus a
 `RESULT: ...` trailer. JSON output:
 
 ```json
 { "result": "pass|fail", "failures": [...], "warnings": [...] }
 ```
 
-Each finding carries a stable `id` for filtering. The catalogue lives in
-`src/audit/rules.js` — adding a rule is one literal.
+Each finding carries a stable `id` so you can filter on it. The catalogue
+lives in `src/audit/rules.js`. Each new rule is one literal.
 
 ### `rotate` — force a part split
 
@@ -110,8 +111,8 @@ Each finding carries a stable `id` for filtering. The catalogue lives in
 npx gemba-wiki rotate --agent X
 ```
 
-Renames the current weekly log to the next `-partN.md` and starts a fresh
-main file.
+`rotate` renames the current weekly log to the next `-partN.md`. It then
+starts a fresh main file.
 
 ### `refresh` — re-render storyboard blocks
 
@@ -119,11 +120,11 @@ main file.
 npx gemba-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. Also sweeps
-every expired row from `MEMORY.md ## Active Claims` as part of the same
-deterministic refresh.
+`refresh` re-renders `<!-- xmr:metric:csv-path -->` and
+`<!-- obstacles:open[:Nd] -->` marker blocks inside a storyboard from the CSV
+and GitHub state behind them. Default path: `wiki/storyboard-YYYY-MMM.md` for
+the current month. It also sweeps every expired row from
+`MEMORY.md ## Active Claims` as part of the same deterministic refresh.
 
 ### `init` / `push` / `pull` — wiki working tree
 
@@ -133,9 +134,9 @@ npx gemba-wiki push
 npx gemba-wiki pull
 ```
 
-`init` clones the wiki repo if missing, scaffolds Active Claims in
-`MEMORY.md`, and creates `wiki/metrics/<skill>/` directories. `push` and
-`pull` are thin wrappers over `git` with conflict handling.
+`init` clones the wiki repo if it is missing. It scaffolds Active Claims in
+`MEMORY.md`. It creates `wiki/metrics/<skill>/` directories. `push` and
+`pull` are thin wrappers over `git` that handle conflicts.
 
 ## Programmatic API
 
@@ -149,14 +150,33 @@ import {
   bullet after the `<!-- memo:inbox -->` marker.
 - `listAgents({ agentsDir, wikiRoot })` — discover agents from
   `.claude/agents/*.md` and derive wiki summary paths.
-- `insertMarkers({ agentsDir, wikiRoot })` — idempotent insertion of the
-  memo marker into existing summaries.
+- `insertMarkers({ agentsDir, wikiRoot })` — insert the memo marker into
+  existing summaries. The call is idempotent.
 - `runAudit(rules, ctx)` — pure audit engine: `(rules, ctx) → findings[]`.
 - `RULES` — the audit rule catalogue (one literal per rule).
 
 ## Documentation
 
-- [Operate a Predictable Agent Team](https://www.forwardimpact.team/docs/libraries/predictable-team/index.md)
-- [Send a Memo or Update a Storyboard](https://www.forwardimpact.team/docs/libraries/predictable-team/wiki-operations/index.md)
-- [Audit and Auto-Fix the Wiki](https://www.forwardimpact.team/docs/libraries/predictable-team/wiki-integrity/index.md)
-- [Allocate Collision-Ledger Entries for Parallel Work](https://www.forwardimpact.team/docs/libraries/predictable-team/collision-ledger/index.md)
+- [Operate a Predictable Agent Team](https://www.gemba.team/docs/predictable-team/index.md)
+- [Send a Memo or Update a Storyboard](https://www.gemba.team/docs/predictable-team/wiki-operations/index.md)
+- [Audit and Auto-Fix the Wiki](https://www.gemba.team/docs/predictable-team/wiki-integrity/index.md)
+- [Allocate Collision-Ledger Entries for Parallel Work](https://www.gemba.team/docs/predictable-team/collision-ledger/index.md)
+
+## Documentation home
+
+libwiki is an import-only library. It declares no `bin`. The `gemba-wiki`
+command ships with the Gemba product, which imports these modules. Run it
+with `npx gemba-wiki`.
+
+The package publishes as `@forwardimpact/libwiki` on the Forward Impact npm
+scope. Install it with `npm install @forwardimpact/libwiki`. Its task guides
+live on the Gemba site at <https://www.gemba.team/>. The Forward Impact library
+guide tree at <https://www.forwardimpact.team/docs/libraries/index.md> is not
+this library's guide home.
+
+**Decision (2026-08-26):** the split package scope and guide host are
+deliberate. libwiki stays a Gear npm package, so `package.json .homepage`
+keeps <https://www.forwardimpact.team>. The agent-memory guides moved to
+gemba.team with the rest of the Gemba product. The `## Documentation` list
+above carries the current URLs. Old `forwardimpact.team/docs/libraries/`
+addresses forward to gemba.team.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/libwiki",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Wiki lifecycle for agent teams — persistent memory, declarative integrity audits, and a collision ledger so coordination survives across sessions and parallel work.",
   "keywords": [
     "wiki",

package/src/active-claims.js

@@ -5,9 +5,9 @@ import {
   ACTIVE_CLAIMS_TABLE_SEPARATOR,
 } from "./constants.js";
 
-// The header matcher is shared with the audit (via constants.js); the loose
-// separator and the 6-cell row parser stay local — they serve parsing, not the
-// audit's column-count check.
+// This module and the audit share the header matcher through constants.js.
+// The loose separator and the 6-cell row parser stay local. This module uses
+// them to parse the table. The audit's column-count check does not use them.
 const SEPARATOR_RE = /^\|\s*---\s*\|/;
 const ROW_RE =
   /^\|\s*([^|]*?)\s*\|\s*([^|]*?)\s*\|\s*([^|]*?)\s*\|\s*([^|]*?)\s*\|\s*([^|]*?)\s*\|\s*([^|]*?)\s*\|\s*$/;
@@ -169,7 +169,7 @@ export function appendClaim(memoryText, claim, _today) {
   };
 }
 
-/** Remove the claim row matching (agent, target). Idempotent. */
+/** Remove the claim row that matches (agent, target). Idempotent. */
 export function removeClaim(memoryText, { agent, target }) {
   const lines = memoryText.split("\n");
   const heading = findSection(lines);
@@ -186,7 +186,7 @@ export function removeClaim(memoryText, { agent, target }) {
   return { text: memoryText, removed: false };
 }
 
-/** Split claims into active vs expired based on `expires_at >= today`. */
+/** Split claims into active and expired, based on `expires_at >= today`. */
 export function filterExpired(claims, today) {
   const active = [];
   const expired = [];

package/src/agent-roster.js

@@ -2,8 +2,8 @@ import path from "node:path";
 import { BROADCAST_TARGET } from "./constants.js";
 
 /**
- * List all agent markdown files in the agents directory, returning agent names
- * and summary paths.
+ * List all agent markdown files in the agents directory. Return the agent
+ * names and the summary paths.
  * @param {{agentsDir: string, wikiRoot: string}} dirs
  * @param {object} fs - Sync filesystem surface (`runtime.fsSync`).
  */

package/src/audit/admission.js

@@ -1,13 +1,15 @@
 import path from "node:path";
 
-// Tracked-file enumerator for the admission scope. Yields the
-// admission universe: the wiki-relative paths the filename grammar governs.
+// Tracked-file enumerator for the admission scope. It yields the
+// admission universe. That universe holds the wiki-relative paths the
+// filename grammar governs.
 //
-// The universe is the on-disk file tree under `wikiRoot`, intersected with the
-// git index when git state is present. Where there is no git state — a fresh
-// bootstrap or a test fixture — the universe is the whole walk. This keeps the
-// rule's true positive (a *git-tracked* residue) in scope while excluding VCS
-// internals and uncommitted scratch where a real repo exists.
+// The enumerator walks the on-disk file tree under `wikiRoot`. It then
+// intersects the walk with the git index when git state is present. Without
+// git state (a fresh bootstrap or a test fixture), the universe is the whole
+// walk. This keeps the rule's true positive (a *git-tracked* residue) in
+// scope. It also excludes VCS internals and uncommitted scratch where a real
+// repo exists.
 
 /** Recursively collect file paths (wiki-relative, POSIX) under `dir`. */
 function walk(absDir, wikiRoot, fs, out) {
@@ -25,9 +27,10 @@ function walk(absDir, wikiRoot, fs, out) {
 
 /**
  * Read the git index at `wikiRoot` as a set of wiki-relative paths, or `null`
- * when there is no git state (no `.git`, or the path is not a work tree — both
- * surface as a non-zero `git ls-files` exit). `-z` is used so paths with
- * unusual characters round-trip; output is NUL-delimited and relative to the
+ * when there is no git state. There is no git state when `.git` is absent, or
+ * when the path is not a work tree. Both cases surface as a non-zero
+ * `git ls-files` exit. The `-z` flag makes paths with unusual characters
+ * round-trip. Git delimits the output with NUL. The paths are relative to the
  * repository root, which is `wikiRoot`.
  */
 function trackedSet(wikiRoot, subprocess) {
@@ -39,7 +42,7 @@ function trackedSet(wikiRoot, subprocess) {
 /**
  * Enumerate the admission universe under `wikiRoot`.
  * @param {{wikiRoot: string, fs: object, subprocess: object}} options
- *   `fs` is the sync filesystem surface (`runtime.fsSync`); `subprocess` is
+ *   `fs` is the sync filesystem surface (`runtime.fsSync`). `subprocess` is
  *   `runtime.subprocess` (its `runSync` shells out to git).
  * @returns {string[]} Wiki-relative POSIX paths, tracked-filtered when git state exists.
  */

package/src/audit/conflict-markers-rule.js

@@ -1,14 +1,14 @@
 import { scanConflictMarkers } from "../conflict-markers.js";
 
 // Fail-severity audit rule that flags unresolved git conflict markers in any
-// audited wiki surface. Resolved by the `conflict-scan` scope (scopes.js),
-// which yields one `{ path, text, fenceExempt }` subject per file. The rule is
-// deliberately distinct from the budget rules: a marker block can fit inside
-// the word/line budget, and when it does trip the budget the budget hint
-// ("trim history") is actively wrong for this defect. A co-occurring size
-// breach therefore reports BOTH findings, never misattributing structure as
-// size. The hint directs the writer to adjudicate the merged form, never to
-// trim.
+// audited wiki surface. The `conflict-scan` scope (scopes.js) resolves it.
+// That scope yields one `{ path, text, fenceExempt }` subject per file. The
+// rule is deliberately distinct from the budget rules. A marker block can fit
+// inside the word/line budget. When it does trip the budget, the budget hint
+// ("trim history") is actively wrong for this defect. So a co-occurring size
+// breach reports BOTH findings. It never misattributes structure as size. The
+// hint directs the writer to adjudicate the merged form. It never directs the
+// writer to trim.
 export const CONFLICT_MARKER_RULE = {
   id: "conflict.markers",
   scope: "conflict-scan",
@@ -20,5 +20,5 @@ export const CONFLICT_MARKER_RULE = {
       : hits.map((h) => ({ lineNo: h.lineNo, kind: h.kind }));
   },
   message: (_s, r) => `unresolved git conflict marker (${r.kind})`,
-  hint: "adjudicate the merged form: reconcile the two variants into the intended content, then delete the markers — this is corruption, not a size breach, so do not shorten history to clear it",
+  hint: "adjudicate the merged form. reconcile the two variants into the intended content, then delete the markers. this defect is corruption. it is not a size breach, so do not shorten history to clear it",
 };

package/src/audit/grammar.js

@@ -1,10 +1,10 @@
 import path from "node:path";
 import { WEEKLY_LOG_NAME_RE, WEEKLY_LOG_PART_NAME_RE } from "../constants.js";
 
-// The wiki filename admission grammar. A pure classifier: given a
-// wiki-relative path, decide whether the filename grammar admits it. The
+// The wiki filename admission grammar. It is a pure classifier. It takes a
+// wiki-relative path and decides whether the filename grammar admits it. The
 // normative prose lives in memory-protocol.md's "Wiki Filename Grammar"
-// section; this module is its enforcement — one home per policy, so the two
+// section. This module enforces that prose. One home per policy, so the two
 // cannot drift. The audit's `admission` scope is the only consumer.
 
 const NAMED_LEDGERS = new Set(["Home.md", "MEMORY.md", "STATUS.md"]);
@@ -12,9 +12,9 @@ const STORYBOARD_RE = /^storyboard-\d{4}-M\d{2}\.md$/;
 const DATED_DELIVERABLE_RE = /^(.+)-\d{4}-\d{2}-\d{2}\.md$/;
 
 // Calendar tokens, anchored at hyphen-segment boundaries so a token must occupy
-// whole `-`-delimited segments: `8080` *inside* a longer segment
-// (`release8080-notes`) is not a token, but a standalone `8080` segment is a
-// bare year. Anchoring with `(?:^|-)…(?=-|$)` is load-bearing — a per-segment
+// whole `-`-delimited segments. `8080` *inside* a longer segment
+// (`release8080-notes`) is not a token. A standalone `8080` segment is a
+// bare year. The anchors `(?:^|-)…(?=-|$)` are load-bearing. A per-segment
 // split would silently miss the multi-segment week/month/date tokens.
 const CALENDAR_TOKEN_RES = [
   /(?:^|-)\d{4}-W\d{2}(?=-|$)/, // week  YYYY-Www
@@ -33,7 +33,10 @@ export function hasCalendarToken(stem) {
   return CALENDAR_TOKEN_RES.some((re) => re.test(stem));
 }
 
-/** A root-level `.md` file whose stem carries no calendar token: the summary class. */
+/**
+ * A root-level `.md` file whose stem carries no calendar token. This is the
+ * summary class.
+ */
 function isSummaryName(base) {
   if (!base.endsWith(".md")) return false;
   return !hasCalendarToken(base.slice(0, -".md".length));
@@ -41,8 +44,8 @@ function isSummaryName(base) {
 
 /**
  * The summary-class stem of a root-level basename, or `null`. Named ledgers
- * (`MEMORY.md` etc.) are not summaries. Used to derive the `rootSummaryAgents`
- * set that gates `<agent>/` sidecar directory admission.
+ * (`MEMORY.md` etc.) are not summaries. Callers use it to derive the
+ * `rootSummaryAgents` set that gates `<agent>/` sidecar directory admission.
  * @param {string} base - A root-level basename.
  * @returns {string|null}
  */
@@ -59,23 +62,23 @@ function classifyRootFile(base) {
   }
   if (STORYBOARD_RE.test(base)) return "admitted";
   const dated = base.match(DATED_DELIVERABLE_RE);
-  // A dated deliverable's `<topic>` must itself be token-free, so a trailing
-  // date cannot smuggle a token-bearing stem (`…-history-YYYY-MM-DD.md`) in.
+  // A dated deliverable's `<topic>` must itself be token-free, so a date at
+  // the end cannot smuggle a token-bearing stem (`…-history-YYYY-MM-DD.md`) in.
   if (dated && !hasCalendarToken(dated[1])) return "admitted";
   if (isSummaryName(base)) return "admitted";
-  // Anything else at the root — non-`.md`, or a token-bearing name matching no
-  // exact dated shape — is rejected.
+  // The classifier rejects anything else at the root. That covers a non-`.md`
+  // name, and a token-bearing name that matches no exact dated shape.
   return "rejected";
 }
 
 /**
  * Classify one wiki-relative path against the filename admission grammar.
  *
- * Root files (no `/`) are classified by their basename. A nested path is
- * admitted iff its first segment is an admitted root-level directory —
- * `metrics` or an `<agent>` that has a root summary-class file — and then every
- * file beneath it is admitted by membership (innards unpoliced). Directory
- * evaluation is at the wiki root level only.
+ * The grammar classifies root files (no `/`) by their basename. It admits a
+ * nested path iff the first segment is an admitted root-level directory. That
+ * is `metrics`, or an `<agent>` that has a root summary-class file. It then
+ * admits every file beneath that directory by membership (innards unpoliced).
+ * The grammar evaluates directories at the wiki root level only.
  *
  * @param {string} relPath - Path relative to the wiki root (POSIX separators).
  * @param {{rootSummaryAgents: Set<string>|string[]}} options

package/src/audit/rule-builders.js

@@ -15,8 +15,8 @@ import {
 // Check builders and the derived matchers they share, extracted from rules.js
 // so the rule table stays under the per-file line cap. Each builder takes a
 // subject (plus optional ctx) and returns null | finding | finding[]. rules.js
-// imports exactly the symbols its rule table references; the pure constants in
-// constants.js/scopes.js it still imports straight from source.
+// imports exactly the symbols its rule table references. It still imports the
+// pure constants in constants.js/scopes.js straight from source.
 
 export const PRIORITY_INDEX_HEADING_RE = new RegExp(
   `^${PRIORITY_INDEX_HEADING}$`,
@@ -28,7 +28,7 @@ export const PRIORITY_SEPARATOR_RE =
 export const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
 
 // improvement-coach is the storyboard facilitator and carries no domain
-// metrics; only the five domain agents need their own H3.
+// metrics. Only the five domain agents need their own H3.
 const STORYBOARD_DOMAIN_AGENTS = [
   "product-manager",
   "release-engineer",
@@ -69,9 +69,9 @@ export const columnCount = (expected) => (s) =>
 export const exists = (s) => (s.exists ? null : {});
 export const expired = (s, ctx) => (s.expires_at < ctx.today ? {} : null);
 
-// The heading must equal `requiredLine` exactly — a suffixed variant like
-// "### Decision — <summary>" does not satisfy it, but is reported as a
-// near miss so the writer fixes the heading instead of hunting for a
+// The heading must equal `requiredLine` exactly. A suffixed variant like
+// "### Decision — <summary>" does not satisfy it. The rule reports the variant
+// as a near miss, so the writer fixes the heading and does not hunt for a
 // "missing" line that is right there.
 function entryHasDecision(lines, startIdx, requiredLine, stopRe) {
   let seen = 0;
@@ -99,11 +99,11 @@ export const decisionWithin5 =
     return offenders.length === 0 ? null : offenders;
   };
 
-// Flag entry-shaped `## ` headings that the rotation seam-finder would skip —
-// the grammar-drift that degrades a whole file to one unsplittable prologue and
-// is otherwise silent (the decision-block rule matches only dated headings).
-// Uses the same WEEKLY_LOG_SEAM_RE the seam-finder uses, so the flagged set is
-// exactly the complement of the rotatable set.
+// Flag entry-shaped `## ` headings that the rotation seam-finder would skip.
+// This is the grammar-drift that degrades a whole file to one unsplittable
+// prologue and is otherwise silent (the decision-block rule matches only dated
+// headings). The check uses the same WEEKLY_LOG_SEAM_RE the seam-finder uses,
+// so the flagged set is exactly the complement of the rotatable set.
 export const headingGrammarDrift = (s) => {
   const offenders = [];
   for (let i = 0; i < s.fileLines.length; i++) {
@@ -178,7 +178,7 @@ export const weeklyAgentMismatch = (s) => {
 // Carry surface: the H1 agent slug (`# <agent> — Carries`) must agree with the
 // filename prefix (`<agent>-carries.md`), the carry analogue of the summary /
 // weekly-log agreement rules. The H1 is the slug form already, so slugify is a
-// no-op for well-formed files; it normalises a stray capitalisation otherwise.
+// no-op for well-formed files. Otherwise it normalises a stray capitalisation.
 export const carryAgentMismatch = (s) => {
   const m = s.firstLine.match(CARRY_SURFACE_H1_RE);
   if (!m) return null;
@@ -186,10 +186,10 @@ export const carryAgentMismatch = (s) => {
   return titleSlug === s.agentPrefix ? null : { titleSlug };
 };
 
-// Each Carry entry is an H3 block; every block must name a clearance trigger
+// Each Carry entry is an H3 block. Every block must name a clearance trigger
 // (the `**Carry-clearance:**` marker). Walk the file's H3 boundaries and emit
-// one finding per block missing the marker — the finding[]-returning shape
-// `nothingAfterH2` uses.
+// one finding for each block that lacks the marker. This uses the same
+// finding[] shape as `nothingAfterH2`.
 export const carryEntryHasClearance = (s) => {
   const offenders = [];
   let blockStart = -1;
@@ -221,10 +221,11 @@ export const AGENT_H3_REQUIREMENTS = STORYBOARD_DOMAIN_AGENTS.map((agent) => ({
 // -- Metrics CSV duplicate rows --
 
 // Report every data line byte-identical to an earlier data line in the same
-// CSV. Line 1 is the header (positionally) and blank lines are skipped; the
-// header is never a duplicate subject. Keying on exact line equality gives the
-// spec's exit path for free: any column edit (run id or note) on one row makes
-// the pair non-identical and stops the finding firing.
+// CSV. Line 1 is the header (positionally) and the check skips blank lines.
+// The header is never a duplicate subject. The check keys on exact line
+// equality, which gives the spec's exit path for free. Any column edit (run id
+// or note) on one row makes the pair non-identical, so the finding no longer
+// fires.
 export const duplicateCsvRows = (s) => {
   const seen = new Set();
   const findings = [];