@opengsd/gsd-core 1.7.0 → 1.9.0

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

@@ -37,7 +37,11 @@ const node_path_1 = __importDefault(require("node:path"));
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const installProfiles = require("./install-profiles.cjs");
-const { readActiveProfile, resolveProfile, loadSkillsManifest, } = installProfiles;
+const { readActiveProfile, resolveProfile, loadSkillsManifest, 
+// #2322 HIGH-3: shared marker name — single source of truth with the writer
+// (install-profiles.cts stageSkillsForRuntimeAsSkills) so the prune reader
+// below can never drift from what the stage-time writer actually wrote.
+CAPABILITY_SKILL_MARKER, } = installProfiles;
 const clusters_cjs_1 = require("./clusters.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const runtimeArtifactLayout = require("./runtime-artifact-layout.cjs");
@@ -379,12 +383,18 @@ function applySurface(runtimeConfigDir, layout, manifest, clusterMap, registry,
  *
  * Ownership criteria:
  *   - Non-empty prefix (e.g. 'gsd-'): dir name starts with that prefix AND
- *     appears in the manifest (manifest membership is required). Dirs that match
- *     the prefix but are NOT in the manifest are treated as user-owned and
+ *     EITHER appears in the manifest (first-party membership) OR carries the
+ *     persisted `CAPABILITY_SKILL_MARKER` file (#2322 HIGH-3: a third-party
+ *     capability skill, self-certifying and independent of current registry
+ *     state — so an uninstalled/unsurfaced capability's stale skill is still
+ *     prunable even though it no longer appears in any registry view). Dirs
+ *     that match the prefix but satisfy NEITHER are treated as user-owned and
  *     preserved — this prevents data loss for user-created gsd-* directories.
  *     A warning is written to stderr when such a dir is encountered.
  *   - Empty prefix (Hermes): dir name appears as a canonical skill stem in the
- *     manifest. User dirs not in the manifest are preserved.
+ *     manifest. User dirs not in the manifest are preserved. (Hermes does not
+ *     yet stage third-party capability skills, so the marker check does not
+ *     apply on this path.)
  *   - Empty prefix without manifest, or manifest not a Map: conservative; no
  *     dirs are removed.
  *
@@ -419,18 +429,50 @@ function pruneSkillDirs(skillsDir, retainedNames, prefix, manifest) {
                 // Does not match prefix at all — user-owned, preserve.
                 continue;
             }
-            if (!canonicalStems) {
-                // No manifest available: cannot confirm ownership — preserve conservatively.
+            // #2322: an entry in THIS apply's retained set is unambiguously wanted —
+            // check that BEFORE the first-party-manifest-membership gate below. The
+            // manifest only ever knows gsd-core's own bundled stems; a materialized
+            // third-party capability skill (retained via the resolved profile's
+            // registry union, #2045/#2322) has no manifest entry at all, so without
+            // this early check it fell into the "unknown, preserve with warning"
+            // branch on EVERY apply — misreporting a live, GSD-managed capability
+            // skill as "user-owned or unknown" noise. This does not change any
+            // deletion outcome (a retained entry was always preserved — see the
+            // `retainedNames.has(entry)` check further below); it only short-
+            // circuits the ambiguous-ownership warning for entries we already know,
+            // this apply, are wanted.
+            if (retainedNames.has(entry))
                 continue;
-            }
             // Finding 1 fix: prefix match is necessary but NOT sufficient.
             // The dir must also be in the manifest to be considered GSD-owned.
             // A user-created gsd-* dir that isn't in the manifest is preserved with a warning.
-            if (!canonicalStems.has(entry.slice(prefix.length))) {
+            const stem = entry.slice(prefix.length);
+            if (canonicalStems && canonicalStems.has(stem)) {
+                isGsdOwned = true;
+            }
+            else if (node_fs_1.default.existsSync(node_path_1.default.join(entryPath, CAPABILITY_SKILL_MARKER))) {
+                // #2322 HIGH-3: not a first-party stem, but self-certified as a
+                // GSD-managed THIRD-PARTY capability skill via the persisted marker
+                // (written by install-profiles.cts stageSkillsForRuntimeAsSkills at
+                // stage time). Without this, an orphaned capability skill — its
+                // owning capability uninstalled/unsurfaced and no longer appearing in
+                // ANY registry view — had no manifest entry at all and fell into the
+                // "unknown, preserve with warning" branch below FOREVER: uninstalling
+                // a malicious capability never actually removed its already-staged
+                // instructions from the agent's context. The marker makes ownership
+                // self-certifying at prune time, independent of current registry
+                // state (or even of whether a manifest was supplied at all).
+                isGsdOwned = true;
+            }
+            else if (!canonicalStems) {
+                // No manifest available and no capability marker: cannot confirm
+                // ownership — preserve conservatively (silent).
+                continue;
+            }
+            else {
                 process.stderr.write(`[gsd] Warning: ${entry} matches GSD prefix '${prefix}' but is not in the manifest — preserving (user-owned or unknown)\n`);
                 continue;
             }
-            isGsdOwned = true;
         }
         else if (canonicalStems) {
             // Hermes: GSD-owned iff the directory name appears in the canonical manifest.

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

@@ -194,9 +194,10 @@ function evaluateUatPassed(phaseFullDir, opts) {
     // ── Process UAT files ──────────────────────────────────────────────────────
     for (const file of uatFileNames) {
         uatFiles.push(file);
+        const uatFilePath = node_path_1.default.join(phaseFullDir, file);
         let raw = '';
         try {
-            raw = node_fs_1.default.readFileSync(node_path_1.default.join(phaseFullDir, file), 'utf-8');
+            raw = node_fs_1.default.readFileSync(uatFilePath, 'utf-8');
         }
         catch {
             blockers.push(`${file}: could not read file`);
@@ -210,7 +211,7 @@ function evaluateUatPassed(phaseFullDir, opts) {
         if (unterminatedFence || unterminatedComment) {
             blockers.push(`${file}: malformed markdown (unterminated fence or comment)`);
         }
-        const fm = extractFrontmatter(raw);
+        const fm = extractFrontmatter(raw, uatFilePath);
         // File-level frontmatter status check
         if (fm['status'] && BLOCKING_UAT_FM_STATUSES.has(fm['status'])) {
             blockers.push(`${file}: frontmatter status=${fm['status']}`);
@@ -240,15 +241,16 @@ function evaluateUatPassed(phaseFullDir, opts) {
     let hasPassingVerification = false;
     for (const file of verFileNames) {
         verificationFiles.push(file);
+        const verificationFilePath = node_path_1.default.join(phaseFullDir, file);
         let raw = '';
         try {
-            raw = node_fs_1.default.readFileSync(node_path_1.default.join(phaseFullDir, file), 'utf-8');
+            raw = node_fs_1.default.readFileSync(verificationFilePath, 'utf-8');
         }
         catch {
             blockers.push(`${file}: could not read verification file`);
             continue;
         }
-        const vfm = extractFrontmatter(raw);
+        const vfm = extractFrontmatter(raw, verificationFilePath);
         const vStatus = vfm['status'];
         if (vStatus && BLOCKING_VERIFICATION_FM_STATUSES.has(vStatus)) {
             blockers.push(`${file}: verification status=${vStatus}`);

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

@@ -39,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');
@@ -60,7 +63,8 @@ function cmdAuditUat(cwd, raw) {
         const files = node_fs_1.default.readdirSync(phaseDir);
         // Process UAT files
         for (const file of files.filter(f => f.includes('-UAT') && f.endsWith('.md'))) {
-            const content = node_fs_1.default.readFileSync(node_path_1.default.join(phaseDir, file), 'utf-8');
+            const uatFilePath = node_path_1.default.join(phaseDir, file);
+            const content = node_fs_1.default.readFileSync(uatFilePath, 'utf-8');
             const items = parseUatItems(content);
             if (items.length > 0) {
                 results.push({
@@ -69,17 +73,18 @@ function cmdAuditUat(cwd, raw) {
                     file,
                     file_path: toPosixPath(node_path_1.default.relative(cwd, node_path_1.default.join(phaseDir, file))),
                     type: 'uat',
-                    status: (extractFrontmatter(content).status || 'unknown'),
+                    status: (extractFrontmatter(content, uatFilePath).status || 'unknown'),
                     items,
                 });
             }
         }
         // Process VERIFICATION files
         for (const file of files.filter(f => f.includes('-VERIFICATION') && f.endsWith('.md'))) {
-            const content = node_fs_1.default.readFileSync(node_path_1.default.join(phaseDir, file), 'utf-8');
-            const status = extractFrontmatter(content).status || 'unknown';
+            const verificationFilePath = node_path_1.default.join(phaseDir, file);
+            const content = node_fs_1.default.readFileSync(verificationFilePath, 'utf-8');
+            const status = extractFrontmatter(content, verificationFilePath).status || 'unknown';
             if (status === 'human_needed' || status === 'gaps_found') {
-                const items = parseVerificationItems(content, status);
+                const items = parseVerificationItems(content, status, verificationFilePath);
                 if (items.length > 0) {
                     results.push({
                         phase: phaseNum,
@@ -93,6 +98,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 = {
@@ -127,7 +155,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,
@@ -240,11 +270,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}**`,
@@ -252,7 +382,7 @@ function buildCheckpoint(currentTest) {
         currentTest.expected,
         '',
         '──────────────────────────────────────────────────────────────',
-        'Type `pass` or describe what\'s wrong.',
+        frame.instruction,
         '──────────────────────────────────────────────────────────────',
     ].join('\n');
 }
@@ -286,12 +416,238 @@ 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) {
+function parseVerificationItems(content, status, sourcePath) {
     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, sourcePath);
+        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) {
@@ -376,11 +732,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) {
@@ -418,4 +834,5 @@ module.exports = {
     cmdRenderCheckpoint,
     parseCurrentTest,
     buildCheckpoint,
+    parseDeferredItems,
 };