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

package/dist/commands/commands.command.js

@@ -1,17 +1,67 @@
 import { flagBool, flagString, resolveCwd } from "../command-registry.js";
+import { PositionalMode } from "../dispatch/positional-mode.js";
 import { asJson, header } from "../output/format-output.js";
 import { BUILTIN_PROFILES, getProfile } from "../surface/profiles.js";
+import { CommandDispatchKind } from "../surface/command-dispatch-kind.js";
+import { buildCommandIndex } from "../surface/command-index.js";
+import { settleVerdict } from "../gates/settle-verdict.js";
+import { verdictLine } from "../gates/verdict-line.js";
 import { buildCommandSafetyMatrix, COMMAND_CATALOG, CommandLifecycle, commandLifecycle, CommandSurface, commandSurface, commandTaskRole, defaultShowInHelp, R46_OVERLAY, renderCommandSafetyMatrixMarkdown, SafetyLevel } from "./command-catalog.js";
 import { buildCommandTaxonomy, buildPrimaryCommandsReport, renderCommandTaxonomyMarkdown, renderCommandTaxonomyText, renderPrimaryCommandsText } from '@shrkcrft/inspector';
-export function makeCommandsCommand(registry) {
+/**
+ * `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 function makeCommandsCommand(registry, catalog = COMMAND_CATALOG) {
     return {
         name: 'commands',
-        description: 'Browse the command catalog. Default view is compact (primary + common); pass --all for the full catalog, or --profile <id> (e.g. agent) for the surface a profile sees. Subcommands: primary | advanced | deprecated | hidden | retirement-plan | docs-check | surface | profile | machine | legacy | overlaps | taxonomy | matrix | tree | search | suggest | explain | entrypoints | doctor | ux-check.',
-        usage: 'shrk commands [primary|advanced|deprecated|hidden|retirement-plan|docs-check|surface <s>|profile [<id>]|machine|legacy|overlaps|taxonomy|matrix|tree|search <q>|suggest <p>|explain <cmd>|entrypoints|doctor|ux-check] [--all] [--profile <id>] [--safety <level>] [--category <name>] [--json]',
+        // `suggest` / `explain` were hard-deleted (folded into the unknown-command
+        // did-you-mean and `shrk explain` — see command-catalog.ts) but still
+        // advertised here, so `commands suggest x` fell through to the default
+        // listing at exit 0. The declared set below is what `run` actually handles;
+        // anything else is an unknown subcommand.
+        description: 'Browse the command catalog. Default view is compact (primary + common); pass --all for the full catalog, or --profile <id> (e.g. agent) for the surface a profile sees. Subcommands: primary | advanced | deprecated | hidden | retirement-plan | docs-check | surface | profile | machine | legacy | overlaps | taxonomy | matrix | tree | search | entrypoints | doctor | ux-check.',
+        usage: 'shrk commands [primary|advanced|deprecated|hidden|retirement-plan|docs-check|surface <s>|profile [<id>]|machine|legacy|overlaps|taxonomy|matrix|tree|search <q>|entrypoints|doctor|ux-check] [--all] [--profile <id>] [--safety <level>] [--category <name>] [--json]',
+        positionals: PositionalMode.None,
+        subverbs: [
+            { name: 'primary', description: 'The primary (spine) commands.', usage: 'shrk commands primary [--json]' },
+            { name: 'advanced', description: 'The advanced commands.', usage: 'shrk commands advanced [--json]' },
+            { name: 'deprecated', description: 'Deprecated commands and their replacements.', usage: 'shrk commands deprecated [--json]' },
+            { name: 'hidden', description: 'Commands hidden from default help.', usage: 'shrk commands hidden [--json]' },
+            { name: 'retirement-plan', description: 'The command retirement plan.', usage: 'shrk commands retirement-plan [--json]' },
+            { name: 'docs-check', description: 'Catalog rows vs the docs that mention them.', usage: 'shrk commands docs-check [--json]' },
+            { name: 'surface', description: 'The catalog filtered to one command surface.', usage: 'shrk commands surface <surface> [--json]', positionals: PositionalMode.Free },
+            {
+                name: 'profile',
+                description: 'List surface profiles, or render the catalog as one profile sees it.',
+                usage: 'shrk commands profile [<id>] [--json]',
+                positionals: PositionalMode.Free,
+            },
+            { name: 'machine', description: 'Machine-oriented (JSON / MCP) commands.', usage: 'shrk commands machine [--json]' },
+            { name: 'legacy', description: 'Legacy command spellings.', usage: 'shrk commands legacy [--json]' },
+            { name: 'overlaps', description: 'Commands that overlap, and which to prefer.', usage: 'shrk commands overlaps [--json]' },
+            {
+                name: 'taxonomy',
+                description: 'The command taxonomy.',
+                usage: 'shrk commands taxonomy [--format text|markdown|json] [--output <path>] [--write-docs] [--json]',
+            },
+            { name: 'matrix', description: 'The command safety matrix.', usage: 'shrk commands matrix [--format markdown|json] [--json]' },
+            { name: 'tree', description: 'The command tree.', usage: 'shrk commands tree [--json]' },
+            { name: 'search', description: 'Filter the catalog by a query.', usage: 'shrk commands search <query> [--json]', positionals: PositionalMode.Free },
+            {
+                name: 'entrypoints',
+                aliases: ['workflows'],
+                description: 'The entrypoint matrix (human / agent / machine / debug).',
+                usage: 'shrk commands entrypoints [--json]',
+            },
+            { name: 'doctor', description: 'Registry ↔ catalog ↔ index consistency.', usage: 'shrk commands doctor [--json]' },
+            { name: 'ux-check', description: 'Command UX checks.', usage: 'shrk commands ux-check [--json]' },
+        ],
         async run(args) {
             const sub = args.positional[0];
             if (sub === 'doctor') {
-                return runCommandsDoctor(args, registry);
+                return runCommandsDoctor(args, registry, catalog);
             }
             if (sub === 'ux-check') {
                 return runCommandsUxCheck(args);
@@ -879,12 +929,18 @@ async function runCommandsUxCheck(args) {
     }
     return report.passed ? 0 : 1;
 }
-/** Pure: build the doctor report. Exported for tests. */
-export function buildCommandsDoctorReport(registry) {
+/**
+ * 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 function buildCommandsDoctorReport(registry, catalog = COMMAND_CATALOG) {
     const issues = [];
     // 1. No duplicate commands.
     const seen = new Set();
-    for (const e of COMMAND_CATALOG) {
+    for (const e of catalog) {
         if (seen.has(e.command)) {
             issues.push({
                 code: 'duplicate-command',
@@ -896,7 +952,7 @@ export function buildCommandsDoctorReport(registry) {
     }
     // 2. Every entry has a safety level + description + category.
     const validLevels = new Set(Object.values(SafetyLevel));
-    for (const e of COMMAND_CATALOG) {
+    for (const e of catalog) {
         if (!e.description || e.description.trim().length === 0) {
             issues.push({
                 code: 'missing-description',
@@ -920,7 +976,7 @@ export function buildCommandsDoctorReport(registry) {
         }
     }
     // 3. writes-source ⇒ not MCP-available.
-    for (const e of COMMAND_CATALOG) {
+    for (const e of catalog) {
         if (e.writesSource && e.mcpAvailable) {
             issues.push({
                 code: 'writes-source-via-mcp',
@@ -930,7 +986,7 @@ export function buildCommandsDoctorReport(registry) {
         }
     }
     // 4. writesSource ⇒ writesFiles.
-    for (const e of COMMAND_CATALOG) {
+    for (const e of catalog) {
         if (e.writesSource && !e.writesFiles) {
             issues.push({
                 code: 'writes-source-without-writes-files',
@@ -940,7 +996,7 @@ export function buildCommandsDoctorReport(registry) {
         }
     }
     // 5. runs-shell safety level ⇒ runsShell flag (and vice versa).
-    for (const e of COMMAND_CATALOG) {
+    for (const e of catalog) {
         if (e.safetyLevel === SafetyLevel.RunsShell && !e.runsShell) {
             issues.push({
                 code: 'shell-level-without-flag',
@@ -959,7 +1015,7 @@ export function buildCommandsDoctorReport(registry) {
             const sub = registry.listGroup(g);
             registeredSub += sub.length;
         }
-        for (const e of COMMAND_CATALOG) {
+        for (const e of catalog) {
             const parts = e.command.split(' ');
             const top = parts[0];
             const second = parts[1];
@@ -995,7 +1051,7 @@ export function buildCommandsDoctorReport(registry) {
         }
         // 7. Registered commands without a catalog entry.
         for (const c of registry.list()) {
-            const inCatalog = COMMAND_CATALOG.some((e) => e.command === c.name || e.command.startsWith(c.name + ' '));
+            const inCatalog = catalog.some((e) => e.command === c.name || e.command.startsWith(c.name + ' '));
             if (!inCatalog) {
                 // Promoted to error for primary verbs: if a user types
                 // `shrk help <cmd>` we should be able to print catalog metadata
@@ -1025,7 +1081,7 @@ export function buildCommandsDoctorReport(registry) {
         // canonical target carries the entry.
         const aliasGroups = new Set(registry.listGroupAliases().keys());
         const catalogTopWords = new Set();
-        for (const e of COMMAND_CATALOG) {
+        for (const e of catalog) {
             const top = e.command.split(/\s+/)[0];
             if (top)
                 catalogTopWords.add(top);
@@ -1042,51 +1098,134 @@ export function buildCommandsDoctorReport(registry) {
             }
         }
     }
+    // 9. Exhaustiveness, at PATH granularity, over THE command index (what
+    // `surface list` and `help` show). Checks 6–8 only compared top-level
+    // handlers and groups, so 75 registered 2-level paths (`knowledge list`,
+    // `gates check`, …) with no catalog row — and so no safety metadata — read
+    // as "OK ✓".
+    let indexEntries = 0;
+    let uncatalogued = 0;
+    const handlerPaths = registry ? registry.listAll().map(({ path }) => path.join(' ')) : [];
+    let unreached = [];
+    if (registry) {
+        const index = buildCommandIndex(registry, catalog);
+        indexEntries = index.entries.length;
+        // The pass below examines INDEX rows. A registered handler path the index
+        // join dropped was never examined — an unexamined unit, not a clean one.
+        unreached = handlerPaths.filter((p) => !index.byPath.has(p));
+        for (const e of index.entries) {
+            if (e.dispatch === CommandDispatchKind.Meta)
+                continue;
+            if (!e.catalogued) {
+                uncatalogued += 1;
+                issues.push({
+                    code: 'registry-path-not-in-catalog',
+                    message: `"${e.path}" is registered and dispatchable but has no catalog row (no safety metadata) — add one to command-catalog.ts`,
+                    severity: 'warning',
+                });
+            }
+            // A catalog row documenting an internal subverb of a handler that
+            // DECLARES its subverbs — but not this one — documents a verb the handler
+            // does not dispatch. (Handlers that declare nothing stay unchecked.)
+            if (e.dispatch === CommandDispatchKind.Subverb && e.declared === false && e.parent) {
+                const parentTokens = e.parent.split(' ');
+                const declared = registry.getAt(parentTokens)?.subverbs;
+                const name = e.tokens[parentTokens.length];
+                if (declared && name !== undefined && !declared.some((s) => s.name === name || s.aliases?.includes(name))) {
+                    issues.push({
+                        code: 'undeclared-internal-subverb',
+                        message: `catalog documents "${e.path}" but "${e.parent}" declares its subverbs and "${name}" is not one of them`,
+                        severity: 'error',
+                    });
+                }
+            }
+        }
+    }
     const errors = issues.filter((i) => i.severity === 'error').length;
     const warnings = issues.filter((i) => i.severity === 'warning').length;
     return {
         passed: errors === 0,
         issues,
         summary: {
-            catalogEntries: COMMAND_CATALOG.length,
+            catalogEntries: catalog.length,
             registeredCommands: registered,
             registeredSubcommands: registeredSub,
             errors,
             warnings,
+            indexEntries,
+            uncatalogued,
+        },
+        // Without a registry the path-level pass examined nothing — say so rather
+        // than let a catalog-only run read as a full exhaustiveness check.
+        coverage: {
+            unit: 'registered command paths',
+            expected: handlerPaths.length,
+            examined: handlerPaths.length - unreached.length,
+            ...(unreached.length > 0
+                ? {
+                    unexamined: unreached.slice(0, 20),
+                    unexaminedTotal: unreached.length,
+                    reason: 'not reached by the command index',
+                }
+                : {}),
+            ...(registry ? {} : { reason: 'no command registry was supplied' }),
         },
     };
 }
-function runCommandsDoctor(args, registry) {
-    const report = buildCommandsDoctorReport(registry);
+/**
+ * The exit-0 sentence. A ✓ only when there is nothing at all to report — "OK ✓"
+ * under 78 warnings read as a clean catalog (policy-lint's §13 precedent).
+ */
+function commandsDoctorCleanLine(report) {
+    const infos = report.issues.filter((i) => i.severity === 'info').length;
+    if (report.summary.warnings > 0) {
+        return `\nNo blocking catalog drift — ${report.summary.warnings} warning(s) reported above.`;
+    }
+    if (infos > 0)
+        return `\nNo catalog drift — ${infos} note(s) reported above.`;
+    return '\nVerdict: OK ✓';
+}
+function runCommandsDoctor(args, registry, catalog = COMMAND_CATALOG) {
+    const report = buildCommandsDoctorReport(registry, catalog);
     const strict = flagBool(args, 'strict');
     // `--strict` promotes any catalog drift (warnings AND info) to a
     // failing verdict. Without --strict, only errors fail the verdict.
     const failed = report.summary.errors > 0 || (strict && report.summary.warnings > 0);
+    // Settle first, render second: the path-level pass must have examined every
+    // registered path for a clean verdict to be a pass.
+    const settled = settleVerdict(failed ? 1 : 0, [report.coverage]);
     if (flagBool(args, 'json')) {
         process.stdout.write(asJson({
             ...report,
             strict,
-            verdict: failed ? 'drift' : 'clean',
+            verdict: settled.exit === 0 ? 'clean' : settled.exit === 1 ? 'drift' : 'not-verified',
+            exitCode: settled.exit,
+            shortfalls: settled.shortfalls,
         }) + '\n');
-        return failed ? 1 : 0;
+        return settled.exit;
     }
     process.stdout.write(header('Command catalog doctor'));
     process.stdout.write(`  catalogEntries: ${report.summary.catalogEntries}\n` +
         `  registered:     ${report.summary.registeredCommands}\n` +
         `  subcommands:    ${report.summary.registeredSubcommands}\n` +
+        `  index entries:  ${report.summary.indexEntries}\n` +
+        `  uncatalogued:   ${report.summary.uncatalogued}\n` +
         `  errors:         ${report.summary.errors}\n` +
         `  warnings:       ${report.summary.warnings}\n` +
         (strict ? `  strict:         on\n` : '') +
         '\n');
     if (report.issues.length === 0) {
         process.stdout.write('No issues.\n');
-        return 0;
     }
     for (const i of report.issues) {
         process.stdout.write(`  ${i.severity.toUpperCase().padEnd(8)} ${i.code.padEnd(34)} ${i.message}\n`);
     }
-    process.stdout.write(`\nVerdict: ${failed ? 'CATALOG DRIFT' : 'OK ✓'}\n`);
-    return failed ? 1 : 0;
+    if (settled.exit === 1)
+        process.stdout.write('\nVerdict: CATALOG DRIFT\n');
+    const line = verdictLine(settled, commandsDoctorCleanLine(report));
+    if (line)
+        process.stdout.write(line + '\n');
+    return settled.exit;
 }
 function printCatalog(args, entries) {
     if (flagBool(args, 'json')) {
@@ -1166,7 +1305,7 @@ function printCompactCatalog(args, entries) {
     process.stdout.write('  $ shrk commands overlaps                — overlapping surfaces + preferred entrypoint\n');
     process.stdout.write('  $ shrk commands retirement-plan         — lifecycle backlog\n');
     process.stdout.write('  $ shrk commands taxonomy                — domain grouping\n');
-    process.stdout.write('  $ shrk commands explain <cmd>           — detail for one command\n');
+    process.stdout.write('  $ shrk explain <cmd>                    — detail for one command\n');
     return 0;
 }
 function sortByCommand(entries) {
@@ -1304,15 +1443,21 @@ function extractShrkRefs(content) {
 }
 async function runCommandsDocsCheck(args) {
     const report = await buildDocsCheckReport();
+    // Zero docs read checked nothing: a ✓ over it is the "check that cannot
+    // fail" this round removes — NOT VERIFIED (2), never a pass.
+    const examinedNothing = report.filesChecked === 0;
+    const exit = !report.passed ? 1 : examinedNothing ? 2 : 0;
     if (flagBool(args, 'json')) {
-        process.stdout.write(asJson(report) + '\n');
-        return report.passed ? 0 : 1;
+        process.stdout.write(asJson({ ...report, exitCode: exit, ...(examinedNothing ? { verdict: 'not-verified' } : {}) }) + '\n');
+        return exit;
     }
     process.stdout.write(header('Commands docs-check'));
     process.stdout.write(`  files ${report.filesChecked}  errors ${report.summary.errors}  warnings ${report.summary.warnings}  info ${report.summary.info}\n\n`);
     if (report.issues.length === 0) {
-        process.stdout.write('No docs drift detected. ✓\n');
-        return 0;
+        process.stdout.write(examinedNothing
+            ? `NOT VERIFIED: 0 of ${DOCS_TO_CHECK.length} docs to check exist here (${DOCS_TO_CHECK.join(', ')}) — nothing was checked (this is not a pass).\n`
+            : 'No docs drift detected. ✓\n');
+        return exit;
     }
     for (const i of report.issues) {
         const tag = `[${i.severity.padEnd(8)}] ${i.code.padEnd(28)}`;

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

@@ -1 +1 @@
-{"version":3,"file":"compress.command.d.ts","sourceRoot":"","sources":["../../src/commands/compress.command.ts"],"names":[],"mappings":"AASA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA8FhC,eAAO,MAAM,eAAe,EAAE,eA0H7B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,eA4B3B,CAAC"}
+{"version":3,"file":"compress.command.d.ts","sourceRoot":"","sources":["../../src/commands/compress.command.ts"],"names":[],"mappings":"AASA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA+FhC,eAAO,MAAM,eAAe,EAAE,eA6H7B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,eA4B3B,CAAC"}

package/dist/commands/compress.command.js

@@ -2,6 +2,7 @@ import { readFileSync } from 'node:fs';
 import { Buffer } from 'node:buffer';
 import { compressContent, ECompressionStrategy, EContentType, } from '@shrkcrft/compress';
 import { flagBool, flagNumber, flagString, resolveCwd, } from "../command-registry.js";
+import { PositionalMode } from "../dispatch/positional-mode.js";
 import { asJson } from "../output/format-output.js";
 import { ccrDir, openCcrStore } from "../output/ccr-store-config.js";
 const CONTENT_TYPES = new Set(Object.values(EContentType));
@@ -85,6 +86,9 @@ const COMPRESS_BOOLEAN_FLAGS = new Set([
 ]);
 export const compressCommand = {
     name: 'compress',
+    // positional[0] is the input FILE (`-` / --stdin read stdin); a verb-shaped
+    // non-file is refused before it becomes an ENOENT.
+    positionals: PositionalMode.Path,
     description: 'Compress a blob (file or stdin) deterministically to cut tokens — JSON→table, logs/search/diffs→signal. Reversible via `shrk expand`. NOTE: `--type code` emits a LOSSY outline (function bodies elided) — good for fitting more code into context, NOT for line-accurate reading; use plain Read (or `--lossless`) to inspect a file.',
     usage: 'shrk [--cwd <dir>] compress [<file>|-] [--stdin] [--type <content-type>] [--query <text>] [--max <n>] [--lossless] [--no-cache] [--json]',
     booleanFlags: COMPRESS_BOOLEAN_FLAGS,

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

@@ -1 +1 @@
-{"version":3,"file":"constructs.command.d.ts","sourceRoot":"","sources":["../../src/commands/constructs.command.ts"],"names":[],"mappings":"AA8BA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAkKhC,eAAO,MAAM,qBAAqB,EAAE,eAqBnC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAmDlC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAgGpC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAyErC,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,eAkCtC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eA2BpC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAiClC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAiBrC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAkBrC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eA2BrC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eA8BrC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eA0DpC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eA0LpC,CAAC"}
+{"version":3,"file":"constructs.command.d.ts","sourceRoot":"","sources":["../../src/commands/constructs.command.ts"],"names":[],"mappings":"AAgCA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAoKhC,eAAO,MAAM,qBAAqB,EAAE,eA2BnC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAmDlC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAgGpC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAyErC,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,eAyDtC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eA2BpC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAiClC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAiBrC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAkBrC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eA2BrC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eA8BrC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eA0DpC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAqMpC,CAAC"}

package/dist/commands/constructs.command.js

@@ -1,8 +1,10 @@
 import { mkdirSync, writeFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
-import { AdoptionCheckpointStatus, buildConstructAdoptionDiff, buildConstructAdoptionPlan, buildSearchIndex, ConstructAdoptionCategory, evaluateAdoptionCheckpoint, hashDiffBody, inferConstructs, InferredConstructConfidence, inspectSharkcraft, loadConstructs, loadPlaybooks, readAdoptionCheckpoint, readConstructAdoptionStatus, recordAdoptionCheckpoint, renderConstructAdoptionDiff, renderConstructAdoptionMarkdown, renderConstructDraftsModule, searchIndex, SearchKind, traceConstruct, writeConstructAdoption, } from '@shrkcrft/inspector';
+import { AdoptionCheckpointStatus, buildConstructAdoptionDiff, buildDeclaredXrefReport, buildConstructAdoptionPlan, buildSearchIndex, ConstructAdoptionCategory, ContributionKind, evaluateAdoptionCheckpoint, hashDiffBody, inferConstructs, InferredConstructConfidence, inspectSharkcraft, loadConstructs, loadPlaybooks, readAdoptionCheckpoint, readConstructAdoptionStatus, recordAdoptionCheckpoint, renderConstructAdoptionDiff, renderConstructAdoptionMarkdown, renderConstructDraftsModule, searchIndex, SearchKind, traceConstruct, writeConstructAdoption, } from '@shrkcrft/inspector';
 import { GraphQueryApi, GraphStore } from '@shrkcrft/graph';
 import { flagBool, flagNumber, flagString, resolveCwd, } from "../command-registry.js";
+import { PositionalMode } from "../dispatch/positional-mode.js";
+import { writeRejectedEntriesNote } from "../output/rejected-entries-note.js";
 import { asJson, header } from "../output/format-output.js";
 /**
  * A construct subverb was handed an id that is NOT a registered construct.
@@ -129,19 +131,25 @@ export const constructsListCommand = {
     description: 'List registered constructs.',
     usage: 'shrk constructs list [--type <type>] [--json]',
     async run(args) {
-        const { constructs } = await loadAll(args);
+        const { constructs, inspection } = await loadAll(args);
         const type = flagString(args, 'type');
         const list = type ? constructs.filter((c) => c.type === type) : constructs;
+        // A construct (or facet) its loader refused is named (round 12, 12.1) —
+        // an id-less one used to vanish, and one without `type` crashed this list.
+        const kinds = [ContributionKind.Construct, ContributionKind.ConstructFacet];
+        const note = { next: 'shrk packs contributions' };
         if (flagBool(args, 'json')) {
             process.stdout.write(asJson(list) + '\n');
+            await writeRejectedEntriesNote(inspection, kinds, { ...note, json: true });
             return 0;
         }
         process.stdout.write(header(`Constructs (${list.length})`));
         if (list.length === 0)
             process.stdout.write('  (none)\n');
         for (const c of list) {
-            process.stdout.write(`  ${c.id.padEnd(40)} ${c.type.padEnd(12)} ${c.title}\n`);
+            process.stdout.write(`  ${c.id.padEnd(40)} ${String(c.type ?? '').padEnd(12)} ${c.title ?? ''}\n`);
         }
+        await writeRejectedEntriesNote(inspection, kinds, note);
         return 0;
     },
 };
@@ -388,18 +396,29 @@ export const constructsRelatedCommand = {
             process.stderr.write('Usage: shrk constructs related <id>\n');
             return 2;
         }
-        const { constructs } = await loadAll(args);
+        const { constructs, inspection } = await loadAll(args);
         const c = constructs.find((x) => x.id === id);
         if (!c) {
             return emitConstructMiss(id, args);
         }
+        // Each id annotated from THE declared cross-reference collector: the
+        // namespace(s) it resolved into, or UNRESOLVED. The `[kind]` label is the
+        // FIELD's kind — it used to be the only thing printed, so a dangling id
+        // rendered exactly like a live one.
+        const xrefs = await buildDeclaredXrefReport(inspection);
+        const rowFor = new Map(xrefs.rows
+            .filter((r) => r.sourceKind === 'construct' && r.sourceId === id)
+            .map((r) => [`${r.field}|${r.targetId}`, r]));
         const related = [
-            ...(c.relatedKnowledge ?? []).map((id) => ({ kind: 'knowledge', id })),
-            ...(c.relatedRules ?? []).map((id) => ({ kind: 'rule', id })),
-            ...(c.relatedTemplates ?? []).map((id) => ({ kind: 'template', id })),
-            ...(c.relatedPipelines ?? []).map((id) => ({ kind: 'pipeline', id })),
-            ...(c.relatedPathConventions ?? []).map((id) => ({ kind: 'path', id })),
-        ];
+            ...(c.relatedKnowledge ?? []).map((rid) => ({ kind: 'knowledge', id: rid, field: 'relatedKnowledge' })),
+            ...(c.relatedRules ?? []).map((rid) => ({ kind: 'rule', id: rid, field: 'relatedRules' })),
+            ...(c.relatedTemplates ?? []).map((rid) => ({ kind: 'template', id: rid, field: 'relatedTemplates' })),
+            ...(c.relatedPipelines ?? []).map((rid) => ({ kind: 'pipeline', id: rid, field: 'relatedPipelines' })),
+            ...(c.relatedPathConventions ?? []).map((rid) => ({ kind: 'path', id: rid, field: 'relatedPathConventions' })),
+        ].map((r) => {
+            const row = rowFor.get(`${r.field}|${r.id}`);
+            return { kind: r.kind, id: r.id, resolvedAs: row?.resolvedAs ?? [], status: row?.status ?? 'unverified' };
+        });
         if (flagBool(args, 'json')) {
             process.stdout.write(asJson({ id, related }) + '\n');
             return 0;
@@ -409,8 +428,16 @@ export const constructsRelatedCommand = {
             process.stdout.write('  (none)\n');
             return 0;
         }
-        for (const r of related)
-            process.stdout.write(`  • [${r.kind}] ${r.id}\n`);
+        for (const r of related) {
+            const resolved = r.status === 'ok'
+                ? `→ ${r.resolvedAs.join(' | ')}`
+                : r.status === 'dangling'
+                    ? 'UNRESOLVED — no registry has this id'
+                    : r.status === 'wrong-kind'
+                        ? `WRONG KIND — resolves as ${r.resolvedAs.join(' | ')}`
+                        : 'NOT VERIFIED';
+            process.stdout.write(`  • [${r.kind}] ${r.id}  ${resolved}\n`);
+        }
         return 0;
     },
 };
@@ -634,6 +661,17 @@ export const constructsInferCommand = {
 };
 export const constructsAdoptCommand = {
     name: 'adopt',
+    // An unknown token used to fall through to the adoption plan at exit 0.
+    positionals: PositionalMode.None,
+    subverbs: [
+        { name: 'status', description: 'Construct-adoption status.', usage: 'shrk constructs adopt status [--json]' },
+        { name: 'review', description: 'Review the construct-adoption plan.', usage: 'shrk constructs adopt review [--json]' },
+        {
+            name: 'diff',
+            description: 'Diff the adoption plan against constructs.ts.',
+            usage: 'shrk constructs adopt diff [--format text|markdown|html|json] [--record-checkpoint]',
+        },
+    ],
     description: 'Build a construct-adoption plan from inferred drafts; classify safe / manual / low-confidence / already-covered / conflict. Never modifies constructs.ts.',
     usage: 'shrk constructs adopt [--dry-run|--write-patch] [--confidence high|medium|low] [--include facets,publicApi,events,tokens] [--json]\n  shrk constructs adopt status [--json]\n  shrk constructs adopt review [--json]\n  shrk constructs adopt diff [--format text|markdown|html|json]',
     async run(args) {

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

@@ -1 +1 @@
-{"version":3,"file":"context.command.d.ts","sourceRoot":"","sources":["../../src/commands/context.command.ts"],"names":[],"mappings":"AAiBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA0ChC,eAAO,MAAM,cAAc,EAAE,eA8I5B,CAAC"}
+{"version":3,"file":"context.command.d.ts","sourceRoot":"","sources":["../../src/commands/context.command.ts"],"names":[],"mappings":"AAmBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA+ChC,eAAO,MAAM,cAAc,EAAE,eAiL5B,CAAC"}

package/dist/commands/context.command.js

@@ -3,8 +3,13 @@ import { buildContext } from '@shrkcrft/context';
 import { loadIntentBenchmark, runIntentBenchmark, STARTER_INTENT_BENCHMARK, writeBenchmarkRun, } from '@shrkcrft/context-planner';
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
-import { buildUniversalSearch, explainTaskRouting, recommendCommands, renderOverviewText, buildProjectOverview, } from '@shrkcrft/inspector';
+import { buildUniversalSearch, rankRecommendationCandidates, recommendationReportFromRanking, renderOverviewText, buildProjectOverview, } from '@shrkcrft/inspector';
 import { flagBool, flagNumber, flagString, flagList, resolveCwd, } from "../command-registry.js";
+import { PositionalMode } from "../dispatch/positional-mode.js";
+import { catalogCommandSafety } from "../surface/catalog-command-safety.js";
+import { dropNotApplicable } from "../surface/audience-applicability.js";
+import { loadSurfaceContext } from "../surface/load-surface-context.js";
+import { buildSurfaceSummary } from "../surface/surface-summary.js";
 import { asJson, header } from "../output/format-output.js";
 /**
  * Budget used for the DEFAULT full human-text orientation view when the caller
@@ -40,6 +45,22 @@ function minimalContext(task, result, commands) {
 }
 export const contextCommand = {
     name: 'context',
+    // The task is `--task "<task>"`; a bare token is no subverb and no task.
+    positionals: PositionalMode.None,
+    subverbs: [
+        { name: 'build', description: 'Build the persisted task context.', usage: 'shrk context build --task "<task>" [--json]' },
+        { name: 'refresh', description: 'Refresh the persisted task context.', usage: 'shrk context refresh [--json]' },
+        { name: 'status', description: 'The persisted task context status.', usage: 'shrk context status [--json]' },
+        {
+            name: 'benchmark',
+            description: 'Score context retrieval against sharkcraft/intent-benchmark.json (`seed` writes a starter).',
+            usage: 'shrk context benchmark [seed] [--no-persist] [--json]',
+            positionals: PositionalMode.None,
+            subverbs: [
+                { name: 'seed', description: 'Write a starter intent benchmark.', usage: 'shrk context benchmark seed [--json]' },
+            ],
+        },
+    ],
     description: 'Build relevant AI-ready context for a task (token-budgeted). Subcommands: build / refresh / status.',
     usage: 'shrk context [build|refresh|status] --task "<task>" [--max-tokens 3000] [--framework x] [--area y] [--json] [--compact] [--full]',
     async run(args) {
@@ -112,8 +133,18 @@ export const contextCommand = {
         let routingMatches = [];
         let searchReport = null;
         try {
-            commandRecommendations = await recommendCommands(inspection, task);
-            routingMatches = await explainTaskRouting(inspection, task);
+            // THE ranked list — the same one `shrk recommend` and MCP
+            // `recommend_commands` render, so a matched routing hint's commands
+            // reach "Top commands" here too, attributed.
+            const ranked = await rankRecommendationCandidates(inspection, task, {
+                safetyOf: (command) => catalogCommandSafety(command),
+            });
+            // THE audience filter `shrk recommend` applies: outside SharkCraft's own
+            // repository a tool-maintenance command (a recipe's `release readiness`)
+            // is no recommendation — it exits 78 there.
+            const { context: surfaceContext } = await loadSurfaceContext({ cwd: inspection.projectRoot, inspection });
+            commandRecommendations = dropNotApplicable(recommendationReportFromRanking(ranked), buildSurfaceSummary(surfaceContext));
+            routingMatches = ranked.routingMatches;
             searchReport = await buildUniversalSearch(inspection, task, {});
         }
         catch {
@@ -146,9 +177,13 @@ export const contextCommand = {
             process.stdout.write(`omitted (budget): ${result.omittedSections.join(', ')}\n`);
         }
         if (commandRecommendations && commandRecommendations.recommendations.length > 0) {
-            process.stdout.write('\nTop commands:\n');
+            const confident = commandRecommendations.confident;
+            process.stdout.write(confident
+                ? '\nTop commands:\n'
+                : '\nTop commands (no confident match — weak candidates, verify before acting):\n');
             for (const r of commandRecommendations.recommendations.slice(0, 4)) {
-                process.stdout.write(`  $ ${r.command}\n`);
+                const mark = !confident || r.weak === true ? '?' : '$';
+                process.stdout.write(`  ${mark} ${r.command}${r.attribution ? `  — ${r.attribution}` : ''}\n`);
             }
         }
         if (routingMatches.length > 0) {

package/dist/commands/contract-templates.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract-templates.command.d.ts","sourceRoot":"","sources":["../../src/commands/contract-templates.command.ts"],"names":[],"mappings":"AASA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC,eAAO,MAAM,2BAA2B,EAAE,eAiBzC,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,eAgCxC,CAAC;AAEF,eAAO,MAAM,6BAA6B,EAAE,eAuC3C,CAAC;AAEF,eAAO,MAAM,gCAAgC,EAAE,eA0B9C,CAAC;AAEF,2EAA2E;AAC3E,eAAO,MAAM,uBAAuB,EAAE,eAkBrC,CAAC"}
+{"version":3,"file":"contract-templates.command.d.ts","sourceRoot":"","sources":["../../src/commands/contract-templates.command.ts"],"names":[],"mappings":"AAWA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAIhC,eAAO,MAAM,2BAA2B,EAAE,eAwBzC,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,eAgCxC,CAAC;AAEF,eAAO,MAAM,6BAA6B,EAAE,eAuC3C,CAAC;AAEF,eAAO,MAAM,gCAAgC,EAAE,eA0B9C,CAAC;AAEF,2EAA2E;AAC3E,eAAO,MAAM,uBAAuB,EAAE,eAkBrC,CAAC"}

package/dist/commands/contract-templates.command.js

@@ -1,16 +1,23 @@
 import { mkdirSync, writeFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
-import { getContractTemplate, listContractTemplates, recommendContractTemplate, renderContractTemplateMarkdown, renderContractTemplateText, } from '@shrkcrft/inspector';
+import { ContributionKind, getContractTemplate, inspectSharkcraft, listContractTemplates, recommendContractTemplate, renderContractTemplateMarkdown, renderContractTemplateText, } from '@shrkcrft/inspector';
 import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
 import { asJson } from "../output/format-output.js";
+import { writeRejectedEntriesNote } from "../output/rejected-entries-note.js";
 export const contractTemplateListCommand = {
     name: 'list',
     description: 'List built-in contract templates. Read-only.',
     usage: 'shrk contract template list [--json]',
     async run(args) {
         const list = listContractTemplates();
+        // A contributed contract template its loader refused is named (round 12,
+        // 12.1) — it used to read `Invalid contract template at <file>; skipped.`
+        // on no surface at all.
+        const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
+        const note = { next: 'shrk packs contributions' };
         if (flagBool(args, 'json')) {
             process.stdout.write(asJson(list) + '\n');
+            await writeRejectedEntriesNote(inspection, [ContributionKind.ContractTemplate], { ...note, json: true });
             return 0;
         }
         for (const t of list) {
@@ -18,6 +25,7 @@ export const contractTemplateListCommand = {
             process.stdout.write(`  role: ${t.role} / mode: ${t.mode}\n`);
             process.stdout.write(`  ${t.description}\n\n`);
         }
+        await writeRejectedEntriesNote(inspection, [ContributionKind.ContractTemplate], note);
         return 0;
     },
 };

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

@@ -1 +1 @@
-{"version":3,"file":"contract.command.d.ts","sourceRoot":"","sources":["../../src/commands/contract.command.ts"],"names":[],"mappings":"AASA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA4BhC,eAAO,MAAM,eAAe,EAAE,eAqF7B,CAAC"}
+{"version":3,"file":"contract.command.d.ts","sourceRoot":"","sources":["../../src/commands/contract.command.ts"],"names":[],"mappings":"AASA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA6BhC,eAAO,MAAM,eAAe,EAAE,eAuH7B,CAAC"}