@tekyzinc/gsd-t 5.17.13 → 5.18.10

package/bin/gsd-t-testplan-lint.cjs

@@ -0,0 +1,437 @@
+#!/usr/bin/env node
+/**
+ * gsd-t-testplan-lint — the A2 test-plan shape gate.
+ *
+ * Contract: .gsd-t/contracts/test-plan-first-contract.md §2–§4
+ * Mold:     templates/TestPlan-spec.md
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * A test plan (`TestPlan-[FeatureArea].md`) is what a reviewer approves BEFORE
+ * any test exists — the row schema and the self-answered-visibility rule are
+ * the whole reason it can be trusted at a glance. This gate checks a plan
+ * against that schema BEFORE the reviewer ever sees it
+ * (`[RULE] plan-gated-before-presentation`): the required section set in
+ * order, the six-column table header exactly, every row in exactly one of
+ * the three states, `Effect on saved data` and `Source` never blank, and the
+ * `## Decided without you` group present and exactly matching the set of
+ * self-answered rows.
+ *
+ * Modelled on the proven shape of `bin/gsd-t-pseudocode-style.cjs`: zero deps,
+ * deterministic, never throws, one JSON envelope, the 0/4/64 exit triple
+ * frozen by the contract §4. The `main()` catch→exit-64 wrapper below is that
+ * SAME frozen halt shape (contract §4: "a gate that cannot decide exits `64`
+ * ... never exits `0` by default") — a HALT, not a fallback: it stops and
+ * reports rather than continuing past a failure with a guessed result.
+ *
+ * Input:  --doc <path> [--json]   |   --dir <dir of TestPlan-*.md> [--json]
+ * Output: JSON envelope { ok, exitCode, violations: [ {kind, detail} ] }
+ * Exit:   0 clean · 4 shape violations · 64 bad input
+ */
+
+"use strict";
+
+const fs = require("fs");
+const { walkSections, parseRows, isFenceToggle, HEADER_CELLS, TABLE_HEADING_RE, tableName: sharedTableName, rowState } = require("./gsd-t-testplan-rows.cjs");
+const path = require("path");
+
+// ─── frozen literals (contract §2–§3) ─────────────────────────────────────
+
+const HEADING_DECIDED = "## Decided without you";
+const MARKER_SELF_ANSWERED = "DECIDED-WITHOUT-YOU";
+const MARKER_GAP = "GAP";
+const MARKER_CONTRADICTION = "GAP:CONTRADICTION";
+const NONE_SOURCED_SENTENCE = "None — every row is sourced.";
+
+// The frozen six-column header, exact text (contract §2.1) — ONE definition, in the shared reader.
+const REQUIRED_COLUMNS = HEADER_CELLS;
+
+// Required top-level sections, in order (mold §"Section order below is FIXED"):
+// Decided without you, at least one Table, Open gaps, Sign-off.
+const REQUIRED_SECTIONS_IN_ORDER = [
+  { key: "decided-without-you", test: (h) => h === HEADING_DECIDED },
+  { key: "table", test: (h) => TABLE_HEADING_RE.test(h) && !!sharedTableName(h), repeatable: true },
+  { key: "open-gaps", test: (h) => h === "## Open gaps" },
+  { key: "sign-off", test: (h) => h === "## Sign-off" },
+];
+
+// ─── parsing (structural, positional — never a substring scan) ────────────
+
+/**
+ * Split a document into an ordered list of `##`-heading sections, each
+ * carrying its raw text and starting line number. Fenced code blocks are
+ * tracked so a `##` INSIDE a fence is never mistaken for a section boundary.
+ * @returns {Array<{heading: string, lines: string[], startLine: number}>}
+ */
+function splitSections(text) {
+  // Shared, fence-aware for ``` AND ~~~ (Red Team M115 run 4: tilde-fenced fake
+  // headings satisfied the required-section walk).
+  return walkSections(text);
+}
+
+/**
+ * Parse the Markdown table rows out of a section's lines, by POSITION (never
+ * a substring search). Skips the header row and the `---` separator row.
+ * @returns {Array<{cells: string[], line: number, raw: string}>}
+ */
+function parseTableRows(sectionLines, sectionStartLine) {
+  return parseRows(sectionLines, sectionStartLine);
+}
+
+/**
+ * Find the table's own header row (the `| Seq | ... |` line) inside a
+ * `## Table:` section, so its exact column text can be checked.
+ * @returns {{cells: string[], line: number}|null}
+ */
+function findTableHeader(sectionLines, sectionStartLine) {
+  // Fence-aware like everything else that reads a section: a table-shaped line
+  // inside a code block is text, not the header (code-review M115 run 5 — a
+  // fenced pipe line was taken as the header and every real row went unchecked).
+  let inFence = false;
+  for (let i = 0; i < sectionLines.length; i++) {
+    if (isFenceToggle(sectionLines[i])) { inFence = !inFence; continue; }
+    if (inFence) continue;
+    const trimmed = sectionLines[i].trim();
+    if (!trimmed.startsWith("|")) continue;
+    const inner = trimmed.replace(/^\|/, "").replace(/\|$/, "");
+    const cells = inner.split("|").map((c) => c.trim());
+    // The first table-shaped line in the section IS the header row, whatever its
+    // text — "missing" means no table-shaped line at all; a wrong-but-present
+    // header text is a separate violation (wrong-table-header), never conflated.
+    return { cells, line: sectionStartLine + i };
+  }
+  return null;
+}
+
+/** Read the row's column-6 state (contract §2.1) from its Source cell text. */
+function classifyRowState(sourceCell) {
+  // The shared reader's classifier, mapped onto this gate's vocabulary. `malformed`
+  // is a cell that LOOKS like a marker and is not one — `GAPX:` — which the gate
+  // once read as a citation (Red Team M115 run 6, HIGH).
+  const st = rowState(sourceCell);
+  if (st === "gap") return "open";
+  if (st === "decided") return "self-answered";
+  return st; // empty | sourced | malformed
+}
+
+/**
+ * Parse the `## Decided without you` group into its bullet entries.
+ * @returns {Array<{table: string|null, seq: string|null, evidencePresent: boolean, raw: string}>}
+ */
+/** The section's lines with every fenced block removed — a bullet inside a code
+ *  block is rendered as code, invisible as a decision (Red Team M115 run 5, HIGH). */
+function unfencedLines(sectionLines) {
+  const out = [];
+  let inFence = false;
+  for (const line of sectionLines) {
+    if (isFenceToggle(line)) { inFence = !inFence; continue; }
+    if (!inFence) out.push(line);
+  }
+  return out;
+}
+
+function parseDecidedGroup(sectionLines) {
+  const entries = [];
+  for (const line of unfencedLines(sectionLines)) {
+    const t = line.trim();
+    if (t === "---" || !/^-\s+\S/.test(t)) continue;
+    if (t === `> ${NONE_SOURCED_SENTENCE}` || t === NONE_SOURCED_SENTENCE) continue;
+    const m = t.match(/^-\s+`([^`]+)`\s+Seq\s+`([^`]+)`\s+—\s+(.*)$/);
+    if (m) {
+      const [, table, seq, rest] = m;
+      entries.push({ table, seq, evidencePresent: /evidence:\s*\S/.test(rest), raw: t });
+    } else {
+      entries.push({ table: null, seq: null, evidencePresent: false, raw: t });
+    }
+  }
+  return entries;
+}
+
+/** True when the Decided group's only content is the "None" sentence (or is empty of bullets). */
+function decidedGroupIsExplicitlyEmpty(sectionLines) {
+  // Positional: the group's ONLY content line is the "None" sentence (bare or
+  // as a blockquote). A "None" buried among real bullets is not an empty group.
+  const content = unfencedLines(sectionLines).map((l) => l.trim()).filter((l) => l && !l.startsWith("## "));
+  return content.length === 1 && (content[0] === NONE_SOURCED_SENTENCE || content[0] === `> ${NONE_SOURCED_SENTENCE}`);
+}
+
+// ─── the gate ──────────────────────────────────────────────────────────────
+
+/**
+ * Gate one test-plan doc. Pure, structural, never throws — caller wraps in
+ * try/catch for I/O.
+ * @returns {{ok: boolean, exitCode: 0|4, violations: Array<{kind:string, detail:string}>}}
+ */
+function checkDoc(text, docPath) {
+  const violations = [];
+  const v = (kind, detail) => violations.push({ kind, detail, doc: docPath });
+
+  const sections = splitSections(text);
+
+  // ── Required section set, present and in order ──
+  // The required set must appear in RELATIVE order; sections the mold does not
+  // name (e.g. the contract-mandated `## HALT — case-space bound reached`) are
+  // skipped, never counted as a break in the order. The first shipped walker
+  // stalled on the first unknown heading and then reported every later required
+  // section missing — failing the milestone's own correctly-halted cold run
+  // (code-review M115, important).
+  let cursor = 0;
+  const foundByKey = {};
+  for (const req of REQUIRED_SECTIONS_IN_ORDER) {
+    let matchedAtLeastOnce = false;
+    for (let i = cursor; i < sections.length; i++) {
+      if (!req.test(sections[i].heading)) continue;
+      matchedAtLeastOnce = true;
+      foundByKey[req.key] = foundByKey[req.key] || [];
+      foundByKey[req.key].push(sections[i]);
+      cursor = i + 1;
+      if (!req.repeatable) break;
+    }
+    if (!matchedAtLeastOnce) {
+      v("missing-or-out-of-order-section", `required section "${req.key}" is missing, out of order, or empty — the mold's fixed section order is Decided without you, one or more Table sections, Open gaps, Sign-off.`);
+    }
+  }
+
+  // Every Table section, wherever it sits — an ordering violation above must not
+  // hide the row defects the reviewer also needs to fix (review M115 run 7).
+  const tableSections = sections.filter((sec) => !!sharedTableName(sec.heading));
+  const seenIdentities = new Set();
+  const decidedSections = foundByKey["decided-without-you"] || [];
+
+  // ── Every sequence table: exact six-column header, row states, blanks ──
+  const allSelfAnsweredRows = []; // {table, seq}
+  for (const tsec of tableSections) {
+    const tableName = sharedTableName(tsec.heading);
+    const header = findTableHeader(tsec.lines, tsec.startLine);
+    if (!header) {
+      v("missing-table-header", `table "${tableName}" has no \`| Seq | ... |\` header row.`);
+      continue;
+    }
+    const headerOk = header.cells.length === REQUIRED_COLUMNS.length
+      && REQUIRED_COLUMNS.every((c, idx) => header.cells[idx] === c);
+    if (!headerOk) {
+      v("wrong-table-header", `table "${tableName}" header is "${header.cells.join(" | ")}" — must be exactly "${REQUIRED_COLUMNS.join(" | ")}".`);
+      continue; // column positions are meaningless if the header doesn't match
+    }
+
+    const rows = parseTableRows(tsec.lines, tsec.startLine);
+    if (rows.length === 0) {
+      v("empty-table", `table "${tableName}" declares the header but has no data rows.`);
+    }
+    for (const row of rows) {
+      // EXACT width. A row with extra cells used to pass and every consumer then
+      // read the wrong cell as column 6 — the state column (code-review M115 run 4).
+      if (row.cells.length !== REQUIRED_COLUMNS.length) {
+        v("row-column-count-mismatch", `table "${tableName}" row "${row.raw.slice(0, 80)}" has ${row.cells.length} columns, expected ${REQUIRED_COLUMNS.length}.`);
+        continue;
+      }
+      const seq = row.cells[0];
+      const effectOnSavedData = row.cells[4];
+      const source = row.cells[5];
+
+      // A row with no Seq has no identity: nothing can cite it, the halt cannot name
+      // it, and one consumer silently dropped it (Red Team M115 run 6, HIGH).
+      if (seq.trim() === "") {
+        v("blank-seq", `table "${tableName}" has a row with a blank "Seq" — every row needs an identity.`);
+        continue;
+      }
+      const identity = `${tableName}::${seq}`;
+      if (seenIdentities.has(identity)) {
+        v("duplicate-row-identity", `table "${tableName}" Seq "${seq}" appears more than once — two rows with one identity let a later row silently overwrite an earlier one (code-review M115 run 6).`);
+      }
+      seenIdentities.add(identity);
+
+      if (effectOnSavedData.trim() === "") {
+        v("blank-effect-on-saved-data", `table "${tableName}" Seq "${seq}" has a blank "Effect on saved data" — write "none" explicitly.`);
+      }
+
+      const state = classifyRowState(source);
+      if (state === "malformed") {
+        v("unknown-source-marker", `table "${tableName}" Seq "${seq}" has a "Source" that looks like a marker but is not one ("${source.slice(0, 40)}") — the only markers are GAP, GAP:CONTRADICTION and DECIDED-WITHOUT-YOU.`);
+        continue;
+      }
+      if (state === "empty") {
+        v("blank-source-not-a-fourth-state", `table "${tableName}" Seq "${seq}" has a blank "Source" — every row must be sourced, self-answered, or a gap; there is no empty fourth state.`);
+        continue;
+      }
+      if (state === "self-answered") {
+        allSelfAnsweredRows.push({ table: tableName, seq });
+      }
+    }
+  }
+
+  // ── `## Decided without you`: present, before the first table, exact match ──
+  const decidedHeadingCount = sections.filter((sec) => sec.heading === HEADING_DECIDED).length;
+  if (decidedHeadingCount > 1) {
+    v("duplicate-decided-group", `"${HEADING_DECIDED}" appears ${decidedHeadingCount} times — the group is ONE heading whose entries match the self-answered rows exactly; a second heading hides its entries from that rule.`);
+  }
+  if (decidedSections.length > 0) {
+    const decidedSection = decidedSections[0];
+    const firstTableSection = tableSections[0];
+    if (firstTableSection && decidedSection.startLine > firstTableSection.startLine) {
+      v("decided-group-after-first-table", `"${HEADING_DECIDED}" must appear before the first Table section.`);
+    }
+
+    const explicitlyEmpty = decidedGroupIsExplicitlyEmpty(decidedSection.lines);
+    const entries = parseDecidedGroup(decidedSection.lines);
+
+    if (allSelfAnsweredRows.length === 0 && !explicitlyEmpty) {
+      v("decided-group-missing-none-sentence", `no self-answered rows exist, but "${HEADING_DECIDED}" does not carry the required "${NONE_SOURCED_SENTENCE}" line.`);
+    }
+
+    // Every self-answered row must have exactly one matching, evidenced entry.
+    for (const r of allSelfAnsweredRows) {
+      const match = entries.find((e) => e.table === r.table && e.seq === r.seq);
+      if (!match) {
+        v("self-answered-row-not-in-decided-group", `table "${r.table}" Seq "${r.seq}" is self-answered but has no entry under "${HEADING_DECIDED}".`);
+      } else if (!match.evidencePresent) {
+        v("decided-entry-missing-evidence", `table "${r.table}" Seq "${r.seq}" appears under "${HEADING_DECIDED}" but names no evidence.`);
+      }
+    }
+
+    // Every entry under the heading must correspond to a real self-answered row —
+    // the group is EXACTLY the set, no extras.
+    for (const e of entries) {
+      if (e.table === null && e.seq === null) {
+        v("decided-group-has-unparsable-entry", `an entry under "${HEADING_DECIDED}" does not match the required "\`table\` Seq \`n\` — decision — evidence: ..." shape: "${e.raw.slice(0, 100)}"`);
+        continue;
+      }
+      const isReal = allSelfAnsweredRows.some((r) => r.table === e.table && r.seq === e.seq);
+      if (!isReal) {
+        v("decided-group-has-extra-entry", `"${HEADING_DECIDED}" cites table "${e.table}" Seq "${e.seq}", which is not a self-answered row in any table.`);
+      }
+    }
+  }
+  // (If the heading itself is missing, that was already raised as
+  // missing-or-out-of-order-section above — not duplicated here.)
+
+  return {
+    ok: violations.length === 0,
+    exitCode: violations.length === 0 ? 0 : 4,
+    violations,
+  };
+}
+
+/**
+ * Gate one file on disk.
+ *
+ * NOT A FALLBACK: an unreadable doc HALTS at exit 64 (never treated as clean,
+ * never guessed) — the frozen contract §4 shape ("a gate that cannot decide
+ * exits 64 ... never exits 0 by default"), identical to gsd-t-pseudocode-style.cjs.
+ * @returns {{ok:boolean, exitCode:0|4|64, doc:string, violations:Array, reason?:string}}
+ */
+function gateDoc(docPath) {
+  let text;
+  try {
+    text = fs.readFileSync(docPath, "utf8");
+  } catch (e) {
+    return { ok: false, exitCode: 64, doc: docPath, reason: `cannot read doc: ${e && e.message}`, violations: [] };
+  }
+  const result = checkDoc(text, docPath);
+  return { ...result, doc: docPath };
+}
+
+/**
+ * Run the gate over one doc or a whole directory.
+ * @returns {object} envelope. I/O failures HALT at exit 64 (see gateDoc) — never
+ * silently degrade to a clean pass.
+ */
+function run({ doc, dir }) {
+  if (!doc && !dir) {
+    return { ok: false, exitCode: 64, reason: "missing --doc and/or --dir", violations: [] };
+  }
+
+  const docs = [];
+  if (doc) docs.push(doc);
+  if (dir) {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir);
+    } catch (e) {
+      return { ok: false, exitCode: 64, reason: `cannot read dir: ${e && e.message}`, violations: [] };
+    }
+    for (const e of entries) {
+      if (/^TestPlan-.*\.md$/.test(e) && e !== "TestPlan-spec.md") docs.push(path.join(dir, e));
+    }
+    if (docs.length === 0) {
+      return { ok: true, exitCode: 0, docsChecked: 0, skips: [{ reason: "no-testplan-docs" }], violations: [] };
+    }
+  }
+
+  const results = [];
+  const violations = [];
+  let worstExit = 0;
+  for (const d of docs) {
+    const r = gateDoc(d);
+    results.push({ doc: d, ok: r.ok, exitCode: r.exitCode, reason: r.reason });
+    for (const v of r.violations) violations.push(v);
+    if (r.exitCode > worstExit) worstExit = r.exitCode;
+  }
+
+  return {
+    ok: worstExit === 0,
+    exitCode: worstExit,
+    docsChecked: docs.length,
+    results,
+    violations,
+  };
+}
+
+// ─── CLI ────────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const o = { doc: null, dir: null, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "-h" || a === "--help") o.help = true;
+    else if (a === "--doc") o.doc = argv[++i];
+    else if (a === "--dir") o.dir = argv[++i];
+    else if (a === "--json") { /* JSON is the only output */ }
+  }
+  return o;
+}
+
+const HELP = `Usage: gsd-t testplan-lint (--doc <TestPlan-[FeatureArea].md> | --dir <dir>) [--json]
+
+Gates a test plan's structural shape against the frozen contract
+(.gsd-t/contracts/test-plan-first-contract.md §2-4): the required section set
+in order, the exact six-column sequence-table header, every row in exactly
+one of the three row states, "Effect on saved data" and "Source" never
+blank, and the "## Decided without you" group present and exactly matching
+the set of self-answered rows.
+
+  --doc PATH   gate one plan.
+  --dir PATH   gate every TestPlan-*.md in a directory.
+
+Exit: 0 clean · 4 shape violations · 64 bad input.`;
+
+/**
+ * NOT A FALLBACK: this catch is the frozen never-throws HALT wrapper required
+ * by contract §4 ("never throws ... exits 64 and says why") — identical in
+ * shape to bin/gsd-t-pseudocode-style.cjs and bin/gsd-t-traceability-gate.cjs.
+ * It stops and REPORTS an unexpected internal error rather than continuing
+ * past it or masking it as a clean pass.
+ */
+function main() {
+  const o = parseArgs(process.argv.slice(2));
+  if (o.help) { process.stdout.write(HELP + "\n"); process.exit(0); }
+  let res;
+  try {
+    res = run(o);
+  } catch (e) {
+    // A gate that cannot run HALTS with the bad-input envelope — exit 64 is a
+    // failure, never a pass. Written as an explicit halt so the fallback guard
+    // reads it as one (an assignment-then-fall-through looks like a continue).
+    process.stdout.write(JSON.stringify({ ok: false, exitCode: 64, reason: `gate-error: ${e && e.message}`, violations: [] }, null, 2) + "\n");
+    process.exit(64);
+  }
+  process.stdout.write(JSON.stringify(res, null, 2) + "\n");
+  process.exit(res.exitCode);
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  run, gateDoc, checkDoc, splitSections, parseTableRows, findTableHeader,
+  classifyRowState, parseDecidedGroup, REQUIRED_COLUMNS,
+};

