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

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

@@ -1 +1 @@
-{"version":3,"file":"review.command.d.ts","sourceRoot":"","sources":["../../src/commands/review.command.ts"],"names":[],"mappings":"AAgBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA6GhC,eAAO,MAAM,aAAa,EAAE,eAiG3B,CAAC"}
+{"version":3,"file":"review.command.d.ts","sourceRoot":"","sources":["../../src/commands/review.command.ts"],"names":[],"mappings":"AAgBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAyHhC,eAAO,MAAM,aAAa,EAAE,eAwH3B,CAAC"}

package/dist/commands/review.command.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
 import { buildReviewPacket, buildReviewPacketV2, buildReviewPacketV3, inspectSharkcraft, renderReviewComment, renderReviewCommentV2, renderReviewCommentV3, REVIEW_PACKET_V2_SCHEMA, REVIEW_PACKET_V3_SCHEMA, } from '@shrkcrft/inspector';
 import { flagBool, flagNumber, flagString, flagList, resolveCwd, } from "../command-registry.js";
+import { PositionalMode } from "../dispatch/positional-mode.js";
 import { asJson, header, kv } from "../output/format-output.js";
 function renderGithubActionYaml(options) {
     const steps = [];
@@ -74,8 +75,39 @@ function scaffoldOptionsFromArgs(args) {
         commentPlaceholder: flagBool(args, 'comment-placeholder'),
     };
 }
