@opengsd/gsd-core 1.14.0 → 1.16.0

package/gsd-core/bin/lib/gate-schema-drift.cjs

@@ -0,0 +1,165 @@
+"use strict";
+/**
+ * `check verify-schema-drift` as a gate module (#5219, epic #5056, ADR-5057 §4 closing arm C): it
+ * returns a `GateResult`; the command router formats it. Imports no io module and performs no direct
+ * console/stdout/stderr write (ESLint-enforced).
+ *
+ * The `drift` capability's blocking gate at `execute:wave:post`. It reports schema-relevant files the
+ * phase's plans declare in `files_modified` for which no database push is evidenced in the phase's
+ * summaries or its own commit subjects (`checkSchemaDrift`, `schema-detect.cjs`).
+ *
+ * Dispatched gate, payload exit mode: the verdict is read from stdout (`.block`) and a non-zero exit
+ * is "the check command failed" (gsd-core/workflows/execute-phase/steps/wave-post-gate-hooks.md step
+ * 1; gsd-core/references/loop-hook-dispatch.md "a gate verb never exits non-zero to say blocked";
+ * capabilities/drift declares schema-drift `blocking: true, onError: skip`). A blocking verdict is
+ * therefore exit 0 and "could not look" is exit 69 (#5170); the router declares both.
+ *
+ * Non-blocking contract: a throw anywhere yields a non-blocking `unreadable` verdict, never a crash.
+ *
+ * Argv after the verb: `<phase>`. The bypass (`GSD_SKIP_SCHEMA_CHECK=true`) arrives as `env`, read by
+ * the router from the process environment; the gate reads no ambient state for it.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluateSchemaDriftGate = evaluateSchemaDriftGate;
+const node_path_1 = __importDefault(require("node:path"));
+const gate_verdict_cjs_1 = require("./gate-verdict.cjs");
+const gate_evidence_cjs_1 = require("./gate-evidence.cjs");
+const gate_evaluation_scope_cjs_1 = require("./gate-evaluation-scope.cjs");
+const schema_detect_cjs_1 = require("./schema-detect.cjs");
+const gate_phase_context_cjs_1 = require("./gate-phase-context.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- planning-workspace.cjs is an export= CommonJS module
+const planningWorkspace = require("./planning-workspace.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- plan-document.cjs is an export= CommonJS module
+const planDocumentMod = require("./plan-document.cjs");
+const { planningDir } = planningWorkspace;
+const { parsePlanDocument } = planDocumentMod;
+/**
+ * The schema-drift verdict for "drift was not evaluated" (#5170): non-blocking payload (the
+ * gate's non-blocking contract), outcome `unreadable` so the exit status says "could not look".
+ */
+function schemaDriftUnreadable(message, detail) {
+    return (0, gate_verdict_cjs_1.gateUnreadable)(false, {
+        block: false,
+        drift_detected: false,
+        blocking: false,
+        ...(detail === undefined ? {} : { unreadable: true, unreadable_file: detail.file, read_error: detail.reason }),
+        message,
+    });
+}
+function runSchemaDriftGate(cwd, phaseArg, skipFlag) {
+    const pDir = planningDir(cwd);
+    const phasesDir = node_path_1.default.join(pDir, 'phases');
+    // An ABSENT phases directory is the documented "nothing to check" (`none`); one that cannot be
+    // examined (an EACCES on a parent — `fs.existsSync` said `false` for it) is `unreadable`.
+    const phasesRoot = (0, gate_evidence_cjs_1.statEvidence)(phasesDir);
+    if (phasesRoot.kind === 'unreadable') {
+        return schemaDriftUnreadable(`schema-drift could not examine ${phasesDir} (${phasesRoot.reason}); drift was not evaluated`, { file: phasesDir, reason: phasesRoot.reason });
+    }
+    if (phasesRoot.kind === 'none') {
+        return (0, gate_verdict_cjs_1.gateVerdict)('skip', false, { block: false, drift_detected: false, blocking: false, message: 'No phases directory' });
+    }
+    // Resolve the phase directory with the canonical phase-directory matcher
+    // (phase-id.cjs::matchPhaseDirs), not a naive substring test. A bare
+    // `.includes(phaseArg)` lets a non-existent phase silently match a different
+    // phase whose directory name merely contains the requested token (e.g. "1"
+    // matching "11-expansion"), making the drift gate inspect the wrong phase.
+    // This shares the one selection rule with find-phase / verify
+    // phase-completeness rather than restating it. (#1571, #2528)
+    const phaseDir = (0, gate_phase_context_cjs_1.resolvePhaseDirByToken)(phasesDir, phaseArg);
+    if (!phaseDir) {
+        // An unresolvable phase is "could not look" (#5170): there is no phase directory to evaluate.
+        return schemaDriftUnreadable(`Phase directory not found: ${phaseArg}`);
+    }
+    // #3183: canonical LIVE plan/summary sets (root+nested,
+    // status: superseded EXCLUDED) from the single owner, rather than a
+    // root-only readdirSync filter — a superseded plan's claimed
+    // files_modified is no longer treated as an expected drift target, and
+    // nested (#3139 layout) plans/summaries are no longer invisible to the
+    // drift check.
+    // A scan that did not see every plan (an existing nested plans/ that could not be read) is
+    // `unreadable`, never a short plan set: the files_modified of the plans it missed are drift targets.
+    const planScan = (0, gate_evidence_cjs_1.readPlanScanEvidence)(phaseDir);
+    if (planScan.kind === 'unreadable' && !skipFlag) {
+        return schemaDriftUnreadable(`schema-drift could not scan the plans of ${phaseDir} (${planScan.reason}); drift was not evaluated`, { file: phaseDir, reason: planScan.reason });
+    }
+    const { planFiles, summaryFiles } = planScan.kind === 'found' ? planScan.value : { planFiles: [], summaryFiles: [] };
+    // #5170 (ADR-5057 §4): every read here is typed evidence. A file that cannot be read is
+    // `unreadable` and is reported as such — it is never "no files, so no drift". A file that
+    // vanished since the scan (`none`) contributes nothing.
+    let unreadableRead = null;
+    const allFiles = [];
+    for (const pf of planFiles) {
+        const read = (0, gate_evidence_cjs_1.readTextEvidence)(node_path_1.default.join(phaseDir, pf));
+        if (read.kind === 'unreadable') {
+            unreadableRead = unreadableRead ?? { file: pf, reason: read.reason };
+            continue;
+        }
+        if (read.kind === 'none')
+            continue;
+        // `files_modified` through the Frontmatter Module (the read phase-plan-index uses via
+        // RawPlan.filesModified): block sequences, inline arrays and CRLF all yield their files.
+        for (const file of parsePlanDocument(read.value).filesModified) {
+            const trimmed = file.trim();
+            if (trimmed)
+                allFiles.push(trimmed);
+        }
+    }
+    let executionLog = '';
+    for (const sf of summaryFiles) {
+        const read = (0, gate_evidence_cjs_1.readTextEvidence)(node_path_1.default.join(phaseDir, sf));
+        if (read.kind === 'unreadable') {
+            unreadableRead = unreadableRead ?? { file: sf, reason: read.reason };
+            continue;
+        }
+        if (read.kind === 'found')
+            executionLog += read.value + '\n';
+    }
+    // `--skip` (GSD_SKIP_SCHEMA_CHECK) bypasses the gate, so what could not be read is moot then.
+    if (unreadableRead !== null && !skipFlag) {
+        return schemaDriftUnreadable(`schema-drift could not read ${unreadableRead.file} (${unreadableRead.reason}); drift was not evaluated`, { file: unreadableRead.file, reason: unreadableRead.reason });
+    }
+    // #5164: the phase's own commits from the evaluation-scope resolver (ADR-5057 §4) — the former
+    // `git log --all -50` let a commit on ANY branch, from ANY phase, put a schema push in the log.
+    const phaseScope = (0, gate_evaluation_scope_cjs_1.resolveEvaluationScope)(cwd, { kind: 'phase', phase: phaseArg, phaseDir }, { includeFiles: false });
+    if (phaseScope.commits.length > 0) {
+        // Subjects only, as the `git log --oneline` it replaces: a quoted push command in a commit BODY must not change the verdict.
+        executionLog += '\n' + phaseScope.commits.map((c) => `${c.sha.slice(0, 7)} ${c.subject}`).join('\n');
+    }
+    const result = (0, schema_detect_cjs_1.checkSchemaDrift)(allFiles, executionLog, { skipCheck: skipFlag });
+    const isSkipped = !!result['skipped'];
+    // Uniform gate contract: `block` = true means "this gate's bad condition is met".
+    // When skipCheck is true (GSD_SKIP_SCHEMA_CHECK=true), the gate is bypassed —
+    // block must be false regardless of whether drift was detected.
+    // drift_detected and blocking are kept for compatibility.
+    const block = isSkipped ? false : !!result['driftDetected'];
+    return (0, gate_verdict_cjs_1.gateVerdict)(isSkipped ? 'skip' : (block ? 'block' : 'pass'), block, {
+        block,
+        drift_detected: result['driftDetected'],
+        blocking: result['blocking'],
+        schema_files: result['schemaFiles'],
+        orms: result['orms'],
+        unpushed_orms: result['unpushedOrms'],
+        message: result['message'],
+        skipped: isSkipped,
+    });
+}
+function evaluateSchemaDriftGate(input) {
+    const phaseArg = input.args[0] || '';
+    if (!phaseArg) {
+        // UNKNOWN: the pre-move `error('Usage…')` named no reason, and the reason is observable (#5219).
+        return (0, gate_verdict_cjs_1.gateUsageFailure)(gate_verdict_cjs_1.GATE_FAILURE_CODE.UNKNOWN, 'Usage: verify schema-drift <phase> [--skip]');
+    }
+    const skipFlag = input.env?.['GSD_SKIP_SCHEMA_CHECK'] === 'true';
+    // Non-blocking contract: a throw anywhere yields a non-blocking payload, never a crash.
+    try {
+        return runSchemaDriftGate(input.projectDir, phaseArg, skipFlag);
+    }
+    catch (err) {
+        // #5170: a gate that threw did not evaluate drift. The payload stays non-blocking (the contract
+        // above), but the exit status says "could not look" (UNAVAILABLE) instead of a clean exit 0.
+        return schemaDriftUnreadable('exception: ' + (err instanceof Error ? err.message : String(err)));
+    }
+}

