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

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

@@ -1 +1 @@
-{"version":3,"file":"biome.command.d.ts","sourceRoot":"","sources":["../../src/commands/biome.command.ts"],"names":[],"mappings":"AAGA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAwChC,eAAO,MAAM,oBAAoB,EAAE,eAuDlC,CAAC;AA+BF,eAAO,MAAM,kBAAkB,EAAE,eAkEhC,CAAC;AAkGF,eAAO,MAAM,iBAAiB,EAAE,eA4C/B,CAAC;AAEF,eAAO,MAAM,8BAA8B,EAAE,eAwC5C,CAAC;AAEF,eAAO,MAAM,YAAY,EAAE,eAkC1B,CAAC"}
+{"version":3,"file":"biome.command.d.ts","sourceRoot":"","sources":["../../src/commands/biome.command.ts"],"names":[],"mappings":"AAGA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAyChC,eAAO,MAAM,oBAAoB,EAAE,eAuDlC,CAAC;AA+BF,eAAO,MAAM,kBAAkB,EAAE,eAkEhC,CAAC;AAkGF,eAAO,MAAM,iBAAiB,EAAE,eA4C/B,CAAC;AAEF,eAAO,MAAM,8BAA8B,EAAE,eAwC5C,CAAC;AAEF,eAAO,MAAM,YAAY,EAAE,eAqD1B,CAAC"}

package/dist/commands/biome.command.js

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
 import { inspectSharkcraft } from '@shrkcrft/inspector';
 import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { PositionalMode } from "../dispatch/positional-mode.js";
 import { asJson, header } from "../output/format-output.js";
 /**
  * Biome bridge. Biome's rule grammar is narrower than ESLint's, so this
@@ -316,6 +317,25 @@ export const biomeExplainLimitationsCommand = {
 };
 export const biomeCommand = {
     name: 'biome',
+    // positional[0] is the bridge verb — `run` refuses anything else. Each spec
+    // reuses its verb handler's usage, so the flags the verb reads (`--force`,
+    // `--output`, `--from`, …) are documented for the post-run flag detector.
+    positionals: PositionalMode.None,
+    subverbs: [
+        {
+            name: 'scaffold',
+            aliases: ['config'],
+            description: biomeScaffoldCommand.description,
+            usage: biomeScaffoldCommand.usage,
+        },
+        { name: 'report', description: biomeReportCommand.description, usage: biomeReportCommand.usage },
+        { name: 'rules', description: biomeRulesCommand.description, usage: biomeRulesCommand.usage },
+        {
+            name: 'explain-limitations',
+            description: biomeExplainLimitationsCommand.description,
+            usage: biomeExplainLimitationsCommand.usage,
+        },
+    ],
     description: 'Biome bridge. `scaffold` emits a minimal biome.json that ignores SharkCraft generated paths; `report` converts boundary JSON to a Biome-adjacent diagnostics shape; `rules` inventories what can be bridged; `explain-limitations` documents what cannot. `config` is an alias for `scaffold`.',
     usage: 'shrk biome <scaffold|config|report|rules|explain-limitations> [...flags]',
     async run(args) {

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

@@ -1,7 +1,15 @@
-import { type ICommandHandler } from '../command-registry.js';
+import { type ICommandHandler, type ParsedArgs } from '../command-registry.js';
 export declare const boundariesListCommand: ICommandHandler;
 export declare const boundariesGetCommand: ICommandHandler;
 export declare const boundariesExplainCommand: ICommandHandler;
+/**
+ * `shrk explain <ruleId>` for a BOUNDARY rule id (round 13): the unified
+ * entrypoint resolved gate-plane rule ids only, so a boundary rule fell through
+ * to the knowledge topic search ("no matching knowledge entries"). Answers with
+ * `boundaries explain` when the id names a registered boundary rule; otherwise
+ * `undefined`, and the caller keeps its topic search.
+ */
+export declare function tryExplainBoundaryRule(args: ParsedArgs, id: string): Promise<number | undefined>;
 export declare const boundariesInferCommand: ICommandHandler;
 /** Polyglot enforcement subcommand. */
 export declare const boundariesEnforceCommand: ICommandHandler;

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