+/**
+ * Every flag `render-comment` reads, in every packet mode: the v1 renderer
+ * reads the artifact flags (`--boundaries|--coverage|--drift <file>`) through
+ * `readArtifact(args, name)` — undocumented, a v3 packet (which never reads
+ * them) turned `--boundaries b.json` into an "ignored flag" exit 2.
+ */
+const RENDER_COMMENT_USAGE = 'shrk review render-comment <packet.json> [--output <file>] [--title <title>] [--format markdown|html|github|gitlab] ' +
+    '[--max-files N] [--max-items N] [--max-rules N] [--include-boundaries] [--include-coverage] [--include-drift] ' +
+    '[--collapse-long-sections] [--boundaries <file>] [--coverage <file>] [--drift <file>]';
 export const reviewCommand = {
     name: 'review',
+    // positionals are changed FILES (`review a.ts b.ts`) or a verb: a
+    // verb-shaped token that is neither is refused, not reviewed as a file.
+    positionals: PositionalMode.Path,
+    subverbs: [
+        {
+            name: 'scaffold',
+            description: 'Print a PR-review workflow template.',
+            usage: 'shrk review scaffold github-action [--with-boundaries] [--with-coverage] [--with-drift] [--artifact-only] [--comment-placeholder]',
+            positionals: PositionalMode.Free,
+        },
+        {
+            name: 'render-comment',
+            description: 'Render a Markdown PR comment from a saved packet.',
+            usage: RENDER_COMMENT_USAGE,
+            positionals: PositionalMode.Path,
+        },
+        {
+            name: 'packet',
+            description: 'Build the review packet.',
+            usage: 'shrk review packet [files... | --files a,b] [--since <ref>] [--staged] [--json]',
+        },
+    ],
     description: 'Build a PR-review packet: changed files (via git), affected path conventions, relevant rules/templates/pipelines, boundary violations on those files, missing-test heuristic, verification commands. Also: `shrk review scaffold github-action` prints a workflow template with optional `--with-boundaries / --with-coverage / --with-drift / --artifact-only / --comment-placeholder` flags. `shrk review render-comment <packet.json>` renders a Markdown PR comment from a saved packet.',
     usage: 'shrk [--cwd <dir>] review [files... | --files a,b] [--since <ref>] [--staged] [--no-untracked] [--json] | shrk review scaffold github-action [...] | shrk review render-comment <packet.json> [--output <file>]',
     booleanFlags: new Set([
@@ -172,7 +204,7 @@ export const reviewCommand = {
 async function runRenderComment(args) {
     const inputPath = args.positional[1];
     if (!inputPath) {
-        process.stderr.write('Usage: shrk review render-comment <packet.json> [--output <file>] [--title <title>]\n');
+        process.stderr.write(`Usage: ${RENDER_COMMENT_USAGE}\n`);
         return 2;
     }
     const full = nodePath.isAbsolute(inputPath)

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

@@ -1 +1 @@
-{"version":3,"file":"rounds.command.d.ts","sourceRoot":"","sources":["../../src/commands/rounds.command.ts"],"names":[],"mappings":"AAsBA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAiBhC,eAAO,MAAM,oBAAoB,EAAE,eAgClC,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,eAmB/B,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,eAiC/B,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,eAc/B,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eAajC,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,eAoC/B,CAAC"}
+{"version":3,"file":"rounds.command.d.ts","sourceRoot":"","sources":["../../src/commands/rounds.command.ts"],"names":[],"mappings":"AAsBA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAkBhC,eAAO,MAAM,oBAAoB,EAAE,eAgClC,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,eAmB/B,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,eAiC/B,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,eAgB/B,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eAejC,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,eAoC/B,CAAC"}

package/dist/commands/rounds.command.js

@@ -12,6 +12,7 @@ import { ALL_TOOLS } from '@shrkcrft/mcp-server';
 import { captureRoundSnapshot, diffRounds as diffRoundSnapshots, listRoundIds, loadRoundSnapshot, renderRoundsDiffMarkdown, writeRoundSnapshot, } from '@shrkcrft/inspector';
 import { COMMAND_CATALOG } from "./command-catalog.js";
 import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { PositionalMode } from "../dispatch/positional-mode.js";
 import { asJson, header } from "../output/format-output.js";
 function collectCommandsFromCatalog() {
     return COMMAND_CATALOG.map((e) => ({
@@ -115,6 +116,8 @@ export const roundsShowCommand = {
 };
 export const diffParentCommand = {
     name: 'diff',
+    // Mixed-mode: `rounds` is a trie child.
+    positionals: PositionalMode.None,
     description: 'Diff two artifacts. Currently supports `diff rounds` for round-to-round snapshot diffs.',
     usage: 'shrk diff rounds --from <id> --to <id> [--json]',
     async run(args) {
@@ -129,6 +132,8 @@ export const diffParentCommand = {
 };
 export const roundsParentCommand = {
     name: 'rounds',
+    // Mixed-mode: capture / list / show are trie children.
+    positionals: PositionalMode.None,
     description: 'Capture / list / show round snapshots under .sharkcraft/rounds/.',
     usage: 'shrk rounds [capture|list|show] [args]',
     async run(args) {

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

@@ -1 +1 @@
-{"version":3,"file":"safety.command.d.ts","sourceRoot":"","sources":["../../src/commands/safety.command.ts"],"names":[],"mappings":"AAMA,OAAO,EAGL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAMhC,eAAO,MAAM,aAAa,EAAE,eAmE3B,CAAC"}
+{"version":3,"file":"safety.command.d.ts","sourceRoot":"","sources":["../../src/commands/safety.command.ts"],"names":[],"mappings":"AAMA,OAAO,EAGL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAOhC,eAAO,MAAM,aAAa,EAAE,eA2E3B,CAAC"}

package/dist/commands/safety.command.js

@@ -1,10 +1,19 @@
 import { buildSafetyAudit, buildSafetyAuditDeep, inspectSharkcraft, } from '@shrkcrft/inspector';
 import { flagBool, resolveCwd, } from "../command-registry.js";
+import { PositionalMode } from "../dispatch/positional-mode.js";
 import { asJson, header, kv } from "../output/format-output.js";
 import { COMMAND_CATALOG } from "./command-catalog.js";
 const PLAN_SECRET_ENV = 'SHARKCRAFT_PLAN_SECRET';
 export const safetyCommand = {
     name: 'safety',
+    positionals: PositionalMode.None,
+    subverbs: [
+        {
+            name: 'audit',
+            description: 'Audit the safety model: writers, shell runners, the MCP read-only invariant, signatures.',
+            usage: 'shrk safety audit [--deep] [--json]',
+        },
+    ],
     description: 'Audit the SharkCraft safety model: which commands write source, which run shell, MCP read-only invariant, pack signature status, plan-signing status. Read-only.',
     usage: 'shrk safety audit [--json]',
     async run(args) {

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

@@ -1 +1 @@
-{"version":3,"file":"scaffolds.command.d.ts","sourceRoot":"","sources":["../../src/commands/scaffolds.command.ts"],"names":[],"mappings":"AAKA,OAAO,EAGL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC,eAAO,MAAM,oBAAoB,EAAE,eA0ClC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eAmCjC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAwCpC,CAAC"}
+{"version":3,"file":"scaffolds.command.d.ts","sourceRoot":"","sources":["../../src/commands/scaffolds.command.ts"],"names":[],"mappings":"AAYA,OAAO,EAGL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAShC,eAAO,MAAM,oBAAoB,EAAE,eAmDlC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eAuCjC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eA8FpC,CAAC"}

package/dist/commands/scaffolds.command.js

@@ -1,6 +1,13 @@
-import { doctorScaffoldPatterns, inspectSharkcraft, loadScaffoldPatternsFromInspection, } from '@shrkcrft/inspector';
+import { assetDoctorProposedExit, buildScaffoldPatternDoctorReport, collectKindRejections, ContributionKind, contributionFileLabel, formatEntryRejection, inspectSharkcraft, loadScaffoldPatternsFromInspection, settledUnitStates, } from '@shrkcrft/inspector';
+import { formatCoverage } from '@shrkcrft/core';
 import { flagBool, resolveCwd, } from "../command-registry.js";
 import { asJson, header, kv } from "../output/format-output.js";
+import { rejectedEntriesNote } from "../output/rejected-entries-note.js";
+import { ALLOW_EMPTY_FLAG, allowEmptyValve } from "../gates/allow-empty.js";
+import { assetDoctorFailingUnits } from "../gates/asset-doctor-failing-units.js";
+import { assetDoctorFailureLine } from "../gates/asset-doctor-failure-line.js";
+import { settleVerdict } from "../gates/settle-verdict.js";
+import { verdictLine } from "../gates/verdict-line.js";
 export const scaffoldsListCommand = {
     name: 'list',
     description: 'List every scaffold pattern contributed by an installed pack.',
@@ -9,6 +16,10 @@ export const scaffoldsListCommand = {
         const cwd = resolveCwd(args);
         const inspection = await inspectSharkcraft({ cwd });
         const result = await loadScaffoldPatternsFromInspection(inspection);
+        // THE rejection channel (round 12, 12.1): a pattern the loader refused
+        // (no templateId / matchPaths / confidence, a duplicate id) is a record
+        // with every reason — it used to be a raw `! …` warning string.
+        const rejected = await collectKindRejections(inspection, [ContributionKind.ScaffoldPattern]);
         if (flagBool(args, 'json')) {
             process.stdout.write(asJson({
                 patterns: result.patterns.map((p) => ({
@@ -17,20 +28,23 @@ export const scaffoldsListCommand = {
                     templateId: p.pattern.templateId,
                     confidence: p.pattern.confidence,
                     matchPaths: p.pattern.matchPaths,
+                    ...(p.pattern.expectEmptyUnits ? { expectEmptyUnits: p.pattern.expectEmptyUnits } : {}),
                     appliesWhen: p.pattern.appliesWhen,
                     source: p.source,
                 })),
                 warnings: result.warnings,
+                rejected: rejected.map((r) => ({ ...r, file: contributionFileLabel(inspection.projectRoot, r.file) })),
             }) + '\n');
             return 0;
         }
         process.stdout.write(header(`Scaffold patterns (${result.patterns.length})`));
         for (const p of result.patterns) {
-            process.stdout.write(`  • ${p.pattern.id.padEnd(36)} ${p.pattern.confidence.padEnd(7)} → ${p.pattern.templateId}\n`);
-            process.stdout.write(`      ${p.pattern.title}\n`);
+            process.stdout.write(`  • ${p.pattern.id.padEnd(36)} ${String(p.pattern.confidence).padEnd(7)} → ${p.pattern.templateId}\n`);
+            process.stdout.write(`      ${p.pattern.title ?? ''}\n`);
             process.stdout.write(`      source: ${p.source.packageName ?? p.source.type}\n`);
         }
         if (result.warnings.length > 0) {
+            // File-level problems (missing, not an array, failed to import).
             process.stdout.write('\nWarnings:\n');
             for (const w of result.warnings)
                 process.stdout.write(`  ! ${w}\n`);
@@ -38,6 +52,9 @@ export const scaffoldsListCommand = {
         if (result.patterns.length === 0) {
             process.stdout.write('\nNo scaffold patterns found. Packs can contribute them via `scaffoldPatternFiles`.\n');
         }
+        const note = rejectedEntriesNote(rejected, inspection.projectRoot, 'shrk scaffolds doctor');
+        if (note)
+            process.stdout.write(`\n${note}`);
         return 0;
     },
 };
@@ -69,8 +86,11 @@ export const scaffoldsGetCommand = {
         process.stdout.write(kv('confidence', match.pattern.confidence) + '\n');
         process.stdout.write(kv('source', match.source.packageName ?? match.source.type) + '\n');
         process.stdout.write(`\nMatch paths:\n`);
-        for (const m of match.pattern.matchPaths)
-            process.stdout.write(`  - ${m}\n`);
+        const marked = new Map((match.pattern.expectEmptyUnits ?? []).map((m) => [m.unit, m]));
+        for (const m of match.pattern.matchPaths) {
+            const mark = marked.get(m);
+            process.stdout.write(`  - ${m}${mark ? `  (expectEmpty${mark.reason ? `: ${mark.reason}` : ''})` : ''}\n`);
+        }
         process.stdout.write(`\nApplies when:\n`);
         for (const a of match.pattern.appliesWhen)
             process.stdout.write(`  - ${a}\n`);
@@ -82,41 +102,93 @@ export const scaffoldsGetCommand = {
 };
 export const scaffoldsDoctorCommand = {
     name: 'doctor',
-    description: 'Validate scaffold pattern definitions (templates exist, strategies recognized, …).',
-    usage: 'shrk scaffolds doctor [--json]',
+    description: 'Validate scaffold pattern definitions (templates exist, strategies recognized, …) and count the files every matchPaths glob matches — a glob or pattern matching nothing is a dead unit (exit 2), unless the glob is marked { pattern, expectEmpty: true } (accepted, printed; reported once a file matches).',
+    usage: 'shrk scaffolds doctor [--json] [--strict] [--fail-on-dead-units] [--allow-empty]',
+    booleanFlags: new Set(['json', 'strict', 'fail-on-dead-units', ALLOW_EMPTY_FLAG]),
     async run(args) {
         const cwd = resolveCwd(args);
         const inspection = await inspectSharkcraft({ cwd });
-        const result = await loadScaffoldPatternsFromInspection(inspection);
-        const issues = doctorScaffoldPatterns(result.patterns, inspection);
-        const errorCount = issues.filter((i) => i.severity === 'error').length;
-        const warningCount = issues.filter((i) => i.severity === 'warning').length;
+        // THE scaffold-pattern doctor (round 13) — MCP get_scaffold_pattern_doctor
+        // reads the same report. No pattern declared examined nothing: NOT VERIFIED
+        // (2), like every other asset doctor over an empty input, unless
+        // `--allow-empty` accepts it (printed).
+        const report = await buildScaffoldPatternDoctorReport(inspection, allowEmptyValve(args, 0));
+        const proposed = assetDoctorProposedExit({ errors: report.errors, warnings: report.warnings, units: report.measured.liveness.flatMap((s) => s.units) }, { strict: flagBool(args, 'strict'), failOnDeadUnits: flagBool(args, 'fail-on-dead-units') });
+        const settled = settleVerdict(proposed, report.coverage);
+        const deadUnits = report.measured.deadUnits;
+        // THE units that fail this run (round 13 review) — printed and in --json,
+        // so a 1 from --fail-on-dead-units is never silent about why.
+        const failing = assetDoctorFailingUnits(report.measured.liveness.flatMap((s) => s.units), {
+            failOnDeadUnits: flagBool(args, 'fail-on-dead-units'),
+            strict: flagBool(args, 'strict'),
+        });
+        const rejected = report.rejected.map((r) => ({ ...r, file: contributionFileLabel(inspection.projectRoot, r.file) }));
         if (flagBool(args, 'json')) {
             process.stdout.write(asJson({
-                patterns: result.patterns.length,
-                errors: errorCount,
-                warnings: warningCount,
-                issues,
-                loadWarnings: result.warnings,
+                patterns: report.patterns.length,
+                failingUnits: failing.map((u) => ({ list: u.list, unit: u.unit, state: u.state, message: u.message })),
+                errors: report.errors,
+                warnings: report.warnings,
+                dead: deadUnits.length,
+                issues: report.issues,
+                loadWarnings: report.loadWarnings,
+                rejected,
+                patternCoverage: report.patternCoverage,
+                coverage: report.coverage,
+                deadUnits,
+                units: settledUnitStates(report.measured.liveness),
+                exitCode: settled.exit,
+                verdict: settled.verdict,
+                shortfalls: settled.shortfalls,
+                accepted: settled.accepted,
             }) + '\n');
-            return errorCount > 0 ? 1 : 0;
+            return settled.exit;
         }
         process.stdout.write(header('Scaffold pattern doctor'));
-        process.stdout.write(kv('patterns', result.patterns.length.toString()) + '\n');
-        process.stdout.write(kv('errors', errorCount.toString()) + '\n');
-        process.stdout.write(kv('warnings', warningCount.toString()) + '\n');
-        if (issues.length > 0) {
+        process.stdout.write(kv('patterns', report.patterns.length.toString()) + '\n');
+        process.stdout.write(kv('errors', report.errors.toString()) + '\n');
+        process.stdout.write(kv('warnings', report.warnings.toString()) + '\n');
+        process.stdout.write(kv('dead', deadUnits.length.toString()) + '\n');
+        for (const c of report.coverage)
+            process.stdout.write(kv('coverage', formatCoverage(c)) + '\n');
+        if (report.issues.length > 0) {
             process.stdout.write('\nIssues:\n');
-            for (const i of issues) {
+            for (const i of report.issues) {
                 const tag = i.severity === 'error' ? 'ERR ' : i.severity === 'warning' ? 'WARN' : 'INFO';
                 process.stdout.write(`  ${tag}  ${i.patternId.padEnd(28)} ${i.field.padEnd(20)} ${i.message}\n`);
             }
         }
-        if (result.warnings.length > 0) {
+        if (report.rejected.length > 0) {
+            process.stdout.write('\nRejected entries (refused by the loader — NOT in effect):\n');
+            for (const r of report.rejected) {
+                process.stdout.write(`  ERR   ${contributionFileLabel(inspection.projectRoot, r.file)}  ${formatEntryRejection(r)}\n`);
+            }
+        }
+        if (report.loadWarnings.length > 0) {
             process.stdout.write('\nLoad warnings:\n');
-            for (const w of result.warnings)
+            for (const w of report.loadWarnings)
                 process.stdout.write(`  ! ${w}\n`);
         }
-        return errorCount > 0 ? 1 : 0;
+        // A stale LOCAL expectEmpty marker withholds the ✓ (a pack's is INFO).
+        const globs = report.measured.liveness[0];
+        const staleLocal = (globs?.wentLive ?? []).filter((u) => u.mark?.packageName === undefined).length;
+        const intendedEmpty = globs?.intendedEmpty.length ?? 0;
+        const clean = report.patterns.length === 0
+            ? 'No scaffold patterns declared — nothing to verify.'
+            : report.warnings > 0
+                ? `No blocking scaffold-pattern issues — ${report.warnings} warning(s) reported above.`
+                : staleLocal > 0
+                    ? `No blocking scaffold-pattern issues — ${staleLocal} expectEmpty marker(s) went live (listed above; remove the markers).`
+                    : `${report.patterns.length} pattern(s) valid; every matchPaths glob matches a file${intendedEmpty > 0 ? ' or is intended empty' : ''}. ✓`;
+        const line = verdictLine(settled, clean);
+        if (line)
+            process.stdout.write('\n' + line + '\n');
+        // Round 13 review: a 1 from --fail-on-dead-units names its units.
+        if (settled.exit === 1) {
+            const failure = assetDoctorFailureLine('scaffold-pattern doctor', failing);
+            if (failure)
+                process.stdout.write('\n' + failure + '\n');
+        }
+        return settled.exit;
     },
 };

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

@@ -1,12 +1,4 @@
 import { type ICommandHandler } from '../command-registry.js';
 export declare const searchCommand: ICommandHandler;
 export declare const searchTuningListCommand: ICommandHandler;
-/**
- * Top-level `shrk search-tuning <verb>` alias.
- *
- * Lets users invoke `shrk search-tuning explain "<query>"` without
- * remembering the nested `shrk search tuning explain ...` form. Routes
- * directly through the existing handler to avoid drift.
- */
-export declare const searchTuningTopLevelCommand: ICommandHandler;
 //# sourceMappingURL=search.command.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"search.command.d.ts","sourceRoot":"","sources":["../../src/commands/search.command.ts"],"names":[],"mappings":"AAiBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAkChC,eAAO,MAAM,aAAa,EAAE,eAsH3B,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eA+FrC,CAAC;AAwEF;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,EAAE,eASzC,CAAC"}
+{"version":3,"file":"search.command.d.ts","sourceRoot":"","sources":["../../src/commands/search.command.ts"],"names":[],"mappings":"AAuBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA0ChC,eAAO,MAAM,aAAa,EAAE,eAqJ3B,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eA6LrC,CAAC"}

package/dist/commands/search.command.js

@@ -1,6 +1,15 @@
-import { buildSearchIndex, entrypointBanner, explainSearchTuning, inspectSharkcraft, loadConstructs, loadPlaybooks, loadSearchTuning, renderSearchText, renderTuningExplainHtml, renderTuningExplainMarkdown, searchIndex, SearchKind, SearchResultKind, SearchSource, } from '@shrkcrft/inspector';
+import { assetDoctorProposedExit, buildSearchIndex, ContributionKind, entrypointBanner, explainSearchTuning, inspectSharkcraft, lintSearchTuning, listSearchTuningIssues, loadConstructs, loadPlaybooks, loadSearchTuning, renderSearchText, renderTuningExplainHtml, renderTuningExplainMarkdown, searchIndex, SearchKind, SearchResultKind, SearchSource, settledUnitStates, } from '@shrkcrft/inspector';
+import { usageExitFor } from "../exit-codes.js";
 import { flagBool, flagNumber, flagString, flagList, resolveCwd, } from "../command-registry.js";
+import { PositionalMode } from "../dispatch/positional-mode.js";
 import { asJson } from "../output/format-output.js";
+import { writeRejectedEntriesNote } from "../output/rejected-entries-note.js";
+import { formatCoverage } from '@shrkcrft/core';
+import { ALLOW_EMPTY_FLAG, allowEmptyValve } from "../gates/allow-empty.js";
+import { assetDoctorFailingUnits } from "../gates/asset-doctor-failing-units.js";
+import { assetDoctorFailureLine } from "../gates/asset-doctor-failure-line.js";
+import { settleVerdict } from "../gates/settle-verdict.js";
+import { verdictLine } from "../gates/verdict-line.js";
 const VALID_KINDS = new Set(Object.values(SearchKind));
 const VALID_SOURCES = new Set(Object.values(SearchSource));
 // Universal-search (v2) filter vocabularies. `--kind` is one of the
@@ -34,6 +43,36 @@ function parseSources(args) {
 }
 export const searchCommand = {
     name: 'search',
+    // The positionals are the free-form query; `tuning` is dispatched here.
+    positionals: PositionalMode.Free,
+    // The group parses every subverb's argv, so the doctor's boolean flags live
+    // here too: none may swallow a following token. `search --fail-on-dead-units
+    // tuning doctor` used to bind `tuning` as the flag's value and run a
+    // universal search for "doctor" at exit 0 (round 13).
+    booleanFlags: new Set([ALLOW_EMPTY_FLAG, 'fail-on-dead-units', 'strict', 'json']),
+    subverbs: [
+        {
+            name: 'tuning',
+            description: 'List, doctor, or explain the search-tuning entries (local + pack).',
+            usage: 'shrk search tuning list|doctor|explain <query> [--format markdown|html|json]',
+            // An unknown token used to fall through to the listing at exit 0.
+            positionals: PositionalMode.None,
+            subverbs: [
+                { name: 'list', description: 'List the search-tuning entries (the default).', usage: 'shrk search tuning list [--format text|json]' },
+                {
+                    name: 'doctor',
+                    description: 'THE search-tuning lint plus the loader issues. A boost key whose target is missing is a dead unit (exit 2) unless its value is marked { weight, expectEmpty: true } (accepted, printed; reported once the target is registered).',
+                    usage: 'shrk search tuning doctor [--strict] [--fail-on-dead-units] [--allow-empty] [--format text|json]',
+                },
+                {
+                    name: 'explain',
+                    description: 'Which tunings move the top results of a query, and by how much.',
+                    usage: 'shrk search tuning explain <query> [--kind <kind>] [--source <source>] [--limit N] [--format markdown|html|json]',
+                    positionals: PositionalMode.Free,
+                },
+            ],
+        },
+    ],
     description: 'Universal search across commands, MCP tools, knowledge, rules, paths, conventions, templates, helpers, playbooks, constructs, policies, decisions, scaffold patterns, contract templates, migration profiles, feedback rules, task routing hints, docs, recent reports. Default emits the 7-section unified output; pass --legacy for the flat output.',
     usage: 'shrk search <query> [--kind <kind>] [--source local|pack|...] [--limit N] [--explain] [--commands-only] [--actions-only] [--format text|markdown|json] [--legacy]',
     async run(args) {
@@ -200,31 +239,115 @@ export const searchTuningListCommand = {
             }
             return 0;
         }
-        const { entries, issues } = await loadSearchTuning(inspection);
         if (sub === 'doctor') {
-            if (flagBool(args, 'json')) {
-                process.stdout.write(asJson({ entries: entries.length, issues }) + '\n');
-                return issues.some((i) => i.severity === 'error') ? 1 : 0;
+            // `--format` takes what the doctor can print: text or JSON. `--format
+            // json` used to be ignored (text), and markdown / html were advertised
+            // but never rendered — a usage error now, never a silent fallback.
+            const format = flagString(args, 'format');
+            if (format !== undefined && format !== 'text' && format !== 'json') {
+                process.stderr.write(`'shrk search tuning doctor' --format takes text or json (got "${format}"). Run \`shrk help search\` for the flags it accepts.\n`);
+                return usageExitFor('search tuning doctor');
             }
-            process.stdout.write(`Tuning entries: ${entries.length}\n`);
-            if (issues.length === 0) {
-                process.stdout.write('No issues.\n');
-                return 0;
+            const wantJson = flagBool(args, 'json') || format === 'json';
+            // THE search-tuning lint (shared with the self-config doctor) plus the
+            // loader's own issues. It used to print "No issues." over a dead bare
+            // key, a misspelled prefix, a missing target, triggers no query can
+            // produce and a silent total-cap discard.
+            const lint = await lintSearchTuning(inspection);
+            const issues = [...listSearchTuningIssues(inspection), ...lint.issues];
+            const errors = issues.filter((i) => i.severity === 'error').length;
+            const warnings = issues.filter((i) => i.severity === 'warning').length;
+            // THE asset-doctor proposal (round 13): errors, warnings under --strict,
+            // and every settled unit THE --fail-on-dead-units predicate fails.
+            const proposed = assetDoctorProposedExit({ errors, warnings, units: lint.liveness.flatMap((s) => s.units) }, { strict: flagBool(args, 'strict'), failOnDeadUnits: flagBool(args, 'fail-on-dead-units') });
+            // Dead keys / triggers and unverifiable keys are coverage: never a pass.
+            // No tuning declared examined nothing: NOT VERIFIED (2), like every other
+            // asset doctor over an empty input, unless `--allow-empty` accepts it.
+            const coverage = lint.entries === 0
+                ? [
+                    ...lint.coverage,
+                    {
+                        unit: 'search-tuning entries',
+                        expected: 0,
+                        examined: 0,
+                        reason: 'no search tuning declared',
+                        ...allowEmptyValve(args, 0),
+                    },
+                ]
+                : lint.coverage;
+            const settled = settleVerdict(proposed, coverage);
+            // THE units that fail this run (round 13 review) — printed and in
+            // --json, so a 1 from --fail-on-dead-units is never silent about why.
+            const failing = assetDoctorFailingUnits(lint.liveness.flatMap((s) => s.units), {
+                failOnDeadUnits: flagBool(args, 'fail-on-dead-units'),
+                strict: flagBool(args, 'strict'),
+            });
+            if (wantJson) {
+                process.stdout.write(asJson({
+                    entries: lint.entries,
+                    failingUnits: failing.map((u) => ({ list: u.list, unit: u.unit, state: u.state, message: u.message })),
+                    issues,
+                    probes: lint.probes,
+                    coverage,
+                    deadUnits: lint.deadUnits,
+                    units: settledUnitStates(lint.liveness),
+                    exitCode: settled.exit,
+                    verdict: settled.verdict,
+                    shortfalls: settled.shortfalls,
+                    accepted: settled.accepted,
+                }) + '\n');
+                return settled.exit;
             }
+            const p = lint.probes;
+            process.stdout.write(`Tuning entries: ${lint.entries}\n`);
+            process.stdout.write(`Boost keys:     probed ${p.probed} · resolved ${p.resolved} · missing ${p.missing} · unprefixed ${p.unprefixed} · unknown-kind ${p.unknownKind} · unverified ${p.unverified}\n`);
+            for (const c of coverage)
+                process.stdout.write(`Coverage:       ${formatCoverage(c)}\n`);
             for (const i of issues) {
-                process.stdout.write(`  ${i.severity.toUpperCase().padEnd(8)} ${i.code.padEnd(20)} ${i.message}${i.tuningId ? `  (${i.tuningId})` : ''}\n`);
+                process.stdout.write(`  ${i.severity.toUpperCase().padEnd(8)} ${i.code.padEnd(22)} ${i.message}${i.tuningId ? `  (${i.tuningId})` : ''}\n`);
+            }
+            // A stale LOCAL expectEmpty marker withholds the ✓ (a pack's is INFO).
+            const keys = lint.liveness[0];
+            const staleLocal = (keys?.wentLive ?? []).filter((u) => u.mark?.packageName === undefined).length;
+            const clean = lint.entries === 0
+                ? 'No search tuning declared — nothing to verify.'
+                : warnings > 0
+                    ? `No blocking search-tuning issues — ${warnings} warning(s) reported above.`
+                    : staleLocal > 0
+                        ? `No blocking search-tuning issues — ${staleLocal} expectEmpty marker(s) went live (listed above; remove the markers).`
+                        : `Every boost key fires${(keys?.intendedEmpty.length ?? 0) > 0 ? ' or is intended empty' : ''} and every trigger is reachable. ✓`;
+            const line = verdictLine(settled, clean);
+            if (line)
+                process.stdout.write(line + '\n');
+            // Round 13 review: a 1 from --fail-on-dead-units names its units.
+            if (settled.exit === 1) {
+                const failure = assetDoctorFailureLine('search-tuning doctor', failing);
+                if (failure)
+                    process.stdout.write(failure + '\n');
             }
-            return issues.some((i) => i.severity === 'error') ? 1 : 0;
+            return settled.exit;
         }
-        // Default: list.
-        if (flagBool(args, 'json')) {
+        // Default: list. It renders text or JSON: a `--format` it cannot render is a
+        // usage error, never a silent text fallback (round 13 review — its usage
+        // advertised markdown / html, which printed the text listing at exit 0).
+        const listFormat = flagString(args, 'format');
+        if (listFormat !== undefined && listFormat !== 'text' && listFormat !== 'json') {
+            process.stderr.write(`'shrk search tuning list' --format takes text or json (got "${listFormat}"). Run \`shrk help search\` for the flags it accepts.\n`);
+            return usageExitFor('search tuning list');
+        }
+        const { entries } = await loadSearchTuning(inspection);
+        // A tuning entry its loader refused (no id) is named (round 12, 12.1).
+        const note = { next: 'shrk search tuning doctor' };
+        if (flagBool(args, 'json') || listFormat === 'json') {
             process.stdout.write(asJson(entries) + '\n');
+            await writeRejectedEntriesNote(inspection, [ContributionKind.SearchTuning], { ...note, json: true });
             return 0;
         }
         process.stdout.write(`Search tuning (${entries.length} entries)\n`);
         for (const e of entries) {
             process.stdout.write(`  ${e.id.padEnd(36)} ${e.source}${e.packageName ? ` (${e.packageName})` : ''}\n`);
         }
+        await writeRejectedEntriesNote(inspection, [ContributionKind.SearchTuning], note);
         return 0;
     },
 };
@@ -276,18 +399,3 @@ function renderUniversalSearchSummary(report, topN) {
     lines.push('(text mode is summary-only — pass --verbose / --full for the 7-section bundle, --json for machine output.)');
     return lines.join('\n') + '\n';
 }
-/**
- * Top-level `shrk search-tuning <verb>` alias.
- *
- * Lets users invoke `shrk search-tuning explain "<query>"` without
- * remembering the nested `shrk search tuning explain ...` form. Routes
- * directly through the existing handler to avoid drift.
- */
-export const searchTuningTopLevelCommand = {
-    name: 'search-tuning',
-    description: 'Alias — `shrk search-tuning <list|doctor|explain>` (delegates to `shrk search tuning ...`).',
-    usage: 'shrk search-tuning <list|doctor|explain> [<query>] [--kind <kind>] [--source <source>] [--limit N] [--format text|markdown|html|json]',
-    async run(args) {
-        return searchTuningListCommand.run(args);
-    },
-};

package/dist/commands/self-config-xrefs.command.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `shrk self-config resolve <id>` and `shrk self-config xrefs` — the lookup and
+ * listing verbs over THE declared cross-reference collector.
+ *
+ * Ids carry no namespace prefix, so "is this `related` id live, and what is
+ * it?" used to mean grepping several asset sources in turn. `resolve` answers
+ * it for one id: every registry that has it (most specific first, with the verb
+ * that shows it) and every declared field pointing at it. `xrefs` prints the
+ * extracted set — the contract `gates explain` honours for gate rules. Both are
+ * thin renderers: the answers come from `buildDeclaredXrefReport` and the
+ * reference registry, never from a walk of their own.
+ */
+import { type ReferenceKind } from '@shrkcrft/inspector';
+import { type ICommandHandler } from '../command-registry.js';
+/**
+ * The verb that shows an id of each kind. Every entry must resolve through the
+ * live command index (`r75-xrefs-cli.test.ts` locks it), so a renamed verb
+ * fails the day it is renamed instead of being printed as a dead command. A
+ * kind with no show / list verb is absent — never guessed.
+ */
+export declare const REFERENCE_KIND_VERBS: Readonly<Partial<Record<ReferenceKind, string>>>;
+export declare const selfConfigResolveCommand: ICommandHandler;
+export declare const selfConfigXrefsCommand: ICommandHandler;
+//# sourceMappingURL=self-config-xrefs.command.d.ts.map

package/dist/commands/self-config-xrefs.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-config-xrefs.command.d.ts","sourceRoot":"","sources":["../../src/commands/self-config-xrefs.command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAaL,KAAK,aAAa,EACnB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAIhC;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC,CAe/B,CAAC;AAuBpD,eAAO,MAAM,wBAAwB,EAAE,eA4DtC,CAAC;AAKF,eAAO,MAAM,sBAAsB,EAAE,eA4DpC,CAAC"}