package/gsd-core/bin/lib/gate-tdd-red-evidence.cjs

@@ -0,0 +1,100 @@
+"use strict";
+/**
+ * `check tdd-red-evidence` as a gate module (#5139, epic #5056, ADR-5057 §4 first bullet, #3770):
+ * it returns a `GateResult`; the command router formats it. Imports no io module and performs no
+ * direct console/stdout/stderr write (ESLint-enforced).
+ *
+ * Validates a persisted RED-phase test-run record for a `type: tdd` plan. Only an INTENTIONAL
+ * failure of the target test (verdict RED_EVIDENCE_OK) may authorize GREEN; zero-test discovery,
+ * fixture/load crashes, nonzero exits without a failing test, unrelated failures, and unexpected
+ * greens are INVALID_RED and block GREEN. The record is the JSON the executor persists after
+ * running the RED command: `{ command, exitCode, output, targetTest, targetFile?, expected?,
+ * actual? }`. Fail-closed: a missing/unreadable/unparseable record is INVALID_RED (reason
+ * `unreadable_record`), never a pass.
+ *
+ * Argv after the verb: `<record.json>`. The record path resolves against the PROCESS cwd
+ * (`path.resolve`), as before the move, and must then stay INSIDE the project directory (realpath
+ * containment, ADR-4650) BEFORE anything is read: a record path that escapes it is the usage
+ * failure `path escapes its allowed directory: <arg>`, so the gate cannot be made to read — and
+ * echo the fields of — an arbitrary readable file (#5139 security review). The path echoed in the
+ * payload stays the resolved (not realpath'd) form, unchanged.
+ *
+ * Consequence of resolving against the process cwd: the CLI runs with cwd === projectDir in every
+ * workflow, so a project-relative path (`r.json`) works. Invoked with cwd !== projectDir, that same
+ * relative path resolves outside the project and is the usage failure above (it was an
+ * `unreadable_record` verdict before containment); an absolute path inside the project works from
+ * any cwd.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluateTddRedEvidence = evaluateTddRedEvidence;
+const node_path_1 = __importDefault(require("node:path"));
+const security_cjs_1 = require("./security.cjs");
+const gate_verdict_cjs_1 = require("./gate-verdict.cjs");
+const gate_evidence_cjs_1 = require("./gate-evidence.cjs");
+const tdd_red_evidence_cjs_1 = require("./tdd-red-evidence.cjs");
+/** Parse the persisted record. A parse failure is typed evidence (never a swallowed `null`). */
+function parseRecordEvidence(text, span) {
+    try {
+        return (0, gate_evidence_cjs_1.evidenceFound)((JSON.parse(text) ?? {}));
+    }
+    catch (err) {
+        return (0, gate_evidence_cjs_1.evidenceFromError)(err, span);
+    }
+}
+function evaluateTddRedEvidence(input) {
+    const recordPath = typeof input.args[0] === 'string' ? input.args[0] : '';
+    if (!recordPath) {
+        return (0, gate_verdict_cjs_1.gateUsageFailure)(gate_verdict_cjs_1.GATE_FAILURE_CODE.SDK_MISSING_ARG, 'tdd-red-evidence requires a record path: check tdd-red-evidence <record.json>');
+    }
+    const resolved = node_path_1.default.resolve(recordPath);
+    // Containment BEFORE the read (the read follows symlinks, so it is decided on the resolved
+    // target). Only the verdict of the predicate is used; the echoed path stays `resolved`.
+    if ((0, security_cjs_1.tryWithinRoot)(resolved, input.projectDir, security_cjs_1.PathAcceptance.AbsoluteInsideRoot) === null) {
+        return (0, gate_verdict_cjs_1.gateUsageFailure)(gate_verdict_cjs_1.GATE_FAILURE_CODE.USAGE, `path escapes its allowed directory: ${recordPath}`);
+    }
+    const read = (0, gate_evidence_cjs_1.readTextEvidence)(resolved);
+    const text = read.kind === 'found' ? read.value : '';
+    const parsed = text ? parseRecordEvidence(text, resolved) : null;
+    // Malformed JSON is content that WAS read: it is a failing record (`block`), not a swallowed error.
+    const record = parsed !== null && parsed.kind === 'found' ? parsed.value : null;
+    if (!record) {
+        const payload = {
+            passed: false,
+            block: true,
+            verdict: 'INVALID_RED',
+            reason: 'unreadable_record',
+            record: resolved,
+            readError: text ? `record is not valid JSON: ${resolved}` : `record not found or unreadable: ${resolved}`,
+        };
+        // Fail-closed policy is unchanged (`block: true`); a record that exists but could not be read
+        // is "could not look" (#5170), so its outcome is `unreadable` and the exit status follows it.
+        return read.kind === 'unreadable' ? (0, gate_verdict_cjs_1.gateUnreadable)(true, payload) : (0, gate_verdict_cjs_1.gateVerdict)('block', true, payload);
+    }
+    const evidenceInput = {
+        command: record['command'],
+        exitCode: record['exitCode'],
+        output: record['output'],
+        targetTest: record['targetTest'],
+        targetFile: record['targetFile'],
+        expected: record['expected'],
+        actual: record['actual'],
+    };
+    const result = (0, tdd_red_evidence_cjs_1.classifyRedEvidence)(evidenceInput);
+    const built = (0, tdd_red_evidence_cjs_1.buildRedEvidenceRecord)(evidenceInput, result);
+    const ok = result.verdict === 'RED_EVIDENCE_OK';
+    // Uniform gate contract: block = !passed. INVALID_RED blocks GREEN.
+    return (0, gate_verdict_cjs_1.gateVerdict)(ok ? 'pass' : 'block', !ok, {
+        passed: ok,
+        block: !ok,
+        verdict: result.verdict,
+        reason: result.reason,
+        evidence: result.evidence,
+        record: built,
+        message: ok
+            ? `RED evidence verified: target test "${result.evidence.target_test}" failed as expected (exit ${result.evidence.exit_code}). GREEN authorized.`
+            : `INVALID_RED (${result.reason}): GREEN blocked. Fix the RED phase — only an intentional failure of target test "${result.evidence.target_test}" authorizes production edits.`,
+    });
+}

