@shrkcrft/cli 0.1.0-alpha.22 → 0.1.0-alpha.24

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

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

package/dist/commands/context.command.js

@@ -1,4 +1,4 @@
-import { entrypointBanner, inspectSharkcraft } from '@shrkcrft/inspector';
+import { contextTuningBoostFor, entrypointBanner, inspectSharkcraft } from '@shrkcrft/inspector';
 import { buildContext } from '@shrkcrft/context';
 import { loadIntentBenchmark, runIntentBenchmark, STARTER_INTENT_BENCHMARK, writeBenchmarkRun, } from '@shrkcrft/context-planner';
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
@@ -67,6 +67,7 @@ export const contextCommand = {
         const includeCommands = flagBool(args, 'include-commands');
         const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
         const overview = buildProjectOverview(inspection.workspace, inspection.config?.projectName);
+        const contextBoost = contextTuningBoostFor(inspection, task);
         const result = buildContext(inspection.knowledgeEntries, {
             task,
             framework,
@@ -81,6 +82,7 @@ export const contextCommand = {
             includeDocs,
             includeCommands,
             projectOverview: renderOverviewText(overview),
+            ...(contextBoost ? { boostFor: contextBoost } : {}),
         });
         // Surface top commands prominently before the long context body.
         // Auto-promote commands-first for action-like tasks (rename / add /

package/dist/commands/daily.commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"daily.commands.d.ts","sourceRoot":"","sources":["../../src/commands/daily.commands.ts"],"names":[],"mappings":"AAOA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAMhC,eAAO,MAAM,WAAW,EAAE,eAsFzB,CAAC;AAcF,eAAO,MAAM,WAAW,EAAE,eAoGzB,CAAC;AAKF,eAAO,MAAM,cAAc,EAAE,eA6D5B,CAAC"}
+{"version":3,"file":"daily.commands.d.ts","sourceRoot":"","sources":["../../src/commands/daily.commands.ts"],"names":[],"mappings":"AAOA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAMhC,eAAO,MAAM,WAAW,EAAE,eAsFzB,CAAC;AAcF,eAAO,MAAM,WAAW,EAAE,eAoGzB,CAAC;AAKF,eAAO,MAAM,cAAc,EAAE,eAyG5B,CAAC"}

package/dist/commands/daily.commands.js

@@ -186,14 +186,33 @@ export const explainCommand = {
         const top = inspection.knowledgeEntries
             .filter((e) => matches(topic, e.id, e.title, e.content, e.tags.join(' ')))
             .slice(0, maxEntries);
+        // Surface the matched items themselves, not just counts. `explain`
+        // otherwise duplicates `shrk search`'s job while hiding what matched.
+        const relevantRules = packet.relevantRules.map((r) => ({
+            id: r.id,
+            title: r.title,
+            priority: r.priority,
+        }));
+        const relevantPaths = packet.relevantPaths.map((p) => ({
+            id: p.id,
+            title: p.title,
+            priority: p.priority,
+        }));
+        const relevantTemplates = packet.relevantTemplates.map((t) => ({
+            id: t.id,
+            name: t.name,
+        }));
         if (flagBool(args, 'json')) {
             process.stdout.write(asJson({
                 topic,
                 summary: {
-                    relevantRules: packet.relevantRules.length,
-                    relevantPaths: packet.relevantPaths.length,
-                    relevantTemplates: packet.relevantTemplates.length,
+                    relevantRules: relevantRules.length,
+                    relevantPaths: relevantPaths.length,
+                    relevantTemplates: relevantTemplates.length,
                 },
+                relevantRules,
+                relevantPaths,
+                relevantTemplates,
                 entries: top.map((e) => ({
                     id: e.id,
                     title: e.title,
@@ -205,11 +224,35 @@ export const explainCommand = {
             return 0;
         }
         process.stdout.write(header(`explain: ${topic}`));
-        process.stdout.write(kv('matches', `rules=${packet.relevantRules.length} paths=${packet.relevantPaths.length} templates=${packet.relevantTemplates.length}`) + '\n\n');
+        process.stdout.write(kv('matches', `rules=${relevantRules.length} paths=${relevantPaths.length} templates=${relevantTemplates.length}`) + '\n\n');
+        if (relevantRules.length > 0) {
+            process.stdout.write('Rules:\n');
+            for (const r of relevantRules) {
+                process.stdout.write(`  • [${r.priority}] ${r.id} — ${r.title}\n`);
+            }
+            process.stdout.write('\n');
+        }
+        if (relevantPaths.length > 0) {
+            process.stdout.write('Paths:\n');
+            for (const p of relevantPaths) {
+                process.stdout.write(`  • [${p.priority}] ${p.id} — ${p.title}\n`);
+            }
+            process.stdout.write('\n');
+        }
+        if (relevantTemplates.length > 0) {
+            process.stdout.write('Templates:\n');
+            for (const t of relevantTemplates) {
+                process.stdout.write(`  • ${t.id} — ${t.name}\n`);
+            }
+            process.stdout.write('\n');
+        }
         if (top.length === 0) {
-            process.stdout.write('(no matching knowledge entries)\n');
+            if (relevantRules.length + relevantPaths.length + relevantTemplates.length === 0) {
+                process.stdout.write('(no matching knowledge entries)\n');
+            }
             return 0;
         }
+        process.stdout.write('Knowledge:\n');
         for (const e of top) {
             process.stdout.write(`• [${e.priority}] ${e.id} — ${e.title}\n`);
             const body = e.content

package/dist/commands/diff-check.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"diff-check.command.d.ts","sourceRoot":"","sources":["../../src/commands/diff-check.command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAcH,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA0GhC,eAAO,MAAM,gBAAgB,EAAE,eAiI9B,CAAC"}
+{"version":3,"file":"diff-check.command.d.ts","sourceRoot":"","sources":["../../src/commands/diff-check.command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAcH,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA6GhC,eAAO,MAAM,gBAAgB,EAAE,eAkI9B,CAAC"}

package/dist/commands/diff-check.command.js

@@ -34,9 +34,12 @@ function resolveScope(args, cwd) {
     const staged = flagBool(args, 'staged');
     const since = flagString(args, 'since');
     const filesRaw = flagString(args, 'files');
+    // Files come from `--files a,b` or as bare positional args
+    // (`shrk diff-check a.ts b.ts`). Positionals were previously ignored, which
+    // silently widened the scope back to the full worktree.
     const files = filesRaw
         ? filesRaw.split(',').map((s) => s.trim()).filter((s) => s.length > 0)
-        : [];
+        : args.positional.filter((s) => s.length > 0);
     if (files.length > 0) {
         return { mode: 'files', options: { projectRoot: cwd, files } };
     }
@@ -97,7 +100,8 @@ function deriveVerdict(env) {
 export const diffCheckCommand = {
     name: 'diff-check',
     description: 'Self-check the current git diff against this project\'s boundary + import-hygiene rules. Single-call composite of `shrk check boundaries --changed-only` + `shrk check imports --changed-only`, with one verdict and one nextAction line. Designed for AI agents to run after editing — pass --json for the structured envelope.',
-    usage: 'shrk [--cwd <dir>] diff-check [--staged | --since <ref> | --files a.ts,b.ts] [--json]',
+    usage: 'shrk [--cwd <dir>] diff-check [files... | --files a.ts,b.ts | --staged | --since <ref>] [--json]',
+    booleanFlags: new Set(['json', 'staged']),
     async run(args) {
         const cwd = resolveCwd(args);
         const wantJson = flagBool(args, 'json');

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

@@ -1 +1 @@
-{"version":3,"file":"feedback.command.d.ts","sourceRoot":"","sources":["../../src/commands/feedback.command.ts"],"names":[],"mappings":"AAiBA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAgBhC,eAAO,MAAM,qBAAqB,EAAE,eAiCnC,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,eA0CtC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAyDpC,CAAC;AAEF,eAAO,MAAM,+BAA+B,EAAE,eAwB7C,CAAC;AAIF,eAAO,MAAM,wBAAwB,EAAE,eAqBtC,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,eAiDxC,CAAC;AAGF,eAAO,MAAM,sBAAsB,EAAE,eAqBpC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eAqBnC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eA6BjC,CAAC"}
+{"version":3,"file":"feedback.command.d.ts","sourceRoot":"","sources":["../../src/commands/feedback.command.ts"],"names":[],"mappings":"AAiBA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAiBhC,eAAO,MAAM,qBAAqB,EAAE,eAiCnC,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,eA0CtC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAyDpC,CAAC;AAEF,eAAO,MAAM,+BAA+B,EAAE,eAwB7C,CAAC;AAIF,eAAO,MAAM,wBAAwB,EAAE,eAqBtC,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,eAoDxC,CAAC;AAGF,eAAO,MAAM,sBAAsB,EAAE,eAqBpC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eAqBnC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eA6BjC,CAAC"}

package/dist/commands/feedback.command.js

@@ -10,6 +10,7 @@ import * as nodePath from 'node:path';
 import { FeedbackBucket, ingestFeedbackFile, inspectSharkcraft, loadFeedbackRules, renderFeedbackBacklog, } from '@shrkcrft/inspector';
 import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
 import { asJson, header } from "../output/format-output.js";
+import { feedbackRulesDoctorHints, renderFailureHints } from "../output/failure-hints.js";
 function ingestPositional(args) {
     return args.positional[0];
 }
@@ -256,6 +257,9 @@ export const feedbackRulesDoctorCommand = {
             process.stdout.write(`  ERROR   ${e.id}: ${e.message}\n`);
         for (const w of warnings)
             process.stdout.write(`  WARN    ${w.id}: ${w.message}\n`);
+        if (errors.length > 0) {
+            process.stdout.write(renderFailureHints(feedbackRulesDoctorHints()));
+        }
         return errors.length > 0 ? 1 : 0;
     },
 };

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"finish.command.d.ts","sourceRoot":"","sources":["../../src/commands/finish.command.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA8DhC,eAAO,MAAM,aAAa,EAAE,eAmB3B,CAAC"}

package/dist/commands/finish.command.js

@@ -0,0 +1,70 @@
+import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { asJson, bullet, header, kv } from "../output/format-output.js";
+import { runFinishGates } from "../finish/run-finish.js";
+function resolveScope(args, cwd) {
+    const staged = flagBool(args, 'staged');
+    const since = flagString(args, 'since');
+    const filesRaw = flagString(args, 'files');
+    const files = filesRaw
+        ? filesRaw.split(',').map((s) => s.trim()).filter((s) => s.length > 0)
+        : args.positional.filter((s) => s.length > 0);
+    if (files.length > 0)
+        return { mode: 'files', options: { projectRoot: cwd, files } };
+    if (staged)
+        return { mode: 'staged', options: { projectRoot: cwd, staged: true } };
+    if (since)
+        return { mode: 'since', options: { projectRoot: cwd, since } };
+    return { mode: 'worktree', options: { projectRoot: cwd, includeWorktree: true } };
+}
+const STATUS_GLYPH = {
+    pass: '✓',
+    fail: '✗',
+    skipped: '–',
+};
+function renderText(report) {
+    process.stdout.write(header('Finish — is this changeset safe to complete?'));
+    process.stdout.write(kv('scope', `${report.scope.mode} (${report.scope.fileCount} file${report.scope.fileCount === 1 ? '' : 's'})`) +
+        '\n');
+    for (const g of report.gates) {
+        process.stdout.write(`  ${STATUS_GLYPH[g.status]} ${g.name.padEnd(11)} ${g.status.padEnd(8)} ${g.detail}\n`);
+    }
+    if (report.impact.ran) {
+        process.stdout.write(kv('impact', `risk=${report.impact.risk}, ${report.impact.directDependents} direct / ${report.impact.transitiveDependents} transitive dependents`) +
+            '\n');
+    }
+    else if (report.impact.note) {
+        process.stdout.write(kv('impact', `(skipped — ${report.impact.note})`) + '\n');
+    }
+    process.stdout.write(kv('verdict', report.verdict) + '\n\n');
+    process.stdout.write(report.summary + '\n');
+    const failing = report.gates.filter((g) => g.status === 'fail');
+    for (const g of failing) {
+        process.stdout.write(`\n${g.name} — failing items:\n`);
+        for (const item of g.items.slice(0, 15)) {
+            const loc = item.file ? `${item.file}${item.line ? `:${item.line}` : ''}` : '';
+            process.stdout.write(bullet(`${loc ? loc + ' — ' : ''}${item.message}`) + '\n');
+        }
+        if (g.items.length > 15) {
+            process.stdout.write(`  … and ${g.items.length - 15} more (pass --json for the full list).\n`);
+        }
+    }
+    process.stdout.write(`\nNext: ${report.nextAction}\n`);
+}
+export const finishCommand = {
+    name: 'finish',
+    description: 'Composite "is this changeset safe to finish?" gate: EXECUTES every deterministic changed-only check inline — boundaries + import-hygiene + wiring + policy + deleted-orphans — plus an impact summary, and returns ONE pass/fail. The single trustworthy "done?" call after editing (superset of `diff-check`; honors 0-rules→skipped). Read-only.',
+    usage: 'shrk [--cwd <dir>] finish [files... | --files a.ts,b.ts | --staged | --since <ref>] [--json]',
+    booleanFlags: new Set(['json', 'staged']),
+    async run(args) {
+        const cwd = resolveCwd(args);
+        const wantJson = flagBool(args, 'json');
+        const { mode, options } = resolveScope(args, cwd);
+        const report = await runFinishGates({ cwd, mode, scope: options });
+        if (wantJson) {
+            process.stdout.write(asJson(report) + '\n');
+            return report.verdict === 'fail' ? 1 : 0;
+        }
+        renderText(report);
+        return report.verdict === 'fail' ? 1 : 0;
+    },
+};

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

@@ -1 +1 @@
-{"version":3,"file":"framework.command.d.ts","sourceRoot":"","sources":["../../src/commands/framework.command.ts"],"names":[],"mappings":"AAOA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,EAAE,eAe9B,CAAC"}
+{"version":3,"file":"framework.command.d.ts","sourceRoot":"","sources":["../../src/commands/framework.command.ts"],"names":[],"mappings":"AAOA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAIhC;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,EAAE,eAe9B,CAAC"}

package/dist/commands/framework.command.js

@@ -1,7 +1,8 @@
 import { buildRegistryWithPacks, defaultRegistry, FrameworkQueryApi, runExtractors, } from '@shrkcrft/framework-scanners';
 import { inspectSharkcraft } from '@shrkcrft/inspector';
-import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { flagBool, flagPositiveInt, flagString, resolveCwd, } from "../command-registry.js";
 import { asJson, header, kv } from "../output/format-output.js";
+import { computeMtimeFreshness } from "../status/freshness.js";
 /**
  * `shrk framework` — run / inspect the framework-aware extractors.
  *
@@ -109,8 +110,20 @@ async function runStatus(args) {
     }
     const api = FrameworkQueryApi.fromStore(cwd);
     const m = api.manifest();
+    // Honest freshness: the framework store is stale once a source file changed
+    // after it was built. Mirror the `state + lastBuiltAt + drift` shape that
+    // `graph status` exposes.
+    const fresh = computeMtimeFreshness(cwd, m.lastBuiltAt);
     if (wantJson) {
-        process.stdout.write(asJson({ ok: true, manifest: m }) + '\n');
+        process.stdout.write(asJson({
+            ok: true,
+            state: fresh.state,
+            lastBuiltAt: m.lastBuiltAt,
+            lastChangedAt: fresh.lastChangedAt,
+            behindMs: fresh.behindMs,
+            ...(fresh.state === 'stale' ? { nextCommand: 'shrk framework index' } : {}),
+            manifest: m,
+        }) + '\n');
         return 0;
     }
     process.stdout.write(header('Framework status'));
@@ -120,6 +133,10 @@ async function runStatus(args) {
         process.stdout.write(kv(`  ${k}`, String(v)) + '\n');
     }
     process.stdout.write(kv('last built', m.lastBuiltAt) + '\n');
+    process.stdout.write(kv('state', fresh.state) + '\n');
+    if (fresh.state === 'stale') {
+        process.stdout.write(`! stale — source changed since last build${fresh.lastChangedAt ? ` (last change ${fresh.lastChangedAt})` : ''}; re-run \`shrk framework index\`\n`);
+    }
     return 0;
 }
 async function runList(args) {
@@ -134,7 +151,7 @@ async function runList(args) {
     const framework = flagString(args, 'framework');
     const subtype = flagString(args, 'subtype');
     const file = flagString(args, 'file');
-    const limit = Number(flagString(args, 'limit') ?? '50');
+    const limit = flagPositiveInt(args, 'limit', 50);
     const entities = api.list({
         ...(framework ? { framework } : {}),
         ...(subtype ? { subtype } : {}),

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

@@ -1 +1 @@
-{"version":3,"file":"gate.command.d.ts","sourceRoot":"","sources":["../../src/commands/gate.command.ts"],"names":[],"mappings":"AAQA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW,EAAE,eA0GzB,CAAC"}
+{"version":3,"file":"gate.command.d.ts","sourceRoot":"","sources":["../../src/commands/gate.command.ts"],"names":[],"mappings":"AAaA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW,EAAE,eAiMzB,CAAC"}

package/dist/commands/gate.command.js

@@ -1,5 +1,5 @@
 import { QualityGateReportStore, renderGateReportMarkdown, runQualityGates, } from '@shrkcrft/quality-gates';
-import { loadProjectConfig } from '@shrkcrft/config';
+import { inspectSharkcraft, resolveChangedFiles, resolveProjectConfig, } from '@shrkcrft/inspector';
 import { chmodSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
 import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
@@ -19,7 +19,7 @@ import { asJson, header, kv } from "../output/format-output.js";
 export const gateCommand = {
     name: 'gate',
     description: 'Aggregator: runs the code-intelligence quality gates (graph freshness, architecture, impact-since-ref) and reports a single pass/fail.',
-    usage: 'shrk gate [--since <gitref>] [--fail-on critical,high] [--arch-all] [--disable arch,impact,api-diff] [--api-baseline <path>] [--no-fail-on-breaking] [--strict] [--no-persist] [--json] [--markdown] [--output <path>]\n         (the arch gate is baseline-relative by default once a baseline is frozen — fails only on NEW errors; --arch-all fails on total)\n         shrk gate scaffold-ci [--provider github|generic] [--force] [--json]\n         shrk gate scaffold-hook [--provider husky|raw] [--force] [--json]',
+    usage: 'shrk gate [--since <gitref>] [--changed-only] [--staged] [--files a,b,c] [--fail-on critical,high] [--arch-all] [--disable arch,impact,policy,knowledge-symbol,api-diff] [--api-baseline <path>] [--no-fail-on-breaking] [--strict] [--no-persist] [--json] [--markdown] [--output <path>]\n         (the arch gate is baseline-relative once a baseline is frozen — fails only on NEW errors; with no baseline it warns on errors rather than going perpetually red — --arch-all fails on total, --strict escalates the warn)\n         (--changed-only / --staged / --files / --since scope the wiring + policy + knowledge-symbol gates to the changeset; they also drive the impact gate — --since diffs the gitref, the others analyze the changed-file set)\n         shrk gate scaffold-ci [--provider github|generic] [--force] [--json]\n         shrk gate scaffold-hook [--provider husky|raw] [--force] [--json]',
     async run(args) {
         if (args.positional[0] === 'scaffold-ci') {
             const sliced = { ...args, positional: args.positional.slice(1) };
@@ -39,30 +39,115 @@ export const gateCommand = {
         const disableRaw = flagString(args, 'disable');
         const apiBaseline = flagString(args, 'api-baseline');
         const noFailOnBreaking = flagBool(args, 'no-fail-on-breaking');
-        const failOn = failOnRaw
+        // `--fail-on` accepts only `high` / `critical`. An unknown token used to
+        // silently REPLACE the default `['critical']`, leaving nothing able to fail
+        // the gate — reject it loudly (exit 2) instead.
+        const failOnTokens = failOnRaw
             ? failOnRaw.split(',').map((s) => s.trim()).filter(Boolean)
             : undefined;
+        if (failOnTokens) {
+            const allowedRisk = new Set(['high', 'critical']);
+            const unknown = failOnTokens.filter((t) => !allowedRisk.has(t));
+            if (unknown.length > 0) {
+                process.stderr.write(`Unknown --fail-on value(s): ${unknown.join(', ')}. Allowed: high, critical.\n`);
+                return 2;
+            }
+        }
+        const failOn = failOnTokens && failOnTokens.length > 0
+            ? failOnTokens
+            : undefined;
         const disable = disableRaw ? disableRaw.split(',').map((s) => s.trim()).filter(Boolean) : undefined;
         // --arch-all: fail on TOTAL architecture errors (ignore the frozen baseline).
         // By default the arch gate is baseline-relative — it fails only on NEW errors.
         const archAll = flagBool(args, 'arch-all');
-        // Wiring rules come from the project config; the gate is skipped (never red)
-        // when none are declared, so this is inert for projects that don't opt in.
-        // An INVALID config is surfaced (warn) rather than silently disabling wiring.
-        const loadedConfig = await loadProjectConfig(cwd);
+        // Changeset scope. `--changed-only` (tracked + untracked worktree),
+        // `--staged`, `--files`, and `--since` all narrow the wiring + policy +
+        // knowledge-symbol gates to the change. `--since` additionally drives the
+        // (ref-based) impact gate, as before.
+        const changedOnly = flagBool(args, 'changed-only');
+        const staged = flagBool(args, 'staged');
+        const filesRaw = flagString(args, 'files');
+        const fileList = filesRaw ? filesRaw.split(',').map((s) => s.trim()).filter(Boolean) : [];
+        const wantChangedScope = changedOnly || staged || Boolean(sinceRef) || fileList.length > 0;
+        let changedFiles;
+        if (wantChangedScope) {
+            const resolved = resolveChangedFiles({
+                projectRoot: cwd,
+                ...(fileList.length > 0 ? { files: fileList } : {}),
+                ...(staged ? { staged: true } : {}),
+                ...(sinceRef ? { since: sinceRef } : {}),
+                ...(changedOnly && !staged && !sinceRef && fileList.length === 0
+                    ? { includeWorktree: true }
+                    : {}),
+            });
+            changedFiles = resolved.files;
+        }
+        // Wiring + policy rules come from the project config; each gate is skipped
+        // (never red) when none are declared, so they're inert for projects that
+        // don't opt in. An INVALID config is surfaced (warn) rather than silently
+        // disabling the plane.
+        const loadedConfig = await resolveProjectConfig(cwd);
         const wiringRules = loadedConfig.ok ? loadedConfig.value.config.wiringRules ?? [] : [];
-        const wiringConfigError = loadedConfig.ok ? undefined : loadedConfig.error.message;
+        const policyRules = loadedConfig.ok ? loadedConfig.value.config.policyRules ?? [] : [];
+        const configError = loadedConfig.ok ? undefined : loadedConfig.error.message;
+        // Pack-plane merge notes (missing/invalid pack rule files, dropped
+        // collisions) go to stderr so they never pollute the JSON/markdown report
+        // on stdout that CI consumes.
+        if (loadedConfig.ok) {
+            for (const d of loadedConfig.value.planeDiagnostics) {
+                process.stderr.write(`plane: ${d}\n`);
+            }
+        }
+        const scopeOpts = wantChangedScope
+            ? { changedOnly: true, changedFiles: changedFiles ?? [] }
+            : {};
+        // Knowledge symbol-ref integrity needs the loaded knowledge entries. The
+        // inspection is async, so we build it here and inject it; the gate stays
+        // synchronous and resolves the code graph itself. Best-effort — a failed
+        // inspection just skips the gate rather than failing `shrk gate`.
+        let inspection;
+        if (!disable?.includes('knowledge-symbol')) {
+            try {
+                inspection = await inspectSharkcraft({ cwd });
+            }
+            catch {
+                inspection = undefined;
+            }
+        }
         const report = runQualityGates({
             projectRoot: cwd,
             ...(archAll ? { arch: { baselineRelative: false } } : {}),
-            ...(wiringConfigError
-                ? { wiring: { configError: wiringConfigError } }
-                : wiringRules.length > 0
-                    ? { wiring: { rules: wiringRules } }
-                    : {}),
+            wiring: {
+                ...(configError
+                    ? { configError }
+                    : wiringRules.length > 0
+                        ? { rules: wiringRules }
+                        : {}),
+                ...scopeOpts,
+            },
+            policy: {
+                ...(configError
+                    ? { configError }
+                    : policyRules.length > 0
+                        ? { rules: policyRules }
+                        : {}),
+                ...scopeOpts,
+            },
+            ...(inspection
+                ? {
+                    knowledgeSymbol: {
+                        inspection,
+                        ...(wantChangedScope ? { changedFiles: changedFiles ?? [] } : {}),
+                    },
+                }
+                : {}),
             impact: {
                 ...(sinceRef ? { sinceRef } : {}),
                 ...(failOn ? { failOn } : {}),
+                // Scope the impact gate to the changeset too: with `--since` we keep the
+                // gitref diff; with `--changed-only` / `--staged` / `--files` (and no
+                // `--since`) we analyze the resolved changed-file set directly.
+                ...(wantChangedScope && !sinceRef ? { files: changedFiles ?? [] } : {}),
             },
             ...(apiBaseline
                 ? {

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

@@ -1 +1 @@
-{"version":3,"file":"graph-code-subverbs.d.ts","sourceRoot":"","sources":["../../src/commands/graph-code-subverbs.ts"],"names":[],"mappings":"AA0BA,OAAO,EAAoC,KAAK,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAiI3F,wBAAsB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAgBrE;AA4FD,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA+DtE;AAiBD,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAwF1E;AAID,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA8EpE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAmFtE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAiDtE;AAID,wBAAsB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAgMvE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA8HtE;AAID;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA+CpE;AAID,wBAAsB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAkGvE;AAyBD;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAgHpE"}
+{"version":3,"file":"graph-code-subverbs.d.ts","sourceRoot":"","sources":["../../src/commands/graph-code-subverbs.ts"],"names":[],"mappings":"AA2BA,OAAO,EAAiE,KAAK,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAgLxH,wBAAsB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAkBrE;AA4FD,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAkEtE;AAiBD,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA2F1E;AAID,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA+EpE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA+FtE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAwEtE;AAID,wBAAsB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA2MvE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA+HtE;AAID;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAgEpE;AAID,wBAAsB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAiGvE;AAyBD;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAgHpE"}