@forwardimpact/libwiki 0.2.26 → 0.2.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/libwiki",
-  "version": "0.2.26",
+  "version": "0.2.27",
   "description": "Wiki lifecycle primitives — stable memory for agent teams so coordination persists across sessions.",
   "keywords": [
     "wiki",

package/src/audit/scopes.js

@@ -2,6 +2,7 @@ import path from "node:path";
 import { yearMonth } from "@forwardimpact/libutil";
 import { parseClaims } from "../active-claims.js";
 import { countLines, countWords } from "../budget.js";
+import { parseStatusRowId } from "../status.js";
 import {
   PRIORITY_INDEX_HEADING,
   WEEKLY_LOG_NAME_RE,
@@ -120,9 +121,12 @@ function readOptional(filePath, fs) {
 
 /**
  * Parse the rows inside STATUS.md's fenced block into audit subjects. Lines
- * outside the ``` fence (header prose) and blank lines are skipped.
+ * outside the ``` fence (header prose) and blank lines are skipped. Each row
+ * carries a `kind` from {@link parseStatusRowId} (`"spec"`, `"experiment"`, or
+ * `null` for an unrecognized id); spec-shaped rules read the positional
+ * `id`/`phase`/`status` fields, experiment rules read `cells`.
  * @param {string} statusText - The full STATUS.md contents.
- * @returns {Array<{lineNo: number, text: string, cells: string[], id: string, phase: string, status: string}>}
+ * @returns {Array<{lineNo: number, text: string, cells: string[], id: string, phase: string, status: string, kind: string|null}>}
  */
 function parseStatusRows(statusText) {
   const lines = statusText.split("\n");
@@ -136,6 +140,12 @@ function parseStatusRows(statusText) {
     }
     if (!inFence || line.trim() === "") continue;
     const cells = line.split("\t");
+    // Classify by id prefix so a malformed `exp:` row (e.g. wrong cell count)
+    // is still routed to the experiment rules, which flag it — rather than
+    // slipping through the spec-shaped rules. parseStatusRowId returns the
+    // structured fields only for a well-formed row; the rules read `cells`.
+    const isExp = typeof cells[0] === "string" && cells[0].startsWith("exp:");
+    const parsed = parseStatusRowId(cells[0], cells);
     rows.push({
       lineNo: i + 1,
       text: line,
@@ -143,6 +153,7 @@ function parseStatusRows(statusText) {
       id: cells[0],
       phase: cells[1],
       status: cells[2],
+      kind: isExp ? "experiment" : parsed ? parsed.kind : null,
     });
   }
   return rows;

package/src/audit/status-row.js

@@ -1,24 +1,37 @@
 import { STATUS_ID_REGEX } from "../status.js";
 
-// Validate every row inside wiki/STATUS.md's code fence against the
-// `{id}<TAB>{phase}<TAB>{status}` shape. Rows are resolved by the `status-row`
-// scope in scopes.js; each subject carries `{ cells, id, phase, status, text }`.
+// Validate every row inside wiki/STATUS.md's code fence. Rows are resolved by
+// the `status-row` scope in scopes.js; each subject carries
+// `{ cells, id, phase, status, kind, text }`. Two row kinds share the fence:
+//
+//   spec        `{id}<TAB>{phase}<TAB>{status}` — three cells
+//   experiment  `exp:{issue}<TAB>{state}<TAB>{pin}<TAB>{plan-ref}` — four cells
+//
+// Spec-shaped rules run for every non-experiment row (`kind !== "experiment"`,
+// which includes an unrecognized id so a malformed id still flags). Experiment
+// rules run only for `kind === "experiment"`.
 
 const PHASES = new Set(["spec", "design", "plan"]);
 const STATUSES = new Set(["draft", "approved", "implemented", "cancelled"]);
+const EXP_STATES = new Set(["registered", "approved", "cancelled"]);
+const PIN_RE = /^[0-9a-f]{40}$/;
 
-const hasThreeCells = (s) => s.cells.length === 3;
+const isSpecShaped = (s) => s.kind !== "experiment";
+const isExperiment = (s) => s.kind === "experiment";
+const hasThreeCells = (s) => isSpecShaped(s) && s.cells.length === 3;
+const hasFourCells = (s) => isExperiment(s) && s.cells.length === 4;
 
 export const STATUS_ROW_RULES = [
   {
     id: "status-row.shape",
     scope: "status-row",
     severity: "fail",
+    when: isSpecShaped,
     check: (s) =>
-      hasThreeCells(s) ? null : { actual: s.cells.length, text: s.text },
+      s.cells.length === 3 ? null : { actual: s.cells.length, text: s.text },
     message: (_s, r) =>
       `${r.actual} tab-separated field(s), expected 3: "${r.text}"`,
-    hint: "each STATUS row is `{id}<TAB>{phase}<TAB>{status}`",
+    hint: "each spec STATUS row is `{id}<TAB>{phase}<TAB>{status}`",
   },
   {
     id: "status-row.id-format",
@@ -48,4 +61,76 @@ export const STATUS_ROW_RULES = [
       `Bad status '${r.status}' (expected draft|approved|implemented|cancelled)`,
     hint: "status is one of draft, approved, implemented, cancelled",
   },
+  {
+    id: "status-row.exp-shape",
+    scope: "status-row",
+    severity: "fail",
+    when: isExperiment,
+    check: (s) =>
+      s.cells.length === 4 ? null : { actual: s.cells.length, text: s.text },
+    message: (_s, r) =>
+      `${r.actual} tab-separated field(s), expected 4: "${r.text}"`,
+    hint: "each experiment row is `exp:{issue}<TAB>{state}<TAB>{pin}<TAB>{plan-ref}`",
+  },
+  {
+    // An experiment-kind row is classified by its `exp:` id prefix
+    // (scopes.js), so the spec `id-format` rule is skipped for it; this rule
+    // enforces the `exp:\d+` id so a non-numeric issue (e.g. `exp:abc`) flags
+    // rather than auditing clean — keeping the audit aligned with
+    // STATUS_ID_REGEX / parseStatusRowId.
+    id: "status-row.exp-id-format",
+    scope: "status-row",
+    severity: "fail",
+    when: isExperiment,
+    check: (s) => (/^exp:\d+$/.test(s.id) ? null : { id: s.id }),
+    message: (_s, r) => `Bad experiment id '${r.id}' (expected exp:NNN)`,
+    hint: "an experiment id is `exp:` followed by the issue number",
+  },
+  {
+    id: "status-row.exp-state",
+    scope: "status-row",
+    severity: "fail",
+    when: hasFourCells,
+    check: (s) => (EXP_STATES.has(s.cells[1]) ? null : { state: s.cells[1] }),
+    message: (_s, r) =>
+      `Bad experiment state '${r.state}' (expected registered|approved|cancelled)`,
+    hint: "experiment state is one of registered, approved, cancelled",
+  },
+  {
+    id: "status-row.exp-pin",
+    scope: "status-row",
+    severity: "fail",
+    when: hasFourCells,
+    // The pin is decidable per state, with no "ever approved" inference: a
+    // `registered` row has no pin (`-`); an `approved` row pins the 40-hex
+    // head; a `cancelled` row may carry the retained pin or `-` (it may or may
+    // not have been approved before cancellation), so both are accepted.
+    check: (s) => {
+      const [, state, pin] = s.cells;
+      if (state === "registered") {
+        return pin === "-" ? null : { state, pin, want: "-" };
+      }
+      if (state === "approved") {
+        return PIN_RE.test(pin) ? null : { state, pin, want: "a 40-hex SHA" };
+      }
+      if (state === "cancelled") {
+        return pin === "-" || PIN_RE.test(pin)
+          ? null
+          : { state, pin, want: "`-` or a 40-hex SHA" };
+      }
+      return null; // bad state already flagged by exp-state
+    },
+    message: (_s, r) =>
+      `Bad pin '${r.pin}' for state '${r.state}' (expected ${r.want})`,
+    hint: "registered pins `-`; approved pins a 40-hex SHA; cancelled pins either",
+  },
+  {
+    id: "status-row.exp-planref",
+    scope: "status-row",
+    severity: "fail",
+    when: hasFourCells,
+    check: (s) => (/^#\d+$/.test(s.cells[3]) ? null : { planRef: s.cells[3] }),
+    message: (_s, r) => `Bad plan-ref '${r.planRef}' (expected #NNN)`,
+    hint: "the plan-ref names the issue carrying the execution plan, e.g. #NNN",
+  },
 ];

package/src/status.js

@@ -1,19 +1,46 @@
-// STATUS.md row ids may carry a `/<unit>` suffix denoting a
-// per-migration-unit sub-row of a master spec (`1370/libutil`, …). The master
-// `NNNN` row advances only when every sub-row reads `plan implemented`.
+// STATUS.md rows come in two kinds. A spec row's id is four digits with an
+// optional `/<unit>` suffix denoting a per-migration-unit sub-row of a master
+// spec (`1370/libutil`, …); the master `NNNN` row advances only when every
+// sub-row reads `plan implemented`. An experiment row's id is `exp:<issue>`
+// and the row carries four tab cells — `exp:<issue><TAB><state><TAB><pin>
+// <TAB><plan-ref>` — keying the merge-gate approval path for a spec-less
+// experiment PR. The `exp:` namespace cannot match the spec id's `^\d{4}`
+// anchor, so the two kinds never collide for any issue-number width.
 
-/** Matches a status-row id: four digits, optionally a `/<unit>` suffix. */
-export const STATUS_ID_REGEX = /^\d{4}(\/[a-z0-9-]+)?$/;
+/** Matches a status-row id: a four-digit spec id (optional `/<unit>`) or `exp:<issue>`. */
+export const STATUS_ID_REGEX = /^(\d{4}(\/[a-z0-9-]+)?|exp:\d+)$/;
 
 /**
- * Parse a status-row id into its master spec id and optional unit suffix.
- * @param {string} id - The id field of a STATUS.md row.
- * @returns {{ specId: string, unit: string|null }|null} Parsed parts, or null
- *   when the id does not match {@link STATUS_ID_REGEX}.
+ * Classify a status-row id into its kind and parts. Experiment rows are
+ * identified by an `exp:` id together with a four-cell row; the optional
+ * `cells` array supplies that count (a bare `exp:` id without four cells is
+ * not a valid row and yields null).
+ * @param {string} id - The id field (cell 0) of a STATUS.md row.
+ * @param {string[]} [cells] - The full tab-separated cells of the row, when
+ *   available. Required to classify an experiment row.
+ * @returns {(
+ *   {kind: "spec", specId: string, unit: string|null} |
+ *   {kind: "experiment", issue: string, state: string, pin: string, planRef: string} |
+ *   null
+ * )} Parsed parts, or null when the id/row does not match a known kind.
  */
-export function parseStatusRowId(id) {
+export function parseStatusRowId(id, cells) {
   if (typeof id !== "string" || !STATUS_ID_REGEX.test(id)) return null;
+  if (id.startsWith("exp:")) {
+    if (!Array.isArray(cells) || cells.length !== 4) return null;
+    return {
+      kind: "experiment",
+      issue: id.slice("exp:".length),
+      state: cells[1],
+      pin: cells[2],
+      planRef: cells[3],
+    };
+  }
   const slash = id.indexOf("/");
-  if (slash === -1) return { specId: id, unit: null };
-  return { specId: id.slice(0, slash), unit: id.slice(slash + 1) };
+  if (slash === -1) return { kind: "spec", specId: id, unit: null };
+  return {
+    kind: "spec",
+    specId: id.slice(0, slash),
+    unit: id.slice(slash + 1),
+  };
 }