@opengsd/gsd-core 1.7.0 → 1.9.0

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

@@ -31,6 +31,7 @@ const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
 const schema_detect_cjs_1 = require("./schema-detect.cjs");
 const artifacts_cjs_1 = require("./artifacts.cjs");
 const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
+const model_catalog_cjs_1 = require("./model-catalog.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- agent-install-check.cjs is an export= CommonJS module
 const agentInstallCheck = require("./agent-install-check.cjs");
 const { checkAgentsInstalled } = agentInstallCheck;
@@ -42,7 +43,7 @@ const configLoaderMod = require("./config-loader.cjs");
 const { loadConfig, CONFIG_DEFAULTS } = configLoaderMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdMod = require("./phase-id.cjs");
-const { normalizePhaseName, phaseTokenMatches, escapeRegex, getMilestoneFromPhaseId, OPTIONAL_PHASE_TAG_SOURCE, PHASE_NUMBER_TOKEN_SOURCE } = phaseIdMod;
+const { normalizePhaseName, phaseTokenMatches, escapeRegex, getMilestoneFromPhaseId, OPTIONAL_PHASE_TAG_SOURCE, PHASE_NUMBER_TOKEN_SOURCE, extractPhaseToken, comparePhaseNum } = phaseIdMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseLocatorMod = require("./phase-locator.cjs");
 const { findPhaseInternal } = phaseLocatorMod;
@@ -52,6 +53,9 @@ const { getMilestoneInfo, stripShippedMilestones, extractCurrentMilestone } = ro
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const worktreeSafetyMod = require("./worktree-safety.cjs");
 const { inspectWorktreeHealth } = worktreeSafetyMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- commands.cjs is an export= CommonJS module
+const commandsMod = require("./commands.cjs");
+const { determinePhaseStatus } = commandsMod;
 const { planningDir, planningRoot } = planningWorkspace;
 const { extractFrontmatter, parseMustHavesBlock } = frontmatterMod;
 const { writeStateMd } = stateMod;
@@ -59,14 +63,35 @@ const { MODEL_PROFILES } = modelProfilesMod;
 // Unused but imported for structural parity
 void stripShippedMilestones;
 void schema_detect_cjs_1.detectSchemaFiles;
-function cmdVerifySummary(cwd, summaryPath, checkFileCount, raw) {
-    if (!summaryPath) {
-        error('summary-path required');
-    }
+/**
+ * Pure core of `verify-summary` (#2572).
+ *
+ * Same artifact↔git checks the CLI verb has always run, lifted out of the
+ * `output()` wrapper so other verbs can consume the structured
+ * `{ passed, checks, errors }` contract directly instead of shelling out and
+ * re-parsing JSON. `cmdVerifySummary` is now a thin adapter over this.
+ *
+ * Never throws and never writes to stdout: a missing SUMMARY, a non-repo, or an
+ * unresolvable commit all come back as structured `false`/`missing` values.
+ *
+ * Caveat for callers surfacing `commits_exist`: the hash pattern is a loose
+ * `\b[0-9a-f]{7,40}\b`, so any hex-shaped token in the prose counts as a
+ * candidate. That is cheap as an advisory signal and unacceptable as a gate.
+ *
+ * @param checkFileCount How many extracted candidates to probe. Defaults to 2 —
+ *   the value the CLI verb has always used. Pass `Infinity` to probe every
+ *   candidate (see `cmdPhaseComplete`, which reports on all of them).
+ * @param opts.checkCommits When `false`, the `git cat-file` probes are skipped
+ *   entirely and `commits_exist` comes back `false` meaning *not checked*.
+ *   Callers that do not surface `commits_exist` should pass `false` so this
+ *   stays a pure-filesystem check with no subprocess cost.
+ */
+function verifySummaryCore(cwd, summaryPath, checkFileCount, opts) {
     const fullPath = node_path_1.default.join(cwd, summaryPath);
     const checkCount = checkFileCount || 2;
+    const checkCommits = opts?.checkCommits !== false;
     if (!node_fs_1.default.existsSync(fullPath)) {
-        const result = {
+        return {
             passed: false,
             checks: {
                 summary_exists: false,
@@ -76,21 +101,75 @@ function cmdVerifySummary(cwd, summaryPath, checkFileCount, raw) {
             },
             errors: ['SUMMARY.md not found'],
         };
-        output(result, raw, 'failed');
-        return;
     }
     const content = node_fs_1.default.readFileSync(fullPath, 'utf-8');
     const errors = [];
+    const projectRoot = node_path_1.default.resolve(cwd);
+    /**
+     * Is `candidate` plausibly a repo-relative file this check should probe?
+     *
+     * Deliberately narrowing. This is an ADVISORY, so the two error directions are
+     * not symmetric: a false positive tells a user their healthy project is
+     * missing a file that was never claimed, while a false negative just means one
+     * reference goes unprobed. Every rejection below is a noise class confirmed on
+     * #2685; when in doubt, skip rather than warn.
+     */
+    const isProbableProjectFile = (candidate) => {
+        // Only repo-relative paths — a bare filename is too ambiguous to locate.
+        if (!candidate.includes('/'))
+            return false;
+        // URLs, protocol-relative links, and any other scheme.
+        if (candidate.startsWith('http') || candidate.startsWith('//'))
+            return false;
+        if (/^[a-z][a-z0-9+.-]*:\/\//i.test(candidate))
+            return false;
+        // Globs name a set, not a file: `src/**/*.cts` is never "missing".
+        if (/[*?]/.test(candidate))
+            return false;
+        // Bare hostnames (`docs.example.com/guide.html`). A repo-relative path's
+        // first segment is a directory name, which in practice contains a dot only
+        // when it is a dotfile directory (`.github/`, `.changeset/`, `.planning/`)
+        // — i.e. the dot is at index 0. A dot anywhere later marks a hostname.
+        const firstSegment = candidate.split('/')[0] || '';
+        if (firstSegment.indexOf('.') > 0)
+            return false;
+        // Containment guard: a `../`-bearing reference must not turn this advisory
+        // into a filesystem existence probe outside the project.
+        const resolved = node_path_1.default.resolve(projectRoot, candidate);
+        if (resolved !== projectRoot && !resolved.startsWith(projectRoot + node_path_1.default.sep))
+            return false;
+        return true;
+    };
+    // Pattern 2 excludes `[` and `]` from its path class (#2685 Blocker 1). All
+    // three SUMMARY templates prescribe a YAML flow sequence for `key-files`:
+    //
+    //     key-files:
+    //       created: [src/auth/login.ts, src/auth/session.ts]
+    //
+    // and the label matches `(?:Created|Modified|…):` case-insensitively. Without
+    // the bracket exclusion the class captures the literal `[` as part of the
+    // first path, yielding `[src/auth/login.ts` — a candidate that can never exist
+    // on disk. That fired on healthy projects built from GSD's own shipped
+    // template. The exclusion also stops a markdown list in the body from
+    // reintroducing the same artifact.
+    //
+    // Stripping frontmatter first was the other remedy offered on #2685. It is a
+    // verified no-op on top of this exclusion — measured identical extraction
+    // across all three shipped templates — because the exclusion already makes a
+    // flow-sequence line contribute nothing. Consequence worth naming: the
+    // `key-files` block, the most authoritative statement of what a phase created,
+    // is still not read. Recovering it needs a real frontmatter parse, which is
+    // deliberately left as a follow-up rather than smuggled in here.
     const mentionedFiles = new Set();
     const patterns = [
         /`([^`]+\.[a-zA-Z]+)`/g,
-        /(?:Created|Modified|Added|Updated|Edited):\s*`?([^\s`]+\.[a-zA-Z]+)`?/gi,
+        /(?:Created|Modified|Added|Updated|Edited):\s*`?([^\s`[\]]+\.[a-zA-Z]+)`?/gi,
     ];
     for (const pattern of patterns) {
         let m;
         while ((m = pattern.exec(content)) !== null) {
             const filePath = m[1];
-            if (filePath && !filePath.startsWith('http') && filePath.includes('/')) {
+            if (filePath && isProbableProjectFile(filePath)) {
                 mentionedFiles.add(filePath);
             }
         }
@@ -98,12 +177,12 @@ function cmdVerifySummary(cwd, summaryPath, checkFileCount, raw) {
     const filesToCheck = Array.from(mentionedFiles).slice(0, checkCount);
     const missing = [];
     for (const file of filesToCheck) {
-        if (!node_fs_1.default.existsSync(node_path_1.default.join(cwd, file))) {
+        if (!node_fs_1.default.existsSync(node_path_1.default.resolve(projectRoot, file))) {
             missing.push(file);
         }
     }
     const commitHashPattern = /\b[0-9a-f]{7,40}\b/g;
-    const hashes = content.match(commitHashPattern) || [];
+    const hashes = checkCommits ? content.match(commitHashPattern) || [] : [];
     let commitsExist = false;
     if (hashes.length > 0) {
         for (const hash of hashes.slice(0, 3)) {
@@ -140,8 +219,15 @@ function cmdVerifySummary(cwd, summaryPath, checkFileCount, raw) {
         self_check: selfCheck,
     };
     const passed = missing.length === 0 && selfCheck !== 'failed';
-    const result = { passed, checks, errors };
-    output(result, raw, passed ? 'passed' : 'failed');
+    return { passed, checks, errors };
+}
+/** CLI adapter over verifySummaryCore — arg guard + output shaping only. */
+function cmdVerifySummary(cwd, summaryPath, checkFileCount, raw) {
+    if (!summaryPath) {
+        error('summary-path required');
+    }
+    const result = verifySummaryCore(cwd, summaryPath, checkFileCount);
+    output(result, raw, result.passed ? 'passed' : 'failed');
 }
 /**
  * Issue #429 — negative-grep comment-text echo gate.
@@ -516,17 +602,153 @@ function scanFileWideNegativeGateConflict(content) {
     // This detector is warn-only: it never sets valid=false.
     return { warnings, valid: true };
 }
+/**
+ * Single pass over `<task ...>…</task>` blocks. The body pattern is
+ * ReDoS-safe stop-at-next-open (mirrors `taggedBlockPattern` in
+ * markdown-sectionizer.cts): bounded attributes (`[^>]{0,1000}`) and a body
+ * boundary that terminates at the NEXT `<task[\s>]` opening, so a document
+ * full of unclosed `<task>` openings scans linearly. Captures both the
+ * attribute string (group 1, so the `type=` selector is not lost the way it is
+ * with `extractTaggedBlocks`) and the body (group 2).
+ */
+const PLAN_TASK_BLOCK_RE = /<task(\s[^>]{0,1000})?>((?:(?!<task[\s>])[\s\S])*?)<\/task>/g;
+/**
+ * Extract one `PlanTaskInfo` per `<task …>…</task>` block in `content`.
+ *
+ * Why a dedicated regex instead of `extractTaggedBlocks('task', true)`:
+ * `extractTaggedBlocks` discards the opening tag, so the task's `type=`
+ * attribute (which selects the validation branch) is lost. This helper
+ * captures both the attribute string and the body in one pass, then reuses
+ * `extractTaggedBlocks` on the body for sub-element extraction.
+ */
+function extractPlanTaskInfos(content) {
+    const infos = [];
+    if (typeof content !== 'string' || content.length === 0)
+        return infos;
+    PLAN_TASK_BLOCK_RE.lastIndex = 0;
+    let match;
+    while ((match = PLAN_TASK_BLOCK_RE.exec(content)) !== null) {
+        const attrs = match[1] ?? '';
+        const body = match[2] ?? '';
+        const typeMatch = attrs.match(/\btype\s*=\s*["']?([\w:-]+)/i);
+        const type = typeMatch ? typeMatch[1].toLowerCase() : '';
+        const nameArr = (0, markdown_sectionizer_cjs_1.extractTaggedBlocks)(body, 'name');
+        const hasName = nameArr.length > 0;
+        const name = hasName ? nameArr[0].trim() : '';
+        infos.push({
+            name,
+            type,
+            hasName,
+            hasFiles: /<files>/.test(body),
+            hasAction: /<action>/.test(body),
+            hasVerify: /<verify>/.test(body),
+            hasDone: /<done>/.test(body),
+            hasWhatBuilt: /<what-built>/.test(body),
+            hasHowToVerify: /<how-to-verify>/.test(body),
+            hasDecision: /<decision>/.test(body),
+            hasOptions: /<options>/.test(body),
+            hasInstructions: /<instructions>/.test(body),
+            hasVerification: /<verification>/.test(body),
+            hasResumeSignal: /<resume-signal>/.test(body),
+        });
+        // Guard against zero-length matches looping forever.
+        if (match.index === PLAN_TASK_BLOCK_RE.lastIndex) {
+            PLAN_TASK_BLOCK_RE.lastIndex++;
+        }
+    }
+    return infos;
+}
+function isCheckpointType(type) {
+    return type.startsWith('checkpoint:');
+}
+/**
+ * Validate one plan task's structure against its type-specific canonical field
+ * set (per `gsd-core/references/checkpoints.md`):
+ *   - `checkpoint:human-verify` requires `<what-built>` / `<how-to-verify>` /
+ *      `<resume-signal>` (the "checkpoint triple").
+ *   - `checkpoint:decision` requires `<decision>` / `<options>` /
+ *      `<resume-signal>`.
+ *   - `checkpoint:human-action` requires `<action>` / `<instructions>` /
+ *      `<verification>` / `<resume-signal>`.
+ *   - Unknown `checkpoint:*` subtypes require only the universal
+ *      `<resume-signal>` (forward-compat — newer checkpoint types registered
+ *      in the reference don't need a verifier change to pass structure
+ *      validation).
+ *   - All other types (`auto`, `tracer`, `manual`, bare `<task>`, …) keep the
+ *      historical `<action>` / `<verify>` / `<done>` / `<files>` requirements.
+ */
+function validatePlanTaskStructure(task) {
+    const errors = [];
+    const warnings = [];
+    const taskName = task.hasName ? task.name : 'unnamed';
+    if (!task.hasName) {
+        errors.push('Task missing <name> element');
+    }
+    if (isCheckpointType(task.type)) {
+        if (!task.hasResumeSignal) {
+            errors.push(`Task '${taskName}' missing <resume-signal>`);
+        }
+        switch (task.type) {
+            case 'checkpoint:human-verify':
+                if (!task.hasWhatBuilt)
+                    errors.push(`Task '${taskName}' missing <what-built>`);
+                if (!task.hasHowToVerify)
+                    errors.push(`Task '${taskName}' missing <how-to-verify>`);
+                break;
+            case 'checkpoint:decision':
+                if (!task.hasDecision)
+                    errors.push(`Task '${taskName}' missing <decision>`);
+                if (!task.hasOptions)
+                    errors.push(`Task '${taskName}' missing <options>`);
+                break;
+            case 'checkpoint:human-action':
+                if (!task.hasAction)
+                    errors.push(`Task '${taskName}' missing <action>`);
+                if (!task.hasInstructions)
+                    errors.push(`Task '${taskName}' missing <instructions>`);
+                if (!task.hasVerification)
+                    errors.push(`Task '${taskName}' missing <verification>`);
+                break;
+            default:
+                // Unknown checkpoint:* subtype: <resume-signal> is the only universal
+                // requirement (forward-compat).
+                break;
+        }
+    }
+    else {
+        if (!task.hasAction)
+            errors.push(`Task '${taskName}' missing <action>`);
+        if (!task.hasVerify)
+            warnings.push(`Task '${taskName}' missing <verify>`);
+        if (!task.hasDone)
+            warnings.push(`Task '${taskName}' missing <done>`);
+        if (!task.hasFiles)
+            warnings.push(`Task '${taskName}' missing <files>`);
+    }
+    return { errors, warnings };
+}
 function cmdVerifyPlanStructure(cwd, filePath, raw) {
     if (!filePath) {
         error('file path required');
     }
+    if (filePath.includes('\0')) {
+        error('file path contains null bytes');
+    }
     const fullPath = node_path_1.default.isAbsolute(filePath) ? filePath : node_path_1.default.join(cwd, filePath);
     const content = (0, shell_command_projection_cjs_1.platformReadSync)(fullPath);
     if (!content) {
         output({ error: 'File not found', path: filePath }, raw);
         return;
     }
-    const fm = extractFrontmatter(content);
+    // #2701: fail loud on NUL/binary corruption before structure checks. A
+    // structurally intact-but-NUL-corrupted plan otherwise passes as valid and is
+    // silently skipped by recursive/binary-skipping searchers downstream.
+    const encErr = (0, validate_cjs_2.textEncodingError)(content, filePath);
+    if (encErr) {
+        output({ valid: false, errors: [encErr] }, raw);
+        return;
+    }
+    const fm = extractFrontmatter(content, fullPath);
     const errors = [];
     const warnings = [];
     const required = ['phase', 'plan', 'type', 'wave', 'depends_on', 'files_modified', 'autonomous', 'must_haves'];
@@ -534,25 +756,20 @@ function cmdVerifyPlanStructure(cwd, filePath, raw) {
         if (fm[field] === undefined)
             errors.push(`Missing required frontmatter field: ${field}`);
     }
+    const extractedTasks = extractPlanTaskInfos(content);
     const tasks = [];
-    for (const taskContent of (0, markdown_sectionizer_cjs_1.extractTaggedBlocks)(content, 'task', true)) {
-        const nameArr = (0, markdown_sectionizer_cjs_1.extractTaggedBlocks)(taskContent, 'name');
-        const taskName = nameArr.length ? nameArr[0].trim() : 'unnamed';
-        const hasFiles = /<files>/.test(taskContent);
-        const hasAction = /<action>/.test(taskContent);
-        const hasVerify = /<verify>/.test(taskContent);
-        const hasDone = /<done>/.test(taskContent);
-        if (nameArr.length === 0)
-            errors.push('Task missing <name> element');
-        if (!hasAction)
-            errors.push(`Task '${taskName}' missing <action>`);
-        if (!hasVerify)
-            warnings.push(`Task '${taskName}' missing <verify>`);
-        if (!hasDone)
-            warnings.push(`Task '${taskName}' missing <done>`);
-        if (!hasFiles)
-            warnings.push(`Task '${taskName}' missing <files>`);
-        tasks.push({ name: taskName, hasFiles, hasAction, hasVerify, hasDone });
+    for (const task of extractedTasks) {
+        const verdict = validatePlanTaskStructure(task);
+        errors.push(...verdict.errors);
+        warnings.push(...verdict.warnings);
+        tasks.push({
+            name: task.hasName ? task.name : 'unnamed',
+            type: task.type,
+            hasFiles: task.hasFiles,
+            hasAction: task.hasAction,
+            hasVerify: task.hasVerify,
+            hasDone: task.hasDone,
+        });
     }
     if (tasks.length === 0)
         warnings.push('No <task> elements found');
@@ -567,6 +784,24 @@ function cmdVerifyPlanStructure(cwd, filePath, raw) {
     if (hasCheckpoints && fm['autonomous'] !== 'false' && String(fm['autonomous']) !== 'false') {
         errors.push('Has checkpoint tasks but autonomous is not false');
     }
+    // #1951: a decision rated one-way is supposed to be confirmed before it is
+    // walked through. Warn (never error — <reversibility> stays additive) when a
+    // one-way rating has no checkpoint:decision anywhere ahead of it in the plan,
+    // which is the planner emitting the rating but skipping the gate.
+    const decisionCheckpointOffsets = [];
+    for (const m of content.matchAll(/<task\s+type=["']?checkpoint:decision/g)) {
+        if (m.index !== undefined)
+            decisionCheckpointOffsets.push(m.index);
+    }
+    for (const m of content.matchAll(/<reversibility\s[^>]*rating=["']?one-way/g)) {
+        const at = m.index;
+        if (at === undefined)
+            continue;
+        if (!decisionCheckpointOffsets.some((offset) => offset < at)) {
+            warnings.push('Task rated <reversibility rating="one-way"> has no preceding checkpoint:decision — '
+                + 'a one-way door must be confirmed before the agent walks through it');
+        }
+    }
     const echoScan = scanNegativeGrepCommentEcho(content);
     errors.push(...echoScan.errors);
     warnings.push(...echoScan.warnings);
@@ -767,7 +1002,7 @@ function collectPromisedFilesAtOrAfterWave(phaseDir, minWave) {
         const planContent = (0, shell_command_projection_cjs_1.platformReadSync)(planFullPath);
         if (!planContent)
             continue;
-        const fm = extractFrontmatter(planContent);
+        const fm = extractFrontmatter(planContent, planFullPath);
         const waveRaw = fm['wave'];
         const wave = typeof waveRaw === 'string' ? parseInt(waveRaw, 10) : (typeof waveRaw === 'number' ? waveRaw : NaN);
         if (isNaN(wave) || wave < minWave)
@@ -802,7 +1037,7 @@ function cmdVerifyKeyLinks(cwd, planFilePath, raw) {
     }
     // Derive the current plan's wave number and phase directory for wave-aware
     // missing-file handling (fix #1202).
-    const currentFm = extractFrontmatter(content);
+    const currentFm = extractFrontmatter(content, fullPath);
     const currentWaveRaw = currentFm['wave'];
     const currentWave = typeof currentWaveRaw === 'string'
         ? parseInt(currentWaveRaw, 10)
@@ -899,8 +1134,16 @@ function listMilestoneArchiveDirs(planBase) {
             .map((e) => node_path_1.default.join(milestonesDir, e.name))
             .sort((a, b) => node_path_1.default.basename(a).localeCompare(node_path_1.default.basename(b), undefined, { numeric: true }));
     }
-    catch {
-        return [];
+    catch (err) {
+        // #1883: distinguish genuine absence from a permission/I-O failure. ENOENT
+        // (no milestones/ dir yet) keeps the long-standing [] contract that
+        // collectPhaseRoots / forEachArchivedPhaseToken depend on for "no archives";
+        // every other error (EACCES, EIO, …) must propagate — otherwise an unreadable
+        // milestones/ dir is silently reported as "no archives" and active-milestone
+        // resolution / archived-phase filtering misbehaves.
+        if (err.code === 'ENOENT')
+            return [];
+        throw err;
     }
 }
 function forEachArchivedPhaseToken(planBase, onPhase) {
@@ -1073,8 +1316,9 @@ function cmdValidateConsistency(cwd, raw) {
                     }
                 }
                 for (const plan of plans) {
-                    const content = node_fs_1.default.readFileSync(node_path_1.default.join(phasePath, plan), 'utf-8');
-                    const fmData = extractFrontmatter(content);
+                    const planFilePath = node_path_1.default.join(phasePath, plan);
+                    const content = node_fs_1.default.readFileSync(planFilePath, 'utf-8');
+                    const fmData = extractFrontmatter(content, planFilePath);
                     if (!fmData['wave']) {
                         warnings.push(`${phaseLabel}/${plan}: missing 'wave' in frontmatter`);
                     }
@@ -1207,9 +1451,22 @@ function cmdValidateHealth(cwd, options, raw) {
         try {
             const rawCfg = node_fs_1.default.readFileSync(configPath, 'utf-8');
             const parsed = JSON.parse(rawCfg);
-            const validProfiles = ['quality', 'balanced', 'budget', 'inherit'];
-            if (parsed['model_profile'] && !validProfiles.includes(parsed['model_profile'])) {
-                addIssue('warning', 'W004', `config.json: invalid model_profile "${parsed['model_profile']}"`, `Valid values: ${validProfiles.join(', ')}`);
+            if (parsed['model_profile'] && !model_catalog_cjs_1.VALID_PROFILES.includes(parsed['model_profile'])) {
+                addIssue('warning', 'W004', `config.json: invalid model_profile "${parsed['model_profile']}"`, `Valid values: ${model_catalog_cjs_1.VALID_PROFILES.join(', ')}`);
+            }
+            const configModels = parsed['models'];
+            if (configModels && typeof configModels === 'object' && !Array.isArray(configModels)) {
+                for (const [phaseType, tierValue] of Object.entries(configModels)) {
+                    if (!model_catalog_cjs_1.VALID_PHASE_TYPES.has(phaseType)) {
+                        addIssue('warning', 'W022', `config.json: models has an unknown phase type "${phaseType}" which will be ignored`, `Valid phase types: ${[...model_catalog_cjs_1.VALID_PHASE_TYPES].join(', ')}`);
+                    }
+                    else if (typeof tierValue !== 'string' || !model_catalog_cjs_1.VALID_TIERS.has(tierValue)) {
+                        addIssue('warning', 'W022', `config.json: models.${phaseType} has an invalid tier value ${JSON.stringify(tierValue)} which will be ignored`, `Valid tiers: ${[...model_catalog_cjs_1.VALID_TIERS].join(', ')}`);
+                    }
+                }
+            }
+            else if (configModels !== undefined && configModels !== null) {
+                addIssue('warning', 'W022', `config.json: models is set to ${JSON.stringify(configModels)}, but must be an object mapping phase types to tiers — this value will be ignored`, `Set models to an object like {"planning": "sonnet"}, or remove the key to use profile defaults`);
             }
         }
         catch (err) {
@@ -1260,6 +1517,49 @@ function cmdValidateHealth(cwd, options, raw) {
             addIssue('warning', 'W005', `Phase directory "${e.name}" doesn't follow NN-name format`, 'Rename to match pattern (e.g., 01-setup)');
         }
     }
+    // W023 (#2408): detect two or more real on-disk phase directories that
+    // normalize to the same phase key (e.g. `05-real/` + `05-real-stray/`).
+    // The collision silently breaks /gsd-stats status accuracy (now folded by
+    // precedence — see commands.cts foldPhaseStatus) and forces an operator
+    // decision. Wording is neutral — never guesses which directory is "real".
+    {
+        const groups = new Map();
+        for (const e of phaseDirEntries) {
+            // extractPhaseToken never returns empty — for unparseable dir names it
+            // falls back to the dir name itself. Two distinct unparseable names
+            // therefore normalize to distinct keys and cannot false-positive here;
+            // only dirs whose tokens collapse to the same key (e.g. `05-real` and
+            // `05-real-stray` → token `05`) produce a collision group.
+            const token = extractPhaseToken(e.name);
+            const key = normalizePhaseName(token);
+            const list = groups.get(key);
+            if (list)
+                list.push(e.name);
+            else
+                groups.set(key, [e.name]);
+        }
+        for (const [key, dirs] of groups) {
+            if (dirs.length < 2)
+                continue;
+            // Compute each dir's status independently so the warning is informative.
+            // Sort by phase id for stable output regardless of readdir order; tie-
+            // break on the dir name itself so two dirs sharing the same phase token
+            // (the collision case itself) still sort deterministically (V8's stable
+            // sort would otherwise fall back to non-portable fs.readdirSync order).
+            const described = dirs
+                .slice()
+                .sort((a, b) => comparePhaseNum(a, b) || String(a).localeCompare(String(b)))
+                .map((d) => {
+                const files = phaseDirFiles.get(d) || [];
+                const plans = files.filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md').length;
+                const summaries = files.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md').length;
+                const status = determinePhaseStatus(plans, summaries, node_path_1.default.join(phasesDir, d), 'Not Started');
+                return `${d} (${status})`;
+            })
+                .join(', ');
+            addIssue('warning', 'W023', `Phase directories collide on normalized key "${key}": ${described}`, 'Inspect each directory; rename or remove the duplicate so only one directory maps to this phase key');
+        }
+    }
     for (const e of phaseDirEntries) {
         const phaseFiles = phaseDirFiles.get(e.name) || [];
         const plans = phaseFiles.filter((f) => f.endsWith('-PLAN.md') || f === 'PLAN.md');
@@ -1949,6 +2249,7 @@ module.exports = {
     scanNegativeGrepCommentEcho,
     scanFileWideNegativeGateConflict,
     cmdVerifySummary,
+    verifySummaryCore,
     cmdVerifyPlanStructure,
     cmdVerifyPhaseCompleteness,
     cmdVerifyReferences,
@@ -1960,4 +2261,9 @@ module.exports = {
     cmdValidateAgents,
     cmdVerifySchemaDrift,
     cmdVerifyCodebaseDrift,
+    // Test seam (#1883): listMilestoneArchiveDirs is private and exercised through
+    // the validate command, which runs in a subprocess — an fs monkeypatch in the
+    // test process cannot reach it. Exposed under a leading underscore so the
+    // permission-error path can be unit-tested directly (no chmod 0o000).
+    _listMilestoneArchiveDirs: listMilestoneArchiveDirs,
 };