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

package/dist/commands/pr.command.js

@@ -11,6 +11,7 @@ import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
 import { buildPrSummary, inspectSharkcraft, } from '@shrkcrft/inspector';
 import { flagBool, flagNumber, flagString, flagList, resolveCwd, } from "../command-registry.js";
+import { PositionalMode } from "../dispatch/positional-mode.js";
 import { asJson } from "../output/format-output.js";
 async function runPrSummary(args) {
     const cwd = resolveCwd(args);
@@ -117,6 +118,19 @@ function writeOutputFile(cwd, file, body) {
 }
 export const prCommand = {
     name: 'pr',
+    positionals: PositionalMode.None,
+    subverbs: [
+        {
+            name: 'summary',
+            description: 'The PR summary (the default).',
+            usage: 'shrk pr summary [--since <ref>|--staged|--files a,b,c] [--max-items N] [--format markdown|json] [--output <file>] [--include-raw-links]',
+        },
+        {
+            name: 'description',
+            description: 'The PR description (the same generator).',
+            usage: 'shrk pr description [--since <ref>|--staged|--files a,b,c] [--max-items N] [--format markdown|json] [--output <file>] [--include-raw-links]',
+        },
+    ],
     description: 'PR summary / description generator. Consumes `shrk changes summary` + .sharkcraft/reports/*. Read-only by default. Write only when --output is passed.',
     usage: 'shrk pr <summary|description> [--since <ref>|--staged|--files a,b,c] [--max-items N] [--format markdown|json] [--output <file>] [--include-raw-links]',
     async run(args) {

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

@@ -1 +1 @@
-{"version":3,"file":"presets.command.d.ts","sourceRoot":"","sources":["../../src/commands/presets.command.ts"],"names":[],"mappings":"AAaA,OAAO,EAGL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA+BhC,eAAO,MAAM,kBAAkB,EAAE,eAgChC,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,eAoF/B,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eAqFnC,CAAC;AA+BF,eAAO,MAAM,uBAAuB,EAAE,eA4CrC,CAAC;AA2BF,eAAO,MAAM,qBAAqB,EAAE,eAmDnC,CAAC;AAiBF,eAAO,MAAM,mBAAmB,EAAE,eAoEjC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eA+DlC,CAAC;AAmCF,eAAO,MAAM,kBAAkB,EAAE,eAgFhC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,eAiDjC,CAAC;AAIF,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE9D"}
+{"version":3,"file":"presets.command.d.ts","sourceRoot":"","sources":["../../src/commands/presets.command.ts"],"names":[],"mappings":"AAcA,OAAO,EAGL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAgChC,eAAO,MAAM,kBAAkB,EAAE,eAqChC,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,eAoF/B,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eAqFnC,CAAC;AASF,eAAO,MAAM,uBAAuB,EAAE,eA4CrC,CAAC;AA2BF,eAAO,MAAM,qBAAqB,EAAE,eAmDnC,CAAC;AAiBF,eAAO,MAAM,mBAAmB,EAAE,eAoEjC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eA+DlC,CAAC;AAmCF,eAAO,MAAM,kBAAkB,EAAE,eAgFhC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,eAiDjC,CAAC;AAIF,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE9D"}

package/dist/commands/presets.command.js

@@ -1,8 +1,10 @@
 import * as nodePath from 'node:path';
-import { inspectSharkcraft, inspectionReferenceLookup } from '@shrkcrft/inspector';
+import { ContributionKind, inspectSharkcraft, inspectionReferenceLookup } from '@shrkcrft/inspector';
 import { applyPresetPlan, previewResolvedPresetApplication, recommendPresets, resolvePreset, resolvePresetReferences, } from '@shrkcrft/presets';
+import { describeWorkspaceProfile } from '@shrkcrft/workspace';
 import { flagBool, resolveCwd, } from "../command-registry.js";
 import { asJson, header, kv } from "../output/format-output.js";
+import { writeRejectedEntriesNote } from "../output/rejected-entries-note.js";
 function compact(p) {
     return {
         id: p.id,
@@ -36,11 +38,15 @@ export const presetsListCommand = {
     async run(args) {
         const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
         const presets = inspection.presetRegistry.list();
+        // A preset its loader refused is named with every failing field (round
+        // 12, 12.1) — it was a `skipping invalid preset (…)` warning string.
+        const note = { next: 'shrk packs contributions' };
         if (flagBool(args, 'json')) {
             process.stdout.write(asJson(presets.map((p) => ({
                 ...compact(p),
                 source: inspection.presetSources.get(p.id) ?? null,
             }))) + '\n');
+            await writeRejectedEntriesNote(inspection, [ContributionKind.Preset], { ...note, json: true });
             return 0;
         }
         process.stdout.write(header(`Presets (${presets.length})`));
@@ -52,6 +58,7 @@ export const presetsListCommand = {
                 process.stdout.write(`      tags=[${p.tags.join(', ')}]\n`);
             }
         }
+        await writeRejectedEntriesNote(inspection, [ContributionKind.Preset], note);
         return 0;
     },
 };
@@ -216,32 +223,10 @@ export const presetsExplainCommand = {
     },
 };
 function humanizeProfile(profile) {
-    // Map WorkspaceProfile string values back to a short natural-language
-    // clause. Keep the mapping local — adding new profiles to the engine
-    // shouldn't break this command; unknown profiles fall through verbatim.
-    const map = {
-        'has-typescript': 'uses TypeScript',
-        'has-bun': 'uses Bun',
-        'has-nx': 'is an Nx workspace',
-        'has-turborepo': 'is a Turborepo workspace',
-        'has-package-workspaces': 'uses package workspaces (npm/pnpm/yarn)',
-        'has-react': 'uses React',
-        'has-next': 'uses Next.js',
-        'has-angular': 'uses Angular',
-        'has-vue': 'uses Vue',
-        'has-nestjs': 'uses NestJS',
-        'has-mcp-sdk': 'depends on the MCP SDK',
-        'has-tests': 'has a test runner',
-        'has-eslint': 'uses ESLint',
-        'has-biome': 'uses Biome',
-        'has-github-actions': 'has GitHub Actions',
-        'is-library': 'is published as a library',
-        'is-service': 'runs as a service',
-        'is-monorepo': 'is a monorepo',
-        'is-frontend': 'is a frontend',
-        'is-backend': 'is a backend',
-    };
-    return map[profile] ?? profile;
+    // THE WorkspaceProfile label table (@shrkcrft/workspace) — the builtin
+    // `workspace` profile kind renders the same clause. Unknown ids fall
+    // through verbatim.
+    return describeWorkspaceProfile(profile);
 }
 export const presetsRecommendCommand = {
     name: 'recommend',

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

@@ -1 +1 @@
-{"version":3,"file":"profiles.command.d.ts","sourceRoot":"","sources":["../../src/commands/profiles.command.ts"],"names":[],"mappings":"AAWA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAUhC,eAAO,MAAM,mBAAmB,EAAE,eA4BjC,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,eAiChC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eAsBnC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eA8BnC,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,eAe7B,CAAC"}
+{"version":3,"file":"profiles.command.d.ts","sourceRoot":"","sources":["../../src/commands/profiles.command.ts"],"names":[],"mappings":"AAkBA,OAAO,EAGL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAyChC,eAAO,MAAM,mBAAmB,EAAE,eA+BjC,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,eA2ChC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eAsBnC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eAgCnC,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,eAiC7B,CAAC"}

package/dist/commands/profiles.command.js

@@ -1,59 +1,102 @@
 /**
- * `shrk profiles ...` — unified read-only surface for all pack-/local-
- * contributed profiles (migration, and future kinds).
+ * `shrk profiles ...` — unified read-only surface for every profile kind: the
+ * builtin `workspace` vocabulary (WorkspaceProfile ids, with this repo's
+ * detection) and pack-/local-contributed `migration` profiles.
  */
-import { findProfile, inspectSharkcraft, listProfileIssues, listProfiles, ProfileKind, } from '@shrkcrft/inspector';
-import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { ContributionKind, findProfile, formatReferenceKindDeclaration, inspectSharkcraft, isProfileKind, listProfileIssues, listProfiles, nearestIds, PROFILE_KIND_REFERENCE_KIND, ProfileKind, } from '@shrkcrft/inspector';
+import { flagBool, resolveCwd, } from "../command-registry.js";
+import { PositionalMode } from "../dispatch/positional-mode.js";
+import { usageExitFor } from "../exit-codes.js";
 import { asJson, header } from "../output/format-output.js";
-function parseKind(value) {
-    if (!value)
-        return undefined;
-    const known = Object.values(ProfileKind);
-    if (known.includes(value))
-        return value;
-    return undefined;
+import { writeRejectedEntriesNote } from "../output/rejected-entries-note.js";
+/** Every profile kind, in enum order — what `--kind` accepts. */
+const KNOWN_KINDS = Object.values(ProfileKind).join(', ');
+/**
+ * Parse `--kind`. An unknown (or valueless) kind is a usage error naming the
+ * known kinds — it used to be dropped silently, so `--kind bogus` listed every
+ * kind and a typo read as "no filter". Exit per THE usage split
+ * (`usageExitFor`: 2 on this non-verdict verb).
+ */
+function parseKind(args, commandPath) {
+    if (!args.flags.has('kind'))
+        return {};
+    const raw = args.flags.get('kind');
+    if (typeof raw === 'string' && isProfileKind(raw))
+        return { kind: raw };
+    process.stderr.write(`unknown --kind ${typeof raw === 'string' ? `"${raw}"` : '(no value)'} — known: ${KNOWN_KINDS}\n`);
+    return { exit: usageExitFor(commandPath) };
+}
+/**
+ * The empty state, from THE declaration table — so it can only name paths
+ * that really fill the kind (it used to say "contribute via packs:
+ * migrationProfileFiles, etc.", where "etc." named nothing and the local path
+ * went unmentioned).
+ */
+function emptyState(kind) {
+    if (!kind)
+        return '  (none)\n';
+    return `  (none — ${kind} profiles are declared via: ${formatReferenceKindDeclaration(PROFILE_KIND_REFERENCE_KIND[kind])})\n`;
+}
+function sourceLabel(e) {
+    const src = e.source === 'pack' ? `pack:${e.packageName ?? '?'}` : e.source;
+    return e.detected === true ? `${src} · detected` : src;
 }
 export const profilesListCommand = {
     name: 'list',
-    description: 'List all registered profiles (migration, ...).',
-    usage: 'shrk profiles list [--kind <kind>] [--json]',
+    description: 'List all registered profiles (workspace, migration).',
+    usage: 'shrk profiles list [--kind workspace|migration] [--json]',
     async run(args) {
+        const parsed = parseKind(args, 'profiles list');
+        if (parsed.exit !== undefined)
+            return parsed.exit;
+        const { kind } = parsed;
         const cwd = resolveCwd(args);
         const inspection = await inspectSharkcraft({ cwd });
-        const kind = parseKind(flagString(args, 'kind'));
         const entries = await listProfiles(inspection, kind ? { kind } : {});
+        // Only migration profiles are contributed (the workspace kind is builtin):
+        // one its loader refused is named (round 12, 12.1) — it read "Invalid
+        // migration profile at <file>; skipped." with no id, on `profiles doctor` only.
+        const migration = !kind || kind === ProfileKind.Migration;
+        const note = { next: 'shrk profiles doctor' };
         if (flagBool(args, 'json')) {
             process.stdout.write(asJson(entries) + '\n');
+            if (migration) {
+                await writeRejectedEntriesNote(inspection, [ContributionKind.MigrationProfile], { ...note, json: true });
+            }
             return 0;
         }
         process.stdout.write(header(`Profiles (${entries.length}${kind ? `, kind=${kind}` : ''})`));
-        if (entries.length === 0) {
-            process.stdout.write('  (none — contribute via packs: migrationProfileFiles, etc.)\n');
-            return 0;
-        }
+        if (entries.length === 0)
+            process.stdout.write(emptyState(kind));
         for (const e of entries) {
-            const src = e.source === 'pack' ? `pack:${e.packageName ?? '?'}` : e.source;
-            process.stdout.write(`  • ${e.kind.padEnd(18)} ${e.id.padEnd(24)} ${e.title}  [${src}]\n`);
+            process.stdout.write(`  • ${e.kind.padEnd(18)} ${e.id.padEnd(24)} ${e.title}  [${sourceLabel(e)}]\n`);
         }
+        if (migration)
+            await writeRejectedEntriesNote(inspection, [ContributionKind.MigrationProfile], note);
         return 0;
     },
 };
 export const profilesGetCommand = {
     name: 'get',
     description: 'Show one profile by id (and optional --kind).',
-    usage: 'shrk profiles get <id> [--kind <kind>] [--json]',
+    usage: 'shrk profiles get <id> [--kind workspace|migration] [--json]',
     async run(args) {
         const id = args.positional[0];
         if (!id) {
             process.stderr.write('Usage: shrk profiles get <id>\n');
             return 2;
         }
+        const parsed = parseKind(args, 'profiles get');
+        if (parsed.exit !== undefined)
+            return parsed.exit;
+        const { kind } = parsed;
         const cwd = resolveCwd(args);
         const inspection = await inspectSharkcraft({ cwd });
-        const kind = parseKind(flagString(args, 'kind'));
         const entry = await findProfile(inspection, id, kind);
         if (!entry) {
-            process.stderr.write(`Unknown profile "${id}"${kind ? ` (kind=${kind})` : ''}.\n`);
+            const pool = (await listProfiles(inspection, kind ? { kind } : {})).map((e) => e.id);
+            const near = nearestIds(id, pool, 3).map((n) => n.id);
+            process.stderr.write(`Unknown profile "${id}"${kind ? ` (kind=${kind})` : ''}.${near.length > 0 ? ` Did you mean: ${near.join(', ')}?` : ''}\n`);
             return 2;
         }
         if (flagBool(args, 'json')) {
@@ -65,6 +108,10 @@ export const profilesGetCommand = {
         if (entry.description)
             process.stdout.write(`  description   ${entry.description}\n`);
         process.stdout.write(`  source        ${entry.source}${entry.packageName ? ' (' + entry.packageName + ')' : ''}\n`);
+        if (entry.detected !== undefined) {
+            const reason = entry.payload?.reason;
+            process.stdout.write(`  detected      ${entry.detected ? `yes${reason ? ` — ${reason}` : ''}` : 'no (not detected in this repo)'}\n`);
+        }
         if (entry.sourceFile)
             process.stdout.write(`  sourceFile    ${entry.sourceFile}\n`);
         if (entry.tags && entry.tags.length > 0)
@@ -101,16 +148,19 @@ export const profilesDoctorCommand = {
 export const profilesSearchCommand = {
     name: 'search',
     description: 'Search registered profiles by free-text token across id / title / tags.',
-    usage: 'shrk profiles search <query> [--kind <kind>] [--json]',
+    usage: 'shrk profiles search <query> [--kind workspace|migration] [--json]',
     async run(args) {
         const query = args.positional[0];
         if (!query) {
             process.stderr.write('Usage: shrk profiles search <query>\n');
             return 2;
         }
+        const parsed = parseKind(args, 'profiles search');
+        if (parsed.exit !== undefined)
+            return parsed.exit;
+        const { kind } = parsed;
         const cwd = resolveCwd(args);
         const inspection = await inspectSharkcraft({ cwd });
-        const kind = parseKind(flagString(args, 'kind'));
         const all = await listProfiles(inspection, kind ? { kind } : {});
         const q = query.toLowerCase();
         const matches = all.filter((e) => {
@@ -132,8 +182,26 @@ export const profilesSearchCommand = {
 };
 export const profilesCommand = {
     name: 'profiles',
-    description: 'List / inspect pack-contributed profiles (migration, conventions, …).',
+    description: 'List / inspect profiles: the builtin workspace vocabulary (WorkspaceProfile ids, with detection) and migration profiles.',
     usage: 'shrk profiles list|get|doctor|search ...',
+    booleanFlags: new Set(['json']),
+    positionals: PositionalMode.None,
+    subverbs: [
+        { name: 'list', description: profilesListCommand.description, usage: profilesListCommand.usage },
+        {
+            name: 'get',
+            description: profilesGetCommand.description,
+            usage: profilesGetCommand.usage,
+            positionals: PositionalMode.Free,
+        },
+        { name: 'doctor', description: profilesDoctorCommand.description, usage: profilesDoctorCommand.usage },
+        {
+            name: 'search',
+            description: profilesSearchCommand.description,
+            usage: profilesSearchCommand.usage,
+            positionals: PositionalMode.Free,
+        },
+    ],
     async run(args) {
         const sub = args.positional[0];
         args.positional = args.positional.slice(1);

package/dist/commands/provenance.command.js

@@ -31,7 +31,7 @@ export const provenanceListCommand = {
         }
         process.stdout.write(header(`Provenance entries (${entries.length})`));
         if (entries.length === 0) {
-            process.stdout.write('  (ledger is empty — run a `shrk knowledge author --write-preview` to start it)\n');
+            process.stdout.write('  (ledger is empty — run a `shrk knowledge add --id <id> --write-preview` to start it)\n');
             return 0;
         }
         for (const e of entries) {

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

@@ -1 +1 @@
-{"version":3,"file":"quality.command.d.ts","sourceRoot":"","sources":["../../src/commands/quality.command.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAOhC,eAAO,MAAM,cAAc,EAAE,eAqE5B,CAAC;AAEF,YAAY,EAAE,cAAc,EAAE,CAAC"}
+{"version":3,"file":"quality.command.d.ts","sourceRoot":"","sources":["../../src/commands/quality.command.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA2ChC,eAAO,MAAM,cAAc,EAAE,eA+I5B,CAAC;AAEF,YAAY,EAAE,cAAc,EAAE,CAAC"}

package/dist/commands/quality.command.js

@@ -1,18 +1,72 @@
-import { buildQualityReport, inspectSharkcraft, } from '@shrkcrft/inspector';
+import { inspectSharkcraft, } from '@shrkcrft/inspector';
 import { flagBool, flagNumber, resolveCwd, } from "../command-registry.js";
+import { GLOBAL_FLAGS } from "../dispatch/global-flags.js";
+import { PositionalMode } from "../dispatch/positional-mode.js";
+import { ExitCode } from "../exit-codes.js";
+import { runQuality } from "../quality/run-quality.js";
+import { verdictLine } from "../gates/verdict-line.js";
 import { asJson, header, kv } from "../output/format-output.js";
+import { narrowToScope, prepare, resolveScope } from "./gates.command.js";
 // `quality baseline {create|compare|update|show|diff|prune|history}`
 // removed. The baseline machinery was hidden / unused; `doctor` and
 // `drift` cover the actionable cases.
+/** Flags `quality` accepts; anything else is a typo, not an opt-in. */
+const QUALITY_FLAGS = new Set([
+    'strict',
+    'ci',
+    'json',
+    'min-readiness',
+    'require-boundary-clean',
+    'require-drift-clean',
+    'require-agent-tests',
+    'require-context-tests',
+    'require-pack-signatures',
+    'changed-only',
+    'since',
+    'base',
+    'fail-fast',
+    'no-color',
+    'color',
+    // Every dispatcher global (THE list). Quality is a verdict verb, so its piped
+    // non-zero exit prints a note naming `--no-hints` as the way to silence it —
+    // rejecting that very flag with exit 3 would make the advice unfollowable.
+    ...GLOBAL_FLAGS,
+]);
+const STATUS_TAG = Object.freeze({
+    passed: 'OK   ',
+    failed: 'FAIL ',
+    skipped: 'SKIP ',
+    error: 'ERROR',
+});
 export const qualityCommand = {
     name: 'quality',
-    description: 'High-level quality gate: orchestrates doctor / boundaries / coverage / drift / context tests / agent tests / packs doctor. Designed to be the single command to run locally before opening a PR or in CI.',
-    usage: 'shrk [--cwd <dir>] quality [--strict] [--ci] [--min-readiness <n>] [--require-boundary-clean] [--require-drift-clean] [--require-agent-tests] [--require-context-tests] [--require-pack-signatures] [--json]',
+    description: 'THE "before you push" command: runs every configured gate — doctor / readiness / boundaries / coverage / drift / context+agent tests / packs doctor AND all seven data-defined rule planes — to completion, reporting EVERY failure with the command that reproduces it. Exhaustive by default so N independent failures cost one local run instead of N CI round-trips; `--fail-fast` opts into stop-at-first.',
+    usage: 'shrk [--cwd <dir>] quality [--changed-only | --since <ref>] [--fail-fast] [--strict] [--ci] [--min-readiness <n>] [--require-boundary-clean] [--require-drift-clean] [--require-agent-tests] [--require-context-tests] [--require-pack-signatures] [--json]',
+    booleanFlags: new Set([
+        'strict',
+        'ci',
+        'json',
+        'changed-only',
+        'fail-fast',
+        'require-boundary-clean',
+        'require-drift-clean',
+        'require-agent-tests',
+        'require-context-tests',
+        'require-pack-signatures',
+    ]),
+    // THE accepted set: the dispatcher refuses any other flag BEFORE `run` (a
+    // mistyped `--changed-only` would otherwise run the UNSCOPED form and exit 0
+    // as though the scoped check had passed). Round 11 moved this out of an
+    // inline guard here, so exactly one checker (`firstUnknownFlag`) judges it.
+    flags: QUALITY_FLAGS,
+    // Flag-driven: a bare token used to be ignored and the whole gate run.
+    positionals: PositionalMode.None,
     async run(args) {
         const cwd = resolveCwd(args);
         const strict = flagBool(args, 'strict');
         const ci = flagBool(args, 'ci');
         const wantJson = flagBool(args, 'json') || ci;
+        const failFast = flagBool(args, 'fail-fast');
         const inspection = await inspectSharkcraft({
             cwd,
             ...(flagBool(args, 'require-pack-signatures') ? { verifyPackSignatures: true } : {}),
@@ -29,41 +83,83 @@ export const qualityCommand = {
             ...(flagBool(args, 'require-context-tests') ? { requireContextTests: true } : {}),
             ...(flagBool(args, 'require-pack-signatures') ? { requirePackSignatures: true } : {}),
         };
-        const report = await buildQualityReport({ inspection, config, strict });
+        // The data-defined planes come through the SAME preparation `gates check`
+        // uses — a second copy of the config load + scope narrowing would
+        // eventually disagree with it, and the aggregate wired into pre-push is
+        // the copy nobody notices is wrong.
+        const prep = await prepare(args);
+        const scope = resolveScope(args, cwd);
+        if (scope.error) {
+            process.stderr.write(`Cannot scope to the changeset: ${scope.error}\n`);
+            return ExitCode.UsageError;
+        }
+        const allRules = prep.ok ? prep.value.rules : [];
+        const { selected } = narrowToScope(allRules, scope.files);
+        const outOfScope = allRules.filter((r) => !selected.includes(r));
+        const run = await runQuality({
+            inspection,
+            config,
+            strict,
+            failFast,
+            cwd,
+            gateRules: selected,
+            excludeDirs: prep.ok ? prep.value.excludeDirs : [],
+            ...(scope.files ? { changedFiles: scope.files } : {}),
+            skippedByScope: outOfScope,
+            ...(prep.ok ? { planeDiagnostics: prep.value.planeDiagnostics, rejectedRules: prep.value.rejectedRules } : {}),
+        });
+        // 0 clean · 1 a blocking gate failed · 2 ran but proved nothing (a gate
+        // errored, a required gate examined nothing, or a rule passed over part of
+        // its scope). Settled by the one coverage guard inside `runQuality`, so a
+        // skip nobody asked for is never masked by a passing sibling.
+        const exit = run.exit;
         if (wantJson) {
-            process.stdout.write(asJson(report) + '\n');
-            return report.overall === 'fail' ? 1 : 0;
+            process.stdout.write(asJson({ ...run, exitCode: exit }) + '\n');
+            return exit;
         }
-        process.stdout.write(header('SharkCraft quality gate'));
-        process.stdout.write(kv('overall', report.overall) + '\n');
-        process.stdout.write(kv('score', `${report.score}%`) + '\n');
-        process.stdout.write(kv('blockers', String(report.blockers)) + '\n');
-        process.stdout.write(kv('warnings', String(report.warnings)) + '\n\n');
-        for (const g of report.gates) {
-            const tag = !g.executed
-                ? 'SKIP '
-                : g.passed
-                    ? 'OK   '
-                    : g.blocking
-                        ? 'BLOCK'
-                        : 'WARN ';
-            process.stdout.write(`  ${tag}  ${g.label}\n`);
-            for (const n of g.notes)
-                process.stdout.write(`         ↳ ${n}\n`);
+        process.stdout.write(header('SharkCraft quality — every gate'));
+        process.stdout.write(kv('summary', `${run.passed} passed / ${run.failed + run.failedWarnings} failed` +
+            (run.failedWarnings > 0 ? ` (${run.failed} blocking, ${run.failedWarnings} advisory)` : '') +
+            ` / ${run.skipped} skipped` +
+            (run.errored > 0 ? ` / ${run.errored} could not run` : '')) + '\n');
+        if (run.scopedFiles !== undefined) {
+            process.stdout.write(kv('scope', `changed-only (${run.scopedFiles} file(s))`) + '\n');
+        }
+        if (run.failFast) {
+            process.stdout.write(kv('mode', '--fail-fast — stopped at the first blocking failure') + '\n');
         }
-        if (report.drift && (report.drift.counts.error > 0 || report.drift.counts.warning > 0)) {
-            process.stdout.write('\nDrift summary:\n');
-            process.stdout.write(`  errors=${report.drift.counts.error}  warnings=${report.drift.counts.warning}  info=${report.drift.counts.info}\n`);
-            for (const f of report.drift.findings.slice(0, 5)) {
-                process.stdout.write(`  • ${f.severity}: ${f.category} — ${f.message}\n`);
+        process.stdout.write('\n');
+        for (const item of run.items) {
+            // A gate that passed over PART of its scope is not "SKIP" (it ran); it
+            // is labelled for what it is. Its status stays `skipped` (accidental),
+            // so the verdict is unchanged: never a pass.
+            process.stdout.write(`  ${item.partial === true ? 'PART ' : STATUS_TAG[item.status]}  ${item.label}\n`);
+            for (const n of item.notes)
+                process.stdout.write(`         ↳ ${n}\n`);
+            // Every failure carries the command that reproduces it alone — the whole
+            // point of the aggregate is that the next step never needs re-derivation.
+            if (item.status === 'failed' || item.status === 'error') {
+                process.stdout.write(`         $ ${item.repro}\n`);
             }
         }
-        if (report.nextRecommendations.length > 0) {
-            process.stdout.write('\nRecommendations:\n');
-            for (const r of report.nextRecommendations)
-                process.stdout.write(`  • ${r}\n`);
+        if (run.diagnostics.length > 0) {
+            process.stdout.write('\nDiagnostics:\n');
+            for (const d of run.diagnostics)
+                process.stdout.write(`  • ${d}\n`);
+        }
+        process.stdout.write(`\nVerdict: ${run.verdict.toUpperCase()}  (exit ${exit})\n`);
+        if (run.verdict === 'pass' && run.failedWarnings > 0) {
+            process.stdout.write(`  ${run.failedWarnings} advisory gate(s) failed without blocking — re-run with --strict to make them block.\n`);
+        }
+        if (run.verdict === 'not-verified') {
+            process.stdout.write('  Nothing failed, but not everything was measured — an unmeasured gate is not a pass.\n');
+        }
+        // Which gates went unexamined, from the settled verdict itself.
+        if (exit !== ExitCode.VerifiedPass) {
+            const line = verdictLine(run, '');
+            if (line)
+                process.stdout.write(`  ${line}\n`);
         }
-        process.stdout.write(`\nVerdict: ${report.overall.toUpperCase()}\n`);
-        return report.overall === 'fail' ? 1 : 0;
+        return exit;
     },
 };

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

@@ -1,10 +1,26 @@
 import { type ICommandHandler } from '../command-registry.js';
+/**
+ * `shrk recommend` renders THE ranked list (`rankRecommendationCandidates`,
+ * inspector). It used to re-rank it: a CLI-only grounding prepend, a
+ * routing-hint "R1" promotion gated on create/build wording, and a separate
+ * "engine match" block — three code paths answering "what do I run first?",
+ * each with its own thresholds, none reachable from MCP or `shrk context`.
+ * Now every row, its attribution, `nextCommand`, the confidence and the
+ * coverage-gap verdict come from the one list; the CLI only gates rows by
+ * surface tier and re-picks `nextCommand` over what it renders, by THE rule.
+ */
 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.
+ * DX#2 — does the query read like planning (a planning verb leading the query
+ * or in slots 1–3)? A thin wrapper over THE query-intent classifier
+ * (`classifyQueryIntent`, inspector), kept for its callers; the planning verb
+ * set lives there now.
  */
-export declare function looksLikeCreateBuild(query: string): boolean;
 export declare function looksLikePlanning(query: string): boolean;
+/**
+ * Does the query read like create/build work? A thin wrapper over THE
+ * query-intent classifier — which now also refuses a create word used as a
+ * noun or adjective in a repair query ("fix the broken build").
+ */
+export declare function looksLikeCreateBuild(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":"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"}
+{"version":3,"file":"recommend.command.d.ts","sourceRoot":"","sources":["../../src/commands/recommend.command.ts"],"names":[],"mappings":"AAmBA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAQhC;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,EAAE,eA6K9B,CAAC;AAwGF;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE3D"}