@forwardimpact/libwiki 0.3.0 → 0.3.1

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,8 +150,8 @@ 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).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/libwiki",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "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 = [];

package/src/audit/rules.js

@@ -56,9 +56,9 @@ import {
 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.
+// outgoing tree. This set names the ids, so the gate selects rules by
+// membership of the set. A future predicate change to any of these
+// rules then flows through the gate with no gate-code change.
 export const BUDGET_RULE_IDS = new Set([
   "summary.line-budget",
   "summary.word-budget",
@@ -110,7 +110,7 @@ export const RULES = [
     severity: "fail",
     check: lineBudget(SUMMARY_LINE_BUDGET),
     message: (_s, r) => `${r.value} lines (limit ${SUMMARY_LINE_BUDGET})`,
-    hint: "trim history into the weekly log; the summary holds settled state, not history",
+    hint: "trim history into the weekly log. the summary holds settled state. it does not hold history",
   },
   {
     id: "summary.word-budget",
@@ -118,7 +118,7 @@ export const RULES = [
     severity: "fail",
     check: wordBudget(SUMMARY_WORD_BUDGET),
     message: (_s, r) => `${r.value} words (limit ${SUMMARY_WORD_BUDGET})`,
-    hint: "trim history into the weekly log; the summary holds settled state, not history",
+    hint: "trim history into the weekly log. the summary holds settled state. it does not hold history",
   },
   {
     id: "summary.h1-agent-matches-filename",
@@ -176,7 +176,7 @@ export const RULES = [
     check: headingGrammarDrift,
     message: (_s, r) =>
       `Entry heading '${r.observed}' does not match the dated grammar`,
-    hint: "weekly-log entry headings must be '## YYYY-MM-DD'; open entries with `gemba-wiki log decision/note`, which emit a conforming heading the rotation seam-finder can split",
+    hint: "weekly-log entry headings must be '## YYYY-MM-DD'. open entries with `gemba-wiki log decision/note`, which emit a heading that conforms and that the rotation seam-finder can split",
   },
   {
     id: "decision-block.heading-within-5",
@@ -189,9 +189,9 @@ export const RULES = [
     }),
     message: (_s, r) =>
       r.nearMiss
-        ? `Entry opens with '${r.nearMiss}'; the heading must be exactly '${DECISION_HEADING}' — move the suffix into the body`
+        ? `Entry opens with '${r.nearMiss}'. The heading must be exactly '${DECISION_HEADING}'. Move the suffix into the body`
         : `Entry lacks a line that is exactly '${DECISION_HEADING}'`,
-    hint: `open each '## YYYY-MM-DD' entry with \`gemba-wiki log decision\`, which emits a line containing exactly '${DECISION_HEADING}' (no suffix — the check is an exact match); put the one-line summary in the body below it, drawn from the entry's own narrative — do not invent rationale the entry does not support`,
+    hint: `open each '## YYYY-MM-DD' entry with \`gemba-wiki log decision\`. it emits a line that contains exactly '${DECISION_HEADING}' (no suffix, because the check is an exact match). put the one-line summary in the body below it, drawn from the entry's own narrative. do not invent rationale the entry does not support`,
   },
 
   // -- Weekly logs (sealed parts) --
@@ -211,7 +211,7 @@ export const RULES = [
     check: headingGrammarDrift,
     message: (_s, r) =>
       `Entry heading '${r.observed}' does not match the dated grammar`,
-    hint: "weekly-log entry headings must be '## YYYY-MM-DD'; open entries with `gemba-wiki log decision/note`, which emit a conforming heading the rotation seam-finder can split",
+    hint: "weekly-log entry headings must be '## YYYY-MM-DD'. open entries with `gemba-wiki log decision/note`, which emit a heading that conforms and that the rotation seam-finder can split",
   },
   {
     id: "weekly-log-part.line-budget",
@@ -220,7 +220,7 @@ export const RULES = [
     remediation: "rotate",
     check: lineBudget(WEEKLY_LOG_LINE_BUDGET),
     message: (_s, r) => `${r.value} lines (limit ${WEEKLY_LOG_LINE_BUDGET})`,
-    hint: "`bunx gemba-wiki fix` re-bisects an over-budget part at its day-section seams and, for a lone over-cap day, at its '### ' block seams; only a single '### ' block that alone exceeds the budget remains for a human to shorten",
+    hint: "`bunx gemba-wiki fix` re-bisects an over-budget part at its day-section seams and, for a lone over-cap day, at its '### ' block seams. only a single '### ' block that alone exceeds the budget remains for a human to shorten",
   },
   {
     id: "weekly-log-part.word-budget",
@@ -229,7 +229,7 @@ export const RULES = [
     remediation: "rotate",
     check: wordBudget(WEEKLY_LOG_WORD_BUDGET),
     message: (_s, r) => `${r.value} words (limit ${WEEKLY_LOG_WORD_BUDGET})`,
-    hint: "`bunx gemba-wiki fix` re-bisects an over-budget part at its day-section seams and, for a lone over-cap day, at its '### ' block seams; only a single '### ' block that alone exceeds the budget remains for a human to shorten",
+    hint: "`bunx gemba-wiki fix` re-bisects an over-budget part at its day-section seams and, for a lone over-cap day, at its '### ' block seams. only a single '### ' block that alone exceeds the budget remains for a human to shorten",
   },
   {
     id: "weekly-log-part.h1-agent-matches-filename",
@@ -242,10 +242,11 @@ export const RULES = [
   },
 
   // -- Carry surfaces --
-  // No `h1-shape` rule: unlike the weekly logs (classified on filename alone),
-  // the carry classifier (scopes.js) requires the Carry H1 before assigning the
-  // scope, so a malformed-H1 file is left unclassified rather than reaching an
-  // h1-shape rule. The two rules below are the reachable, failable set (SC #2).
+  // There is no `h1-shape` rule. The classifier classifies a weekly log on
+  // filename alone. The carry classifier (scopes.js) instead requires the
+  // Carry H1 before it assigns the scope. So it leaves a malformed-H1 file
+  // unclassified, and that file never reaches an h1-shape rule. The two rules
+  // below are the reachable, failable set (SC #2).
 
   {
     id: "carry-surface.h1-agent-matches-filename",
@@ -282,7 +283,7 @@ export const RULES = [
     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",
+    hint: "MEMORY.md holds settled cross-cutting state. it does not hold 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",
@@ -291,7 +292,7 @@ export const RULES = [
     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",
+    hint: "MEMORY.md holds settled cross-cutting state. it does not hold 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",
@@ -400,7 +401,7 @@ export const RULES = [
     when: storyboardExists,
     check: lineBudget(STORYBOARD_LINE_BUDGET),
     message: (_s, r) => `${r.value} lines (limit ${STORYBOARD_LINE_BUDGET})`,
-    hint: "see per-section word budgets in storyboard-template.md; retire prior-session Headlines/Notes/Next-review entries to weekly logs",
+    hint: "see per-section word budgets in storyboard-template.md. retire prior-session Headlines/Notes/Next-review entries to weekly logs",
   },
   {
     id: "storyboard.word-budget",
@@ -409,7 +410,7 @@ export const RULES = [
     when: storyboardExists,
     check: wordBudget(STORYBOARD_WORD_BUDGET),
     message: (_s, r) => `${r.value} words (limit ${STORYBOARD_WORD_BUDGET})`,
-    hint: "see per-section word budgets in storyboard-template.md; retire prior-session Headlines/Notes/Next-review entries to weekly logs",
+    hint: "see per-section word budgets in storyboard-template.md. retire prior-session Headlines/Notes/Next-review entries to weekly logs",
   },
   {
     id: "storyboard.markers-balanced.xmr",
@@ -454,8 +455,9 @@ export const RULES = [
     hint: "every '<!-- agent-experiments -->' needs a matching '<!-- /agent-experiments -->'",
   },
 
-  // -- Metrics CSVs (union merge keeps both sides on concurrent appends;
-  // exact-duplicate rows are surfaced here, never silently removed) --
+  // -- Metrics CSVs (union merge keeps both sides on concurrent appends. The
+  // audit surfaces exact-duplicate rows here. It never silently removes
+  // them) --
 
   {
     id: "metrics-csv.duplicate-row",
@@ -464,7 +466,7 @@ export const RULES = [
     check: duplicateCsvRows,
     message: (_s, r) =>
       `Duplicate metrics row at line ${r.lineNo} (exact match of an earlier row)`,
-    hint: "remove the surplus row, or differentiate a genuinely-distinct measurement by editing its run id or note so the rows are no longer identical",
+    hint: "remove the surplus row, or differentiate a genuinely-distinct measurement. edit its run id or note so the rows are no longer identical",
   },
 
   // -- STATUS.md rows (per-migration-unit sub-row schema) --
@@ -478,17 +480,18 @@ export const RULES = [
   // -- Filename admission --
 
   // The `admission` resolver yields one subject per git-tracked path the
-  // filename grammar rejects, so the check always fires. Flag-for-human: a
-  // wrong automated move or delete destroys memory, so `fix` routes this to the
-  // human report (any non-`agent` remediation class does) and never touches the
-  // file.
+  // filename grammar rejects, so the check always fires. This finding is a
+  // flag for a human. A wrong automated move or delete destroys memory, so
+  // `fix` routes it to the human report and never touches the file. Any
+  // non-`agent` remediation class does the same.
   {
     id: "admission.not-in-grammar",
     scope: "admission",
     severity: "fail",
     remediation: "flag",
     check: () => ({}),
-    message: (s) => `${s.relPath} matches no wiki filename grammar class`,
+    message: (s) =>
+      `${s.relPath} matches no class in the wiki filename grammar`,
     hint: "rename to an admitted class, or extend the Wiki Filename Grammar section in memory-protocol.md and audit/grammar.js together (the single admission path)",
   },
 ];