feat(#2873): detect cross-scope shadowing and reach the local spec tree

4a - the detection floor. A shadowed install now reports which triggers are
shadowed and which scope wins, at install time and through a new W028
/gsd-health diagnostic. Exit codes are untouched: a shadowed install is a
warning, not a failure. Only triggers whose stem exists at BOTH scopes are
reported, so a global full profile beside a local core profile no longer
names local artifacts the user does not have.

4b - spec-root reachability, claude runtime and global scope only. The
winning global skill stops carrying a static workflow @-include and instead
resolves its spec at runtime: prefer the project-local copy, fall back to
the global one, stop if neither exists. Every other @-include stays static,
and the local emission is byte-identical. It runs after the staged-skills
rewrite pass, whose claude branch would otherwise mangle the literal tilde
path into an undocumented $HOME form.

Also fixed inline: readInstallManifest classified a top-level JSON array as
an installed v1 manifest, because typeof [] is object.

Refs #2873
This commit is contained in:
sim
2026-08-14 22:47:17 -04:00
parent 52f4ea17cc
commit 2641e6cb67
14 changed files with 1765 additions and 176 deletions

View File

@@ -43,6 +43,55 @@
* (`installed-surface-resolver.cts`'s `deriveStemsForKindEntry`) before they
* ever reach a `TriggerSurface` — this module does not re-gate them.
*
* ── Per-scope truth filter (why this lives HERE, not in the resolver) ──────
* `resolveOneRuntime` (`installed-surface-resolver.cts`) builds ONE union of
* every installed scope's `stems` and hands that single list to
* `resolveTriggerSurface`, which then synthesizes a candidate trigger for
* EVERY stem at EVERY installed scope's trigger-bearing kind entry —
* regardless of whether that specific scope's own manifest actually shipped
* that stem. Concretely: a global `full`-profile install (stems a, b, c)
* alongside a local `core`-profile install (stem a only) unions to
* `{a, b, c}`, and `resolveTriggerSurface` then reports `commands@local`
* candidates for b and c too — trigger names for artifacts that do not exist
* on disk at that scope. Left unfiltered, this module would tell the user
* `/gsd-b` and `/gsd-c` are shadowed local commands when there is no local
* artifact for either at all — over-reporting that is not cosmetic, since
* the whole point of this report is to make a real failure legible.
*
* `resolveTriggerSurface`'s API takes ONE stem list shared by every scope it
* is asked about, so per-scope truth cannot be expressed through it without
* either widening a shipped Phase-2 contract other callers may depend on, or
* calling it once per scope and re-implementing its winner computation
* (`isHigherPriority`) here as a second, driftable copy. `resolveOneRuntime`
* / `resolveInstalledSurfaces` (Phase 3, #2872) is likewise a shipped module
* this task deliberately leaves untouched. This module already receives the
* full `InstalledRuntimeSurface`, including each scope's own REAL `stems`
* list (`installed-surface-resolver.cts`'s `deriveStemsFromManifest`) — so
* the correction belongs here, as a filter over `resolveTriggerSurface`'s
* already-computed `shadowedBy` groups: a trigger is reported as shadowed
* only when its underlying stem is present in BOTH the winner's scope's own
* `stems` AND the shadowed side's scope's own `stems` — i.e. an artifact
* genuinely exists at both scopes, not merely "some stem exists somewhere in
* the union".
*
* `TriggerSurface` does not carry the originating stem OR the composing
* prefix on its output — only the already-composed `trigger` string
* (`${prefix}${stem}`) — so the stem cannot be read off it directly. Rather
* than hand-roll a fixed-offset `trigger.slice(4)` (which would silently
* assume every runtime's prefix is exactly `gsd-` — true today, but not a
* contract this module owns), the prefix is recovered the honest way: by
* re-resolving that scope's `ArtifactKind` layout (`resolveRuntimeArtifactLayout`
* / `resolveRuntimeArtifactLayoutFromRegistry`, the SAME layout descriptor
* `resolveTriggerSurface` itself reads its `entry.prefix` from) for the
* winner's and shadowed side's own `(scope, kind)`, and reading `.prefix`
* off the matching kind entry. This is metadata-only (constructing an
* `ArtifactKind` never touches the filesystem — see
* `runtime-artifact-layout.cts`'s kind-builder functions), so it costs
* nothing beyond a small per-`(scope,kind)` memo. If a prefix cannot be
* resolved at all (a `TypeError` from an unexpected registry shape), the
* trigger is conservatively DROPPED rather than kept — the same
* report-nothing-you-cannot-prove posture as the rest of this filter.
*
* ── Pure with respect to caller-visible state ───────────────────────────────
* `buildShadowReport` builds a fresh `ShadowReport` (fresh arrays, fresh
* objects) on every call, exactly as the resolver documents for itself
@@ -55,8 +104,24 @@ import {
resolveInstalledSurfaces,
type ResolveInstalledSurfacesOptions,
type InstalledRuntimeSurface,
type InstalledScopeRecord,
} from './installed-surface-resolver.cjs';
// eslint-disable-next-line @typescript-eslint/no-require-imports
import runtimeArtifactLayoutMod = require('./runtime-artifact-layout.cjs');
const { resolveRuntimeArtifactLayout, resolveRuntimeArtifactLayoutFromRegistry } = runtimeArtifactLayoutMod;
/** The registry shape `resolveRuntimeArtifactLayoutFromRegistry` accepts as
* its first argument — reused (not re-typed) so `opts.registry` can be
* forwarded to it, mirroring `installed-surface-resolver.cts`'s own
* `LayoutRegistryLike`. */
type LayoutRegistryLike = Parameters<typeof resolveRuntimeArtifactLayoutFromRegistry>[0];
/** `installed-surface-resolver.cts` does not export `TriggerSurface` by
* name (only via `InstalledRuntimeSurface.triggers`'s element type) —
* derived here rather than re-declared as a second, driftable shape. */
type TriggerSurface = InstalledRuntimeSurface['triggers'][number];
// ── Reason enum ─────────────────────────────────────────────────────────
export const SHADOW_REASON = Object.freeze({
@@ -133,6 +198,76 @@ export function sanitizeForRender(value: string | null): string | null {
return stripped.replace(/\s+/g, ' ').trim();
}
// ── Per-scope truth filter helpers ─────────────────────────────────────
/**
* Build a `(scope, kind) -> prefix | null` lookup for one runtime, memoized
* per call to `buildShadowReport` (never shared across calls — matches this
* module's "fresh objects on every call" contract). `null` means "could not
* be resolved" (unknown scope record, or a `TypeError` from the layout
* resolver) — the caller treats that as "cannot honestly attribute this
* trigger to a real stem here", not as "assume it is fine".
*/
function buildPrefixLookup(
runtime: string,
scopeRecords: Map<InstallScope, InstalledScopeRecord>,
opts: ResolveInstalledSurfacesOptions,
): (scope: InstallScope, kind: string) => string | null {
const cache = new Map<string, string | null>();
return (scope: InstallScope, kind: string): string | null => {
const key = `${scope}:${kind}`;
if (cache.has(key)) return cache.get(key) as string | null;
const record = scopeRecords.get(scope);
let prefix: string | null = null;
if (record) {
try {
const layout = opts.registry !== undefined
? resolveRuntimeArtifactLayoutFromRegistry(opts.registry as LayoutRegistryLike, runtime, record.configHome, record.scope)
: resolveRuntimeArtifactLayout(runtime, record.configHome, record.scope);
const kindEntry = (layout.kinds as Array<{ kind: string; prefix: string }>).find((k) => k.kind === kind);
prefix = kindEntry ? kindEntry.prefix : null;
} catch {
// Unknown runtime / malformed registry — degrade to "cannot resolve",
// never throw out of a report builder (matches this module's own
// RESOLVER_UNAVAILABLE degrade-not-propagate posture above).
prefix = null;
}
}
cache.set(key, prefix);
return prefix;
};
}
/** `trigger` minus `prefix`, or `null` when `prefix` is unknown, does not
* actually prefix `trigger`, or the remainder would be empty (a `prefix`
* covering the whole trigger string is not a real stem). */
function stemFromTrigger(trigger: string, prefix: string | null): string | null {
if (prefix === null || !trigger.startsWith(prefix)) return null;
const stem = trigger.slice(prefix.length);
return stem === '' ? null : stem;
}
/**
* True when `t` (a `resolveTriggerSurface`-reported shadowed trigger) is a
* REAL cross-scope shadow: its stem is present in the winner's OWN scope
* `stems` and, independently, in the shadowed side's OWN scope `stems`. See
* the module-level "Per-scope truth filter" comment for why this check
* exists and why it lives here rather than in the resolver.
*/
function isGenuinelyShadowed(
t: TriggerSurface,
scopeRecords: Map<InstallScope, InstalledScopeRecord>,
prefixFor: (scope: InstallScope, kind: string) => string | null,
): boolean {
if (t.shadowedBy === null) return false;
const winnerRecord = scopeRecords.get(t.shadowedBy.scope);
const shadowedRecord = scopeRecords.get(t.scope);
const winnerStem = stemFromTrigger(t.trigger, prefixFor(t.shadowedBy.scope, t.shadowedBy.kind));
const shadowedStem = stemFromTrigger(t.trigger, prefixFor(t.scope, t.kind));
if (winnerStem === null || shadowedStem === null) return false;
return (winnerRecord?.stems ?? []).includes(winnerStem) && (shadowedRecord?.stems ?? []).includes(shadowedStem);
}
// ── Report builder ──────────────────────────────────────────────────────
/**
@@ -171,7 +306,15 @@ export function buildShadowReport(runtime: string, opts: ResolveInstalledSurface
// always returns exactly one element (see its own doc comment).
const surface = surfaces[0];
const shadowedSurfaces = surface.triggers.filter((t) => t.shadowedBy !== null);
// Per-scope truth filter (see module comment): `surface.triggers` may
// contain candidates synthesized from the CROSS-SCOPE stem union
// (`installed-surface-resolver.cts`'s `stemUnion`) that do not correspond
// to a real artifact at one or both scopes. Only a trigger whose stem is
// provably present in BOTH the winner's own `stems` and the shadowed
// side's own `stems` is reported.
const scopeRecords = new Map<InstallScope, InstalledScopeRecord>(surface.scopes.map((r) => [r.scope, r] as const));
const prefixFor = buildPrefixLookup(runtime, scopeRecords, opts);
const shadowedSurfaces = surface.triggers.filter((t) => isGenuinelyShadowed(t, scopeRecords, prefixFor));
const triggers: ShadowedTrigger[] = shadowedSurfaces
.map((t) => ({
trigger: t.trigger,