package/bin/gsd-t-testplan-rows.cjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * gsd-t-testplan-rows.cjs — the ONE reader of a test-plan document's shape.
+ *
+ * Three consumers read `TestPlan-*.md` (contract test-plan-first-contract.md §2):
+ * the shape lint (bin/gsd-t-testplan-lint.cjs), the convergence halt
+ * (bin/gsd-t-testplan-halt.cjs) and the traceability gate's plan-row binding
+ * (bin/gsd-t-traceability-gate.cjs). M115 verify run 4 found them drifting:
+ * one tracked backtick fences but not tilde fences, one tracked none, and all
+ * three accepted a row with EXTRA cells and then read the wrong cell as column
+ * 6 — the state column the whole contract rests on. A GAP row with one extra
+ * cell passed the lint, cleared an acceptance criterion, and was invisible to
+ * the halt. Same defect, three places. This module is where it is fixed once.
+ *
+ * Rules pinned here:
+ *   - a fenced block opened by ``` or ~~~ (three or more) hides every line
+ *     inside it: a `##` there is text, not a heading; a `|` there is not a row
+ *   - a row has EXACTLY six cells; anything else is `width` !== 6 and the
+ *     consumer decides what a malformed row means for ITS job (the lint: a
+ *     violation; the gate: never clears; the halt: still open)
+ *   - a row's state is read from cell 6 alone: empty | gap | decided | sourced
+ */
+
+const REQUIRED_COLUMN_COUNT = 6;
+const HEADER_CELLS = ["Seq", "Setup / date", "Action", "Expected result", "Effect on saved data", "Source"];
+
+// \x60 is the backtick, kept out of the source text so no scanner mistakes
+// this regex for a template literal (TD-299).
+const FENCE_RE = /^\s*(?:\x60{3,}|~{3,})/;
+
+function isFenceToggle(line) { return FENCE_RE.test(line); }
+
+/**
+ * Split a document into `##` sections, fence-aware for BOTH fence styles.
+ * @returns {Array<{heading: string, lines: string[], startLine: number}>}
+ *   startLine is the 1-based line number of the first line AFTER the heading.
+ */
+function walkSections(text) {
+  const lines = String(text).split(/\r?\n/);
+  const sections = [];
+  let cur = null;
+  let inFence = false;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (isFenceToggle(line)) { inFence = !inFence; if (cur) cur.lines.push(line); continue; }
+    if (!inFence && /^##\s+\S/.test(line)) {
+      if (cur) sections.push(cur);
+      cur = { heading: line.trim(), lines: [], startLine: i + 2 };
+      continue;
+    }
+    if (cur) cur.lines.push(line);
+  }
+  if (cur) sections.push(cur);
+  return sections;
+}
+
+function splitCells(line) {
+  const inner = line.trim().replace(/^\|/, "").replace(/\|$/, "");
+  return inner.split("|").map((c) => c.trim());
+}
+function isHeaderRow(cells) { return cells[0] === "Seq"; }
+function isSeparatorRow(cells) { return cells.length > 0 && cells.every((c) => /^:?-+:?$/.test(c)); }
+
+/**
+ * Data rows of a section, by position, fence-aware. Header and separator rows
+ * are skipped. Every row carries its `width` so a consumer can refuse a
+ * malformed one instead of reading the wrong cell.
+ * @returns {Array<{cells: string[], width: number, line: number, raw: string}>}
+ */
+function parseRows(sectionLines, sectionStartLine) {
+  const rows = [];
+  let inFence = false;
+  for (let i = 0; i < sectionLines.length; i++) {
+    const raw = sectionLines[i];
+    if (isFenceToggle(raw)) { inFence = !inFence; continue; }
+    if (inFence) continue;
+    const trimmed = raw.trim();
+    if (!trimmed.startsWith("|")) continue;
+    const cells = splitCells(trimmed);
+    if (isHeaderRow(cells)) continue;
+    if (isSeparatorRow(cells)) continue;
+    rows.push({ cells, width: cells.length, line: (sectionStartLine || 0) + i, raw: trimmed });
+  }
+  return rows;
+}
+
+/** `## Table: <name>` — the ONE heading pattern every consumer uses (the lint once
+ *  required exactly one space while the others accepted any whitespace). */
+const TABLE_HEADING_RE = /^##\s+Table:\s*(.+?)\s*$/;
+function tableName(heading) { const m = String(heading || "").match(TABLE_HEADING_RE); return m ? m[1].trim() : null; }
+
+/**
+ * The row state, read from cell 6 ALONE — the ONE classifier (Red Team M115 run 6:
+ * the gate matched `GAP\b`, the lint and halt matched `startsWith("GAP")`, and a
+ * `GAPX:` cell was a gap to two tools and a sourced answer to the third, which
+ * cleared an acceptance criterion). Markers are exact tokens, case-insensitive
+ * (project rule: domain values compare case-insensitively):
+ *   empty     — nothing written
+ *   gap       — `GAP` / `GAP: …` / `GAP:CONTRADICTION …`
+ *   decided   — `DECIDED-WITHOUT-YOU …`
+ *   malformed — looks like a marker but is not one (`GAPX`, `GAP-ish`, `DECIDED …`)
+ *   sourced   — anything else: a citation
+ */
+function rowState(sourceCell) {
+  const s = String(sourceCell == null ? "" : sourceCell).trim();
+  if (s === "") return "empty";
+  if (/^gap(?::|\s|$)/i.test(s)) return "gap";
+  if (/^decided-without-you(?::|\s|$)/i.test(s)) return "decided";
+  if (/^(?:gap|decided)/i.test(s)) return "malformed";
+  return "sourced";
+}
+
+module.exports = { REQUIRED_COLUMN_COUNT, HEADER_CELLS, TABLE_HEADING_RE, tableName, isFenceToggle, walkSections, splitCells, isHeaderRow, isSeparatorRow, parseRows, rowState };