@opengsd/gsd-core 1.18.0 → 1.20.0

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

@@ -34,7 +34,10 @@ const gate_phase_context_cjs_1 = require("./gate-phase-context.cjs");
 const planningWorkspace = require("./planning-workspace.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- verification.cjs is an export= CommonJS module
 const verificationMod = require("./verification.cjs");
-const { planningDir } = planningWorkspace;
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-id.cjs is an export= CommonJS module
+const phaseIdMod = require("./phase-id.cjs");
+const { scopeToPhase } = phaseIdMod;
+const { planningDir, isPhaseSpecFile, findPhaseSpecIn } = planningWorkspace;
 const { defaultPhaseCleanCommitTimesMs } = verificationMod;
 /**
  * Pure comparator: which of `entries` have an effective last-changed time
@@ -54,7 +57,7 @@ function buildContextDriftMessage(staleArtifacts, phaseArg, projectDir) {
     if (staleArtifacts.some((f) => f.endsWith('-PATTERNS.md'))) {
         parts.push(`Regenerate patterns: delete the PATTERNS.md file, then re-run ${(0, runtime_slash_cjs_1.runtimeCommand)(projectDir, 'plan-phase')}.`);
     }
-    if (staleArtifacts.some((f) => f.endsWith('-VALIDATION.md') || (f.endsWith('-SPEC.md') && !f.endsWith('-AI-SPEC.md') && !f.endsWith('-UI-SPEC.md')))) {
+    if (staleArtifacts.some((f) => f.endsWith('-VALIDATION.md') || isPhaseSpecFile(f))) {
         parts.push('Regenerate or manually reconcile VALIDATION.md / SPEC.md against the current decisions.');
     }
     parts.push('Do not hand-inject the newer decisions into a prompt as a substitute for regenerating — that carries the staleness forward.');
@@ -82,7 +85,7 @@ function runContextDriftGate(cwd, phaseArg) {
     }
     // Same phase-directory resolution rule the schema-drift gate uses (#1571, #2528):
     // matchPhaseDirs, never a naive substring test.
-    const phaseDir = (0, gate_phase_context_cjs_1.resolvePhaseDirByToken)(phasesDir, phaseArg);
+    const phaseDir = (0, gate_phase_context_cjs_1.resolvePhaseDirByToken)(cwd, phasesDir, phaseArg);
     if (!phaseDir) {
         return unresolvable();
     }
@@ -98,7 +101,9 @@ function runContextDriftGate(cwd, phaseArg) {
     const researchFile = phaseFiles.find((f) => f.endsWith('-RESEARCH.md'));
     const patternsFile = phaseFiles.find((f) => f.endsWith('-PATTERNS.md'));
     const validationFile = phaseFiles.find((f) => f.endsWith('-VALIDATION.md'));
-    const specFile = phaseFiles.find((f) => f.endsWith('-SPEC.md') && !f.endsWith('-AI-SPEC.md') && !f.endsWith('-UI-SPEC.md'));
+    // #5629: the shared phase-SPEC predicate (the init payloads' `has_spec` / `spec_path` use the same one).
+    // Scoped to this phase's own artifacts, as init scopes it, so a misfiled `02-SPEC.md` agrees in both.
+    const specFile = findPhaseSpecIn(scopeToPhase(phaseFiles, node_path_1.default.basename(phaseDir)));
     const upstreamFiles = [researchFile, patternsFile, validationFile, specFile].filter((f) => !!f);
     if (upstreamFiles.length === 0) {
         return skip('no-upstream-artifacts');

package/gsd-core/bin/lib/gate-decision-coverage-plan.cjs

@@ -163,7 +163,10 @@ function evaluateDecisionCoveragePlan(input) {
     if (phaseDir && planContents.value.length === 0) {
         return (0, gate_verdict_cjs_1.gateVerdict)('block', true, { passed: false, skipped: false, reason: 'phase directory holds no plans', total: null, covered: null, message: `Decision coverage gate: the phase directory "${positionals[0]}" holds no PLAN files, so no plans were scanned. Pass the phase DIRECTORY that holds the plans (e.g. .planning/phases/01-slug), not the phase number.` });
     }
-    const sections = planContents.value.map(decision_coverage_support_cjs_1.extractPlanDesignatedSections);
+    const tracker = (0, decision_coverage_support_cjs_1.resolveTrackerBodies)(projectDir, planContents.value, input.deps);
+    if (tracker.kind === 'unreadable')
+        return unreadableDecisionGate(`${tracker.span}: ${tracker.reason}`);
+    const sections = planContents.value.map((c, i) => (0, decision_coverage_support_cjs_1.extractPlanDesignatedSections)(c) + (tracker.value.bodies[i] ? '\n' + tracker.value.bodies[i] : ''));
     const uncovered = [];
     let covered = 0;
     for (const decision of decisions) {
@@ -172,6 +175,8 @@ function evaluateDecisionCoveragePlan(input) {
         else
             uncovered.push({ id: decision.id, text: decision.text, category: decision.category });
     }
+    if (uncovered.length > 0 && tracker.value.missingResolver)
+        return unreadableDecisionGate(`${tracker.value.missingResolver.span}: ${tracker.value.missingResolver.reason}`);
     const passed = uncovered.length === 0;
     return (0, gate_verdict_cjs_1.gateVerdict)(passed ? 'pass' : 'block', !passed, {
         passed,

package/gsd-core/bin/lib/gate-decision-coverage-verify.cjs

@@ -103,6 +103,9 @@ function evaluateDecisionCoverageVerify(input) {
     const planContents = (0, decision_coverage_support_cjs_1.loadPlanContents)(phaseDir);
     if (planContents.kind === 'unreadable')
         return unreadableVerify(`${planContents.span ?? phaseDir}: ${planContents.reason}`);
+    const tracker = (0, decision_coverage_support_cjs_1.resolveTrackerBodies)(projectDir, planContents.value, input.deps);
+    if (tracker.kind === 'unreadable')
+        return unreadableVerify(`${tracker.span}: ${tracker.reason}`);
     const summaryParts = (0, decision_coverage_support_cjs_1.loadSummaryContents)(phaseDir);
     if (summaryParts.kind === 'unreadable')
         return unreadableVerify(`${summaryParts.span ?? phaseDir}: ${summaryParts.reason}`);
@@ -115,7 +118,7 @@ function evaluateDecisionCoverageVerify(input) {
     if (modifiedFiles.kind === 'unreadable')
         return unreadableVerify(`${modifiedFiles.span ?? 'files_modified'}: ${modifiedFiles.reason}`);
     const haystack = [
-        planContents.value.join('\n\n'),
+        planContents.value.map((c, i) => c + (tracker.value.bodies[i] ? '\n' + tracker.value.bodies[i] : '')).join('\n\n'),
         summaryParts.value.join('\n\n'),
         modifiedFiles.value,
         (0, decision_coverage_support_cjs_1.phaseCommitMessages)(projectDir, phaseDir),
@@ -128,6 +131,8 @@ function evaluateDecisionCoverageVerify(input) {
         else
             notHonored.push({ id: decision.id, text: decision.text, category: decision.category });
     }
+    if (notHonored.length > 0 && tracker.value.missingResolver)
+        return unreadableVerify(`${tracker.value.missingResolver.span}: ${tracker.value.missingResolver.reason}`);
     return (0, gate_verdict_cjs_1.gateVerdict)(notHonored.length === 0 ? 'pass' : 'advisory', false, {
         skipped: false,
         blocking: false,

package/gsd-core/bin/lib/gate-evaluation-scope.cjs

@@ -35,9 +35,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MAX_COMMITS_CEILING = exports.SCOPE_EXCLUSION_PATHSPECS = void 0;
 exports.extractTaskCommitRefs = extractTaskCommitRefs;
+exports.qualifiedPlanSubjectPattern = qualifiedPlanSubjectPattern;
 exports.planSubjectPattern = planSubjectPattern;
 exports.isSafeRefArgument = isSafeRefArgument;
 exports.isSafeDateArgument = isSafeDateArgument;
+exports.commitIsAncestor = commitIsAncestor;
 exports.resolveEvaluationScope = resolveEvaluationScope;
 exports.evaluateEvaluationScope = evaluateEvaluationScope;
 const node_fs_1 = __importDefault(require("node:fs"));
@@ -46,6 +48,9 @@ const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs")
 const gate_verdict_cjs_1 = require("./gate-verdict.cjs");
 const gate_phase_context_cjs_1 = require("./gate-phase-context.cjs");
 const pattern_cjs_1 = require("./pattern.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planningWorkspaceMod = require("./planning-workspace.cjs");
+const { readScopedConfigValue } = planningWorkspaceMod;
 const gate_evidence_cjs_1 = require("./gate-evidence.cjs");
 // ─── Constants ────────────────────────────────────────────────────────────────
 /** Paths that are never part of a code-review or UI scope (planning artifacts, lockfiles). */
@@ -107,25 +112,124 @@ function paddedPattern(value) {
     const intPart = (m[1] ?? '').replace(/^0+(?=\d)/, '');
     return `0*${(0, pattern_cjs_1.escapeEre)(intPart)}${(0, pattern_cjs_1.escapeEre)(m[2] ?? '')}`;
 }
+/**
+ * The `<phase>-<plan>` fragment of a plan subject pattern, or null when `id` is not that shape.
+ *
+ * Zero-padding tolerant in both halves: `03-01` yields `0*3-0*1`, so `feat(03-01):`, `test(3-1):`
+ * and `fix(03-01)!:` match while `feat(03-010):` does not (#4003, #4619, #4748).
+ */
+function phasePlanPattern(id) {
+    const dash = id.indexOf('-');
+    const phasePart = dash > 0 ? id.slice(0, dash) : '';
+    const planPart = dash > 0 ? id.slice(dash + 1) : '';
+    if (/^[0-9A-Za-z.]+$/.test(phasePart) && /^[0-9A-Za-z.]+$/.test(planPart)) {
+        return `${paddedPattern(phasePart)}-${paddedPattern(planPart)}`;
+    }
+    return null;
+}
+/**
+ * The anchored subject pattern for a `<phase>-<plan>` ERE fragment, optionally behind one scope
+ * qualifier as the group `(<qualifier>-)?`.
+ *
+ * Every spelling of a plan id goes through this one builder: the bare id, the id carrying the
+ * configured project code (#5271), and the workstream-qualified id `<ws>-<phase>-<plan>` that #5177
+ * proposes. The qualifier is ERE-escaped, so a workstream name (a path segment, not a project-code
+ * token) is matched literally. The group is a real capture group, never `(?:…)`: the pattern goes
+ * to `git log --extended-regexp`, and POSIX ERE has no non-capturing group.
+ */
+function qualifiedPlanSubjectPattern(fragment, qualifier = null) {
+    const group = qualifier === null ? '' : `(${(0, pattern_cjs_1.escapeEre)(qualifier)}-)?`;
+    return `^[a-z]+\\(${group}${fragment}\\)!?:`;
+}
+/**
+ * The `<CODE>-` prefix of `planId` when it is EXACTLY the project's configured `project_code`
+ * followed by a dash — the separator included — else null.
+ *
+ * The match is CASE-SENSITIVE and anchored to the configured value. The phase-id module's
+ * `stripProjectCodePrefix` grammar (case-insensitive, any code before a digit) recognises ANY
+ * letter prefix, which is deliberately wider than the project: `AUTH-01-02` and `setup-1-2` are
+ * ids this project never assigned a code to, and stripping their prefixes made them resolve
+ * another plan's commits (#5271). Only the code the project actually configures may be
+ * stripped, so an id that merely LOOKS coded keeps its literal-match guarantee.
+ */
+function configuredCodePrefix(planId, projectCode) {
+    if (projectCode === null || !isUsableProjectCode(projectCode))
+        return null;
+    const prefix = `${projectCode}-`;
+    return planId.startsWith(prefix) ? prefix : null;
+}
 /**
  * The anchored subject pattern for a plan id, or null when `planId` is empty, over-long or carries a
  * control / whitespace character.
  *
  * A `<phase>-<plan>` id (`03-01`) is zero-padding tolerant: `feat(03-01):`, `test(3-1):` and
- * `fix(03-01)!:` match, `feat(03-010):` does not. Any other id (a plan FILE NAME that does not follow
- * the numbering) is matched LITERALLY — every ERE metacharacter escaped — so `x.*` or `a[b]` can only
- * match a commit that names that exact id, and never widens the pattern.
+ * `fix(03-01)!:` match, `feat(03-010):` does not. An id carrying the CONFIGURED project code
+ * (`PRJ-01-01` with `project_code: "PRJ"`, #5271) matches either spelling of the SAME plan —
+ * `feat(PRJ-01-01):` and `feat(01-01):` — because the two init verbs hand out different phase
+ * tokens for one plan. The code is stripped ONLY when it is the configured one: an id like
+ * `AUTH-01-02` or `setup-1-2`, which merely looks coded, is matched LITERALLY — every ERE
+ * metacharacter escaped — so it can only match a commit naming that exact id and never widens the
+ * pattern to another plan's commits. Any other id (a plan FILE NAME that does not follow the
+ * numbering) is matched literally for the same reason.
+ *
+ * `projectCode` is the project's configured `project_code`; with none (no config, no `planningDir`),
+ * every id is matched literally, which is the pre-#5271 behaviour.
  */
-function planSubjectPattern(planId) {
+function planSubjectPattern(planId, projectCode = null) {
     if (planId.length === 0 || planId.length > 200 || /[\s\x00-\x1f\x7f]/.test(planId))
         return null;
-    const dash = planId.indexOf('-');
-    const phasePart = dash > 0 ? planId.slice(0, dash) : '';
-    const planPart = dash > 0 ? planId.slice(dash + 1) : '';
-    if (/^[0-9A-Za-z.]+$/.test(phasePart) && /^[0-9A-Za-z.]+$/.test(planPart)) {
-        return `^[a-z]+\\(${paddedPattern(phasePart)}-${paddedPattern(planPart)}\\)!?:`;
+    const direct = phasePlanPattern(planId);
+    if (direct)
+        return qualifiedPlanSubjectPattern(direct);
+    // #5271: `init.execute-phase` returns `phase_number: "PRJ-01"` where `init.plan-phase` returns
+    // `padded_phase: "01"`, and every gate builds its `--plan` from the former. Splitting `PRJ-01-01`
+    // at its FIRST dash leaves `01-01` as the plan half, which is not a plan number, so the id fell
+    // through to the literal pattern that no executor commit can ever carry — an empty scope at exit
+    // 0, which is the correct answer for a plan that has NOT started and the wrong one for one that
+    // has. Retry on the CONFIGURED project-code-stripped id, with the code OPTIONAL so the commit the
+    // executor actually wrote still matches.
+    //
+    // The `(PRJ-)?` group comes from `qualifiedPlanSubjectPattern`, and it rides ONLY on a remainder
+    // that could be a plan number, so an empty or non-numeric remainder keeps the whole id literal —
+    // never WIDER than the pre-#5271 pattern.
+    const prefix = configuredCodePrefix(planId, projectCode);
+    if (prefix !== null) {
+        const stripped = planId.slice(prefix.length);
+        const coded = phasePlanPattern(stripped);
+        // The only remainder `phasePlanPattern` cannot split is the N-segment milestone shape
+        // (`01-02-03`), so require that whole shape: a bare `1`, `01-` or a trailing dash would
+        // otherwise widen the optional group onto `feat(1):`.
+        const planShaped = coded !== null || /^\d[0-9A-Za-z.]*(-[0-9A-Za-z.]+){2,}$/.test(stripped);
+        if (!planShaped)
+            return qualifiedPlanSubjectPattern((0, pattern_cjs_1.escapeEre)(planId));
+        return qualifiedPlanSubjectPattern(coded ?? (0, pattern_cjs_1.escapeEre)(stripped), projectCode);
     }
-    return `^[a-z]+\\(${(0, pattern_cjs_1.escapeEre)(planId)}\\)!?:`;
+    return qualifiedPlanSubjectPattern((0, pattern_cjs_1.escapeEre)(planId));
+}
+/**
+ * Whether a configured `project_code` can safely be stripped from a plan id and put in a pattern.
+ *
+ * `config-set` stores `project_code` unvalidated and docs/CONFIGURATION.md calls it "any short
+ * string", so this is a SAFETY check, not the phase-id module's uppercase grammar: a letter first,
+ * then letters, digits, `_`, `.` or `-`, at most 32 characters. That admits `gsd` and `AUTH-X`
+ * (which the uppercase grammar left in the #5271 symptom) while excluding whitespace, control
+ * characters and anything long enough to be a sentence. The value is ERE-escaped by the pattern
+ * builder, so no metacharacter it admits can change the pattern.
+ */
+function isUsableProjectCode(code) {
+    return /^[A-Za-z][A-Za-z0-9_.-]{0,31}$/.test(code);
+}
+/**
+ * The project's configured `project_code`, or null when it is absent, non-string or unusable
+ * (`isUsableProjectCode`). An unusable value reads as ABSENT: the coded id keeps its LITERAL
+ * spelling, which is never WIDER than the pre-#5271 pattern, since a literal id can only match a
+ * subject naming that exact id.
+ */
+function configuredProjectCode(projectDir) {
+    const { present, value } = readScopedConfigValue(projectDir, ['project_code']);
+    if (!present || typeof value !== 'string')
+        return null;
+    return isUsableProjectCode(value) ? value : null;
 }
 // ─── Git plumbing ─────────────────────────────────────────────────────────────
 class ScopeUnreadable extends Error {
@@ -189,6 +293,23 @@ function isSafeDateArgument(candidate) {
 function isAncestor(git, sha, of) {
     return gitOrNo(git, ['merge-base', '--is-ancestor', sha, of]) !== null;
 }
+/**
+ * Whether commit `sha` is an ancestor of commit `of` (#5275): ancestry, never log position or commit
+ * date, so a history merged from worktree branches is judged by what it descends from. `null` means
+ * git could not answer (missing, hung, a bad object): the caller must not read that as "no".
+ */
+function commitIsAncestor(projectDir, sha, of, execGit) {
+    if (!isSafeRefArgument(sha) || !isSafeRefArgument(of))
+        return null;
+    try {
+        return isAncestor(makeGit(projectDir, execGit ?? shell_command_projection_cjs_1.execGit), sha, of);
+    }
+    catch (error) {
+        if (error instanceof ScopeUnreadable)
+            return null;
+        throw error;
+    }
+}
 // ─── The resolver ─────────────────────────────────────────────────────────────
 function emptyScope(unit) {
     return {
@@ -210,7 +331,7 @@ function resolveEvaluationScope(projectDir, unit, options = {}) {
         if (unit.kind === 'phase')
             resolvePhase(projectDir, unit, scope, git, ref, options, repoRoot);
         else
-            resolveBySubject(unit, scope, git, ref, options, repoRoot);
+            resolveBySubject(projectDir, unit, scope, git, ref, options, repoRoot);
         return scope;
     }
     catch (error) {
@@ -388,7 +509,7 @@ function resolvePhase(projectDir, unit, scope, git, ref, options, repoRoot) {
     scope.commits = parseLog(git(['log', `${scope.rangeBase}..${ref}`, logFormat(options.includeBody === true), '-n', String(max)]), options.includeBody === true);
     finalizeFiles(scope, repoRoot, rangeFiles(git, scope.rangeBase, ref));
 }
-function resolveBySubject(unit, scope, git, ref, options, repoRoot) {
+function resolveBySubject(projectDir, unit, scope, git, ref, options, repoRoot) {
     const withBody = options.includeBody === true;
     // Refuse rather than truncate: a silently dropped positive pathspec narrows the match.
     const pathspecs = options.pathspecs ?? [];
@@ -412,7 +533,7 @@ function resolveBySubject(unit, scope, git, ref, options, repoRoot) {
     const grepArgs = [];
     let anchored = null;
     if (unit.kind === 'plan') {
-        const pattern = planSubjectPattern(unit.planId);
+        const pattern = planSubjectPattern(unit.planId, configuredProjectCode(projectDir));
         if (pattern === null)
             throw new ScopeUnreadable('invalid-plan-id');
         grepArgs.push('--extended-regexp', `--grep=${pattern}`);

package/gsd-core/bin/lib/gate-phase-context.cjs

@@ -34,10 +34,7 @@ const planningWorkspaceMod = require("./planning-workspace.cjs");
 const { planningDir } = planningWorkspaceMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseLocatorMod = require("./phase-locator.cjs");
-const { findPhaseInternal } = phaseLocatorMod;
-// eslint-disable-next-line @typescript-eslint/no-require-imports
-const phaseIdMod = require("./phase-id.cjs");
-const { normalizePhaseName, matchPhaseDirs } = phaseIdMod;
+const { phaseDirectoryOptions, findPhaseInternal, resolvePhaseDirectoryLookup, matchPhaseDirsForLookup } = phaseLocatorMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const roadmapModule = require("./roadmap.cjs");
 const { getRoadmapPhaseWithFallback } = roadmapModule;
@@ -78,7 +75,7 @@ function unresolvableProbeVerdict(readError) {
 function resolvePhaseDir(projectDir, phase) {
     let result;
     try {
-        result = findPhaseInternal(projectDir, phase);
+        result = findPhaseInternal(projectDir, phase, undefined, phaseDirectoryOptions(projectDir));
     }
     catch (err) {
         return (0, gate_evidence_cjs_1.evidenceFromError)(err, `phase ${phase}`);
@@ -109,11 +106,13 @@ function resolvePhaseDir(projectDir, phase) {
  * `resolvePhaseDir` would widen what those gates inspect, so the two stay apart and each states its
  * scope. Throws when `phasesDir` cannot be listed; both callers sit inside their non-blocking catch.
  */
-function resolvePhaseDirByToken(phasesDir, phaseArg) {
-    const normalizedPhase = normalizePhaseName(phaseArg);
+function resolvePhaseDirByToken(cwd, phasesDir, phaseArg, directoryContext = phaseDirectoryOptions(cwd)) {
+    const lookup = resolvePhaseDirectoryLookup(cwd, phaseArg, undefined, directoryContext);
     const dirEntries = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true });
     const dirNames = dirEntries.filter((e) => e.isDirectory()).map((e) => e.name);
-    const matched = matchPhaseDirs(dirNames, normalizedPhase).matches[0];
+    // #4304: both drift gates resolve a directory in the current checkout.
+    // Bracket is the only opt-in grammar; all other conventions remain legacy.
+    const matched = matchPhaseDirsForLookup(dirNames, lookup, undefined, directoryContext).matches[0];
     if (matched)
         return node_path_1.default.join(phasesDir, matched);
     const contained = (0, security_cjs_1.tryWithinRoot)(phaseArg, phasesDir);

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

@@ -68,7 +68,7 @@ function runSchemaDriftGate(cwd, phaseArg, skipFlag) {
     // 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);
+    const phaseDir = (0, gate_phase_context_cjs_1.resolvePhaseDirByToken)(cwd, 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}`);

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

@@ -29,6 +29,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.TDD_ROW_REASON = void 0;
 exports.evaluateTddReviewCheckpoint = evaluateTddReviewCheckpoint;
 const node_path_1 = __importDefault(require("node:path"));
 const gate_verdict_cjs_1 = require("./gate-verdict.cjs");
@@ -38,6 +39,9 @@ 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, extractFrontmatter } = frontmatterMod;
+exports.TDD_ROW_REASON = {
+    GREEN_BEFORE_RED: 'green_before_red',
+};
 /**
  * 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
@@ -78,19 +82,39 @@ function transitiveDependents(planId, dependents) {
     return [...seen].sort();
 }
 /**
- * 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".
+ * The plan's own commits (`test`, `feat`, `refactor`, …) — those that touched at least one path
+ * (`pathspecs: ['.']`, as the old `git log -- .` lookup did) — with the sha the ordering check needs.
+ * An unresolvable scope (git unavailable, an id that is not `<phase>-<plan>`) is "no commits".
  */
-function planCommitKinds(projectDir, planId) {
+function planCommits(projectDir, planId) {
     const scope = (0, gate_evaluation_scope_cjs_1.resolveEvaluationScope)(projectDir, { kind: 'plan', planId }, { pathspecs: ['.'], commitsOnly: true });
-    const kinds = new Set();
+    const commits = [];
     for (const commit of scope.commits) {
         const kind = /^([a-z]+)\(/.exec(commit.subject)?.[1];
         if (kind)
-            kinds.add(kind);
+            commits.push({ sha: commit.sha, kind });
     }
-    return kinds;
+    return commits;
+}
+const shasOfKind = (commits, kind) => commits.filter((c) => c.kind === kind).map((c) => c.sha);
+/**
+ * Whether some GREEN descends from some RED (#5275). Decided by ancestry only — never log position or
+ * commit date — so a history merged from worktree branches is judged by what each commit descends from.
+ * `true` as soon as one pair is in order; `null` when git could not answer for a pair and none was
+ * in order (an environment fault is not a violation, so the caller keeps the credit); else `false`.
+ */
+function greenFollowsRed(projectDir, reds, greens) {
+    let unanswered = false;
+    for (const red of reds) {
+        for (const green of greens) {
+            const redIsAncestor = (0, gate_evaluation_scope_cjs_1.commitIsAncestor)(projectDir, red, green);
+            if (redIsAncestor === true)
+                return true;
+            if (redIsAncestor === null)
+                unanswered = true;
+        }
+    }
+    return unanswered ? null : false;
 }
 /**
  * The verdict when the review could not read a plan or the phase directory. Advisory policy is
@@ -177,26 +201,41 @@ function evaluateTddReviewCheckpoint(input) {
     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 refactor = kinds.has('refactor');
+        const commits = planCommits(projectDir, planId);
+        const reds = shasOfKind(commits, 'test');
+        const red = reds.length > 0;
+        const refactor = commits.some((c) => c.kind === 'refactor');
+        // #5275: with a RED present, a GREEN counts only when it descends from a RED. Without one there is
+        // nothing to order against and the plan is already missing RED, so a GREEN commit stays credited.
+        const inOrder = (greens) => greens.length > 0 && (!red || greenFollowsRed(projectDir, reds, greens) !== false);
+        const ownGreens = shasOfKind(commits, 'feat');
+        const ownOk = inOrder(ownGreens);
         // #4867: a RED-only probe plan is satisfied by the GREEN of a plan that (transitively) declares
-        // `depends_on` it. Only a real `feat(...)` commit under such a plan counts; the plan's own RED is
-        // still required, and a plan nothing depends on is scored on its own commits alone.
-        const ownGreen = kinds.has('feat');
-        const greenFrom = ownGreen
+        // `depends_on` it. Only a real `feat(...)` commit under such a plan counts, and it must follow the
+        // RED too (#5275); the plan's own RED is still required, and a plan nothing depends on is scored
+        // on its own commits alone.
+        const dependentGreens = ownOk
             ? []
-            : transitiveDependents(planId, dependents).filter((dependentId) => planCommitKinds(projectDir, dependentId).has('feat'));
-        const green = ownGreen || greenFrom.length > 0;
+            : transitiveDependents(planId, dependents).map((id) => ({ id, greens: shasOfKind(planCommits(projectDir, id), 'feat') }));
+        const greenFrom = dependentGreens.filter((d) => inOrder(d.greens)).map((d) => d.id);
+        const green = ownOk || greenFrom.length > 0;
+        const anyGreenCommit = ownGreens.length > 0 || dependentGreens.some((d) => d.greens.length > 0);
         const missing = [];
         if (!red)
             missing.push('RED');
-        if (!green)
+        if (!anyGreenCommit)
             missing.push('GREEN');
-        const status = missing.length === 0 ? 'Pass' : 'FAIL';
-        rows.push(greenFrom.length > 0
-            ? { planId, red, green, refactor, status, missing, greenFrom }
-            : { planId, red, green, refactor, status, missing });
+        const status = missing.length === 0 && green ? 'Pass' : 'FAIL';
+        // Both commit kinds exist but no GREEN follows a RED: its own reason. A row that fails for a
+        // missing commit keeps the exact shape it always had (`missing` already says why).
+        const reason = status === 'FAIL' && missing.length === 0
+            ? exports.TDD_ROW_REASON.GREEN_BEFORE_RED
+            : undefined;
+        rows.push({
+            planId, red, green, refactor, status, missing,
+            ...(reason ? { reason } : {}),
+            ...(greenFrom.length > 0 ? { greenFrom } : {}),
+        });
     }
     const violations = rows.filter(r => r.status === 'FAIL').length;
     // Build review table
@@ -218,7 +257,9 @@ function evaluateTddReviewCheckpoint(input) {
     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 += r.reason === exports.TDD_ROW_REASON.GREEN_BEFORE_RED
+                ? `\n  Plan ${r.planId} GREEN precedes RED: no feat(...) commit descends from a test(...) commit.`
+                : `\n  Plan ${r.planId} missing: ${r.missing.join(', ')} gate commit(s).`;
             table += `\n  Expected commit pattern: test(${r.planId}): ... → feat(${r.planId}): ...`;
         }
     }

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

@@ -21,6 +21,8 @@ const gate_phase_context_cjs_1 = require("./gate-phase-context.cjs");
 const gate_evaluation_scope_cjs_1 = require("./gate-evaluation-scope.cjs");
 const runtime_slash_cjs_1 = require("./runtime-slash.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");
 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;
 /**
@@ -32,7 +34,10 @@ const UI_PATH_PATTERNS_RE = /\/(components|pages|views|screens|layouts|ui|fronte
  *       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`.
+ *   (c') Static frontend evidence (`readStaticFrontendEvidence`, the definition `computeUiPlanGate` uses),
+ *       probed only for a frontend phase that changed UI files (#5646).
+ *
+ * `block = frontend && hasUiFiles && hasFrontendEvidence && !hasUiSpec`.
  */
 function computeUiSafetyGate(projectDir, phase) {
     // (a) phase section text (same two-pass lookup as computeUiPlanGate)
@@ -43,14 +48,27 @@ function computeUiSafetyGate(projectDir, phase) {
     // (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)));
+    // (c') #5646 — static structural corroboration, the same evidence `computeUiPlanGate` requires (#3312):
+    // `hasUiFiles` is a weak signal (an `.html` fixture, or any file under a `ui/` directory in any
+    // language), so on its own it halted projects with no frontend that the plan gate had cleared. Only
+    // probed when it could change the answer. `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).
+    const frontendEvidence = frontend && hasUiFiles ? (0, ui_frontend_evidence_cjs_1.readStaticFrontendEvidence)(projectDir) : (0, gate_evidence_cjs_1.evidenceNone)();
+    const hasFrontendEvidence = frontendEvidence.kind === 'found';
     // (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 };
+    // 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 only when: this is a frontend phase AND UI files were changed AND the project has static
+    // frontend evidence AND no UI-SPEC exists
+    const block = frontend && hasUiFiles && hasFrontendEvidence && !hasUiSpec;
+    const result = { frontend, hasUiFiles, hasFrontendEvidence, hasUiSpec, block };
     if (block) {
         result.message = `UI files changed in this wave but no UI-SPEC.md exists for Phase ${phase}. ` +
             `Run ${(0, runtime_slash_cjs_1.runtimeCommand)(projectDir, `ui-phase ${phase}`)} to generate the design contract before continuing.`;

package/gsd-core/bin/lib/git-info-exclude.cjs

@@ -0,0 +1,52 @@
+"use strict";
+/**
+ * Keep a machine-local file out of `git status` without touching any tracked
+ * file: append an anchored entry to the enclosing repo's `info/exclude` (#5551).
+ *
+ * Used for files GSD writes under `.planning/` that are per-machine state, not
+ * project content (the milestone claim). A copy that is already tracked is left
+ * alone — an exclude entry never untracks, and migrating it is the user's call.
+ *
+ * Best-effort by contract: never throws. Ignoring is optional, so no failure
+ * here (no git, read-only `.git`, odd path) may perturb the caller.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.excludeFromGit = excludeFromGit;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+const text_lines_cjs_1 = require("./text-lines.cjs");
+/** Escape gitignore metacharacters so a directory or file name matches literally. */
+function escapeGitignore(s) {
+    return s.replace(/[\\*?[]/g, '\\$&');
+}
+/**
+ * Exclude `<dir>/<filename>` from git via the repo-local `info/exclude`.
+ * `dir` must already exist (it is the spawn cwd).
+ */
+function excludeFromGit(dir, filename) {
+    try {
+        // gitignore cannot express a newline in a pattern, and git's line output could not be split.
+        if (/[\r\n]/.test(dir))
+            return;
+        // The prefix goes last: stdout is trimmed, and a non-empty prefix ends in `/`, so only an
+        // empty prefix (dir is the git root) loses its line; a leading space survives.
+        const revParse = (0, shell_command_projection_cjs_1.execGit)(['rev-parse', '--git-path', 'info/exclude', '--show-prefix'], { cwd: dir });
+        const [excludeRel, prefix = ''] = (0, text_lines_cjs_1.splitLines)(String(revParse.stdout));
+        if (revParse.exitCode !== 0 || !excludeRel)
+            return;
+        const exclude = node_path_1.default.resolve(dir, excludeRel);
+        const entry = `/${escapeGitignore(prefix)}${escapeGitignore(filename)}`;
+        const existing = node_fs_1.default.existsSync(exclude) ? node_fs_1.default.readFileSync(exclude, 'utf8') : '';
+        if ((0, text_lines_cjs_1.splitLines)(existing).includes(entry))
+            return;
+        node_fs_1.default.mkdirSync(node_path_1.default.dirname(exclude), { recursive: true });
+        node_fs_1.default.appendFileSync(exclude, (existing && !existing.endsWith('\n') ? '\n' : '') + entry + '\n');
+    }
+    catch {
+        // advisory: see the module header.
+    }
+}