@opengsd/gsd-core 1.7.0-rc.6 → 1.8.0

package/gsd-core/bin/lib/markdown-table.cjs

@@ -0,0 +1,698 @@
+"use strict";
+/**
+ * Markdown Table Model — canonical GFM table parsing + schema registry seam
+ * (ADR-2143, epic #2143). Pure functions, Node built-ins only, string-in/value-out,
+ * no I/O. Compiled by tsc to gsd-core/bin/lib/markdown-table.cjs.
+ *
+ * NOTE: the `Result<T>` here is the ADR-2143 §5 parse-result shape {ok,value|reason},
+ * now defined once in `./write-set.cjs` (the shared fail-loud + write-set seam) and
+ * re-exported here so existing importers of `Result` from this module keep working
+ * unchanged — deliberately distinct from command-routing-hub's dispatch `Result`
+ * {ok,data|kind}; the two never mix (different modules).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TABLE_SCHEMAS = void 0;
+exports.matchTableSchema = matchTableSchema;
+exports.splitTableRow = splitTableRow;
+exports.isDelimiterRow = isDelimiterRow;
+exports.parseMarkdownTable = parseMarkdownTable;
+exports.updateTableCell = updateTableCell;
+exports.deleteTableRow = deleteTableRow;
+exports.insertTableRow = insertTableRow;
+exports.findTableBySchema = findTableBySchema;
+exports.findTableWithColumns = findTableWithColumns;
+exports.escapeCell = escapeCell;
+exports.appendQuickTaskRow = appendQuickTaskRow;
+const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
+// ─── Schema registry ──────────────────────────────────────────────────────────
+/**
+ * Canonical column-header shapes for every GFM table GSD parses or generates.
+ * Each entry in `TABLE_SCHEMAS[id]` is one accepted variant (exact column names,
+ * in order); `matchTableSchema` resolves a parsed header back to `{id, label}`.
+ *
+ * This registry is the single source of truth — a parity test
+ * (tests/markdown-table.test.cjs) asserts every variant's header appears
+ * verbatim in the template/workflow file that generates it, so the registry
+ * and the templates can never silently drift (ADR-2143 §3 Generative-Fix-
+ * Divergence guard).
+ */
+exports.TABLE_SCHEMAS = {
+    RoadmapProgress: [
+        { label: 'flat', columns: ['Phase', 'Plans Complete', 'Status', 'Completed'] },
+        {
+            label: 'milestone-grouped',
+            columns: ['Phase', 'Milestone', 'Plans Complete', 'Status', 'Completed'],
+        },
+    ],
+    RequirementsTraceability: [
+        { label: 'default', columns: ['Requirement', 'Phase', 'Status'] },
+    ],
+    QuickTasks: [
+        { label: 'no-status', columns: ['#', 'Description', 'Date', 'Commit', 'Directory'] },
+        {
+            label: 'with-status',
+            columns: ['#', 'Description', 'Date', 'Commit', 'Status', 'Directory'],
+        },
+    ],
+    Security: [
+        { label: 'trust-boundaries', columns: ['Boundary', 'Description', 'Data Crossing'] },
+        {
+            label: 'threat-register',
+            columns: [
+                'Threat ID',
+                'Category',
+                'Component',
+                'Severity',
+                'Disposition',
+                'Mitigation',
+                'Status',
+            ],
+        },
+        {
+            label: 'accepted-risks',
+            columns: ['Risk ID', 'Threat Ref', 'Rationale', 'Accepted By', 'Date'],
+        },
+        {
+            label: 'audit-trail',
+            columns: ['Audit Date', 'Threats Total', 'Closed', 'Open', 'Run By'],
+        },
+    ],
+};
+/**
+ * Resolve a parsed table's header columns to the canonical schema it matches
+ * (exact column names, same length, same order), else `null`.
+ */
+function matchTableSchema(columns) {
+    for (const [id, variants] of Object.entries(exports.TABLE_SCHEMAS)) {
+        for (const variant of variants) {
+            if (variant.columns.length === columns.length
+                && variant.columns.every((col, idx) => col === columns[idx])) {
+                return { id, label: variant.label };
+            }
+        }
+    }
+    return null;
+}
+// ─── Parsing ──────────────────────────────────────────────────────────────────
+/**
+ * Split one GFM table row line into trimmed cell strings.
+ * Strips one leading and one trailing `|`, splits on unescaped `|`, trims
+ * each cell, and unescapes `\\` back to `\` and `\|` back to `|` (the exact
+ * reverse of `escapeCell`'s `\`->`\\` then `|`->`\|` order below), so cell
+ * values round-trip exactly — including literal backslashes.
+ */
+function splitTableRow(line) {
+    let stripped = line.trim();
+    if (stripped.startsWith('|'))
+        stripped = stripped.slice(1);
+    if (stripped.endsWith('|'))
+        stripped = stripped.slice(0, -1);
+    return stripped.split(/(?<!\\)\|/).map((cell) => cell.trim().replace(/\\([\\|])/g, '$1'));
+}
+/**
+ * True when every delimiter cell matches GFM's `:?-{1,}:?` shape (spaces
+ * removed). Exported (alongside `splitTableRow`) so callers that need their
+ * own ragged-tolerant header/delimiter detection — e.g. state.cts's
+ * `cmdStateRecordMetric` row-append, which must recognize an existing table
+ * without requiring every DATA row to also parse cleanly (#2245 Blocker 2) —
+ * reuse the exact same header/delimiter-shape check `parseMarkdownTable` uses,
+ * instead of re-deriving it and risking divergence.
+ */
+function isDelimiterRow(cells) {
+    return cells.every((cell) => /^:?-{1,}:?$/.test(cell.replace(/\s+/g, '')));
+}
+/**
+ * Parse the FIRST GFM pipe table found in `sectionText`.
+ *
+ * Defensive by design: never throws — every malformed shape (no table,
+ * missing/misaligned delimiter row, ragged data row) returns a typed
+ * `{ok:false, reason}` instead of silently coercing or dropping data
+ * (ADR-2143 §3 — ragged rows are errors, not silent).
+ *
+ * Scope note: GSD planning tables (STATE.md/ROADMAP.md/requirements.md/
+ * SECURITY.md) are always fully-piped (leading + trailing `|` on every row)
+ * and non-indented — this parser targets THAT shape, not arbitrary
+ * CommonMark (which also allows non-piped rows and up to 3 leading spaces).
+ */
+function parseMarkdownTable(sectionText) {
+    if (typeof sectionText !== 'string' || sectionText.trim() === '') {
+        return { ok: false, reason: 'empty or non-string input' };
+    }
+    const lines = sectionText.split(/\r?\n/);
+    let headerIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const trimmed = lines[i].trim();
+        if (trimmed.startsWith('|') && trimmed.indexOf('|', 1) !== -1) {
+            headerIdx = i;
+            break;
+        }
+    }
+    if (headerIdx === -1) {
+        return { ok: false, reason: 'no table found' };
+    }
+    const columns = splitTableRow(lines[headerIdx]);
+    const delimiterLine = lines[headerIdx + 1];
+    if (delimiterLine === undefined || !delimiterLine.trim().startsWith('|')) {
+        return { ok: false, reason: 'missing delimiter row' };
+    }
+    const delimiterCells = splitTableRow(delimiterLine);
+    if (!isDelimiterRow(delimiterCells)) {
+        return { ok: false, reason: 'missing delimiter row' };
+    }
+    if (delimiterCells.length !== columns.length) {
+        return { ok: false, reason: 'delimiter/header column count mismatch' };
+    }
+    const rows = [];
+    let rowNum = 0;
+    for (let i = headerIdx + 2; i < lines.length; i++) {
+        const trimmed = lines[i].trim();
+        if (!trimmed.startsWith('|'))
+            break;
+        rowNum += 1;
+        const cells = splitTableRow(lines[i]);
+        if (cells.length !== columns.length) {
+            return {
+                ok: false,
+                reason: `row ${rowNum} has ${cells.length} cells, expected ${columns.length}`,
+            };
+        }
+        const row = {};
+        columns.forEach((col, idx) => {
+            row[col] = cells[idx];
+        });
+        rows.push(row);
+    }
+    return { ok: true, value: { columns, rows } };
+}
+/**
+ * Split `text` into lines exactly like `.split(/\r?\n/)` (bare `\r` is NOT a
+ * line break, matching `parseMarkdownTable`), tracking each line's absolute
+ * start offset in `text` so cell ranges can be computed relative to the
+ * ORIGINAL string, not the trimmed/relative line.
+ */
+function splitLinesWithOffsets(text) {
+    const result = [];
+    let start = 0;
+    const re = /\r\n|\n/g;
+    let m;
+    while ((m = re.exec(text)) !== null) {
+        result.push({ line: text.slice(start, m.index), start });
+        start = m.index + m[0].length;
+    }
+    result.push({ line: text.slice(start), start });
+    return result;
+}
+/**
+ * Split one GFM table row LINE into raw cell ranges, absolute to the original
+ * `text` the line was sliced from (`lineStart` = that line's start offset).
+ * Mirrors `splitTableRow`'s trim + strip-leading/trailing-pipe + unescaped-pipe
+ * split EXACTLY, but returns character ranges instead of trimmed values, so a
+ * caller can splice a replacement into the original string byte-for-byte.
+ */
+function splitTableRowRanges(line, lineStart) {
+    const leftTrim = /^\s*/.exec(line)[0].length;
+    const rightTrim = /\s*$/.exec(line)[0].length;
+    let stripped = line.slice(leftTrim, line.length - rightTrim);
+    let strippedStart = lineStart + leftTrim;
+    if (stripped.startsWith('|')) {
+        stripped = stripped.slice(1);
+        strippedStart += 1;
+    }
+    if (stripped.endsWith('|')) {
+        stripped = stripped.slice(0, -1);
+    }
+    const cells = [];
+    const re = /(?<!\\)\|/g;
+    let cellStartRel = 0;
+    let m;
+    while ((m = re.exec(stripped)) !== null) {
+        cells.push({ start: strippedStart + cellStartRel, end: strippedStart + m.index });
+        cellStartRel = m.index + 1;
+    }
+    cells.push({ start: strippedStart + cellStartRel, end: strippedStart + stripped.length });
+    return cells;
+}
+/** Unescape one raw (still-`\`-escaped) cell/column-name span exactly like
+ * `splitTableRow`: trim, then reverse `\\` -> `\` and `\|` -> `|`. */
+function unescapeCellText(raw) {
+    return raw.trim().replace(/\\([\\|])/g, '$1');
+}
+/**
+ * Surgically edit ONE table cell while preserving the table's exact byte
+ * formatting (ADR-2143 §7). Locates the first GFM table's header + delimiter
+ * row in `tableText` (own header/delimiter detection — deliberately does NOT
+ * gate on `parseMarkdownTable(tableText).ok`), finds the first DATA row where
+ * `match(row, index)` is true, and replaces ONLY that row's `column` cell's
+ * raw inner text (the span between its two delimiting `|` characters) — every
+ * other byte of `tableText` (other cells, padding, alignment, EOL style) is
+ * left BYTE-IDENTICAL. This is deliberately NOT a parse-then-render: a
+ * render pass would reformat padding/alignment/dates that mutation sites
+ * (e.g. `status.padEnd(11)`) depend on staying pinned.
+ *
+ * Ragged-tolerant by design (#2245 review Fix 2): each data row's
+ * `{colName:cellText}` record is built ONLY from the columns physically
+ * present in THAT row — a short row simply omits its trailing column names;
+ * an over-long row's extra trailing cells are ignored — so `match` is called
+ * with whatever partial record a ragged row yields. A single sibling row
+ * whose cell count doesn't match the header must never silently no-op the
+ * whole write (the prior `parseMarkdownTable(tableText).ok` gate failed the
+ * ENTIRE table — including an otherwise-well-formed target row — the moment
+ * ANY other row in the same table was ragged). A row that matches on content
+ * but is too short to physically contain `column` has no cell to splice
+ * into, so it cannot be selected; the scan continues past it.
+ *
+ * `newValue` is spliced in VERBATIM as the new raw cell span — it is the
+ * caller's responsibility to supply the fully-formatted text (including any
+ * leading/trailing padding needed to reproduce the table's existing column
+ * alignment, and to escape a literal `|` or `\` the value might contain via
+ * the same convention `splitTableRow`/`escapeCell` use elsewhere in this
+ * module). When `newValue` is a function, it receives the CURRENT (trimmed,
+ * unescaped) cell value — the same value that appears in `match`'s `row`
+ * argument — and must return the full literal replacement text. Returning
+ * the current value unchanged is a supported no-op-probe pattern for callers
+ * that need to know whether (and to what current value) a row matched
+ * without necessarily writing a new value.
+ *
+ * Returns `{ok:false, reason}` only for a genuinely absent/malformed table
+ * (no header line, or no valid delimiter row immediately below it), an
+ * unknown `column`, or zero rows satisfying `match` while physically
+ * containing `column` — never for a ragged sibling row.
+ */
+function updateTableCell(tableText, match, column, newValue) {
+    const lines = splitLinesWithOffsets(tableText);
+    let headerIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const trimmed = lines[i].line.trim();
+        if (trimmed.startsWith('|') && trimmed.indexOf('|', 1) !== -1) {
+            headerIdx = i;
+            break;
+        }
+    }
+    if (headerIdx === -1) {
+        return { ok: false, reason: 'no table found' };
+    }
+    const delimiterLine = lines[headerIdx + 1]?.line;
+    if (delimiterLine === undefined || !delimiterLine.trim().startsWith('|')) {
+        return { ok: false, reason: 'missing delimiter row' };
+    }
+    const headerRanges = splitTableRowRanges(lines[headerIdx].line, lines[headerIdx].start);
+    const columns = headerRanges.map((r) => unescapeCellText(tableText.slice(r.start, r.end)));
+    const delimiterCells = splitTableRow(delimiterLine);
+    if (!isDelimiterRow(delimiterCells)) {
+        return { ok: false, reason: 'missing delimiter row' };
+    }
+    if (delimiterCells.length !== columns.length) {
+        return { ok: false, reason: 'delimiter/header column count mismatch' };
+    }
+    if (!columns.includes(column)) {
+        return { ok: false, reason: `unknown column: ${column}` };
+    }
+    const targetColIdx = columns.indexOf(column);
+    let selectedRange;
+    let dataRowIndex = 0;
+    for (let i = headerIdx + 2; i < lines.length; i++) {
+        const trimmed = lines[i].line.trim();
+        if (!trimmed.startsWith('|'))
+            break;
+        const cellRanges = splitTableRowRanges(lines[i].line, lines[i].start);
+        const record = {};
+        const presentCount = Math.min(cellRanges.length, columns.length);
+        for (let c = 0; c < presentCount; c++) {
+            record[columns[c]] = unescapeCellText(tableText.slice(cellRanges[c].start, cellRanges[c].end));
+        }
+        if (targetColIdx < cellRanges.length && match(record, dataRowIndex)) {
+            selectedRange = cellRanges[targetColIdx];
+            break;
+        }
+        dataRowIndex += 1;
+    }
+    if (!selectedRange) {
+        return { ok: false, reason: 'no matching row' };
+    }
+    const currentValue = unescapeCellText(tableText.slice(selectedRange.start, selectedRange.end));
+    const replacement = typeof newValue === 'function' ? newValue(currentValue) : newValue;
+    // True no-op guard: a function `newValue` that returns `current` UNCHANGED
+    // (the documented no-op-probe pattern) must leave `tableText` genuinely
+    // byte-identical, padding included. `current` is already trimmed/unescaped,
+    // so naively splicing it back in would strip the raw cell's original
+    // leading/trailing padding — this returns the ORIGINAL text untouched
+    // instead whenever the callback's answer is "no change".
+    if (typeof newValue === 'function' && replacement === currentValue) {
+        return { ok: true, value: tableText };
+    }
+    return {
+        ok: true,
+        value: tableText.slice(0, selectedRange.start) + replacement + tableText.slice(selectedRange.end),
+    };
+}
+// ─── deleteTableRow (ADR-2143 §7 row-removal sibling of updateTableCell) ─────
+/**
+ * Surgically delete ONE whole table row while preserving every other byte of
+ * `tableText` (ADR-2143 §7, row-removal sibling of `updateTableCell`). Locates
+ * the first GFM table's header + delimiter row in `tableText` using the exact
+ * same self-contained, ragged-tolerant scan `updateTableCell` uses (own
+ * header/delimiter detection — does NOT gate on `parseMarkdownTable(tableText).ok`),
+ * finds the FIRST data row where `match(row, index)` is true, and splices out
+ * that row's entire LINE — including its trailing newline (`\r\n` or `\n`,
+ * whichever terminates it) — from `tableText`. Every other byte (header,
+ * delimiter, other rows, surrounding prose before/after the table, EOL style)
+ * is left BYTE-IDENTICAL.
+ *
+ * Ragged-tolerant by design, mirroring `updateTableCell` (#2245 review Fix 2):
+ * each data row's `{colName:cellText}` record is built ONLY from the columns
+ * physically present in THAT row — a sibling row whose cell count doesn't
+ * match the header must never abort the whole scan; `match` is simply called
+ * with whatever partial record a ragged row yields.
+ *
+ * Returns `{ok:false, reason}` for a genuinely absent/malformed table (no
+ * header line, or no valid delimiter row immediately below it) or zero rows
+ * satisfying `match` — never for a ragged sibling row.
+ */
+function deleteTableRow(tableText, match) {
+    const lines = splitLinesWithOffsets(tableText);
+    let headerIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const trimmed = lines[i].line.trim();
+        if (trimmed.startsWith('|') && trimmed.indexOf('|', 1) !== -1) {
+            headerIdx = i;
+            break;
+        }
+    }
+    if (headerIdx === -1) {
+        return { ok: false, reason: 'no table found' };
+    }
+    const delimiterLine = lines[headerIdx + 1]?.line;
+    if (delimiterLine === undefined || !delimiterLine.trim().startsWith('|')) {
+        return { ok: false, reason: 'missing delimiter row' };
+    }
+    const headerRanges = splitTableRowRanges(lines[headerIdx].line, lines[headerIdx].start);
+    const columns = headerRanges.map((r) => unescapeCellText(tableText.slice(r.start, r.end)));
+    const delimiterCells = splitTableRow(delimiterLine);
+    if (!isDelimiterRow(delimiterCells)) {
+        return { ok: false, reason: 'missing delimiter row' };
+    }
+    if (delimiterCells.length !== columns.length) {
+        return { ok: false, reason: 'delimiter/header column count mismatch' };
+    }
+    let selectedLineIdx = -1;
+    let dataRowIndex = 0;
+    for (let i = headerIdx + 2; i < lines.length; i++) {
+        const trimmed = lines[i].line.trim();
+        if (!trimmed.startsWith('|'))
+            break;
+        const cellRanges = splitTableRowRanges(lines[i].line, lines[i].start);
+        const record = {};
+        const presentCount = Math.min(cellRanges.length, columns.length);
+        for (let c = 0; c < presentCount; c++) {
+            record[columns[c]] = unescapeCellText(tableText.slice(cellRanges[c].start, cellRanges[c].end));
+        }
+        if (match(record, dataRowIndex)) {
+            selectedLineIdx = i;
+            break;
+        }
+        dataRowIndex += 1;
+    }
+    if (selectedLineIdx === -1) {
+        return { ok: false, reason: 'no matching row' };
+    }
+    // Splice out the whole LINE including its trailing EOL: the next line's
+    // recorded `start` offset is already positioned right after whatever EOL
+    // (`\r\n` or `\n`) terminated the selected line (see `splitLinesWithOffsets`
+    // above) — when the selected row is the LAST line in `tableText` (no
+    // trailing EOL to preserve), fall back to the end of the string.
+    let rowStart = lines[selectedLineIdx].start;
+    let rowEnd;
+    if (selectedLineIdx + 1 < lines.length) {
+        rowEnd = lines[selectedLineIdx + 1].start;
+    }
+    else {
+        // The selected row is the LAST line and has no trailing EOL: deleting from
+        // its `start` to end-of-string would strand the EOL that terminated the
+        // PREVIOUS line as a dangling newline. Back `rowStart` up over that
+        // preceding `\n` (and its `\r`, if any) so the table ends cleanly after the
+        // new last row.
+        rowEnd = tableText.length;
+        if (rowStart > 0 && tableText[rowStart - 1] === '\n') {
+            rowStart -= 1;
+            if (rowStart > 0 && tableText[rowStart - 1] === '\r')
+                rowStart -= 1;
+        }
+    }
+    return {
+        ok: true,
+        value: tableText.slice(0, rowStart) + tableText.slice(rowEnd),
+    };
+}
+// ─── insertTableRow (ADR-2143 §7 row-insertion sibling of updateTableCell) ───
+/**
+ * Insert ONE new row into a GFM table while preserving every other byte of
+ * `tableText` (ADR-2143 §7, row-insertion sibling of `updateTableCell` /
+ * `deleteTableRow`). Locates the first table's header + delimiter row using
+ * the exact same self-contained, ragged-tolerant scan the other two use (own
+ * header/delimiter detection — does NOT gate on `parseMarkdownTable(tableText).ok`),
+ * builds the new row's cells in the table's ACTUAL header order — each column
+ * name is passed through `valueFor(column)`; a column for which `valueFor`
+ * returns `undefined` gets `fallback` (default `'-'`) — and splices it in
+ * immediately after the table's LAST existing data row (or immediately after
+ * the delimiter row when the table has zero data rows).
+ *
+ * Name-addressed and header-order-agnostic by construction: unlike a
+ * hardcoded positional literal (`| ${a} | ${b} | - | - |`), this never
+ * silently no-ops or mis-maps a value onto the wrong column when the header
+ * is reordered or a superset of the columns `valueFor` knows about (#2245
+ * audit sibling finding — the bug this helper replaces).
+ *
+ * EOL-preserving: the new row reuses whatever exact EOL bytes (`\r\n` or
+ * `\n`) already terminate the line it's inserted after, so a CRLF document
+ * stays CRLF and an LF document stays LF — never guessed or hardcoded. When
+ * the insertion point is at the very end of `tableText` with no following
+ * line (the table's last row has no trailing EOL of its own), the existing
+ * last row is terminated with the header/delimiter boundary's own EOL (so it
+ * gains a terminator, since it is no longer the last line) and the new row
+ * becomes the new EOL-less tail — mirroring `tableText`'s own convention of
+ * not forcing a trailing newline that wasn't already there.
+ *
+ * Escaping (F4 #2245 review): unlike `updateTableCell`, whose `newValue` is
+ * spliced in VERBATIM (caller-must-escape — see its doc comment above), every
+ * value returned by `valueFor` (and `fallback`) IS escaped internally here via
+ * `escapeCell` before being joined into the new row, exactly like
+ * `appendQuickTaskRow` below — a caller-supplied name containing a literal
+ * `|` or `\` cannot silently split the new row into extra columns. Callers do
+ * NOT need to pre-escape their values.
+ *
+ * Returns `{ok:false, reason}` only for a genuinely absent/malformed table
+ * (no header line, or no valid delimiter row immediately below it) — never
+ * for a ragged data row (mirrors `updateTableCell`/`deleteTableRow`).
+ */
+function insertTableRow(tableText, valueFor, fallback = '-') {
+    const lines = splitLinesWithOffsets(tableText);
+    let headerIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const trimmed = lines[i].line.trim();
+        if (trimmed.startsWith('|') && trimmed.indexOf('|', 1) !== -1) {
+            headerIdx = i;
+            break;
+        }
+    }
+    if (headerIdx === -1) {
+        return { ok: false, reason: 'no table found' };
+    }
+    const delimiterLine = lines[headerIdx + 1]?.line;
+    if (delimiterLine === undefined || !delimiterLine.trim().startsWith('|')) {
+        return { ok: false, reason: 'missing delimiter row' };
+    }
+    const delimiterCells = splitTableRow(delimiterLine);
+    if (!isDelimiterRow(delimiterCells)) {
+        return { ok: false, reason: 'missing delimiter row' };
+    }
+    const headerRanges = splitTableRowRanges(lines[headerIdx].line, lines[headerIdx].start);
+    const columns = headerRanges.map((r) => unescapeCellText(tableText.slice(r.start, r.end)));
+    // Header -> delimiter EOL, reused as the fallback terminator for the "insert
+    // point is at the absolute end of tableText" edge case below.
+    const headerToDelimiterEol = tableText.slice(lines[headerIdx].start + lines[headerIdx].line.length, lines[headerIdx + 1].start) || '\n';
+    let lastLineIdx = headerIdx + 1; // delimiter row, when the table has zero data rows
+    for (let i = headerIdx + 2; i < lines.length; i++) {
+        if (!lines[i].line.trim().startsWith('|'))
+            break;
+        lastLineIdx = i;
+    }
+    const newRow = `| ${columns.map((col) => escapeCell(valueFor(col) ?? fallback)).join(' | ')} |`;
+    if (lastLineIdx + 1 < lines.length) {
+        // A following line exists — insert the new row, reusing the EXACT EOL
+        // that already terminates the current last table line, so every other
+        // byte (including everything after the table) stays untouched.
+        const insertAt = lines[lastLineIdx + 1].start;
+        const eol = tableText.slice(lines[lastLineIdx].start + lines[lastLineIdx].line.length, insertAt);
+        return { ok: true, value: tableText.slice(0, insertAt) + newRow + eol + tableText.slice(insertAt) };
+    }
+    // The table's last row is also the last line of `tableText` (no trailing
+    // EOL). Terminate it now — it needs one, since it is no longer last — and
+    // append the new row as the new EOL-less tail.
+    return { ok: true, value: tableText + headerToDelimiterEol + newRow };
+}
+/**
+ * Find the first table in `text` whose header matches `TABLE_SCHEMAS[schemaId]`,
+ * scanning the WHOLE document (not just a named section). Returns `null` when
+ * no table with that schema is found.
+ *
+ * Fixes the regression where callers first located a named heading (e.g.
+ * `## Progress`) via `collectSection` and only then parsed a table inside it —
+ * a schema-matching table that lives under a differently-named heading (or no
+ * heading at all), or that isn't the first table in the document, was
+ * invisible to that approach. Scanning the whole document by schema restores
+ * the old "find the progress table anywhere" behaviour while staying
+ * seam-based (ADR-2143).
+ */
+function findTableBySchema(text, schemaId) {
+    if (typeof text !== 'string')
+        return null;
+    const lines = text.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const t = lines[i].trim();
+        if (!t.startsWith('|') || t.indexOf('|', 1) === -1)
+            continue;
+        const cols = splitTableRow(lines[i]);
+        const m = matchTableSchema(cols);
+        if (m && m.id === schemaId) {
+            const parsed = parseMarkdownTable(lines.slice(i).join('\n'));
+            if (parsed.ok)
+                return parsed.value;
+        }
+    }
+    return null;
+}
+/**
+ * Find the first GFM table in `text` whose header contains ALL of `required`
+ * column names (order-independent; extra/injected columns allowed). Returns
+ * the parsed `MarkdownTable`, or `null` when no table's header is a superset
+ * of `required`.
+ *
+ * Column-NAME/order/count-invariant counterpart to `findTableBySchema` (ADR-2143
+ * §3 "addressed by NAME, never ordinal"): where `findTableBySchema` requires an
+ * EXACT canonical column set+order registered in `TABLE_SCHEMAS`, this scans
+ * for any header that names the required columns, in any order, tolerating
+ * extra/unrelated injected columns. Cells remain addressable by column NAME
+ * via the returned `MarkdownTable`.
+ */
+function findTableWithColumns(text, required) {
+    if (typeof text !== 'string')
+        return null;
+    const lines = text.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const t = lines[i].trim();
+        if (!t.startsWith('|') || t.indexOf('|', 1) === -1)
+            continue;
+        const cols = splitTableRow(lines[i]);
+        if (required.every((rq) => cols.includes(rq))) {
+            const parsed = parseMarkdownTable(lines.slice(i).join('\n'));
+            if (parsed.ok)
+                return parsed.value;
+        }
+    }
+    return null;
+}
+// ─── Quick Tasks row append (#2133) ────────────────────────────────────────────
+/**
+ * Escape one dynamic cell value for insertion into a GFM pipe-table row.
+ *
+ * Escapes `\` -> `\\` FIRST, then `|` -> `\|` (in that order, so a literal
+ * backslash already in the value is never mistaken for part of an escape
+ * sequence introduced by this function — CodeQL js/incomplete-sanitization).
+ * `splitTableRow` reverses both in the opposite order (`\\` -> `\` then
+ * `\|` -> `|`, see line ~114 above), so escaping/unescaping round-trips
+ * exactly, including literal backslashes. Newlines are collapsed to a
+ * single space — a raw `|` or embedded newline in a cell value (e.g. a task
+ * `description`) would otherwise corrupt the table (extra column / a fake
+ * extra row) and get rejected by the now-fail-loud `parseMarkdownTable` as a
+ * ragged row.
+ *
+ * Exported (F3/#2245 review) so callers of `updateTableCell` that build a
+ * replacement value by transforming the CURRENT (already-unescaped) cell
+ * text — e.g. phase.cts's Progress-ordinal renumber, which decrements the
+ * leading digit of a `Phase` cell like `3. Parser | Lexer` and splices the
+ * rest of the cell text back verbatim — can re-escape that value before
+ * returning it from the `newValue` callback, honoring `updateTableCell`'s
+ * caller-must-re-escape contract (see its doc comment above) instead of
+ * spliceing a raw, unescaped `|` back into the table and silently splitting
+ * the cell.
+ */
+function escapeCell(value) {
+    return String(value)
+        .replace(/\r?\n+/g, ' ')
+        .replace(/\\/g, '\\\\') // escape the escape char FIRST (CodeQL js/incomplete-sanitization)
+        .replace(/\|/g, '\\|')
+        .trim();
+}
+/**
+ * Append one row to STATE.md's "Quick Tasks Completed" table.
+ *
+ * Pure, schema-driven replacement for fast.md's inline `awk NF-2` column-count
+ * guess (#2133, ADR-2143 §3 schema registry / §7 fail-loud unrecognized-schema
+ * guard). Never touches disk, git, or the clock — callers (the `gsd-tools
+ * quick-tasks-append` subcommand) compute `date`/`commit` and pass them in.
+ *
+ * Fails loud (`{ok:false, reason}`, never a silent skip) when:
+ *   - no "Quick Tasks Completed" heading exists in `stateContent`
+ *   - the section's body doesn't parse as a GFM table (parseMarkdownTable failure)
+ *   - the table's header doesn't match a known `TABLE_SCHEMAS.QuickTasks` variant
+ *     (the old awk arithmetic silently skipped here instead — that silent-skip
+ *     branch is the bug this replaces).
+ *
+ * The new row is inserted immediately after the LAST existing table row line
+ * (or immediately after the header/delimiter when the table has zero data
+ * rows), preserving any surrounding blank lines/trailing content in the section.
+ */
+function appendQuickTaskRow(stateContent, fields) {
+    const section = (0, markdown_sectionizer_cjs_1.collectSection)(stateContent, (h) => /^quick tasks completed$/i.test(h.text.trim()));
+    if (!section) {
+        return { ok: false, reason: 'no Quick Tasks Completed section' };
+    }
+    const parsed = parseMarkdownTable(section.body);
+    if (!parsed.ok) {
+        return { ok: false, reason: `quick-tasks table: ${parsed.reason}` };
+    }
+    const match = matchTableSchema(parsed.value.columns);
+    if (!match || match.id !== 'QuickTasks') {
+        return {
+            ok: false,
+            reason: `unrecognized Quick Tasks schema (columns: ${parsed.value.columns.join(' | ')})`,
+        };
+    }
+    const variant = exports.TABLE_SCHEMAS.QuickTasks.find((v) => v.label === match.label);
+    const columns = variant ? variant.columns : parsed.value.columns;
+    const rowNumber = parsed.value.rows.length + 1;
+    const cellFor = (col) => {
+        switch (col) {
+            case '#': return escapeCell(String(rowNumber));
+            case 'Description': return escapeCell(fields.description);
+            case 'Date': return escapeCell(fields.date);
+            case 'Commit': return escapeCell(fields.commit);
+            case 'Status': return escapeCell(fields.status ?? '—');
+            case 'Directory': return escapeCell(fields.directory ?? '—');
+            default: return '—';
+        }
+    };
+    const row = `| ${columns.map(cellFor).join(' | ')} |`;
+    // Detect the section's EOL BEFORE splitting on /\r?\n/ (which discards it) so
+    // the rejoin below preserves CRLF instead of downgrading a CRLF section to
+    // mixed EOL (the inserted `row` itself never contains a newline).
+    const eol = /\r\n/.test(section.body) ? '\r\n' : '\n';
+    const lines = section.body.split(/\r?\n/);
+    let lastTableLineIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].trim().startsWith('|'))
+            lastTableLineIdx = i;
+    }
+    // lastTableLineIdx is always >= 0 here — parseMarkdownTable already
+    // confirmed a header + delimiter row exist in this same `section.body`.
+    const newLines = [
+        ...lines.slice(0, lastTableLineIdx + 1),
+        row,
+        ...lines.slice(lastTableLineIdx + 1),
+    ];
+    const newBody = newLines.join(eol);
+    const content = (0, markdown_sectionizer_cjs_1.replaceSection)(stateContent, section, newBody);
+    return { ok: true, value: { content, row, variant: match.label } };
+}
+// Consumers: require('../gsd-core/bin/lib/markdown-table.cjs')
+// Named CJS exports are the canonical surface (ADR-457 .cts → .cjs build-at-publish).