@@ -1 +1 @@
-{"version":3,"file":"boundaries.command.d.ts","sourceRoot":"","sources":["../../src/commands/boundaries.command.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAwB,KAAK,eAAe,EAA+B,MAAM,wBAAwB,CAAC;AAGjH,eAAO,MAAM,qBAAqB,EAAE,eAuBnC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAqClC,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,eAmDtC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAyEpC,CAAC;AAsCF,uCAAuC;AACvC,eAAO,MAAM,wBAAwB,EAAE,eAqEtC,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,eA0CtC,CAAC"}
+{"version":3,"file":"boundaries.command.d.ts","sourceRoot":"","sources":["../../src/commands/boundaries.command.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAwB,KAAK,eAAe,EAAE,KAAK,UAAU,EAAc,MAAM,wBAAwB,CAAC;AAKjH,eAAO,MAAM,qBAAqB,EAAE,eA0BnC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAgDlC,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,eAyGtC,CAAC;AAEF;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAItG;AAED,eAAO,MAAM,sBAAsB,EAAE,eAyEpC,CAAC;AAsCF,uCAAuC;AACvC,eAAO,MAAM,wBAAwB,EAAE,eAqEtC,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,eA6CtC,CAAC"}

package/dist/commands/boundaries.command.js

@@ -1,9 +1,11 @@
 import { mkdirSync, writeFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
-import { buildOnboardingPlan, buildPolyglotBoundaryReport, inspectSharkcraft, renderPolyglotBoundaryReportMarkdown, renderPolyglotBoundaryReportText, suggestBoundaryFixes, } from '@shrkcrft/inspector';
-import { evaluateBoundaries, loadTsconfigPaths, scanImports, } from '@shrkcrft/boundaries';
+import { buildOnboardingPlan, buildPolyglotBoundaryReport, ContributionKind, describeBoundaryConfiguration, inspectSharkcraft, renderPolyglotBoundaryReportMarkdown, renderPolyglotBoundaryReportText, runBoundaryCheck, suggestBoundaryFixes, } from '@shrkcrft/inspector';
+import { boundaryForbiddenMatch, boundaryIntendedEmptyLine, boundaryPatternOverlaps, boundaryRuleFailsOnEmpty, boundaryRuleSeverity, } from '@shrkcrft/boundaries';
 import { flagBool, flagString, resolveCwd } from "../command-registry.js";
 import { asJson, header, kv } from "../output/format-output.js";
+import { writeRejectedEntriesNote } from "../output/rejected-entries-note.js";
+import { ExitCode } from "../exit-codes.js";
 export const boundariesListCommand = {
     name: 'list',
     description: 'List all registered boundary rules (local + pack-contributed).',
@@ -11,18 +13,22 @@ export const boundariesListCommand = {
     async run(args) {
         const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
         const rules = inspection.boundaryRegistry.list();
+        // A rule its loader refused is named (round 12, 12.1); `check boundaries`
+        // reports it as an ERRORED rule. The exit stays 0: a list is no verdict.
+        const note = { next: 'shrk check boundaries' };
         if (flagBool(args, 'json')) {
             process.stdout.write(asJson(rules) + '\n');
+            await writeRejectedEntriesNote(inspection, [ContributionKind.Boundary], { ...note, json: true });
             return 0;
         }
         process.stdout.write(header(`Boundary rules (${rules.length})`));
-        if (rules.length === 0) {
+        if (rules.length === 0)
             process.stdout.write('  (none registered)\n');
-            return 0;
-        }
         for (const r of rules) {
-            process.stdout.write(`  ${(r.severity ?? 'warning').toUpperCase().padEnd(8)} ${r.id.padEnd(36)} ${r.title}\n`);
+            // The ENFORCED severity (unset = error) — one authority with the evaluator.
+            process.stdout.write(`  ${boundaryRuleSeverity(r).toUpperCase().padEnd(8)} ${r.id.padEnd(36)} ${r.title}\n`);
         }
+        await writeRejectedEntriesNote(inspection, [ContributionKind.Boundary], note);
         return 0;
     },
 };
@@ -48,16 +54,28 @@ export const boundariesGetCommand = {
         }
         process.stdout.write(header(`Boundary rule: ${rule.id}`));
         process.stdout.write(kv('title', rule.title) + '\n');
-        process.stdout.write(kv('severity', rule.severity ?? 'warning') + '\n');
+        process.stdout.write(kv('severity', boundaryRuleSeverity(rule)) + '\n');
         if (rule.from && rule.from.length > 0) {
             process.stdout.write(kv('from', rule.from.join(', ')) + '\n');
         }
         if (rule.forbiddenImports && rule.forbiddenImports.length > 0) {
             process.stdout.write(kv('forbidden', rule.forbiddenImports.join(', ')) + '\n');
+            process.stdout.write(kv('forbiddenMatch', boundaryForbiddenMatch(rule)) + '\n');
         }
         if (rule.allowedImports && rule.allowedImports.length > 0) {
             process.stdout.write(kv('allowed', rule.allowedImports.join(', ')) + '\n');
         }
+        if (rule.exemptFiles && rule.exemptFiles.length > 0) {
+            process.stdout.write(kv('exemptFiles', rule.exemptFiles.join(', ')) + '\n');
+        }
+        if (rule.excludeTests)
+            process.stdout.write(kv('excludeTests', 'true') + '\n');
+        for (const m of rule.expectEmptyUnits ?? []) {
+            process.stdout.write(kv('expectEmpty marker', `${boundaryIntendedEmptyLine(m)} (state: see \`shrk check boundaries\`)`) + '\n');
+        }
+        if (rule.exceptions && rule.exceptions.length > 0) {
+            process.stdout.write(kv('exceptions', String(rule.exceptions.length)) + '\n');
+        }
         if (rule.suggestedFix) {
             process.stdout.write(kv('suggestedFix', rule.suggestedFix) + '\n');
         }
@@ -66,7 +84,7 @@ export const boundariesGetCommand = {
 };
 export const boundariesExplainCommand = {
     name: 'explain',
-    description: 'Explain a boundary rule: where it came from (local vs pack), what it forbids, what to do about violations.',
+    description: 'Explain a boundary rule: where it came from (local vs pack), what it forbids, what it exempts, what to do about violations.',
     usage: 'shrk [--cwd <dir>] boundaries explain <ruleId> [--json]',
     async run(args) {
         const id = args.positional[0];
@@ -81,14 +99,29 @@ export const boundariesExplainCommand = {
             return 1;
         }
         const source = inspection.boundarySources.get(id);
+        // The one static answer the evaluator's coverage (`subsumedBy` /
+        // `shadowedBy`) and MCP `get_boundary_rule` read (round 12, R12-5.3/5.6).
+        const overlaps = boundaryPatternOverlaps(rule);
         const explanation = {
             id: rule.id,
             title: rule.title,
-            severity: rule.severity ?? 'warning',
+            // The severity the evaluator ENFORCES (an unset one is `error`) — this
+            // used to print `warning` for a rule that blocks CI.
+            severity: boundaryRuleSeverity(rule),
             origin: source ? (source.type === 'pack' ? `pack: ${source.packageName}` : 'local') : 'unknown',
             from: rule.from ?? [],
             forbiddenImports: rule.forbiddenImports ?? [],
+            forbiddenMatch: boundaryForbiddenMatch(rule),
             allowedImports: rule.allowedImports ?? [],
+            exemptFiles: rule.exemptFiles ?? [],
+            excludeTests: rule.excludeTests === true,
+            exceptions: rule.exceptions ?? [],
+            failOnEmpty: boundaryRuleFailsOnEmpty(rule),
+            redundantForbidden: overlaps.redundantForbidden.map((o) => ({ pattern: o.pattern, coveredBy: o.by })),
+            shadowedAllowed: overlaps.shadowedAllowed.map((o) => ({ pattern: o.pattern, shadowedBy: o.by })),
+            // Round 13: the rule's expectEmpty markers — each an 'intended empty'
+            // line below, next to redundant and shadowed.
+            expectEmptyUnits: rule.expectEmptyUnits ?? [],
             suggestedFix: rule.suggestedFix,
             howToFix: 'Adjust the offending import to either (a) drop the disallowed dependency, (b) use a public interface from the allowed list, or (c) move the importer into a layer where this dependency is permitted.',
         };
@@ -98,23 +131,56 @@ export const boundariesExplainCommand = {
         }
         process.stdout.write(header(`Boundary explain: ${rule.id}`));
         process.stdout.write(kv('title', rule.title) + '\n');
-        process.stdout.write(kv('severity', rule.severity ?? 'warning') + '\n');
+        process.stdout.write(kv('severity', explanation.severity) + '\n');
         process.stdout.write(kv('origin', explanation.origin) + '\n');
         if (explanation.from.length > 0) {
             process.stdout.write(kv('applies to', explanation.from.join(', ')) + '\n');
         }
         if (explanation.forbiddenImports.length > 0) {
-            process.stdout.write(kv('forbidden', explanation.forbiddenImports.join(', ')) + '\n');
+            process.stdout.write(kv('forbidden', `${explanation.forbiddenImports.join(', ')} (${explanation.forbiddenMatch === 'package' ? 'package semantics: each bare pattern covers its subpaths' : 'exact: entrypoint only'})`) + '\n');
         }
         if (explanation.allowedImports.length > 0) {
             process.stdout.write(kv('allowed', explanation.allowedImports.join(', ')) + '\n');
         }
+        const pkgNote = explanation.forbiddenMatch === 'package';
+        for (const o of explanation.redundantForbidden) {
+            process.stdout.write(kv('redundant', `'${o.pattern}' is covered by '${o.coveredBy}'${pkgNote ? ' (package semantics)' : ''} — redundant; safe to delete`) + '\n');
+        }
+        for (const o of explanation.shadowedAllowed) {
+            process.stdout.write(kv('shadowed', `allowed '${o.pattern}' can never admit an import — forbidden '${o.shadowedBy}' is checked first and covers it; carve the subpath out with exceptions[{ path, target, reason }]${pkgNote ? " or set forbiddenMatch: 'exact'" : ''}`) + '\n');
+        }
+        // Round 13: each expectEmpty marker, beside redundant and shadowed. The
+        // assertion only — whether its target has appeared since (went live) is a
+        // run-time fact `shrk check boundaries` reports.
+        for (const m of explanation.expectEmptyUnits) {
+            process.stdout.write(kv('expectEmpty marker', `${boundaryIntendedEmptyLine(m)} (state: see \`shrk check boundaries\`)`) + '\n');
+        }
+        if (explanation.exemptFiles.length > 0 || explanation.excludeTests) {
+            process.stdout.write(kv('exempt', [...explanation.exemptFiles, ...(explanation.excludeTests ? ['(test files)'] : [])].join(', ')) + '\n');
+        }
+        for (const ex of explanation.exceptions) {
+            process.stdout.write(kv('exception', `${ex.path} → ${ex.target} — ${ex.reason}`) + '\n');
+        }
+        process.stdout.write(kv('failOnEmpty', explanation.failOnEmpty ? 'yes — matching no file fails the run' : 'no — matching no file is reported skipped') + '\n');
         if (rule.suggestedFix)
             process.stdout.write(`\nSuggested fix: ${rule.suggestedFix}\n`);
         process.stdout.write(`\nHow to fix: ${explanation.howToFix}\n`);
         return 0;
     },
 };
+/**
+ * `shrk explain <ruleId>` for a BOUNDARY rule id (round 13): the unified
+ * entrypoint resolved gate-plane rule ids only, so a boundary rule fell through
+ * to the knowledge topic search ("no matching knowledge entries"). Answers with
+ * `boundaries explain` when the id names a registered boundary rule; otherwise
+ * `undefined`, and the caller keeps its topic search.
+ */
+export async function tryExplainBoundaryRule(args, id) {
+    const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
+    if (!inspection.boundaryRegistry.has(id))
+        return undefined;
+    return boundariesExplainCommand.run({ ...args, positional: [id] });
+}
 export const boundariesInferCommand = {
     name: 'infer',
     description: 'Infer candidate boundary rules from the current repo (monorepo structure, package boundaries, naming heuristics). Dry-run by default; --write-drafts writes to sharkcraft/boundary-drafts/boundaries.draft.ts. --language all|java|csharp|python|go|rust adds polyglot suggestions.',
@@ -280,18 +346,20 @@ export const boundariesSuggestCommand = {
         const inspection = await inspectSharkcraft({ cwd });
         const rules = inspection.boundaryRegistry.list();
         if (rules.length === 0) {
-            process.stderr.write('No boundary rules configured.\n');
-            return 0;
+            // Zero rules is not "nothing to suggest" — nothing was checked (round 11,
+            // L-1). Say where discovery looked and why nothing loaded.
+            const status = describeBoundaryConfiguration(inspection);
+            process.stderr.write(`No boundary rules loaded — nothing was checked (sharkcraft dir: ${status.sharkcraftDir ?? '(none found)'}).\n`);
+            for (const d of status.diagnostics)
+                process.stderr.write(`  ! ${d}\n`);
+            return ExitCode.NotVerified;
         }
-        const scan = scanImports({ projectRoot: cwd });
-        const tsconfigPaths = loadTsconfigPaths(cwd);
-        const evalResult = evaluateBoundaries(scan, rules, {
-            ...(tsconfigPaths.aliases.size > 0 ? { tsconfigPaths } : {}),
-        });
+        // THE boundary orchestrator — the same violations `check boundaries` reports.
+        const result = runBoundaryCheck(inspection);
         const filter = args.positional[0];
         const filtered = filter
-            ? evalResult.violations.filter((v) => v.ruleId === filter || v.file.includes(filter))
-            : evalResult.violations;
+            ? result.violations.filter((v) => v.ruleId === filter || v.file.includes(filter))
+            : result.violations;
         const suggestions = suggestBoundaryFixes(inspection, filtered.map((v) => ({
             ruleId: v.ruleId,
             file: v.file,

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

@@ -1 +1 @@
-{"version":3,"file":"bundle.command.d.ts","sourceRoot":"","sources":["../../src/commands/bundle.command.ts"],"names":[],"mappings":"AA0CA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA+4BhC,eAAO,MAAM,aAAa,EAAE,eAkC3B,CAAC"}
+{"version":3,"file":"bundle.command.d.ts","sourceRoot":"","sources":["../../src/commands/bundle.command.ts"],"names":[],"mappings":"AA0CA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAu5BhC,eAAO,MAAM,aAAa,EAAE,eA2E3B,CAAC"}

package/dist/commands/bundle.command.js

@@ -3,6 +3,7 @@ import * as nodePath from 'node:path';
 import { buildBundleDiffFromIds, buildPlanDependencyGraph, buildTaskPacket, createFeatureBundleState, decomposeTask, inspectSharkcraft, listFeatureBundles, markBundlePlanApplied, readFeatureBundle, recomputeBundleStatus, recordBundleReport, recordBundleValidation, renderBundleDiff, renderBundleValidationHtml, renderGraphDot, renderGraphMermaid, renderGraphText, renderBundleReplayWorkflow, replayAllBundles, replayBundle, renderBundleReplayBatchHtml, setBundleDependencies, setBundleNextAction, upsertBundlePlan, writeFeatureBundle, getBundleDir, BundleReplayStatus, } from '@shrkcrft/inspector';
 import { buildSavedPlan, generate, OverwriteStrategy, savePlanToFile, } from '@shrkcrft/generator';
 import { flagBool, flagString, flagVars, resolveCwd, } from "../command-registry.js";
+import { PositionalMode } from "../dispatch/positional-mode.js";
 import { asJson, header, kv } from "../output/format-output.js";
 const SUBCOMMANDS = new Set([
     'create',
@@ -638,18 +639,17 @@ async function bundleValidate(args) {
     let warnings = 0;
     if (runBoundaries) {
         try {
-            const { evaluateBoundaries, loadTsconfigPaths, scanImports } = await import('@shrkcrft/boundaries');
-            const scan = scanImports({ projectRoot: cwd });
-            const tsconfigPaths = loadTsconfigPaths(cwd);
-            const evalResult = evaluateBoundaries(scan, inspection.boundaryRegistry.list(), {
-                ...(tsconfigPaths.aliases.size > 0 ? { tsconfigPaths } : {}),
-            });
+            // THE boundary orchestrator — the verdict `check boundaries` settles
+            // (round 11 review R11-GAP-3): zero rules, an errored rule or a scope it
+            // could not fully examine is never a passed boundaries step.
+            const { runBoundaryCheck } = await import('@shrkcrft/inspector');
+            const evalResult = runBoundaryCheck(inspection, { strict });
             boundaryViolations = evalResult.violations.length;
-            const fail = strict ? boundaryViolations > 0 : evalResult.counts.error > 0;
+            const notVerified = evalResult.verdict === 'not-verified' ? ` — NOT VERIFIED: ${evalResult.shortfalls.slice(0, 2).join('; ')}` : '';
             commandsRun.push({
                 command: 'boundaries',
-                passed: !fail,
-                note: `${boundaryViolations} violations (${evalResult.counts.error}err / ${evalResult.counts.warning}warn)`,
+                passed: evalResult.exitCode === 0,
+                note: `${boundaryViolations} violations (${evalResult.counts.error}err / ${evalResult.counts.warning}warn)${notVerified}`,
             });
             warnings += evalResult.counts.warning;
         }
@@ -661,11 +661,14 @@ async function bundleValidate(args) {
         try {
             const { buildDriftReport } = await import('@shrkcrft/inspector');
             const drift = buildDriftReport(inspection);
-            const fail = drift.counts.error > 0 || (strict && drift.counts.warning > 0);
+            // THE drift verdict: a boundary scope drift could not fully examine is
+            // NOT VERIFIED, never a passed step.
+            const fail = drift.exitCode !== 0 || (strict && drift.counts.warning > 0);
             commandsRun.push({
                 command: 'drift',
                 passed: !fail,
-                note: `${drift.counts.error}err / ${drift.counts.warning}warn / ${drift.counts.info}info`,
+                note: `${drift.counts.error}err / ${drift.counts.warning}warn / ${drift.counts.info}info` +
+                    (drift.verdict === 'not-verified' ? ` — NOT VERIFIED: ${drift.shortfalls.slice(0, 2).join('; ')}` : ''),
             });
             warnings += drift.counts.warning;
         }
@@ -692,6 +695,8 @@ async function bundleValidate(args) {
     if (runAgent) {
         try {
             const { loadAgentContractTests, runAgentContractTest } = await import('@shrkcrft/inspector');
+            // Same registry + command index `shrk test agent` resolves against.
+            await (await import("../surface/cli-command-resolver.js")).warmCliReferenceRegistries(inspection);
             const tests = await loadAgentContractTests(inspection);
             const results = tests.map((t) => runAgentContractTest(inspection, t));
             const failed = results.filter((r) => !r.passed).length;
@@ -708,6 +713,7 @@ async function bundleValidate(args) {
     if (runContext) {
         try {
             const { loadContextTests, runContextTest } = await import('@shrkcrft/inspector');
+            await (await import("../surface/cli-command-resolver.js")).warmCliReferenceRegistries(inspection);
             const tests = await loadContextTests(inspection);
             const results = tests.map((t) => runContextTest(inspection, t));
             const failed = results.filter((r) => !r.passed).length;
@@ -846,6 +852,46 @@ async function bundleDecompose(args) {
 }
 export const bundleCommand = {
     name: 'bundle',
+    positionals: PositionalMode.None,
+    subverbs: [
+        { name: 'create', description: 'Create a feature bundle for a task.', usage: 'shrk bundle create "<task>"', positionals: PositionalMode.Free },
+        { name: 'list', description: 'List the feature bundles.', usage: 'shrk bundle list' },
+        { name: 'show', description: 'Show one bundle.', usage: 'shrk bundle show <id>', positionals: PositionalMode.Free },
+        { name: 'status', description: 'Which of a bundle’s plans are applied / validated.', usage: 'shrk bundle status <id>', positionals: PositionalMode.Free },
+        { name: 'next', description: 'The next plan to work on in a bundle.', usage: 'shrk bundle next <id>', positionals: PositionalMode.Free },
+        { name: 'report', description: 'A bundle report.', usage: 'shrk bundle report <id>', positionals: PositionalMode.Free },
+        { name: 'review', description: 'Review a bundle before applying it.', usage: 'shrk bundle review <id>', positionals: PositionalMode.Free },
+        { name: 'commands', description: 'The CLI commands a bundle needs, in order.', usage: 'shrk bundle commands <id>', positionals: PositionalMode.Free },
+        { name: 'plan', description: 'One plan of a bundle.', usage: 'shrk bundle plan <id> [<planName>]', positionals: PositionalMode.Free },
+        { name: 'graph', description: 'The bundle’s plan dependency graph.', usage: 'shrk bundle graph <id>', positionals: PositionalMode.Free },
+        {
+            name: 'apply-assist',
+            aliases: ['apply-plan'],
+            description: 'Apply assist: the next `shrk apply` step for a bundle.',
+            usage: 'shrk bundle apply-assist <id>',
+            positionals: PositionalMode.Free,
+        },
+        { name: 'validate', description: 'Validate a bundle.', usage: 'shrk bundle validate <id>', positionals: PositionalMode.Free },
+        { name: 'decompose', description: 'Decompose a task into bundle subtasks.', usage: 'shrk bundle decompose "<task>"', positionals: PositionalMode.Free },
+        {
+            name: 'record-apply',
+            description: 'Record that one bundle plan was applied.',
+            usage: 'shrk bundle record-apply <id> <planName> [--note <text>]',
+            positionals: PositionalMode.Free,
+        },
+        {
+            name: 'replay',
+            description: 'Replay a bundle (or --all) to detect drift; `replay scaffold github-actions` prints a CI job.',
+            usage: 'shrk bundle replay <id> [--strict] [--json]  |  shrk bundle replay --all  |  shrk bundle replay scaffold github-actions [--schedule weekly|daily|manual] [--with-report-site] [--output <path>] [--write] [--force]',
+            positionals: PositionalMode.Free,
+        },
+        {
+            name: 'diff',
+            description: 'Diff two bundles.',
+            usage: 'shrk bundle diff <bundleA> <bundleB> [--format text|markdown|html|json] [--output <path>]',
+            positionals: PositionalMode.Free,
+        },
+    ],
     description: 'Feature workflow bundles (multi-plan, dep graph, apply assist, validate).',
     usage: 'shrk bundle create|list|show|status|report|commands|plan|graph|apply-assist|validate|replay|decompose|record-apply|next|review [...args]',
     async run(args) {

package/dist/commands/cache-align.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache-align.command.d.ts","sourceRoot":"","sources":["../../src/commands/cache-align.command.ts"],"names":[],"mappings":"AAOA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAkBhC;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,EAAE,eA4B1B,CAAC;AAEF,gFAAgF;AAChF,eAAO,MAAM,cAAc,EAAE,eAuB5B,CAAC"}
+{"version":3,"file":"cache-align.command.d.ts","sourceRoot":"","sources":["../../src/commands/cache-align.command.ts"],"names":[],"mappings":"AAOA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAkBhC;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,EAAE,eA4B1B,CAAC;AAEF,gFAAgF;AAChF,eAAO,MAAM,cAAc,EAAE,eAyB5B,CAAC"}

package/dist/commands/cache-align.command.js

@@ -55,7 +55,9 @@ export const alignCommand = {
 export const unalignCommand = {
     name: 'unalign',
     description: 'Restore the original volatile tokens in aligned text using its `--map`.',
-    usage: 'shrk [--cwd <dir>] unalign [<file>|-] [--stdin] --map <path>',
+    // `--map` defaults to .sharkcraft/cache-align/align.json (the file `align`
+    // writes), so it is optional — the usage used to mark it required.
+    usage: 'shrk [--cwd <dir>] unalign [<file>|-] [--stdin] [--map <path>]',
     run(args) {
         const cwd = resolveCwd(args);
         const mapPath = flagString(args, 'map') ?? nodePath.join(cwd, '.sharkcraft', 'cache-align', 'align.json');

package/dist/commands/changelog-data.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"changelog-data.d.ts","sourceRoot":"","sources":["../../src/commands/changelog-data.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,2CAA2C;AAC3C,MAAM,WAAW,oBAAoB;IACnC,oDAAoD;IACpD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yCAAyC;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,wDAAwD;IACxD,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,eAAO,MAAM,sBAAsB,EAAE,SAAS,oBAAoB,EAkJjE,CAAC"}
+{"version":3,"file":"changelog-data.d.ts","sourceRoot":"","sources":["../../src/commands/changelog-data.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,2CAA2C;AAC3C,MAAM,WAAW,oBAAoB;IACnC,oDAAoD;IACpD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yCAAyC;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,wDAAwD;IACxD,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,eAAO,MAAM,sBAAsB,EAAE,SAAS,oBAAoB,EAsTjE,CAAC"}