@opengsd/gsd-core 1.10.0 → 1.12.0

package/gsd-core/bin/lib/health-diagnostic-rules/install-surface-shadowing.cjs

@@ -0,0 +1,98 @@
+"use strict";
+/**
+ * Install Surface Shadowing rule (#2873, epic #2866 Phase 4a — governed by
+ * `.gsd/phase/feat-2873-cross-scope-shadowing/40-design.md`).
+ *
+ * One code, W028, surfacing `install-shadow-report.cts`'s `ShadowReport` as
+ * a `/gsd-health` diagnostic — the design doc's row #4 ("one diagnostic,
+ * severity WARNING, same projection" as the install-time report). WARNING
+ * severity, ADVISE remedy with `risk: NONE`: shadowing is never auto-fixable
+ * (there is no single correct scope to remove) so this is advisory only,
+ * mirroring `agent-install.cts`'s W010 shape.
+ *
+ * Reaches OUTSIDE the planning snapshot the same way `agent-install.cts`
+ * does for W010: `resolveRuntime(cwd)` (`runtime-slash.cjs`) resolves the
+ * runtime id from `process.env.GSD_RUNTIME` / `config.runtime` / the
+ * `'claude'` default (never throws), using `snapshot.cwd`
+ * (`planning-snapshot.cts`'s `buildPlanningSnapshot` — `path.resolve(cwd)`)
+ * as the project directory. `buildShadowReport` is then called with that
+ * `cwd` so the local scope resolves against the project actually being
+ * health-checked, while `home` is left un-injected so the resolver defaults
+ * to `os.homedir()` — the real machine, same production call shape the
+ * installer uses.
+ *
+ * `check(snapshot)` degrades to `[]` (never throws) whenever there is
+ * nothing installable to report: `buildShadowReport` itself already
+ * degrades an unresolvable runtime (`configHome.kind === 'none'`, e.g.
+ * vscode — design row #7) to `reason: RESOLVER_UNAVAILABLE`, which
+ * `renderShadowReport` renders as `[]`; the try/catch around both calls
+ * below additionally absorbs any other unexpected throw (design row D5),
+ * since this rule is advisory and must never make `/gsd-health` itself
+ * fail.
+ *
+ * Design: .gsd/phase/feat-2873-cross-scope-shadowing/40-design.md
+ *
+ * ADR-457 build-at-publish: source in
+ * src/health-diagnostic-rules/install-surface-shadowing.cts, compiled to
+ * gsd-core/bin/lib/health-diagnostic-rules/install-surface-shadowing.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 installShadowReportMod = require("../install-shadow-report.cjs");
+const { buildShadowReport, renderShadowReport } = installShadowReportMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const runtimeSlashMod = require("../runtime-slash.cjs");
+const { resolveRuntime } = runtimeSlashMod;
+const package_identity_cjs_1 = require("../package-identity.cjs");
+/**
+ * `check(snapshot)` for W028 — see module header for the degrade-to-`[]`
+ * cases and the runtime-resolution mechanism reused from `agent-install.cts`.
+ */
+function checkInstallSurfaceShadowing(snapshot) {
+    let lines;
+    let runtime;
+    try {
+        runtime = resolveRuntime(snapshot.cwd);
+        const report = buildShadowReport(runtime, { cwd: snapshot.cwd });
+        // `renderShadowReport` returns `[]` for every reason other than
+        // SCOPE_SHADOWED (design rows #1, #2, #6, #7, #8, #11), and sanitizes
+        // every `declaredRuntime` it interpolates via `sanitizeForRender`
+        // internally (`install-shadow-report.cts`) — this rule's `message`
+        // reuses that render path rather than re-sanitizing, so the
+        // sanitize-at-the-render-seam guarantee (design row #13) holds here too.
+        // Trigger names are already SAFE_STEM-gated upstream
+        // (`installed-surface-resolver.cts`'s `deriveStemsForKindEntry`) before
+        // they ever reach a rendered line — no re-gating needed here either.
+        lines = renderShadowReport(report);
+    }
+    catch {
+        // Advisory rule: an unresolvable runtime, a `configHome.kind === 'none'`
+        // runtime, or any other unexpected failure degrades to "no finding",
+        // never a thrown exception that would break `/gsd-health` itself
+        // (design row D5).
+        return [];
+    }
+    if (lines.length === 0)
+        return [];
+    return [
+        {
+            code: 'W028',
+            severity: SEVERITY.WARNING,
+            message: lines.join(' '),
+            remedy: adviseRemedy(`Review install scopes for ${runtime}: npx ${package_identity_cjs_1.PACKAGE_NAME}@latest`),
+        },
+    ];
+}
+const RULES = [
+    {
+        code: 'W028',
+        severity: SEVERITY.WARNING,
+        description: 'A GSD-owned install scope shadows another on this machine',
+        repairable: false,
+        check: checkInstallSurfaceShadowing,
+    },
+];
+module.exports = { RULES };

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 };