@opengsd/gsd-core 1.10.0 → 1.11.0

package/gsd-core/bin/lib/health-diagnostic-rules/root-existence.cjs

@@ -0,0 +1,161 @@
+"use strict";
+/**
+ * Health Diagnostic — Root existence + PROJECT.md rules (Phase 11, #3309,
+ * ADR-3180 §8.2/§8.3/§8.5).
+ *
+ * Group: "Root existence + PROJECT.md" (design doc, "Rule table organization"
+ * table) — E002, E003, E004, W001. E001 (the `.planning/` root missing guard)
+ * stays OUTSIDE the rule table entirely per the design doc's "Two guards that
+ * stay OUTSIDE the rule table entirely" section — it is not a row here.
+ *
+ * Ported behavior-preserving from `cmdValidateHealth`
+ * (`src/verify.cts:1681-1705`), the exact call sites for E002/E003/E004/W001.
+ *
+ * E002's original message interpolates `${slash('new-project')}`
+ * (`verify.cts:1682`, ``Run ${slash('new-project')} to create``) and E003's
+ * interpolates `${slash('new-milestone')}` (`verify.cts:1694`, ``Run
+ * ${slash('new-milestone')} to create roadmap``) — both per-project
+ * runtime-resolved values (`formatGsdSlash`, `src/runtime-slash.cts`) this
+ * rule's `(snapshot) => Diagnostic[]` signature has no access to (§8.1 rule
+ * 1 forbids ambient I/O, including `cwd`, inside `check`). Hardcodes the
+ * canonical `/gsd-new-project`/`/gsd-new-milestone` 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/root-existence.cts,
+ * compiled to gsd-core/bin/lib/health-diagnostic-rules/root-existence.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;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planningScopeMod = require("../planning-scope.cjs");
+const { SCOPE } = planningScopeMod;
+// ─── E002 — PROJECT.md not found (verify.cts:1682) ─────────────────────────
+function checkE002(snapshot) {
+    if (snapshot.projectSections.exists)
+        return [];
+    return [
+        {
+            code: 'E002',
+            severity: SEVERITY.ERROR,
+            message: 'PROJECT.md not found',
+            remedy: adviseRemedy('/gsd-new-project'),
+        },
+    ];
+}
+// ─── E003 — ROADMAP.md not found (verify.cts:1694) ─────────────────────────
+//
+// Condition uses `snapshot.milestone.scope === SCOPE.UNREADABLE`
+// (`getMilestoneInfo`, `src/roadmap-parser.cts`). KNOWN AMBIGUITY (flagged in
+// this batch's report, not silently papered over): `getMilestoneInfo` returns
+// `SCOPE.UNREADABLE` for TWO distinct causes it does not otherwise
+// distinguish — (1) ROADMAP.md absent (`platformReadSync` returns `null` ->
+// synthetic `Error('missing')`, no errno, `reportUnreadableRoadmap` finds no
+// `.code` and stays silent) and (2) ROADMAP.md present but unreadable (a real
+// read fault, e.g. EACCES/EISDIR, which DOES carry an errno and fires
+// `warnUnusableInput(ROADMAP_UNREADABLE)`). Unlike `config`/`projectSections`,
+// `milestone` carries no `exists` discriminator, so this rule cannot tell the
+// two apart from the snapshot alone without adding cwd/fs access to `check`
+// (forbidden by §8.1 rule 1). This is a best-effort port of the pre-migration
+// condition (`!fs.existsSync(roadmapPath)`), which itself only asked "does
+// the file exist" — this rule now also fires (message-mismatched, but
+// error-preserving) on a present-but-corrupt ROADMAP.md.
+function checkE003(snapshot) {
+    if (snapshot.milestone.scope !== SCOPE.UNREADABLE)
+        return [];
+    return [
+        {
+            code: 'E003',
+            severity: SEVERITY.ERROR,
+            message: 'ROADMAP.md not found',
+            remedy: adviseRemedy('/gsd-new-milestone'),
+        },
+    ];
+}
+// ─── E004 — STATE.md not found (verify.cts:1697) ───────────────────────────
+//
+// Condition uses `snapshot.currentPhaseLabel.scope === SCOPE.UNREADABLE`
+// (`buildStateFields`, `src/planning-snapshot.cts:210-249`). KNOWN GAP
+// (flagged in this batch's report): `buildStateFields` collapses TWO distinct
+// causes into the same `UNREADABLE` scope with no discriminator field at
+// all — STATE.md absent (`platformReadSync` returns `null`, a real
+// non-answer, `warnUnusableInput` NOT called) and STATE.md present but
+// unreadable (any other read error, e.g. EISDIR, corruption,
+// `warnUnusableInput(STATE_UNREADABLE)` fires). Unlike `config`, there is no
+// `exists` flag on `currentPhaseLabel` (or on `PlanningSnapshot` generally)
+// to distinguish "STATE.md was never created" from "STATE.md exists but
+// could not be read" — this is a REAL gap in the current 15-field
+// `PlanningSnapshot` shape, not something this rule can work around without
+// extending that snapshot (out of this batch's scope per the brief). This
+// rule is therefore a best-effort port: it fires E004 ("STATE.md not found")
+// for both causes, exactly mirroring what `snapshot.currentPhaseLabel.scope`
+// can express today.
+//
+// Remedy is `regenerateState`, one of the two DESTRUCTIVE-risk actions (loses
+// session history, design doc "Risk assignment" section) — per §8.3 rule 3
+// `--repair` will refuse to auto-apply it once `applyRepairs`'s dispatch
+// wires this rule in; the remedy is still described (ADVISE-shaped for
+// display, per `applyRepairs`'s own contract) but never executed.
+function checkE004(snapshot) {
+    if (snapshot.currentPhaseLabel.scope !== SCOPE.UNREADABLE)
+        return [];
+    return [
+        {
+            code: 'E004',
+            severity: SEVERITY.ERROR,
+            message: 'STATE.md not found',
+            remedy: {
+                action: REMEDY_ACTION.REGENERATE_STATE,
+                risk: REMEDY_RISK.DESTRUCTIVE,
+                args: {},
+            },
+        },
+    ];
+}
+// ─── W001 — PROJECT.md missing a required section (verify.cts:1684-1690) ──
+//
+// `REQUIRED_SECTIONS` carries the exact `## `-prefixed strings
+// `verify.cts:1685` uses in its message text; membership is tested against
+// `snapshot.projectSections.value`, which `buildProjectSectionsField`
+// (`src/planning-snapshot.cts:367-381`) stores WITHOUT the `##` prefix (its
+// `/^##\s+(.+)$/gm` capture group), so each required string's own `## `
+// prefix is stripped before the membership check. `projectSections.value ===
+// null` (PROJECT.md absent OR unreadable) emits zero diagnostics — E002
+// already reports absence; this rule does not double-report it.
+const REQUIRED_SECTIONS = ['## What This Is', '## Core Value', '## Requirements'];
+function checkW001(snapshot) {
+    const { value } = snapshot.projectSections;
+    if (value === null)
+        return [];
+    const diagnostics = [];
+    for (const required of REQUIRED_SECTIONS) {
+        const heading = required.replace(/^##\s+/, '');
+        if (!value.includes(heading)) {
+            diagnostics.push({
+                code: 'W001',
+                severity: SEVERITY.WARNING,
+                message: `PROJECT.md missing section: ${required}`,
+                remedy: adviseRemedy('Add section manually'),
+            });
+        }
+    }
+    return diagnostics;
+}
+// ─── Exports ────────────────────────────────────────────────────────────────
+const RULES = [
+    { code: 'E002', severity: SEVERITY.ERROR, description: 'PROJECT.md not found', repairable: false, check: checkE002 },
+    { code: 'E003', severity: SEVERITY.ERROR, description: 'ROADMAP.md not found', repairable: false, check: checkE003 },
+    { code: 'E004', severity: SEVERITY.ERROR, description: 'STATE.md not found', repairable: false, check: checkE004 },
+    {
+        code: 'W001',
+        severity: SEVERITY.WARNING,
+        description: 'PROJECT.md missing required section',
+        repairable: false,
+        check: checkW001,
+    },
+];
+module.exports = { RULES };

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

@@ -0,0 +1,303 @@
+"use strict";
+/**
+ * Health Diagnostic Rules — STATE.md consistency group (Phase 11, #3309,
+ * ADR-3180 §8.2/§8.3/§8.5).
+ *
+ * Five rules, each a near-mechanical extraction of an already-working
+ * `addIssue` call site in `cmdValidateHealth` (Gall's Law, design doc "Rule
+ * table organization" / "Laws applied"):
+ *
+ *  - W024 (`verify.cts:1709-1729`) — STATE.md `state_head` commit-age
+ *    freshness vs. git HEAD. GENUINE GAP, deliberately NOT migrated — see the
+ *    `RULE_W024` comment below for exactly why.
+ *  - W002 (`verify.cts:1731-1774`) — STATE.md references a phase token not
+ *    declared anywhere (disk or ROADMAP).
+ *  - W011 (`verify.cts:2104-2134`) — STATE's current-phase status disagrees
+ *    with ROADMAP's `[x]` checkbox for that same phase.
+ *  - W021 (`verify.cts:2270-2299`, the FIRST `addIssue('warning', 'W021', ...)`
+ *    call site) — under the `'milestone-prefixed'` `phase_id_convention`, a
+ *    phase's integer prefix implies a different milestone than the ROADMAP
+ *    section it is actually listed under.
+ *  - W026 (`verify.cts:2356-2399`, the SECOND `addIssue('warning', 'W021', ...)`
+ *    call site — split off per the design doc's "New codes for the two split
+ *    subjects" section, since one code covering two unrelated subjects is a
+ *    genuine conflation) — STATE says the milestone is complete/archived, but
+ *    ROADMAP (scoped to that same milestone) still lists a phase with no
+ *    matching disk directory.
+ *
+ * - W002's original message interpolates `${slash('health')}`
+ *   (`verify.cts:1770`) and W011's interpolates `${slash('progress')}`
+ *   (`verify.cts:2126`) — both per-project runtime-resolved values
+ *   (`formatGsdSlash`, `src/runtime-slash.cts`) this rule's
+ *   `(snapshot) => Diagnostic[]` signature has no access to. Hardcodes the
+ *   canonical `/gsd-health`/`/gsd-progress` 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
+ */
+// Runtime values (SEVERITY/REMEDY_ACTION/REMEDY_RISK) are needed here, not
+// just types, so this is a normal (non type-only) `import ... = require(...)`
+// — unlike `health-diagnostic.cts`'s own type-only import of
+// `planning-snapshot.cjs`, which never touches that module's runtime values.
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- export= CommonJS module
+const healthDiagnosticMod = require("../health-diagnostic-types.cjs");
+const { SEVERITY, adviseRemedy } = healthDiagnosticMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const phaseIdMod = require("../phase-id.cjs");
+const { getMilestoneFromPhaseId, matchPhaseDirs, normalizePhaseName, extractPhaseToken, PHASE_NUMBER_TOKEN_SOURCE } = phaseIdMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- the single owner of the persisted status vocabulary
+const stateDocumentMod = require("../state-document.cjs");
+const { normalizeStateStatus } = stateDocumentMod;
+// ─── W024 — STATE.md commit-age freshness (DELIBERATELY INERT) ─────────────
+/**
+ * W024's real check (`verify.cts:1709-1729`) calls
+ * `readStateHeadFreshness(cwd, fm['state_head'])`, which shells out to `git
+ * log` to count commits between the frontmatter's `state_head` and the
+ * current HEAD. That is ambient I/O (git history), not `.planning/` content —
+ * confirmed against `src/planning-snapshot.cts`'s full 15-field
+ * `PlanningSnapshot` interface: no field wraps `readStateHeadFreshness` or
+ * exposes a commits-behind count.
+ *
+ * §8.1 rule 1 requires a rule's signature to be `(snapshot) => Diagnostic[]`
+ * with no ambient I/O inside `check` — so this rule does NOT call
+ * `readStateHeadFreshness` itself (that would violate the constraint the
+ * skeleton's own `Rule.check` type exists to enforce). Adding a 16th
+ * `PlanningSnapshot` field (e.g. `stateHeadFreshness: {value:
+ * {commitsBehind, stateHead}, scope}`) is the fix, but is out of this
+ * group's scope (`src/planning-snapshot.cts` is a shared file this task was
+ * not dispatched to extend).
+ *
+ * Registered here, `check` always returning `[]`, so the code table stays
+ * complete per §8.2's 1:1 invariant (every code the old `verify.cts` emitted
+ * has exactly one `Rule` entry) rather than silently dropping W024 from the
+ * table. This is a documented, deliberate deferral pending the 16th snapshot
+ * field — flagged prominently rather than quietly ported as a no-op.
+ */
+const RULE_W024 = {
+    code: 'W024',
+    severity: SEVERITY.WARNING,
+    description: 'STATE.md was written many commits ago — treat its contents as approximate',
+    repairable: false,
+    check: (_snapshot) => [],
+};
+// ─── W002 — STATE.md references an undeclared phase token ──────────────────
+/**
+ * The "valid phase" set the original code builds from
+ * `collectDiskPhases(planBase)` (disk dir tokens) + ROADMAP heading tokens +
+ * `forEachArchivedPhaseToken` (archived milestone-phase-dir tokens,
+ * `verify.cts:1748`). This rebuilds the disk+ROADMAP two-thirds from parsed
+ * snapshot fields only: `phaseDirs.value` (disk dir names, tokenized the same
+ * way `collectDiskPhaseEntries` does — via `extractPhaseToken`) and
+ * `roadmapDeclaredPhases.value.map(p => p.phaseId)` (ROADMAP-declared phase
+ * ids). Archived-phase-token coverage is NOT included — no
+ * `PlanningSnapshot` field exposes archived milestone-phase-dir tokens
+ * (confirmed against the 15-field interface). Omitting it makes this valid
+ * set a SUBSET of the original's, which can only make MORE STATE.md phase
+ * tokens look "invalid" (never fewer) — a conservative, safe direction; a
+ * project with archived phases still referenced from STATE.md is the
+ * fixture shape that would expose a false positive, and none of this
+ * group's fixtures exercise archives, so this gap is disclosed rather than
+ * silently absorbed.
+ *
+ * UPDATE (#3652): archived-phase-token coverage IS now included, via the
+ * additive `snapshot.archivedPhaseTokens` field
+ * (`src/planning-snapshot.cts`, added for this fix) — the disclosed gap
+ * above is closed; the paragraph is kept for the "conservative direction"
+ * reasoning, which still explains why every OTHER omission in this
+ * function is safe.
+ */
+function buildValidPhaseSet(snapshot) {
+    const valid = new Set();
+    for (const dir of snapshot.phaseDirs.value) {
+        const token = extractPhaseToken(dir);
+        if (token)
+            valid.add(token);
+    }
+    for (const entry of snapshot.roadmapDeclaredPhases.value) {
+        valid.add(entry.phaseId);
+    }
+    for (const token of snapshot.archivedPhaseTokens.value) {
+        valid.add(token);
+    }
+    return valid;
+}
+/** Mirrors `verify.cts:1749-1758`'s zero-padding normalization exactly. */
+function normalizePhaseTokenSet(valid) {
+    const normalized = new Set();
+    for (const p of valid) {
+        normalized.add(p);
+        const dotIdx = p.indexOf('.');
+        const head = dotIdx === -1 ? p : p.slice(0, dotIdx);
+        const tail = dotIdx === -1 ? '' : p.slice(dotIdx);
+        if (/^\d+$/.test(head)) {
+            normalized.add(head.padStart(2, '0') + tail);
+        }
+    }
+    return normalized;
+}
+const RULE_W002 = {
+    code: 'W002',
+    severity: SEVERITY.WARNING,
+    description: 'STATE.md references invalid phase',
+    repairable: false,
+    check: (snapshot) => {
+        const validPhases = buildValidPhaseSet(snapshot);
+        // Mirrors `verify.cts:1765`'s `if (normalizedValid.size > 0)` guard
+        // exactly — a project with zero declared phases emits nothing, never a
+        // false positive on every STATE.md phase mention.
+        if (validPhases.size === 0)
+            return [];
+        const normalizedValid = normalizePhaseTokenSet(validPhases);
+        const sortedValid = [...validPhases].sort((a, b) => a.localeCompare(b, undefined, { numeric: true }));
+        const diagnostics = [];
+        for (const ref of snapshot.statePhaseTokens.value) {
+            const dotIdx = ref.indexOf('.');
+            const head = dotIdx === -1 ? ref : ref.slice(0, dotIdx);
+            const tail = dotIdx === -1 ? '' : ref.slice(dotIdx);
+            const padded = /^\d+$/.test(head) ? head.padStart(2, '0') + tail : ref;
+            if (normalizedValid.has(ref) || normalizedValid.has(padded))
+                continue;
+            diagnostics.push({
+                code: 'W002',
+                severity: SEVERITY.WARNING,
+                message: `STATE.md references phase ${ref}, but only phases ${sortedValid.join(', ')} are declared`,
+                remedy: adviseRemedy('Review STATE.md manually before changing it; /gsd-health --repair will not overwrite an existing STATE.md for phase mismatches'),
+            });
+        }
+        return diagnostics;
+    },
+};
+// ─── W011 — STATE current-phase status vs. ROADMAP checkbox disagree ───────
+/**
+ * `currentPhaseLabel.value` is a prose string (e.g. `"3 of 8 (User Auth)"`),
+ * not a clean phase id — the leading integer (optionally letter-suffixed /
+ * dotted, the same `PHASE_NUMBER_TOKEN_SOURCE` grammar) is the "current
+ * phase" proxy the original `verify.cts:2109-2113` derives via its own
+ * `**Current Phase:**`/`Current Phase:` regex + `.replace(/^0+/, '')`. That
+ * literal field name does not exist in the current `state.md` template
+ * (which uses `Phase: [X] of [Y] ([Phase name])` under `## Current
+ * Position`) — `currentPhaseLabel` is the parsed owner of that exact field,
+ * so extracting its leading number is the equivalent-intent read against
+ * the template STATE.md actually ships. #3280: the label's ladder
+ * (`buildStateFields`, `src/planning-snapshot.cts`) now leads with the
+ * frontmatter `current_phase` scalar — the key `gsd-tools state update` /
+ * `state begin-phase` persist — so a bare `"2"` is the expected value on
+ * the machine-readable format, and this leading-number extraction handles
+ * it identically.
+ */
+function currentPhaseIdFromLabel(label) {
+    if (!label)
+        return null;
+    const m = label.match(new RegExp(`^0*(${PHASE_NUMBER_TOKEN_SOURCE})`));
+    return m ? m[1] : null;
+}
+const RULE_W011 = {
+    code: 'W011',
+    severity: SEVERITY.WARNING,
+    description: 'STATE.md current-phase status disagrees with ROADMAP.md checkbox',
+    repairable: false,
+    check: (snapshot) => {
+        const phaseId = currentPhaseIdFromLabel(snapshot.currentPhaseLabel.value);
+        if (phaseId === null)
+            return [];
+        const checked = snapshot.roadmapPhaseCheckboxes.value[phaseId];
+        if (checked !== true)
+            return [];
+        // #3280: the state writer persists `status` through `normalizeStateStatus`
+        // (`state.cts`'s syncStateFrontmatter), whose completion token is
+        // `completed` — an exact `'complete' || 'done'` comparison rejects the
+        // exact vocabulary the product writes and turns every legitimately
+        // completed frontmatter STATE.md into a false positive. Route the
+        // comparison through the same seam that owns the vocabulary
+        // (`state-document.cjs`'s `normalizeStateStatus`) rather than growing a
+        // second bespoke token list here.
+        const statusVal = (snapshot.stateStatus.value ?? '').trim();
+        if (normalizeStateStatus(statusVal, null) === 'completed')
+            return [];
+        return [
+            {
+                code: 'W011',
+                severity: SEVERITY.WARNING,
+                message: `STATE.md says current phase is ${phaseId} (status: ${statusVal.toLowerCase() || 'unknown'}) but ROADMAP.md shows it as [x] complete — state files may be out of sync`,
+                remedy: adviseRemedy('Run /gsd-progress to re-derive current position, or manually update STATE.md'),
+            },
+        ];
+    },
+};
+// ─── W021 — phase_id_convention integer-prefix/milestone mismatch ──────────
+const RULE_W021 = {
+    code: 'W021',
+    severity: SEVERITY.WARNING,
+    description: "Phase's integer prefix implies a different milestone than its ROADMAP section (phase_id_convention: milestone-prefixed)",
+    repairable: false,
+    check: (snapshot) => {
+        const convention = snapshot.config.value?.['phase_id_convention'];
+        if (convention !== 'milestone-prefixed')
+            return [];
+        const diagnostics = [];
+        for (const entry of snapshot.roadmapDeclaredPhases.value) {
+            // `entry.milestone === null` means the builder never found this phase
+            // heading inside any versioned (`v\d+\.\d+`) section — the original
+            // `checkMilestonePrefixMismatches` only ever iterates phases found
+            // WITHIN a section, so a phase outside any section is equivalently
+            // never checked here.
+            if (entry.milestone === null)
+                continue;
+            const expectedMilestone = getMilestoneFromPhaseId(entry.phaseId);
+            if (expectedMilestone === null || expectedMilestone === entry.milestone)
+                continue;
+            diagnostics.push({
+                code: 'W021',
+                severity: SEVERITY.WARNING,
+                message: `Phase ${entry.phaseId}: integer prefix implies ${expectedMilestone} but listed under ${entry.milestone}`,
+                remedy: adviseRemedy('gsd-tools roadmap upgrade --convention milestone-prefixed'),
+            });
+        }
+        return diagnostics;
+    },
+};
+// ─── W026 — STATE says milestone complete but ROADMAP lists unstarted phase ─
+const RULE_W026 = {
+    code: 'W026',
+    severity: SEVERITY.WARNING,
+    description: 'STATE says milestone complete but ROADMAP lists an unstarted phase for that milestone',
+    repairable: false,
+    check: (snapshot) => {
+        const statusVal = (snapshot.stateStatus.value ?? '').trim().toLowerCase();
+        if (!/milestone complete|archived/.test(statusVal))
+            return [];
+        // `currentMilestoneRoadmapPhaseIds` is already scoped to the current
+        // milestone (`extractCurrentMilestone(roadmapRaw, cwd)`, the same
+        // `<details>`/`<summary>`-tolerant owner `verify.cts:2364` used) — no
+        // separate `currentMilestone` resolution/filter needed here (see the
+        // field's own doc comment on `PlanningSnapshot` for why
+        // `roadmapDeclaredPhases`'s `milestone` attribution is the wrong fit).
+        const unstarted = [];
+        for (const phaseId of snapshot.currentMilestoneRoadmapPhaseIds.value) {
+            const normalized = normalizePhaseName(phaseId);
+            // `allPhaseDirNames` — every directory under `phases/`, UNWINDOWED by
+            // ROADMAP-declaration membership — mirrors the original's own
+            // unwindowed `phaseDirNames2` (`verify.cts:2372-2382`, a direct
+            // `readdirSync` of the phases dir), not the current-milestone-windowed
+            // `phaseDirs`.
+            const hasDirectory = matchPhaseDirs(snapshot.allPhaseDirNames.value, normalized).matches.length > 0;
+            if (!hasDirectory)
+                unstarted.push(phaseId);
+        }
+        if (unstarted.length === 0)
+            return [];
+        return [
+            {
+                code: 'W026',
+                severity: SEVERITY.WARNING,
+                message: `STATE says milestone complete but ROADMAP lists ${unstarted.length} unstarted phase(s) (e.g. Phase ${unstarted[0]})`,
+                remedy: adviseRemedy('Run validate consistency or re-run complete-milestone after verifying all phases are done'),
+            },
+        ];
+    },
+};
+// ─── Exports ────────────────────────────────────────────────────────────────
+const RULES = [RULE_W024, RULE_W002, RULE_W011, RULE_W021, RULE_W026];
+module.exports = { RULES };

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

