refactor(#3309): add root-existence health-diagnostic rules

E002, E003, E004, W001 — PROJECT.md/ROADMAP.md/STATE.md existence and
PROJECT.md section-completeness checks, migrated onto the frozen rule
table per ADR-3180 §8.2.

src/health-diagnostic-rules/root-existence.cts

@@ -0,0 +1,172 @@
+/**
+ * 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.
+ *
+ * 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 -- type-only; erased at compile time, no runtime require emitted
+import type planningSnapshotMod = require('../planning-snapshot.cjs');
+
+type PlanningSnapshot = ReturnType<typeof planningSnapshotMod.buildPlanningSnapshot>;
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+import healthDiagnosticMod = require('../health-diagnostic.cjs');
+const { SEVERITY, REMEDY_ACTION, REMEDY_RISK } = healthDiagnosticMod;
+type Diagnostic = healthDiagnosticMod.Diagnostic;
+type Rule = healthDiagnosticMod.Rule;
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+import planningScopeMod = require('../planning-scope.cjs');
+const { SCOPE } = planningScopeMod;
+
+// ─── E002 — PROJECT.md not found (verify.cts:1682) ─────────────────────────
+
+function checkE002(snapshot: PlanningSnapshot): Diagnostic[] {
+  if (snapshot.projectSections.exists) return [];
+  return [
+    {
+      code: 'E002',
+      severity: SEVERITY.ERROR,
+      message: 'PROJECT.md not found',
+      remedy: {
+        action: REMEDY_ACTION.ADVISE,
+        risk: REMEDY_RISK.NONE,
+        args: { command: '/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: PlanningSnapshot): Diagnostic[] {
+  if (snapshot.milestone.scope !== SCOPE.UNREADABLE) return [];
+  return [
+    {
+      code: 'E003',
+      severity: SEVERITY.ERROR,
+      message: 'ROADMAP.md not found',
+      remedy: {
+        action: REMEDY_ACTION.ADVISE,
+        risk: REMEDY_RISK.NONE,
+        args: { command: '/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: PlanningSnapshot): Diagnostic[] {
+  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: PlanningSnapshot): Diagnostic[] {
+  const { value } = snapshot.projectSections;
+  if (value === null) return [];
+
+  const diagnostics: Diagnostic[] = [];
+  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: {
+          action: REMEDY_ACTION.ADVISE,
+          risk: REMEDY_RISK.NONE,
+          args: { command: 'Add section manually' },
+        },
+      });
+    }
+  }
+  return diagnostics;
+}
+
+// ─── Exports ────────────────────────────────────────────────────────────────
+
+const RULES: Rule[] = [
+  { code: 'E002', severity: SEVERITY.ERROR, check: checkE002 },
+  { code: 'E003', severity: SEVERITY.ERROR, check: checkE003 },
+  { code: 'E004', severity: SEVERITY.ERROR, check: checkE004 },
+  { code: 'W001', severity: SEVERITY.WARNING, check: checkW001 },
+];
+
+export = { RULES };