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

package/dist/commands/templates.command.js

@@ -1,11 +1,16 @@
 import { mkdirSync, writeFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
-import { AssetKind, AssetProvenanceOperation, AssetProvenanceSource, buildTemplateAuthoringPreview, buildTemplateDriftReport, inspectSharkcraft, recordProvenance, TemplateAuthoringOperation, TemplateDriftStatus, } from '@shrkcrft/inspector';
+import { AssetKind, AssetProvenanceOperation, AssetProvenanceSource, buildTemplateAuthoringPreview, buildTemplateDriftReport, ContributionKind, inspectSharkcraft, lintTemplates, recordProvenance, TemplateAuthoringOperation, TemplateDriftStatus, } from '@shrkcrft/inspector';
+import { ALLOW_EMPTY_FLAG, allowEmptyValve } from "../gates/allow-empty.js";
+import { settleVerdict } from "../gates/settle-verdict.js";
+import { templateRegistryCoverage } from "../gates/template-registry-coverage.js";
+import { verdictLine } from "../gates/verdict-line.js";
+import { writeRejectedEntriesNote } from "../output/rejected-entries-note.js";
 import { detectAuthoringSource, multiFlagValues, writeAuthoringDrafts, } from "../authoring/authoring-kit.js";
 import { applyTemplateUpdate } from "../asset-preview/apply-template-update.js";
-import { previewTemplate } from '@shrkcrft/templates';
+import { previewTemplate, templateRemainderFields, templateRemainderLines } from '@shrkcrft/templates';
 import { buildNameVariables } from '@shrkcrft/generator';
-import { flagBool, flagList, flagString, flagVars, resolveCwd, } from "../command-registry.js";
+import { flagBool, flagList, flagString, flagVars, requireInputSelector, resolveCwd, } from "../command-registry.js";
 import { asJson, header, kv } from "../output/format-output.js";
 import { maybeRunInWatchMode } from "../output/watch-loop.js";
 import { renderFailureHints, templateDriftHints } from "../output/failure-hints.js";
@@ -80,17 +85,24 @@ export const templatesListCommand = {
     async run(args) {
         const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
         const list = inspection.templateRegistry.list();
+        // A template its loader refused (no `name`, a duplicate id) is named
+        // (round 12, 12.1) — it used to appear on no surface at all.
+        const note = { next: 'shrk templates doctor' };
         if (flagBool(args, 'json')) {
-            process.stdout.write(asJson(list.map((t) => ({ id: t.id, name: t.name, description: t.description, tags: t.tags }))) + '\n');
+            process.stdout.write(asJson(list.map((t) => ({ id: t.id, name: t.name, description: t.description, tags: t.tags ?? [] }))) + '\n');
+            await writeRejectedEntriesNote(inspection, [ContributionKind.Template], { ...note, json: true });
             return 0;
         }
         process.stdout.write(header(`Templates (${list.length})`));
         for (const t of list) {
             process.stdout.write(`  ${t.id.padEnd(28)} — ${t.name}\n`);
-            process.stdout.write(`      ${t.description}\n`);
-            if (t.tags.length)
-                process.stdout.write(`      tags: ${t.tags.join(', ')}\n`);
+            process.stdout.write(`      ${t.description ?? ''}\n`);
+            // The loader normalises a missing `tags` to []; guard a frozen literal anyway (12.1d).
+            const tags = Array.isArray(t.tags) ? t.tags : [];
+            if (tags.length)
+                process.stdout.write(`      tags: ${tags.join(', ')}\n`);
         }
+        await writeRejectedEntriesNote(inspection, [ContributionKind.Template], note);
         return 0;
     },
 };
@@ -120,6 +132,9 @@ export const templatesGetCommand = {
                 appliesWhen: template.appliesWhen,
                 variables: template.variables,
                 postGenerationNotes: template.postGenerationNotes ?? [],
+                // The one remainder shape MCP `get_template` carries too.
+                ...templateRemainderFields(template),
+                remainderLines: templateRemainderLines(template),
                 related: template.related ?? [],
             };
             process.stdout.write(asJson(safe) + '\n');
@@ -140,6 +155,9 @@ export const templatesGetCommand = {
                 process.stdout.write(`  - ${v.name}${v.required ? ' (required)' : ''}${v.default ? ` = ${v.default}` : ''}${v.description ? ` — ${v.description}` : ''}\n`);
             }
         }
