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

package/dist/commands/contract.command.js

@@ -2,6 +2,7 @@ import { mkdirSync, writeFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
 import { buildAgentContract, inspectSharkcraft, renderAgentContractHtml, renderAgentContractMarkdown, renderAgentContractText, } from '@shrkcrft/inspector';
 import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { PositionalMode } from "../dispatch/positional-mode.js";
 import { asJson } from "../output/format-output.js";
 import { contractApproveCommand, contractCheckCommand, contractStatusCommand, } from "./contract-gate.command.js";
 import { contractTemplateCommand } from "./contract-templates.command.js";
@@ -23,6 +24,40 @@ function safeSlug(s) {
 }
 export const contractCommand = {
     name: 'contract',
+    // Free: `contract "<task>"` takes the task as free text.
+    positionals: PositionalMode.Free,
+    subverbs: [
+        { name: 'check', description: 'Check a saved contract against the workspace.', usage: 'shrk contract check <contract.json>', positionals: PositionalMode.Path },
+        {
+            name: 'approve',
+            description: 'Approve a saved contract.',
+            usage: 'shrk contract approve <contract.json> --by <name> --reason "<why>"',
+            positionals: PositionalMode.Path,
+        },
+        { name: 'status', description: 'Inspect a saved contract file.', usage: 'shrk contract status <contract.json>', positionals: PositionalMode.Path },
+        {
+            name: 'template',
+            description: 'Contract templates: list / get / render / recommend.',
+            usage: 'shrk contract template <list|get|render|recommend>',
+            positionals: PositionalMode.None,
+            subverbs: [
+                { name: 'list', description: 'List the contract templates.', usage: 'shrk contract template list [--json]' },
+                { name: 'get', description: 'Show one contract template.', usage: 'shrk contract template get <id>', positionals: PositionalMode.Free },
+                {
+                    name: 'render',
+                    description: 'Render a contract template for a task.',
+                    usage: 'shrk contract template render <id> --task "<task>"',
+                    positionals: PositionalMode.Free,
+                },
+                {
+                    name: 'recommend',
+                    description: 'Recommend a contract template for a task.',
+                    usage: 'shrk contract template recommend "<task>"',
+                    positionals: PositionalMode.Free,
+                },
+            ],
+        },
+    ],
     description: 'Build a deterministic agent contract for a task (intent + risk + impact + ownership + boundaries + policies + playbooks). Read-only unless --save (writes only to .sharkcraft/contracts/).',
     usage: 'shrk contract "<task>" [--role developer|reviewer|architect|release-manager|security|ai-agent] [--mode conservative|balanced|aggressive] [--files a,b,c] [--since <ref>] [--staged] [--format text|markdown|html|json] [--output <file>] [--save]',
     async run(args) {

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

@@ -1 +1 @@
-{"version":3,"file":"conventions.command.d.ts","sourceRoot":"","sources":["../../src/commands/conventions.command.ts"],"names":[],"mappings":"AAcA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC,eAAO,MAAM,sBAAsB,EAAE,eAgCpC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eAsCnC,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,eAsBtC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAkCrC,CAAC;AAEF,eAAO,MAAM,yBAAyB,EAAE,eAOvC,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,eAgBhC,CAAC"}
+{"version":3,"file":"conventions.command.d.ts","sourceRoot":"","sources":["../../src/commands/conventions.command.ts"],"names":[],"mappings":"AAgBA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAUhC,eAAO,MAAM,sBAAsB,EAAE,eA0CpC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eAsCnC,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,eAoEtC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAqHrC,CAAC;AAEF,eAAO,MAAM,yBAAyB,EAAE,eAOvC,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,eAsDhC,CAAC"}

package/dist/commands/conventions.command.js

@@ -1,12 +1,13 @@
-/**
- * `shrk conventions ...` — pack/local conventions surface.
- *
- * Read-only listing + doctor + check. `check` runs the loaded conventions
- * against caller-supplied files (or git diff). Never writes.
- */
-import { checkConventionsAgainstFiles, findConvention, getChangedFiles, inspectSharkcraft, listConventions, listConventionIssues, } from '@shrkcrft/inspector';
+import { checkConventionsAgainstFiles, ContributionKind, findConvention, getChangedFiles, inspectSharkcraft, listConventions, loadConventions, } from '@shrkcrft/inspector';
 import { flagBool, flagString, flagList, resolveCwd, } from "../command-registry.js";
+import { PositionalMode } from "../dispatch/positional-mode.js";
+import { ExitCode } from "../exit-codes.js";
+import { ALLOW_EMPTY_FLAG, allowEmptyValve } from "../gates/allow-empty.js";
+import { buildGateEnvelope } from "../gates/gate-envelope.js";
+import { settleVerdict } from "../gates/settle-verdict.js";
+import { verdictLine } from "../gates/verdict-line.js";
 import { asJson, header } from "../output/format-output.js";
+import { collectListVerbNote, writeListVerbNote } from "../output/rejected-entries-note.js";
 export const conventionsListCommand = {
     name: 'list',
     description: 'List registered conventions. Read-only.',
@@ -22,19 +23,29 @@ export const conventionsListCommand = {
             filtered = filtered.filter((e) => e.convention.kind === kind);
         if (source)
             filtered = filtered.filter((e) => e.source === source);
+        // A convention its loader refused, and a conventions file that failed to
+        // load, are said out loud (round 12, 12.1 + review A-4) — never a silently
+        // shorter list. The exit stays 0: a list is no verdict.
+        const note = { source, next: 'shrk conventions doctor' };
+        const outcomes = await collectListVerbNote(inspection, [ContributionKind.Convention], note);
         if (flagBool(args, 'json')) {
             process.stdout.write(asJson(filtered) + '\n');
+            writeListVerbNote(outcomes, inspection.projectRoot, { ...note, json: true });
             return 0;
         }
         process.stdout.write(header(`Conventions (${filtered.length})`));
         if (filtered.length === 0) {
-            process.stdout.write('  (none — contribute via a pack manifest "conventionFiles" entry or sharkcraft/conventions.ts)\n');
-            return 0;
+            // Never point at a conventions file that exists and FAILED as the place
+            // to contribute — the note below names it and its error.
+            process.stdout.write(outcomes.loadFailures.length > 0
+                ? '  (none loaded — a conventions file failed to load; see below)\n'
+                : '  (none — contribute via a pack manifest "conventionFiles" entry or sharkcraft/conventions.ts)\n');
         }
         for (const e of filtered) {
             const src = e.source === 'pack' ? `pack:${e.packageName ?? '?'}` : e.source;
             process.stdout.write(`  • ${e.convention.kind.padEnd(12)} ${e.convention.id.padEnd(28)} ${e.convention.title}  [${src}]\n`);
         }
+        writeListVerbNote(outcomes, inspection.projectRoot, note);
         return 0;
     },
 };
@@ -81,61 +92,172 @@ export const conventionsGetCommand = {
 };
 export const conventionsDoctorCommand = {
     name: 'doctor',
-    description: 'Surface load/validation issues for conventions.',
-    usage: 'shrk conventions doctor [--json]',
+    description: 'Surface load / validation issues for conventions — an invalid shape (a kind, severity or reference kind outside its closed set is named with the allowed values), a shape warning, a file that failed to load. Exit 0 · 1 an invalid convention (or a warning under --strict) · 2 a convention file never read, or none discovered (--allow-empty accepts that explicitly). Read-only.',
+    usage: 'shrk conventions doctor [--strict] [--allow-empty] [--json]',
+    booleanFlags: new Set(['json', 'strict', ALLOW_EMPTY_FLAG]),
     async run(args) {
         const cwd = resolveCwd(args);
         const inspection = await inspectSharkcraft({ cwd });
-        const issues = await listConventionIssues(inspection);
+        const { entries, issues, files } = await loadConventions(inspection);
+        // Convention FILES are the unit: a file that failed to load was never
+        // validated, so "no issues" over it is not a pass.
+        const coverage = {
+            unit: 'convention files',
+            expected: files.discovered,
+            examined: files.discovered - files.unread.length,
+            root: inspection.projectRoot,
+            reason: files.discovered === 0
+                ? 'no sharkcraft/conventions.ts, conventionFiles entry or pack conventionFiles'
+                : 'missing or failed to load, so their conventions were never validated',
+            ...(files.unread.length > 0 ? { unexamined: files.unread.slice(0, 20), unexaminedTotal: files.unread.length } : {}),
+            ...allowEmptyValve(args, files.discovered),
+        };
+        const errors = issues.filter((i) => i.severity === 'error').length;
+        const warnings = issues.filter((i) => i.severity === 'warning').length;
+        const strict = flagBool(args, 'strict');
+        const settled = settleVerdict(errors > 0 || (strict && warnings > 0) ? 1 : 0, [coverage]);
         if (flagBool(args, 'json')) {
-            process.stdout.write(asJson({ issues }) + '\n');
-            return issues.some((i) => i.severity === 'error') ? 1 : 0;
+            process.stdout.write(asJson({
+                issues,
+                conventions: entries.length,
+                files,
+                coverage,
+                exitCode: settled.exit,
+                verdict: settled.verdict,
+                shortfalls: settled.shortfalls,
+                accepted: settled.accepted,
+            }) + '\n');
+            return settled.exit;
         }
         process.stdout.write(header('Conventions doctor'));
-        if (issues.length === 0) {
-            process.stdout.write('  ok — no load/validation issues.\n');
-            return 0;
-        }
+        process.stdout.write(`  ${entries.length} convention(s) loaded from ${files.discovered - files.unread.length} of ${files.discovered} file(s) · ${errors} error(s) · ${warnings} warning(s)\n`);
         for (const i of issues) {
-            process.stdout.write(`  ${i.severity.padEnd(7)} [${i.code}] ${i.message}\n`);
+            const where = i.conventionId ? ` ${i.conventionId}` : '';
+            process.stdout.write(`  ${i.severity.padEnd(7)} [${i.code}]${where} ${i.message}\n`);
+        }
+        const clean = files.discovered === 0
+            ? 'No conventions declared — accepted.'
+            : warnings > 0
+                ? `No blocking convention issues — ${warnings} warning(s) reported above.`
+                : 'ok — no load/validation issues.';
+        const line = verdictLine(settled, clean, files.discovered === 0 ? 'No convention files discovered — nothing validated.' : undefined);
+        if (line)
+            process.stdout.write(`\n${line}\n`);
+        if (settled.exit === ExitCode.NotVerified && files.discovered === 0) {
+            process.stdout.write('Pass --allow-empty to accept a project with no conventions explicitly.\n');
         }
-        return issues.some((i) => i.severity === 'error') ? 1 : 0;
+        return settled.exit;
     },
 };
 export const conventionsCheckCommand = {
     name: 'check',
-    description: 'Run loaded conventions against files (--files / --since / --staged).',
-    usage: 'shrk conventions check [--files a,b,c] [--since <ref>] [--staged] [--json]',
+    description: 'Run the loaded conventions against files (--files / --since / --staged; default: the working-tree change). Exit 0 no error-severity hit · 1 an error-severity hit · 2 NOT VERIFIED — no file in scope, no convention declared (--allow-empty accepts either explicitly), or a convention file never read · 3 usage. Read-only.',
+    usage: 'shrk conventions check [--files a,b,c] [--since <ref>] [--staged] [--allow-empty] [--json]',
+    booleanFlags: new Set(['json', 'staged', ALLOW_EMPTY_FLAG]),
     async run(args) {
         const cwd = resolveCwd(args);
         const inspection = await inspectSharkcraft({ cwd });
         let files = [];
+        let scope = 'the working-tree change';
         const explicit = flagList(args, 'files');
         if (explicit.length > 0) {
             files = explicit;
+            scope = '--files';
         }
         else if (flagBool(args, 'staged')) {
             files = getChangedFiles(cwd, { staged: true });
+            scope = 'the staged change';
         }
         else {
             const since = flagString(args, 'since');
             files = since ? getChangedFiles(cwd, { since }) : getChangedFiles(cwd, {});
+            if (since)
+                scope = `the change since ${since}`;
         }
+        // Round 13: a verdict verb. "Nothing to check" is not a pass — an empty
+        // file scope, a project with no convention, or a convention file that
+        // never loaded (its conventions were never checked) settle NOT VERIFIED
+        // (2) through the shared gate envelope; it printed "ok — no violations"
+        // at exit 0 over all three. `--allow-empty` accepts an empty scope or an
+        // empty registry explicitly (printed) — never an unread file.
+        const loaded = await loadConventions(inspection);
         const report = await checkConventionsAgainstFiles(inspection, files);
+        const unread = loaded.files.unread;
+        const rows = [
+            {
+                id: 'convention files',
+                type: 'convention',
+                status: 'passed',
+                severity: 'warning',
+                counts: { discovered: loaded.files.discovered, unread: unread.length, conventions: loaded.entries.length },
+                violations: [],
+                coverage: {
+                    unit: 'convention files',
+                    expected: loaded.files.discovered,
+                    examined: loaded.files.discovered - unread.length,
+                    root: inspection.projectRoot,
+                    reason: loaded.files.discovered === 0
+                        ? 'no sharkcraft/conventions.ts, conventionFiles entry or pack conventionFiles — nothing to check the files against'
+                        : 'missing or failed to load, so their conventions were never checked',
+                    ...(unread.length > 0 ? { unexamined: unread.slice(0, 20), unexaminedTotal: unread.length } : {}),
+                    ...allowEmptyValve(args, loaded.files.discovered),
+                },
+            },
+            ...loaded.entries.map((e) => {
+                const hits = report.hits.filter((h) => h.conventionId === e.convention.id);
+                return {
+                    id: e.convention.id,
+                    type: 'convention',
+                    status: hits.some((h) => h.severity === 'error') ? 'failed' : 'passed',
+                    severity: e.convention.severity === 'error' ? 'error' : 'warning',
+                    counts: { rules: e.convention.rules.length, hits: hits.length },
+                    violations: hits.map((h) => ({ id: `${h.conventionId}/${h.ruleId}`, file: h.file, message: h.message })),
+                    coverage: { unit: 'conventions', expected: 1, examined: 1 },
+                };
+            }),
+        ];
+        const gate = buildGateEnvelope('conventions check', report.verdict === 'clean' ? ExitCode.VerifiedPass : ExitCode.Failure, rows, {
+            unit: 'files',
+            expected: files.length,
+            examined: files.length,
+            root: inspection.projectRoot,
+            reason: `no file in ${scope} — nothing to check the conventions against`,
+            ...allowEmptyValve(args, files.length),
+        });
         if (flagBool(args, 'json')) {
-            process.stdout.write(asJson(report) + '\n');
-            return report.verdict === 'clean' ? 0 : 1;
+            process.stdout.write(asJson({
+                ...report,
+                // The engine's `clean` over an empty scope is not a pass (round 13
+                // review): at 2 the top-level verdict says so, never contradicting
+                // `exitCode` / `gate.verdict` beside it.
+                verdict: gate.exit === ExitCode.NotVerified ? 'not-verified' : report.verdict,
+                conventions: loaded.entries.length,
+                exitCode: gate.exit,
+                shortfalls: gate.shortfalls,
+                accepted: gate.accepted,
+                gate,
+            }) + '\n');
+            return gate.exit;
         }
         process.stdout.write(header(`Convention check (${report.filesScanned} files, ${report.hits.length} hits)`));
-        if (report.hits.length === 0) {
-            process.stdout.write('  ok — no violations.\n');
-            return 0;
-        }
         for (const h of report.hits.slice(0, 200)) {
             process.stdout.write(`  ${h.severity.padEnd(7)} ${h.conventionId}/${h.ruleId} — ${h.file}\n`);
             process.stdout.write(`           ${h.message}\n`);
         }
-        return report.verdict === 'clean' ? 0 : 1;
+        const empty = files.length === 0 || loaded.files.discovered === 0;
+        const warnings = report.hits.filter((h) => h.severity !== 'error').length;
+        const clean = empty
+            ? 'Nothing to check — accepted.'
+            : warnings > 0
+                ? `No blocking convention violation — ${warnings} non-error hit(s) reported above.`
+                : 'ok — no violations.';
+        const line = verdictLine(gate, clean);
+        if (line)
+            process.stdout.write(`\n${line}\n`);
+        if (gate.exit === ExitCode.NotVerified && empty) {
+            process.stdout.write(`Pass --${ALLOW_EMPTY_FLAG} to accept an empty changeset or a project with no conventions explicitly.\n`);
+        }
+        return gate.exit;
     },
 };
 export const conventionsExplainCommand = {
@@ -150,6 +272,44 @@ export const conventionsCommand = {
     name: 'conventions',
     description: 'Generic conventions registry (naming / path / barrel / layout / command / validation / ownership / testing / release / safety). Read-only.',
     usage: 'shrk conventions list|get|doctor|check|explain ...',
+    // Declared (round 11 review): the dispatcher guard refuses an unknown verb
+    // with the closest one, and the declared walk reaches `conventions doctor` —
+    // a verdict verb, so a bad flag there exits 3, labelled with its own path.
+    positionals: PositionalMode.None,
+    subverbs: [
+        {
+            name: conventionsListCommand.name,
+            description: conventionsListCommand.description,
+            usage: conventionsListCommand.usage,
+            positionals: PositionalMode.None,
+        },
+        {
+            name: conventionsGetCommand.name,
+            description: conventionsGetCommand.description,
+            usage: conventionsGetCommand.usage,
+            positionals: PositionalMode.Free,
+        },
+        {
+            name: conventionsDoctorCommand.name,
+            description: conventionsDoctorCommand.description,
+            usage: conventionsDoctorCommand.usage,
+            positionals: PositionalMode.None,
+        },
+        {
+            name: conventionsCheckCommand.name,
+            description: conventionsCheckCommand.description,
+            usage: conventionsCheckCommand.usage,
+            positionals: PositionalMode.None,
+        },
+        {
+            name: conventionsExplainCommand.name,
+            description: conventionsExplainCommand.description,
+            usage: conventionsExplainCommand.usage,
+            positionals: PositionalMode.Free,
+        },
+    ],
+    // The group parses every subverb's argv, so the subverbs' boolean flags live here too.
+    booleanFlags: new Set(['json', 'strict', 'staged', ALLOW_EMPTY_FLAG]),
     async run(args) {
         const sub = args.positional[0];
         args.positional = args.positional.slice(1);

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

@@ -1 +1 @@
-{"version":3,"file":"coverage.command.d.ts","sourceRoot":"","sources":["../../src/commands/coverage.command.ts"],"names":[],"mappings":"AAMA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC,eAAO,MAAM,eAAe,EAAE,eAkC7B,CAAC"}
+{"version":3,"file":"coverage.command.d.ts","sourceRoot":"","sources":["../../src/commands/coverage.command.ts"],"names":[],"mappings":"AAMA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAIhC,eAAO,MAAM,eAAe,EAAE,eA0C7B,CAAC"}

package/dist/commands/coverage.command.js

@@ -1,8 +1,17 @@
 import { buildCoverageReport, buildScaffoldCoverageReport, inspectSharkcraft, renderScaffoldCoverageMarkdown, } from '@shrkcrft/inspector';
 import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { PositionalMode } from "../dispatch/positional-mode.js";
 import { asJson, header, kv } from "../output/format-output.js";
 export const coverageCommand = {
     name: 'coverage',
+    positionals: PositionalMode.None,
+    subverbs: [
+        {
+            name: 'scaffolds',
+            description: 'Scaffold coverage for a task or a domain.',
+            usage: 'shrk coverage scaffolds [--task "<task>"|--domain <domain>] [--json]',
+        },
+    ],
     description: 'Report relationship/coverage quality across registries + scaffold coverage (`shrk coverage scaffolds --task "<task>"`).',
     usage: 'shrk [--cwd <dir>] coverage [--json]\n  shrk [--cwd <dir>] coverage scaffolds [--task "<task>"|--domain <domain>] [--json]',
     async run(args) {

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

@@ -1,5 +1,4 @@
 import { type ICommandHandler } from '../command-registry.js';
 export declare const nextCommand: ICommandHandler;
-export declare const findCommand: ICommandHandler;
 export declare const explainCommand: ICommandHandler;
 //# sourceMappingURL=daily.commands.d.ts.map

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

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

package/dist/commands/daily.commands.js

@@ -1,7 +1,9 @@
 import { buildAiReadinessReport, buildTaskPacket, inspectSharkcraft, runDoctor, } from '@shrkcrft/inspector';
 import { recommendPresets } from '@shrkcrft/presets';
 import { flagBool, flagNumber, resolveCwd, } from "../command-registry.js";
+import { PositionalMode } from "../dispatch/positional-mode.js";
 import { asJson, header, kv } from "../output/format-output.js";
+import { tryExplainBoundaryRule } from "./boundaries.command.js";
 import { tryExplainGateRule } from "./gates.command.js";
 // ────────────────────────────────────────────────────────────────────────
 // shrk next — "what should I do right now in this repo?"
@@ -84,7 +86,9 @@ export const nextCommand = {
     },
 };
 // ────────────────────────────────────────────────────────────────────────
-// shrk find — grouped search across all SharkCraft kinds.
+// Topic matching for `explain`. (`shrk find` was retired — `shrk search` is
+// the grouped search across every kind; its handler lingered here
+// unregistered.)
 // ────────────────────────────────────────────────────────────────────────
 function lc(s) {
     return s.toLowerCase();
@@ -93,86 +97,13 @@ function matches(query, ...texts) {
     const q = lc(query);
     return texts.some((t) => typeof t === 'string' && lc(t).includes(q));
 }
-export const findCommand = {
-    name: 'find',
-    description: 'Search across knowledge / rules / paths / templates / pipelines / packs / presets in one place.',
-    usage: 'shrk [--cwd <dir>] find "<query>" [--limit N] [--json]',
-    async run(args) {
-        const query = args.positional.join(' ').trim();
-        if (!query) {
-            process.stderr.write('Usage: shrk find "<query>"\n');
-            return 2;
-        }
-        const limit = flagNumber(args, 'limit') ?? 8;
-        const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
-        const knowledge = inspection.knowledgeEntries
-            .filter((e) => matches(query, e.id, e.title, e.content, e.tags.join(' ')))
-            .slice(0, limit);
-        const rules = inspection.ruleService.list()
-            .filter((r) => matches(query, r.id, r.title, r.content))
-            .slice(0, limit);
-        const paths = inspection.pathService.list()
-            .filter((p) => matches(query, p.id, p.title, p.content))
-            .slice(0, limit);
-        const templates = inspection.templates
-            .filter((t) => matches(query, t.id, t.name, t.description))
-            .slice(0, limit);
-        const pipelines = inspection.pipelines
-            .filter((p) => matches(query, p.id, p.title, p.description))
-            .slice(0, limit);
-        const packs = inspection.packs.discoveredPacks
-            .filter((p) => matches(query, p.packageName, p.manifest?.info.description))
-            .slice(0, limit);
-        const presets = inspection.presetRegistry
-            .list()
-            .filter((p) => matches(query, p.id, p.title, p.description, (p.tags ?? []).join(' ')))
-            .slice(0, limit);
-        if (flagBool(args, 'json')) {
-            process.stdout.write(asJson({
-                query,
-                knowledge: knowledge.map((e) => ({ id: e.id, title: e.title, type: e.type })),
-                rules: rules.map((r) => ({ id: r.id, title: r.title })),
-                paths: paths.map((p) => ({ id: p.id, title: p.title })),
-                templates: templates.map((t) => ({ id: t.id, name: t.name })),
-                pipelines: pipelines.map((p) => ({ id: p.id, title: p.title })),
-                packs: packs.map((p) => ({ name: p.packageName, version: p.packageVersion })),
-                presets: presets.map((p) => ({ id: p.id, title: p.title })),
-            }) + '\n');
-            return 0;
-        }
-        process.stdout.write(header(`find: ${query}`));
-        function group(title, items) {
-            if (items.length === 0)
-                return;
-            process.stdout.write(`\n${title} (${items.length}):\n`);
-            for (const it of items)
-                process.stdout.write(`  ${it.line}\n`);
-        }
-        group('Knowledge', knowledge.map((e) => ({ line: `${e.id.padEnd(30)} ${e.title}` })));
-        group('Rules', rules.map((r) => ({ line: `${r.id.padEnd(30)} ${r.title}` })));
-        group('Paths', paths.map((p) => ({ line: `${p.id.padEnd(30)} ${p.title}` })));
-        group('Templates', templates.map((t) => ({ line: `${t.id.padEnd(30)} ${t.name}` })));
-        group('Pipelines', pipelines.map((p) => ({ line: `${p.id.padEnd(30)} ${p.title}` })));
-        group('Packs', packs.map((p) => ({ line: `${p.packageName}@${p.packageVersion}` })));
-        group('Presets', presets.map((p) => ({ line: `${p.id.padEnd(22)} ${p.title}` })));
-        const total = knowledge.length +
-            rules.length +
-            paths.length +
-            templates.length +
-            pipelines.length +
-            packs.length +
-            presets.length;
-        if (total === 0) {
-            process.stdout.write('\n(no matches)\n');
-        }
-        return 0;
-    },
-};
 // ────────────────────────────────────────────────────────────────────────
 // shrk explain <topic> — compact local explanation, no AI.
 // ────────────────────────────────────────────────────────────────────────
 export const explainCommand = {
     name: 'explain',
+    // The positionals are the free-form topic (or a rule id).
+    positionals: PositionalMode.Free,
     description: 'Search the project knowledge / rules / paths / templates / pipelines for a topic and print a compact explanation. No AI required.',
     usage: 'shrk [--cwd <dir>] explain "<topic>" [--max-entries N] [--json]',
     async run(args) {
@@ -189,6 +120,11 @@ export const explainCommand = {
             const asRule = await tryExplainGateRule(args, topic);
             if (asRule !== undefined)
                 return asRule;
+            // Round 13: a BOUNDARY rule id too — it used to fall through to the
+            // topic search ("no matching knowledge entries").
+            const asBoundary = await tryExplainBoundaryRule(args, topic);
+            if (asBoundary !== undefined)
+                return asBoundary;
         }
         const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
         const maxEntries = flagNumber(args, 'max-entries') ?? 6;

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

@@ -1 +1 @@
-{"version":3,"file":"dashboard.command.d.ts","sourceRoot":"","sources":["../../src/commands/dashboard.command.ts"],"names":[],"mappings":"AAgBA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAMhC,eAAO,MAAM,gBAAgB,EAAE,eAY9B,CAAC"}
+{"version":3,"file":"dashboard.command.d.ts","sourceRoot":"","sources":["../../src/commands/dashboard.command.ts"],"names":[],"mappings":"AAgBA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAOhC,eAAO,MAAM,gBAAgB,EAAE,eAsB9B,CAAC"}

package/dist/commands/dashboard.command.js

@@ -15,11 +15,21 @@ import { existsSync } from 'node:fs';
 import * as nodePath from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { PositionalMode } from "../dispatch/positional-mode.js";
 import { startDashboardApiServer } from "../dashboard/dashboard-api-server.js";
 import { asJson } from "../output/format-output.js";
 const DEFAULT_PORT = 4567;
 export const dashboardCommand = {
     name: 'dashboard',
+    // Mixed-mode (export / diff are trie children); `serve` is dispatched here.
+    positionals: PositionalMode.None,
+    subverbs: [
+        {
+            name: 'serve',
+            description: 'Start the dashboard (the same as bare `shrk dashboard`).',
+            usage: 'shrk [--cwd <dir>] dashboard serve [--host <addr>] [--port <n>] [--open|--no-open] [--api-only] [--static-only] [--dev-assets <path>] [--json]',
+        },
+    ],
     description: 'Start the local read-only SharkCraft dashboard (web UI + API). GET/HEAD only; 127.0.0.1 by default; no write endpoints.',
     usage: 'shrk [--cwd <dir>] dashboard [serve] [--host <addr>] [--port <n>] [--open|--no-open] [--api-only] [--static-only] [--dev-assets <path>] [--json]',
     async run(args) {

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

@@ -1 +1 @@
-{"version":3,"file":"dev.command.d.ts","sourceRoot":"","sources":["../../src/commands/dev.command.ts"],"names":[],"mappings":"AA6CA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAg8ChC,eAAO,MAAM,UAAU,EAAE,eAkExB,CAAC"}
+{"version":3,"file":"dev.command.d.ts","sourceRoot":"","sources":["../../src/commands/dev.command.ts"],"names":[],"mappings":"AA6CA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAm8ChC,eAAO,MAAM,UAAU,EAAE,eA0GxB,CAAC"}

package/dist/commands/dev.command.js

@@ -4,6 +4,7 @@ import * as nodePath from 'node:path';
 import { archiveDevSession, buildAgentBrief, buildTaskPacket, computeDevNextAction, createDevSessionState, DevSessionPhase, DevSessionPlanStatus, diffDevSessions, getDevSessionDir, inspectSharkcraft, listDevCleanCandidates, listDevSessionsDetailed, parseDurationToMs, recordAppliedPlan, recordReportFile, recordValidation, recomputePhase, renderDevSessionFinalReport, renderDevSessionHtml, reviewSavedPlan, scanDevSession, setDevNextAction, setDevSessionBriefFile, setDevSessionPhase, upsertDevPlanEntry, writeDevSessionState, } from '@shrkcrft/inspector';
 import { buildSavedPlan, generate, OverwriteStrategy, PLAN_SECRET_ENV, savePlanToFile, signPlan, } from '@shrkcrft/generator';
 import { flagBool, flagList, flagString, flagVars, resolveCwd, } from "../command-registry.js";
+import { PositionalMode } from "../dispatch/positional-mode.js";
 import { asJson, header, kv } from "../output/format-output.js";
 import { runValidationLoop } from "../validation/run-validation-loop.js";
 const SUBCOMMANDS = new Set([
@@ -231,7 +232,7 @@ async function planSession(args) {
     }
     if (!load.state) {
         process.stderr.write(`Session ${load.id} has no session.json (legacy session). ` +
-            `Use shrk dev status / shrk session report for legacy sessions.\n`);
+            `Use shrk dev status ${load.id} / shrk dev report ${load.id} for legacy sessions.\n`);
         return 1;
     }
     const packet = load.packet;
@@ -799,7 +800,9 @@ function reportSession(args) {
         if (htmlOut)
             state = recordReportFile(state, 'final-report.html');
         state = setDevSessionPhase(state, DevSessionPhase.Completed);
-        state = setDevNextAction(state, `shrk session show ${load.id}`);
+        // `shrk session show` never existed; a completed session's next action is
+        // its reports — the same answer the inspector's computeDevNextAction gives.
+        state = setDevNextAction(state, `shrk dev reports ${load.id}`);
         writeDevSessionState(cwd, state);
     }
     if (flagBool(args, 'json')) {
@@ -1335,6 +1338,46 @@ function commandsCmd(args) {
 }
 export const devCommand = {
     name: 'dev',
+    // Free: `shrk dev "<task>"` is the documented alias of `dev start "<task>"`.
+    positionals: PositionalMode.Free,
+    subverbs: [
+        { name: 'start', description: 'Start a dev session for a task.', usage: 'shrk dev start "<task>"', positionals: PositionalMode.Free },
+        { name: 'plan', description: 'Plan the next step of a session.', usage: 'shrk dev plan <sessionId>', positionals: PositionalMode.Free },
+        { name: 'status', description: 'A session’s status.', usage: 'shrk dev status [<sessionId>]', positionals: PositionalMode.Free },
+        { name: 'next', description: 'The next action for a session.', usage: 'shrk dev next [<sessionId>]', positionals: PositionalMode.Free },
+        { name: 'continue', description: 'Continue a session (same as `next`).', usage: 'shrk dev continue [<sessionId>]', positionals: PositionalMode.Free },
+        { name: 'validate', description: 'Validate a session’s applied plans.', usage: 'shrk dev validate <sessionId>', positionals: PositionalMode.Free },
+        { name: 'report', description: 'A session report.', usage: 'shrk dev report <sessionId>', positionals: PositionalMode.Free },
+        { name: 'list', description: 'List dev sessions.', usage: 'shrk dev list' },
+        {
+            name: 'mark-applied',
+            description: 'Record that a plan of the session was applied.',
+            usage: 'shrk dev mark-applied <sessionId> <planPath> [--note <text>]',
+            positionals: PositionalMode.Free,
+        },
+        {
+            name: 'mark-validated',
+            description: 'Record a session’s validation result.',
+            usage: 'shrk dev mark-validated <sessionId> [--report <path>] [--status passed|failed] [--note <text>]',
+            positionals: PositionalMode.Free,
+        },
+        { name: 'diff', description: 'Diff two sessions.', usage: 'shrk dev diff <sessionA> <sessionB> [--json]', positionals: PositionalMode.Free },
+        { name: 'archive', description: 'Archive a session.', usage: 'shrk dev archive <sessionId>', positionals: PositionalMode.Free },
+        {
+            name: 'clean',
+            description: 'Clean old sessions (dry-run unless --write).',
+            usage: 'shrk dev clean --older-than <duration> [--archive] [--write] [--include-active]',
+        },
+        {
+            name: 'open',
+            description: 'Open a session report.',
+            usage: 'shrk dev open <sessionId> [--html] [--serve [--host <addr>] [--port <n>]]',
+            positionals: PositionalMode.Free,
+        },
+        { name: 'plans', description: 'A session’s plans.', usage: 'shrk dev plans <sessionId>', positionals: PositionalMode.Free },
+        { name: 'reports', description: 'A session’s reports.', usage: 'shrk dev reports <sessionId>', positionals: PositionalMode.Free },
+        { name: 'commands', description: 'The commands a session ran / needs.', usage: 'shrk dev commands <sessionId>', positionals: PositionalMode.Free },
+    ],
     description: 'Safe AI-assisted development workflow: task → session → plan → review → apply (CLI) → validate → report. ' +
         'Never auto-applies plans; never runs untrusted pack commands; never writes outside .sharkcraft/sessions/.',
     usage: 'shrk dev <start|plan|status|next|continue|validate|report|list|mark-applied|mark-validated|diff|archive|clean|open|plans|reports|commands> [args...] [--cwd <dir>] [--json]\n' +

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

@@ -1,5 +1,3 @@
 import { type ICommandHandler } from '../command-registry.js';
 export declare const diagnosticsListCommand: ICommandHandler;
-export declare const diagnosticsGetCommand: ICommandHandler;
-export declare const diagnosticsSuggestCommand: ICommandHandler;
 //# sourceMappingURL=diagnostics.command.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"diagnostics.command.d.ts","sourceRoot":"","sources":["../../src/commands/diagnostics.command.ts"],"names":[],"mappings":"AAQA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC,eAAO,MAAM,sBAAsB,EAAE,eAiBpC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eA+BnC,CAAC;AAEF,eAAO,MAAM,yBAAyB,EAAE,eAsCvC,CAAC"}
+{"version":3,"file":"diagnostics.command.d.ts","sourceRoot":"","sources":["../../src/commands/diagnostics.command.ts"],"names":[],"mappings":"AACA,OAAO,EAAY,KAAK,eAAe,EAAmB,MAAM,wBAAwB,CAAC;AAMzF,eAAO,MAAM,sBAAsB,EAAE,eAiBpC,CAAC"}