@shrkcrft/cli 0.1.0-alpha.2 → 0.1.0-alpha.21

package/dist/commands/profiles.command.js

@@ -1,6 +1,6 @@
 /**
  * `shrk profiles ...` — unified read-only surface for all pack-/local-
- * contributed profiles (plugin lifecycle, migration, and future kinds).
+ * contributed profiles (migration, and future kinds).
  */
 import { findProfile, inspectSharkcraft, listProfileIssues, listProfiles, ProfileKind, } from '@shrkcrft/inspector';
 import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
@@ -15,7 +15,7 @@ function parseKind(value) {
 }
 export const profilesListCommand = {
     name: 'list',
-    description: 'List all registered profiles (plugin-lifecycle, migration, ...).',
+    description: 'List all registered profiles (migration, ...).',
     usage: 'shrk profiles list [--kind <kind>] [--json]',
     async run(args) {
         const cwd = resolveCwd(args);
@@ -28,7 +28,7 @@ export const profilesListCommand = {
         }
         process.stdout.write(header(`Profiles (${entries.length}${kind ? `, kind=${kind}` : ''})`));
         if (entries.length === 0) {
-            process.stdout.write('  (none — contribute via packs: pluginLifecycleProfileFiles, migrationProfileFiles, etc.)\n');
+            process.stdout.write('  (none — contribute via packs: migrationProfileFiles, etc.)\n');
             return 0;
         }
         for (const e of entries) {
@@ -132,7 +132,7 @@ export const profilesSearchCommand = {
 };
 export const profilesCommand = {
     name: 'profiles',
-    description: 'List / inspect pack-contributed profiles (plugin-lifecycle, migration, conventions, …).',
+    description: 'List / inspect pack-contributed profiles (migration, conventions, …).',
     usage: 'shrk profiles list|get|doctor|search ...',
     async run(args) {
         const sub = args.positional[0];

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

@@ -1,4 +1,10 @@
 import { type ICommandHandler } from '../command-registry.js';
 export declare const recommendCommand: ICommandHandler;
+/**
+ * Does the query look like create/build work (a routing hint's `shrk gen`
+ * playbook is most useful here)? Mirrors {@link looksLikePlanning}: a
+ * create/build verb leading the query or in slots 1–3.
+ */
+export declare function looksLikeCreateBuild(query: string): boolean;
 export declare function looksLikePlanning(query: string): boolean;
 //# sourceMappingURL=recommend.command.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"recommend.command.d.ts","sourceRoot":"","sources":["../../src/commands/recommend.command.ts"],"names":[],"mappings":"AASA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAShC,eAAO,MAAM,gBAAgB,EAAE,eA0K9B,CAAC;AAoGF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAcxD"}
+{"version":3,"file":"recommend.command.d.ts","sourceRoot":"","sources":["../../src/commands/recommend.command.ts"],"names":[],"mappings":"AAUA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAShC,eAAO,MAAM,gBAAgB,EAAE,eAkP9B,CAAC;AA0HF;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAY3D;AAcD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAcxD"}

package/dist/commands/recommend.command.js

@@ -1,5 +1,5 @@
 import { readFileSync } from 'node:fs';
-import { buildUniversalSearch, entrypointBanner, explainTaskRouting, inspectSharkcraft, recommendCommands, renderUncertaintyReportText, } from '@shrkcrft/inspector';
+import { buildUniversalSearch, entrypointBanner, explainTaskRouting, inspectSharkcraft, rankAll, recommendCommands, renderUncertaintyReportText, } from '@shrkcrft/inspector';
 import { flagBool, flagNumber, flagString, resolveCwd, } from "../command-registry.js";
 import { asJson } from "../output/format-output.js";
 import { loadSurfaceContext } from "../surface/load-surface-context.js";
@@ -65,6 +65,10 @@ export const recommendCommand = {
         const machineJson = flagBool(args, 'json') || flagBool(args, 'machine-json');
         let routingMatches = [];
         let searchReport = null;
+        // Reconcile with `brief`/`task`: those route through the SAME shared ranker
+        // (`rankAll`). Consult it here so `recommend` never claims a "coverage gap"
+        // for a task the rest of the engine confidently matches to a template/pipeline.
+        let ranking = null;
         if (query.length > 0) {
             try {
                 routingMatches = await explainTaskRouting(inspection, query);
@@ -78,6 +82,46 @@ export const recommendCommand = {
             catch {
                 searchReport = null;
             }
+            try {
+                ranking = rankAll(inspection, query);
+            }
+            catch {
+                ranking = null;
+            }
+        }
+        const topTemplate = ranking?.templates[0];
+        const topPipeline = ranking?.pipelines[0];
+        const engineHasMatch = (topTemplate?.score ?? 0) >= TEMPLATE_MATCH_THRESHOLD ||
+            (topPipeline?.score ?? 0) >= PIPELINE_MATCH_THRESHOLD;
+        // R1 — promote a strongly-matched task-routing hint's recommends.commands
+        // into the HEADLINE for create/build intents. Routing hints are scored by
+        // explainTaskRouting but were previously only shown under --verbose, so the
+        // headline fell back to generic review/report/impact commands even when the
+        // pack declared the right `shrk gen <template>` playbook. When the top hint
+        // clears the threshold AND the query looks like create/build work, its
+        // commands lead and the generic defaults slide to the tail. Deterministic.
+        const topHint = routingMatches[0];
+        const hintCommands = topHint?.hint.recommends.commands ?? [];
+        if (query.length > 0 &&
+            looksLikeCreateBuild(query) &&
+            topHint &&
+            topHint.score >= ROUTING_HINT_PROMOTE_THRESHOLD &&
+            hintCommands.length > 0) {
+            const promoted = hintCommands.map((command) => ({
+                command,
+                why: `Routing hint "${topHint.hint.id}" matched (score ${topHint.score}) — project playbook for this create/build task.`,
+                safetyLevel: promotedSafetyLevel(command),
+            }));
+            const promotedSet = new Set(promoted.map((p) => p.command));
+            const isGenericDefault = (c) => /^(bun run )?shrk (review|report|impact)\b/i.test(c);
+            const existing = report.recommendations;
+            const keptNonGeneric = existing.filter((r) => !promotedSet.has(r.command) && !isGenericDefault(r.command));
+            const keptGeneric = existing.filter((r) => !promotedSet.has(r.command) && isGenericDefault(r.command));
+            report.recommendations = [
+                ...promoted,
+                ...keptNonGeneric,
+                ...keptGeneric,
+            ];
         }
         if (machineJson) {
             process.stdout.write(asJson({
@@ -85,6 +129,12 @@ export const recommendCommand = {
                 routingMatches,
                 search: searchReport,
                 gated,
+                rankerMatch: ranking
+                    ? {
+                        topTemplate: topTemplate ? { id: topTemplate.item.id, score: topTemplate.score } : null,
+                        topPipeline: topPipeline ? { id: topPipeline.item.id, score: topPipeline.score } : null,
+                    }
+                    : null,
             }) + '\n');
             return 0;
         }
@@ -128,16 +178,29 @@ export const recommendCommand = {
                 }
             }
         }
-        // Coverage gap — explicit if recommendations look thin and no routing hint fired.
-        if (report.recommendations.length <= 1 &&
-            routingMatches.length === 0 &&
-            query.length > 0) {
+        // Coverage gap — explicit if recommendations look thin AND no routing hint
+        // fired AND the shared ranker (the engine `brief`/`task` use) also found no
+        // template/pipeline. The last clause stops `recommend` from contradicting
+        // `task`/`brief`, which would confidently route the same task.
+        const thinResult = report.recommendations.length <= 1 && routingMatches.length === 0 && query.length > 0;
+        if (thinResult && !engineHasMatch) {
             process.stdout.write(`\n⚠ Coverage gap — no recipe, no routing hint, and no helper/template matched "${query}".\n` +
                 `  Suggest:\n` +
                 `    shrk coverage scaffolds --task "${query}"\n` +
                 `    shrk feedback actions\n` +
                 `    (or contribute a pack template / helper / routing hint)\n`);
         }
+        else if (thinResult && engineHasMatch && !actionsOnly) {
+            // The recipe/routing surface was thin, but the shared ranker DID match —
+            // surface that concrete next step instead of a misleading gap.
+            process.stdout.write('\nEngine match (shared ranker — same as `shrk task` / `shrk brief`):\n');
+            if (topTemplate && topTemplate.score >= TEMPLATE_MATCH_THRESHOLD) {
+                process.stdout.write(`  $ shrk gen ${topTemplate.item.id} <name> --dry-run  [writes-source] — template "${topTemplate.item.name}" matched (score ${topTemplate.score}).\n`);
+            }
+            if (topPipeline && topPipeline.score >= PIPELINE_MATCH_THRESHOLD) {
+                process.stdout.write(`  Pipeline: ${topPipeline.item.id} — run \`shrk task "${query}"\` for the full packet.\n`);
+            }
+        }
         if (gated.length > 0 && !actionsOnly) {
             process.stdout.write(`\nGated (experimental, not enabled in this repo):\n`);
             for (const g of gated.slice(0, 3)) {
@@ -250,6 +313,57 @@ const PLANNING_VERBS = new Set([
     'evaluate',
     'assess',
 ]);
+/**
+ * Minimum routing-hint score (from `explainTaskRouting`: +2 per keyword, +3 per
+ * phrase, +2 per regex, + confidenceBoost) required to promote a hint's
+ * commands into the recommend headline. 3 ⇒ at least one phrase match or two
+ * keyword/regex hits — a real match, not a single weak keyword.
+ */
+const ROUTING_HINT_PROMOTE_THRESHOLD = 3;
+/**
+ * Minimum `rankAll` score for a template / pipeline to count as a real engine
+ * match — used only to suppress a false "coverage gap" verdict (and surface the
+ * match) when the recipe/routing surface is thin but the shared ranker, which
+ * `brief`/`task` also use, found project coverage. Conservative: a single weak
+ * token hit scores below this.
+ */
+const TEMPLATE_MATCH_THRESHOLD = 3;
+const PIPELINE_MATCH_THRESHOLD = 3;
+const CREATE_BUILD_VERBS = new Set([
+    'create', 'build', 'add', 'generate', 'scaffold', 'implement', 'make', 'new', 'introduce', 'write',
+]);
+/**
+ * Does the query look like create/build work (a routing hint's `shrk gen`
+ * playbook is most useful here)? Mirrors {@link looksLikePlanning}: a
+ * create/build verb leading the query or in slots 1–3.
+ */
+export function looksLikeCreateBuild(query) {
+    const tokens = query
+        .toLowerCase()
+        .replace(/[^a-z0-9\s]/g, ' ')
+        .split(/\s+/)
+        .filter((t) => t.length > 0);
+    if (tokens.length === 0)
+        return false;
+    if (CREATE_BUILD_VERBS.has(tokens[0]))
+        return true;
+    for (let i = 1; i < Math.min(4, tokens.length); i++) {
+        if (CREATE_BUILD_VERBS.has(tokens[i]))
+            return true;
+    }
+    return false;
+}
+/** Conservative safety classification for a promoted routing-hint command. */
+function promotedSafetyLevel(command) {
+    if (/^(bun run )?shrk (gen|init|apply|import)\b/i.test(command))
+        return 'writes-source';
+    if (/^(bun run )?shrk (brief|dev|onboard|simulate|orchestrate|spec)\b/i.test(command)) {
+        return 'writes-drafts';
+    }
+    if (/^(bun|bunx|npm|pnpm|node|git|nx) /i.test(command))
+        return 'runs-shell';
+    return 'read-only';
+}
 export function looksLikePlanning(query) {
     const tokens = query
         .toLowerCase()

package/dist/commands/release.command.js

@@ -204,8 +204,8 @@ function resolveSmokeFlags(args) {
     const noAssertions = flagBool(args, 'no-assertions');
     return { assertionsEnabled: !noAssertions };
 }
-// Generic adopter target replaces the previous hardcoded project target.
-const BUILTIN_TARGET_IDS = ['sharkcraft', 'dogfood', 'synthetic', 'adopter'];
+// Generic consumer target replaces the previous hardcoded project target.
+const BUILTIN_TARGET_IDS = ['sharkcraft', 'dogfood', 'synthetic', 'consumer'];
 function resolveTargets(cwd, args, requested) {
     const want = (id) => requested.length === 0 || requested.includes(id);
     const out = [];
@@ -224,19 +224,19 @@ function resolveTargets(cwd, args, requested) {
         writeFileSync(nodePath.join(root, 'package.json'), JSON.stringify({ name: 'sharkcraft-synth', version: '0.0.0', type: 'module' }, null, 2), 'utf8');
         out.push({ id: 'synthetic', cwd: root, label: 'synthetic-fixture' });
     }
-    if (want('adopter')) {
-        const adopterRoot = flagString(args, 'adopter-root') ??
-            process.env['SHARKCRAFT_ADOPTER_ROOT'] ??
+    if (want('consumer')) {
+        const consumerRoot = flagString(args, 'consumer-root') ??
+            process.env['SHARKCRAFT_CONSUMER_ROOT'] ??
             '';
-        if (adopterRoot && existsSync(adopterRoot)) {
-            out.push({ id: 'adopter', cwd: adopterRoot, label: `adopter:${adopterRoot}` });
+        if (consumerRoot && existsSync(consumerRoot)) {
+            out.push({ id: 'consumer', cwd: consumerRoot, label: `consumer:${consumerRoot}` });
         }
         else {
             out.push({
-                id: 'adopter',
-                cwd: adopterRoot || '(unset)',
-                label: 'adopter target',
-                warning: 'Adopter root not set (pass --adopter-root or set SHARKCRAFT_ADOPTER_ROOT) — skipped.',
+                id: 'consumer',
+                cwd: consumerRoot || '(unset)',
+                label: 'consumer target',
+                warning: 'Consumer root not set (pass --consumer-root or set SHARKCRAFT_CONSUMER_ROOT) — skipped.',
             });
         }
     }
@@ -292,7 +292,7 @@ async function runReleaseSmoke(args) {
  *    examples/dogfood-target as the fixture.
  *  - `synthetic` runs the scenarios that don't depend on a prepared source
  *    (unconfigured-repo + pack-authoring).
- *  - `adopter` runs the read-only scenarios that don't write outside the
+ *  - `consumer` runs the read-only scenarios that don't write outside the
  *    fixture (e.g. an external project that consumes a SharkCraft pack).
  */
 function isScenarioApplicableTo(scenario, target) {
@@ -304,7 +304,7 @@ function isScenarioApplicableTo(scenario, target) {
     if (target.id === 'dogfood') {
         return scenario === 'dev-workflow' || scenario === 'pr-review' || scenario === 'governance';
     }
-    if (target.id === 'adopter') {
+    if (target.id === 'consumer') {
         return scenario === 'unconfigured-repo' || scenario === 'pack-authoring' || scenario === 'governance';
     }
     return true;

package/dist/commands/rule-graph-subverbs.d.ts

@@ -0,0 +1,3 @@
+import { type ICommandHandler } from '../command-registry.js';
+export declare const ruleGraphCommand: ICommandHandler;
+//# sourceMappingURL=rule-graph-subverbs.d.ts.map

package/dist/commands/rule-graph-subverbs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-graph-subverbs.d.ts","sourceRoot":"","sources":["../../src/commands/rule-graph-subverbs.ts"],"names":[],"mappings":"AAQA,OAAO,EAAwB,KAAK,eAAe,EAAmB,MAAM,wBAAwB,CAAC;AAGrG,eAAO,MAAM,gBAAgB,EAAE,eAc9B,CAAC"}

package/dist/commands/rule-graph-subverbs.js

@@ -0,0 +1,132 @@
+/**
+ * CLI subverbs for `@shrkcrft/rule-graph`.
+ *
+ * Sub-namespace: `shrk rule-graph <verb>`. Lives in its own command
+ * because the verbs operate on a separate `.sharkcraft/bridge/` store
+ * and don't conceptually belong under `shrk graph`.
+ */
+import { buildBridge, RuleGraphQueryApi } from '@shrkcrft/rule-graph';
+import { flagBool, resolveCwd } from "../command-registry.js";
+import { asJson, header, kv } from "../output/format-output.js";
+export const ruleGraphCommand = {
+    name: 'rule-graph',
+    description: 'Bridge the SharkCraft code graph to asset registries (boundary rules, path conventions, templates). Sub-verbs: index, status, for <file>.',
+    usage: 'shrk rule-graph index [--json] | shrk rule-graph status [--json] | shrk rule-graph for <file> [--json]',
+    async run(args) {
+        const sub = args.positional[0];
+        if (sub === 'index')
+            return runIndex(args);
+        if (sub === 'status')
+            return runStatus(args);
+        if (sub === 'for')
+            return runFor(args);
+        process.stderr.write(this.usage + '\n');
+        return 2;
+    },
+};
+async function runIndex(args) {
+    const cwd = resolveCwd(args);
+    const wantJson = flagBool(args, 'json');
+    const r = await buildBridge({ projectRoot: cwd });
+    if (wantJson) {
+        process.stdout.write(asJson({ ok: true, manifest: r.manifest, durationMs: r.durationMs }) + '\n');
+        return 0;
+    }
+    process.stdout.write(header('Rule-graph bridge'));
+    process.stdout.write(kv('schema', r.manifest.schema) + '\n');
+    process.stdout.write(kv('bridge edges', String(sumValues(r.manifest.edgesByKind))) + '\n');
+    process.stdout.write(kv('rules → files', String(r.manifest.sourceCounts['rule'] ?? 0)) + '\n');
+    process.stdout.write(kv('paths → files', String(r.manifest.sourceCounts['path'] ?? 0)) + '\n');
+    process.stdout.write(kv('templates → files', String(r.manifest.sourceCounts['template'] ?? 0)) + '\n');
+    process.stdout.write(kv('duration', `${r.durationMs}ms`) + '\n');
+    return 0;
+}
+async function runStatus(args) {
+    const cwd = resolveCwd(args);
+    const wantJson = flagBool(args, 'json');
+    const missing = RuleGraphQueryApi.missingDescription(cwd);
+    if (missing) {
+        if (wantJson) {
+            process.stdout.write(asJson({ ok: false, state: 'missing', message: missing, nextCommand: 'shrk rule-graph index' }) + '\n');
+            return 1;
+        }
+        process.stderr.write(missing + '\n');
+        return 1;
+    }
+    const api = RuleGraphQueryApi.fromStores(cwd);
+    // No public counters from the API itself — just confirm it loads.
+    if (wantJson) {
+        process.stdout.write(asJson({ ok: true, state: 'fresh' }) + '\n');
+        return 0;
+    }
+    process.stdout.write(header('Rule-graph status'));
+    process.stdout.write(kv('state', 'fresh') + '\n');
+    void api;
+    return 0;
+}
+async function runFor(args) {
+    const cwd = resolveCwd(args);
+    const wantJson = flagBool(args, 'json');
+    const file = args.positional[1];
+    if (!file) {
+        process.stderr.write('Usage: shrk rule-graph for <file>\n');
+        return 2;
+    }
+    const missing = RuleGraphQueryApi.missingDescription(cwd);
+    if (missing) {
+        if (wantJson) {
+            process.stdout.write(asJson({ ok: false, message: missing, nextCommand: 'shrk rule-graph index' }) + '\n');
+            return 1;
+        }
+        process.stderr.write(missing + '\n');
+        return 1;
+    }
+    const api = RuleGraphQueryApi.fromStores(cwd);
+    const r = api.forFile(file);
+    if (!r) {
+        const payload = { ok: false, error: 'not-found', file };
+        if (wantJson) {
+            process.stdout.write(asJson(payload) + '\n');
+            return 1;
+        }
+        process.stderr.write(`No file node for "${file}".\n`);
+        return 1;
+    }
+    const payload = {
+        schema: 'sharkcraft.rule-graph-for-file/v1',
+        file: r.path,
+        rules: r.rules.map((h) => ({ id: h.target.id, label: h.target.label, severity: h.edge.data?.['severity'] ?? undefined })),
+        paths: r.paths.map((h) => ({ id: h.target.id, label: h.target.label })),
+        templates: r.templates.map((h) => ({ id: h.target.id, label: h.target.label })),
+    };
+    if (wantJson) {
+        process.stdout.write(asJson(payload) + '\n');
+        return 0;
+    }
+    process.stdout.write(header(`Rule-graph for: ${r.path}`));
+    if (payload.rules.length > 0) {
+        process.stdout.write('\nRules (boundary):\n');
+        for (const h of payload.rules)
+            process.stdout.write(`  ${h.id} — ${h.label}${h.severity ? ' [' + h.severity + ']' : ''}\n`);
+    }
+    if (payload.paths.length > 0) {
+        process.stdout.write('\nPath conventions:\n');
+        for (const h of payload.paths)
+            process.stdout.write(`  ${h.id} — ${h.label}\n`);
+    }
+    if (payload.templates.length > 0) {
+        process.stdout.write('\nTemplates:\n');
+        for (const h of payload.templates)
+            process.stdout.write(`  ${h.id} — ${h.label}\n`);
+    }
+    if (payload.rules.length === 0 && payload.paths.length === 0 && payload.templates.length === 0) {
+        process.stdout.write('  (no bridge edges for this file)\n');
+    }
+    return 0;
+}
+function sumValues(record) {
+    let n = 0;
+    for (const v of Object.values(record))
+        n += v;
+    return n;
+}

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

@@ -1 +1 @@
-{"version":3,"file":"rules.command.d.ts","sourceRoot":"","sources":["../../src/commands/rules.command.ts"],"names":[],"mappings":"AAcA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAQhC,eAAO,MAAM,gBAAgB,EAAE,eAe9B,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,eAuB7B,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAmClC,CAAC;AAuBF,eAAO,MAAM,oBAAoB,EAAE,eAiFlC,CAAC;AAkBF;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,EAAE,eAsB7B,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,EAAE,eA6BhC,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,kBAAkB,EAAE,eA6BhC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,EAAE,eA2F9B,CAAC;AAoCF,eAAO,MAAM,kBAAkB,EAAE,eAiChC,CAAC"}
+{"version":3,"file":"rules.command.d.ts","sourceRoot":"","sources":["../../src/commands/rules.command.ts"],"names":[],"mappings":"AAcA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAQhC,eAAO,MAAM,gBAAgB,EAAE,eAgC9B,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,eAuB7B,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAmClC,CAAC;AAuBF,eAAO,MAAM,oBAAoB,EAAE,eAiFlC,CAAC;AAkBF;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,EAAE,eAsB7B,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,EAAE,eA6BhC,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,kBAAkB,EAAE,eA6BhC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,EAAE,eA2F9B,CAAC;AAoCF,eAAO,MAAM,kBAAkB,EAAE,eAiChC,CAAC"}

package/dist/commands/rules.command.js

@@ -8,12 +8,29 @@ import { knowledgeAddCommand, knowledgeRemoveCommand, knowledgeUpdateCommand, }
 export const rulesListCommand = {
     name: 'list',
     description: 'List all rules.',
-    usage: 'shrk rules list [--json]',
+    usage: 'shrk rules list [--top N] [--brief] [--json]',
     async run(args) {
         const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
-        const rules = inspection.ruleService.list();
+        let rules = inspection.ruleService.list();
+        // --top N: deterministic, token-bounded slice (id-sorted so it's stable).
+        const top = flagNumber(args, 'top');
+        if (top !== undefined && top > 0) {
+            rules = [...rules].sort((a, b) => a.id.localeCompare(b.id)).slice(0, top);
+        }
         if (flagBool(args, 'json')) {
-            process.stdout.write(asJson(rules) + '\n');
+            // --brief: project to the high-signal fields (drop content/examples).
+            const payload = flagBool(args, 'brief')
+                ? rules.map((r) => ({
+                    id: r.id,
+                    type: r.type,
+                    priority: r.priority,
+                    title: r.title,
+                    scope: r.scope,
+                    tags: r.tags,
+                    appliesWhen: r.appliesWhen,
+                }))
+                : rules;
+            process.stdout.write(asJson(payload) + '\n');
             return 0;
         }
         process.stdout.write(header(`Rules (${rules.length})`));

package/dist/commands/scaffold-validate.command.d.ts

@@ -0,0 +1,22 @@
+import { type ICommandHandler } from '../command-registry.js';
+/**
+ * `shrk scaffold-validate <plan-file>` — verify that the files
+ * recorded in a saved generation plan actually exist on disk and
+ * look like they came from the template.
+ *
+ * Read-only: never writes, never re-runs the template. Designed to
+ * run after `shrk apply` (or after a human manually copied a plan
+ * into place) to catch:
+ *   - missing files (apply was interrupted, or somebody deleted)
+ *   - shrunken files (someone replaced the body with `// TODO`)
+ *   - mismatched operation type (plan said `create`, disk shows
+ *     something else)
+ *
+ * NOT a full template-replay check — we can't know the exact
+ * expected body without re-rendering the template, which would
+ * be far more expensive and would couple this command to every
+ * template's variable resolution. Sizes + existence + type catches
+ * 95% of real-world failures.
+ */
+export declare const scaffoldValidateCommand: ICommandHandler;
+//# sourceMappingURL=scaffold-validate.command.d.ts.map

package/dist/commands/scaffold-validate.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold-validate.command.d.ts","sourceRoot":"","sources":["../../src/commands/scaffold-validate.command.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAgChC;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,uBAAuB,EAAE,eAkGrC,CAAC"}