@opengsd/gsd-core 1.10.0 → 1.12.0

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,187 @@
+"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).
+ */
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const shellCmdProjection = require("../shell-command-projection.cjs");
+// 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.
+// ─── #3663 — path-comparison provenance helper ─────────────────────────────
+//
+// snapshot.cwd is raw process-cwd-derived — path.resolve() normalizes
+// separators and relative segments but NOT casing, and a process launched via
+// a differently-cased path echoes that spelling back. finding.path is
+// `git worktree list`-derived, which self-normalizes to the canonical
+// on-disk casing (forward slashes). Comparing those two spellings strictly
+// misclassifies the ACTIVE worktree as stale on win32 — so the comparison
+// folds case ONLY on win32 (case-insensitive filesystem, via the Shell
+// Command Projection seam's toComparablePathKey — the platform-conditional
+// fold policy lives there, not per call site) and stays case-sensitive on
+// POSIX, where differently-cased paths are genuinely different directories.
+// No realpath resolution — that would change symlink matching behavior.
+function isActiveWorktreePath(activeCwd, worktreePath, platform = process.platform) {
+    const active = shellCmdProjection.toComparablePathKey(activeCwd, platform);
+    const worktree = shellCmdProjection.toComparablePathKey(worktreePath, platform);
+    return active === worktree || active.startsWith(worktree + '/');
+}
+function checkW027(snapshot) {
+    const diagnostics = [];
+    const activeCwd = snapshot.cwd;
+    for (const finding of snapshot.worktreeHealth.value) {
+        if (finding.kind !== 'stale')
+            continue;
+        if (isActiveWorktreePath(activeCwd, finding.path))
+            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, isActiveWorktreePath };

package/gsd-core/bin/lib/health-diagnostic-types.cjs

@@ -0,0 +1,68 @@
+"use strict";
+/**
+ * Health Diagnostic Types — shared, dependency-free rule-table types (Phase
+ * 11, #3309, ADR-3180 §8.2/§8.3/§8.5).
+ *
+ * Split out from `src/health-diagnostic.cts` to break a CJS circular
+ * dependency between the evaluator and its own rule-group files
+ * (`src/health-diagnostic-rules/*.cts`): those files need the frozen
+ * `SEVERITY`/`REMEDY_ACTION`/`REMEDY_RISK` enums and the `Diagnostic`/
+ * `Remedy`/`Rule` shapes, but the evaluator (`health-diagnostic.cts`) also
+ * needs to `require()` every rule-group file to populate its `RULES` array —
+ * a rule-group file requiring `health-diagnostic.cjs` back, mid-load, reads
+ * `module.exports` before it is assigned, so the destructured enums come
+ * back `undefined`. This leaf has NO runtime dependency on anything in that
+ * cycle, so both sides can depend on it directly.
+ *
+ * Design: .gsd/phase/refactor-3309-health-diagnostic-rule-table/40-design.md
+ * Test matrix: .gsd/phase/refactor-3309-health-diagnostic-rule-table/50-test-matrix.md
+ *
+ * ADR-457 build-at-publish: source in src/health-diagnostic-types.cts,
+ * compiled to gsd-core/bin/lib/health-diagnostic-types.cjs (gitignored).
+ */
+// ─── Severity ───────────────────────────────────────────────────────────────
+const SEVERITY = Object.freeze({
+    ERROR: 'error',
+    WARNING: 'warning',
+    INFO: 'info',
+});
+// ─── Remedy action / risk ───────────────────────────────────────────────────
+// Harvested from health.md's published table + the corrected 6-action
+// implementation (`src/verify.cts:2405-2553`) — not 5; `addAiIntegrationPhaseKey`
+// (verify.cts:1860/2481-2502) was live in code, missing from docs (design
+// doc, "Ground truth vs. issue #3309's claims" section).
+const REMEDY_ACTION = Object.freeze({
+    CREATE_CONFIG: 'createConfig',
+    RESET_CONFIG: 'resetConfig',
+    REGENERATE_STATE: 'regenerateState',
+    ADD_NYQUIST_KEY: 'addNyquistKey',
+    ADD_AI_INTEGRATION_PHASE_KEY: 'addAiIntegrationPhaseKey',
+    BACKFILL_MILESTONES: 'backfillMilestones',
+    // §8.3 rule 5 — every non-repairable finding's `fix` string becomes an
+    // ADVISE payload; ADVISE never acts, only describes.
+    ADVISE: 'advise',
+});
+const REMEDY_RISK = Object.freeze({
+    NONE: 'none',
+    DESTRUCTIVE: 'destructive',
+});
+// ─── adviseRemedy — shared ADVISE-remedy builder ───────────────────────────
+/**
+ * Every rule-group file needs the same `{action: ADVISE, risk: NONE, args:
+ * {command}}` shape for a non-repairable finding's `fix` string (§8.3 rule
+ * 5). Was defined identically in `config-validation.cts` and
+ * `agent-install.cts`, and repeated inline elsewhere — moved to this shared,
+ * dependency-free leaf so every rule-group file imports one implementation
+ * instead of duplicating it.
+ */
+function adviseRemedy(command) {
+    return { action: REMEDY_ACTION.ADVISE, risk: REMEDY_RISK.NONE, args: { command } };
+}
+// ─── Exports ────────────────────────────────────────────────────────────────
+const healthDiagnosticTypes = {
+    SEVERITY,
+    REMEDY_ACTION,
+    REMEDY_RISK,
+    adviseRemedy,
+};
+module.exports = healthDiagnosticTypes;