@shrkcrft/cli 0.1.0-alpha.29 → 0.1.0-alpha.31

package/dist/surface/tier.d.ts

@@ -1,5 +1,6 @@
 import type { ISurfaceConfig } from '@shrkcrft/config';
 import { CommandTier, type ICommandCatalogEntry } from '../commands/command-catalog.js';
+import type { ISurfaceDenial } from './i-surface-denial.js';
 /**
  * Bootstrap commands. Always tier=Core regardless of any other
  * derivation rule. Listed here (and only here) so the rule is mechanical:
@@ -14,6 +15,11 @@ import { CommandTier, type ICommandCatalogEntry } from '../commands/command-cata
  * recommend`.
  */
 export declare const BOOTSTRAP_COMMANDS: readonly string[];
+/**
+ * The detail of a tool-maintenance command resolved outside SharkCraft's own
+ * repository (round 11 §5.1).
+ */
+export declare const TOOL_MAINTENANCE_DETAIL = "maintains SharkCraft itself; does not apply to this repository";
 /**
  * Source explanations for tier classification. Returned by the
  * resolver so `shrk surface explain <name>` can describe why a
@@ -25,7 +31,21 @@ export declare enum TierSource {
     PackContribution = "pack-contribution",
     Override = "override",
     Hidden = "hidden-flag",
-    Default = "default"
+    Default = "default",
+    /**
+     * A registered, dispatchable command with no catalog row. Extended (it runs),
+     * flagged so `commands doctor` / `surface list` point at the missing row.
+     */
+    Uncatalogued = "uncatalogued",
+    /**
+     * A command that maintains SharkCraft itself (catalog audience
+     * `tool-maintenance`), resolved OUTSIDE SharkCraft's own repository:
+     * experimental (gated, hidden from `--help`) unless `surface.enabled` names
+     * it. Invoking it exits 78 through the surface gate — never a check failure.
+     */
+    ToolMaintenance = "tool-maintenance",
+    /** Denied by a `surface.disabled` selector (project config or profile). */
+    Disabled = "disabled"
 }
 export interface ITierResolution {
     /** Resolved tier (post-derivation, post-config). */
@@ -36,14 +56,32 @@ export interface ITierResolution {
     detail?: string;
     /** True if the user's surface config flipped the default. */
     configApplied?: boolean;
+    /** The `surface.disabled` selector (and its layer) that denies the command — source `disabled` only. */
+    deniedBy?: ISurfaceDenial;
 }
 export interface ITierResolverContext {
     /** Catalog command names ({@link ICommandCatalogEntry.command}) referenced by spine pipelines. */
     spineCommands: ReadonlySet<string>;
     /** Catalog command names contributed by loaded packs (pack-contributed commands). */
     packContributions: ReadonlyMap<string, string>;
-    /** User's `sharkcraft.config.ts surface{}` block (may be undefined for a fresh repo). */
+    /**
+     * The EFFECTIVE `surface{}` block: the active profile's lists merged with the
+     * project config's (may be undefined for a fresh repo).
+     */
     surfaceConfig: ISurfaceConfig | undefined;
+    /**
+     * True only inside SharkCraft's OWN repository — `detectSharkcraftRepo`, the
+     * one host authority. Everywhere else a tool-maintenance command resolves
+     * experimental with source {@link TierSource.ToolMaintenance}.
+     */
+    isToolRepo: boolean;
+    /**
+     * The project config's OWN `surface.enabled` / `surface.disabled`, before the
+     * profile merge. The resolver needs the layer for exactly one rule: an
+     * explicit config `enabled` overrides a PROFILE's deny, never a config deny.
+     * Absent = `surfaceConfig` IS the project config (no profile layer).
+     */
+    explicitSurface?: Pick<ISurfaceConfig, 'enabled' | 'disabled'>;
 }
 /**
  * Mechanically derive a command's tier.
@@ -52,36 +90,61 @@ export interface ITierResolverContext {
  *
  *   1. Bootstrap set → Core.
  *   2. Spine pipeline reference → Core.
- *   3. Pack contribution → Experimental (unless in surface.enabled).
- *   4. Explicit catalog `tier` override → that value (cannot demote Core).
- *   5. Catalog overlay `hidden` verdict → Experimental.
- *   6. Otherwise → Extended.
+ *   3. A `surface.disabled` selector → Experimental, source `disabled`
+ *      (never a bootstrap command or one of its subverbs; an explicit config
+ *      `enabled` overrides a PROFILE's deny, never a config deny).
+ *   4. A tool-maintenance command outside SharkCraft's own repository →
+ *      Experimental, source `tool-maintenance` (unless in surface.enabled).
+ *   5. Pack contribution → Experimental (unless in surface.enabled).
+ *   6. Explicit catalog `tier` override → that value (cannot demote Core).
+ *   7. Catalog overlay `hidden` verdict → Experimental.
+ *   8. Otherwise → Extended.
  *
- * After derivation, the user's `surface.enabled` / `surface.hidden`
- * config can flip a single dimension:
+ * Every `enabled` / `hidden` / `disabled` entry is a selector — an exact path
+ * (or alias spelling) or `<group> *` — matched by the ONE matcher
+ * (`surface-selector.ts`).
  *
- *   - `surface.enabled` contains the command → promote Experimental
- *     to Extended (callable, visible in `surface list` only — `--help`
- *     visibility is governed by the catalog's own defaultShowInHelp).
- *   - `surface.hidden` contains the command AND tier is Extended →
- *     remains Extended-tier but hidden from `--help`. The visibility
- *     flip is read by the help renderer, not by the tier resolver
- *     directly.
+ * After derivation, `surface.hidden` flips `--help` visibility of an Extended
+ * command (read by the summary); it never changes callability.
  *
  * Core commands cannot be hidden or disabled. Attempts to do so are
  * surfaced as warnings by `shrk doctor` and `shrk surface list --json`.
  */
 export declare function resolveTier(entry: ICommandCatalogEntry, context: ITierResolverContext): ITierResolution;
+/**
+ * Tier of a command-index path. `entry` is the path's base catalog row, or
+ * `undefined` for a registered command the catalog does not document — which
+ * still gets the bootstrap / spine / deny / pack derivation, and otherwise
+ * resolves Extended with {@link TierSource.Uncatalogued}. `aliases` are the
+ * path's alias spellings: a selector naming an alias names the command.
+ */
+export declare function resolveTierForPath(path: string, entry: ICommandCatalogEntry | undefined, context: ITierResolverContext, aliases?: readonly string[]): ITierResolution;
+/**
+ * A bootstrap command or one of its subverbs (`surface allow`, `doctor
+ * suppress`). A deny selector never applies to one: `surface deny 'surface *'`
+ * must not lock the user out of the verb that undoes it.
+ */
+export declare function isBootstrapFamily(name: string): boolean;
+/**
+ * THE deny decision: the `surface.disabled` selector that denies a command
+ * named by any of `names` (its path plus alias spellings), with the layer that
+ * declared it — or `undefined` when nothing denies it.
+ *
+ *   - a config deny always wins (even over a config `enabled` — the summary
+ *     warns `enable-disable-conflict`);
+ *   - a deny only the active PROFILE declares is overridden by an explicit
+ *     config `enabled` match ("config wins over the profile").
+ */
+export declare function surfaceDenial(names: readonly string[], context: ITierResolverContext): ISurfaceDenial | undefined;
 /**
  * Is the command callable from the CLI / MCP in the current
  * surface configuration?
  *
  *   - Core: always callable.
  *   - Extended: always callable.
- *   - Experimental: callable only if in `surface.enabled`.
- *
- * The resolver's promotion of Experimental → Extended already accounts
- * for `enabled[]`, so this is a simple tier check.
+ *   - Experimental: callable only if in `surface.enabled` (the resolver has
+ *     already promoted an enabled command to Extended — and never promotes a
+ *     denied one).
  */
 export declare function isCallable(resolution: ITierResolution): boolean;
 /**
@@ -92,9 +155,9 @@ export declare function isCallable(resolution: ITierResolution): boolean;
  *     checks the config and consults `defaultShowInHelp(entry)`).
  *   - Experimental: never visible in `--help`; only in `surface list`.
  *
- * The caller still consults `defaultShowInHelp(entry)` for the
- * underlying surface/lifecycle gating; this function answers "does
- * the tier permit visibility at all?".
+ * The caller still consults the catalog's help rule for the underlying
+ * surface/lifecycle gating; this function answers "does the tier permit
+ * visibility at all?".
  */
 export declare function isVisibleInDefaultHelp(resolution: ITierResolution, hiddenByConfig: boolean): boolean;
 //# sourceMappingURL=tier.d.ts.map

package/dist/surface/tier.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tier.d.ts","sourceRoot":"","sources":["../../src/surface/tier.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EACL,WAAW,EACX,KAAK,oBAAoB,EAC1B,MAAM,gCAAgC,CAAC;AAExC;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAW9C,CAAC;AAEH;;;;GAIG;AACH,oBAAY,UAAU;IACpB,SAAS,cAAc;IACvB,KAAK,UAAU;IACf,gBAAgB,sBAAsB;IACtC,QAAQ,aAAa;IACrB,MAAM,gBAAgB;IACtB,OAAO,YAAY;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,oDAAoD;IACpD,IAAI,EAAE,WAAW,CAAC;IAClB,sCAAsC;IACtC,MAAM,EAAE,UAAU,CAAC;IACnB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,kGAAkG;IAClG,aAAa,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACnC,qFAAqF;IACrF,iBAAiB,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/C,yFAAyF;IACzF,aAAa,EAAE,cAAc,GAAG,SAAS,CAAC;CAC3C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,oBAAoB,EAC3B,OAAO,EAAE,oBAAoB,GAC5B,eAAe,CA4EjB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,eAAe,GAAG,OAAO,CAK/D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,eAAe,EAC3B,cAAc,EAAE,OAAO,GACtB,OAAO,CAKT"}
+{"version":3,"file":"tier.d.ts","sourceRoot":"","sources":["../../src/surface/tier.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EACL,WAAW,EAEX,KAAK,oBAAoB,EAC1B,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAI5D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAW9C,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,uBAAuB,mEAAmE,CAAC;AAExG;;;;GAIG;AACH,oBAAY,UAAU;IACpB,SAAS,cAAc;IACvB,KAAK,UAAU;IACf,gBAAgB,sBAAsB;IACtC,QAAQ,aAAa;IACrB,MAAM,gBAAgB;IACtB,OAAO,YAAY;IACnB;;;OAGG;IACH,YAAY,iBAAiB;IAC7B;;;;;OAKG;IACH,eAAe,qBAAqB;IACpC,2EAA2E;IAC3E,QAAQ,aAAa;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,oDAAoD;IACpD,IAAI,EAAE,WAAW,CAAC;IAClB,sCAAsC;IACtC,MAAM,EAAE,UAAU,CAAC;IACnB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,wGAAwG;IACxG,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B;AAED,MAAM,WAAW,oBAAoB;IACnC,kGAAkG;IAClG,aAAa,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACnC,qFAAqF;IACrF,iBAAiB,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/C;;;OAGG;IACH,aAAa,EAAE,cAAc,GAAG,SAAS,CAAC;IAC1C;;;;OAIG;IACH,UAAU,EAAE,OAAO,CAAC;IACpB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,SAAS,GAAG,UAAU,CAAC,CAAC;CAChE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,oBAAoB,EAC3B,OAAO,EAAE,oBAAoB,GAC5B,eAAe,CAEjB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,oBAAoB,GAAG,SAAS,EACvC,OAAO,EAAE,oBAAoB,EAC7B,OAAO,GAAE,SAAS,MAAM,EAAO,GAC9B,eAAe,CAEjB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,OAAO,EAAE,oBAAoB,GAC5B,cAAc,GAAG,SAAS,CAQ5B;AAiID;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,eAAe,GAAG,OAAO,CAK/D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,eAAe,EAC3B,cAAc,EAAE,OAAO,GACtB,OAAO,CAKT"}

package/dist/surface/tier.js

@@ -1,4 +1,6 @@
-import { CommandTier, } from "../commands/command-catalog.js";
+import { CommandTier, isToolMaintenance, } from "../commands/command-catalog.js";
+import { SurfaceLayer } from "./surface-layer.js";
+import { firstMatchingSelector } from "./surface-selector.js";
 /**
  * Bootstrap commands. Always tier=Core regardless of any other
  * derivation rule. Listed here (and only here) so the rule is mechanical:
@@ -24,6 +26,11 @@ export const BOOTSTRAP_COMMANDS = Object.freeze([
     // completeness so `surface list` surfaces it.
     '--about',
 ]);
+/**
+ * The detail of a tool-maintenance command resolved outside SharkCraft's own
+ * repository (round 11 §5.1).
+ */
+export const TOOL_MAINTENANCE_DETAIL = 'maintains SharkCraft itself; does not apply to this repository';
 /**
  * Source explanations for tier classification. Returned by the
  * resolver so `shrk surface explain <name>` can describe why a
@@ -37,6 +44,20 @@ export var TierSource;
     TierSource["Override"] = "override";
     TierSource["Hidden"] = "hidden-flag";
     TierSource["Default"] = "default";
+    /**
+     * A registered, dispatchable command with no catalog row. Extended (it runs),
+     * flagged so `commands doctor` / `surface list` point at the missing row.
+     */
+    TierSource["Uncatalogued"] = "uncatalogued";
+    /**
+     * A command that maintains SharkCraft itself (catalog audience
+     * `tool-maintenance`), resolved OUTSIDE SharkCraft's own repository:
+     * experimental (gated, hidden from `--help`) unless `surface.enabled` names
+     * it. Invoking it exits 78 through the surface gate — never a check failure.
+     */
+    TierSource["ToolMaintenance"] = "tool-maintenance";
+    /** Denied by a `surface.disabled` selector (project config or profile). */
+    TierSource["Disabled"] = "disabled";
 })(TierSource || (TierSource = {}));
 /**
  * Mechanically derive a command's tier.
@@ -45,27 +66,70 @@ export var TierSource;
  *
  *   1. Bootstrap set → Core.
  *   2. Spine pipeline reference → Core.
- *   3. Pack contribution → Experimental (unless in surface.enabled).
- *   4. Explicit catalog `tier` override → that value (cannot demote Core).
- *   5. Catalog overlay `hidden` verdict → Experimental.
- *   6. Otherwise → Extended.
+ *   3. A `surface.disabled` selector → Experimental, source `disabled`
+ *      (never a bootstrap command or one of its subverbs; an explicit config
+ *      `enabled` overrides a PROFILE's deny, never a config deny).
+ *   4. A tool-maintenance command outside SharkCraft's own repository →
+ *      Experimental, source `tool-maintenance` (unless in surface.enabled).
+ *   5. Pack contribution → Experimental (unless in surface.enabled).
+ *   6. Explicit catalog `tier` override → that value (cannot demote Core).
+ *   7. Catalog overlay `hidden` verdict → Experimental.
+ *   8. Otherwise → Extended.
  *
- * After derivation, the user's `surface.enabled` / `surface.hidden`
- * config can flip a single dimension:
+ * Every `enabled` / `hidden` / `disabled` entry is a selector — an exact path
+ * (or alias spelling) or `<group> *` — matched by the ONE matcher
+ * (`surface-selector.ts`).
  *
- *   - `surface.enabled` contains the command → promote Experimental
- *     to Extended (callable, visible in `surface list` only — `--help`
- *     visibility is governed by the catalog's own defaultShowInHelp).
- *   - `surface.hidden` contains the command AND tier is Extended →
- *     remains Extended-tier but hidden from `--help`. The visibility
- *     flip is read by the help renderer, not by the tier resolver
- *     directly.
+ * After derivation, `surface.hidden` flips `--help` visibility of an Extended
+ * command (read by the summary); it never changes callability.
  *
  * Core commands cannot be hidden or disabled. Attempts to do so are
  * surfaced as warnings by `shrk doctor` and `shrk surface list --json`.
  */
 export function resolveTier(entry, context) {
-    const name = entry.command;
+    return deriveTier(entry.command, entry, context, []);
+}
+/**
+ * Tier of a command-index path. `entry` is the path's base catalog row, or
+ * `undefined` for a registered command the catalog does not document — which
+ * still gets the bootstrap / spine / deny / pack derivation, and otherwise
+ * resolves Extended with {@link TierSource.Uncatalogued}. `aliases` are the
+ * path's alias spellings: a selector naming an alias names the command.
+ */
+export function resolveTierForPath(path, entry, context, aliases = []) {
+    return deriveTier(path, entry, context, aliases);
+}
+/**
+ * A bootstrap command or one of its subverbs (`surface allow`, `doctor
+ * suppress`). A deny selector never applies to one: `surface deny 'surface *'`
+ * must not lock the user out of the verb that undoes it.
+ */
+export function isBootstrapFamily(name) {
+    return BOOTSTRAP_COMMANDS.some((b) => name === b || name.startsWith(`${b} `));
+}
+/**
+ * THE deny decision: the `surface.disabled` selector that denies a command
+ * named by any of `names` (its path plus alias spellings), with the layer that
+ * declared it — or `undefined` when nothing denies it.
+ *
+ *   - a config deny always wins (even over a config `enabled` — the summary
+ *     warns `enable-disable-conflict`);
+ *   - a deny only the active PROFILE declares is overridden by an explicit
+ *     config `enabled` match ("config wins over the profile").
+ */
+export function surfaceDenial(names, context) {
+    const explicit = context.explicitSurface ?? context.surfaceConfig;
+    const configSelector = firstMatchingSelector(explicit?.disabled, names);
+    if (configSelector !== undefined)
+        return { selector: configSelector, origin: SurfaceLayer.Config };
+    const mergedSelector = firstMatchingSelector(context.surfaceConfig?.disabled, names);
+    if (mergedSelector === undefined)
+        return undefined;
+    if (firstMatchingSelector(explicit?.enabled, names) !== undefined)
+        return undefined;
+    return { selector: mergedSelector, origin: SurfaceLayer.Profile };
+}
+function deriveTier(name, entry, context, aliases) {
     // 1. Bootstrap set always wins.
     if (BOOTSTRAP_COMMANDS.includes(name)) {
         return {
@@ -82,10 +146,33 @@ export function resolveTier(entry, context) {
             detail: 'referenced from a spine pipeline',
         };
     }
-    // 3. Pack contributions default to Experimental, unless explicitly enabled.
+    const names = [name, ...aliases];
+    // 3. A deny selector. Not callable, whatever the other derivations say.
+    const deniedBy = isBootstrapFamily(name) ? undefined : surfaceDenial(names, context);
+    if (deniedBy) {
+        return {
+            tier: CommandTier.Experimental,
+            source: TierSource.Disabled,
+            detail: deniedBy.origin === SurfaceLayer.Config
+                ? `disabled by surface.disabled ('${deniedBy.selector}')`
+                : `disabled by the ${profileLabel(context)} surface profile ('${deniedBy.selector}')`,
+            configApplied: true,
+            deniedBy,
+        };
+    }
+    const enabled = firstMatchingSelector(context.surfaceConfig?.enabled, names) !== undefined;
+    // 4. A command that maintains SharkCraft itself, outside SharkCraft's repo.
+    if (entry && isToolMaintenance(entry) && !context.isToolRepo) {
+        return {
+            tier: enabled ? CommandTier.Extended : CommandTier.Experimental,
+            source: TierSource.ToolMaintenance,
+            detail: enabled ? `${TOOL_MAINTENANCE_DETAIL} — enabled in surface.enabled` : TOOL_MAINTENANCE_DETAIL,
+            ...(enabled ? { configApplied: true } : {}),
+        };
+    }
+    // 5. Pack contributions default to Experimental, unless explicitly enabled.
     const pack = context.packContributions.get(name);
     if (pack !== undefined) {
-        const enabled = (context.surfaceConfig?.enabled ?? []).includes(name);
         return {
             tier: enabled ? CommandTier.Extended : CommandTier.Experimental,
             source: TierSource.PackContribution,
@@ -95,11 +182,23 @@ export function resolveTier(entry, context) {
             configApplied: enabled,
         };
     }
-    // 4. Explicit override on the catalog entry.
+    // No catalog row: the derivations above are all that apply.
+    if (!entry) {
+        return {
+            tier: CommandTier.Extended,
+            source: TierSource.Uncatalogued,
+            // `commands doctor` maintains SharkCraft itself (exit 78 elsewhere): only
+            // inside the tool repository is it the remedy. Outside, the missing row
+            // is SharkCraft's catalog gap — nothing this repository can fix.
+            detail: context.isToolRepo
+                ? 'registered but has no catalog row — run `shrk commands doctor`'
+                : "registered but missing from SharkCraft's command catalog — a SharkCraft catalog gap, not a problem in this repository",
+        };
+    }
+    // 6. Explicit override on the catalog entry.
     if (entry.tier !== undefined) {
         // Cannot demote Core. The override applies for Extended/Experimental only.
         if (entry.tier === CommandTier.Experimental) {
-            const enabled = (context.surfaceConfig?.enabled ?? []).includes(name);
             return {
                 tier: enabled ? CommandTier.Extended : CommandTier.Experimental,
                 source: TierSource.Override,
@@ -113,14 +212,13 @@ export function resolveTier(entry, context) {
             detail: `catalog override (tier=${entry.tier})`,
         };
     }
-    // 5. Catalog overlay `hidden` verdict implies Experimental.
+    // 7. Catalog overlay `hidden` verdict implies Experimental.
     // We can't import the overlay here without a circular dep risk; the
     // caller passes a precomputed view via context. For now, we rely on
     // the catalog's surface=Internal/Legacy combined with showInDefaultHelp.
     // If the entry is marked showInDefaultHelp: false explicitly, that's a
     // weaker signal than the overlay but still pushes toward Experimental.
     if (entry.showInDefaultHelp === false) {
-        const enabled = (context.surfaceConfig?.enabled ?? []).includes(name);
         return {
             tier: enabled ? CommandTier.Extended : CommandTier.Experimental,
             source: TierSource.Hidden,
@@ -128,23 +226,27 @@ export function resolveTier(entry, context) {
             configApplied: enabled,
         };
     }
-    // 6. Default — Extended.
+    // 8. Default — Extended. No `detail`: it was the same placeholder sentence on
+    // every one of ~436 rows, so the listing could not say what anything does.
+    // `surface explain` renders the source instead.
     return {
         tier: CommandTier.Extended,
         source: TierSource.Default,
-        detail: 'default for catalog entries not in spine and not pack-contributed',
     };
 }
+function profileLabel(context) {
+    const id = context.surfaceConfig?.profile;
+    return id ? `'${id}'` : 'active';
+}
 /**
  * Is the command callable from the CLI / MCP in the current
  * surface configuration?
  *
  *   - Core: always callable.
  *   - Extended: always callable.
- *   - Experimental: callable only if in `surface.enabled`.
- *
- * The resolver's promotion of Experimental → Extended already accounts
- * for `enabled[]`, so this is a simple tier check.
+ *   - Experimental: callable only if in `surface.enabled` (the resolver has
+ *     already promoted an enabled command to Extended — and never promotes a
+ *     denied one).
  */
 export function isCallable(resolution) {
     return (resolution.tier === CommandTier.Core ||
@@ -158,9 +260,9 @@ export function isCallable(resolution) {
  *     checks the config and consults `defaultShowInHelp(entry)`).
  *   - Experimental: never visible in `--help`; only in `surface list`.
  *
- * The caller still consults `defaultShowInHelp(entry)` for the
- * underlying surface/lifecycle gating; this function answers "does
- * the tier permit visibility at all?".
+ * The caller still consults the catalog's help rule for the underlying
+ * surface/lifecycle gating; this function answers "does the tier permit
+ * visibility at all?".
  */
 export function isVisibleInDefaultHelp(resolution, hiddenByConfig) {
     if (resolution.tier === CommandTier.Core)

package/dist/usage/usage-log.d.ts

@@ -49,6 +49,11 @@ export declare function sanitizeFlagNames(rawArgv: readonly string[]): string[];
 /**
  * Extract the leading command path (top-level + first
  * subcommand if present, no flags) from raw argv.
+ *
+ * `maxTokens` defaults to 2, which is what the usage log records. The
+ * verdict-verb check passes `VERDICT_PATH_TOKENS` (3) so a three-token verdict
+ * verb (`docs references check`) can be told apart from its informational
+ * siblings (`docs references list`).
  */
-export declare function extractCommandPath(rawArgv: readonly string[]): string;
+export declare function extractCommandPath(rawArgv: readonly string[], maxTokens?: number): string;
 //# sourceMappingURL=usage-log.d.ts.map

package/dist/usage/usage-log.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usage-log.d.ts","sourceRoot":"","sources":["../../src/usage/usage-log.ts"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;GAcG;AAEH,eAAO,MAAM,gBAAgB,wBAAwB,CAAC;AACtD,eAAO,MAAM,aAAa,sBAAsB,CAAC;AACjD,eAAO,MAAM,cAAc,mBAAmB,CAAC;AAC/C,eAAO,MAAM,sBAAsB,QAAmB,CAAC;AAEvD,MAAM,WAAW,WAAW;IAC1B,aAAa,EAAE,OAAO,gBAAgB,CAAC;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,0DAA0D;IAC1D,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,mBAAmB,GAAG,IAAI,CAqB3D;AAcD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAkBtE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAQrE"}
+{"version":3,"file":"usage-log.d.ts","sourceRoot":"","sources":["../../src/usage/usage-log.ts"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;GAcG;AAEH,eAAO,MAAM,gBAAgB,wBAAwB,CAAC;AACtD,eAAO,MAAM,aAAa,sBAAsB,CAAC;AACjD,eAAO,MAAM,cAAc,mBAAmB,CAAC;AAC/C,eAAO,MAAM,sBAAsB,QAAmB,CAAC;AAEvD,MAAM,WAAW,WAAW;IAC1B,aAAa,EAAE,OAAO,gBAAgB,CAAC;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,0DAA0D;IAC1D,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,mBAAmB,GAAG,IAAI,CAqB3D;AAcD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAkBtE;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,EAAE,SAAS,SAAI,GAAG,MAAM,CAQpF"}

package/dist/usage/usage-log.js

@@ -91,13 +91,18 @@ export function sanitizeFlagNames(rawArgv) {
 /**
  * Extract the leading command path (top-level + first
  * subcommand if present, no flags) from raw argv.
+ *
+ * `maxTokens` defaults to 2, which is what the usage log records. The
+ * verdict-verb check passes `VERDICT_PATH_TOKENS` (3) so a three-token verdict
+ * verb (`docs references check`) can be told apart from its informational
+ * siblings (`docs references list`).
  */
-export function extractCommandPath(rawArgv) {
+export function extractCommandPath(rawArgv, maxTokens = 2) {
     const tokens = [];
     for (const t of rawArgv) {
         if (t.startsWith('-'))
             break;
-        if (tokens.length >= 2)
+        if (tokens.length >= maxTokens)
             break;
         tokens.push(t);
     }

package/dist/validation/run-validation-loop.d.ts

@@ -26,6 +26,15 @@ export interface IRunValidationLoopResult {
     commandsRun: IValidationCommandResult[];
     commandsFailed: string[];
     boundaryViolations: number;
+    /**
+     * THE boundary verdict (`runBoundaryCheck`, what `check boundaries`
+     * reports): `not-verified` when zero rules loaded or part of a rule's scope
+     * was never examined — never a silent `boundaryViolations: 0`. Absent when
+     * the scan itself could not run.
+     */
+    boundaryVerdict?: 'pass' | 'fail' | 'not-verified' | 'usage-error';
+    /** Why the boundary verdict is not a clean pass, when it is not. */
+    boundaryShortfalls?: readonly string[];
     reportPath?: string;
 }
 /**

package/dist/validation/run-validation-loop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-validation-loop.d.ts","sourceRoot":"","sources":["../../src/validation/run-validation-loop.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,yBAAyB;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,qEAAqE;IACrE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mEAAmE;IACnE,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,2EAA2E;IAC3E,gBAAgB,EAAE,OAAO,CAAC;IAC1B,6EAA6E;IAC7E,iBAAiB,EAAE,OAAO,CAAC;IAC3B,2DAA2D;IAC3D,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,+DAA+D;IAC/D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,6EAA6E;IAC7E,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CAC1C;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,wBAAwB,EAAE,CAAC;IACxC,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,wBAAwB,CAAC,CAyGnC"}
+{"version":3,"file":"run-validation-loop.d.ts","sourceRoot":"","sources":["../../src/validation/run-validation-loop.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,yBAAyB;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,qEAAqE;IACrE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mEAAmE;IACnE,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,2EAA2E;IAC3E,gBAAgB,EAAE,OAAO,CAAC;IAC1B,6EAA6E;IAC7E,iBAAiB,EAAE,OAAO,CAAC;IAC3B,2DAA2D;IAC3D,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,+DAA+D;IAC/D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,6EAA6E;IAC7E,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CAC1C;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,wBAAwB,EAAE,CAAC;IACxC,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,kBAAkB,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,cAAc,GAAG,aAAa,CAAC;IACnE,oEAAoE;IACpE,kBAAkB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,wBAAwB,CAAC,CA2GnC"}

package/dist/validation/run-validation-loop.js

@@ -75,19 +75,22 @@ export async function runValidationLoop(options) {
             out.passed = false;
         }
     }
-    // Boundary scan as a non-fatal warning (mirrors `shrk apply --validate`).
+    // Boundary scan as a non-fatal warning (mirrors `shrk apply --validate`) —
+    // through THE boundary orchestrator (round 11 review R11-GAP-3). It used to
+    // evaluate without the tsconfig alias map, skip unread files, and report
+    // `boundaryViolations: 0` over zero rules; zero rules or an unexamined scope
+    // is now `boundaryVerdict: not-verified` (a warning), an errored rule fails.
     try {
-        const { inspectSharkcraft } = await import('@shrkcrft/inspector');
-        const { evaluateBoundaries, scanImports } = await import('@shrkcrft/boundaries');
+        const { inspectSharkcraft, runBoundaryCheck } = await import('@shrkcrft/inspector');
         const inspection = await inspectSharkcraft({ cwd: options.cwd });
-        if (inspection.boundaryRegistry.size() > 0) {
-            const scan = scanImports({ projectRoot: options.cwd });
-            const evalResult = evaluateBoundaries(scan, inspection.boundaryRegistry.list());
-            out.boundaryViolations = evalResult.violations.length;
-            out.warnings += evalResult.counts.warning;
-            if (evalResult.counts.error > 0)
-                out.passed = false;
-        }
+        const evalResult = runBoundaryCheck(inspection);
+        out.boundaryViolations = evalResult.violations.length;
+        out.boundaryVerdict = evalResult.verdict;
+        if (evalResult.shortfalls.length > 0)
+            out.boundaryShortfalls = evalResult.shortfalls;
+        out.warnings += evalResult.counts.warning + (evalResult.verdict === 'not-verified' ? 1 : 0);
+        if (evalResult.counts.error > 0 || evalResult.loadIssues.length > 0)
+            out.passed = false;
     }
     catch {
         // boundary scan is best-effort.

package/dist/validation/typecheck-emitted.d.ts

@@ -21,16 +21,15 @@ export interface IEmittedTypecheckResult {
 }
 /**
  * Typecheck a set of EMITTED (not-yet-written) files against the project's
- * detected tsconfig, without touching disk. Builds a `ts.Program` whose root
- * names are the emitted files, over a compiler host that overlays the rendered
- * bodies for those paths and reads everything else (imports, lib) from disk — so
- * a scaffold that references a real project symbol resolves, and a template bug
- * (bad syntax, a dangling import, a type mismatch) surfaces BEFORE apply instead
- * of at the human's next build.
+ * detected tsconfig, without touching disk — a scaffold that references a real
+ * project symbol resolves, and a template bug (bad syntax, a dangling import, a
+ * type mismatch) surfaces BEFORE apply instead of at the human's next build.
  *
- * Only diagnostics located IN the emitted files are reported; pre-existing
- * errors elsewhere in the project are ignored (this is a generation gate, not a
- * whole-repo typecheck).
+ * A thin wrapper over the ONE in-process TypeScript check,
+ * `typecheckFiles` (`@shrkcrft/inspector`): the emitted bodies are passed as
+ * an overlay and only diagnostics IN the emitted files are reported —
+ * pre-existing errors elsewhere in the project are ignored (this is a
+ * generation gate, not a whole-repo typecheck).
  */
 export declare function typecheckEmittedFiles(projectRoot: string, files: readonly IEmittedFile[]): IEmittedTypecheckResult;
 //# sourceMappingURL=typecheck-emitted.d.ts.map

package/dist/validation/typecheck-emitted.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"typecheck-emitted.d.ts","sourceRoot":"","sources":["../../src/validation/typecheck-emitted.ts"],"names":[],"mappings":"AAIA,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IAC3B,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,2DAA2D;AAC3D,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,uBAAuB;IACtC,kFAAkF;IAClF,GAAG,EAAE,OAAO,CAAC;IACb,MAAM,EAAE,SAAS,sBAAsB,EAAE,CAAC;IAC1C,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAYD;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,SAAS,YAAY,EAAE,GAC7B,uBAAuB,CAmFzB"}
+{"version":3,"file":"typecheck-emitted.d.ts","sourceRoot":"","sources":["../../src/validation/typecheck-emitted.ts"],"names":[],"mappings":"AAGA,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IAC3B,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,2DAA2D;AAC3D,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,uBAAuB;IACtC,kFAAkF;IAClF,GAAG,EAAE,OAAO,CAAC;IACb,MAAM,EAAE,SAAS,sBAAsB,EAAE,CAAC;IAC1C,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,SAAS,YAAY,EAAE,GAC7B,uBAAuB,CAczB"}