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

package/dist/commands/policy-lint.command.js

@@ -0,0 +1,135 @@
+import * as nodePath from 'node:path';
+import { runPolicyLint } from '@shrkcrft/boundaries';
+import { resolveChangedFiles, resolveProjectConfig } from '@shrkcrft/inspector';
+import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { asJson, header, kv } from "../output/format-output.js";
+const VALID_SURFACES = new Set(['template', 'style', 'ts']);
+export const policyLintCommand = {
+    name: 'policy-lint',
+    description: 'Lint template/markup, stylesheet, and AOT-invisible TS surfaces against data-defined policyRules[] (e.g. flag raw markup when a primitive exists). Sees `.html` files AND inline `template:` strings — surfaces tsc/AOT cannot. Deterministic; no AI.',
+    usage: 'shrk [--cwd <dir>] policy-lint [--surface template|style|ts] [--changed-only] [--since <ref>] [--only <ids>] [--json]',
+    async run(args) {
+        const cwd = resolveCwd(args);
+        const wantJson = flagBool(args, 'json');
+        const changedOnly = flagBool(args, 'changed-only');
+        const since = flagString(args, 'since');
+        const only = flagString(args, 'only');
+        const surfaceRaw = flagString(args, 'surface');
+        let surfaces;
+        if (surfaceRaw) {
+            const parts = surfaceRaw.split(',').map((s) => s.trim()).filter(Boolean);
+            const bad = parts.filter((s) => !VALID_SURFACES.has(s));
+            if (bad.length > 0) {
+                process.stderr.write(`Unknown --surface "${bad.join(', ')}". Use template | style | ts.\n`);
+                return 2;
+            }
+            surfaces = parts;
+        }
+        // Distinguish invalid config from valid-with-no-rules (no silent fail-open).
+        const loaded = await resolveProjectConfig(cwd);
+        if (!loaded.ok) {
+            const msg = loaded.error.message;
+            if (wantJson) {
+                process.stdout.write(asJson({ schema: 'sharkcraft.policy-lint/v1', error: msg, rules: [], findings: [], diagnostics: [msg], evaluated: 0, verdict: 'errors' }) + '\n');
+                return 1;
+            }
+            process.stdout.write(header('Policy lint'));
+            process.stdout.write(`  ✗ Could not load config: ${msg}\n  Run \`shrk doctor\` for details.\n`);
+            return 1;
+        }
+        const rules = loaded.value.config.policyRules ?? [];
+        const planeDiagnostics = loaded.value.planeDiagnostics;
+        if (rules.length === 0) {
+            if (wantJson) {
+                process.stdout.write(asJson({ schema: 'sharkcraft.policy-lint/v1', rules: [], findings: [], diagnostics: [], evaluated: 0, verdict: 'pass' }) + '\n');
+                return 0;
+            }
+            process.stdout.write(header('Policy lint'));
+            process.stdout.write('  No policy rules configured. Declare `policyRules[]` in sharkcraft.config.ts to lint\n' +
+                '  templates / styles / AOT-invisible TS shapes (see docs/policy-lint.md).\n');
+            return 0;
+        }
+        // A typo'd --only id must not silently select nothing and report green.
+        if (only) {
+            const requested = only.split(',').map((s) => s.trim()).filter(Boolean);
+            const known = new Set(rules.map((r) => r.id));
+            const unknown = requested.filter((id) => !known.has(id));
+            if (unknown.length > 0) {
+                process.stderr.write(`Unknown --only rule id(s): ${unknown.join(', ')}. Configured: ${[...known].join(', ') || '(none)'}\n`);
+                return 2;
+            }
+        }
+        let changedFiles;
+        if (changedOnly || since) {
+            changedFiles = resolveChangedFiles({
+                projectRoot: cwd,
+                ...(since ? { since } : {}),
+                ...(changedOnly && !since ? { includeWorktree: true } : {}),
+            }).files;
+        }
+        // Don't lint SharkCraft's own asset/config dir by default (its .ts files
+        // hold the rule definitions themselves, which can self-match).
+        const sharkcraftRel = nodePath.relative(cwd, loaded.value.sharkcraftDir).split(nodePath.sep).join('/');
+        const excludeDirs = sharkcraftRel && !sharkcraftRel.startsWith('..') ? [sharkcraftRel] : [];
+        const reportRaw = runPolicyLint(cwd, rules, {
+            ...(surfaces ? { surfaces } : {}),
+            ...(changedOnly || since ? { changedOnly: true, changedFiles: changedFiles ?? [] } : {}),
+            ...(only ? { only: only.split(',').map((s) => s.trim()).filter(Boolean) } : {}),
+            ...(excludeDirs.length > 0 ? { excludeDirs } : {}),
+        });
+        // Surface pack-plane merge notes (missing/invalid pack policy files, dropped
+        // collisions) in the same diagnostics array the engine already emits.
+        const report = planeDiagnostics.length > 0
+            ? { ...reportRaw, diagnostics: [...reportRaw.diagnostics, ...planeDiagnostics] }
+            : reportRaw;
+        if (wantJson) {
+            process.stdout.write(asJson(report) + '\n');
+            return report.verdict === 'errors' ? 1 : 0;
+        }
+        process.stdout.write(header('Policy lint'));
+        // `evaluated` counts rules that actually scanned ≥1 file. When 0 rules
+        // evaluated but rules ARE configured, say so loudly — "scanned nothing" must
+        // never read as the green "no policy violations" pass.
+        if (report.evaluated === 0) {
+            process.stdout.write(`  ! Nothing evaluated — ${report.rules.length} rule(s) configured but none matched files in scope` +
+                (changedOnly || since ? ' (changed-only).\n' : '.\n'));
+            return 0;
+        }
+        process.stdout.write(kv('rules evaluated', `${report.evaluated} of ${report.rules.length}`) + '\n');
+        const errors = report.findings.filter((f) => f.severity === 'error').length;
+        const warnings = report.findings.filter((f) => f.severity === 'warning').length;
+        process.stdout.write(kv('findings', `${errors} error(s), ${warnings} warning(s)`) + '\n');
+        if (report.diagnostics.length > 0) {
+            process.stdout.write('\nMisconfigured rules:\n');
+            for (const d of report.diagnostics)
+                process.stdout.write(`  ! ${d}\n`);
+        }
+        if (report.findings.length === 0 && report.diagnostics.length === 0) {
+            process.stdout.write('\nNo policy violations on the scanned surfaces. ✓\n');
+            return 0;
+        }
+        // Group findings by rule.
+        const byRule = new Map();
+        for (const f of report.findings) {
+            const arr = byRule.get(f.ruleId) ?? [];
+            arr.push(f);
+            byRule.set(f.ruleId, arr);
+        }
+        for (const r of report.rules) {
+            const fs = byRule.get(r.ruleId);
+            if (!fs || fs.length === 0)
+                continue;
+            process.stdout.write(`\n[${r.severity}] ${r.ruleId} (${r.surface}) — ${fs[0].message}\n`);
+            for (const f of fs.slice(0, 50)) {
+                const tag = f.inlineTemplate ? ' [inline template]' : '';
+                process.stdout.write(`    • ${f.match}  (${f.file}:${f.line})${tag}\n`);
+            }
+            if (fs.length > 50)
+                process.stdout.write(`    … (${fs.length - 50} more)\n`);
+            const suggest = fs.find((f) => f.suggest)?.suggest;
+            if (suggest)
+                process.stdout.write(`    → ${suggest}\n`);
+        }
+        return report.verdict === 'errors' ? 1 : 0;
+    },
+};

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":"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"}
+{"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,eA4P9B,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

@@ -114,10 +114,18 @@ export const recommendCommand = {
             }));
             const promotedSet = new Set(promoted.map((p) => p.command));
             const isGenericDefault = (c) => /^(bun run )?shrk (review|report|impact)\b/i.test(c);