package/gsd-core/bin/lib/gate-tdd-review-checkpoint.cjs

@@ -0,0 +1,182 @@
+"use strict";
+/**
+ * `check tdd-review-checkpoint` as a gate module (#5139, epic #5056, ADR-5057 §4 first bullet): it
+ * returns a `GateResult`; the command router formats it. Imports no io module and performs no
+ * direct console/stdout/stderr write (ESLint-enforced).
+ *
+ * End-of-phase advisory check: scans `type: tdd` plans for RED/GREEN/REFACTOR gate-sequence
+ * compliance (`test(<plan>):` / `feat(<plan>):` / `refactor(<plan>):` commits) and builds a review
+ * table. `passed` is always true (advisory — never truly blocks); `block` is `violations > 0` so
+ * the host loop can read one uniform field.
+ *
+ * `type: tdd` is detected by the Frontmatter Module's `frontmatterKeyHasValue` (the old
+ * `^type:\s*tdd\s*$` multiline test over the fence owner's block, key and value escaped).
+ *
+ * A plan's commits come from the evaluation-scope resolver (#5164, ADR-5057 §4): the commits
+ * reachable from HEAD whose SUBJECT is `<type>(<phase>-<plan>):`, anchored and zero-padding
+ * tolerant. A plan id that is not `<phase>-<plan>` (a plan named `.*-PLAN.md`) matches nothing,
+ * and a git failure is "no commits" exactly as before.
+ *
+ * Argv after the verb: `<phase>` (a number; an unresolvable phase reports zero plans).
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluateTddReviewCheckpoint = evaluateTddReviewCheckpoint;
+const node_path_1 = __importDefault(require("node:path"));
+const gate_verdict_cjs_1 = require("./gate-verdict.cjs");
+const gate_phase_context_cjs_1 = require("./gate-phase-context.cjs");
+const gate_evidence_cjs_1 = require("./gate-evidence.cjs");
+const gate_evaluation_scope_cjs_1 = require("./gate-evaluation-scope.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const frontmatterMod = require("./frontmatter.cjs");
+const { frontmatterKeyHasValue } = frontmatterMod;
+/**
+ * True when the plan's frontmatter declares `type: tdd` (CRLF included, #2449). The block is the
+ * one fence owner's, read as RAW text — not through the YAML parser — so a block the parser refuses
+ * (a `--- x` line before `type:`) still classifies, exactly as under the old `^type:\s*tdd\s*$`
+ * multiline regex, whose edge behaviour (a duplicate `type:` key, a value on the next line,
+ * `type : tdd` NOT matching, `type: "tdd"` / `type: tdd # note` NOT matching) is preserved.
+ */
+function isTddPlan(content) {
+    return frontmatterKeyHasValue(content, 'type', 'tdd');
+}
+/**
+ * The commit types (`test`, `feat`, `refactor`, …) among the plan's own commits — those that
+ * touched at least one path (`pathspecs: ['.']`, as the old `git log -- .` lookup did). An
+ * unresolvable scope (git unavailable, an id that is not `<phase>-<plan>`) is "no commits".
+ */
+function planCommitKinds(projectDir, planId) {
+    const scope = (0, gate_evaluation_scope_cjs_1.resolveEvaluationScope)(projectDir, { kind: 'plan', planId }, { pathspecs: ['.'], commitsOnly: true });
+    const kinds = new Set();
+    for (const commit of scope.commits) {
+        const kind = /^([a-z]+)\(/.exec(commit.subject)?.[1];
+        if (kind)
+            kinds.add(kind);
+    }
+    return kinds;
+}
+/**
+ * The verdict when the review could not read a plan or the phase directory. Advisory policy is
+ * unchanged (`block: false`); the outcome is `unreadable` (exit UNAVAILABLE) and `passed` is false
+ * because nothing was certified.
+ */
+function unreadableReview(phase, tddPlans, unreadable) {
+    const names = unreadable.map((u) => `${u.source} (${u.reason})`).join(', ');
+    return (0, gate_verdict_cjs_1.gateUnreadable)(false, {
+        block: false,
+        passed: false,
+        tddPlans,
+        violations: 0,
+        table: '',
+        rows: [],
+        unreadable,
+        message: `TDD review could not read: ${names}. Phase ${phase} was not reviewed.`,
+    });
+}
+function evaluateTddReviewCheckpoint(input) {
+    const { projectDir } = input;
+    const phase = input.args[0] || '';
+    if (!phase) {
+        return (0, gate_verdict_cjs_1.gateUsageFailure)(gate_verdict_cjs_1.GATE_FAILURE_CODE.SDK_MISSING_ARG, 'tdd.review-checkpoint requires a phase argument: check tdd.review-checkpoint <phase>');
+    }
+    // #5170 (ADR-5057 §4): an ABSENT phase directory is `none` (no plans, the skip below); anything
+    // that exists but cannot be read is `unreadable` and the verdict says so — an unreadable plan is
+    // never "not a TDD plan".
+    const located = (0, gate_phase_context_cjs_1.resolvePhaseDir)(projectDir, phase);
+    if (located.kind === 'unreadable') {
+        return unreadableReview(phase, 0, [{ source: `phase ${phase}`, reason: located.reason }]);
+    }
+    const phaseDir = located.kind === 'found' ? located.value : '';
+    // Find all PLAN.md files with type: tdd in frontmatter
+    const tddPlanFiles = [];
+    const unreadable = [];
+    if (phaseDir) {
+        const entries = (0, gate_evidence_cjs_1.readDirEvidence)(phaseDir);
+        if (entries.kind === 'unreadable') {
+            unreadable.push({ source: phaseDir, reason: entries.reason });
+        }
+        else if (entries.kind === 'found') {
+            // #3183: canonical plan set (root+nested, superseded-excluded) from the single owner. A scan
+            // that did not see every plan (an unreadable nested plans/) is `unreadable`, never a short list.
+            const planSet = (0, gate_evidence_cjs_1.readPlanSetEvidence)(phaseDir);
+            if (planSet.kind === 'unreadable') {
+                unreadable.push({ source: planSet.span ?? phaseDir, reason: planSet.reason });
+            }
+            else {
+                for (const file of planSet.value) {
+                    const planPath = node_path_1.default.join(phaseDir, file);
+                    const plan = (0, gate_evidence_cjs_1.readTextEvidence)(planPath);
+                    if (plan.kind === 'unreadable')
+                        unreadable.push({ source: planPath, reason: plan.reason });
+                    else if (plan.kind === 'found' && isTddPlan(plan.value))
+                        tddPlanFiles.push(planPath);
+                }
+            }
+        }
+    }
+    if (unreadable.length > 0)
+        return unreadableReview(phase, tddPlanFiles.length, unreadable);
+    if (tddPlanFiles.length === 0) {
+        return (0, gate_verdict_cjs_1.gateVerdict)('skip', false, {
+            // Uniform gate contract: block = violations > 0 (advisory; never truly blocks).
+            block: false,
+            passed: true,
+            tddPlans: 0,
+            violations: 0,
+            table: '',
+            rows: [],
+            message: `No type:tdd plans found in phase ${phase}. TDD review skipped.`,
+        });
+    }
+    // For each TDD plan, extract the plan ID (e.g. "01-02-PLAN.md" → "01-02") and check git log
+    const rows = [];
+    for (const planPath of tddPlanFiles) {
+        const planId = node_path_1.default.basename(planPath, '-PLAN.md');
+        const kinds = planCommitKinds(projectDir, planId);
+        const red = kinds.has('test');
+        const green = kinds.has('feat');
+        const refactor = kinds.has('refactor');
+        const missing = [];
+        if (!red)
+            missing.push('RED');
+        if (!green)
+            missing.push('GREEN');
+        const status = missing.length === 0 ? 'Pass' : 'FAIL';
+        rows.push({ planId, red, green, refactor, status, missing });
+    }
+    const violations = rows.filter(r => r.status === 'FAIL').length;
+    // Build review table
+    const tableHeader = '| Plan | RED | GREEN | REFACTOR | Status |';
+    const tableDivider = '|------|-----|-------|----------|--------|';
+    const tableRows = rows.map(r => `| ${r.planId.padEnd(4)} | ${r.red ? ' ✓ ' : ' ✗ '} | ${r.green ? '  ✓  ' : '  ✗  '} | ${r.refactor ? '   ✓    ' : '   —    '} | ${r.status.padEnd(6)} |`);
+    let table = [
+        `### TDD REVIEW — Phase ${phase}`,
+        '',
+        `TDD Plans: ${tddPlanFiles.length} | Gate violations: ${violations}`,
+        '',
+        tableHeader,
+        tableDivider,
+        ...tableRows,
+    ].join('\n');
+    if (violations > 0) {
+        table += '\n\n⚠ Gate violations are advisory — review before advancing.';
+        for (const r of rows.filter(row => row.status === 'FAIL')) {
+            table += `\n  Plan ${r.planId} missing: ${r.missing.join(', ')} gate commit(s).`;
+            table += `\n  Expected commit pattern: test(${r.planId}): ... → feat(${r.planId}): ...`;
+        }
+    }
+    // Uniform gate contract: block = violations > 0. The gate is advisory (blocking:false in
+    // capability.json), so block:true only surfaces as a warning, never halts. The human-readable
+    // report is carried in `message` (and `table`) for the dispatch's advisory branch.
+    return (0, gate_verdict_cjs_1.gateVerdict)(violations > 0 ? 'advisory' : 'pass', violations > 0, {
+        block: violations > 0,
+        passed: true,
+        tddPlans: tddPlanFiles.length,
+        violations,
+        table,
+        rows,
+        message: table,
+    });
+}

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

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * `check ui-plan-gate` as a gate module (#5139, epic #5056, ADR-5057 §4 first bullet): it returns a
+ * `GateResult`; the command router formats it. Imports no io module and performs no direct
+ * console/stdout/stderr write (ESLint-enforced).
+ *
+ * Given a phase number, checks whether the phase has frontend indicators and whether a
+ * `*-UI-SPEC.md` already exists in the phase directory. Uses `checkUiPresence` from
+ * `ui-safety-gate.cjs` (frontend detection is not reimplemented) and the shared phase-context
+ * helpers for the ROADMAP lookup and the phase directory.
+ *
+ * Argv after the verb: `<phase>`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeUiPlanGate = computeUiPlanGate;
+exports.evaluateUiPlanGate = evaluateUiPlanGate;
+const gate_verdict_cjs_1 = require("./gate-verdict.cjs");
+const gate_phase_context_cjs_1 = require("./gate-phase-context.cjs");
+const ui_safety_gate_cjs_1 = require("./ui-safety-gate.cjs");
+const ui_frontend_evidence_cjs_1 = require("./ui-frontend-evidence.cjs");
+const gate_evidence_cjs_1 = require("./gate-evidence.cjs");
+/**
+ * Pure logic for ui-plan-gate — exposed for direct behavioral testing.
+ *
+ * Given a projectDir and phase number:
+ *   (a) Reads the phase section from ROADMAP.md via the two-pass lookup `roadmap.get-phase` uses
+ *       (current milestone → full roadmap). ROADMAP.md missing = project has no roadmap = cannot
+ *       be frontend. Phase absent from a present ROADMAP.md sets `phaseLookupFailed` so callers
+ *       can surface the miss — we do NOT silently degrade to frontend:false.
+ *   (b) Runs checkUiPresence (frontend detection).
+ *   (c) Resolves the phase directory; checks for *-UI-SPEC.md.
+ *
+ * `block = frontend && hasFrontendEvidence && !hasUiSpec` (#3312): `frontend` is a vocabulary
+ * signal only (a hyphen is a word boundary, so a repo named `dashboard-financeiro` matches the
+ * token `dashboard`; the boundary rule of #3718 is intentional), so the gate blocks only when the
+ * token match is corroborated by static frontend evidence in the repo tree
+ * (`hasStaticFrontendEvidence`). matchedToken/matchedLine surface what tripped the sniffer.
+ */
+function computeUiPlanGate(projectDir, phase) {
+    // (a) phase section text
+    const { phaseSection, phaseLookupFailed, readError: roadmapReadError } = (0, gate_phase_context_cjs_1.lookupRoadmapPhase)(projectDir, phase);
+    // (b) frontend detection — reuse the existing helper; no reimplementation
+    const presenceResult = (0, ui_safety_gate_cjs_1.checkUiPresence)(phaseSection);
+    const frontend = presenceResult.hasUI;
+    // (b') #3312 — static structural corroboration. Only probed when the sniffer matched. `unreadable`
+    // (#5170) is a manifest or tree the probe could not look at: absence of evidence is then not
+    // established, and the verdict says so (below) instead of reading it as "no frontend".
+    const frontendEvidence = frontend ? (0, ui_frontend_evidence_cjs_1.readStaticFrontendEvidence)(projectDir) : (0, gate_evidence_cjs_1.evidenceNone)();
+    const hasFrontendEvidence = frontendEvidence.kind === 'found';
+    // (c) phase directory and *-UI-SPEC.md. `none` is "no spec"; `unreadable` is "could not look"
+    // (#5170) and is carried to the verdict, never read as "no spec".
+    const uiSpec = (0, gate_phase_context_cjs_1.locateUiSpec)(projectDir, phase);
+    const uiSpecPath = uiSpec.kind === 'found' ? uiSpec.value : '';
+    const hasUiSpec = uiSpecPath !== '';
+    // Unreadable frontend evidence only matters when it could flip the verdict: with a UI-SPEC present the
+    // gate does not block whatever the tree holds.
+    const frontendReadError = frontendEvidence.kind === 'unreadable' && !hasUiSpec
+        ? `static frontend evidence could not be read (${frontendEvidence.reason})`
+        : undefined;
+    const readError = roadmapReadError ?? (uiSpec.kind === 'unreadable' ? uiSpec.reason : undefined) ?? frontendReadError;
+    // block = frontend phase with structural frontend evidence and no UI-SPEC (#3312)
+    const block = frontend && hasFrontendEvidence && !hasUiSpec;
+    const result = {
+        frontend, hasFrontendEvidence, hasUiSpec, block,
+        uiSpecPath: hasUiSpec ? uiSpecPath : null,
+        matchedToken: presenceResult.matchedToken,
+        matchedLine: presenceResult.matchedLine,
+    };
+    if (phaseLookupFailed)
+        result.phaseLookupFailed = true;
+    if (readError !== undefined)
+        result.readError = readError;
+    return result;
+}
+function evaluateUiPlanGate(input) {
+    const phase = input.args[0] || '';
+    if (!phase) {
+        return (0, gate_verdict_cjs_1.gateUsageFailure)(gate_verdict_cjs_1.GATE_FAILURE_CODE.SDK_MISSING_ARG, 'ui-plan-gate requires a phase argument: check ui-plan-gate <phase>');
+    }
+    const result = computeUiPlanGate(input.projectDir, phase);
+    // Evidence the gate could not read is "could not look", never a pass (ADR-5057 §4). `block` is
+    // the gate's own policy and is unchanged; the exit status follows the outcome.
+    if (result.readError !== undefined)
+        return (0, gate_verdict_cjs_1.gateUnreadable)(result.block, { ...result });
+    return (0, gate_verdict_cjs_1.gateVerdict)(result.block ? 'block' : 'pass', result.block, { ...result });
+}

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

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * `check ui-safety-gate` as a gate module (#5139, epic #5056, ADR-5057 §4 first bullet): it returns
+ * a `GateResult`; the command router formats it. Imports no io module and performs no direct
+ * console/stdout/stderr write (ESLint-enforced).
+ *
+ * Post-wave check that verifies UI-changed files conform to the active UI-SPEC for the phase.
+ * Uses `checkUiPresence` from `ui-safety-gate.cjs` (frontend detection is not reimplemented) and
+ * looks for frontend files in the phase's evaluation scope (#5164, ADR-5057 §4): the union of the
+ * phase's own commits' file sets from `gate-evaluation-scope`, not the last commit. A scope the
+ * resolver could not read, or had to widen, is reported (`scopeStatus` / `scopeReason`), never
+ * silently treated as "no UI files".
+ *
+ * Argv after the verb: `<phase>`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeUiSafetyGate = computeUiSafetyGate;
+exports.evaluateUiSafetyGate = evaluateUiSafetyGate;
+const gate_verdict_cjs_1 = require("./gate-verdict.cjs");
+const gate_phase_context_cjs_1 = require("./gate-phase-context.cjs");
+const gate_evaluation_scope_cjs_1 = require("./gate-evaluation-scope.cjs");
+const ui_safety_gate_cjs_1 = require("./ui-safety-gate.cjs");
+const UI_FILE_EXTENSIONS_RE = /\.(tsx|jsx|css|scss|sass|less|vue|svelte|html)$/i;
+const UI_PATH_PATTERNS_RE = /\/(components|pages|views|screens|layouts|ui|frontend)\//i;
+/**
+ * Pure logic for ui-safety-gate — exposed for direct behavioral testing.
+ *
+ *   (a) ROADMAP phase section via the shared lookup (same as ui-plan-gate) → is this a frontend phase.
+ *   (b) checkUiPresence (frontend detection).
+ *   (c) UI files among the phase's evaluation scope (`resolveEvaluationScope`, phase unit; every
+ *       git call is bounded by the resolver's seam; an unreadable scope is reported, not "clean").
+ *   (d) Phase directory → `*-UI-SPEC.md`.
+ *
+ * `block = frontend && hasUiFiles && !hasUiSpec`.
+ */
+function computeUiSafetyGate(projectDir, phase) {
+    // (a) phase section text (same two-pass lookup as computeUiPlanGate)
+    const { phaseSection, phaseLookupFailed, readError: roadmapReadError } = (0, gate_phase_context_cjs_1.lookupRoadmapPhase)(projectDir, phase);
+    // (b) frontend detection — reuse the existing helper; no reimplementation
+    const presenceResult = (0, ui_safety_gate_cjs_1.checkUiPresence)(phaseSection);
+    const frontend = presenceResult.hasUI;
+    // (c) any UI files in the phase's own commits? (deleted paths count: a removed component is a UI change)
+    const scope = (0, gate_evaluation_scope_cjs_1.resolveEvaluationScope)(projectDir, { kind: 'phase', phase });
+    const hasUiFiles = scope.changedFiles.some((f) => f.trim() && (UI_FILE_EXTENSIONS_RE.test(f) || UI_PATH_PATTERNS_RE.test(f)));
+    // (d) phase directory and *-UI-SPEC.md
+    // `none` is "no spec"; `unreadable` is "could not look" (#5170) and is carried to the verdict.
+    const uiSpec = (0, gate_phase_context_cjs_1.locateUiSpec)(projectDir, phase);
+    const hasUiSpec = uiSpec.kind === 'found';
+    const readError = roadmapReadError ?? (uiSpec.kind === 'unreadable' ? uiSpec.reason : undefined);
+    // block only when: this is a frontend phase AND UI files were changed AND no UI-SPEC exists
+    const block = frontend && hasUiFiles && !hasUiSpec;
+    const result = { frontend, hasUiFiles, hasUiSpec, block };
+    if (block) {
+        result.message = `UI files changed in this wave but no UI-SPEC.md exists for Phase ${phase}. ` +
+            `Run /gsd:ui-phase ${phase} to generate the design contract before continuing.`;
+    }
+    if (phaseLookupFailed)
+        result.phaseLookupFailed = true;
+    if (scope.status !== 'resolved') {
+        result.scopeStatus = scope.status;
+        result.scopeReason = scope.reason ?? '';
+    }
+    if (readError !== undefined)
+        result.readError = readError;
+    return result;
+}
+function evaluateUiSafetyGate(input) {
+    const phase = input.args[0] || '';
+    if (!phase) {
+        return (0, gate_verdict_cjs_1.gateUsageFailure)(gate_verdict_cjs_1.GATE_FAILURE_CODE.SDK_MISSING_ARG, 'ui-safety-gate requires a phase argument: check ui-safety-gate <phase>');
+    }
+    const result = computeUiSafetyGate(input.projectDir, phase);
+    // A scope the resolver could not read, or a ROADMAP / phase directory that could not be read, is
+    // "could not look", never a pass (ADR-5057 §4): the outcome is `unreadable` and the exit status
+    // follows it. `block` is the gate's own policy and is unchanged.
+    if (result.scopeStatus === 'unresolvable' || result.readError !== undefined) {
+        return (0, gate_verdict_cjs_1.gateUnreadable)(result.block, { ...result });
+    }
+    return (0, gate_verdict_cjs_1.gateVerdict)(result.block ? 'block' : 'pass', result.block, { ...result });
+}