@@ -0,0 +1,173 @@
+"use strict";
+/**
+ * Health Diagnostic — Worktree health rules (Phase 11, #3309, ADR-3180
+ * §8.2/§8.3/§8.5).
+ *
+ * Group: "Worktree health" (design doc, "Rule table organization" table) —
+ * W020 (×3 internal conditions, one subject: "the worktree health scan
+ * itself is degraded", design doc "Rejected alternatives" §3), W017 (orphan
+ * worktree), W027 (NEW — the split-off "stale worktree" subject, design
+ * doc's "New codes for the two split subjects" section).
+ *
+ * Ported behavior-preserving from `cmdValidateHealth`
+ * (`src/verify.cts:2193-2268`), the exact call sites for W020/W017/W027 (the
+ * pre-migration source still names the split-off stale-worktree site
+ * 'W017' — this batch is what actually applies the W027 split).
+ *
+ * W020's original THREE conditions were git_timed_out / git_list_failed / a
+ * per-finding 'unverified' kind, each with its own message. The first two
+ * are scan-level failures reported by `inspectWorktreeHealth`'s own `reason`
+ * field ('git_timed_out' vs 'git_list_failed' vs 'not_a_git_repo') —
+ * `planning-snapshot.cts`'s `buildWorktreeHealthField` now carries `reason`
+ * straight through on `PlanningSnapshot.worktreeHealth`, so `checkW020`
+ * below reproduces the original's exact branch-per-reason messages instead
+ * of collapsing them (a prior version of this file collapsed both into one
+ * message AND, worse, warned on 'not_a_git_repo' too — a regression, since
+ * the original silently skips a non-git cwd; see `verify.cts:2202-2217`).
+ *
+ * W027 restores the pre-migration active-worktree exclusion
+ * (`verify.cts:2233-2242`) via `PlanningSnapshot.cwd` — see `checkW027`'s own
+ * comment below for the mechanism.
+ *
+ * Design: .gsd/phase/refactor-3309-health-diagnostic-rule-table/40-design.md
+ *
+ * ADR-457 build-at-publish: source in
+ * src/health-diagnostic-rules/worktree-health.cts, compiled to
+ * gsd-core/bin/lib/health-diagnostic-rules/worktree-health.cjs (gitignored).
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_path_1 = __importDefault(require("node:path"));
+// 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;
+// ─── W020 — worktree health scan itself is degraded (verify.cts:2193-2264) ─
+//
+// ONE rule, THREE internal conditions, all the same subject ("the worktree
+// health scan itself is degraded" — design doc "Rejected alternatives" §3):
+// (a) `git worktree list` timed out (verify.cts:2202-2209), (b) `git
+// worktree list` failed outright (verify.cts:2210-2217), (c) a specific
+// 'unverified' finding (existsSync ok, statSync threw,
+// verify.cts:2256-2263). A fourth `!ok` reason, 'not_a_git_repo', and a
+// thrown exception ('exception') are DELIBERATELY silent — the original's
+// `if` ladder never matches 'not_a_git_repo', and the outer try/catch around
+// the whole block is commented "git worktree not available or not a git
+// repo — skip silently".
+function checkW020(snapshot) {
+    const diagnostics = [];
+    const { scope, reason } = snapshot.worktreeHealth;
+    const degraded = scope === SCOPE.UNREADABLE;
+    // (a) — git worktree list timed out (verify.cts:2202-2209).
+    if (degraded && reason === 'git_timed_out') {
+        diagnostics.push({
+            code: 'W020',
+            severity: SEVERITY.WARNING,
+            message: 'Worktree health check degraded: git worktree list timed out after 10s — orphan/stale worktrees could not be inspected',
+            remedy: adviseRemedy('Run: git worktree list --porcelain to diagnose; check for .git/index.lock or a hung git process'),
+        });
+    }
+    // (b) — git worktree list failed outright (verify.cts:2210-2217).
+    if (degraded && reason === 'git_list_failed') {
+        diagnostics.push({
+            code: 'W020',
+            severity: SEVERITY.WARNING,
+            message: 'Worktree health check degraded: git worktree list failed — orphan/stale worktrees could not be inspected',
+            remedy: adviseRemedy('Run: git worktree list --porcelain to diagnose; check git repository state and permissions'),
+        });
+    }
+    // (c) — per-finding 'unverified' (existsSync ok, statSync threw).
+    for (const finding of snapshot.worktreeHealth.value) {
+        if (finding.kind !== 'unverified')
+            continue;
+        diagnostics.push({
+            code: 'W020',
+            severity: SEVERITY.WARNING,
+            message: `Worktree health check degraded: could not stat ${finding.path} — presence/staleness could not be verified`,
+            remedy: adviseRemedy('Check filesystem permissions on the worktree path, or investigate why statSync failed for it'),
+        });
+    }
+    return diagnostics;
+}
+// ─── W017 — orphan git worktree (verify.cts:2222-2229) ─────────────────────
+//
+// `finding.kind === 'orphan'` — path no longer exists on disk. One
+// Diagnostic per orphan finding. Remedy mirrors the exact original literal
+// fix, `verify.cts:2227`: `'Run: git worktree prune'`.
+function checkW017(snapshot) {
+    const diagnostics = [];
+    for (const finding of snapshot.worktreeHealth.value) {
+        if (finding.kind !== 'orphan')
+            continue;
+        diagnostics.push({
+            code: 'W017',
+            severity: SEVERITY.WARNING,
+            message: `Orphan git worktree: ${finding.path} (path no longer exists on disk)`,
+            remedy: adviseRemedy('git worktree prune'),
+        });
+    }
+    return diagnostics;
+}
+// ─── W027 — stale git worktree (verify.cts:2232-2249, the split-off half of
+// the pre-migration 'W017' site) ─────────────────────────────────────────
+//
+// `finding.kind === 'stale'` — age-based. Excludes the active session's own
+// worktree, restored via `snapshot.cwd` (see module doc, gap 2 — RESOLVED):
+// a 'stale' finding is skipped when `snapshot.cwd` equals the finding's path
+// or is nested under it, the exact comparison `verify.cts:2238-2241` made
+// against `process.cwd()`. Per this batch's brief: the interpolated command
+// (with the real path) lives in `message`; `remedy.args.command` stays a
+// static `<path>` template, mirroring the split the brief specifies.
+function checkW027(snapshot) {
+    const diagnostics = [];
+    const activeCwd = snapshot.cwd;
+    for (const finding of snapshot.worktreeHealth.value) {
+        if (finding.kind !== 'stale')
+            continue;
+        const normalizedWorktree = node_path_1.default.resolve(finding.path);
+        const isActiveWorktree = activeCwd === normalizedWorktree || activeCwd.startsWith(normalizedWorktree + node_path_1.default.sep);
+        if (isActiveWorktree)
+            continue;
+        diagnostics.push({
+            code: 'W027',
+            severity: SEVERITY.WARNING,
+            // #3280: staleness is a pure mtime heuristic and carries no information
+            // about whether the tree is clean — git's own refusal of a non-forced
+            // removal on a dirty tree is the safety net, so the remediation must
+            // direct the operator (or an agent executing this literally) to check
+            // for uncommitted work FIRST and keep `--force` an explicit discard
+            // opt-in, never the default instruction.
+            message: `Stale git worktree: ${finding.path} (last modified ${finding.ageMinutes} minutes ago). Inspect uncommitted work first: git -C ${finding.path} status --porcelain; if clean run: git worktree remove ${finding.path}; only add --force to discard changes`,
+            remedy: adviseRemedy('git -C <path> status --porcelain; if clean: git worktree remove <path>; add --force only to discard changes'),
+        });
+    }
+    return diagnostics;
+}
+// ─── Exports ────────────────────────────────────────────────────────────────
+const RULES = [
+    {
+        code: 'W020',
+        severity: SEVERITY.WARNING,
+        description: 'Worktree health scan degraded — git worktree list timed out, failed, or a finding could not be verified',
+        repairable: false,
+        check: checkW020,
+    },
+    {
+        code: 'W017',
+        severity: SEVERITY.WARNING,
+        description: 'Orphan git worktree (path no longer exists on disk)',
+        repairable: false,
+        check: checkW017,
+    },
+    {
+        code: 'W027',
+        severity: SEVERITY.WARNING,
+        description: 'Stale git worktree (not modified in a long time)',
+        repairable: false,
+        check: checkW027,
+    },
+];
+module.exports = { RULES };