@opengsd/gsd-core 1.10.0 → 1.11.0

package/gsd-core/bin/lib/health-diagnostic-rules/milestone-archive-hygiene.cjs

@@ -0,0 +1,100 @@
+"use strict";
+/**
+ * Health Diagnostic — Milestone archive + root hygiene rules (Phase 11,
+ * #3309, ADR-3180 §8.2/§8.3/§8.5).
+ *
+ * Group: "Milestone archive + root hygiene" (design doc, "Rule table
+ * organization" table) — W018, W019.
+ *
+ * Ported behavior-preserving from `cmdValidateHealth`
+ * (`src/verify.cts:2301-2354`), the exact call sites for W018/W019.
+ *
+ * Design: .gsd/phase/refactor-3309-health-diagnostic-rule-table/40-design.md
+ *
+ * ADR-457 build-at-publish: source in
+ * src/health-diagnostic-rules/milestone-archive-hygiene.cts, compiled to
+ * gsd-core/bin/lib/health-diagnostic-rules/milestone-archive-hygiene.cjs
+ * (gitignored).
+ */
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const healthDiagnosticMod = require("../health-diagnostic-types.cjs");
+const { SEVERITY, REMEDY_ACTION, REMEDY_RISK, adviseRemedy } = healthDiagnosticMod;
+const artifacts_cjs_1 = require("../artifacts.cjs");
+// ─── W018 — MILESTONES.md missing archived milestone(s) (verify.cts:2301-2335) ──
+//
+// Condition: `snapshot.milestoneArchiveStatus.value.archivedVersions` (list of
+// versions with a `.planning/milestones/<ver>-ROADMAP.md` snapshot file) minus
+// `.documentedVersions` (list of `## <version>` headings already present in
+// MILESTONES.md) — versions present in the archive but not documented in the
+// registry. ONE aggregate `Diagnostic` listing every missing version, exactly
+// mirroring the original's single `addIssue` call
+// (`verify.cts:2321-2330`, `` `MILESTONES.md missing ${missingFromRegistry.length}
+// archived milestone(s): ${missingFromRegistry.join(', ')}` ``) — the original
+// computes the FULL list first (`missingFromRegistry`), then fires exactly one
+// `addIssue` after the loop, not once per version. No diagnostic at all if the
+// archive dir has zero recognized `-ROADMAP.md` snapshots (mirrors the
+// original's `if (archivedVersions.length > 0)` guard) or if nothing is
+// missing.
+function checkW018(snapshot) {
+    const { archivedVersions, documentedVersions } = snapshot.milestoneArchiveStatus.value;
+    if (archivedVersions.length === 0)
+        return [];
+    const documented = new Set(documentedVersions);
+    const missingFromRegistry = archivedVersions.filter((ver) => !documented.has(ver));
+    if (missingFromRegistry.length === 0)
+        return [];
+    return [
+        {
+            code: 'W018',
+            severity: SEVERITY.WARNING,
+            message: `MILESTONES.md missing ${missingFromRegistry.length} archived milestone(s): ${missingFromRegistry.join(', ')}`,
+            remedy: {
+                action: REMEDY_ACTION.BACKFILL_MILESTONES,
+                risk: REMEDY_RISK.NONE,
+                args: {},
+            },
+        },
+    ];
+}
+// ─── W019 — Unrecognized .planning/ root file (verify.cts:2337-2354) ───────
+//
+// Condition: for each filename in `snapshot.planningRootFiles.value` ending in
+// `.md`, call `isCanonicalPlanningFile(filename)` (bare basename, not a path —
+// `src/artifacts.cts:43`); flag any that return false. One `Diagnostic` PER
+// unrecognized file (array return), mirroring the original's `addIssue` call
+// INSIDE the `for` loop (`verify.cts:2343-2349`) — unlike W018 this is not an
+// aggregate. Fix text copied verbatim from `verify.cts:2347`.
+function checkW019(snapshot) {
+    const diagnostics = [];
+    for (const filename of snapshot.planningRootFiles.value) {
+        if (!filename.endsWith('.md'))
+            continue;
+        if ((0, artifacts_cjs_1.isCanonicalPlanningFile)(filename))
+            continue;
+        diagnostics.push({
+            code: 'W019',
+            severity: SEVERITY.WARNING,
+            message: `Unrecognized .planning/ file: ${filename} — not a canonical GSD artifact`,
+            remedy: adviseRemedy('Move to .planning/milestones/ archive subdir or delete if stale. See templates/README.md for the canonical artifact list.'),
+        });
+    }
+    return diagnostics;
+}
+// ─── Exports ────────────────────────────────────────────────────────────────
+const RULES = [
+    {
+        code: 'W018',
+        severity: SEVERITY.WARNING,
+        description: 'MILESTONES.md missing entry for archived milestone snapshot',
+        repairable: true,
+        check: checkW018,
+    },
+    {
+        code: 'W019',
+        severity: SEVERITY.WARNING,
+        description: 'Unrecognized .planning/ root file — not a canonical GSD artifact',
+        repairable: false,
+        check: checkW019,
+    },
+];
+module.exports = { RULES };

