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

package/dist/commands/impact.command.js

@@ -3,6 +3,8 @@ import * as nodePath from 'node:path';
 import { analyzeImpact, analyzeTestImpact, findSymbolInProject, FuzzyImpactSourceKind, getChangedFiles, ImpactInputKind, inspectSharkcraft, QueryMatchKind, readFeatureBundle, renderImpactGraph, renderImpactHtml, renderImpactMarkdown, renderImpactText, resolveFuzzyImpact, warmConstructCache, } from '@shrkcrft/inspector';
 import { flagBool, flagNumber, flagString, flagList, resolveCwd, } from "../command-registry.js";
 import { asJson, header, kv } from "../output/format-output.js";
+import { fuzzyImpactAmbiguousHints, renderFailureHints } from "../output/failure-hints.js";
+import { collectChangedPaths } from "../diff/collect-changed-paths.js";
 function collectFiles(args, cwd) {
     const diagnostics = [];
     const explicitFiles = flagList(args, 'files');
@@ -278,10 +280,90 @@ async function runViaGraph(args) {
         process.stdout.write(`! ${d}\n`);
     return 0;
 }
+/**
+ * `shrk impact --deleted`: deleted-symbol orphan check. Reads the
+ * working-tree diff's DELETED files (relative to `--since <ref>` or the
+ * default branch) and queries the graph for surviving files that still
+ * import them or reference a symbol they declared (alias-resolved, incl.
+ * barrel re-exports). Any surviving importer is reported with `file:line`
+ * and the command exits non-zero; with none it exits 0 with
+ * "no orphaned importers". Mirrors `--via-graph`'s flag/JSON style.
+ *
+ * The graph is queried against the CURRENT index snapshot — a not-yet-
+ * reindexed delete still carries its inbound edges, which is exactly what
+ * lets the check see the broken importers before they hit the build.
+ */
+async function runDeletedOrphans(args) {
+    const cwd = resolveCwd(args);
+    const wantJson = flagBool(args, 'json') || flagString(args, 'format') === 'json';
+    const sinceRef = flagString(args, 'since');
+    const changed = collectChangedPaths({ cwd, ...(sinceRef ? { ref: sinceRef } : {}) });
+    if (!changed.isAvailable) {
+        if (wantJson) {
+            process.stdout.write(asJson({ ok: false, error: changed.error }) + '\n');
+        }
+        else {
+            process.stderr.write(`Cannot resolve diff: ${changed.error ?? 'unknown'}\n`);
+        }
+        return 2;
+    }
+    const deleted = changed.deleted;
+    if (deleted.length === 0) {
+        if (wantJson) {
+            process.stdout.write(asJson({
+                schema: 'sharkcraft.deleted-orphans/v1',
+                resolvedDeleted: [],
+                unresolvedDeleted: [],
+                orphans: [],
+                diagnostics: [`no deleted files in diff vs ${changed.ref}`],
+            }) + '\n');
+            return 0;
+        }
+        process.stdout.write(header('Deleted-symbol orphans'));
+        process.stdout.write(`No deleted files in diff vs ${changed.ref}.\n`);
+        return 0;
+    }
+    const { GraphStore, GraphQueryApi } = await import('@shrkcrft/graph');
+    if (!new GraphStore(cwd).exists()) {
+        const msg = 'code-graph store missing — run `shrk graph index` first.';
+        if (wantJson) {
+            process.stdout.write(asJson({ ok: false, error: msg }) + '\n');
+        }
+        else {
+            process.stderr.write(msg + '\n');
+        }
+        return 2;
+    }
+    const { findDeletedOrphans } = await import('@shrkcrft/impact-engine');
+    const report = findDeletedOrphans(GraphQueryApi.fromStore(cwd), deleted);
+    if (wantJson) {
+        process.stdout.write(asJson(report) + '\n');
+        return report.orphans.length > 0 ? 1 : 0;
+    }
+    process.stdout.write(header('Deleted-symbol orphans'));
+    process.stdout.write(`Deleted files (vs ${changed.ref}): ${deleted.length}\n`);
+    if (report.orphans.length === 0) {
+        process.stdout.write('no orphaned importers\n');
+        for (const d of report.diagnostics.slice(0, 5))
+            process.stdout.write(`! ${d}\n`);
+        return 0;
+    }
+    process.stdout.write(`\n${report.orphans.length} surviving importer(s) still reference deleted code:\n`);
+    for (const o of report.orphans) {
+        const loc = o.path ? `${o.path}${o.line ? `:${o.line}` : ''}` : o.id;
+        const detail = o.via === 'reference' && o.symbol
+            ? `references \`${o.symbol}\``
+            : 'imports';
+        process.stdout.write(`  ✗ ${loc} ${detail} from deleted ${o.deletedFile}\n`);
+    }
+    for (const d of report.diagnostics.slice(0, 5))
+        process.stdout.write(`! ${d}\n`);
+    return 1;
+}
 export const impactCommand = {
     name: 'impact',
     description: 'Architecture impact analysis: direct + transitive dependents, risk + suggested commands. Supports fuzzy <query> resolution. Read-only.',
-    usage: 'shrk impact <fileOrQuery> | --file <path> | --specifier <spec> | --since <ref> | --staged | --files a,b | --plan <plan.json> | --bundle <id> [--max-depth N] [--limit N] [--format text|markdown|html|json] [--output <path>] [--tree|--no-tree] [--json] [--html] [--resolve|--resolve-only|--explain-resolution|--no-resolve]',
+    usage: 'shrk impact <fileOrQuery> | --file <path> | --specifier <spec> | --since <ref> | --staged | --files a,b | --plan <plan.json> | --bundle <id> | --deleted [--since <ref>] [--max-depth N] [--limit N] [--format text|markdown|html|json] [--output <path>] [--tree|--no-tree] [--json] [--html] [--resolve|--resolve-only|--explain-resolution|--no-resolve]',
     async run(args) {
         if (args.positional[0] === 'tests') {
             return runImpactTests({ ...args, positional: args.positional.slice(1) });
@@ -299,6 +381,13 @@ export const impactCommand = {
         if (args.flags.has('via-graph')) {
             return runViaGraph(args);
         }
+        // --deleted: reverse-of-impact orphan check. Reads the working-tree
+        // diff's DELETED files and asks the graph which surviving files still
+        // import them or reference a symbol they declared. Any surviving
+        // importer is an error (its build breaks once the delete lands).
+        if (args.flags.has('deleted')) {
+            return runDeletedOrphans(args);
+        }
         const cwd = resolveCwd(args);
         const inspection = await inspectSharkcraft({ cwd });
         // Warm construct cache so fuzzy resolution can map plugin keys / events /
@@ -487,6 +576,7 @@ export const impactCommand = {
                     }
                     for (const d of fuzzyResolution.diagnostics)
                         process.stdout.write(`  ! ${d}\n`);
+                    process.stdout.write(renderFailureHints(fuzzyImpactAmbiguousHints()));
                 }
                 return 1;
             }

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

@@ -1 +1 @@
-{"version":3,"file":"knowledge.command.d.ts","sourceRoot":"","sources":["../../src/commands/knowledge.command.ts"],"names":[],"mappings":"AAkBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAoFhC,eAAO,MAAM,oBAAoB,EAAE,eA8ClC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eAuBjC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAqCpC,CAAC;AAoBF,eAAO,MAAM,0BAA0B,EAAE,eAWxC,CAAC;AA8NF,eAAO,MAAM,sBAAsB,EAAE,eAQpC,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,eA8CxC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAuBrC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,EAAE,eA8B1C,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,eA8BxC,CAAC;AAEF,eAAO,MAAM,4BAA4B,EAAE,eAkC1C,CAAC"}
+{"version":3,"file":"knowledge.command.d.ts","sourceRoot":"","sources":["../../src/commands/knowledge.command.ts"],"names":[],"mappings":"AAoBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAoGhC,eAAO,MAAM,oBAAoB,EAAE,eAgDlC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eAuBjC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAuCpC,CAAC;AAoBF,eAAO,MAAM,0BAA0B,EAAE,eAWxC,CAAC;AA8NF,eAAO,MAAM,sBAAsB,EAAE,eAQpC,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,eA8CxC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAuBrC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,EAAE,eA8B1C,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,eA8BxC,CAAC;AAEF,eAAO,MAAM,4BAA4B,EAAE,eAkC1C,CAAC"}

package/dist/commands/knowledge.command.js

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join as nodePathJoin, resolve as nodePathResolve } from 'node:path';
 import { buildAnchorUpdatePlan, buildKnowledgeStaleReport, buildRenameFilePlan, buildRenameSymbolPlan, inspectSharkcraft, ReferenceCheckOutcome, resolveChangedFiles, } from '@shrkcrft/inspector';
-import { formatEntryCompact, formatEntryFull, projectKnowledgeEntryForJson, searchKnowledge, } from '@shrkcrft/knowledge';
+import { ALL_KNOWLEDGE_TYPES, formatEntryCompact, formatEntryFull, isKnowledgeType, projectKnowledgeEntryForJson, searchKnowledge, } from '@shrkcrft/knowledge';
 import { flagBool, flagNumber, flagString, flagList, resolveCwd, } from "../command-registry.js";
 import { asJson, header } from "../output/format-output.js";
 import { maybeRunInWatchMode } from "../output/watch-loop.js";
@@ -51,6 +51,20 @@ function renderStaleCheckHtml(p) {
 ${p.ci.exitNonZero ? `<p style="color:#a40000;font-weight:bold">FAIL: ${esc(p.ci.exitReason ?? '')}</p>` : ''}
 `;
 }
+/**
+ * Validate `--type` filter values against the KnowledgeType vocabulary and
+ * reject (exit 2) on any unknown value. Without this a typo'd `--type` would
+ * silently filter every entry out and return an empty result with exit 0.
+ * Returns the exit code to propagate when a value is unknown, or null when all
+ * values are valid (or none were supplied).
+ */
+function rejectUnknownKnowledgeTypes(types) {
+    const unknown = types.filter((t) => !isKnowledgeType(t));
+    if (unknown.length === 0)
+        return null;
+    process.stderr.write(`Unknown --type ${unknown.join(', ')}. Valid: ${ALL_KNOWLEDGE_TYPES.join(', ')}\n`);
+    return 2;
+}
 export const knowledgeListCommand = {
     name: 'list',
     description: 'List knowledge entries.',
@@ -58,6 +72,9 @@ export const knowledgeListCommand = {
     async run(args) {
         const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
         const types = flagList(args, 'type');
+        const typeReject = rejectUnknownKnowledgeTypes(types);
+        if (typeReject !== null)
+            return typeReject;
         const scope = flagList(args, 'scope');
         let entries = inspection.knowledgeEntries;
         if (types.length)
@@ -129,6 +146,9 @@ export const knowledgeSearchCommand = {
         const query = args.positional.join(' ').trim();
         const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
         const types = flagList(args, 'type');
+        const typeReject = rejectUnknownKnowledgeTypes(types);
+        if (typeReject !== null)
+            return typeReject;
         const scope = flagList(args, 'scope');
         const tags = flagList(args, 'tag');
         const appliesWhen = flagList(args, 'appliesWhen');

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

@@ -1 +1 @@
-{"version":3,"file":"onboard.command.d.ts","sourceRoot":"","sources":["../../src/commands/onboard.command.ts"],"names":[],"mappings":"AA6CA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC,eAAO,MAAM,cAAc,EAAE,eA4N5B,CAAC"}
+{"version":3,"file":"onboard.command.d.ts","sourceRoot":"","sources":["../../src/commands/onboard.command.ts"],"names":[],"mappings":"AA6CA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC,eAAO,MAAM,cAAc,EAAE,eAwO5B,CAAC"}

package/dist/commands/onboard.command.js

@@ -14,13 +14,22 @@ export const onboardCommand = {
             return runOnboardAdopt(sliced);
         }
         const cwd = resolveCwd(args);
-        const writeDrafts = flagBool(args, 'write-drafts');
+        const writeDraftsFlag = flagBool(args, 'write-drafts');
+        const dryRunFlag = flagBool(args, 'dry-run');
+        // --dry-run is authoritative: it overrides --write-drafts so that
+        // `onboard --dry-run --write-drafts` never writes. `writeDrafts` below is
+        // the EFFECTIVE value used by every write guard / mode label.
+        const writeDrafts = writeDraftsFlag && !dryRunFlag;
+        const dryRunOverrodeWrite = writeDraftsFlag && dryRunFlag;
         const scaffoldTemplates = flagBool(args, 'scaffold-templates');
         const importAgents = flagBool(args, 'import-agents');
         const diffMode = flagBool(args, 'diff');
-        const dryRun = flagBool(args, 'dry-run') || !writeDrafts;
+        const dryRun = !writeDrafts;
         const preferredPreset = flagString(args, 'preset');
         const asJsonOut = flagBool(args, 'json');
+        if (dryRunOverrodeWrite) {
+            process.stderr.write('Note: --dry-run overrode --write-drafts; no files were written.\n');
+        }
         const inspection = await inspectSharkcraft({ cwd });
         const plan = buildOnboardingPlan(inspection, {
             ...(preferredPreset ? { preferredPreset } : {}),

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

@@ -1 +1 @@
-{"version":3,"file":"orchestrate.command.d.ts","sourceRoot":"","sources":["../../src/commands/orchestrate.command.ts"],"names":[],"mappings":"AASA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC,eAAO,MAAM,kBAAkB,EAAE,eA8ChC,CAAC"}
+{"version":3,"file":"orchestrate.command.d.ts","sourceRoot":"","sources":["../../src/commands/orchestrate.command.ts"],"names":[],"mappings":"AASA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAKhC,eAAO,MAAM,kBAAkB,EAAE,eAoDhC,CAAC"}

package/dist/commands/orchestrate.command.js

@@ -3,10 +3,11 @@ import * as nodePath from 'node:path';
 import { buildAgentOrchestrationPlan, inspectSharkcraft, OrchestrationMode, renderOrchestrationMarkdown, renderOrchestrationText, } from '@shrkcrft/inspector';
 import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
 import { asJson } from "../output/format-output.js";
+const VALID_ORCHESTRATION_MODES = ['conservative', 'balanced', 'aggressive'];
 export const orchestrateCommand = {
     name: 'orchestrate',
     description: 'Produce a read-only agent orchestration plan (discovery / plan / review / apply / validate). No execution; no writes.',
-    usage: 'shrk orchestrate "<task>" [--mode conservative|balanced|aggressive] [--bundle] [--session] [--json] [--output <file.md>]',
+    usage: 'shrk orchestrate "<task>" [--mode conservative|balanced|aggressive] [--json] [--output <file.md>]',
     async run(args) {
         const task = args.positional.join(' ').trim();
         if (!task) {
@@ -16,6 +17,10 @@ export const orchestrateCommand = {
         const cwd = resolveCwd(args);
         const inspection = await inspectSharkcraft({ cwd });
         const modeRaw = (flagString(args, 'mode') ?? '').toLowerCase();
+        // Warn on a typo'd --mode rather than silently treating it as balanced.
+        if (modeRaw && !VALID_ORCHESTRATION_MODES.includes(modeRaw)) {
+            process.stderr.write(`Unknown --mode ${modeRaw}. Valid: ${VALID_ORCHESTRATION_MODES.join(', ')} (defaulting to balanced).\n`);
+        }
         const mode = modeRaw === 'conservative'
             ? OrchestrationMode.Conservative
             : modeRaw === 'aggressive'

package/dist/commands/pack-author.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pack-author.command.d.ts","sourceRoot":"","sources":["../../src/commands/pack-author.command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAaH,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAuChC,eAAO,MAAM,uBAAuB,EAAE,eA2BrC,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,eAoFtC,CAAC;AAKF,eAAO,MAAM,wBAAwB,EAAE,eAgCtC,CAAC;AAEF,eAAO,MAAM,yBAAyB,EAAE,eAgBvC,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,EAAE,eA2BlC,CAAC"}
+{"version":3,"file":"pack-author.command.d.ts","sourceRoot":"","sources":["../../src/commands/pack-author.command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAaH,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAuChC,eAAO,MAAM,uBAAuB,EAAE,eA2CrC,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,eAoFtC,CAAC;AAKF,eAAO,MAAM,wBAAwB,EAAE,eAgCtC,CAAC;AAEF,eAAO,MAAM,yBAAyB,EAAE,eAgBvC,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,EAAE,eA2BlC,CAAC"}

package/dist/commands/pack-author.command.js

@@ -49,8 +49,16 @@ export const packAuthorStatusCommand = {
         const cwd = resolveCwd(args);
         const inspection = await inspectSharkcraft({ cwd });
         const status = buildPackAuthorStatus(inspection);
+        // Freshness: the pack authoring state is stale (relative to a signed,
+        // applied baseline) while drafts are pending — they have been authored
+        // since the last apply/sign but not yet incorporated.
+        const state = status.pendingDrafts > 0 ? 'stale' : 'fresh';
         if (flagBool(args, 'json')) {
-            process.stdout.write(asJson(status) + '\n');
+            process.stdout.write(asJson({
+                ...status,
+                state,
+                ...(state === 'stale' ? { nextCommand: 'shrk pack author pending' } : {}),
+            }) + '\n');
             return 0;
         }
         process.stdout.write(header('Pack author status'));
@@ -60,6 +68,10 @@ export const packAuthorStatusCommand = {
         process.stdout.write(`  pending drafts: ${status.pendingDrafts}\n`);
         for (const f of status.pendingDraftFiles)
             process.stdout.write(`    - ${f}\n`);
+        process.stdout.write(`  state: ${state}\n`);
+        if (state === 'stale') {
+            process.stdout.write(`  ! stale — ${status.pendingDrafts} pending draft(s) authored since the last apply/sign; run \`shrk pack author pending\`\n`);
+        }
         process.stdout.write('  contribution counts:\n');
         for (const [k, n] of Object.entries(status.contributionCounts)) {
             const support = status.authoringSupport[k] ?? 'deferred';

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

@@ -1 +1 @@
-{"version":3,"file":"packs.command.d.ts","sourceRoot":"","sources":["../../src/commands/packs.command.ts"],"names":[],"mappings":"AAoBA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAQhC,eAAO,MAAM,yBAAyB,EAAE,eAoCvC,CAAC;AAEF,eAAO,MAAM,2BAA2B,EAAE,eAsGzC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eA+CnC,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,eAuD9B,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,eAsE7B,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eAqDjC,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,eAyFhC,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,eAqEhC,CAAC;AA4DF,eAAO,MAAM,gBAAgB,EAAE,eA+K9B,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,eAmCtC,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,eAmFhC,CAAC;AAMF,eAAO,MAAM,qBAAqB,EAAE,eA4BnC,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,eA+E/B,CAAC"}
+{"version":3,"file":"packs.command.d.ts","sourceRoot":"","sources":["../../src/commands/packs.command.ts"],"names":[],"mappings":"AAoBA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAQhC,eAAO,MAAM,yBAAyB,EAAE,eAoCvC,CAAC;AAEF,eAAO,MAAM,2BAA2B,EAAE,eAsGzC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eA+CnC,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,eAwD9B,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,eAyE7B,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eAqDjC,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,eAoGhC,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,eA2IhC,CAAC;AA4DF,eAAO,MAAM,gBAAgB,EAAE,eA+K9B,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,eAmCtC,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,eAmFhC,CAAC;AAMF,eAAO,MAAM,qBAAqB,EAAE,eA4BnC,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,eA+E/B,CAAC"}

package/dist/commands/packs.command.js

@@ -201,6 +201,7 @@ export const packsListCommand = {
                 resolvedCounts: p.resolvedCounts,
                 signatureStatus: p.signatureStatus,
                 signatureMessage: p.signatureMessage,
+                signatureDev: p.signatureDev,
                 loadError: p.loadError,
                 validationIssues: p.validationIssues,
             }))) + '\n');