+        const remainder = templateRemainderLines(template);
+        if (remainder.length > 0)
+            process.stdout.write(remainder.join('\n') + '\n');
         return 0;
     },
 };
@@ -148,6 +166,10 @@ export const templatesSearchCommand = {
     description: 'Search templates.',
     usage: 'shrk templates search <query>',
     async run(args) {
+        // No query is a usage error (3), never `Templates (N)` over nothing asked.
+        const noSelector = requireInputSelector(args, { flags: [], positional: true, usage: 'shrk templates search <query>' });
+        if (noSelector !== null)
+            return noSelector;
         const query = args.positional.join(' ');
         const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
         const results = inspection.templateRegistry.search(query);
@@ -205,6 +227,9 @@ export const templatesPreviewCommand = {
                 process.stdout.write(`  • ${note}\n`);
             }
         }
+        const remainder = templateRemainderLines(template);
+        if (remainder.length > 0)
+            process.stdout.write('\n' + remainder.join('\n') + '\n');
         return 0;
     },
 };
@@ -222,6 +247,9 @@ export const templatesDriftCommand = {
 async function templatesDriftImpl(args) {
     const cwd = resolveCwd(args);
     const inspection = await inspectSharkcraft({ cwd });
+    // `related` ids resolve against EVERY registry; a cold construct / playbook
+    // registry would report them NOT VERIFIED instead of resolving them.
+    await (await import("../surface/cli-command-resolver.js")).warmCliReferenceRegistries(inspection);
     const report = buildTemplateDriftReport(inspection, {
         ...(flagString(args, 'template') ? { templateId: flagString(args, 'template') } : {}),
         ...(flagString(args, 'pack') ? { packId: flagString(args, 'pack') } : {}),
@@ -415,6 +443,7 @@ export const templatesVerifyPathsCommand = {
     usage: 'shrk templates verify-paths [--template <id>] [--json]',
     async run(args) {
         const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
+        await (await import("../surface/cli-command-resolver.js")).warmCliReferenceRegistries(inspection);
         const report = buildTemplateDriftReport(inspection, {
             ...(flagString(args, 'template') ? { templateId: flagString(args, 'template') } : {}),
         });
@@ -627,6 +656,19 @@ export const templatesAddCommand = {
     name: 'add',
     description: 'Alias of `templates scaffold` — preview-only TS draft for a new template.',
 };
+/** Drift status rank — a folded lint finding can only raise a template's status. */
+const DRIFT_STATUS_RANK = {
+    [TemplateDriftStatus.Pass]: 0,
+    [TemplateDriftStatus.Warn]: 1,
+    [TemplateDriftStatus.Fail]: 2,
+};
+/**
+ * The lint findings the doctor folds in: every error (`templates lint` exits 1
+ * on them — an invalid change operation, a malformed remainder, an unsafe
+ * target), plus `render-threw`, the one that means the operations were never
+ * checked (it is what the doctor's coverage counts as unexamined).
+ */
+const FOLDED_LINT_WARNINGS = new Set(['render-threw']);
 /**
  * `shrk templates doctor` aggregates the existing drift + lint
  * signals into one structured report. Read-only.
@@ -634,46 +676,91 @@ export const templatesAddCommand = {
  * 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 const templatesDoctorCommand = {
     name: 'doctor',
-    description: 'Template-quality doctor — combines drift + lint signals into one clean/dirty verdict per template. Read-only.',
-    usage: 'shrk templates doctor [--strict] [--json]',
+    description: 'Template-quality doctor — combines drift + lint signals into one clean/dirty verdict per template. A lint error (an invalid change operation, a malformed remainder) fails the template, as `templates lint` does. Exit 0 clean · 1 a failing template (or a warning under --strict) · 2 nothing verified (no template registered — `--allow-empty` accepts that — or a changes() that threw with sample variables). Read-only.',
+    usage: 'shrk templates doctor [--strict] [--allow-empty] [--json]',
+    booleanFlags: new Set(['strict', 'json', ALLOW_EMPTY_FLAG]),
     async run(args) {
         const cwd = resolveCwd(args);
         const inspection = await inspectSharkcraft({ cwd });
+        await (await import("../surface/cli-command-resolver.js")).warmCliReferenceRegistries(inspection);
         const drift = buildTemplateDriftReport(inspection);
+        // Both read the one template set (`templateRegistry` is built from
+        // `inspection.templates`), so every lint result has a drift entry.
+        const lint = lintTemplates(inspection);
+        const lintById = new Map(lint.results.map((r) => [r.templateId, r.issues]));
+        const entries = drift.entries.map((e) => {
+            const folded = (lintById.get(e.templateId) ?? [])
+                .filter((i) => i.severity === 'error' || FOLDED_LINT_WARNINGS.has(i.code))
+                .map((i) => ({
+                severity: i.severity,
+                code: i.code,
+                message: `[lint ${i.code}] ${i.message}`,
+                ...(i.suggestion ? { suggestedFix: i.suggestion } : {}),
+            }));
+            if (folded.length === 0)
+                return e;
+            const lintStatus = folded.some((i) => i.severity === 'error') ? TemplateDriftStatus.Fail : TemplateDriftStatus.Warn;
+            const status = DRIFT_STATUS_RANK[lintStatus] > DRIFT_STATUS_RANK[e.status] ? lintStatus : e.status;
+            return { ...e, status, issues: [...e.issues, ...folded] };
+        });
         const totals = {
-            total: drift.entries.length,
-            pass: drift.entries.filter((e) => e.status === TemplateDriftStatus.Pass).length,
-            warn: drift.entries.filter((e) => e.status === TemplateDriftStatus.Warn).length,
-            fail: drift.entries.filter((e) => e.status === TemplateDriftStatus.Fail).length,
+            total: entries.length,
+            pass: entries.filter((e) => e.status === TemplateDriftStatus.Pass).length,
+            warn: entries.filter((e) => e.status === TemplateDriftStatus.Warn).length,
+            fail: entries.filter((e) => e.status === TemplateDriftStatus.Fail).length,
         };
+        const unchecked = entries
+            .filter((e) => e.issues.some((i) => FOLDED_LINT_WARNINGS.has(i.code)))
+            .map((e) => e.templateId);
+        // THE template-registry coverage record — `check templates` settles on it too.
+        const coverage = templateRegistryCoverage({
+            total: totals.total,
+            unchecked,
+            root: inspection.projectRoot,
+            acceptance: allowEmptyValve(args, totals.total),
+        });
         const strict = flagBool(args, 'strict');
-        const exit = totals.fail > 0 || (strict && totals.warn > 0) ? 1 : 0;
+        const settled = settleVerdict(totals.fail > 0 || (strict && totals.warn > 0) ? 1 : 0, [coverage]);
         if (flagBool(args, 'json')) {
             process.stdout.write(asJson({
                 schema: 'sharkcraft.templates-doctor/v1',
                 generatedAt: new Date().toISOString(),
                 totals,
-                entries: drift.entries,
+                entries,
+                coverage,
+                exitCode: settled.exit,
+                verdict: settled.verdict,
+                shortfalls: settled.shortfalls,
+                accepted: settled.accepted,
             }) + '\n');
-            return exit;
+            return settled.exit;
         }
         process.stdout.write(header('Templates doctor'));
         process.stdout.write(kv('totals', `${totals.pass} pass, ${totals.warn} warn, ${totals.fail} fail`) + '\n\n');
-        for (const e of drift.entries) {
+        for (const e of entries) {
             const label = (e.templateName ?? e.templateId);
             process.stdout.write(`  ${e.status.toUpperCase().padEnd(8)} ${label}\n`);
             for (const issue of e.issues) {
                 process.stdout.write(`           [${issue.severity}] ${issue.message}\n`);
             }
         }
-        if (exit === 0)
-            process.stdout.write('\nClean. ✓\n');
-        else
-            process.stdout.write('\nIssues found. Run `shrk templates drift --min-severity warning` for detail.\n');
-        return exit;
+        if (settled.exit === 1) {
+            process.stdout.write('\nIssues found. Run `shrk templates lint` and `shrk templates drift --min-severity warning` for detail.\n');
+        }
+        const line = verdictLine(settled, '\nClean. ✓');
+        if (line)
+            process.stdout.write(`${settled.exit === 0 ? '' : '\n'}${line}\n`);
+        if (settled.exit === 2 && totals.total === 0) {
+            process.stdout.write('Pass --allow-empty to accept a project with no templates explicitly.\n');
+        }
+        return settled.exit;
     },
 };
 // ─────────────────────────────────────────────────────────────────────────────

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

@@ -1 +1 @@
-{"version":3,"file":"test.command.d.ts","sourceRoot":"","sources":["../../src/commands/test.command.ts"],"names":[],"mappings":"AAUA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAiShC,eAAO,MAAM,WAAW,EAAE,eA4BzB,CAAC"}
+{"version":3,"file":"test.command.d.ts","sourceRoot":"","sources":["../../src/commands/test.command.ts"],"names":[],"mappings":"AAWA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAuahC,eAAO,MAAM,WAAW,EAAE,eA6CzB,CAAC"}

package/dist/commands/test.command.js

@@ -1,29 +1,105 @@
 import { mkdirSync, writeFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
-import { buildTaskPacket, inspectSharkcraft, loadAgentContractTests, loadContextTests, runAgentContractTest, runContextTest, } from '@shrkcrft/inspector';
+import { buildTaskPacket, inspectSharkcraft, loadAgentContractTests, loadContextTests, nearestIds, runAgentContractTest, runContextTest, } from '@shrkcrft/inspector';
 import { flagBool, flagList, flagString, resolveCwd, } from "../command-registry.js";
+import { PositionalMode } from "../dispatch/positional-mode.js";
 import { asJson, header, kv } from "../output/format-output.js";
 import { agentTestMissingExpectedHints, renderFailureHints } from "../output/failure-hints.js";
 import { maybeRunInWatchMode } from "../output/watch-loop.js";
+import { warmCliReferenceRegistries } from "../surface/cli-command-resolver.js";
+import { ExitCode } from "../exit-codes.js";
+import { ALLOW_EMPTY_FLAG, allowEmptyValve } from "../gates/allow-empty.js";
+import { settleVerdict } from "../gates/settle-verdict.js";
+import { verdictLine } from "../gates/verdict-line.js";
+/**
+ * The `--id` selection. An id that selects NOTHING is a usage error (3) — a
+ * typo'd id used to print "No … tests configured." and exit 0, a green run
+ * over an empty selection.
+ */
+function selectById(all, args, kind) {
+    const filter = flagString(args, 'id');
+    if (filter === undefined)
+        return { tests: all };
+    const tests = all.filter((t) => t.id === filter);
+    if (tests.length > 0)
+        return { tests };
+    // An unknown DECLARED id — the same `nearestIds` every other id site uses
+    // (`checks --rule`, `checks run`, `self-config resolve`), never the
+    // command-typo scorer.
+    const near = nearestIds(filter, all.map((t) => t.id)).map((n) => n.id);
+    return {
+        tests,
+        usageError: `no ${kind} test with id '${filter}' (${all.length} configured)${near.length > 0 ? ` — did you mean ${near.map((n) => `'${n}'`).join(', ')}?` : ''}`,
+    };
+}
+/** Print (or JSON-encode) the `--id` usage error and return 3. */
+function writeUsageError(args, message) {
+    if (flagBool(args, 'json')) {
+        process.stdout.write(asJson({ tests: 0, results: [], exitCode: ExitCode.UsageError, verdict: 'usage-error', error: message }) + '\n');
+    }
+    else {
+        process.stderr.write(`\`shrk test\`: ${message}\n`);
+    }
+    return ExitCode.UsageError;
+}
+/**
+ * Zero tests configured examined nothing — NOT VERIFIED (2), the verdict
+ * `shrk quality` gives the same empty gate, unless `--allow-empty` accepts it.
+ */
+function settleEmptySet(args, unit, reason, root) {
+    return settleVerdict(ExitCode.VerifiedPass, [
+        { unit, expected: 0, examined: 0, root, reason, ...allowEmptyValve(args, 0) },
+    ]);
+}
+function writeEmptySet(args, title, none, settled) {
+    if (flagBool(args, 'json')) {
+        process.stdout.write(asJson({
+            tests: 0,
+            results: [],
+            exitCode: settled.exit,
+            verdict: settled.verdict,
+            shortfalls: settled.shortfalls,
+            accepted: settled.accepted,
+        }) + '\n');
+        return settled.exit;
+    }
+    process.stdout.write(header(title));
+    process.stdout.write(`${none}\n`);
+    const line = verdictLine(settled, 'Nothing to test — accepted.');
+    if (line)
+        process.stdout.write(line + '\n');
+    if (settled.exit === ExitCode.NotVerified) {
+        process.stdout.write(`Pass --${ALLOW_EMPTY_FLAG} to accept an empty test set explicitly.\n`);
+    }
+    return settled.exit;
+}
 async function runContextTests(args) {
     const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
+    // Existence answers come from the shared reference registry — warm it.
+    await warmCliReferenceRegistries(inspection);
     const all = await loadContextTests(inspection);
-    const filter = flagString(args, 'id');
-    const tests = filter ? all.filter((t) => t.id === filter) : all;
+    const { tests, usageError } = selectById(all, args, 'context');
+    if (usageError)
+        return writeUsageError(args, usageError);
     if (tests.length === 0) {
-        if (flagBool(args, 'json')) {
-            process.stdout.write(asJson({ tests: 0, results: [] }) + '\n');
-            return 0;
-        }
-        process.stdout.write(header('Context tests'));
-        process.stdout.write('No context tests configured.\n');
-        return 0;
+        const settled = settleEmptySet(args, 'context tests', 'no context tests configured (sharkcraft/context-tests.ts, or a pack `contextTestFiles` contribution)', inspection.projectRoot);
+        return writeEmptySet(args, 'Context tests', 'No context tests configured.', settled);
     }
     const results = tests.map((t) => runContextTest(inspection, t));
     const failed = results.filter((r) => !r.passed);
+    const settled = settleVerdict(failed.length > 0 ? ExitCode.Failure : ExitCode.VerifiedPass, [
+        { unit: 'context tests', expected: results.length, examined: results.length },
+    ]);
     if (flagBool(args, 'json')) {
-        process.stdout.write(asJson({ total: results.length, failed: failed.length, results }) + '\n');
-        return failed.length > 0 ? 1 : 0;
+        process.stdout.write(asJson({
+            total: results.length,
+            failed: failed.length,
+            exitCode: settled.exit,
+            verdict: settled.verdict,
+            shortfalls: settled.shortfalls,
+            results,
+        }) + '\n');
+        return settled.exit;
     }
     process.stdout.write(header(`Context tests (${results.length})`));
     for (const r of results) {
@@ -50,37 +126,65 @@ async function runContextTests(args) {
         }
     }
     process.stdout.write(`\nSummary: ${results.length - failed.length}/${results.length} passed.\n`);
-    return failed.length > 0 ? 1 : 0;
+    const line = verdictLine(settled, '');
+    if (line)
+        process.stdout.write(line + '\n');
+    return settled.exit;
 }
 async function runAgentTests(args) {
     const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
     const all = await loadAgentContractTests(inspection);
-    const filter = flagString(args, 'id');
-    const tests = filter ? all.filter((t) => t.id === filter) : all;
+    const { tests, usageError } = selectById(all, args, 'agent');
+    if (usageError)
+        return writeUsageError(args, usageError);
     if (tests.length === 0) {
-        if (flagBool(args, 'json')) {
-            process.stdout.write(asJson({ tests: 0, results: [] }) + '\n');
-            return 0;
-        }
-        process.stdout.write(header('Agent contract tests'));
-        process.stdout.write('No agent contract tests configured.\n');
-        return 0;
+        const settled = settleEmptySet(args, 'agent tests', 'no agent contract tests configured (sharkcraft/agent-tests.ts, or a pack `agentTestFiles` contribution)', inspection.projectRoot);
+        return writeEmptySet(args, 'Agent contract tests', 'No agent contract tests configured.', settled);
     }
-    // Pre-load policy / construct / playbook id sets so the runner can
-    // evaluate strict expectations accurately.
-    const { loadAgentContractRegistries } = await import('@shrkcrft/inspector');
-    const registries = await loadAgentContractRegistries(inspection);
-    const results = tests.map((t) => runAgentContractTest(inspection, t, registries));
+    // Warm the shared reference registry WITH the command resolver: existence
+    // expectations read the registry `shrk <kind> list` prints, and
+    // `expectedCommands` resolve against the live command index.
+    await warmCliReferenceRegistries(inspection);
+    const results = tests.map((t) => runAgentContractTest(inspection, t));
     const failed = results.filter((r) => !r.passed);
+    // A test whose every failing expectation could not be evaluated is NOT
+    // VERIFIED — an unexamined unit, never a pass and never a plain failure.
+    const notVerified = results.filter((r) => r.verdict === 'not-verified');
+    const anyFailed = results.some((r) => r.verdict === 'fail');
+    const settled = settleVerdict(anyFailed ? ExitCode.Failure : ExitCode.VerifiedPass, [
+        {
+            unit: 'agent tests',
+            expected: results.length,
+            examined: results.length - notVerified.length,
+            ...(notVerified.length > 0
+                ? {
+                    unexamined: notVerified.slice(0, 20).map((r) => r.id),
+                    unexaminedTotal: notVerified.length,
+                    reason: 'an expectation could not be evaluated',
+                }
+                : {}),
+        },
+    ]);
+    const exit = settled.exit;
     if (flagBool(args, 'json')) {
-        process.stdout.write(asJson({ total: results.length, failed: failed.length, results }) + '\n');
-        return failed.length > 0 ? 1 : 0;
+        process.stdout.write(asJson({
+            total: results.length,
+            failed: failed.length,
+            notVerified: notVerified.length,
+            exitCode: exit,
+            verdict: settled.verdict,
+            shortfalls: settled.shortfalls,
+            results,
+        }) + '\n');
+        return exit;
     }
     process.stdout.write(header(`Agent contract tests (${results.length})`));
     for (const r of results) {
-        const tag = r.passed ? 'PASS' : 'FAIL';
+        const tag = r.passed ? 'PASS' : r.verdict === 'not-verified' ? 'N/V ' : 'FAIL';
         process.stdout.write(`  ${tag}  ${r.id.padEnd(36)} task: ${r.task}\n`);
         if (!r.passed) {
+            if ((r.unverified ?? []).length)
+                process.stdout.write(`         NOT VERIFIED: ${r.unverified.join(', ')}\n`);
             if (r.expectedPipeline) {
                 process.stdout.write(`         expected pipeline: ${r.expectedPipeline}\n`);
                 process.stdout.write(`         actual pipelines:  ${r.actualPipelines?.join(', ') ?? '(none)'}\n`);
@@ -108,7 +212,11 @@ async function runAgentTests(args) {
             if ((r.unexpectedlyIncluded ?? []).length)
                 process.stdout.write(`         unexpectedly included: ${r.unexpectedlyIncluded.join(', ')}\n`);
             for (const d of r.diagnostics ?? []) {
-                process.stdout.write(`         · ${d.kind}: ${d.id} (${d.existsInRegistry ? 'exists' : 'missing from registry'}):\n`);
+                const why = d.code ?? (d.existsInRegistry ? 'exists' : 'missing from registry');
+                const where = d.consulted
+                    ? ` — ${d.assertion ?? 'check'} · consulted ${d.consulted.kind} (${d.consulted.listVerb}${d.consulted.kind === 'command' ? '' : `, ${d.consulted.size} ids`})`
+                    : '';
+                process.stdout.write(`         · ${d.kind}: ${d.id} (${why})${where}:\n`);
                 for (const s of d.suggestions)
                     process.stdout.write(`             - ${s}\n`);
             }
@@ -131,7 +239,10 @@ async function runAgentTests(args) {
     if (anyMissingExpected) {
         process.stdout.write(renderFailureHints(agentTestMissingExpectedHints()));
     }
-    return failed.length > 0 ? 1 : 0;
+    const line = verdictLine(settled, '', exit === ExitCode.NotVerified ? 'Some expectations could not be evaluated (see NOT VERIFIED above).' : undefined);
+    if (line)
+        process.stdout.write(line + '\n');
+    return exit;
 }
 async function generateContextTest(args) {
     const task = args.positional.join(' ').trim();
@@ -250,8 +361,25 @@ function slug(s) {
 }
 export const testCommand = {
     name: 'test',
+    positionals: PositionalMode.None,
+    subverbs: [
+        { name: 'context', description: 'Run the context regression tests.', usage: 'shrk test context [--id <id>] [--allow-empty] [--json]' },
+        { name: 'agent', description: 'Run the agent-contract tests.', usage: 'shrk test agent [--id <id>] [--allow-empty] [--watch] [--json]' },
+        {
+            name: 'generate',
+            description: 'Generate a context or agent test from a task.',
+            usage: 'shrk test generate <context|agent> "<task>" [--write]',
+            positionals: PositionalMode.None,
+            subverbs: [
+                { name: 'context', description: 'Generate a context test.', usage: 'shrk test generate context "<task>" [--write]', positionals: PositionalMode.Free },
+                { name: 'agent', description: 'Generate an agent test.', usage: 'shrk test generate agent "<task>" [--write]', positionals: PositionalMode.Free },
+            ],
+        },
+    ],
     description: 'Run or generate SharkCraft regression tests: `test context` / `test agent`, or `test generate context|agent "<task>"`.',
-    usage: 'shrk [--cwd <dir>] test <context|agent|generate> [args...] [--id <id>] [--json]',
+    usage: 'shrk [--cwd <dir>] test <context|agent|generate> [args...] [--id <id>] [--allow-empty] [--json]',
+    // `--allow-empty` never swallows a following positional.
+    booleanFlags: new Set(['json', ALLOW_EMPTY_FLAG]),
     async run(args) {
         const sub = args.positional[0];
         const sliced = { ...args, positional: args.positional.slice(1) };

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

@@ -1 +1 @@
-{"version":3,"file":"tests.command.d.ts","sourceRoot":"","sources":["../../src/commands/tests.command.ts"],"names":[],"mappings":"AASA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAwChC,eAAO,MAAM,kBAAkB,EAAE,eAyBhC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eAajC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eAgBjC,CAAC"}
+{"version":3,"file":"tests.command.d.ts","sourceRoot":"","sources":["../../src/commands/tests.command.ts"],"names":[],"mappings":"AASA,OAAO,EAOL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA+ChC,eAAO,MAAM,kBAAkB,EAAE,eAiChC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eAajC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eA0BjC,CAAC"}

package/dist/commands/tests.command.js

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
 import { analyzeTestImpact, getChangedFiles, inspectSharkcraft, readFeatureBundle, suggestTestPathFor, } from '@shrkcrft/inspector';
-import { flagBool, flagString, flagList, resolveCwd, } from "../command-registry.js";
+import { emptySelectionExit, flagBool, flagString, flagList, requireInputSelector, resolveCwd, } from "../command-registry.js";
 import { asJson, header } from "../output/format-output.js";
 function collectFiles(cwd, args) {
     const files = flagList(args, 'files');
@@ -46,15 +46,29 @@ function collectFiles(cwd, args) {
     }
     return [...new Set(out)];
 }
+/** The input selectors `tests impact` / `tests missing` accept — at least one is required. */
+const TEST_SELECTORS = ['files', 'since', 'staged', 'plan', 'bundle'];
+const TESTS_IMPACT_USAGE = 'shrk tests impact [--files a,b] [--since <ref>] [--staged] [--plan <plan>] [--bundle <id>] "<task>"';
+const TESTS_MISSING_USAGE = 'shrk tests missing --files a,b | --since <ref> | --staged | --plan <plan> | --bundle <id>';
 export const testsImpactCommand = {
     name: 'impact',
     description: 'Test impact analysis for changed files / plan / bundle.',
-    usage: 'shrk tests impact [--files a,b] [--since <ref>] [--staged] [--plan <plan>] [--bundle <id>] "<task>"',
+    usage: TESTS_IMPACT_USAGE,
+    booleanFlags: new Set(['json', 'staged']),
     async run(args) {
+        const noSelector = requireInputSelector(args, {
+            flags: TEST_SELECTORS,
+            positional: true,
+            usage: TESTS_IMPACT_USAGE,
+        });
+        if (noSelector !== null)
+            return noSelector;
         const cwd = resolveCwd(args);
         const inspection = await inspectSharkcraft({ cwd });
         const task = args.positional.join(' ').trim() || undefined;
         const files = collectFiles(cwd, args);
+        if (files.length === 0 && !task)
+            return emptySelectionExit(flagBool(args, 'json'));
         const result = analyzeTestImpact(inspection, {
             ...(task ? { task } : {}),
             files,
@@ -91,16 +105,28 @@ export const testsSuggestCommand = {
 export const testsMissingCommand = {
     name: 'missing',
     description: 'Show missing test files for the given inputs.',
-    usage: 'shrk tests missing --files a,b',
+    usage: TESTS_MISSING_USAGE,
+    booleanFlags: new Set(['json', 'staged']),
     async run(args) {
+        // The selector is REQUIRED: without one this printed zero bytes and exit 0
+        // — "you gave me nothing" rendered as "I found nothing".
+        const noSelector = requireInputSelector(args, { flags: TEST_SELECTORS, usage: TESTS_MISSING_USAGE });
+        if (noSelector !== null)
+            return noSelector;
         const cwd = resolveCwd(args);
         const inspection = await inspectSharkcraft({ cwd });
         const files = collectFiles(cwd, args);
+        if (files.length === 0)
+            return emptySelectionExit(flagBool(args, 'json'));
         const r = analyzeTestImpact(inspection, { files });
         if (flagBool(args, 'json')) {
             process.stdout.write(asJson({ missing: r.missingTestFiles }) + '\n');
             return 0;
         }
+        if (r.missingTestFiles.length === 0) {
+            // Never zero bytes on a verified run.
+            process.stdout.write(`No missing tests for ${files.length} file(s).\n`);
+        }
         for (const f of r.missingTestFiles)
             process.stdout.write(f + '\n');
         return 0;

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

@@ -1 +1 @@
-{"version":3,"file":"trace.command.d.ts","sourceRoot":"","sources":["../../src/commands/trace.command.ts"],"names":[],"mappings":"AAmBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA8EhC,eAAO,MAAM,YAAY,EAAE,eA+H1B,CAAC"}
+{"version":3,"file":"trace.command.d.ts","sourceRoot":"","sources":["../../src/commands/trace.command.ts"],"names":[],"mappings":"AAoBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAuFhC,eAAO,MAAM,YAAY,EAAE,eAgJ1B,CAAC"}