package/gsd-core/bin/lib/health-diagnostic-rules/phase-structure.cjs

@@ -0,0 +1,222 @@
+"use strict";
+/**
+ * Health Diagnostic — Phase directory structure rules (Phase 11, #3309,
+ * ADR-3180 §8.2/§8.3/§8.5).
+ *
+ * Group: "Phase directory structure" (design doc, "Rule table organization"
+ * table) — W005, W023, I001, W009.
+ *
+ * Ported behavior-preserving from `cmdValidateHealth`
+ * (`src/verify.cts:1893-1990`, the exact call sites for W005/W023/I001/W009),
+ * with two disclosed fidelity reductions forced by `PlanningSnapshot`'s
+ * current shape (see each rule's own comment below):
+ *
+ * - I001 cannot name the individual unsummarized PLAN filename (`snapshot.
+ *   phases.value[i]` exposes only `planCount`/`summaryCount`, not per-plan
+ *   filenames) — this rule reports a coarser per-PHASE message instead.
+ * - W023's original "described" list called `determinePhaseStatus`
+ *   (`commands.cts:154`), a SIX-way status string ('Not Started'/'Planned'/
+ *   'In Progress'/'Executed'/'Needs Review'/'Complete') computed from its own
+ *   raw `readdirSync` + `*-VERIFICATION.md` frontmatter read of `phaseDir`.
+ *   This rule cannot re-run that raw read (§8.1 rule 1 forbids ambient I/O in
+ *   `check`), so `derivePhaseStatusLabel` below reconstructs the same
+ *   six-way label from fields `PlanningSnapshot` already exposes —
+ *   `PhaseSnapshot.planCount`/`summaryCount` (the plan/no-plan and
+ *   in-progress/planned branches, identical inputs to the original) and
+ *   `PhaseSnapshot.complete`/`verificationStatus` (`isPhaseComplete`'s own
+ *   §7.4 disk-strict routing of the SAME `*-VERIFICATION.md` file) for the
+ *   verification-gated branches. This is a disclosed fidelity reduction, not
+ *   a byte-for-byte guarantee: `verificationStatus` is the DIFFERENT,
+ *   `readVerificationStatus`-routed vocabulary ('passed'/'gaps_found'/
+ *   'human_needed'/'stale'/'unknown'/'missing') and can disagree with a raw
+ *   frontmatter re-read in edge cases (e.g. a stale-but-frontmatter-"passed"
+ *   VERIFICATION.md routes to 'stale', not 'passed', under §7.4's staleness
+ *   handling — this rule reports 'Executed' there, not 'Complete'). No new
+ *   ambient I/O and no new `PlanningSnapshot` field were needed — every input
+ *   was already on `PhaseSnapshot`.
+ *
+ * W009's original message interpolates `${slash('plan-phase')}`
+ * (`verify.cts:1982`, ``Re-run ${slash('plan-phase')} with --research to
+ * regenerate``), a per-project runtime-resolved value (`formatGsdSlash`,
+ * `src/runtime-slash.cts`) this rule's `(snapshot) => Diagnostic[]`
+ * signature has no access to. Hardcodes the canonical `/gsd-plan-phase`
+ * hyphen form instead, mirroring the sibling "config.json validation"
+ * group's W016 rule (`src/health-diagnostic-rules/config-validation.cts`),
+ * which hardcodes `/gsd-ai-integration-phase` the same way for the
+ * identical reason.
+ *
+ * Design: .gsd/phase/refactor-3309-health-diagnostic-rule-table/40-design.md
+ *
+ * ADR-457 build-at-publish: source in
+ * src/health-diagnostic-rules/phase-structure.cts, compiled to
+ * gsd-core/bin/lib/health-diagnostic-rules/phase-structure.cjs (gitignored).
+ */
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const healthDiagnosticMod = require("../health-diagnostic-types.cjs");
+const { SEVERITY, adviseRemedy } = healthDiagnosticMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const validateMod = require("../validate.cjs");
+const { phaseDirNameRe } = validateMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const phaseIdMod = require("../phase-id.cjs");
+const { extractPhaseToken, normalizePhaseName, comparePhaseNum } = phaseIdMod;
+// ─── W005 — phase directory doesn't follow NN-name format (verify.cts:1893-1902) ─
+function checkW005(snapshot) {
+    const diagnostics = [];
+    for (const name of snapshot.phaseDirs.value) {
+        if (!name.match(phaseDirNameRe)) {
+            diagnostics.push({
+                code: 'W005',
+                severity: SEVERITY.WARNING,
+                message: `Phase directory "${name}" doesn't follow NN-name format`,
+                remedy: adviseRemedy('Rename to match pattern (e.g., 01-setup)'),
+            });
+        }
+    }
+    return diagnostics;
+}
+// ─── W023 — phase directories collide on normalized key (verify.cts:1904-1950) ─
+//
+// Groups `snapshot.phaseDirs.value` by `normalizePhaseName(extractPhaseToken(name))`
+// — the exact same two owners (`phase-id.cjs`) the original `verify.cts:1917-1918`
+// call site uses, relocated verbatim rather than reimplemented. Sorted with
+// `comparePhaseNum` + a `localeCompare` tiebreak, mirroring
+// `verify.cts:1930-1932`'s deterministic-output rationale. See the file-level
+// comment for the disclosed "described" fidelity reduction.
+/**
+ * Reconstruct `commands.cts:154`'s `determinePhaseStatus` six-way label from
+ * fields `PhaseSnapshot` already exposes (no ambient I/O, no new snapshot
+ * field — see file-level comment). `complete`/`verificationStatus` come from
+ * `isPhaseComplete`'s §7.4 disk-strict routing of the same `*-VERIFICATION.md`
+ * file the original raw read targeted.
+ */
+function derivePhaseStatusLabel(planCount, summaryCount, complete, verificationStatus) {
+    if (planCount === 0)
+        return 'Not Started';
+    if (summaryCount < planCount && summaryCount > 0)
+        return 'In Progress';
+    if (summaryCount < planCount)
+        return 'Planned';
+    // summaryCount >= planCount > 0 — verification-gated, same as the original's
+    // post-count fall-through.
+    if (complete)
+        return 'Complete';
+    if (verificationStatus === 'human_needed')
+        return 'Needs Review';
+    // gaps_found / stale / missing / unknown all land here, same as the
+    // original's "verification exists but unrecognized" and "no verification
+    // file" branches both returning 'Executed'.
+    return 'Executed';
+}
+function checkW023(snapshot) {
+    const groups = new Map();
+    for (const name of snapshot.phaseDirs.value) {
+        const token = extractPhaseToken(name);
+        const key = normalizePhaseName(token);
+        const list = groups.get(key);
+        if (list)
+            list.push(name);
+        else
+            groups.set(key, [name]);
+    }
+    const phaseByDir = new Map(snapshot.phases.value.map((p) => [p.dir, p]));
+    const diagnostics = [];
+    for (const [key, dirs] of groups) {
+        if (dirs.length < 2)
+            continue;
+        const described = dirs
+            .slice()
+            .sort((a, b) => comparePhaseNum(a, b) || String(a).localeCompare(String(b)))
+            .map((d) => {
+            const phase = phaseByDir.get(d);
+            const plans = phase ? phase.planCount : 0;
+            const summaries = phase ? phase.summaryCount : 0;
+            const complete = phase ? phase.complete : false;
+            const verificationStatus = phase ? phase.verificationStatus : 'missing';
+            const status = derivePhaseStatusLabel(plans, summaries, complete, verificationStatus);
+            return `${d} (${status})`;
+        })
+            .join(', ');
+        diagnostics.push({
+            code: 'W023',
+            severity: SEVERITY.WARNING,
+            message: `Phase directories collide on normalized key "${key}": ${described}`,
+            remedy: adviseRemedy('Inspect each directory; rename or remove the duplicate so only one directory maps to this phase key'),
+        });
+    }
+    return diagnostics;
+}
+// ─── I001 — plan(s) without a matching SUMMARY.md (verify.cts:1952-1965) ───
+//
+// GENUINE FIDELITY GAP (see file-level comment): the original is PER-PLAN
+// (`${e.name}/${plan} has no SUMMARY.md`, `plan` an individual PLAN.md
+// filename from `findUnsummarizedPlans`). `PlanningSnapshot`'s
+// `phases.value[i]` carries only `planCount`/`summaryCount` NUMBERS per
+// phase — no per-plan filenames — so this rule cannot name which plan lacks
+// a summary without reading the phase directory directly inside `check`
+// (forbidden by §8.1 rule 1). This rule instead reports one coarser
+// per-PHASE diagnostic naming the deficit count, not the individual
+// filename(s).
+function checkI001(snapshot) {
+    const diagnostics = [];
+    for (const phase of snapshot.phases.value) {
+        const deficit = phase.planCount - phase.summaryCount;
+        if (deficit > 0) {
+            diagnostics.push({
+                code: 'I001',
+                severity: SEVERITY.INFO,
+                message: `Phase ${phase.dir} has ${deficit} plan(s) without a matching summary`,
+                remedy: adviseRemedy('May be in progress'),
+            });
+        }
+    }
+    return diagnostics;
+}
+// ─── W009 — Validation Architecture in RESEARCH.md but no VALIDATION.md ────
+// (verify.cts:1967-1990)
+function checkW009(snapshot) {
+    const diagnostics = [];
+    for (const entry of snapshot.researchValidationStatus.value) {
+        if (entry.hasValidationArchitecture && !entry.hasValidationMd) {
+            diagnostics.push({
+                code: 'W009',
+                severity: SEVERITY.WARNING,
+                message: `Phase ${entry.dir}: has Validation Architecture in RESEARCH.md but no VALIDATION.md`,
+                remedy: adviseRemedy('Re-run /gsd-plan-phase with --research to regenerate'),
+            });
+        }
+    }
+    return diagnostics;
+}
+// ─── Exports ────────────────────────────────────────────────────────────────
+const RULES = [
+    {
+        code: 'W005',
+        severity: SEVERITY.WARNING,
+        description: 'Phase directory naming mismatch',
+        repairable: false,
+        check: checkW005,
+    },
+    {
+        code: 'W023',
+        severity: SEVERITY.WARNING,
+        description: 'Phase directories collide on normalized key',
+        repairable: false,
+        check: checkW023,
+    },
+    {
+        code: 'I001',
+        severity: SEVERITY.INFO,
+        description: 'Plan without SUMMARY (may be in progress)',
+        repairable: false,
+        check: checkI001,
+    },
+    {
+        code: 'W009',
+        severity: SEVERITY.WARNING,
+        description: 'Phase has Validation Architecture in RESEARCH.md but no VALIDATION.md',
+        repairable: false,
+        check: checkW009,
+    },
+];
+module.exports = { RULES };

