@opengsd/gsd-core 1.10.0 → 1.11.0

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

@@ -0,0 +1,348 @@
+"use strict";
+/**
+ * Health Diagnostic — config.json validation rules (Phase 11, #3309,
+ * ADR-3180 §8.2/§8.3/§8.5).
+ *
+ * Group: "config.json validation" (design doc, "Rule table organization"
+ * table) — W003, W004, W022 (one rule, three internal conditions), E005,
+ * W008, W016, W012, W013, W014, W015.
+ *
+ * Ported behavior-preserving from `cmdValidateHealth`'s config.json blocks
+ * (`src/verify.cts:1777-1835` for W003/W004/W022/E005,
+ * `src/verify.cts:1837-1865` for W008/W016,
+ * `src/verify.cts:2136-2191` for W012/W013/W014/W015). Every rule here reads
+ * ONLY `snapshot.config` (`{value, scope, exists}`, `src/planning-snapshot.cts`'s
+ * `buildConfigField`).
+ *
+ * W022 stays a SINGLE code across its three call sites per the design doc's
+ * "Rejected alternatives" §3: all three are variations on one question ("is
+ * `models` well-formed"), not a genuine multi-subject conflation. This rule's
+ * `checkW022` mirrors the original's exact if / else-if control flow
+ * (`verify.cts:1799-1824`): the object-shaped branch loops every `models`
+ * entry (0-N diagnostics, one per malformed entry); the non-object branch
+ * fires independently and ONLY when the object-shaped branch did not run —
+ * `models` is never checked against both.
+ *
+ * Two disclosed fidelity reductions, forced by `snapshot.config`'s shape
+ * (neither is available without violating §8.1 rule 1's "no ambient I/O in a
+ * rule's `check`"):
+ *
+ * - E005's original message interpolates the live `JSON.parse` error text
+ *   (`config.json: JSON parse error - ${err.message}`, `verify.cts:1829`).
+ *   `buildConfigField` (`src/planning-snapshot.cts:268-281`) catches and
+ *   discards that error, collapsing an unparseable config.json to
+ *   `{value: null, scope: UNREADABLE, exists: true}` with no error text
+ *   anywhere in the snapshot. This rule's message drops the interpolated
+ *   suffix rather than fabricate error text the snapshot never carried.
+ * - W016's original message interpolates `${slash('ai-integration-phase')}`
+ *   (`verify.cts:1856`), 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-ai-integration-phase` hyphen form instead, mirroring the sibling
+ *   "Phase directory structure" group's W009 rule
+ *   (`src/health-diagnostic-rules/phase-structure.cts`), which hardcodes
+ *   `/gsd-plan-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/config-validation.cts, compiled to
+ * gsd-core/bin/lib/health-diagnostic-rules/config-validation.cjs (gitignored).
+ */
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- health-diagnostic-types.cjs is an export= CommonJS module
+const healthDiagnosticMod = require("../health-diagnostic-types.cjs");
+const { SEVERITY, REMEDY_ACTION, REMEDY_RISK, adviseRemedy } = healthDiagnosticMod;
+const model_catalog_cjs_1 = require("../model-catalog.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planningScopeMod = require("../planning-scope.cjs");
+const { SCOPE } = planningScopeMod;
+// verify.cts:2141 — inlined literal, not exported from anywhere; same list.
+const VALID_BRANCHING_STRATEGIES = ['none', 'phase', 'milestone'];
+// ─── W003 — config.json not found (verify.cts:1777-1785) ───────────────────
+function checkW003(snapshot) {
+    if (snapshot.config.exists)
+        return [];
+    return [
+        {
+            code: 'W003',
+            severity: SEVERITY.WARNING,
+            message: 'config.json not found',
+            remedy: { action: REMEDY_ACTION.CREATE_CONFIG, risk: REMEDY_RISK.NONE, args: {} },
+        },
+    ];
+}
+// ─── E005 — config.json JSON parse error (verify.cts:1825-1834) ────────────
+//
+// `exists: true, value: null` is exactly `buildConfigField`'s "present but
+// unparseable" contract (planning-snapshot.cts:268-281) — the same
+// discriminator that separates this from W003's "absent" case.
+function checkE005(snapshot) {
+    if (!snapshot.config.exists || snapshot.config.value !== null)
+        return [];
+    return [
+        {
+            code: 'E005',
+            severity: SEVERITY.ERROR,
+            message: 'config.json: JSON parse error',
+            remedy: { action: REMEDY_ACTION.RESET_CONFIG, risk: REMEDY_RISK.DESTRUCTIVE, args: {} },
+        },
+    ];
+}
+// ─── W004 — invalid model_profile (verify.cts:1790-1797) ───────────────────
+function checkW004(snapshot) {
+    const value = snapshot.config.value;
+    if (!value)
+        return [];
+    const profile = value['model_profile'];
+    if (profile && !model_catalog_cjs_1.VALID_PROFILES.includes(profile)) {
+        return [
+            {
+                code: 'W004',
+                severity: SEVERITY.WARNING,
+                message: `config.json: invalid model_profile "${profile}"`,
+                remedy: adviseRemedy(`Valid values: ${model_catalog_cjs_1.VALID_PROFILES.join(', ')}`),
+            },
+        ];
+    }
+    return [];
+}
+// ─── W008 — workflow.nyquist_validation absent (verify.cts:1841-1851) ──────
+function checkW008(snapshot) {
+    const value = snapshot.config.value;
+    const workflow = value ? value['workflow'] : undefined;
+    if (workflow && workflow['nyquist_validation'] === undefined) {
+        return [
+            {
+                code: 'W008',
+                severity: SEVERITY.WARNING,
+                message: 'config.json: workflow.nyquist_validation absent (defaults to enabled but agents may skip)',
+                remedy: { action: REMEDY_ACTION.ADD_NYQUIST_KEY, risk: REMEDY_RISK.NONE, args: {} },
+            },
+        ];
+    }
+    return [];
+}
+// ─── W016 — workflow.ai_integration_phase absent (verify.cts:1852-1861) ────
+function checkW016(snapshot) {
+    const value = snapshot.config.value;
+    const workflow = value ? value['workflow'] : undefined;
+    if (workflow && workflow['ai_integration_phase'] === undefined) {
+        return [
+            {
+                code: 'W016',
+                severity: SEVERITY.WARNING,
+                message: 'config.json: workflow.ai_integration_phase absent (defaults to enabled — run /gsd-ai-integration-phase before planning AI system phases)',
+                remedy: { action: REMEDY_ACTION.ADD_AI_INTEGRATION_PHASE_KEY, risk: REMEDY_RISK.NONE, args: {} },
+            },
+        ];
+    }
+    return [];
+}
+// ─── W012 — invalid branching_strategy (verify.cts:2141-2152) ──────────────
+function checkW012(snapshot) {
+    const value = snapshot.config.value;
+    if (!value)
+        return [];
+    const strategy = value['branching_strategy'];
+    if (strategy && !VALID_BRANCHING_STRATEGIES.includes(strategy)) {
+        return [
+            {
+                code: 'W012',
+                severity: SEVERITY.WARNING,
+                message: `config.json: invalid branching_strategy "${strategy}"`,
+                remedy: adviseRemedy(`Valid values: ${VALID_BRANCHING_STRATEGIES.join(', ')}`),
+            },
+        ];
+    }
+    return [];
+}
+// ─── W013 — context_window not a positive integer (verify.cts:2154-2164) ───
+function checkW013(snapshot) {
+    const value = snapshot.config.value;
+    if (!value)
+        return [];
+    const cw = value['context_window'];
+    if (cw !== undefined && (typeof cw !== 'number' || cw <= 0 || !Number.isInteger(cw))) {
+        return [
+            {
+                code: 'W013',
+                severity: SEVERITY.WARNING,
+                message: `config.json: context_window should be a positive integer, got "${cw}"`,
+                remedy: adviseRemedy('Set to 200000 (default) or 1000000 (for 1M models)'),
+            },
+        ];
+    }
+    return [];
+}
+// ─── W014 — phase_branch_template missing {phase} (verify.cts:2166-2176) ───
+function checkW014(snapshot) {
+    const value = snapshot.config.value;
+    if (!value)
+        return [];
+    const tmpl = value['phase_branch_template'];
+    if (tmpl && !tmpl.includes('{phase}')) {
+        return [
+            {
+                code: 'W014',
+                severity: SEVERITY.WARNING,
+                message: 'config.json: phase_branch_template missing {phase} placeholder',
+                remedy: adviseRemedy('Template must include {phase} for phase number substitution'),
+            },
+        ];
+    }
+    return [];
+}
+// ─── W015 — milestone_branch_template missing {milestone} (verify.cts:2177-2187) ─
+function checkW015(snapshot) {
+    const value = snapshot.config.value;
+    if (!value)
+        return [];
+    const tmpl = value['milestone_branch_template'];
+    if (tmpl && !tmpl.includes('{milestone}')) {
+        return [
+            {
+                code: 'W015',
+                severity: SEVERITY.WARNING,
+                message: 'config.json: milestone_branch_template missing {milestone} placeholder',
+                remedy: adviseRemedy('Template must include {milestone} for version substitution'),
+            },
+        ];
+    }
+    return [];
+}
+// ─── W022 — models malformed, 3 internal conditions (verify.cts:1798-1824) ─
+//
+// Mirrors the original if / else-if chain exactly: the object-shaped branch
+// (a: unknown phase type, b: invalid tier value) loops every `models` entry,
+// pushing 0-N diagnostics; the non-object branch (c) is an ELSE-IF, so it
+// only runs when `models` is truthy but did NOT satisfy "object, not array" —
+// (a)/(b) are never evaluated against a non-object `models`.
+function checkW022(snapshot) {
+    const value = snapshot.config.value;
+    if (!value)
+        return [];
+    const diagnostics = [];
+    const configModels = value['models'];
+    if (configModels && typeof configModels === 'object' && !Array.isArray(configModels)) {
+        for (const [phaseType, tierValue] of Object.entries(configModels)) {
+            if (!model_catalog_cjs_1.VALID_PHASE_TYPES.has(phaseType)) {
+                diagnostics.push({
+                    code: 'W022',
+                    severity: SEVERITY.WARNING,
+                    message: `config.json: models has an unknown phase type "${phaseType}" which will be ignored`,
+                    remedy: adviseRemedy(`Valid phase types: ${[...model_catalog_cjs_1.VALID_PHASE_TYPES].join(', ')}`),
+                });
+            }
+            else if (typeof tierValue !== 'string' || !model_catalog_cjs_1.VALID_TIERS.has(tierValue)) {
+                diagnostics.push({
+                    code: 'W022',
+                    severity: SEVERITY.WARNING,
+                    message: `config.json: models.${phaseType} has an invalid tier value ${JSON.stringify(tierValue)} which will be ignored`,
+                    remedy: adviseRemedy(`Valid tiers: ${[...model_catalog_cjs_1.VALID_TIERS].join(', ')}`),
+                });
+            }
+        }
+    }
+    else if (configModels !== undefined && configModels !== null) {
+        diagnostics.push({
+            code: 'W022',
+            severity: SEVERITY.WARNING,
+            message: `config.json: models is set to ${JSON.stringify(configModels)}, but must be an object mapping phase types to tiers — this value will be ignored`,
+            remedy: adviseRemedy('Set models to an object like {"planning": "sonnet"}, or remove the key to use profile defaults'),
+        });
+    }
+    return diagnostics;
+}
+// ─── W029 — `.planning/` ignored but still tracked (#3586, epic #2292) ─────
+//
+// Not a config.json-sourced check (unlike every other rule in this file) —
+// registered here per the phase brief rather than in a new file, reading
+// only `snapshot.planningTracked` (`src/planning-snapshot.cts`'s
+// `buildPlanningTrackedField`). Fires ONLY when the probe's scope is
+// COMPLETE and both `ignored` and `tracked` are true: `.gitignore` has no
+// effect on files git already tracks, so a project that committed
+// `.planning/` before ignoring it keeps staging those files forever even
+// though `commit_docs` correctly auto-resolves `false`. Any other COMPLETE
+// combination (most importantly `ignored: false, tracked: true` — the
+// default, healthy state of every normal project) is silent; a degraded
+// (non-COMPLETE) scope is ALSO silent — a probe that could not run must
+// never manufacture a finding. ADVISE-only: auto-untracking is destructive
+// and outside this phase's stated boundary (design doc, "Rejected" #3).
+function checkW029(snapshot) {
+    const field = snapshot.planningTracked;
+    if (!field || field.scope !== SCOPE.COMPLETE)
+        return [];
+    if (!field.value.ignored || !field.value.tracked)
+        return [];
+    return [
+        {
+            code: 'W029',
+            severity: SEVERITY.WARNING,
+            message: '.planning/ matches a gitignore rule but is still tracked by git — .gitignore has no effect on already-tracked files, so staging keeps picking them up',
+            remedy: adviseRemedy('Run `git rm -r --cached .planning/` to untrack it (the ignore rule then takes effect); this does not delete the files on disk'),
+        },
+    ];
+}
+// ─── Exports ────────────────────────────────────────────────────────────────
+const RULES = [
+    { code: 'W003', severity: SEVERITY.WARNING, description: 'config.json not found', repairable: true, check: checkW003 },
+    { code: 'E005', severity: SEVERITY.ERROR, description: 'config.json parse error', repairable: false, check: checkE005 },
+    { code: 'W004', severity: SEVERITY.WARNING, description: 'config.json invalid field value', repairable: false, check: checkW004 },
+    {
+        code: 'W008',
+        severity: SEVERITY.WARNING,
+        description: 'config.json: workflow.nyquist_validation absent (defaults to enabled but agents may skip)',
+        repairable: true,
+        check: checkW008,
+    },
+    {
+        code: 'W016',
+        severity: SEVERITY.WARNING,
+        description: 'config.json: workflow.ai_integration_phase absent (defaults to enabled but agents may skip AI-integration-phase planning)',
+        repairable: true,
+        check: checkW016,
+    },
+    {
+        code: 'W012',
+        severity: SEVERITY.WARNING,
+        description: 'config.json invalid branching_strategy value',
+        repairable: false,
+        check: checkW012,
+    },
+    {
+        code: 'W013',
+        severity: SEVERITY.WARNING,
+        description: 'config.json context_window not a positive integer',
+        repairable: false,
+        check: checkW013,
+    },
+    {
+        code: 'W014',
+        severity: SEVERITY.WARNING,
+        description: 'config.json phase_branch_template missing {phase} placeholder',
+        repairable: false,
+        check: checkW014,
+    },
+    {
+        code: 'W015',
+        severity: SEVERITY.WARNING,
+        description: 'config.json milestone_branch_template missing {milestone} placeholder',
+        repairable: false,
+        check: checkW015,
+    },
+    {
+        code: 'W022',
+        severity: SEVERITY.WARNING,
+        description: 'config.json models entry malformed (unknown phase type, invalid tier, or non-object value)',
+        repairable: false,
+        check: checkW022,
+    },
+    {
+        code: 'W029',
+        severity: SEVERITY.WARNING,
+        description: '.planning/ matches a gitignore rule but is still tracked by git (gitignore has no effect on already-tracked files)',
+        repairable: false,
+        check: checkW029,
+    },
+];
+module.exports = { RULES };

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

@@ -0,0 +1,145 @@
+"use strict";
+/**
+ * Health Diagnostic — `validate.consistency`-only rules (Phase 12, #3310,
+ * ADR-3180 §8.4).
+ *
+ * Group: "consistency" — a NEW `C0NN` code namespace, parallel to (not part
+ * of) `validate.health`'s `E`/`W`/`I` space Phase 11 minted. These four
+ * subjects are `cmdValidateConsistency`'s (`src/verify.cts:1466-1612`)
+ * own findings, not `validate.health` findings — see the design doc's
+ * "Code namespace" section for why they get their own prefix instead of
+ * competing for the next free `W0NN` number.
+ *
+ * Ported behavior-preserving from `cmdValidateConsistency`
+ * (`src/verify.cts:1504-1519` for C001, `:1570-1576` for C002, `:1584-1587`
+ * for C003, `:1596-1602` for C004) — relocated, not reinvented. The
+ * duplicate subjects `cmdValidateConsistency` also computed (phase-in-
+ * roadmap-no-dir / dir-on-disk-not-in-roadmap) are NOT here: those are
+ * W006/W007, reused verbatim from
+ * `src/health-diagnostic-rules/roadmap-disk-consistency.cts` via
+ * `health-diagnostic.cts`'s `CONSISTENCY_RULES` composition, not
+ * reimplemented in this file (design doc, "Which rules run where").
+ *
+ * All four remedies are `ADVISE` — none of these four subjects had a repair
+ * path in the pre-migration code either, matching Phase 11's own convention
+ * for message-only findings with no automated fix.
+ *
+ * Design: .gsd/phase/feat-3310-enhance-3180-the-sibling-validators-shar/40-design.md
+ * Test matrix: .gsd/phase/feat-3310-enhance-3180-the-sibling-validators-shar/50-test-matrix.md
+ *
+ * ADR-457 build-at-publish: source in src/health-diagnostic-rules/consistency.cts,
+ * compiled to gsd-core/bin/lib/health-diagnostic-rules/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 phaseIdMod = require("../phase-id.cjs");
+const { isSentinelPhaseId } = phaseIdMod;
+// ─── C001 — gap in disk phase numbering (integer sequence) ────────────────
+// (verify.cts:1504-1519)
+function checkC001(snapshot) {
+    // verify.cts:1505 — `if (config.phase_naming !== 'custom')`; the
+    // integer-sequence gap check is skipped entirely under custom phase
+    // naming, since a custom naming scheme has no integer sequence to have a
+    // gap in.
+    if (snapshot.config.value?.['phase_naming'] === 'custom')
+        return [];
+    const integerPhases = snapshot.allPhaseDirNames.value
+        // #3225: exclude sentinel phase ids (999.x/0.x) — never part of the
+        // sequential numbering, mirrors verify.cts:1510 verbatim.
+        .filter((p) => !p.includes('.') && !isSentinelPhaseId(p))
+        .map((p) => parseInt(p, 10))
+        .filter((n) => !Number.isNaN(n))
+        .sort((a, b) => a - b);
+    const diagnostics = [];
+    for (let i = 1; i < integerPhases.length; i++) {
+        if (integerPhases[i] !== integerPhases[i - 1] + 1) {
+            diagnostics.push({
+                code: 'C001',
+                severity: SEVERITY.WARNING,
+                message: `Gap in phase numbering: ${integerPhases[i - 1]} → ${integerPhases[i]}`,
+                remedy: adviseRemedy('Create the missing phase directory or renumber to close the gap'),
+            });
+        }
+    }
+    return diagnostics;
+}
+// ─── C002 — gap in plan numbering within a phase ───────────────────────────
+// (verify.cts:1570-1576)
+// Fidelity note: the original's `phaseLabel` (verify.cts:1532,
+// `posixNormalize(path.relative(planBase, phasePath))`) is a
+// `.planning/`-relative posix path, which for the flat `phases/<dir>` case
+// this rule scans reduces to the bare directory name (`phaseDir` below) —
+// same string, not a narrower one, since `perPhasePlanNumbering` only
+// enumerates the flat `phases/` root (see `PlanningSnapshot`'s own doc
+// comment on this field for the one disclosed scope reduction, an active
+// archived milestone's second phase root, which is out of scope here too).
+function checkC002(snapshot) {
+    const diagnostics = [];
+    for (const { phaseDir, planNums } of snapshot.perPhasePlanNumbering.value) {
+        for (let i = 1; i < planNums.length; i++) {
+            if (planNums[i] !== planNums[i - 1] + 1) {
+                diagnostics.push({
+                    code: 'C002',
+                    severity: SEVERITY.WARNING,
+                    message: `Gap in plan numbering in ${phaseDir}: plan ${planNums[i - 1]} → ${planNums[i]}`,
+                    remedy: adviseRemedy('Create the missing plan or renumber to close the gap'),
+                });
+            }
+        }
+    }
+    return diagnostics;
+}
+// ─── C003 — orphan SUMMARY with no matching live PLAN ──────────────────────
+// (verify.cts:1584-1587)
+function checkC003(snapshot) {
+    return snapshot.perPhaseOrphanSummaries.value.map(({ phaseDir, orphanSummary }) => ({
+        code: 'C003',
+        severity: SEVERITY.WARNING,
+        message: `Summary ${orphanSummary} in ${phaseDir} has no matching PLAN.md`,
+        remedy: adviseRemedy('Create the matching PLAN.md or remove the orphan summary'),
+    }));
+}
+// ─── C004 — PLAN missing `wave` frontmatter ────────────────────────────────
+// (verify.cts:1596-1602)
+function checkC004(snapshot) {
+    return snapshot.perPhaseWaveMissingPlans.value.map(({ phaseDir, plan }) => ({
+        code: 'C004',
+        severity: SEVERITY.WARNING,
+        message: `${phaseDir}/${plan}: missing 'wave' in frontmatter`,
+        remedy: adviseRemedy("Add a 'wave' key to the plan's frontmatter"),
+    }));
+}
+// ─── Exports ────────────────────────────────────────────────────────────────
+const RULES = [
+    {
+        code: 'C001',
+        severity: SEVERITY.WARNING,
+        description: 'Gap in disk phase numbering (integer sequence)',
+        repairable: false,
+        check: checkC001,
+    },
+    {
+        code: 'C002',
+        severity: SEVERITY.WARNING,
+        description: 'Gap in plan numbering within a phase',
+        repairable: false,
+        check: checkC002,
+    },
+    {
+        code: 'C003',
+        severity: SEVERITY.WARNING,
+        description: 'Orphan SUMMARY with no matching live PLAN',
+        repairable: false,
+        check: checkC003,
+    },
+    {
+        code: 'C004',
+        severity: SEVERITY.WARNING,
+        description: "PLAN missing 'wave' in frontmatter",
+        repairable: false,
+        check: checkC004,
+    },
+];
+module.exports = { RULES };

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