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

package/dist/commands/command-catalog.js

@@ -31,6 +31,16 @@ export var CommandAudience;
     CommandAudience["Ci"] = "ci";
     CommandAudience["PackAuthor"] = "pack-author";
     CommandAudience["Maintainer"] = "maintainer";
+    /**
+     * The command's OBJECT is SharkCraft itself — its own docs set, examples
+     * tree, release artifacts, command catalog, round snapshots (round 11
+     * §5.1). Outside SharkCraft's own repository (`detectSharkcraftRepo`, the
+     * one host authority) such a command is gated: tier source
+     * `tool-maintenance`, hidden from `--help`, and invoking it exits 78 through
+     * the surface gate — never a check failure. `surface.enabled` is the escape
+     * hatch.
+     */
+    CommandAudience["ToolMaintenance"] = "tool-maintenance";
 })(CommandAudience || (CommandAudience = {}));
 /**
  * User-journey role. Distinct from {@link SafetyLevel} and from the
@@ -162,7 +172,7 @@ export const COMMAND_CATALOG = Object.freeze([
     // Adaptive surface tier introspection + management.
     entry({
         command: 'surface',
-        description: 'Inspect / change the adaptive command surface. Subcommands: list, enable, disable, hide, unhide, reset, explain.',
+        description: 'Inspect / change the adaptive command surface. Subcommands: list, enable, disable, hide, unhide, deny, allow, reset, explain, profiles.',
         category: 'core',
         safetyLevel: SafetyLevel.WritesSource,
         writesFiles: true,
@@ -220,9 +230,27 @@ export const COMMAND_CATALOG = Object.freeze([
         surface: CommandSurface.Advanced,
         taskRole: CommandTaskRole.Config,
     }),
+    entry({
+        command: 'surface deny',
+        description: 'Disable a command or a whole group (`<group> *`) in this repository — it stops being callable (exit 78) and leaves --help. Writes surface.disabled; preview-first.',
+        category: 'core',
+        safetyLevel: SafetyLevel.WritesSource,
+        writesFiles: true,
+        surface: CommandSurface.Advanced,
+        taskRole: CommandTaskRole.Config,
+    }),
+    entry({
+        command: 'surface allow',
+        description: 'Reverse a prior `surface deny` — remove the selector from surface.disabled (preview-first).',
+        category: 'core',
+        safetyLevel: SafetyLevel.WritesSource,
+        writesFiles: true,
+        surface: CommandSurface.Advanced,
+        taskRole: CommandTaskRole.Config,
+    }),
     entry({
         command: 'surface reset',
-        description: 'Clear surface.enabled + surface.hidden in sharkcraft.config.ts (preview-first).',
+        description: 'Clear surface.enabled + surface.hidden + surface.disabled in sharkcraft.config.ts (preview-first).',
         category: 'core',
         safetyLevel: SafetyLevel.WritesSource,
         writesFiles: true,
@@ -375,7 +403,7 @@ export const COMMAND_CATALOG = Object.freeze([
     }),
     entry({
         command: 'check boundaries',
-        description: 'Boundary enforcement against tsconfig aliases + import graph.',
+        description: 'Boundary enforcement against tsconfig aliases + import graph (imports read from code, not comments). Bare forbidden patterns cover subpaths; exemptFiles / excludeTests / exceptions are marked, never dropped; a rule matching nothing is never "evaluated" (0/1/2/3, gate envelope). [--rule <id>] [--rule-file <path> | --diff-against <path>] [--changed-only …] [--fail-on-dead-units] [--include-comments] [--allow-empty] [--json]',
         category: 'core',
         safetyLevel: SafetyLevel.ReadOnly,
         mcpAvailable: true,
@@ -384,7 +412,7 @@ export const COMMAND_CATALOG = Object.freeze([
     }),
     entry({
         command: 'check wiring',
-        description: 'Completeness checks: flags config-defined "declared but not wired" tokens (a declared value/identifier set that must be a subset of a registered set). Generic + deterministic; rules from sharkcraft.config.ts wiringRules[]. [--changed-only] [--only <ids>] [--json]',
+        description: 'Completeness checks: flags config-defined "declared but not wired" tokens (a declared value/identifier set that must be a subset of a registered set). Generic + deterministic; rules from sharkcraft.config.ts wiringRules[]. A subset rule whose registered side holds tokens no declared site produced is `partial` (exit 2) unless `registeredExtras` accepts them. [--changed-only] [--only <ids>] [--allow-empty] [--json]',
         category: 'core',
         safetyLevel: SafetyLevel.ReadOnly,
         surface: CommandSurface.Common,
@@ -392,7 +420,7 @@ export const COMMAND_CATALOG = Object.freeze([
     }),
     entry({
         command: 'check orphans',
-        description: 'Write-safety guard: after deleting file(s)/export(s), finds surviving files that still import them or reference a symbol they declared — alias-resolved, incl. barrel re-exports the type checker misses. Reverse-closure over the diff vs --since (or --staged) against the code-graph snapshot; each survivor reported with file:line. [--since <ref>] [--staged] [--json]',
+        description: 'Write-safety guard: after deleting file(s)/export(s), finds surviving files that still import them or reference a symbol they declared — alias-resolved, incl. barrel re-exports the type checker misses. Reverse-closure over the diff vs --since (or --staged) against the code-graph snapshot; each survivor reported with file:line. Nothing deleted is NOT a pass (exit 2) unless --allow-empty. [--since <ref>] [--staged] [--allow-empty] [--json]',
         category: 'core',
         safetyLevel: SafetyLevel.ReadOnly,
         surface: CommandSurface.Common,
@@ -400,7 +428,7 @@ export const COMMAND_CATALOG = Object.freeze([
     }),
     entry({
         command: 'policy-lint',
-        description: 'Lint template/markup, stylesheet, and AOT-invisible TS surfaces against config-defined policyRules[] — sees `.html` files AND inline `template:` strings that tsc/AOT cannot. Deterministic; no AI. [--surface template|style|ts] [--changed-only] [--only <ids>] [--json]',
+        description: 'Lint template/markup, stylesheet, and AOT-invisible TS surfaces against config-defined policyRules[] — sees `.html` files AND inline `template:` strings that tsc/AOT cannot. Deterministic; no AI. No rules declared is NOT a pass (exit 2) unless --allow-empty. [--surface template|style|ts] [--changed-only] [--only <ids>] [--allow-empty] [--json]',
         category: 'core',
         safetyLevel: SafetyLevel.ReadOnly,
         surface: CommandSurface.Common,
@@ -440,7 +468,7 @@ export const COMMAND_CATALOG = Object.freeze([
     }),
     entry({
         command: 'gates coverage',
-        description: 'The stale-selector detector: what every data-defined rule actually MATCHED against the live tree, flagging each rule that matched 0 files/ids (a rule matching nothing is a bug in the rule, never a pass) and running each rule\'s declared selfTest expectations. Run it in CI so a rule quietly dying is itself a failure. Exit 2 when a rule matched nothing, 1 when it set failOnEmpty. [--plane <p>] [--json]',
+        description: 'The stale-selector detector: what every data-defined rule actually MATCHED against the live tree, flagging each rule that matched 0 files/ids (a rule matching nothing is a bug in the rule, never a pass), each glob inside a connected rule that matched 0 files (advisory; --fail-on-dead-units fails on it), and running each rule\'s declared selfTest expectations (every failure names the selector it consulted). Run it in CI so a rule quietly dying is itself a failure. Exit 2 when a rule matched nothing, 1 when it set failOnEmpty or broke its selfTest. [--plane <p>] [--fail-on-dead-units] [--json]',
         category: 'core',
         safetyLevel: SafetyLevel.ReadOnly,
         surface: CommandSurface.Common,
@@ -574,6 +602,14 @@ export const COMMAND_CATALOG = Object.freeze([
         surface: CommandSurface.Common,
         taskRole: CommandTaskRole.Search,
     }),
+    entry({
+        command: 'reuse coverage',
+        description: 'Curated reusePrimitives[] vs the real public export surface: curated vs exported counts, dead curated entries, importPaths that do not expose their symbol, and curation gaps (an exported name the reuse lookup answers with a different curated entry). Exit 2 over a missing/stale index. [--min-coverage <pct>] [--package <name>] [--include-types] [--json]',
+        category: 'analysis',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Advanced,
+        taskRole: CommandTaskRole.Validate,
+    }),
     entry({
         command: 'diff-check',
         description: 'Self-check current git diff against boundary + import-hygiene rules. Single-call composite for agents to validate edits before declaring done. Read-only.',
@@ -1384,6 +1420,24 @@ export const COMMAND_CATALOG = Object.freeze([
         surface: CommandSurface.Advanced,
         taskRole: CommandTaskRole.Inspect,
     }),
+    entry({
+        command: 'self-config resolve',
+        description: 'Which registry an id resolves in — every kind, most specific first, with the verb that shows it — and every declared cross-reference pointing at it; did-you-mean when it resolves nowhere. Exit 0 resolved · 1 unresolved · 3 no id. [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.ReadOnly,
+        mcpAvailable: false,
+        surface: CommandSurface.Advanced,
+        taskRole: CommandTaskRole.Explain,
+    }),
+    entry({
+        command: 'self-config xrefs',
+        description: 'Every declared cross-reference id (knowledge related / seeAlso / supersededBy / action hints, construct related* + facets with resolvesAs, boundary related*, template related) with the namespace it resolved into and its status. [--source <kind>:<id>] [--dangling-only] [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.ReadOnly,
+        mcpAvailable: false,
+        surface: CommandSurface.Advanced,
+        taskRole: CommandTaskRole.Inspect,
+    }),
     entry({
         command: 'self-config doctor',
         description: 'Cross-reference integrity for self-config (rule wiring, action hints, verification commands).',
@@ -1546,7 +1600,28 @@ export const COMMAND_CATALOG = Object.freeze([
         category: 'meta',
         safetyLevel: SafetyLevel.ReadOnly,
         surface: CommandSurface.Advanced,
-        intendedAudience: [CommandAudience.Maintainer],
+        intendedAudience: [CommandAudience.Maintainer, CommandAudience.ToolMaintenance],
+        taskRole: CommandTaskRole.Inspect,
+    }),
+    // Round 11 review: both read SharkCraft's OWN catalog and docs
+    // (command-entrypoints / start-here / overview; the `overlaps` view), so in
+    // a consumer repo `docs-check` reported a green check over 0 files.
+    entry({
+        command: 'commands docs-check',
+        description: "Check SharkCraft's own command docs (command-entrypoints / start-here / overview) and catalog pointers for drift.",
+        category: 'meta',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Advanced,
+        intendedAudience: [CommandAudience.Maintainer, CommandAudience.ToolMaintenance],
+        taskRole: CommandTaskRole.Inspect,
+    }),
+    entry({
+        command: 'commands retirement-plan',
+        description: "SharkCraft's own command retirement plan (derived from `commands overlaps`).",
+        category: 'meta',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Advanced,
+        intendedAudience: [CommandAudience.Maintainer, CommandAudience.ToolMaintenance],
         taskRole: CommandTaskRole.Inspect,
     }),
     entry({
@@ -1858,7 +1933,8 @@ export const COMMAND_CATALOG = Object.freeze([
         mcpAvailable: true,
     }),
     // `commands suggest` hard-deleted (folded into unknown-command did-you-mean).
-    // `commands explain` hard-deleted (folded into `shrk explain`).
+    // `commands explain` hard-deleted (use `shrk help <cmd>`; `shrk explain` is the
+    // knowledge / rule topic explainer and never describes a command).
     // `doctor watch` removed (use `shrk doctor --watch`).
     entry({
         command: 'knowledge stale-check --watch',
@@ -2677,7 +2753,7 @@ export const COMMAND_CATALOG = Object.freeze([
         safetyLevel: SafetyLevel.ReadOnly,
         mcpAvailable: true,
         surface: CommandSurface.Advanced,
-        intendedAudience: [CommandAudience.Human, CommandAudience.Ci],
+        intendedAudience: [CommandAudience.Human, CommandAudience.Ci, CommandAudience.ToolMaintenance],
         taskRole: CommandTaskRole.Release,
     }),
     entry({
@@ -2686,6 +2762,7 @@ export const COMMAND_CATALOG = Object.freeze([
         category: 'release',
         safetyLevel: SafetyLevel.ReadOnly,
         mcpAvailable: true,
+        intendedAudience: [CommandAudience.Human, CommandAudience.Agent, CommandAudience.ToolMaintenance],
     }),
     // Additions: human entrypoint, governance, smoke harness.
     entry({
@@ -2708,12 +2785,16 @@ export const COMMAND_CATALOG = Object.freeze([
         intendedAudience: [CommandAudience.Human],
         taskRole: CommandTaskRole.Start,
     }),
+    // Tool-maintenance rows (round 11 §5.1): their object is SharkCraft ITSELF —
+    // its docs set, examples tree, release artifacts. Gated outside the tool's
+    // own repository (tier source `tool-maintenance`, exit 78 — never a failure).
     entry({
         command: 'docs check',
         description: 'Verify docs/ and README content.',
         category: 'governance',
         safetyLevel: SafetyLevel.ReadOnly,
         mcpAvailable: true,
+        intendedAudience: [CommandAudience.Human, CommandAudience.Agent, CommandAudience.ToolMaintenance],
     }),
     entry({
         command: 'examples check',
@@ -2721,6 +2802,7 @@ export const COMMAND_CATALOG = Object.freeze([
         category: 'governance',
         safetyLevel: SafetyLevel.ReadOnly,
         mcpAvailable: true,
+        intendedAudience: [CommandAudience.Human, CommandAudience.Agent, CommandAudience.ToolMaintenance],
     }),
     entry({
         command: 'self audit',
@@ -2728,6 +2810,7 @@ export const COMMAND_CATALOG = Object.freeze([
         category: 'release',
         safetyLevel: SafetyLevel.ReadOnly,
         mcpAvailable: true,
+        intendedAudience: [CommandAudience.Human, CommandAudience.Agent, CommandAudience.ToolMaintenance],
     }),
     entry({
         command: 'release smoke',
@@ -2737,6 +2820,7 @@ export const COMMAND_CATALOG = Object.freeze([
         writesFiles: true,
         runsShell: true,
         mcpAvailable: true,
+        intendedAudience: [CommandAudience.Human, CommandAudience.Agent, CommandAudience.ToolMaintenance],
     }),
     entry({
         command: 'install smoke',
@@ -2745,6 +2829,7 @@ export const COMMAND_CATALOG = Object.freeze([
         safetyLevel: SafetyLevel.WritesDraftsOnly,
         runsShell: true,
         mcpAvailable: true,
+        intendedAudience: [CommandAudience.Human, CommandAudience.Agent, CommandAudience.ToolMaintenance],
     }),
     entry({
         command: 'ci permissions --fix-preview',
@@ -2780,6 +2865,7 @@ export const COMMAND_CATALOG = Object.freeze([
         category: 'release',
         safetyLevel: SafetyLevel.ReadOnly,
         mcpAvailable: true,
+        intendedAudience: [CommandAudience.Human, CommandAudience.Agent, CommandAudience.ToolMaintenance],
     }),
     entry({
         command: 'release readiness --html',
@@ -2787,6 +2873,7 @@ export const COMMAND_CATALOG = Object.freeze([
         category: 'release',
         safetyLevel: SafetyLevel.ReadOnly,
         mcpAvailable: true,
+        intendedAudience: [CommandAudience.Human, CommandAudience.Agent, CommandAudience.ToolMaintenance],
     }),
     // `ci scaffold jenkins|azure --with-release-readiness` hard-deleted with their parents.
     entry({
@@ -2813,6 +2900,7 @@ export const COMMAND_CATALOG = Object.freeze([
         writesFiles: true,
         runsShell: true,
         mcpAvailable: true,
+        intendedAudience: [CommandAudience.Human, CommandAudience.Agent, CommandAudience.ToolMaintenance],
     }),
     entry({
         command: 'release smoke --matrix',
@@ -2822,6 +2910,7 @@ export const COMMAND_CATALOG = Object.freeze([
         writesFiles: true,
         runsShell: true,
         mcpAvailable: true,
+        intendedAudience: [CommandAudience.Human, CommandAudience.Agent, CommandAudience.ToolMaintenance],
     }),
     entry({
         command: 'install smoke --tarball',
@@ -2831,6 +2920,7 @@ export const COMMAND_CATALOG = Object.freeze([
         writesFiles: true,
         runsShell: true,
         mcpAvailable: true,
+        intendedAudience: [CommandAudience.Human, CommandAudience.Agent, CommandAudience.ToolMaintenance],
     }),
     entry({
         command: 'self audit --run',
@@ -2839,6 +2929,7 @@ export const COMMAND_CATALOG = Object.freeze([
         safetyLevel: SafetyLevel.WritesDraftsOnly,
         runsShell: true,
         mcpAvailable: true,
+        intendedAudience: [CommandAudience.Human, CommandAudience.Agent, CommandAudience.ToolMaintenance],
     }),
     entry({
         command: 'diagnostics list',
@@ -2853,7 +2944,10 @@ export const COMMAND_CATALOG = Object.freeze([
         description: 'Audit catalog UX — descriptions, safety metadata, alias collisions.',
         category: 'meta',
         safetyLevel: SafetyLevel.ReadOnly,
-        mcpAvailable: true,
+        // No MCP tool backs this verb (round 11: every tool-maintenance row that
+        // claims mcpAvailable must name a gated tool — r75-tool-maintenance-mcp-gate).
+        mcpAvailable: false,
+        intendedAudience: [CommandAudience.Human, CommandAudience.Agent, CommandAudience.ToolMaintenance],
     }),
     entry({
         command: 'report site --pack-compat',
@@ -3054,7 +3148,8 @@ export const COMMAND_CATALOG = Object.freeze([
         writesFiles: true,
         mcpAvailable: false,
     }),
-    // `heal from-command|-error|-file|-report` hard-deleted. Use `shrk heal --from <source>`.
+    // `heal from-command|-error|-file|-report` hard-deleted, and later the `heal`
+    // group itself. Preview-only repair suggestions live in `shrk fix`.
     entry({
         command: 'contract check',
         description: 'Validate an agent contract (gates, plan readiness, forbidden files, public-API touch, risk/memory approval). Read-only.',
@@ -3229,6 +3324,13 @@ export const COMMAND_CATALOG = Object.freeze([
         safetyLevel: SafetyLevel.WritesDraftsOnly,
         mcpAvailable: true,
     }),
+    entry({
+        command: 'helper doctor',
+        description: 'Validate every helper file (built-in + pack/local): load failures, invalid helpers, duplicate ids, unknown operation keys. Read-only; exit 2 when nothing was examined.',
+        category: 'lifecycle',
+        safetyLevel: SafetyLevel.ReadOnly,
+        mcpAvailable: false,
+    }),
     entry({
         command: 'packs dev-status',
         description: 'Pack-author dev status. Read-only.',
@@ -3246,14 +3348,14 @@ export const COMMAND_CATALOG = Object.freeze([
     }),
     entry({
         command: 'check registry-lifecycle',
-        description: 'register*/remove* symmetry rule. Read-only.',
+        description: 'register*/remove* symmetry rule. Sorted, bounded scan: a capped / over-budget / interrupted run exits 2 with the `--offset <n>` that continues it (`--limit <n>`, `--limit 0` uncapped, `--budget-ms <n>`). Read-only.',
         category: 'core',
         safetyLevel: SafetyLevel.ReadOnly,
         mcpAvailable: true,
     }),
     entry({
         command: 'registry lifecycle',
-        description: 'register*/remove* symmetry rule (standalone command). Read-only.',
+        description: 'register*/remove* symmetry rule (standalone command) — the same body and flags as `check registry-lifecycle`, including `--offset` continuation. Read-only.',
         category: 'core',
         safetyLevel: SafetyLevel.ReadOnly,
         mcpAvailable: true,
@@ -3308,7 +3410,7 @@ export const COMMAND_CATALOG = Object.freeze([
         safetyLevel: SafetyLevel.WritesDraftsOnly,
         writesFiles: true,
         surface: CommandSurface.Advanced,
-        intendedAudience: [CommandAudience.Human],
+        intendedAudience: [CommandAudience.Human, CommandAudience.ToolMaintenance],
         taskRole: CommandTaskRole.Diagnose,
     }),
     entry({
@@ -3317,7 +3419,7 @@ export const COMMAND_CATALOG = Object.freeze([
         category: 'meta',
         safetyLevel: SafetyLevel.ReadOnly,
         surface: CommandSurface.Advanced,
-        intendedAudience: [CommandAudience.Human, CommandAudience.Agent],
+        intendedAudience: [CommandAudience.Human, CommandAudience.Agent, CommandAudience.ToolMaintenance],
         taskRole: CommandTaskRole.Inspect,
     }),
     entry({
@@ -3326,7 +3428,7 @@ export const COMMAND_CATALOG = Object.freeze([
         category: 'meta',
         safetyLevel: SafetyLevel.ReadOnly,
         surface: CommandSurface.Advanced,
-        intendedAudience: [CommandAudience.Human, CommandAudience.Agent],
+        intendedAudience: [CommandAudience.Human, CommandAudience.Agent, CommandAudience.ToolMaintenance],
         taskRole: CommandTaskRole.Inspect,
     }),
     entry({
@@ -3335,7 +3437,7 @@ export const COMMAND_CATALOG = Object.freeze([
         category: 'meta',
         safetyLevel: SafetyLevel.ReadOnly,
         surface: CommandSurface.Advanced,
-        intendedAudience: [CommandAudience.Human, CommandAudience.Agent],
+        intendedAudience: [CommandAudience.Human, CommandAudience.Agent, CommandAudience.ToolMaintenance],
         taskRole: CommandTaskRole.Inspect,
     }),
     // Explore a directory (workspace-aware).
@@ -3375,7 +3477,7 @@ export const COMMAND_CATALOG = Object.freeze([
         safetyLevel: SafetyLevel.ReadOnly,
         mcpAvailable: false,
         surface: CommandSurface.Advanced,
-        intendedAudience: [CommandAudience.Maintainer, CommandAudience.Agent],
+        intendedAudience: [CommandAudience.Maintainer, CommandAudience.Agent, CommandAudience.ToolMaintenance],
         taskRole: CommandTaskRole.Inspect,
     }),
     entry({
@@ -3385,7 +3487,7 @@ export const COMMAND_CATALOG = Object.freeze([
         safetyLevel: SafetyLevel.ReadOnly,
         mcpAvailable: false,
         surface: CommandSurface.Advanced,
-        intendedAudience: [CommandAudience.Maintainer],
+        intendedAudience: [CommandAudience.Maintainer, CommandAudience.ToolMaintenance],
         taskRole: CommandTaskRole.Inspect,
     }),
     entry({
@@ -3395,7 +3497,7 @@ export const COMMAND_CATALOG = Object.freeze([
         safetyLevel: SafetyLevel.ReadOnly,
         mcpAvailable: false,
         surface: CommandSurface.Common,
-        intendedAudience: [CommandAudience.Human, CommandAudience.Maintainer],
+        intendedAudience: [CommandAudience.Human, CommandAudience.Maintainer, CommandAudience.ToolMaintenance],
         taskRole: CommandTaskRole.Inspect,
     }),
     // ── D3-2: registered command groups that resolved live but had ZERO
@@ -3496,14 +3598,14 @@ export const COMMAND_CATALOG = Object.freeze([
     // checks — custom-check registry declared by rules (metadata.checks[]).
     entry({
         command: 'checks list',
-        description: 'List custom checks declared by rules (metadata.checks[]). Read-only.',
+        description: "List custom checks declared on type:'rule' entries (metadata.checks[] in TypeScript rule / knowledge files, local or pack). Names every dropped declaration (a non-rule entry, a Markdown rule, a non-array value) and exits 1 on one. Read-only.",
         category: 'checks',
         safetyLevel: SafetyLevel.ReadOnly,
         taskRole: CommandTaskRole.Inspect,
     }),
     entry({
         command: 'checks doctor',
-        description: 'Validate custom-check descriptors (missing fields, duplicate ids).',
+        description: 'Validate custom-check descriptors (missing fields, duplicate ids, declarations that can never run). Exit 0 · 1 errors · 2 nothing declared (--allow-empty accepts).',
         category: 'checks',
         safetyLevel: SafetyLevel.ReadOnly,
         taskRole: CommandTaskRole.Diagnose,
@@ -3724,6 +3826,7 @@ export const R46_OVERLAY = Object.freeze({
     'helper get': { verdict: 'hidden', reason: 'Helpers advanced.' },
     'helper list': { verdict: 'hidden', reason: 'Helpers advanced.' },
     'helper plan': { verdict: 'hidden', reason: 'Helpers advanced.' },
+    'helper doctor': { verdict: 'hidden', reason: 'Helpers advanced.' },
     // memory.
     'memory diagnostics': { verdict: 'hidden', reason: 'Memory support tools are advanced.' },
     'memory diff': { verdict: 'hidden', reason: 'Memory support tools are advanced.' },
@@ -3781,6 +3884,13 @@ export function commandAudience(e) {
         ? [CommandAudience.Human, CommandAudience.Agent]
         : [CommandAudience.Human];
 }
+/**
+ * True when the row maintains SharkCraft itself ({@link CommandAudience.ToolMaintenance}).
+ * The tier resolver gates such a row outside the tool's own repository.
+ */
+export function isToolMaintenance(e) {
+    return commandAudience(e).includes(CommandAudience.ToolMaintenance);
+}
 /** Task role (or `undefined` when not classified). */
 export function commandTaskRole(e) {
     return e.taskRole;
@@ -3938,21 +4048,28 @@ export function defaultShowInHelp(e) {
  * R46-pruned are excluded), sorted by command.
  */
 export function listExplainFamily() {
-    return COMMAND_CATALOG.filter((e) => {
-        const lc = commandLifecycle(e);
-        if (lc === CommandLifecycle.Deprecated ||
-            lc === CommandLifecycle.Retired ||
-            lc === CommandLifecycle.Alias) {
-            return false;
-        }
-        if (R46_OVERLAY[e.command])
-            return false;
-        const role = commandTaskRole(e);
-        return role === CommandTaskRole.Explain || /(^|\s)explain$/.test(e.command);
-    })
+    return COMMAND_CATALOG.filter(isExplainFamily)
         .slice()
         .sort((a, b) => a.command.localeCompare(b.command));
 }
+/**
+ * Membership in the explain / dry-run family ({@link listExplainFamily}).
+ * `--full-help` lists the family in its own section, so the surface summary's
+ * `visibleInHelp` counts it too: the one visibility authority and the help
+ * renderer must answer "is X in --help" identically.
+ */
+export function isExplainFamily(e) {
+    const lc = commandLifecycle(e);
+    if (lc === CommandLifecycle.Deprecated ||
+        lc === CommandLifecycle.Retired ||
+        lc === CommandLifecycle.Alias) {
+        return false;
+    }
+    if (R46_OVERLAY[e.command])
+        return false;
+    const role = commandTaskRole(e);
+    return role === CommandTaskRole.Explain || /(^|\s)explain$/.test(e.command);
+}
 /**
  * Short "Use this when…" line derived from `surface`, `taskRole`,
  * `preferredCommand`, `replacedBy`, and `machineOnly`. Empty string when

package/dist/commands/commands.command.d.ts

@@ -1,7 +1,13 @@
 import { type CommandRegistry, type ICommandHandler } from '../command-registry.js';
 import { type ISurfaceProfile } from '../surface/profiles.js';
+import type { IVerdictCoverage } from '@shrkcrft/core';
 import { type ICommandCatalogEntry } from './command-catalog.js';
-export declare function makeCommandsCommand(registry: CommandRegistry): ICommandHandler;
+/**
+ * `catalog` is the rows `commands doctor` checks against `registry` (default
+ * COMMAND_CATALOG) — injectable so a test can prove a catalog/registry join
+ * end to end through the verb. Every other subcommand browses COMMAND_CATALOG.
+ */
+export declare function makeCommandsCommand(registry: CommandRegistry, catalog?: readonly ICommandCatalogEntry[]): ICommandHandler;
 export interface ICommandsProfileView {
     profile: ISurfaceProfile;
     entries: readonly ICommandCatalogEntry[];
@@ -52,7 +58,13 @@ export interface ICommandsDoctorReport {
         registeredSubcommands: number;
         errors: number;
         warnings: number;
+        /** Rows of the command index (0 without a registry). */
+        indexEntries: number;
+        /** Registered, dispatchable paths with no catalog row (`registry-path-not-in-catalog`). */
+        uncatalogued: number;
     };
+    /** What the exhaustiveness pass examined: every registered handler path. */
+    coverage: IVerdictCoverage;
 }
 export interface ICommandsUxIssue {
     code: 'missing-description' | 'missing-safety-metadata' | 'duplicate-alias' | 'unreferenced-primary' | 'short-description' | 'missing-docs-link' | 'primary-without-audience' | 'primary-without-role' | 'machine-marked-primary' | 'legacy-without-replacement' | 'overlap-without-preferred' | 'description-without-purpose' | 'too-many-primary-for-role' | 'deprecated-without-replacement' | 'alias-without-target' | 'nonstandard-verbosity-flag';
@@ -72,8 +84,14 @@ export interface ICommandsUxReport {
     };
 }
 export declare function buildCommandsUxReport(): ICommandsUxReport;
-/** Pure: build the doctor report. Exported for tests. */
-export declare function buildCommandsDoctorReport(registry: CommandRegistry | null): ICommandsDoctorReport;
+/**
+ * Pure: build the doctor report. Exported for tests.
+ *
+ * `catalog` defaults to COMMAND_CATALOG. A test passes its own rows (with a
+ * registry of its own) to prove a join end to end — every check below reads
+ * the SAME rows, so a fixture catalog is never mixed with the real one.
+ */
+export declare function buildCommandsDoctorReport(registry: CommandRegistry | null, catalog?: readonly ICommandCatalogEntry[]): ICommandsDoctorReport;
 /**
  * Docs drift check. Walks the canonical docs pages and verifies that
  * every `shrk <command>` reference resolves to a non-deprecated catalog

package/dist/commands/commands.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commands.command.d.ts","sourceRoot":"","sources":["../../src/commands/commands.command.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"commands.command.d.ts","sourceRoot":"","sources":["../../src/commands/commands.command.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,eAAe,EAGpB,KAAK,eAAe,EAGrB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAKvD,OAAO,EASL,KAAK,oBAAoB,EAI1B,MAAM,sBAAsB,CAAC;AAS9B;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,eAAe,EACzB,OAAO,GAAE,SAAS,oBAAoB,EAAoB,GACzD,eAAe,CA2NjB;AAkDD,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,eAAe,CAAC;IACzB,OAAO,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACzC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,EACjB,YAAY,GAAE,SAAS,eAAe,EAAO,GAC5C,oBAAoB,GAAG,SAAS,CAMlC;AAwND,MAAM,WAAW,oBAAoB;IACnC,MAAM,EACF,YAAY,GACZ,SAAS,GACT,iBAAiB,GACjB,aAAa,GACb,oBAAoB,GACpB,uBAAuB,CAAC;IAC5B,OAAO,EAAE,SAAS;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,eAAe,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACtK;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,wCAAwC,CAAC;IACjD,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,SAAS,oBAAoB,EAAE,CAAC;CACzC;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,IAAI,qBAAqB,CAqDjE;AAsFD,iFAAiF;AACjF,eAAO,MAAM,eAAe,EAAE,eAqE7B,CAAC;AAEF,UAAU,oBAAoB;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;CACxC;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACxC,OAAO,EAAE;QACP,cAAc,EAAE,MAAM,CAAC;QACvB,kBAAkB,EAAE,MAAM,CAAC;QAC3B,qBAAqB,EAAE,MAAM,CAAC;QAC9B,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,wDAAwD;QACxD,YAAY,EAAE,MAAM,CAAC;QACrB,2FAA2F;QAC3F,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,4EAA4E;IAC5E,QAAQ,EAAE,gBAAgB,CAAC;CAC5B;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EACA,qBAAqB,GACrB,yBAAyB,GACzB,iBAAiB,GACjB,sBAAsB,GACtB,mBAAmB,GACnB,mBAAmB,GAEnB,0BAA0B,GAC1B,sBAAsB,GACtB,wBAAwB,GACxB,4BAA4B,GAC5B,2BAA2B,GAC3B,6BAA6B,GAC7B,2BAA2B,GAE3B,gCAAgC,GAChC,sBAAsB,GACtB,4BAA4B,CAAC;IACjC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,iCAAiC,CAAC;IAC1C,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACpC,OAAO,EAAE;QACP,cAAc,EAAE,MAAM,CAAC;QACvB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;CACH;AAoBD,wBAAgB,qBAAqB,IAAI,iBAAiB,CAsMzD;AAsBD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,eAAe,GAAG,IAAI,EAChC,OAAO,GAAE,SAAS,oBAAoB,EAAoB,GACzD,qBAAqB,CA+OvB;AAgKD;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EACA,qBAAqB,GACrB,yBAAyB,GACzB,qBAAqB,GACrB,2BAA2B,CAAC;IAChC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,mCAAmC,CAAC;IAC5C,MAAM,EAAE,OAAO,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,SAAS,eAAe,EAAE,CAAC;IACnC,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7D;AAQD,wBAAsB,oBAAoB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA+ElF"}