package/gsd-core/bin/lib/health-diagnostic-rules/roadmap-disk-consistency.cjs

@@ -0,0 +1,265 @@
+"use strict";
+/**
+ * Health Diagnostic — ROADMAP/disk consistency rules (Phase 11, #3309,
+ * ADR-3180 §8.2/§8.3/§8.5).
+ *
+ * Group: "ROADMAP/disk consistency" (design doc, "Rule table organization"
+ * table) — W006, W007.
+ *
+ * Ported behavior-preserving from `cmdValidateHealth`
+ * (`src/verify.cts:2029-2101`, the exact call sites for W006/W007).
+ *
+ * Both rules share ONE matcher — `matchPhaseDirs` + `normalizePhaseName`
+ * (`src/phase-id.cts`), the same canonical directory-resolution owner
+ * `verify.cts:2060/2073` already calls (its own #2528 comment explains why:
+ * pairing roadmap phases against disk by intersecting independently-derived
+ * TOKEN SETS mislabels digit-leading slugs like `05-80-20-cleanup` in BOTH
+ * directions at once — phase 5 reads as missing a directory (W006) AND that
+ * directory reads as not in the roadmap (W007) — so both rules here resolve
+ * through `matchPhaseDirs`, never a hand-rolled string/token comparison, and
+ * `dirsForPhase` below is the single call site both go through, so they
+ * cannot independently drift on what "matches" means (#2528's own bug
+ * class).
+ *
+ * DISK-SIDE SOURCE — `allPhaseDirNames`, NOT `phaseDirs` (found while
+ * implementing this file, fixed inline rather than deferred).
+ * `snapshot.phaseDirs` (Phase 10, `listMilestonePhaseDirs`) is WINDOWED: its
+ * `inWindow` filter (`getMilestonePhaseFilter`, `src/roadmap-parser.cts:1220`)
+ * admits a directory only when its phase id is a MEMBER of the roadmap's
+ * current-milestone-declared phase set (`isDirInMilestone`). That makes
+ * `phaseDirs.value` a subset that, by construction, can never contain a
+ * directory the roadmap does NOT declare — exactly the directory W007 exists
+ * to find. Sourced from `phaseDirs`, W007 would be structurally inert: every
+ * member of the set is already provably claimable. Verified empirically
+ * (`node -e` trace against a real `buildPlanningSnapshot`): a genuine orphan
+ * directory (`04-extra`, no roadmap entry) was silently absent from
+ * `phaseDirs.value` and W007 fired zero diagnostics. `phaseDirs`'s windowing
+ * also risks a W006 false positive for a phase declared in a NON-current
+ * milestone section (`roadmapDeclaredPhases` is built from the FULL raw
+ * ROADMAP, all milestones — `src/planning-snapshot.cts:398-436` — while
+ * `phaseDirs` is scoped to the current milestone only), so both rules here
+ * use the new, additive `allPhaseDirNames` field
+ * (`src/planning-snapshot.cts`) instead: every directory actually present
+ * under the active `phases/` root, unfiltered by roadmap declaration.
+ * Archived-milestone directory names (`verify.cts:2050`,
+ * `collectArchivedPhaseDirNames`) are still not exposed as directory NAMES
+ * on `PlanningSnapshot`, but the equivalent TOKEN set is: `checkW006` below
+ * additionally consults `snapshot.archivedPhaseTokens` (added for the
+ * W002/state-consistency group's #3652 fix, reused verbatim here — see that
+ * field's own doc comment) so a phase whose only directory lives in a
+ * milestone archive (shipped OR the current milestone's own archive layout)
+ * no longer reads as W006-missing (Bug 1, found post-migration: the archived
+ * fixtures under `tests/milestone-archive.test.cjs` and
+ * `tests/verify-health.test.cjs` regressed against the pre-migration
+ * `verify.cts` behavior). W007 still never scans archived dirs (its loop is
+ * `allPhaseDirNames.value`, the active `phases/` root only), so an archived
+ * dir still cannot spuriously read as W007-orphaned either — unchanged.
+ *
+ * Bug 2 (found alongside Bug 1): `dirsForPhase` below also runs a
+ * `phaseVariants()`-based fallback when `matchPhaseDirs` finds nothing — see
+ * its own doc comment. Pre-migration, `verify.cts:2071-2073`/`2092-2093` ran
+ * this as a SECOND, independent check the migrated matchPhaseDirs-only path
+ * had dropped, causing a false W006/W007 whenever ROADMAP and disk spelled
+ * the same phase with a different zero-padding (e.g. ROADMAP "01A" vs disk
+ * "1A-...").
+ *
+ * Not-started exclusion (verify.cts:2065/2075-2076,
+ * `buildNotStartedPhaseVariants`, `src/validate.cts:160`): the design doc's
+ * field table assigns this group only `roadmapDeclaredPhases`/`phaseDirs`,
+ * and `roadmapDeclaredPhases` (`src/planning-snapshot.cts:398-436`) does
+ * NOT filter not-started phases out — it returns every heading- and
+ * checklist-declared phase id regardless of checked state (confirmed by
+ * direct read: its `buildRoadmapPhaseVariants` call includes BOTH `[x]` and
+ * `[ ]` checklist entries). Omitting the exclusion here would regress a
+ * COMMON case: `gsd-core/templates/roadmap.md`'s "Initial Roadmap" shape
+ * declares every phase as an unchecked `- [ ] **Phase N: [Name]**` checklist
+ * item before any phase directory exists, so a freshly created ROADMAP.md
+ * would immediately spam one W006 per phase. `snapshot.roadmapPhaseCheckboxes`
+ * (`src/planning-snapshot.cts:457-480`, backs W011 in the STATE.md-consistency
+ * group) already parses exactly this `[x]`/`[ ]` state — `check(snapshot)`'s
+ * signature grants the full snapshot, not just this group's assigned column,
+ * so `isPhaseNotStarted` below reads it directly rather than re-deriving a
+ * third independent regex over raw ROADMAP text (forbidden by §8.1 rule 2).
+ * KNOWN GAP, disclosed rather than silently dropped: `roadmapPhaseCheckboxes`
+ * is keyed by `PHASE_NUMBER_TOKEN_SOURCE` (`phase-id.cts:54`, no dash), so a
+ * milestone-dash-prefixed phase id ("2-01") can never match a checkbox key —
+ * unlike the original `buildNotStartedPhaseVariants`, which captures the
+ * fuller `[\w][\w.-]*` grammar (dashes included). For that id shape only,
+ * this rule's not-started exclusion silently no-ops (never excludes), which
+ * is the conservative direction (a possible false W006, not a suppressed
+ * true one).
+ *
+ * Design: .gsd/phase/refactor-3309-health-diagnostic-rule-table/40-design.md
+ *
+ * ADR-457 build-at-publish: source in
+ * src/health-diagnostic-rules/roadmap-disk-consistency.cts, compiled to
+ * gsd-core/bin/lib/health-diagnostic-rules/roadmap-disk-consistency.cjs
+ * (gitignored).
+ */
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const healthDiagnosticMod = require("../health-diagnostic-types.cjs");
+const { SEVERITY, adviseRemedy } = healthDiagnosticMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planningScopeMod = require("../planning-scope.cjs");
+const { SCOPE } = planningScopeMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const phaseIdMod = require("../phase-id.cjs");
+const { matchPhaseDirs, normalizePhaseName, extractPhaseToken, isSentinelPhaseId } = phaseIdMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const validateMod = require("../validate.cjs");
+const { phaseVariants } = validateMod;
+// ─── Shared matcher — the single call site both W006 and W007 go through ───
+/**
+ * Every on-disk directory (from `allPhaseDirNames.value`) that `phaseId`
+ * resolves to via the canonical `matchPhaseDirs` selection. Both `checkW006`
+ * (does ANY directory resolve) and `computeClaimedDirs` (which directories
+ * does the roadmap claim, for W007) call this — one matcher, reused, per the
+ * file-level comment.
+ */
+function dirsForPhase(dirs, phaseId) {
+    const canonical = matchPhaseDirs(dirs, normalizePhaseName(phaseId)).matches;
+    if (canonical.length > 0)
+        return canonical;
+    // Bug 2 (#3309 W006/W007 migration cluster, found while fixing the
+    // originally-reported archived-directory gap): `matchPhaseDirs`'s
+    // `phaseTokenMatches` compares `extractPhaseToken(dir)` (the directory's
+    // LITERAL, un-normalized digit run — e.g. "1A" for `1A-suffix-phase`)
+    // against `normalizePhaseName(phaseId)` (which PADS — "01A") case-
+    // insensitively, but never unifies a padding/letter-suffix mismatch
+    // BETWEEN the two sides: "1A" !== "01A" even though they name the same
+    // phase. Pre-migration, `verify.cts:2071-2073`/`2092-2093` ran a SECOND,
+    // independent check here — `[...phaseVariants(p)].some((v) =>
+    // diskPhases.has(v))` — that the migrated matchPhaseDirs-only path
+    // dropped. `phaseVariants` (`validate.cts:101`) is symmetric
+    // (padded<->unpadded, letter-suffix preserved both ways), so generating
+    // variants from `phaseId` and checking raw-disk-token membership is
+    // equivalent to intersecting `phaseVariants(phaseId)` with
+    // `phaseVariants(diskToken)` — variants always include their own input
+    // verbatim, so this fallback catches exactly the cases `matchPhaseDirs`
+    // alone misses without re-deriving a second matcher.
+    const variants = phaseVariants(phaseId);
+    return dirs.filter((d) => {
+        const token = extractPhaseToken(d).toUpperCase();
+        for (const variant of variants) {
+            if (token === variant.toUpperCase())
+                return true;
+        }
+        return false;
+    });
+}
+/**
+ * True when `phaseId` has an unchecked (`[ ]`) checklist entry in
+ * `roadmapPhaseCheckboxes` under any of its padding/case variants
+ * (`phaseVariants`, `src/validate.cts:101` — the same variant-expansion
+ * owner `verify.cts:2071/2075` uses for this exact exclusion). See the
+ * file-level comment for the KNOWN GAP on dash-shaped ids.
+ */
+function isPhaseNotStarted(phaseId, checkboxes) {
+    for (const variant of phaseVariants(phaseId)) {
+        if (Object.prototype.hasOwnProperty.call(checkboxes, variant) && checkboxes[variant] === false) {
+            return true;
+        }
+    }
+    return false;
+}
+// ─── W006 — ROADMAP.md declares a phase with no directory on disk ─────────
+// (verify.cts:2067-2084)
+function checkW006(snapshot) {
+    // Mirrors verify.cts:2029's `if (fs.existsSync(roadmapPath))` guard: ROADMAP.md
+    // absent or unreadable means the field degrades to `{value: [], scope:
+    // UNREADABLE}` (`src/planning-snapshot.cts:401-403/407-409`) and NEITHER
+    // W006 nor W007 evaluates — an empty declared-phase list must not be
+    // mistaken for "the roadmap legitimately declares zero phases" here.
+    if (snapshot.roadmapDeclaredPhases.scope !== SCOPE.COMPLETE)
+        return [];
+    const dirs = snapshot.allPhaseDirNames.value;
+    const archivedTokens = new Set(snapshot.archivedPhaseTokens.value);
+    const checkboxes = snapshot.roadmapPhaseCheckboxes.value;
+    const diagnostics = [];
+    for (const { phaseId } of snapshot.roadmapDeclaredPhases.value) {
+        // #3225: sentinel phase ids (999.x/0.x) are never-on-roadmap by
+        // convention; a sentinel heading shouldn't demand a directory.
+        if (isSentinelPhaseId(phaseId))
+            continue;
+        if (dirsForPhase(dirs, phaseId).length > 0)
+            continue;
+        // Bug 1 (#3309 W006/W007 migration cluster): a phase whose ONLY
+        // directory lives under a milestone archive
+        // (`.planning/milestones/vX.Y-phases/<phase>/`, shipped OR the current
+        // milestone's own archive layout) must not read as "no directory on
+        // disk" — mirrors `verify.cts:2038`'s
+        // `forEachArchivedPhaseToken(planBase, (token) => diskPhases.add(token))`
+        // feeding the archived-phase token set into this exact existence check.
+        // `snapshot.archivedPhaseTokens` (`src/planning-snapshot.cts`) is the
+        // same token set, reused verbatim from the W002/state-consistency
+        // group's own fix for the analogous gap — not a re-derivation.
+        if ([...phaseVariants(phaseId)].some((v) => archivedTokens.has(v)))
+            continue;
+        if (isPhaseNotStarted(phaseId, checkboxes))
+            continue;
+        diagnostics.push({
+            code: 'W006',
+            severity: SEVERITY.WARNING,
+            message: `Phase ${phaseId} in ROADMAP.md but no directory on disk`,
+            remedy: adviseRemedy('Create phase directory or remove from roadmap'),
+        });
+    }
+    return diagnostics;
+}
+// ─── W007 — an on-disk phase directory has no matching ROADMAP entry ──────
+// (verify.cts:2086-2101)
+/** Every directory in `dirs` that ANY declared roadmap phase resolves to. */
+function computeClaimedDirs(dirs, declaredPhases) {
+    const claimed = new Set();
+    for (const { phaseId } of declaredPhases) {
+        for (const dir of dirsForPhase(dirs, phaseId))
+            claimed.add(dir);
+    }
+    return claimed;
+}
+function checkW007(snapshot) {
+    // Same guard as W006 — see its comment.
+    if (snapshot.roadmapDeclaredPhases.scope !== SCOPE.COMPLETE)
+        return [];
+    const dirs = snapshot.allPhaseDirNames.value;
+    const claimedDirs = computeClaimedDirs(dirs, snapshot.roadmapDeclaredPhases.value);
+    const diagnostics = [];
+    for (const dirName of dirs) {
+        // `extractPhaseToken` is the phase-id.cts owner `PHASE_TOKEN_FROM_DIR_RE`
+        // (`src/validate.cts:73-76`) is documented to match exactly
+        // (verify.cts's original `p` key from `collectDiskPhaseEntries`,
+        // `verify.cts:1373-1397`) — same token, relocated read, not reinvented.
+        const token = extractPhaseToken(dirName);
+        // #3225: a sentinel dir on disk (999-interim, 0-drafts) is defined as
+        // never-on-roadmap; it must not trigger W007.
+        if (isSentinelPhaseId(token))
+            continue;
+        if (claimedDirs.has(dirName))
+            continue;
+        diagnostics.push({
+            code: 'W007',
+            severity: SEVERITY.WARNING,
+            message: `Phase ${token} exists on disk but not in ROADMAP.md`,
+            remedy: adviseRemedy('Add to roadmap or remove directory'),
+        });
+    }
+    return diagnostics;
+}
+// ─── Exports ────────────────────────────────────────────────────────────────
+const RULES = [
+    {
+        code: 'W006',
+        severity: SEVERITY.WARNING,
+        description: 'Phase in ROADMAP but no directory',
+        repairable: false,
+        check: checkW006,
+    },
+    {
+        code: 'W007',
+        severity: SEVERITY.WARNING,
+        description: 'Phase on disk but not in ROADMAP',
+        repairable: false,
+        check: checkW007,
+    },
+];
+module.exports = { RULES };