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

package/dist/commands/surface.command.js

@@ -1,8 +1,15 @@
 import { flagBool, resolveCwd, } from "../command-registry.js";
+import { PositionalMode } from "../dispatch/positional-mode.js";
 import { asJson, header, kv, table } from "../output/format-output.js";
 import { loadSurfaceContext } from "../surface/load-surface-context.js";
 import { buildSurfaceSummary, findCommandInSummary, } from "../surface/surface-summary.js";
-import { CommandTier } from "./command-catalog.js";
+import { CommandAudience, CommandTier } from "./command-catalog.js";
+import { CommandDispatchKind } from "../surface/command-dispatch-kind.js";
+import { isBootstrapFamily, TierSource } from "../surface/tier.js";
+import { firstMatchingSelector, matchesSurfaceSelector } from "../surface/surface-selector.js";
+import { surfaceRefusalFor } from "../surface/not-enabled-error.js";
+import { SurfaceLayer } from "../surface/surface-layer.js";
+import { SurfaceRefusalReason } from "../surface/surface-refusal-reason.js";
 import { applySurfaceEdit, defaultConfigFile, planSurfaceEdit, } from "../surface/surface-config-writer.js";
 /**
  * `shrk surface`. Top-level introspection + opt-in management
@@ -13,33 +20,64 @@ import { applySurfaceEdit, defaultConfigFile, planSurfaceEdit, } from "../surfac
  *   - disable <command>     undo a prior enable
  *   - hide    <command>     hide an extended command from --help
  *   - unhide  <command>     reverse hide
- *   - reset                 clear surface.enabled + surface.hidden
+ *   - deny    <selector>    disable a command or a group (`<group> *`)
+ *   - allow   <selector>    reverse a deny
+ *   - reset                 clear surface.enabled + hidden + disabled
  *   - explain <command>     why this command has its current tier
  *   - profiles [get <id>]   list surface profiles (or show one)
+ *
+ * Every mutation edits the project config's OWN `surface{}` block (never the
+ * profile-merged view) and preserves its `profile`.
  */
 export const surfaceCommand = {
     name: 'surface',
+    positionals: PositionalMode.None,
+    subverbs: [
+        { name: 'list', description: 'Every command grouped by tier (the default).', usage: 'shrk surface list [--json]' },
+        { name: 'explain', description: 'Why a command has its current tier.', usage: 'shrk surface explain <command> [--json]', positionals: PositionalMode.Free },
+        { name: 'enable', description: 'Promote an experimental (or gated tool-maintenance) command to callable.', usage: 'shrk surface enable <command> [--write] [--json]', positionals: PositionalMode.Free },
+        { name: 'disable', description: 'Undo a prior enable.', usage: 'shrk surface disable <command> [--write] [--json]', positionals: PositionalMode.Free },
+        { name: 'hide', description: 'Hide an extended command from --help.', usage: 'shrk surface hide <command> [--write] [--json]', positionals: PositionalMode.Free },
+        { name: 'unhide', description: 'Reverse a hide.', usage: 'shrk surface unhide <command> [--write] [--json]', positionals: PositionalMode.Free },
+        {
+            name: 'deny',
+            description: 'Disable a command or a group (`<group> *`) here: not callable (exit 78), absent from --help.',
+            usage: "shrk surface deny <command|'<group> *'> [--write] [--json]",
+            positionals: PositionalMode.Free,
+        },
+        {
+            name: 'allow',
+            description: 'Reverse a deny: remove the selector from surface.disabled.',
+            usage: "shrk surface allow <command|'<group> *'> [--write] [--json]",
+            positionals: PositionalMode.Free,
+        },
+        { name: 'reset', description: 'Clear surface.enabled + surface.hidden + surface.disabled.', usage: 'shrk surface reset [--write] [--json]' },
+        { name: 'profiles', description: 'List the surface profiles, or show one.', usage: 'shrk surface profiles [get <id>] [--json]', positionals: PositionalMode.Free },
+    ],
     description: 'Inspect or change the adaptive command surface (core / extended / experimental tiers).',
-    usage: 'shrk surface <list|enable|disable|hide|unhide|reset|explain|profiles> [name] [--write] [--json]',
+    usage: 'shrk surface <list|enable|disable|hide|unhide|deny|allow|reset|explain|profiles> [name] [--write] [--json]',
     async run(args) {
         const [verb, ...rest] = args.positional;
         const json = flagBool(args, 'json');
         const write = flagBool(args, 'write');
         const cwd = resolveCwd(args);
+        // A multi-word path (`surface enable docs check`) names ONE command.
+        const target = rest.length > 0 ? rest.join(' ') : undefined;
         switch (verb) {
             case undefined:
             case 'list':
                 return await runList({ cwd, json });
             case 'explain':
-                return await runExplain({ cwd, json, target: rest[0] });
+                return await runExplain({ cwd, json, target });
             case 'enable':
-                return await runMutate({ cwd, json, write, target: rest[0], op: 'enable' });
             case 'disable':
-                return await runMutate({ cwd, json, write, target: rest[0], op: 'disable' });
             case 'hide':
-                return await runMutate({ cwd, json, write, target: rest[0], op: 'hide' });
             case 'unhide':
-                return await runMutate({ cwd, json, write, target: rest[0], op: 'unhide' });
+                return await runMutate({ cwd, json, write, target, op: verb });
+            case 'deny':
+                return await runDeny({ cwd, json, write, target });
+            case 'allow':
+                return await runAllow({ cwd, json, write, target });
             case 'reset':
                 return await runReset({ cwd, json, write });
             case 'profiles':
@@ -50,10 +88,19 @@ export const surfaceCommand = {
         }
     },
 };
+/** The project config's OWN `surface{}` block — what every mutation edits. */
+function rawSurface(loaded) {
+    return loaded.inspection.config?.surface ?? undefined;
+}
+function configFileOf(loaded, cwd) {
+    return (loaded.inspection.configFile ??
+        defaultConfigFile(loaded.inspection.sharkcraftDir ?? `${cwd}/sharkcraft`));
+}
+function allViews(summary) {
+    return [...summary.tiers.core, ...summary.tiers.extended, ...summary.tiers.experimental];
+}
 async function runProfiles(opts) {
-    const { context, inspection, availableProfiles, activeProfile } = await loadSurfaceContext({ cwd: opts.cwd });
-    void inspection;
-    void context;
+    const { availableProfiles, activeProfile } = await loadSurfaceContext({ cwd: opts.cwd });
     if (!opts.sub || opts.sub === 'list') {
         if (opts.json) {
             process.stdout.write(asJson({
@@ -72,7 +119,8 @@ async function runProfiles(opts) {
             const src = p.source === 'pack' ? ` (pack: ${p.pack})` : ` (builtin)`;
             const hiddenCount = p.hidden?.length ?? 0;
             const enabledCount = p.enabled?.length ?? 0;
-            process.stdout.write(`  ${tag} ${p.id.padEnd(14)} ${src.padEnd(20)} hides=${hiddenCount}, enables=${enabledCount}\n`);
+            const disabledCount = p.disabled?.length ?? 0;
+            process.stdout.write(`  ${tag} ${p.id.padEnd(14)} ${src.padEnd(20)} hides=${hiddenCount}, enables=${enabledCount}, disables=${disabledCount}\n`);
             process.stdout.write(`      ${p.description}\n`);
         }
         return 0;
@@ -96,6 +144,7 @@ async function runProfiles(opts) {
         process.stdout.write(kv('source', found.source + (found.pack ? ` (${found.pack})` : '')) + '\n');
         process.stdout.write(kv('hidden', String(found.hidden?.length ?? 0)) + '\n');
         process.stdout.write(kv('enabled', String(found.enabled?.length ?? 0)) + '\n');
+        process.stdout.write(kv('disabled', String(found.disabled?.length ?? 0)) + '\n');
         if (found.hidden && found.hidden.length > 0) {
             process.stdout.write('\nHidden:\n');
             for (const h of found.hidden)
@@ -106,6 +155,11 @@ async function runProfiles(opts) {
             for (const e of found.enabled)
                 process.stdout.write(`  + ${e}\n`);
         }
+        if (found.disabled && found.disabled.length > 0) {
+            process.stdout.write('\nDisabled:\n');
+            for (const d of found.disabled)
+                process.stdout.write(`  x ${d}\n`);
+        }
         return 0;
     }
     process.stderr.write(`Unknown subcommand: surface profiles ${opts.sub}\nUse: list, get <id>\n`);
@@ -115,22 +169,31 @@ async function runList({ cwd, json }) {
     const { context, activeProfile } = await loadSurfaceContext({ cwd });
     const summary = buildSurfaceSummary(context);
     if (json) {
-        process.stdout.write(asJson({ ...summary, activeProfile: activeProfile?.id ?? null }) + '\n');
+        process.stdout.write(asJson({ ...summary, activeProfile: activeProfile?.id ?? null, isToolRepo: context.isToolRepo }) + '\n');
         return 0;
     }
-    renderSurfaceText(summary, activeProfile?.id);
+    renderSurfaceText(summary, activeProfile?.id, context.isToolRepo);
     return 0;
 }
-function renderSurfaceText(summary, activeProfileId) {
+function renderSurfaceText(summary, activeProfileId, isToolRepo) {
     process.stdout.write(header('Command surface'));
     process.stdout.write(kv('schema', summary.schema) + '\n');
     process.stdout.write(kv('hash', summary.hash) + '\n');
     process.stdout.write(kv('profile', activeProfileId ?? '(none — sharkcraft.config.ts surface.profile not set)') + '\n');
+    process.stdout.write(kv('host', isToolRepo
+        ? "SharkCraft's own repository (tool-maintenance commands callable)"
+        : 'not the SharkCraft repository (tool-maintenance commands gated)') + '\n');
     process.stdout.write(kv('core', String(summary.totals.core)) + '\n');
     process.stdout.write(kv('extended', String(summary.totals.extended)) + '\n');
     process.stdout.write(kv('experimental', String(summary.totals.experimental)) + '\n');
     process.stdout.write(kv('visible in --help', String(summary.totals.visible)) + '\n');
     process.stdout.write(kv('callable', String(summary.totals.callable)) + '\n');
+    process.stdout.write(kv('uncatalogued', String(summary.totals.uncatalogued)) + '\n');
+    if (!summary.registryBacked) {
+        // Only reachable from a direct engine call: never pass a partial listing
+        // off as the dispatch table.
+        process.stdout.write(kv('inventory', 'PARTIAL — catalog rows only (no command registry); run `shrk surface list`') + '\n');
+    }
     process.stdout.write('\n');
     printBucket('core', summary.tiers.core);
     printBucket('extended', summary.tiers.extended);
@@ -148,25 +211,46 @@ function printBucket(label, items) {
         process.stdout.write('  (empty)\n');
         return;
     }
+    // command | what it does | who it is for | flags. The tier `detail` stays in
+    // `surface explain` and `--json`: it used to be the only text column, and
+    // for every extended row it was the same placeholder sentence. The audience
+    // column answers "is this for me?" next to "does this exist?".
     const rows = items.map((c) => {
         const flags = [];
         if (c.hidden)
             flags.push('hidden');
         if (c.enabled)
             flags.push('enabled');
+        if (c.disabled)
+            flags.push('disabled');
         if (!c.callable)
             flags.push('gated');
+        if (!c.catalogued && c.dispatch !== CommandDispatchKind.Meta)
+            flags.push('uncatalogued');
+        if (c.audience.includes(CommandAudience.ToolMaintenance))
+            flags.push('tool-maintenance');
         if (c.pack)
             flags.push(`pack:${c.pack}`);
-        return [
-            '  ' + c.command,
-            c.source,
-            flags.join(','),
-            c.detail ?? '',
-        ];
+        return ['  ' + c.command, oneLineDescription(c.description), c.audience.join(','), flags.join(',')];
     });
     process.stdout.write(table(rows) + '\n');
 }
+/** First sentence of a description, at most 72 characters. */
+function oneLineDescription(description) {
+    const flat = description.replace(/\s+/g, ' ').trim();
+    const dot = flat.search(/[.!?](\s|$)/);
+    const sentence = dot > 0 ? flat.slice(0, dot + 1) : flat;
+    return sentence.length > 72 ? sentence.slice(0, 71).trimEnd() + '…' : sentence;
+}
+/** Why a view has its tier, when the resolver attached no detail. */
+function tierExplanation(view) {
+    if (view.detail)
+        return view.detail;
+    if (view.source === TierSource.Default) {
+        return `${view.tier} — default tier (not in a spine pipeline, not pack-contributed)`;
+    }
+    return undefined;
+}
 async function runExplain({ cwd, json, target }) {
     if (!target) {
         process.stderr.write('Usage: shrk surface explain <command>\n');
@@ -185,27 +269,45 @@ async function runExplain({ cwd, json, target }) {
         process.stderr.write(`Unknown command: ${target}\n`);
         return 2;
     }
-    // Attribute the hide/enable to a profile when one is active.
-    const hiddenByProfile = !!activeProfile?.hidden?.includes(target);
-    const enabledByProfile = !!activeProfile?.enabled?.includes(target);
+    // Attribute the hide/enable to a profile when one is active (the same
+    // selector matcher the resolver uses — `bundle *` names `bundle list`).
+    const hiddenByProfile = firstMatchingSelector(activeProfile?.hidden, [view.command]) !== undefined;
+    const enabledByProfile = firstMatchingSelector(activeProfile?.enabled, [view.command]) !== undefined;
+    const disabledByProfile = view.deniedBy?.origin === SurfaceLayer.Profile;
     if (json) {
         process.stdout.write(asJson({
             ...view,
             activeProfile: activeProfile?.id ?? null,
+            isToolRepo: context.isToolRepo,
             hiddenByProfile,
             enabledByProfile,
+            disabledByProfile,
         }) + '\n');
         return 0;
     }
-    process.stdout.write(header(`Surface — ${target}`));
+    process.stdout.write(header(`Surface — ${view.command}`));
+    process.stdout.write(kv('description', view.description) + '\n');
+    if (view.usage)
+        process.stdout.write(kv('usage', view.usage) + '\n');
+    process.stdout.write(kv('dispatch', view.dispatch) + '\n');
+    process.stdout.write(kv('catalogued', view.catalogued
+        ? 'yes'
+        : context.isToolRepo
+            ? 'no — run `shrk commands doctor`'
+            : "no — missing from SharkCraft's command catalog (a SharkCraft catalog gap)") + '\n');
+    process.stdout.write(kv('audience', view.audience.join(', ')) + '\n');
+    if (view.variants.length > 0)
+        process.stdout.write(kv('variants', view.variants.join(' · ')) + '\n');
     process.stdout.write(kv('tier', view.tier) + '\n');
     process.stdout.write(kv('source', view.source) + '\n');
-    if (view.detail)
-        process.stdout.write(kv('detail', view.detail) + '\n');
+    const explanation = tierExplanation(view);
+    if (explanation)
+        process.stdout.write(kv('detail', explanation) + '\n');
     process.stdout.write(kv('callable', String(view.callable)) + '\n');
     process.stdout.write(kv('visible-in-help', String(view.visibleInHelp)) + '\n');
     process.stdout.write(kv('hidden-by-config', String(view.hidden)) + '\n');
     process.stdout.write(kv('enabled-by-config', String(view.enabled)) + '\n');
+    process.stdout.write(kv('disabled', String(view.disabled)) + '\n');
     if (view.pack)
         process.stdout.write(kv('pack', view.pack) + '\n');
     if (activeProfile) {
@@ -214,12 +316,22 @@ async function runExplain({ cwd, json, target }) {
             process.stdout.write(kv('hidden-by-profile', 'yes — profile hides this from --help') + '\n');
         if (enabledByProfile)
             process.stdout.write(kv('enabled-by-profile', 'yes — profile turns this on') + '\n');
+        if (disabledByProfile)
+            process.stdout.write(kv('disabled-by-profile', 'yes — profile disables this') + '\n');
     }
     if (view.tier === CommandTier.Experimental && !view.callable) {
+        const refusal = surfaceRefusalFor(view);
         process.stdout.write('\nWhy gated: ' + (view.detail ?? 'experimental — opt-in required.') + '\n');
-        process.stdout.write('\nTo enable:\n');
-        process.stdout.write(`  $ shrk surface enable ${target} --write\n`);
-        if (activeProfile) {
+        if (refusal.reasonCode === SurfaceRefusalReason.ToolMaintenance) {
+            process.stdout.write("It maintains SharkCraft itself (its docs set, examples, release artifacts or command catalog), so it does not apply to this repository. Invoking it exits 78 — this is not a check failure.\n");
+        }
+        const remedy = refusal.enableCommand.endsWith('--write') ? refusal.enableCommand : `${refusal.enableCommand} --write`;
+        const allowAgain = refusal.reasonCode === SurfaceRefusalReason.Disabled && view.deniedBy?.origin === SurfaceLayer.Config;
+        process.stdout.write(allowAgain ? '\nTo allow it again:\n' : '\nTo enable:\n');
+        process.stdout.write(`  $ ${remedy}\n`);
+        // Another profile only helps when the profile is what gates it.
+        const profileGated = refusal.reasonCode === SurfaceRefusalReason.Experimental || view.deniedBy?.origin === SurfaceLayer.Profile;
+        if (activeProfile && profileGated) {
             process.stdout.write(`\nOr switch profile (current: ${activeProfile.id}):\n`);
             process.stdout.write('  $ shrk surface profiles list\n');
         }
@@ -238,8 +350,8 @@ async function runMutate({ cwd, json, write, target, op }) {
         process.stderr.write(`Usage: shrk surface ${op} <command> [--write]\n`);
         return 2;
     }
-    const { context, inspection } = await loadSurfaceContext({ cwd });
-    const summary = buildSurfaceSummary(context);
+    const loaded = await loadSurfaceContext({ cwd });
+    const summary = buildSurfaceSummary(loaded.context);
     const view = findCommandInSummary(summary, target);
     if (!view) {
         process.stderr.write(`Unknown command: ${target}\n`);
@@ -250,22 +362,10 @@ async function runMutate({ cwd, json, write, target, op }) {
         process.stderr.write(refusal + '\n');
         return 2;
     }
-    const edit = toEdit(op, target);
-    const configFile = inspection.configFile ?? defaultConfigFile(inspection.sharkcraftDir ?? `${cwd}/sharkcraft`);
-    const diff = planSurfaceEdit(configFile, context.surfaceConfig, [edit]);
-    if (json) {
-        process.stdout.write(asJson({ diff, willWrite: write }) + '\n');
-    }
-    else {
-        renderDiffText(diff, write);
-    }
-    if (!write)
-        return 0;
-    const result = applySurfaceEdit(diff);
-    if (!json) {
-        process.stdout.write(`\nWrote ${result.configFile} (${result.edits.length} edit${result.edits.length === 1 ? '' : 's'}).\n`);
-    }
-    return 0;
+    // The canonical path (never a flag variant, which no selector would match).
+    const edit = toEdit(op, view.command);
+    const diff = planSurfaceEdit(configFileOf(loaded, cwd), rawSurface(loaded), [edit]);
+    return await emitDiff(diff, { json, write });
 }
 function refuseIfInvalid(op, view) {
     if (view.tier === CommandTier.Core && (op === 'disable' || op === 'hide')) {
@@ -274,6 +374,10 @@ function refuseIfInvalid(op, view) {
     if (op === 'hide' && view.tier === CommandTier.Experimental) {
         return `Cannot hide an experimental command (${view.command}); use disable instead.`;
     }
+    if (op === 'enable' && view.deniedBy?.origin === SurfaceLayer.Config) {
+        return (`${view.command} is disabled by surface.disabled ('${view.deniedBy.selector}'), which wins over surface.enabled. ` +
+            `Run: shrk surface allow '${view.deniedBy.selector}' --write`);
+    }
     if (op === 'enable' && view.tier !== CommandTier.Experimental && !view.enabled) {
         return `Refusing no-op: ${view.command} is not experimental (tier=${view.tier}).`;
     }
@@ -297,17 +401,92 @@ function toEdit(op, command) {
             return { field: 'hidden', command, operation: 'remove' };
     }
 }
+/** A command a deny can never reach: Core (bootstrap / spine / meta) or a bootstrap subverb. */
+function isDenyProtected(view) {
+    return view.tier === CommandTier.Core || isBootstrapFamily(view.command);
+}
+/**
+ * `surface deny <selector>` — add an exact path or `<group> *` to
+ * `surface.disabled`. Refused (2) when the selector names no command, only
+ * core commands, or is already denied.
+ */
+async function runDeny({ cwd, json, write, target }) {
+    if (!target) {
+        process.stderr.write("Usage: shrk surface deny <command|'<group> *'> [--write]\n");
+        return 2;
+    }
+    const loaded = await loadSurfaceContext({ cwd });
+    const summary = buildSurfaceSummary(loaded.context);
+    const matched = allViews(summary).filter((v) => matchesSurfaceSelector(target, v.command));
+    if (matched.length === 0) {
+        process.stderr.write(`'${target}' names no command. A group selector is '<group> *' (e.g. 'bundle *'); ` +
+            'run `shrk surface list` for the paths.\n');
+        return 2;
+    }
+    const protectedViews = matched.filter(isDenyProtected);
+    const deniable = matched.filter((v) => !isDenyProtected(v));
+    if (deniable.length === 0) {
+        process.stderr.write(`Cannot disable a core command (${matched.map((v) => v.command).join(', ')}).\n`);
+        return 2;
+    }
+    const raw = rawSurface(loaded);
+    if ((raw?.disabled ?? []).includes(target)) {
+        process.stderr.write(`Refusing no-op: '${target}' is already in surface.disabled.\n`);
+        return 2;
+    }
+    const diff = planSurfaceEdit(configFileOf(loaded, cwd), raw, [
+        { field: 'disabled', command: target, operation: 'add' },
+    ]);
+    const notes = [`Denies ${deniable.length} command(s): ${previewList(deniable.map((v) => v.command))}`];
+    if (protectedViews.length > 0) {
+        notes.push(`Stays callable (core / bootstrap): ${previewList(protectedViews.map((v) => v.command))}`);
+    }
+    return await emitDiff(diff, {
+        json,
+        write,
+        notes,
+        extra: { denies: deniable.map((v) => v.command), protected: protectedViews.map((v) => v.command) },
+    });
+}
+/** `surface allow <selector>` — remove a selector from the config's `surface.disabled`. */
+async function runAllow({ cwd, json, write, target }) {
+    if (!target) {
+        process.stderr.write("Usage: shrk surface allow <command|'<group> *'> [--write]\n");
+        return 2;
+    }
+    const loaded = await loadSurfaceContext({ cwd });
+    const raw = rawSurface(loaded);
+    const configDisabled = raw?.disabled ?? [];
+    if (!configDisabled.includes(target)) {
+        const profile = loaded.activeProfile;
+        if (profile?.disabled?.includes(target)) {
+            process.stderr.write(`'${target}' is disabled by the '${profile.id}' surface profile, not by surface.disabled. ` +
+                'Override it for one command with `shrk surface enable "<command>" --write`, or choose another profile.\n');
+            return 2;
+        }
+        process.stderr.write(`Refusing no-op: '${target}' is not in surface.disabled` +
+            (configDisabled.length > 0 ? ` (entries: ${configDisabled.join(', ')}).\n` : '.\n'));
+        return 2;
+    }
+    const diff = planSurfaceEdit(configFileOf(loaded, cwd), raw, [
+        { field: 'disabled', command: target, operation: 'remove' },
+    ]);
+    return await emitDiff(diff, { json, write });
+}
 async function runReset({ cwd, json, write }) {
-    const { context, inspection } = await loadSurfaceContext({ cwd });
+    const loaded = await loadSurfaceContext({ cwd });
+    const raw = rawSurface(loaded);
     const edits = [];
-    for (const name of context.surfaceConfig?.enabled ?? []) {
+    for (const name of raw?.enabled ?? []) {
         edits.push({ field: 'enabled', command: name, operation: 'remove' });
     }
-    for (const name of context.surfaceConfig?.hidden ?? []) {
+    for (const name of raw?.hidden ?? []) {
         edits.push({ field: 'hidden', command: name, operation: 'remove' });
     }
-    const configFile = inspection.configFile ?? defaultConfigFile(inspection.sharkcraftDir ?? `${cwd}/sharkcraft`);
-    const diff = planSurfaceEdit(configFile, context.surfaceConfig, edits);
+    for (const name of raw?.disabled ?? []) {
+        edits.push({ field: 'disabled', command: name, operation: 'remove' });
+    }
+    const diff = planSurfaceEdit(configFileOf(loaded, cwd), raw, edits);
     if (json) {
         process.stdout.write(asJson({ diff, willWrite: write }) + '\n');
     }
@@ -321,7 +500,23 @@ async function runReset({ cwd, json, write }) {
         process.stdout.write(`\nWrote ${diff.configFile} (reset).\n`);
     return 0;
 }
-function renderDiffText(diff, willWrite) {
+/** Print (text or JSON) a planned edit, and apply it under `--write`. */
+async function emitDiff(diff, opts) {
+    if (opts.json) {
+        process.stdout.write(asJson({ diff, willWrite: opts.write, ...(opts.extra ?? {}) }) + '\n');
+    }
+    else {
+        renderDiffText(diff, opts.write, opts.notes ?? []);
+    }
+    if (!opts.write)
+        return 0;
+    const result = applySurfaceEdit(diff);
+    if (!opts.json) {
+        process.stdout.write(`\nWrote ${result.configFile} (${result.edits.length} edit${result.edits.length === 1 ? '' : 's'}).\n`);
+    }
+    return 0;
+}
+function renderDiffText(diff, willWrite, notes = []) {
     process.stdout.write(header('Surface config edit'));
     process.stdout.write(kv('configFile', diff.configFile) + '\n');
     process.stdout.write(kv('edits', String(diff.edits.length)) + '\n');
@@ -329,7 +524,14 @@ function renderDiffText(diff, willWrite) {
         const sign = edit.operation === 'add' ? '+' : '-';
         process.stdout.write(`  ${sign} surface.${edit.field}: ${edit.command}\n`);
     }
+    for (const note of notes)
+        process.stdout.write(`${note}\n`);
     if (!willWrite) {
         process.stdout.write('\nDry run. Pass --write to apply.\n');
     }
 }
+/** At most eight paths, then `(+N more)`. */
+function previewList(paths) {
+    const head = paths.slice(0, 8).join(', ');
+    return paths.length > 8 ? `${head} (+${paths.length - 8} more)` : head;
+}

package/dist/commands/task-context.command.js

@@ -455,7 +455,7 @@ async function collectLikelyFilesV2(input) {
     if (generatedFiles.length > 0)
         suggestedFirstCommands.push('shrk generated report');
     if (stabilityWarnings.length > 0)
-        suggestedFirstCommands.push('shrk stability map');
+        suggestedFirstCommands.push('shrk ingest report');
     if (suggestedFirstCommands.length === 0)
         suggestedFirstCommands.push('shrk task "' + task + '"');
     return {

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

@@ -1 +1 @@
-{"version":3,"file":"task.command.d.ts","sourceRoot":"","sources":["../../src/commands/task.command.ts"],"names":[],"mappings":"AAiBA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAkEhC,eAAO,MAAM,WAAW,EAAE,eAgRzB,CAAC"}
+{"version":3,"file":"task.command.d.ts","sourceRoot":"","sources":["../../src/commands/task.command.ts"],"names":[],"mappings":"AAkBA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAqEhC,eAAO,MAAM,WAAW,EAAE,eA+RzB,CAAC"}

package/dist/commands/task.command.js

@@ -1,6 +1,8 @@
 import { buildKnowledgeStaleReport, buildScaffoldCoverageReport, buildSpecList, buildTaskPacket, buildTemplateDriftReport, buildUncertaintySummary, decomposeTask, entrypointBanner, inspectSharkcraft, lintKnowledge, renderScaffoldCoverageMarkdown, renderUncertaintyText, runDoctor, } from '@shrkcrft/inspector';
 import { SpecStatus } from '@shrkcrft/generator';
+import { templateRemainderSummary } from '@shrkcrft/templates';
 import { flagBool, flagNumber, flagList, resolveCwd, } from "../command-registry.js";
+import { PositionalMode } from "../dispatch/positional-mode.js";
 import { asJson, header, kv } from "../output/format-output.js";
 import { buildTaskNextReport } from "../task-next/task-next-ranker.js";
 /**
@@ -21,7 +23,8 @@ function compactTaskPacket(p) {
         })),
         relevantRules: p.relevantRules.map((r) => ({ id: r.id, title: r.title })),
         relevantPaths: p.relevantPaths.map((r) => ({ id: r.id, title: r.title })),
-        relevantTemplates: p.relevantTemplates.map((t) => ({ id: t.id, name: t.name })),
+        // A template's declared remainder rides on its row (R11-GAP-7).
+        relevantTemplates: p.relevantTemplates.map((t) => ({ id: t.id, name: t.name, ...templateRemainderSummary(t) })),
         recommendedMcpTools: p.recommendedMcpTools,
         recommendedCliCommands: p.recommendedCliCommands,
         forbiddenActions: p.forbiddenActions,
@@ -56,6 +59,7 @@ function minimalTaskPacket(p) {
             id: t.id,
             name: t.name,
             ...(t.appliesWhen.length > 0 ? { appliesWhen: t.appliesWhen } : {}),
+            ...templateRemainderSummary(t),
         })),
         verificationCommands: p.verificationCommands,
         recommendedMcpTools: p.recommendedMcpTools,
@@ -64,6 +68,16 @@ function minimalTaskPacket(p) {
 }
 export const taskCommand = {
     name: 'task',
+    // The positionals are the free-form task (`task "add a thing"`).
+    positionals: PositionalMode.Free,
+    subverbs: [
+        {
+            name: 'decompose',
+            description: 'Decompose a task into ranked subtasks.',
+            usage: 'shrk task decompose "<task>" [--json]',
+            positionals: PositionalMode.Free,
+        },
+    ],
     description: 'Build an AI-ready task packet: relevant context, action hints, recommended pipeline, templates, paths, verification commands. Defaults to a compact packet (top-5 rules / top-3 templates / 5 hints per field) to keep agent token cost low. Pass `--full` to get the unrestricted packet, or `--next` to skip the packet and survey the workspace for the highest-leverage next action.',
     usage: 'shrk [--cwd <dir>] task "<task>" [--max-tokens 4000] [--scope x,y] [--explain-ranking] [--full] [--json]   OR   shrk task --next [--json]',
     async run(args) {
@@ -73,6 +87,8 @@ export const taskCommand = {
         // command. Pure ranker over existing JSON outputs.
         if (flagBool(args, 'next')) {
             const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
+            // Warm before the stale report resolves any id (CLAUDE.md "Warm before you resolve").
+            await (await import("../surface/cli-command-resolver.js")).warmCliReferenceRegistries(inspection);
             const [doctorRes, staleRes, driftRes] = await Promise.all([
                 runDoctor(inspection),
                 Promise.resolve(buildKnowledgeStaleReport(inspection)),
@@ -259,6 +275,11 @@ export const taskCommand = {
             process.stdout.write('\nRelevant templates:\n');
             for (const t of packet.relevantTemplates.slice(0, 6)) {
                 process.stdout.write(`  • ${t.id}  ${t.name}\n`);
+                const remainder = templateRemainderSummary(t);
+                if (remainder.notScaffolded)
+                    process.stdout.write(`      not scaffolded: ${remainder.notScaffolded.join(', ')}\n`);
+                if (remainder.manualSteps)
+                    process.stdout.write(`      manual steps: ${remainder.manualSteps.length}\n`);
             }
         }
         if (packet.suggestedGen) {

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

@@ -19,6 +19,10 @@ export declare const templatesAddCommand: ICommandHandler;
  * Distinct from `templates lint` (which surfaces test-style findings)
  * and `templates drift` (which compares declared vs. rendered output)
  * by combining them with a clean/dirty verdict + per-template summary.
+ * Lint is READ, never re-derived: a template `templates lint` fails can
+ * never read "Clean" here. Settled against coverage — 0 templates, or a
+ * template whose `changes()` threw with sample variables (its operations
+ * were never checked), is NOT VERIFIED (2), never a pass.
  */
 export declare const templatesDoctorCommand: ICommandHandler;
 export declare const templatesUpdateCommand: ICommandHandler;

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

@@ -1 +1 @@
-{"version":3,"file":"templates.command.d.ts","sourceRoot":"","sources":["../../src/commands/templates.command.ts"],"names":[],"mappings":"AAyBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAUhC,eAAO,MAAM,oBAAoB,EAAE,eA6DlC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAmBlC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eA+CjC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAgBpC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAiDrC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eAWnC,CAAC;AAgNF,eAAO,MAAM,2BAA2B,EAAE,eA+BzC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eAOnC,CAAC;AA2GF,eAAO,MAAM,wBAAwB,EAAE,eA+FtC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,mBAAmB,EAAE,eAKjC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,EAAE,eAyCpC,CAAC;AAwHF,eAAO,MAAM,sBAAsB,EAAE,eAiKpC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAkEpC,CAAC"}
+{"version":3,"file":"templates.command.d.ts","sourceRoot":"","sources":["../../src/commands/templates.command.ts"],"names":[],"mappings":"AAiCA,OAAO,EAOL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAUhC,eAAO,MAAM,oBAAoB,EAAE,eA6DlC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eA0BlC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eAoDjC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAmBpC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAmDrC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eAWnC,CAAC;AAmNF,eAAO,MAAM,2BAA2B,EAAE,eAgCzC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eAOnC,CAAC;AA2GF,eAAO,MAAM,wBAAwB,EAAE,eA+FtC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,mBAAmB,EAAE,eAKjC,CAAC;AAiBF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB,EAAE,eAoFpC,CAAC;AAwHF,eAAO,MAAM,sBAAsB,EAAE,eAiKpC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAkEpC,CAAC"}