@@ -282,6 +283,9 @@ export const packsGetCommand = {
         if (pack.signatureStatus) {
             process.stdout.write('\nSignature:\n');
             process.stdout.write(`  status:  ${pack.signatureStatus}\n`);
+            if (pack.signatureDev) {
+                process.stdout.write('  dev:     yes (NOT release-trusted)\n');
+            }
             if (pack.signatureMessage) {
                 process.stdout.write(`  message: ${pack.signatureMessage}\n`);
             }
@@ -355,20 +359,30 @@ export const packsInspectCommand = {
 export const packsDoctorCommand = {
     name: 'doctor',
     description: 'Validate pack discovery: invalid manifests, missing files, empty contributions, duplicates, template/pipeline quality, action-hint coverage, signatures. `--release` folds pack-release-check findings into the report. `--signature-explain` adds per-pack signature explanation.',
-    usage: 'shrk [--cwd <dir>] packs doctor [--verify-signatures] [--require-signatures] [--release] [--strict] [--secret <secret>] [--signature-explain] [--json]',
+    usage: 'shrk [--cwd <dir>] packs doctor [--verify-signatures] [--require-signatures] [--allow-dev-signature] [--release] [--strict] [--secret <secret>] [--signature-explain] [--json]',
     async run(args) {
-        const verify = flagBool(args, 'verify-signatures') || flagBool(args, 'require-signatures');
+        const signatureExplain = flagBool(args, 'signature-explain');
+        // `--signature-explain` implies signature verification so the lifecycle
+        // states it prints are backed by a real HMAC check this run — otherwise a
+        // bogus-HMAC-but-fresh-timestamp pack would be reported off freshness
+        // alone instead of the honest "invalid".
+        const verify = flagBool(args, 'verify-signatures') ||
+            flagBool(args, 'require-signatures') ||
+            signatureExplain;
         const required = flagBool(args, 'require-signatures');
         const release = flagBool(args, 'release');
         const strict = flagBool(args, 'strict');
         const secret = flagString(args, 'secret');
-        const signatureExplain = flagBool(args, 'signature-explain');
+        const allowDev = flagBool(args, 'allow-dev-signature');
         const inspection = await inspectSharkcraft({
             cwd: resolveCwd(args),
             ...(verify ? { verifyPackSignatures: true } : {}),
             ...(secret !== undefined ? { packSecret: secret } : {}),
         });
-        const report = buildPackDoctorReport(inspection, { requireSignatures: required });
+        const report = buildPackDoctorReport(inspection, {
+            requireSignatures: required,
+            ...(allowDev ? { allowDevSignatures: true } : {}),
+        });
         if (release) {
             const releaseChecks = await runPackReleaseChecksForReport(inspection);
             mergePackReleaseChecks(inspection, report, releaseChecks, { strict });
@@ -439,32 +453,93 @@ export const packsDoctorCommand = {
 };
 export const packsVerifyCommand = {
     name: 'verify',
-    description: 'Verify HMAC signatures on every discovered pack. Unsigned packs are reported but do not fail.',
-    usage: 'shrk [--cwd <dir>] packs verify [--secret <secret>] [--required] [--json]',
+    description: 'Verify HMAC signatures on every discovered pack. Unsigned packs are reported but do not fail. Under --required, a signed pack that could not be verified (no secret) or that carries a dev signature fails too — pass --allow-dev-signature to trust dev signatures for local-only flows.',
+    usage: 'shrk [--cwd <dir>] packs verify [--secret <secret>] [--required] [--allow-dev-signature] [--json]',
     async run(args) {
         const secret = flagString(args, 'secret');
+        const allowDev = flagBool(args, 'allow-dev-signature');
         const inspection = await inspectSharkcraft({
             cwd: resolveCwd(args),
             verifyPackSignatures: true,
             ...(secret !== undefined ? { packSecret: secret } : {}),
         });
         const required = flagBool(args, 'required');
-        const rows = inspection.packs.discoveredPacks.map((p) => ({
-            packageName: p.packageName,
-            packageVersion: p.packageVersion,
-            valid: p.valid,
-            signatureStatus: p.signatureStatus ?? 'not-checked',
-            signatureMessage: p.signatureMessage,
-        }));
+        const rows = inspection.packs.discoveredPacks.map((p) => {
+            let signatureStatus = (p.signatureStatus ?? 'not-checked');
+            let signatureMessage = p.signatureMessage;
+            let signatureDev = p.signatureDev === true;
+            // --allow-dev-signature: actually run the HMAC check against the
+            // well-known dev secret so a *tampered* dev signature still fails. The
+            // default discovery path short-circuits to 'dev-signature' BEFORE
+            // hashing, so we must re-verify here rather than blindly trust the tag.
+            if (allowDev && signatureStatus === 'dev-signature' && p.manifest) {
+                const v = verifyPackManifest(p.manifest, {
+                    allowDev: true,
+                    ...(secret !== undefined ? { secret } : {}),
+                });
+                signatureStatus = (v.ok ? 'verified' : v.status);
+                signatureMessage = v.ok ? 'Dev signature verified (--allow-dev-signature).' : v.message;
+                signatureDev = true;
+            }
+            return {
+                packageName: p.packageName,
+                packageVersion: p.packageVersion,
+                valid: p.valid,
+                signatureStatus,
+                signatureMessage,
+                signatureDev,
+            };
+        });
         const tampered = rows.some((r) => r.signatureStatus === 'invalid-signature');
         const unsigned = rows.some((r) => r.signatureStatus === 'missing-signature');
-        const passed = !tampered && (!required || !unsigned);
+        // A SIGNED pack we could NOT actually verify this run: the secret was
+        // missing, or it carries a dev signature that is not release-trusted (and
+        // --allow-dev-signature was not passed). Reporting these as "OK" was the
+        // fail-open hole — required verification that could not run must FAIL.
+        const missingSecretCount = rows.filter((r) => r.signatureStatus === 'missing-secret').length;
+        const devCount = rows.filter((r) => r.signatureStatus === 'dev-signature').length;
+        const unverifiable = missingSecretCount > 0 || devCount > 0;
+        const signedCount = rows.filter((r) => r.signatureStatus !== 'missing-signature' && r.signatureStatus !== 'not-checked').length;
+        const verifiedCount = rows.filter((r) => r.signatureStatus === 'verified').length;
+        const allSignedVerified = signedCount > 0 && verifiedCount === signedCount;
+        const passed = !tampered && (!required || (!unsigned && !unverifiable));
+        const verdict = (() => {
+            if (tampered)
+                return 'TAMPERED pack detected — abort!';
+            if (required && (unverifiable || unsigned)) {
+                const bits = [];
+                if (missingSecretCount > 0)
+                    bits.push(`${missingSecretCount} signed pack(s) could not be verified (no secret) — set ${PACK_SECRET_ENV}`);
+                if (devCount > 0)
+                    bits.push(`${devCount} dev-signed pack(s) are not release-trusted — pass --allow-dev-signature to accept them`);
+                if (unsigned)
+                    bits.push('unsigned pack present');
+                return bits.join('; ');
+            }
+            if (allSignedVerified && !unsigned && !unverifiable)
+                return 'all signatures OK ✓';
+            if (unverifiable || unsigned) {
+                const bits = [];
+                if (missingSecretCount > 0)
+                    bits.push(`${missingSecretCount} signed pack(s) unverified (no secret)`);
+                if (devCount > 0)
+                    bits.push(`${devCount} dev-signed pack(s) not release-trusted`);
+                if (unsigned)
+                    bits.push('unsigned pack present');
+                return bits.join('; ') + ' (use --required to fail)';
+            }
+            return signedCount > 0 ? 'all signatures OK ✓' : 'no signatures to verify';
+        })();
         if (flagBool(args, 'json')) {
             process.stdout.write(asJson({
                 passed,
                 required,
+                allowDevSignature: allowDev,
                 tampered,
                 unsignedPresent: unsigned,
+                unverifiable,
+                unverifiableCount: missingSecretCount,
+                devSignatureCount: devCount,
                 packs: rows,
             }) + '\n');
             return passed ? 0 : 1;
@@ -483,10 +558,13 @@ export const packsVerifyCommand = {
                         ? 'UNSIGNED'
                         : r.signatureStatus === 'missing-secret'
                             ? 'NO SECRET'
-                            : 'NOT CHECKED';
-            process.stdout.write(`  ${tag.padEnd(12)} ${r.packageName.padEnd(40)} ${r.signatureMessage ?? ''}\n`);
+                            : r.signatureStatus === 'dev-signature'
+                                ? 'DEV'
+                                : 'NOT CHECKED';
+            const devNote = r.signatureStatus === 'dev-signature' ? ' (not release-trusted)' : '';
+            process.stdout.write(`  ${tag.padEnd(12)} ${r.packageName.padEnd(40)} ${r.signatureMessage ?? ''}${devNote}\n`);
         }
-        process.stdout.write(`\nVerdict: ${passed ? 'all signatures OK ✓' : tampered ? 'TAMPERED pack detected — abort!' : 'unsigned pack present (use --required to fail)'}\n`);
+        process.stdout.write(`\nVerdict: ${verdict}\n`);
         if (!secret && !process.env[PACK_SECRET_ENV]) {
             process.stdout.write(`(Tip: set ${PACK_SECRET_ENV} or pass --secret to verify signed packs.)\n`);
         }

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

@@ -1 +1 @@
-{"version":3,"file":"paths.command.d.ts","sourceRoot":"","sources":["../../src/commands/paths.command.ts"],"names":[],"mappings":"AAEA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC,eAAO,MAAM,gBAAgB,EAAE,eAmB9B,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,eAuB7B,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,eAsBhC,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,eA0B9B,CAAC"}
+{"version":3,"file":"paths.command.d.ts","sourceRoot":"","sources":["../../src/commands/paths.command.ts"],"names":[],"mappings":"AAEA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC,eAAO,MAAM,gBAAgB,EAAE,eAmB9B,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,eAuB7B,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,eAsBhC,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,eAiC9B,CAAC"}

package/dist/commands/paths.command.js

@@ -82,11 +82,18 @@ export const pathsBestCommand = {
         }
         const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
         const selection = inspection.pathService.findBestForTask(task);
+        const wantJson = flagBool(args, 'json');
         if (!selection) {
+            // Keep `--json` machine-parseable on a miss: emit `{match:null}` rather
+            // than the human sentence so a consumer can `JSON.parse` the output.
+            if (wantJson) {
+                process.stdout.write(asJson({ match: null }) + '\n');
+                return 0;
+            }
             process.stdout.write('No matching path convention.\n');
             return 0;
         }
-        if (flagBool(args, 'json')) {
+        if (wantJson) {
             process.stdout.write(asJson(selection) + '\n');
             return 0;
         }

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

@@ -1 +1 @@
-{"version":3,"file":"pipelines.command.d.ts","sourceRoot":"","sources":["../../src/commands/pipelines.command.ts"],"names":[],"mappings":"AAUA,OAAO,EAOL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC,eAAO,MAAM,oBAAoB,EAAE,eA2BlC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eAuBjC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAsDrC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eA+DlC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAoCpC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eA6ClC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAiElC,CAAC"}
+{"version":3,"file":"pipelines.command.d.ts","sourceRoot":"","sources":["../../src/commands/pipelines.command.ts"],"names":[],"mappings":"AAeA,OAAO,EAOL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC,eAAO,MAAM,oBAAoB,EAAE,eA2BlC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eAuBjC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAuDrC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eA+DlC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAoCpC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eA6ClC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAiElC,CAAC"}

package/dist/commands/pipelines.command.js

@@ -1,4 +1,4 @@
-import { inspectSharkcraft, buildProjectOverview, renderOverviewText } from '@shrkcrft/inspector';
+import { inspectSharkcraft, buildProjectOverview, renderOverviewText, contextTuningBoostFor, } from '@shrkcrft/inspector';
 import { buildContext } from '@shrkcrft/context';
 import { findNextStep, formatPipelineCompact, formatPipelineFull, interpolatePipeline, renderPipelineScript, } from '@shrkcrft/pipelines';
 import { flagBool, flagNumber, flagString, flagList, flagVars, resolveCwd, } from "../command-registry.js";
@@ -81,6 +81,7 @@ export const pipelinesContextCommand = {
             scope,
             maxTokens,
             projectOverview: renderOverviewText(overview),
+            boostFor: contextTuningBoostFor(inspection, task),
         });
         if (flagBool(args, 'json')) {
             process.stdout.write(asJson({

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

@@ -1 +1 @@
-{"version":3,"file":"plan-context.command.d.ts","sourceRoot":"","sources":["../../src/commands/plan-context.command.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,EAAE,eAsEhC,CAAC"}
+{"version":3,"file":"plan-context.command.d.ts","sourceRoot":"","sources":["../../src/commands/plan-context.command.ts"],"names":[],"mappings":"AACA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,EAAE,eAyEhC,CAAC"}

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

@@ -1,5 +1,5 @@
 import { planContext } from '@shrkcrft/context-planner';
-import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { flagBool, flagPositiveInt, flagString, resolveCwd, } from "../command-registry.js";
 import { asJson, header, kv } from "../output/format-output.js";
 /**
  * `shrk plan-context` — produce a deterministic, token-budgeted context
@@ -21,8 +21,11 @@ export const planContextCommand = {
             process.stderr.write(this.usage + '\n');
             return 2;
         }
-        const budget = Number(flagString(args, 'budget') ?? '8000');
-        const maxFiles = Number(flagString(args, 'max-files') ?? '30');
+        // NaN-safe: a fat-fingered `--budget abc` would otherwise become NaN and
+        // print "NaN tokens" while selecting 0 files at exit 0. Fall back to the
+        // documented defaults instead.
+        const budget = flagPositiveInt(args, 'budget', 8000);
+        const maxFiles = flagPositiveInt(args, 'max-files', 30);
         const hintedFiles = collectMulti(args, 'hint-file');
         const hintedPackages = collectMulti(args, 'hint-package');
         const pack = planContext({

package/dist/commands/plan-simulate.command.js

@@ -6,7 +6,7 @@ import { asJson } from "../output/format-output.js";
 export const planSimulateCommand = {
     name: 'simulate',
     description: 'Simulate a saved generation plan (v1 or v2): virtual final content, classified operations, boundary/policy/impact/test gates, apply readiness. Read-only.',
-    usage: 'shrk plan simulate <plan.json> [--format text|markdown|html|json] [--output <file>] [--strict] [--include-boundaries] [--include-impact] [--include-tests] [--include-policies] [--include-ownership] [--include-memory] [--diff] [--max-diff-lines N]',
+    usage: 'shrk plan simulate <plan.json> [--format text|markdown|html|json] [--output <file>] [--strict] [--no-boundaries] [--no-impact] [--no-tests] [--no-policies] [--no-ownership] [--include-memory] [--diff] [--max-diff-lines N]',
     async run(args) {
         const planPath = args.positional[0];
         if (!planPath) {

package/dist/commands/policy-lint.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"policy-lint.command.d.ts","sourceRoot":"","sources":["../../src/commands/policy-lint.command.ts"],"names":[],"mappings":"AAKA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAKhC,eAAO,MAAM,iBAAiB,EAAE,eAiI/B,CAAC"}
+{"version":3,"file":"policy-lint.command.d.ts","sourceRoot":"","sources":["../../src/commands/policy-lint.command.ts"],"names":[],"mappings":"AAIA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAKhC,eAAO,MAAM,iBAAiB,EAAE,eAkJ/B,CAAC"}

package/dist/commands/policy-lint.command.js

@@ -1,7 +1,6 @@
 import * as nodePath from 'node:path';
 import { runPolicyLint } from '@shrkcrft/boundaries';
-import { loadProjectConfig } from '@shrkcrft/config';
-import { resolveChangedFiles } from '@shrkcrft/inspector';
+import { resolveChangedFiles, resolveProjectConfig } from '@shrkcrft/inspector';
 import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
 import { asJson, header, kv } from "../output/format-output.js";
 const VALID_SURFACES = new Set(['template', 'style', 'ts']);
@@ -27,11 +26,11 @@ export const policyLintCommand = {
             surfaces = parts;
         }
         // Distinguish invalid config from valid-with-no-rules (no silent fail-open).
-        const loaded = await loadProjectConfig(cwd);
+        const loaded = await resolveProjectConfig(cwd);
         if (!loaded.ok) {
             const msg = loaded.error.message;
             if (wantJson) {
-                process.stdout.write(asJson({ schema: 'sharkcraft.policy-lint/v1', error: msg, rules: [], findings: [], diagnostics: [msg], verdict: 'errors' }) + '\n');
+                process.stdout.write(asJson({ schema: 'sharkcraft.policy-lint/v1', error: msg, rules: [], findings: [], diagnostics: [msg], evaluated: 0, verdict: 'errors' }) + '\n');
                 return 1;
             }
             process.stdout.write(header('Policy lint'));
@@ -39,9 +38,10 @@ export const policyLintCommand = {
             return 1;
         }
         const rules = loaded.value.config.policyRules ?? [];
+        const planeDiagnostics = loaded.value.planeDiagnostics;
         if (rules.length === 0) {
             if (wantJson) {
-                process.stdout.write(asJson({ schema: 'sharkcraft.policy-lint/v1', rules: [], findings: [], diagnostics: [], verdict: 'pass' }) + '\n');
+                process.stdout.write(asJson({ schema: 'sharkcraft.policy-lint/v1', rules: [], findings: [], diagnostics: [], evaluated: 0, verdict: 'pass' }) + '\n');
                 return 0;
             }
             process.stdout.write(header('Policy lint'));
@@ -71,18 +71,31 @@ export const policyLintCommand = {
         // hold the rule definitions themselves, which can self-match).
         const sharkcraftRel = nodePath.relative(cwd, loaded.value.sharkcraftDir).split(nodePath.sep).join('/');
         const excludeDirs = sharkcraftRel && !sharkcraftRel.startsWith('..') ? [sharkcraftRel] : [];
-        const report = runPolicyLint(cwd, rules, {
+        const reportRaw = runPolicyLint(cwd, rules, {
             ...(surfaces ? { surfaces } : {}),
             ...(changedOnly || since ? { changedOnly: true, changedFiles: changedFiles ?? [] } : {}),
             ...(only ? { only: only.split(',').map((s) => s.trim()).filter(Boolean) } : {}),
             ...(excludeDirs.length > 0 ? { excludeDirs } : {}),
         });
+        // Surface pack-plane merge notes (missing/invalid pack policy files, dropped
+        // collisions) in the same diagnostics array the engine already emits.
+        const report = planeDiagnostics.length > 0
+            ? { ...reportRaw, diagnostics: [...reportRaw.diagnostics, ...planeDiagnostics] }
+            : reportRaw;
         if (wantJson) {
             process.stdout.write(asJson(report) + '\n');
             return report.verdict === 'errors' ? 1 : 0;
         }
         process.stdout.write(header('Policy lint'));
-        process.stdout.write(kv('rules evaluated', String(report.rules.length)) + '\n');
+        // `evaluated` counts rules that actually scanned ≥1 file. When 0 rules
+        // evaluated but rules ARE configured, say so loudly — "scanned nothing" must
+        // never read as the green "no policy violations" pass.
+        if (report.evaluated === 0) {
+            process.stdout.write(`  ! Nothing evaluated — ${report.rules.length} rule(s) configured but none matched files in scope` +
+                (changedOnly || since ? ' (changed-only).\n' : '.\n'));
+            return 0;
+        }
+        process.stdout.write(kv('rules evaluated', `${report.evaluated} of ${report.rules.length}`) + '\n');
         const errors = report.findings.filter((f) => f.severity === 'error').length;
         const warnings = report.findings.filter((f) => f.severity === 'warning').length;
         process.stdout.write(kv('findings', `${errors} error(s), ${warnings} warning(s)`) + '\n');

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

@@ -1 +1 @@
-{"version":3,"file":"recommend.command.d.ts","sourceRoot":"","sources":["../../src/commands/recommend.command.ts"],"names":[],"mappings":"AAUA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAShC,eAAO,MAAM,gBAAgB,EAAE,eAkP9B,CAAC;AA0HF;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAY3D;AAcD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAcxD"}
+{"version":3,"file":"recommend.command.d.ts","sourceRoot":"","sources":["../../src/commands/recommend.command.ts"],"names":[],"mappings":"AAUA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAShC,eAAO,MAAM,gBAAgB,EAAE,eA4P9B,CAAC;AA0HF;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAY3D;AAcD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAcxD"}