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

package/gsd-core/bin/lib/uat.cjs

@@ -21,6 +21,9 @@ const { output, error } = io;
 const markdownSectionizer = require("./markdown-sectionizer.cjs");
 const { collectSection, tokenizeHeadings } = markdownSectionizer;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
+const markdownTable = require("./markdown-table.cjs");
+const { splitTableRow } = markdownTable;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
 const roadmapParser = require("./roadmap-parser.cjs");
 const { getMilestonePhaseFilter } = roadmapParser;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -36,6 +39,9 @@ const { extractFrontmatter } = frontmatter;
 const phaseIdMod = require("./phase-id.cjs");
 const { PHASE_NUMBER_TOKEN_SOURCE } = phaseIdMod;
 const security_cjs_1 = require("./security.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- config-loader.cjs is an export= CommonJS module
+const configLoader = require("./config-loader.cjs");
+const { loadConfig } = configLoader;
 // ─── cmdAuditUat ─────────────────────────────────────────────────────────────
 function cmdAuditUat(cwd, raw) {
     const phasesDir = node_path_1.default.join(planningDir(cwd), 'phases');
@@ -90,6 +96,29 @@ function cmdAuditUat(cwd, raw) {
                 }
             }
         }
+        // Process deferred-items.md (#2287) — the SCOPE BOUNDARY convention
+        // (agents/gsd-executor.md) has the executor log out-of-scope discoveries
+        // to this file; nothing previously read it back. Surface every
+        // UNRESOLVED entry (see parseDeferredItems for the resolved/unresolved
+        // parsing rule) as a 'deferred'-typed result, keeping deferred-items.md
+        // itself the single source of truth — no duplicate pending-todo entry
+        // required.
+        const deferredFile = 'deferred-items.md';
+        if (files.includes(deferredFile)) {
+            const content = node_fs_1.default.readFileSync(node_path_1.default.join(phaseDir, deferredFile), 'utf-8');
+            const items = parseDeferredItems(content);
+            if (items.length > 0) {
+                results.push({
+                    phase: phaseNum,
+                    phase_dir: dir,
+                    file: deferredFile,
+                    file_path: toPosixPath(node_path_1.default.relative(cwd, node_path_1.default.join(phaseDir, deferredFile))),
+                    type: 'deferred',
+                    status: 'unresolved',
+                    items,
+                });
+            }
+        }
     }
     // Compute summary
     const summary = {
@@ -124,7 +153,9 @@ function cmdRenderCheckpoint(cwd, options = {}, raw) {
     if (currentTest.complete) {
         error('UAT session is already complete; no pending checkpoint to render');
     }
-    const checkpoint = buildCheckpoint(currentTest);
+    const config = loadConfig(cwd);
+    const responseLanguage = typeof config.response_language === 'string' ? config.response_language : undefined;
+    const checkpoint = buildCheckpoint(currentTest, responseLanguage);
     output({
         file_path: toPosixPath(node_path_1.default.relative(cwd, resolvedPath)),
         test_number: currentTest.number,
@@ -237,11 +268,111 @@ function parseExpectedFromTestBlock(block) {
     const expectedInlineMatch = block.match(/^expected:\s*(.+)\s*$/m);
     return expectedInlineMatch ? expectedInlineMatch[1].trim() : null;
 }
-// ─── buildCheckpoint ──────────────────────────────────────────────────────────
-function buildCheckpoint(currentTest) {
+const CHECKPOINT_BOX_WIDTH = 64; // total column width of the ╔══...╗ border, borders stay byte-identical
+const CHECKPOINT_FRAMES = {
+    english: {
+        banner: 'CHECKPOINT: Verification Required',
+        instruction: 'Type `pass` or describe what\'s wrong.',
+    },
+    spanish: {
+        banner: 'PUNTO DE CONTROL: Verificación requerida',
+        instruction: 'Escribe `pass` o describe qué está mal.',
+    },
+    french: {
+        banner: 'POINT DE CONTRÔLE : Vérification requise',
+        instruction: 'Tapez `pass` ou décrivez ce qui ne va pas.',
+    },
+    german: {
+        banner: 'KONTROLLPUNKT: Überprüfung erforderlich',
+        instruction: 'Gib `pass` ein oder beschreibe, was nicht stimmt.',
+    },
+    portuguese: {
+        banner: 'PONTO DE VERIFICAÇÃO: Verificação necessária',
+        instruction: 'Digite `pass` ou descreva o que está errado.',
+    },
+    japanese: {
+        banner: 'チェックポイント: 検証が必要です',
+        instruction: '`pass` と入力するか、問題点を説明してください。',
+    },
+    chinese: {
+        banner: '检查点：需要验证',
+        instruction: '输入 `pass` 或描述问题所在。',
+    },
+    korean: {
+        banner: '체크포인트: 검증 필요',
+        instruction: '`pass`를 입력하거나 문제를 설명하세요.',
+    },
+    italian: {
+        banner: 'PUNTO DI CONTROLLO: Verifica richiesta',
+        instruction: 'Digita `pass` o descrivi cosa non va.',
+    },
+};
+// Free-form response_language aliases → canonical CHECKPOINT_FRAMES key.
+const CHECKPOINT_LANGUAGE_ALIASES = {
+    english: 'english', en: 'english', 'en-us': 'english', 'en-gb': 'english',
+    spanish: 'spanish', es: 'spanish', 'español': 'spanish', espanol: 'spanish', castellano: 'spanish',
+    french: 'french', fr: 'french', 'français': 'french', francais: 'french',
+    german: 'german', de: 'german', deutsch: 'german',
+    portuguese: 'portuguese', pt: 'portuguese', 'pt-br': 'portuguese', 'português': 'portuguese', portugues: 'portuguese', 'brazilian portuguese': 'portuguese',
+    japanese: 'japanese', ja: 'japanese', '日本語': 'japanese',
+    chinese: 'chinese', zh: 'chinese', 'zh-cn': 'chinese', 'zh-tw': 'chinese', mandarin: 'chinese', 'simplified chinese': 'chinese', 'traditional chinese': 'chinese', '中文': 'chinese',
+    korean: 'korean', ko: 'korean', '한국어': 'korean',
+    italian: 'italian', it: 'italian', italiano: 'italian',
+};
+function resolveCheckpointFrame(responseLanguage) {
+    if (!responseLanguage)
+        return CHECKPOINT_FRAMES.english;
+    const key = CHECKPOINT_LANGUAGE_ALIASES[responseLanguage.trim().toLowerCase()];
+    return (key && CHECKPOINT_FRAMES[key]) || CHECKPOINT_FRAMES.english;
+}
+// Approximate East Asian Width ranges (Unicode property values W and F) — the
+// CJK scripts CHECKPOINT_FRAMES ships (Japanese/Chinese/Korean) render each
+// matching code point at 2 terminal/display columns, not 1. Padding computed
+// from `.length` (UTF-16 code units) undercounts these by one column per
+// wide character, visually misaligning the box's right border (#2402 review
+// medium finding). Latin-script frames (English/Spanish/French/German/
+// Portuguese/Italian) contain no wide code points, so displayWidth === length
+// for them — no behavior change there.
+function isWideCodePoint(codePoint) {
+    return ((codePoint >= 0x1100 && codePoint <= 0x115f) || // Hangul Jamo
+        codePoint === 0x2329 || codePoint === 0x232a ||
+        (codePoint >= 0x2e80 && codePoint <= 0x303e) || // CJK Radicals .. CJK Symbols and Punctuation
+        (codePoint >= 0x3041 && codePoint <= 0x33ff) || // Hiragana .. CJK Compatibility
+        (codePoint >= 0x3400 && codePoint <= 0x4dbf) || // CJK Unified Ideographs Extension A
+        (codePoint >= 0x4e00 && codePoint <= 0x9fff) || // CJK Unified Ideographs
+        (codePoint >= 0xa000 && codePoint <= 0xa4cf) || // Yi Syllables
+        (codePoint >= 0xac00 && codePoint <= 0xd7a3) || // Hangul Syllables
+        (codePoint >= 0xf900 && codePoint <= 0xfaff) || // CJK Compatibility Ideographs
+        (codePoint >= 0xfe30 && codePoint <= 0xfe4f) || // CJK Compatibility Forms
+        (codePoint >= 0xff00 && codePoint <= 0xff60) || // Fullwidth Forms
+        (codePoint >= 0xffe0 && codePoint <= 0xffe6) ||
+        (codePoint >= 0x20000 && codePoint <= 0x3fffd) // CJK Unified Ideographs Extension B+ / supplementary
+    );
+}
+// Iterates by Unicode code point (not UTF-16 code unit) so astral characters
+// are measured once, not as two surrogate units.
+function displayWidth(text) {
+    let width = 0;
+    for (const ch of text) {
+        width += isWideCodePoint(ch.codePointAt(0)) ? 2 : 1;
+    }
+    return width;
+}
+// Pads `text` into a `║  text…  ║` line matching CHECKPOINT_BOX_WIDTH. Content
+// that overflows the box (a longer translated string) is left unpadded rather
+// than truncated — a slightly ragged border beats losing text.
+function checkpointBoxLine(text) {
+    const innerWidth = CHECKPOINT_BOX_WIDTH - 2;
+    const content = `  ${text}`;
+    const padLength = innerWidth - displayWidth(content);
+    const padded = padLength > 0 ? content + ' '.repeat(padLength) : content;
+    return `║${padded}║`;
+}
+function buildCheckpoint(currentTest, responseLanguage) {
+    const frame = resolveCheckpointFrame(responseLanguage);
     return [
         '╔══════════════════════════════════════════════════════════════╗',
-        '║  CHECKPOINT: Verification Required                           ║',
+        checkpointBoxLine(frame.banner),
         '╚══════════════════════════════════════════════════════════════╝',
         '',
         `**Test ${currentTest.number}: ${currentTest.name}**`,
@@ -249,7 +380,7 @@ function buildCheckpoint(currentTest) {
         currentTest.expected,
         '',
         '──────────────────────────────────────────────────────────────',
-        'Type `pass` or describe what\'s wrong.',
+        frame.instruction,
         '──────────────────────────────────────────────────────────────',
     ].join('\n');
 }
@@ -283,33 +414,302 @@ function parseUatItems(content) {
             items.push(item);
         }
     }
+    items.push(...parseGapsItems(content));
     return items;
 }
+// ─── parseGapsItems ───────────────────────────────────────────────────────────
+/**
+ * Extract unresolved entries from a UAT file's `## Gaps` section (#2286).
+ *
+ * `## Gaps` records open findings as a YAML-lite bullet list (see
+ * `templates/UAT.md`'s `## Gaps` block: `- truth: "..."` followed by indented
+ * continuation lines `status:` / `reason:` / `severity:` / `test:` / etc.,
+ * and — for `artifacts:` / `missing:` — a further-nested `- ` sub-list).
+ * `parseUatItems`'s `### N.` test-block regex never looks at this section at
+ * all, so a UAT file whose only outstanding findings live in `## Gaps` was
+ * silently invisible — the false-negative this fix addresses.
+ *
+ * Reuses the existing `collectSection` seam (already used elsewhere in this
+ * file for `## Current Test` / `## Tests`) to locate the section. Field
+ * extraction is deliberately NOT done via `iterateBullets`: that seam folds
+ * every continuation line onto ONE space-joined `text` string per bullet,
+ * which erases line boundaries — a `key:` scan against that flattened text
+ * matches the FIRST `key:`-shaped substring anywhere, including one that
+ * happens to appear inside an EARLIER field's own quoted free-text value
+ * (e.g. `truth: "The status: resolved workflow should trigger"` — a real
+ * `status: failed` on the next line would never be reached, silently
+ * DROPPING a genuinely open gap — the exact false-negative class #2286
+ * exists to fix, so the fix must not reintroduce it). `splitGapsEntries` /
+ * `extractGapEntryFields` below instead walk the section PER LINE and only
+ * recognise a field at the START of its own (trimmed) line, so a `key:`
+ * embedded inside another field's quoted value can never be mistaken for a
+ * field declaration.
+ *
+ * Every entry whose `status` is present and NOT `resolved` (case-insensitive)
+ * is surfaced — mirroring the "ignore passing/resolved" convention already
+ * used for `### N.` test blocks (`result: pass` is never surfaced) and the
+ * VERIFICATION table-row PASS/resolved skip (`hasPassResult`, below). An
+ * entry with NO parseable `status:` field is surfaced too, as `result:
+ * 'unknown'` — #2286 is a false-NEGATIVE bug, and a `## Gaps` entry only
+ * exists to record an outstanding finding (a template-conformant RESOLVED
+ * entry always carries an explicit `status: resolved`); a garbled or
+ * non-conformant entry is far more likely to be an unresolved finding whose
+ * `status:` line failed to parse than a genuinely resolved one, so the
+ * fail-safe direction is to surface it rather than silently drop it.
+ */
+function parseGapsItems(content) {
+    const gapsSection = collectSection(content, (h) => /^gaps$/i.test(h.text) && h.level === 2, { levelBounded: true });
+    if (!gapsSection)
+        return [];
+    const items = [];
+    for (const entryLines of splitGapsEntries(gapsSection.body)) {
+        const fields = extractGapEntryFields(entryLines);
+        const rawStatus = fields.status;
+        if (rawStatus && rawStatus.toLowerCase() === 'resolved')
+            continue;
+        // Fail-safe: missing/garbled status surfaces as 'unknown' rather than
+        // being dropped (see doc comment above).
+        const status = rawStatus || 'unknown';
+        const truth = fields.truth;
+        const reason = fields.reason;
+        const testNum = fields.test;
+        const item = {
+            name: truth || rawGapEntryText(entryLines),
+            result: status,
+            category: categorizeItem(status, reason, undefined),
+        };
+        if (testNum && /^\d+$/.test(testNum))
+            item.test = parseInt(testNum, 10);
+        if (reason)
+            item.reason = reason;
+        items.push(item);
+    }
+    return items;
+}
+// ─── parseDeferredItems ────────────────────────────────────────────────────────
+/**
+ * Extract unresolved entries from a phase directory's `deferred-items.md`
+ * (#2287) — the SCOPE BOUNDARY convention `agents/gsd-executor.md` instructs
+ * the executor to follow: "Log out-of-scope discoveries to `deferred-items.md`
+ * in the phase directory". Nothing previously read this file back, so a
+ * deferred entry was permanently invisible outside the phase directory.
+ *
+ * The writer convention (unchanged by this fix, per the issue's stated
+ * out-of-scope) emits a plain bullet list, typically under a `## Deferred
+ * Items` heading (see the issue's own reproduction fixture), one entry per
+ * top-level `- ` line with optional indented continuation lines. There is no
+ * mandated heading text, so if no `## Deferred Items`-shaped level-2 heading
+ * is found, the WHOLE file is scanned as the entry list — fail-safe, so an
+ * agent writing a differently-headed (or headless) deferred-items.md still
+ * has its entries surfaced rather than silently skipped.
+ *
+ * Reuses the same per-line field/entry-splitting seams as `parseGapsItems`
+ * (`splitGapsEntries`, `extractGapEntryFields`, `rawGapEntryText`) — an entry
+ * is RESOLVED only when it carries an explicit `status: resolved` field
+ * (case-insensitive), mirroring the established Gaps convention so a human or
+ * follow-up agent can mark a deferred item done in place, keeping
+ * `deferred-items.md` the single source of truth (no duplicate
+ * `.planning/todos/pending/*.md` entry required). Every other entry —
+ * including one with no `status:` field at all — is UNRESOLVED and is
+ * surfaced.
+ */
+function parseDeferredItems(content) {
+    const deferredSection = collectSection(content, (h) => /^deferred\s+items$/i.test(h.text) && h.level === 2, { levelBounded: true });
+    const sectionBody = deferredSection ? deferredSection.body : content;
+    const items = [];
+    for (const entryLines of splitGapsEntries(sectionBody)) {
+        const fields = extractGapEntryFields(entryLines);
+        const rawStatus = fields.status;
+        if (rawStatus && rawStatus.toLowerCase() === 'resolved')
+            continue;
+        const text = rawGapEntryText(entryLines);
+        if (!text)
+            continue;
+        items.push({
+            name: text,
+            result: 'unresolved',
+            category: 'deferred',
+        });
+    }
+    return items;
+}
+/**
+ * Split a `## Gaps` section body into per-entry line groups on TOP-LEVEL
+ * `- ` bullet openers.
+ *
+ * The indentation of the FIRST bullet line encountered establishes the
+ * "top-level" indent for the whole section; any subsequent `- `-opening line
+ * at that same indent (or shallower) starts a NEW entry, while everything
+ * more deeply indented — field continuation lines (`  status: ...`) AND
+ * nested sub-lists (`    - src/foo.ts` under `  artifacts:`) — is folded into
+ * the CURRENT entry. This keeps a `artifacts:`/`missing:` sub-list's `- `
+ * items from being mis-split into spurious standalone entries (#2286 review
+ * LOW finding).
+ *
+ * Lines before the first bullet (e.g. the `<!-- YAML format ... -->` comment
+ * the template emits) are discarded. An empty/whitespace-only section body
+ * (heading present, no bullets) returns `[]`.
+ */
+function splitGapsEntries(sectionBody) {
+    const lines = sectionBody.split('\n');
+    const entries = [];
+    let current = null;
+    let baseIndent = null;
+    for (const rawLine of lines) {
+        const line = rawLine.replace(/\r$/, '');
+        const bulletMatch = line.match(/^(\s*)-\s/);
+        if (bulletMatch) {
+            const indent = bulletMatch[1].length;
+            if (baseIndent === null)
+                baseIndent = indent;
+            if (indent <= baseIndent) {
+                if (current)
+                    entries.push(current);
+                current = [line];
+                continue;
+            }
+        }
+        if (current)
+            current.push(line);
+        // else: pre-first-bullet content (e.g. the template's HTML comment) — discarded.
+    }
+    if (current)
+        entries.push(current);
+    return entries;
+}
+/**
+ * Extract `key: value` fields from one Gaps entry's lines, anchored to the
+ * START of each (bullet-marker-stripped, trimmed) line — never scanning the
+ * REST of a line, so a colon-bearing phrase inside a quoted `truth`/`reason`
+ * value is never misread as a field declaration (see `parseGapsItems`'s doc
+ * comment for the false-negative this specifically guards against).
+ *
+ * Recognises a double-quoted value (`truth: "..."`, stripped of its wrapping
+ * quotes — the value may itself contain any character, including `:`) or a
+ * bare value (`status: open`, `test: 2`, `artifacts: []`) taken verbatim.
+ * The FIRST occurrence of a given key wins (top-level fields always precede
+ * any nested sub-list content in the template's field ordering); later
+ * `key:`-shaped nested-list content is captured, if it parses as one, but
+ * never overrides an already-seen top-level field.
+ */
+function extractGapEntryFields(entryLines) {
+    const fields = {};
+    const fieldLineRe = /^([A-Za-z_][A-Za-z0-9_-]*):\s*(.*)$/;
+    entryLines.forEach((rawLine, idx) => {
+        const line = rawLine.replace(/\r$/, '');
+        // Strip ONLY the entry-opening bullet marker (idx 0); a bullet marker on
+        // a later line belongs to a nested sub-list and is handled by
+        // `splitGapsEntries` already folding it in — it is not itself a field
+        // line unless it independently matches `key: value` after stripping.
+        const bulletStripped = line.match(/^(\s*)-\s+(.*)$/);
+        const content = idx === 0 && bulletStripped ? bulletStripped[2] : line.trim();
+        const m = fieldLineRe.exec(content);
+        if (!m)
+            return;
+        const key = m[1];
+        let value = m[2].trim();
+        if (value.startsWith('"') && value.endsWith('"') && value.length >= 2) {
+            value = value.slice(1, -1);
+        }
+        if (!(key in fields))
+            fields[key] = value;
+    });
+    return fields;
+}
+/** Fallback display text for a Gaps entry with no parseable `truth:` field. */
+function rawGapEntryText(entryLines) {
+    return entryLines
+        .map((l, i) => (i === 0 ? l.replace(/^(\s*)-\s+/, '') : l.trim()))
+        .join(' ')
+        .trim();
+}
 // ─── parseVerificationItems ───────────────────────────────────────────────────
 function parseVerificationItems(content, status) {
     const items = [];
     if (status === 'human_needed') {
+        // #2286: the frontmatter's structured `human_verification:` YAML array
+        // (extractFrontmatter) is the PRIMARY source of truth when present and
+        // non-empty — it fully bypasses the body-shape scan below, so a file
+        // whose frontmatter declares the array doesn't require any particular
+        // `## Human Verification` body shape at all. An absent or empty array
+        // (length 0) falls back to the body scan unchanged.
+        const frontmatter = extractFrontmatter(content);
+        const humanVerification = frontmatter.human_verification;
+        if (Array.isArray(humanVerification) && humanVerification.length > 0) {
+            humanVerification.forEach((entry, idx) => {
+                items.push({
+                    test: idx + 1,
+                    name: normalizeHumanVerificationEntry(entry),
+                    result: 'human_needed',
+                    category: 'human_uat',
+                });
+            });
+            return items;
+        }
         // Use the seam to locate the ## Human Verification section (ADR-1372 T5).
         const hvSection = collectSection(content, (h) => /^human\s+verification/i.test(h.text) && h.level === 2, { levelBounded: true });
         if (hvSection) {
+            // #2245 review Fix 3: reverted to the pre-Phase-4 (HEAD 2cbf18642)
+            // implementation. The live Human Verification section is NOT a strict
+            // GFM table — the planner/verifier templates mix table rows, numbered
+            // items, and bullet items in the same section (and a `### N.` heading
+            // format is common too), so a table-XOR-list read (parse a table, and
+            // if it parses, suppress numbered/bullet items entirely) silently
+            // dropped items on any mixed or malformed section: a malformed
+            // `| N | … |` table with no valid header/delimiter yielded ZERO items
+            // instead of reading the rows positionally. This per-line scan reads
+            // table rows AND numbered items AND bullet items as a UNION (whichever
+            // pattern a given line matches), exactly like OLD, and reads
+            // `| N | desc |` rows even without a valid table header/delimiter.
+            //
+            // #2245 audit: the table-row branch's CELL SPLIT is name/position-
+            // addressed via `splitTableRow` (escape-aware, canonical) instead of a
+            // hand-rolled pipe regex — candidacy itself is decided WITHOUT a table
+            // regex (a leading `|` plus a purely-numeric first cell), so this no
+            // longer needs an allow-adhoc-markdown suppression at all.
             const lines = hvSection.body.split('\n');
             for (const line of lines) {
-                // Match table rows: | N | description | ... |
-                const tableMatch = line.match(/\|\s*(\d+)\s*\|\s*([^|]+)/);
+                const trimmedLine = line.trim();
+                // Match table rows: | N | description | ... — candidacy requires a
+                // leading pipe and a purely-numeric first cell (mirrors what the old
+                // regex effectively required: a "|digit|" cell immediately followed
+                // by more content), with at least 2 physical cells so a bare "| N |"
+                // with nothing after it is NOT treated as a row.
+                //
+                // #2245 review Fix 9: this is NOT the same as OLD for a row whose
+                // ONLY content past the digit cell is trailing whitespace (e.g.
+                // "| N | ", no second delimiting `|`). OLD's `([^|]+)` regex ran
+                // against the RAW (untrimmed) line and its `\s*` would backtrack to
+                // let `[^|]+` swallow that trailing whitespace, so OLD matched and
+                // pushed an item with an EMPTY (`.trim()`-collapsed) name. Here,
+                // `trimmedLine = line.trim()` strips that trailing whitespace BEFORE
+                // `splitTableRow` ever sees it, collapsing the line to a single cell
+                // (`candidateCells.length === 1`), which fails the `>= 2` check —
+                // the item is silently dropped instead. A real, acceptable behaviour
+                // change (an empty-named UAT item is not useful either way), but the
+                // two implementations are NOT equivalent on this input.
+                let tableCells = null;
+                if (trimmedLine.startsWith('|')) {
+                    const candidateCells = splitTableRow(trimmedLine);
+                    if (candidateCells.length >= 2 && /^\d+$/.test(candidateCells[0])) {
+                        tableCells = candidateCells;
+                    }
+                }
                 // Match bullet items: - description
                 const bulletMatch = line.match(/^[-*]\s+(.+)/);
                 // Match numbered items: 1. description
                 const numberedMatch = line.match(/^(\d+)\.\s+(.+)/);
-                if (tableMatch) {
+                if (tableCells) {
                     // Skip rows that already have a passing result (PASS, pass, resolved, etc.)
-                    const rowRemainder = line.slice(tableMatch.index + tableMatch[0].length);
-                    const cellValues = rowRemainder.split('|').map(c => c.trim());
-                    const hasPassResult = cellValues.some(c => /^pass$/i.test(c) || /^resolved$/i.test(c));
+                    // — checked over every cell AFTER the description column, mirroring
+                    // OLD's rowRemainder scan (which only ever saw cells past the
+                    // description, the description itself having already been consumed).
+                    const hasPassResult = tableCells.slice(2).some(c => /^pass$/i.test(c) || /^resolved$/i.test(c));
                     if (hasPassResult)
                         continue;
                     items.push({
-                        test: parseInt(tableMatch[1], 10),
-                        name: tableMatch[2].trim(),
+                        test: parseInt(tableCells[0], 10),
+                        name: tableCells[1] ?? '',
                         result: 'human_needed',
                         category: 'human_uat',
                     });
@@ -330,11 +730,71 @@ function parseVerificationItems(content, status) {
                     });
                 }
             }
+            // #2286: fall back to the `### N. <label>` heading + bold-led paragraph
+            // shape (the canonical form emitted by `templates/verification-report.md`
+            // — `### 1. {Test Name}` followed by `**Test:** ... **Expected:** ...
+            // **Why human:** ...`), which the table/bullet/numbered per-line scan
+            // above never recognises (a `###`-prefixed line matches none of those
+            // three patterns). Uses the same `tokenizeHeadings` seam
+            // `parseFirstPendingTest` already uses for `### N.` sub-headings,
+            // applied here to the Human Verification section body. Runs in
+            // addition to (a union with) the scan above — the two shapes don't
+            // collide, so this only adds items a `###` heading page would have
+            // silently produced zero for.
+            const hvSubHeadings = tokenizeHeadings(hvSection.body).filter((h) => h.level === 3 && /^\d+\.\s+/.test(h.text));
+            for (let i = 0; i < hvSubHeadings.length; i += 1) {
+                const current = hvSubHeadings[i];
+                const next = hvSubHeadings[i + 1];
+                const block = next
+                    ? hvSection.body.slice(current.offset, next.offset)
+                    : hvSection.body.slice(current.offset);
+                const bodyAfterHeading = block.slice(block.indexOf('\n') + 1);
+                // Require a bold-led paragraph body (`**Test:** ...`) to distinguish
+                // a genuine verification item from an unrelated numbered heading.
+                if (!/^\s*\*\*/.test(bodyAfterHeading))
+                    continue;
+                const headingParts = current.text.match(/^(\d+)\.\s+(.+)$/);
+                if (!headingParts)
+                    continue;
+                items.push({
+                    test: parseInt(headingParts[1], 10),
+                    name: headingParts[2].trim(),
+                    result: 'human_needed',
+                    category: 'human_uat',
+                });
+            }
         }
     }
     // gaps_found items are already handled by plan-phase --gaps pipeline
     return items;
 }
+/**
+ * Normalize a single `human_verification:` frontmatter array entry (#2286)
+ * into a display-ready name.
+ *
+ * #2286 review (LOW finding): `extractFrontmatter`'s generic array-item
+ * parser (`src/frontmatter.cts`, the `line.trim().startsWith('- ')` branch)
+ * has NO notion of nested key/value objects — regardless of whether the
+ * source YAML was authored as `- test: "..."` (an implied-but-unsupported
+ * shorthand) or `- "plain string"`, it ALWAYS pushes the raw post-`- ` text
+ * (with only a single layer of wrapping quotes stripped) as a plain string.
+ * There is therefore no reliable signal here to distinguish a genuine
+ * `key: value`-shaped pseudo-field from a legitimate plain string that
+ * itself happens to start with a word and a colon (e.g. `"Confirm: the
+ * button responds"`). A prior version of this function stripped a leading
+ * `word:` prefix on the assumption it was always a flattened nested-object
+ * key — that assumption is false, and it silently truncated real plain-string
+ * content. No such stripping is applied: any residual wrapping-quote noise
+ * left by `extractFrontmatter`'s own (anchor-only) quote handling is cleaned
+ * up, and everything else is preserved verbatim.
+ */
+function normalizeHumanVerificationEntry(raw) {
+    if (typeof raw !== 'string') {
+        return raw === null || raw === undefined ? '' : JSON.stringify(raw);
+    }
+    const s = raw.trim().replace(/^["']+|["']+$/g, '').trim();
+    return s || raw.trim();
+}
 // ─── categorizeItem ───────────────────────────────────────────────────────────
 function categorizeItem(result, reason, blockedBy) {
     if (result === 'blocked' || blockedBy) {
@@ -372,4 +832,5 @@ module.exports = {
     cmdRenderCheckpoint,
     parseCurrentTest,
     buildCheckpoint,
+    parseDeferredItems,
 };

package/gsd-core/bin/lib/ui-safety-gate.cjs

@@ -67,14 +67,36 @@ function checkUiPresence(text) {
     }
     // Normalise CRLF so the pattern sees consistent line boundaries.
     const normalised = text.replace(/\r\n/g, '\n');
+    // #2150: an explicit `**UI hint**: yes|no` metadata line is the author's
+    // authoritative declaration of whether the phase has a UI surface — progress.md
+    // and new-project.md already parse this line (`UI hint.*yes`). The bare token
+    // `UI` in the line itself must not count as a UI indicator, and the declaration
+    // overrides token-sniffing. Line-anchored (`m`) so a mid-line prose mention is
+    // not treated as the metadata line; word-boundary on the value so `nope`/`not`
+    // do not match `no`.
+    const hintMatch = normalised.match(/^\s*\*\*UI hint\*\*\s*:\s*(yes|no)\b/im);
+    const hint = hintMatch ? hintMatch[1].toLowerCase() : null;
+    // Strip ANY `**UI hint**:` line before token-sniffing so a hint without a
+    // recognised yes/no (or one we did not short-circuit on) cannot false-positive
+    // on the bare `UI` token.
+    const sniffable = normalised
+        .split('\n')
+        .filter((line) => !/^\s*\*\*UI hint\*\*\s*:/i.test(line))
+        .join('\n');
     const found = new Set();
-    for (const line of normalised.split('\n')) {
+    for (const line of sniffable.split('\n')) {
         // Reset lastIndex before each line so the global pattern restarts from 0.
         UI_GATE_PATTERN_GLOBAL.lastIndex = 0;
         for (const m of line.matchAll(UI_GATE_PATTERN_GLOBAL)) {
             found.add(m[2].toLowerCase());
         }
     }
+    if (hint === 'no') {
+        return { hasUI: false, tokens: [] };
+    }
+    if (hint === 'yes') {
+        return { hasUI: true, tokens: [...found] };
+    }
     return { hasUI: found.size > 0, tokens: [...found] };
 }
 // ── CLI entry point ─────────────────────────────────────────────────────────

package/gsd-core/bin/lib/validate.cjs

@@ -39,28 +39,32 @@ exports.buildRoadmapPhaseVariants = buildRoadmapPhaseVariants;
 exports.buildNotStartedPhaseVariants = buildNotStartedPhaseVariants;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdMod = require("./phase-id.cjs");
-const { OPTIONAL_PROJECT_CODE_PREFIX_SOURCE, PHASE_NUMBER_TOKEN_SOURCE } = phaseIdMod;
+const { OPTIONAL_PROJECT_CODE_PREFIX_SOURCE, PHASE_NUMBER_TOKEN_SOURCE, PHASE_CONTINUATION_SEGMENT_SOURCE, } = phaseIdMod;
 // ── Issue #26: regex constants (W005, W006-archived) ────────────────────────
 // Matches legacy numeric dirs (01-setup), milestone-prefixed dirs (02-01-setup),
 // deep dirs (02-04-01-deep), and project-code-prefixed variants (GSD-02-01-setup).
 exports.phaseDirNameRe = new RegExp(`^${OPTIONAL_PROJECT_CODE_PREFIX_SOURCE}\\d{2,}(?:-\\d+)*(?:\\.\\d+)*-[\\w-]+$`, 'i');
 // Extracts the full phase token from a directory name, including milestone-prefixed
 // multi-segment tokens like "02-01" from "02-01-setup" or "GSD-02-01-setup".
-// #2043: a *continuation* sub-phase segment must be zero-padded (≥2 digits), so a
+// #2043: a *continuation* sub-phase segment must be zero-padded, so a
 // single-digit slug word after a phase number (e.g. "46-6-rs-…", slug "6 Rs …") is
-// NOT absorbed — it captures "46", not "46-6". The first component stays "\d+"
+// NOT absorbed — it captures "46", not "46-6". #2232: the continuation width is
+// exactly 2 (PHASE_CONTINUATION_SEGMENT_SOURCE), so a ≥3-digit slug word (a year:
+// "14-2026-photos-…") is not absorbed either — it captures "14", not "14-2026".
+// The first component stays "\d+"
 // (with the "[A-Z]?" suffix) so single-digit letter-suffixed phase ids ("1A") and
 // milestone-prefixed single-digit sub-phases ("M1-2" → prefix "M1-" stripped, then
 // "2") still match. The trailing boundary "(?:-|$)" (was "(?:-[a-z]|$)") lets a slug
 // that starts with a digit terminate the token.
-exports.PHASE_TOKEN_FROM_DIR_RE = new RegExp(`^${OPTIONAL_PROJECT_CODE_PREFIX_SOURCE}(\\d+(?:-\\d{2,})*[A-Z]?(?:\\.\\d+)*)(?:-|$)`, 'i');
+exports.PHASE_TOKEN_FROM_DIR_RE = new RegExp(`^${OPTIONAL_PROJECT_CODE_PREFIX_SOURCE}(\\d+(?:-${PHASE_CONTINUATION_SEGMENT_SOURCE})*[A-Z]?(?:\\.\\d+)*)(?:-|$)`, 'i');
 exports.MILESTONE_ARCHIVE_DIR_RE = /^v\d+.*-phases$/i;
 // ── Issue #26: I001 canonicalization ────────────────────────────────────────
 function canonicalPlanStem(stem) {
-    // #2043: the plan component (after the phase number) must be zero-padded
-    // (≥2 digits), so a digit-leading slug word (e.g. "46-6-rs-…") is not mistaken
-    // for a "46-6" phase/plan pair.
-    const m = stem.match(new RegExp(`^(${PHASE_NUMBER_TOKEN_SOURCE}-\\d{2,})`, 'i'));
+    // #2043: the plan component (after the phase number) must be zero-padded,
+    // so a digit-leading slug word (e.g. "46-6-rs-…") is not mistaken
+    // for a "46-6" phase/plan pair. #2232: exactly 2 digits, so a year-leading
+    // slug ("14-2026-photos-…") is not mistaken for a "14-2026" pair either.
+    const m = stem.match(new RegExp(`^(${PHASE_NUMBER_TOKEN_SOURCE}-${PHASE_CONTINUATION_SEGMENT_SOURCE})`, 'i'));
     return m ? m[1] : stem;
 }
 // ── Issue #6: phase variant helpers (W006/W007) ──────────────────────────────