+            // The recommender (inspector) already arbitrates the keyword recipe
+            // against the shared ranker and may have promoted a `shrk gen <template>`
+            // / `shrk task` headline (its `why` starts with "Ranker matched"). That
+            // ranker-confirmed scaffold is the engine's corrected route — keep it
+            // ahead of even the routing-hint promotion so the headline survives.
+            const isRankerPromoted = (r) => /^Ranker matched /.test(r.why);
             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));
+            const keptRankerPromoted = existing.filter((r) => !promotedSet.has(r.command) && isRankerPromoted(r));
+            const keptNonGeneric = existing.filter((r) => !promotedSet.has(r.command) && !isRankerPromoted(r) && !isGenericDefault(r.command));
+            const keptGeneric = existing.filter((r) => !promotedSet.has(r.command) && !isRankerPromoted(r) && isGenericDefault(r.command));
             report.recommendations = [
+                ...keptRankerPromoted,
                 ...promoted,
                 ...keptNonGeneric,
                 ...keptGeneric,

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

@@ -1 +1 @@
-{"version":3,"file":"registry.command.d.ts","sourceRoot":"","sources":["../../src/commands/registry.command.ts"],"names":[],"mappings":"AASA,OAAO,EAGL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC,eAAO,MAAM,wBAAwB,EAAE,eActC,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,eAa7B,CAAC"}
+{"version":3,"file":"registry.command.d.ts","sourceRoot":"","sources":["../../src/commands/registry.command.ts"],"names":[],"mappings":"AAwBA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC,eAAO,MAAM,wBAAwB,EAAE,eAetC,CAAC;AAsGF,eAAO,MAAM,eAAe,EAAE,eAuB7B,CAAC"}

package/dist/commands/registry.command.js

@@ -1,18 +1,27 @@
 /**
  * `shrk registry` commands.
  *
- *   shrk registry lifecycle [--json]
+ *   shrk registry lifecycle [--json]            # register/remove symmetry
+ *   shrk registry <name> list [--json]          # every declared id
+ *   shrk registry <name> exists <id> [--json]   # is the id taken? (exit 1 if not)
+ *   shrk registry <name> where <id> [--json]    # declaration (+ consumer) sites
+ *
+ * `<name>` resolves a `registries[]` declaration in sharkcraft.config.ts — one
+ * deterministic multi-root scan that answers "is this id taken / where is it"
+ * without an agent re-running a fragile grep.
  */
-import { buildRegistryLifecycleReport, renderRegistryLifecycleReportText, } from '@shrkcrft/inspector';
-import { flagBool, resolveCwd, } from "../command-registry.js";
+import { buildRegistryLifecycleReport, renderRegistryLifecycleReportText, resolveProjectConfig, } from '@shrkcrft/inspector';
+import { scanRegistry, registryExists, registryWhere, } from '@shrkcrft/boundaries';
+import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
 import { asJson } from "../output/format-output.js";
 export const registryLifecycleCommand = {
     name: 'lifecycle',
-    description: 'Scan the workspace for register*/remove* symmetry. Read-only.',
-    usage: 'shrk registry lifecycle [--json]',
+    description: 'Scan the workspace for register/remove symmetry. Read-only.',
+    usage: 'shrk registry lifecycle [--scope <dir>] [--json]',
     async run(args) {
         const cwd = resolveCwd(args);
-        const report = buildRegistryLifecycleReport({ projectRoot: cwd });
+        const scope = flagString(args, 'scope');
+        const report = buildRegistryLifecycleReport({ projectRoot: cwd, ...(scope ? { scope } : {}) });
         if (flagBool(args, 'json')) {
             process.stdout.write(asJson(report) + '\n');
             return report.missingRemovers.length === 0 ? 0 : 1;
@@ -21,17 +30,116 @@ export const registryLifecycleCommand = {
         return report.missingRemovers.length === 0 ? 0 : 1;
     },
 };
+async function loadRegistries(cwd) {
+    const loaded = await resolveProjectConfig(cwd);
+    if (!loaded.ok)
+        return { ok: false, message: loaded.error.message };
+    return {
+        ok: true,
+        registries: loaded.value.config.registries ?? [],
+        planeDiagnostics: loaded.value.planeDiagnostics,
+    };
+}
+function findRegistry(registries, name) {
+    return registries.find((r) => r.name === name);
+}
+/** Run a `list | exists | where` query against a declared registry. */
+async function runRegistryInventory(args, name) {
+    const cwd = resolveCwd(args);
+    const json = flagBool(args, 'json');
+    const action = args.positional[1];
+    const id = args.positional[2];
+    const loaded = await loadRegistries(cwd);
+    if (!loaded.ok) {
+        if (json)
+            process.stdout.write(asJson({ error: loaded.message }) + '\n');
+        else
+            process.stderr.write(`Could not load config: ${loaded.message}\n  Run \`shrk doctor\` for details.\n`);
+        return 1;
+    }
+    const decl = findRegistry(loaded.registries, name);
+    if (!decl) {
+        const names = loaded.registries.map((r) => r.name);
+        const avail = names.length > 0 ? `Declared registries: ${names.join(', ')}.` : 'No registries declared in sharkcraft.config.ts `registries[]`.';
+        if (json)
+            process.stdout.write(asJson({ error: `unknown registry "${name}"`, available: names }) + '\n');
+        else
+            process.stderr.write(`No registry named "${name}". ${avail}\n`);
+        return 2;
+    }
+    const inventory = scanRegistry(cwd, decl);
+    if (action === 'list' || action === undefined) {
+        // Fold pack-plane merge notes (missing/invalid pack registry files, dropped
+        // collisions) into the inventory's own scan diagnostics.
+        const diagnostics = [...inventory.diagnostics, ...loaded.planeDiagnostics];
+        if (json) {
+            process.stdout.write(asJson({ name: inventory.name, count: inventory.entries.length, ids: inventory.entries.map((e) => e.id), diagnostics }) + '\n');
+            return 0;
+        }
+        process.stdout.write(`Registry "${inventory.name}"${inventory.description ? ' — ' + inventory.description : ''}\n`);
+        process.stdout.write(`  ${inventory.entries.length} id(s)\n`);
+        for (const e of inventory.entries) {
+            process.stdout.write(`  • ${e.id}  (${e.sites.length} site${e.sites.length === 1 ? '' : 's'})\n`);
+        }
+        for (const d of diagnostics)
+            process.stdout.write(`  ! ${d}\n`);
+        return 0;
+    }
+    if (action === 'exists') {
+        if (!id) {
+            process.stderr.write(`Usage: shrk registry ${name} exists <id>\n`);
+            return 2;
+        }
+        const exists = registryExists(inventory, id);
+        if (json)
+            process.stdout.write(asJson({ name: inventory.name, id, exists }) + '\n');
+        else
+            process.stdout.write(`${exists ? 'yes' : 'no'} — "${id}" is ${exists ? 'declared' : 'NOT declared'} in registry "${inventory.name}".\n`);
+        return exists ? 0 : 1;
+    }
+    if (action === 'where') {
+        if (!id) {
+            process.stderr.write(`Usage: shrk registry ${name} where <id>\n`);
+            return 2;
+        }
+        const entry = registryWhere(inventory, id);
+        if (json) {
+            process.stdout.write(asJson({ name: inventory.name, id, found: entry !== undefined, entry: entry ?? null }) + '\n');
+            return entry ? 0 : 1;
+        }
+        if (!entry) {
+            process.stdout.write(`"${id}" is not declared in registry "${inventory.name}".\n`);
+            return 1;
+        }
+        process.stdout.write(`"${id}" in registry "${inventory.name}":\n`);
+        for (const s of entry.sites)
+            process.stdout.write(`  declared  ${s.file}:${s.line}\n`);
+        for (const s of entry.consumerSites ?? [])
+            process.stdout.write(`  consumed  ${s.file}:${s.line}\n`);
+        return 0;
+    }
+    process.stderr.write(`Unknown action "${action}". Usage: shrk registry ${name} list | exists <id> | where <id>\n`);
+    return 2;
+}
 export const registryCommand = {
     name: 'registry',
-    description: 'Registry inspections (lifecycle symmetry, etc.). Read-only.',
-    usage: 'shrk registry lifecycle',
+    description: 'Registry inspections: lifecycle symmetry + declared-registry inventory. Read-only.',
+    usage: 'shrk registry lifecycle | <name> list | <name> exists <id> | <name> where <id>',
     async run(args) {
         const sub = args.positional[0];
         if (sub === 'lifecycle') {
             args.positional = args.positional.slice(1);
             return registryLifecycleCommand.run(args);
         }
-        process.stderr.write('Usage: shrk registry lifecycle\n');
+        if (sub !== undefined && sub.length > 0) {
+            // `<name> list | exists <id> | where <id>` — sub is the registry name.
+            return runRegistryInventory(args, sub);
+        }
+        const cwd = resolveCwd(args);
+        const loaded = await loadRegistries(cwd);
+        const names = loaded.ok ? loaded.registries.map((r) => r.name) : [];
+        process.stderr.write('Usage: shrk registry lifecycle | <name> list | <name> exists <id> | <name> where <id>\n' +
+            (names.length > 0 ? `Declared registries: ${names.join(', ')}.\n` : 'No registries declared (sharkcraft.config.ts `registries[]`).\n'));
         return 2;
     },
 };

package/dist/commands/report.command.js

@@ -8,7 +8,7 @@ const VALID_FORMATS = new Set(['text', 'markdown', 'html', 'json']);
 export const reportCommand = {
     name: 'report',
     description: 'Render runtime reports in text / markdown / html / json. Subcommands: adoption / session / quality / safety / review / coverage / drift / graph.',
-    usage: 'shrk report <adoption|session <id>|quality|safety|review <packet.json>|coverage|drift|graph> [--format text|markdown|html|json] [--output <path>] [--collapse-long-sections] [--max-items N] [--include-raw-json] [--json]',
+    usage: 'shrk report <adoption|session <id>|quality|safety|review <packet.json>|coverage|drift|graph> [--format text|markdown|html|json] [--output <path>] [--collapse-long-sections] [--max-items N] [--json]',
     async run(args) {
         const sub = args.positional[0];
         const sliced = { ...args, positional: args.positional.slice(1) };

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"reuse.command.d.ts","sourceRoot":"","sources":["../../src/commands/reuse.command.ts"],"names":[],"mappings":"AAGA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA4DhC,eAAO,MAAM,YAAY,EAAE,eAqK1B,CAAC"}

package/dist/commands/reuse.command.js

@@ -0,0 +1,202 @@
+import { GraphStore, GraphQueryApi } from '@shrkcrft/graph';
+import { resolveProjectConfig } from '@shrkcrft/inspector';
+import { flagBool, flagNumber, resolveCwd, } from "../command-registry.js";
+import { asJson, header } from "../output/format-output.js";
+const STOP = new Set([
+    'the', 'a', 'an', 'to', 'for', 'of', 'and', 'or', 'with', 'in', 'on', 'into', 'my',
+    'add', 'use', 'using', 'create', 'make', 'new', 'build', 'want', 'need', 'how', 'do',
+]);
+function tokenize(s) {
+    // Min length 3: 2-char tokens (`ui`, `id`) substring-match unrelated text
+    // (`guidance`, `valid`) and produce false-positive primitive matches.
+    return [
+        ...new Set(s
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, ' ')
+            .split(' ')
+            .filter((t) => t.length >= 3 && !STOP.has(t))),
+    ];
+}
+function scorePrimitive(p, tokens) {
+    // Substring match (so intent "debounce" matches symbol `useDebounce`); the
+    // 3-char minimum above keeps it from over-matching on tiny fragments.
+    const hay = [p.symbol, ...(p.roles ?? []), ...(p.keywords ?? []), p.description ?? '']
+        .join(' ')
+        .toLowerCase();
+    let s = 0;
+    for (const t of tokens)
+        if (hay.includes(t))
+            s += 1;
+    // A role the intent mentions is a strong signal; re-weight role hits.
+    for (const role of p.roles ?? []) {
+        const rl = role.toLowerCase();
+        if (rl.length >= 3 && tokens.some((t) => rl.includes(t)))
+            s += 0.5;
+    }
+    return s;
+}
+const INDEX_RE = /(^|\/)index\.[cm]?[jt]sx?$/;
+export const reuseCommand = {
+    name: 'reuse',
+    description: 'Intent → the canonical primitive to reuse. Matches your intent against configured reusePrimitives[], then resolves the symbol in the code graph to its declaration, public import path, sibling exports, and real consumer files to copy. Deterministic; no AI.',
+    usage: 'shrk reuse "<what I want to build>" [--limit N] [--json]',
+    async run(args) {
+        const cwd = resolveCwd(args);
+        const wantJson = flagBool(args, 'json');
+        const limit = flagNumber(args, 'limit') ?? 3;
+        const intent = args.positional.join(' ').trim();
+        if (!intent) {
+            process.stderr.write('Usage: shrk reuse "<what I want to build>" [--limit N] [--json]\n');
+            return 2;
+        }
+        const loaded = await resolveProjectConfig(cwd);
+        if (!loaded.ok) {
+            const msg = loaded.error.message;
+            if (wantJson) {
+                process.stdout.write(asJson({ schema: 'sharkcraft.reuse/v1', intent, error: msg, results: [] }) + '\n');
+                return 1;
+            }
+            process.stdout.write(header(`Reuse: "${intent}"`));
+            process.stdout.write(`  ✗ Could not load config: ${msg}\n  Run \`shrk doctor\` for details.\n`);
+            return 1;
+        }
+        const primitives = loaded.value.config.reusePrimitives ?? [];
+        const planeDiagnostics = loaded.value.planeDiagnostics;
+        // reuse has no pre-existing diagnostics surface; expose pack-plane merge
+        // notes (missing/invalid pack primitive files, dropped collisions) so a
+        // pack contribution that failed to load isn't silently invisible.
+        const planeJson = planeDiagnostics.length > 0 ? { planeDiagnostics } : {};
+        const writePlaneNotes = () => {
+            for (const d of planeDiagnostics)
+                process.stdout.write(`  ! ${d}\n`);
+        };
+        if (primitives.length === 0) {
+            if (wantJson) {
+                process.stdout.write(asJson({ schema: 'sharkcraft.reuse/v1', intent, results: [], ...planeJson }) + '\n');
+                return 0;
+            }
+            process.stdout.write(header(`Reuse: "${intent}"`));
+            process.stdout.write('  No reuse primitives configured. Declare `reusePrimitives[]` in sharkcraft.config.ts\n' +
+                '  to map roles/intents to canonical symbols (see docs/reuse.md).\n');
+            writePlaneNotes();
+            return 0;
+        }
+        const tokens = tokenize(intent);
+        const ranked = primitives
+            .map((p) => ({ p, score: scorePrimitive(p, tokens) }))
+            .filter((x) => x.score > 0)
+            .sort((a, b) => b.score - a.score || a.p.symbol.localeCompare(b.p.symbol))
+            .slice(0, Math.max(1, limit));
+        const store = new GraphStore(cwd);
+        const api = store.exists() ? GraphQueryApi.fromStore(cwd) : null;
+        if (ranked.length === 0) {
+            const roles = [...new Set(primitives.flatMap((p) => p.roles))].sort();
+            if (wantJson) {
+                process.stdout.write(asJson({ schema: 'sharkcraft.reuse/v1', intent, results: [], availableRoles: roles, ...planeJson }) + '\n');
+                return 0;
+            }
+            process.stdout.write(header(`Reuse: "${intent}"`));
+            process.stdout.write('  No primitive matched. Available roles:\n');
+            for (const r of roles.slice(0, 40))
+                process.stdout.write(`    • ${r}\n`);
+            writePlaneNotes();
+            return 0;
+        }
+        const results = ranked.map(({ p, score }) => {
+            const r = { symbol: p.symbol, score, roles: p.roles, siblings: [], consumers: [] };
+            if (p.description)
+                r.description = p.description;
+            if (p.importPath)
+                r.importPath = p.importPath;
+            if (api) {
+                // Disambiguate same-named declarations deterministically: prefer
+                // exported symbols, then shallowest path; disclose the alternates.
+                const candidates = api
+                    .findSymbol(p.symbol, { exact: true })
+                    .slice()
+                    .sort((a, b) => (a.path ?? '').localeCompare(b.path ?? ''));
+                const exported = candidates.filter((c) => c.data?.['isExported'] === true);
+                const pool = exported.length > 0 ? exported : candidates;
+                const sym = pool[0];
+                if (sym) {
+                    if (sym.path)
+                        r.declaredIn = sym.path;
+                    if (sym.line)
+                        r.declaredLine = sym.line;
+                    if (sym.path) {
+                        const fileNode = api.findFile(sym.path);
+                        if (fileNode) {
+                            r.siblings = api
+                                .symbolsIn(fileNode.id)
+                                .filter((s) => s.data?.['isExported'] === true && s.label && s.label !== p.symbol)
+                                .map((s) => s.label)
+                                .slice(0, 8);
+                            // When no public importPath is configured, surface a re-exporting
+                            // barrel as a hint (we never fabricate a module specifier from a
+                            // deep file path — that would be a broken/unusable import).
+                            if (!r.importPath) {
+                                const barrel = api.importersOf(fileNode.id).find((n) => n.path && INDEX_RE.test(n.path));
+                                if (barrel?.path)
+                                    r.reExportedVia = barrel.path;
+                            }
+                        }
+                    }
+                    r.consumers = api
+                        .referenceSitesOf(sym.id)
+                        .slice(0, 5)
+                        .map((s) => ({ path: s.node.path ?? s.node.id, ...(s.line ? { line: s.line } : {}) }));
+                    const alts = pool.slice(1).map((c) => c.path).filter((x) => !!x);
+                    if (alts.length > 0)
+                        r.alternates = alts;
+                }
+                else {
+                    r.notFound = true;
+                }
+            }
+            // The import line is emitted ONLY from a configured importPath (a clean,
+            // copy-pasteable specifier). Without it we show declaration + barrel hint.
+            if (r.importPath)
+                r.importLine = `import { ${p.symbol} } from '${r.importPath}';`;
+            return r;
+        });
+        if (wantJson) {
+            process.stdout.write(asJson({ schema: 'sharkcraft.reuse/v1', intent, graphIndexed: !!api, results, ...planeJson }) + '\n');
+            return 0;
+        }
+        process.stdout.write(header(`Reuse: "${intent}"`));
+        writePlaneNotes();
+        if (!api) {
+            process.stdout.write('  (code graph missing — import path/siblings/consumers limited; run `shrk graph index`)\n');
+        }
+        let i = 0;
+        for (const r of results) {
+            i += 1;
+            process.stdout.write(`\n${i}. ${r.symbol}\n`);
+            if (r.description)
+                process.stdout.write(`   ${r.description}\n`);
+            if (r.notFound) {
+                process.stdout.write('   ⚠ symbol not found in the code graph — verify reusePrimitives[].symbol (typo/rename?) or run `shrk graph index`\n');
+            }
+            if (r.importLine) {
+                process.stdout.write(`   import: ${r.importLine}\n`);
+            }
+            else if (r.reExportedVia) {
+                process.stdout.write(`   re-exported via: ${r.reExportedVia}  (set reusePrimitives[].importPath for a copy-paste import)\n`);
+            }
+            if (r.declaredIn) {
+                process.stdout.write(`   declared in: ${r.declaredIn}${r.declaredLine ? ':' + r.declaredLine : ''}\n`);
+            }
+            if (r.alternates && r.alternates.length > 0) {
+                process.stdout.write(`   ⚠ name also declared in: ${r.alternates.join(', ')}\n`);
+            }
+            if (r.siblings.length > 0)
+                process.stdout.write(`   sibling exports: ${r.siblings.join(', ')}\n`);
+            if (r.consumers.length > 0) {
+                process.stdout.write('   consumers to copy:\n');
+                for (const c of r.consumers)
+                    process.stdout.write(`     - ${c.path}${c.line ? ':' + c.line : ''}\n`);
+            }
+        }
+        return 0;
+    },
+};

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,eA+E3B,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;AA6GhC,eAAO,MAAM,aAAa,EAAE,eAiG3B,CAAC"}

package/dist/commands/review.command.js

@@ -77,7 +77,20 @@ function scaffoldOptionsFromArgs(args) {
 export const reviewCommand = {
     name: 'review',
     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 [--since <ref>] [--staged] [--files a,b] [--json] | shrk review scaffold github-action [...] | shrk review render-comment <packet.json> [--output <file>]',
+    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([
+        'json',
+        'staged',
+        'untracked',
+        'no-untracked',
+        'v2',
+        'v3',
+        'with-boundaries',
+        'with-coverage',
+        'with-drift',
+        'artifact-only',
+        'comment-placeholder',
+    ]),
     async run(args) {
         if (args.positional[0] === 'scaffold') {
             const which = args.positional[1] ?? 'github-action';
@@ -97,11 +110,16 @@ export const reviewCommand = {
         }
         const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
         const since = flagString(args, 'since');
-        const files = flagList(args, 'files');
+        // Accept files via `--files a,b` OR as bare positional args
+        // (`shrk review a.ts b.ts`). Positionals were previously dropped silently,
+        // yielding a confident "0 changed files" with exit 0.
+        const filesFlag = flagList(args, 'files');
+        const files = filesFlag.length ? filesFlag : args.positional;
         const packet = buildReviewPacket(inspection, {
             ...(since ? { since } : {}),
             ...(flagBool(args, 'staged') ? { staged: true } : {}),
             ...(files.length ? { files } : {}),
+            ...(flagBool(args, 'no-untracked') ? { untracked: false } : {}),
         });
         if (flagBool(args, 'json')) {
             process.stdout.write(asJson(packet) + '\n');

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

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

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

@@ -5,7 +5,8 @@
  * 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 { buildBridge, BridgeStore, RuleGraphQueryApi } from '@shrkcrft/rule-graph';
+import { detectGraphFreshness } from '@shrkcrft/graph';
 import { flagBool, resolveCwd } from "../command-registry.js";
 import { asJson, header, kv } from "../output/format-output.js";
 export const ruleGraphCommand = {
@@ -54,13 +55,39 @@ async function runStatus(args) {
         return 1;
     }
     const api = RuleGraphQueryApi.fromStores(cwd);
-    // No public counters from the API itself — just confirm it loads.
+    // The bridge maps code-graph files → asset registries, so it is stale once
+    // the underlying code graph has drifted. Reuse the already-available graph
+    // freshness signal (the same one `graph status` reports) rather than a
+    // hardcoded 'fresh'. `lastBuiltAt` comes from the bridge manifest.
+    let lastBuiltAt = null;
+    try {
+        lastBuiltAt = new BridgeStore(cwd).loadSnapshot().manifest.lastBuiltAt;
+    }
+    catch {
+        lastBuiltAt = null;
+    }
+    const fresh = detectGraphFreshness(cwd);
+    const behind = fresh.modified.length + fresh.added.length + fresh.deleted.length;
+    const state = behind > 0 ? 'stale' : 'fresh';
     if (wantJson) {
-        process.stdout.write(asJson({ ok: true, state: 'fresh' }) + '\n');
+        process.stdout.write(asJson({
+            ok: true,
+            state,
+            lastBuiltAt,
+            modifiedSinceIndex: fresh.modified.length,
+            newSinceIndex: fresh.added.length,
+            deletedSinceIndex: fresh.deleted.length,
+            ...(state === 'stale' ? { nextCommand: 'shrk rule-graph index' } : {}),
+        }) + '\n');
         return 0;
     }
     process.stdout.write(header('Rule-graph status'));
-    process.stdout.write(kv('state', 'fresh') + '\n');
+    if (lastBuiltAt)
+        process.stdout.write(kv('last built', lastBuiltAt) + '\n');
+    process.stdout.write(kv('state', state) + '\n');
+    if (state === 'stale') {
+        process.stdout.write(`! stale — ${fresh.modified.length} modified, ${fresh.added.length} new, ${fresh.deleted.length} deleted in the code graph since the bridge was built; re-run \`shrk rule-graph index\`\n`);
+    }
     void api;
     return 0;
 }