@therocketcode/gsd-core 1.4.0

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

@@ -0,0 +1,237 @@
+"use strict";
+/**
+ * Template — Template selection and fill operations
+ *
+ * ADR-457 build-at-publish: the hand-written bin/lib/template.cjs collapsed
+ * to a TypeScript source of truth. Behaviour is preserved byte-for-behaviour
+ * from the prior hand-written .cjs; only strict types are added.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const core = require("./core.cjs");
+const { normalizePhaseName, findPhaseInternal, generateSlugInternal, toPosixPath, output, error } = core;
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planningWorkspace = require("./planning-workspace.cjs");
+const { planningDir } = planningWorkspace;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const frontmatter = require("./frontmatter.cjs");
+const { reconstructFrontmatter } = frontmatter;
+// ─── cmdTemplateSelect ────────────────────────────────────────────────────────
+function cmdTemplateSelect(cwd, planPath, raw) {
+    if (!planPath) {
+        error('plan-path required');
+    }
+    try {
+        const fullPath = node_path_1.default.join(cwd, planPath);
+        const content = node_fs_1.default.readFileSync(fullPath, 'utf-8');
+        // Simple heuristics
+        const taskMatch = content.match(/###\s*Task\s*\d+/g) || [];
+        const taskCount = taskMatch.length;
+        const decisionMatch = content.match(/decision/gi) || [];
+        const hasDecisions = decisionMatch.length > 0;
+        // Count file mentions
+        const fileMentions = new Set();
+        const filePattern = /`([^`]+\.[a-zA-Z]+)`/g;
+        let m;
+        while ((m = filePattern.exec(content)) !== null) {
+            if (m[1].includes('/') && !m[1].startsWith('http')) {
+                fileMentions.add(m[1]);
+            }
+        }
+        const fileCount = fileMentions.size;
+        let template = 'templates/summary-standard.md';
+        let type = 'standard';
+        if (taskCount <= 2 && fileCount <= 3 && !hasDecisions) {
+            template = 'templates/summary-minimal.md';
+            type = 'minimal';
+        }
+        else if (hasDecisions || fileCount > 6 || taskCount > 5) {
+            template = 'templates/summary-complex.md';
+            type = 'complex';
+        }
+        const result = { template, type, taskCount, fileCount, hasDecisions };
+        output(result, raw, template);
+    }
+    catch (e) {
+        // Fallback to standard
+        output({ template: 'templates/summary-standard.md', type: 'standard', error: e.message }, raw, 'templates/summary-standard.md');
+    }
+}
+// ─── cmdTemplateFill ──────────────────────────────────────────────────────────
+function cmdTemplateFill(cwd, templateType, options, raw) {
+    if (!templateType) {
+        error('template type required: summary, plan, or verification');
+    }
+    if (!options.phase) {
+        error('--phase required');
+    }
+    const phaseInfo = findPhaseInternal(cwd, options.phase);
+    if (!phaseInfo || !phaseInfo.found) {
+        output({ error: 'Phase not found', phase: options.phase }, raw, undefined);
+        return;
+    }
+    const padded = normalizePhaseName(options.phase);
+    const today = new Date().toISOString().split('T')[0];
+    const phaseName = options.name || phaseInfo.phase_name || 'Unnamed';
+    const phaseSlug = phaseInfo.phase_slug || generateSlugInternal(phaseName);
+    const phaseId = `${padded}-${phaseSlug}`;
+    const planNum = (options.plan || '01').padStart(2, '0');
+    const fields = options.fields || {};
+    let frontmatterObj;
+    let body;
+    let fileName;
+    switch (templateType) {
+        case 'summary': {
+            frontmatterObj = {
+                phase: phaseId,
+                plan: planNum,
+                subsystem: '[primary category]',
+                tags: [],
+                provides: [],
+                affects: [],
+                'tech-stack': { added: [], patterns: [] },
+                'key-files': { created: [], modified: [] },
+                'key-decisions': [],
+                'patterns-established': [],
+                duration: '[X]min',
+                completed: today,
+                ...fields,
+            };
+            body = [
+                `# Phase ${options.phase}: ${phaseName} Summary`,
+                '',
+                '**[Substantive one-liner describing outcome]**',
+                '',
+                '## Performance',
+                '- **Duration:** [time]',
+                '- **Tasks:** [count completed]',
+                '- **Files modified:** [count]',
+                '',
+                '## Accomplishments',
+                '- [Key outcome 1]',
+                '- [Key outcome 2]',
+                '',
+                '## Task Commits',
+                '1. **Task 1: [task name]** - `hash`',
+                '',
+                '## Files Created/Modified',
+                '- `path/to/file.ts` - What it does',
+                '',
+                '## Decisions & Deviations',
+                '[Key decisions or "None - followed plan as specified"]',
+                '',
+                '## Next Phase Readiness',
+                '[What\'s ready for next phase]',
+            ].join('\n');
+            fileName = `${padded}-${planNum}-SUMMARY.md`;
+            break;
+        }
+        case 'plan': {
+            const planType = options.type || 'execute';
+            const wave = parseInt(String(options.wave), 10) || 1;
+            frontmatterObj = {
+                phase: phaseId,
+                plan: planNum,
+                type: planType,
+                wave,
+                depends_on: [],
+                files_modified: [],
+                autonomous: true,
+                user_setup: [],
+                must_haves: { truths: [], artifacts: [], key_links: [] },
+                ...fields,
+            };
+            const planBase = planningDir(cwd);
+            const projectRef = toPosixPath(node_path_1.default.relative(cwd, node_path_1.default.join(planBase, 'PROJECT.md')));
+            const roadmapRef = toPosixPath(node_path_1.default.relative(cwd, node_path_1.default.join(planBase, 'ROADMAP.md')));
+            const stateRef = toPosixPath(node_path_1.default.relative(cwd, node_path_1.default.join(planBase, 'STATE.md')));
+            body = [
+                `# Phase ${options.phase} Plan ${planNum}: [Title]`,
+                '',
+                '## Objective',
+                '- **What:** [What this plan builds]',
+                '- **Why:** [Why it matters for the phase goal]',
+                '- **Output:** [Concrete deliverable]',
+                '',
+                '## Context',
+                `@${projectRef}`,
+                `@${roadmapRef}`,
+                `@${stateRef}`,
+                '',
+                '## Tasks',
+                '',
+                '<task type="code">',
+                '  <name>[Task name]</name>',
+                '  <files>[file paths]</files>',
+                '  <action>[What to do]</action>',
+                '  <verify>[How to verify]</verify>',
+                '  <done>[Definition of done]</done>',
+                '</task>',
+                '',
+                '## Verification',
+                '[How to verify this plan achieved its objective]',
+                '',
+                '## Success Criteria',
+                '- [ ] [Criterion 1]',
+                '- [ ] [Criterion 2]',
+            ].join('\n');
+            fileName = `${padded}-${planNum}-PLAN.md`;
+            break;
+        }
+        case 'verification': {
+            frontmatterObj = {
+                phase: phaseId,
+                verified: new Date().toISOString(),
+                status: 'pending',
+                score: '0/0 must-haves verified',
+                ...fields,
+            };
+            body = [
+                `# Phase ${options.phase}: ${phaseName} — Verification`,
+                '',
+                '## Observable Truths',
+                '| # | Truth | Status | Evidence |',
+                '|---|-------|--------|----------|',
+                '| 1 | [Truth] | pending | |',
+                '',
+                '## Required Artifacts',
+                '| Artifact | Expected | Status | Details |',
+                '|----------|----------|--------|---------|',
+                '| [path] | [what] | pending | |',
+                '',
+                '## Key Link Verification',
+                '| From | To | Via | Status | Details |',
+                '|------|----|----|--------|---------|',
+                '| [source] | [target] | [connection] | pending | |',
+                '',
+                '## Requirements Coverage',
+                '| Requirement | Status | Blocking Issue |',
+                '|-------------|--------|----------------|',
+                '| [req] | pending | |',
+                '',
+                '## Result',
+                '[Pending verification]',
+            ].join('\n');
+            fileName = `${padded}-VERIFICATION.md`;
+            break;
+        }
+        default:
+            error(`Unknown template type: ${templateType}. Available: summary, plan, verification`);
+            return;
+    }
+    const fullContent = `---\n${reconstructFrontmatter(frontmatterObj)}\n---\n\n${body}\n`;
+    const outPath = node_path_1.default.join(cwd, phaseInfo.directory, fileName);
+    if (node_fs_1.default.existsSync(outPath)) {
+        output({ error: 'File already exists', path: toPosixPath(node_path_1.default.relative(cwd, outPath)) }, raw, undefined);
+        return;
+    }
+    (0, shell_command_projection_cjs_1.platformWriteSync)(outPath, fullContent);
+    const relPath = toPosixPath(node_path_1.default.relative(cwd, outPath));
+    output({ created: true, path: relPath, template: templateType }, raw, relPath);
+}
+module.exports = { cmdTemplateSelect, cmdTemplateFill };

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

@@ -0,0 +1,297 @@
+"use strict";
+/**
+ * UAT Audit — Cross-phase UAT/VERIFICATION scanner
+ *
+ * Reads all *-UAT.md and *-VERIFICATION.md files across all phases.
+ * Extracts non-passing items. Returns structured JSON for workflow consumption.
+ *
+ * ADR-457 build-at-publish: the hand-written bin/lib/uat.cjs collapsed
+ * to a TypeScript source of truth. Behaviour is preserved byte-for-behaviour
+ * from the prior hand-written .cjs; only strict types are added.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const core = require("./core.cjs");
+const { output, error, getMilestonePhaseFilter, toPosixPath } = core;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planningWorkspace = require("./planning-workspace.cjs");
+const { planningDir } = planningWorkspace;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const frontmatter = require("./frontmatter.cjs");
+const { extractFrontmatter } = frontmatter;
+const security_cjs_1 = require("./security.cjs");
+// ─── cmdAuditUat ─────────────────────────────────────────────────────────────
+function cmdAuditUat(cwd, raw) {
+    const phasesDir = node_path_1.default.join(planningDir(cwd), 'phases');
+    if (!node_fs_1.default.existsSync(phasesDir)) {
+        error('No phases directory found in planning directory');
+    }
+    const isDirInMilestone = getMilestonePhaseFilter(cwd);
+    const results = [];
+    // Scan all phase directories
+    const dirs = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true })
+        .filter(e => e.isDirectory())
+        .map(e => e.name)
+        .filter(isDirInMilestone)
+        .sort();
+    for (const dir of dirs) {
+        const phaseMatch = dir.match(/^(\d+[A-Z]?(?:\.\d+)*)/i);
+        const phaseNum = phaseMatch ? phaseMatch[1] : dir;
+        const phaseDir = node_path_1.default.join(phasesDir, dir);
+        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 items = parseUatItems(content);
+            if (items.length > 0) {
+                results.push({
+                    phase: phaseNum,
+                    phase_dir: dir,
+                    file,
+                    file_path: toPosixPath(node_path_1.default.relative(cwd, node_path_1.default.join(phaseDir, file))),
+                    type: 'uat',
+                    status: (extractFrontmatter(content).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';
+            if (status === 'human_needed' || status === 'gaps_found') {
+                const items = parseVerificationItems(content, status);
+                if (items.length > 0) {
+                    results.push({
+                        phase: phaseNum,
+                        phase_dir: dir,
+                        file,
+                        file_path: toPosixPath(node_path_1.default.relative(cwd, node_path_1.default.join(phaseDir, file))),
+                        type: 'verification',
+                        status,
+                        items,
+                    });
+                }
+            }
+        }
+    }
+    // Compute summary
+    const summary = {
+        total_files: results.length,
+        total_items: results.reduce((sum, r) => sum + r.items.length, 0),
+        by_category: {},
+        by_phase: {},
+    };
+    for (const r of results) {
+        if (!summary.by_phase[r.phase])
+            summary.by_phase[r.phase] = 0;
+        for (const item of r.items) {
+            summary.by_phase[r.phase]++;
+            const cat = item.category || 'unknown';
+            summary.by_category[cat] = (summary.by_category[cat] || 0) + 1;
+        }
+    }
+    output({ results, summary }, raw, undefined);
+}
+// ─── cmdRenderCheckpoint ──────────────────────────────────────────────────────
+function cmdRenderCheckpoint(cwd, options = {}, raw) {
+    const filePath = options.file;
+    if (!filePath) {
+        error('UAT file required: use uat render-checkpoint --file <path>');
+    }
+    const resolvedPath = (0, security_cjs_1.requireSafePath)(filePath, cwd, 'UAT file', { allowAbsolute: true });
+    if (!node_fs_1.default.existsSync(resolvedPath)) {
+        error(`UAT file not found: ${filePath}`);
+    }
+    const content = node_fs_1.default.readFileSync(resolvedPath, 'utf-8');
+    const currentTest = parseCurrentTest(content);
+    if (currentTest.complete) {
+        error('UAT session is already complete; no pending checkpoint to render');
+    }
+    const checkpoint = buildCheckpoint(currentTest);
+    output({
+        file_path: toPosixPath(node_path_1.default.relative(cwd, resolvedPath)),
+        test_number: currentTest.number,
+        test_name: currentTest.name,
+        checkpoint,
+    }, raw, checkpoint);
+}
+// ─── parseCurrentTest ─────────────────────────────────────────────────────────
+function parseCurrentTest(content) {
+    const currentTestMatch = content.match(/##\s*Current Test\s*(?:\n<!--[\s\S]*?-->)?\n([\s\S]*?)(?=\n##\s|$)/i);
+    if (!currentTestMatch) {
+        error('UAT file is missing a Current Test section');
+    }
+    const section = currentTestMatch[1].trimEnd();
+    if (!section.trim()) {
+        error('Current Test section is empty');
+    }
+    if (/\[testing complete\]/i.test(section)) {
+        return { complete: true };
+    }
+    const numberMatch = section.match(/^number:\s*(\d+)\s*$/m);
+    const nameMatch = section.match(/^name:\s*(.+)\s*$/m);
+    const expectedBlockMatch = section.match(/^expected:\s*\|\n([\s\S]*?)(?=^\w[\w-]*:\s)/m)
+        || section.match(/^expected:\s*\|\n([\s\S]+)/m);
+    const expectedInlineMatch = section.match(/^expected:\s*(.+)\s*$/m);
+    if (!numberMatch || !nameMatch || (!expectedBlockMatch && !expectedInlineMatch)) {
+        error('Current Test section is malformed');
+    }
+    let expected;
+    if (expectedBlockMatch) {
+        expected = expectedBlockMatch[1]
+            .split('\n')
+            .map((line) => line.replace(/^ {2}/, ''))
+            .join('\n')
+            .trim();
+    }
+    else {
+        expected = expectedInlineMatch[1].trim();
+    }
+    return {
+        complete: false,
+        number: parseInt(numberMatch[1], 10),
+        name: (0, security_cjs_1.sanitizeForDisplay)(nameMatch[1].trim()),
+        expected: (0, security_cjs_1.sanitizeForDisplay)(expected),
+    };
+}
+// ─── buildCheckpoint ──────────────────────────────────────────────────────────
+function buildCheckpoint(currentTest) {
+    return [
+        '╔══════════════════════════════════════════════════════════════╗',
+        '║  CHECKPOINT: Verification Required                           ║',
+        '╚══════════════════════════════════════════════════════════════╝',
+        '',
+        `**Test ${currentTest.number}: ${currentTest.name}**`,
+        '',
+        currentTest.expected,
+        '',
+        '──────────────────────────────────────────────────────────────',
+        'Type `pass` or describe what\'s wrong.',
+        '──────────────────────────────────────────────────────────────',
+    ].join('\n');
+}
+// ─── parseUatItems ────────────────────────────────────────────────────────────
+function parseUatItems(content) {
+    const items = [];
+    // Match test blocks: ### N. Name\nexpected: ...\nresult: ...\n
+    // Accept both bare (result: pending) and bracketed (result: [pending]) formats (#2273)
+    const testPattern = /###\s*(\d+)\.\s*([^\n]+)\nexpected:\s*([^\n]+)\nresult:\s*\[?(\w+)\]?(?:\n(?:reported|reason|blocked_by):\s*[^\n]*)?/g;
+    let match;
+    while ((match = testPattern.exec(content)) !== null) {
+        const [, num, name, expected, result] = match;
+        if (result === 'pending' || result === 'skipped' || result === 'blocked') {
+            // Extract optional fields — limit to current test block (up to next ### or EOF)
+            const afterMatch = content.slice(match.index);
+            const nextHeading = afterMatch.indexOf('\n###', 1);
+            const blockText = nextHeading > 0 ? afterMatch.slice(0, nextHeading) : afterMatch;
+            const reasonMatch = blockText.match(/reason:\s*(.+)/);
+            const blockedByMatch = blockText.match(/blocked_by:\s*(.+)/);
+            const item = {
+                test: parseInt(num, 10),
+                name: name.trim(),
+                expected: expected.trim(),
+                result,
+                category: categorizeItem(result, reasonMatch?.[1], blockedByMatch?.[1]),
+            };
+            if (reasonMatch)
+                item.reason = reasonMatch[1].trim();
+            if (blockedByMatch)
+                item.blocked_by = blockedByMatch[1].trim();
+            items.push(item);
+        }
+    }
+    return items;
+}
+// ─── parseVerificationItems ───────────────────────────────────────────────────
+function parseVerificationItems(content, status) {
+    const items = [];
+    if (status === 'human_needed') {
+        // Extract from human_verification section — look for numbered items or table rows
+        const hvSection = content.match(/##\s*Human Verification.*?\n([\s\S]*?)(?=\n##\s|\n---\s|$)/i);
+        if (hvSection) {
+            const lines = hvSection[1].split('\n');
+            for (const line of lines) {
+                // Match table rows: | N | description | ... |
+                const tableMatch = line.match(/\|\s*(\d+)\s*\|\s*([^|]+)/);
+                // Match bullet items: - description
+                const bulletMatch = line.match(/^[-*]\s+(.+)/);
+                // Match numbered items: 1. description
+                const numberedMatch = line.match(/^(\d+)\.\s+(.+)/);
+                if (tableMatch) {
+                    // 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));
+                    if (hasPassResult)
+                        continue;
+                    items.push({
+                        test: parseInt(tableMatch[1], 10),
+                        name: tableMatch[2].trim(),
+                        result: 'human_needed',
+                        category: 'human_uat',
+                    });
+                }
+                else if (numberedMatch) {
+                    items.push({
+                        test: parseInt(numberedMatch[1], 10),
+                        name: numberedMatch[2].trim(),
+                        result: 'human_needed',
+                        category: 'human_uat',
+                    });
+                }
+                else if (bulletMatch && bulletMatch[1].length > 10) {
+                    items.push({
+                        name: bulletMatch[1].trim(),
+                        result: 'human_needed',
+                        category: 'human_uat',
+                    });
+                }
+            }
+        }
+    }
+    // gaps_found items are already handled by plan-phase --gaps pipeline
+    return items;
+}
+// ─── categorizeItem ───────────────────────────────────────────────────────────
+function categorizeItem(result, reason, blockedBy) {
+    if (result === 'blocked' || blockedBy) {
+        if (blockedBy) {
+            if (/server/i.test(blockedBy))
+                return 'server_blocked';
+            if (/device|physical/i.test(blockedBy))
+                return 'device_needed';
+            if (/build|release|preview/i.test(blockedBy))
+                return 'build_needed';
+            if (/third.party|twilio|stripe/i.test(blockedBy))
+                return 'third_party';
+        }
+        return 'blocked';
+    }
+    if (result === 'skipped') {
+        if (reason) {
+            if (/server|not running|not available/i.test(reason))
+                return 'server_blocked';
+            if (/simulator|physical|device/i.test(reason))
+                return 'device_needed';
+            if (/build|release|preview/i.test(reason))
+                return 'build_needed';
+        }
+        return 'skipped_unresolved';
+    }
+    if (result === 'pending')
+        return 'pending';
+    if (result === 'human_needed')
+        return 'human_uat';
+    return 'unknown';
+}
+module.exports = {
+    cmdAuditUat,
+    cmdRenderCheckpoint,
+    parseCurrentTest,
+    buildCheckpoint,
+};

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

@@ -0,0 +1,98 @@
+"use strict";
+/**
+ * UI Safety Gate — shell-free implementation (ADR-457 build-at-publish: the
+ * hand-written bin/lib/ui-safety-gate.cjs collapsed to a TypeScript source of
+ * truth). Behaviour is preserved byte-for-behaviour from the prior hand-written
+ * .cjs; only types are added.
+ *
+ * Replaces the bash shell-based one-liner that silently degraded on Windows
+ * PowerShell / cmd.exe because the locale env-var prefix was not recognised.
+ * This module runs inside Node.js — no shell dependency, works identically
+ * on bash, Git-Bash, PowerShell, and cmd.exe.
+ *
+ * Word-boundary anchoring:
+ *   (^|[^a-zA-Z0-9])(TOKEN)([^a-zA-Z0-9]|$)
+ * Equivalent to POSIX ERE [^[:alnum:]] — matches tokens only when they are not
+ * interior substrings of alphanumeric compound words (e.g. "microfrontend" is NOT
+ * matched; "micro-frontend" and "micro frontend" ARE matched).
+ *
+ * Public API:
+ *   checkUiPresence(text: string): { hasUI: boolean, tokens: string[] }
+ *
+ * CLI usage — reads phase-section text from STDIN to avoid ARG_MAX limits:
+ *   echo "$PHASE_SECTION" | node gsd-core/bin/lib/ui-safety-gate.cjs
+ *   echo $?   → 0 if UI tokens found, 1 if not, 2 on usage error
+ *
+ * Exit codes mirror grep: 0 = match found, 1 = no match, 2 = usage error.
+ *
+ * Canonical location: gsd-core/bin/lib/ui-safety-gate.cjs (#448)
+ * This path is deployed by the GSD installer to $RUNTIME_DIR/gsd-core/bin/lib/.
+ * bin/lib/ui-safety-gate.cjs (root) is retained for source-repo and npm usage.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UI_TOKENS = void 0;
+exports.checkUiPresence = checkUiPresence;
+exports.UI_TOKENS = [
+    'UI',
+    'interface',
+    'frontend',
+    'component',
+    'layout',
+    'page',
+    'screen',
+    'view',
+    'form',
+    'dashboard',
+    'widget',
+];
+/**
+ * Built once at module load — no per-call compilation overhead.
+ * ASCII word boundaries — matches the original ASCII-grep intent of #3706.
+ * Note: JS [a-zA-Z0-9] is ASCII-only and NOT equivalent to POSIX [[:alnum:]],
+ * which is locale-sensitive and includes accented characters.
+ */
+const UI_GATE_PATTERN = new RegExp('(^|[^a-zA-Z0-9])(' + exports.UI_TOKENS.join('|') + ')([^a-zA-Z0-9]|$)', 'i');
+// Global-flagged variant for extracting ALL matches per line (matchAll).
+const UI_GATE_PATTERN_GLOBAL = new RegExp(UI_GATE_PATTERN.source, 'gi');
+/**
+ * Check a roadmap phase section string for frontend UI indicators.
+ *
+ * @param text - The roadmap phase section content (may be multi-line, CRLF or LF).
+ * @returns hasUI — true if any UI token was matched as a standalone word;
+ *          tokens — matched token strings (lowercased), deduplicated.
+ */
+function checkUiPresence(text) {
+    if (typeof text !== 'string') {
+        return { hasUI: false, tokens: [] };
+    }
+    // Normalise CRLF so the pattern sees consistent line boundaries.
+    const normalised = text.replace(/\r\n/g, '\n');
+    const found = new Set();
+    for (const line of normalised.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());
+        }
+    }
+    return { hasUI: found.size > 0, tokens: [...found] };
+}
+// ── CLI entry point ─────────────────────────────────────────────────────────
+// Reads phase-section text from STDIN (not argv) to avoid OS ARG_MAX limits.
+// Invoked by workflow .md bash blocks as: echo "$PHASE_SECTION" | node .../ui-safety-gate.cjs
+// Exit 0 = UI found, 1 = no UI, 2 = startup error.
+if (require.main === module) {
+    // Collect stdin chunks asynchronously.
+    const chunks = [];
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (chunk) => chunks.push(chunk));
+    process.stdin.on('end', () => {
+        const input = chunks.join('');
+        const result = checkUiPresence(input);
+        process.exit(result.hasUI ? 0 : 1);
+    });
+    process.stdin.on('error', (err) => {
+        process.stderr.write(`ERROR: ui-safety-gate.cjs stdin read failed: ${err.message}\n`);
+        process.exit(2);
+    });
+}