@shrkcrft/inspector 0.1.0-alpha.30 → 0.1.0-alpha.31

package/dist/command-recommender.js

@@ -1,277 +1,55 @@
-/**
- * Deterministic command recommender.
- *
- * Given an input ("what I want to do" or stderr blob), surface the
- * most relevant commands from the catalog + diagnostics + start-here
- * flow + intent classification. No AI, no embeddings.
- */
-import { classifyChangeIntent, ChangeIntentKind } from "./change-intent.js";
-import { buildDiagnosticByCode, listDiagnostics } from "./failure-diagnostics.js";
-import { rankAll } from "./task-ranker.js";
-import { buildUncertaintyReport, } from "./uncertainty-report.js";
+import { rankRecommendationCandidates } from "./recommendation-ranking.js";
+import { buildUncertaintyReport } from "./uncertainty-report.js";
 export const COMMAND_RECOMMENDER_SCHEMA = 'sharkcraft.command-recommender/v1';
-const RECIPES = [
-    {
-        match: /review|pr|pull[-\s]?request/i,
-        recommendations: [
-            { command: 'shrk review packet --v3 --since main', why: 'Generate an agent-ready PR review packet.' },
-            { command: 'shrk impact --since main', why: 'See what changed and what depends on it.' },
-            { command: 'shrk report site --output .sharkcraft/reports/site', why: 'Render the local read-only review site.' },
-        ],
-    },
-    {
-        match: /start|begin|new task|feature/i,
-        recommendations: [
-            { command: 'shrk brief "<task>"', why: 'Pre-work brief for the agent.' },
-            { command: 'shrk dev start "<task>"', why: 'Start a tracked dev session.' },
-            { command: 'shrk intent "<task>"', why: 'Classify the change intent first.' },
-        ],
-    },
-    {
-        match: /publish|release|tag|alpha|beta/i,
-        recommendations: [
-            { command: 'shrk release readiness --strict', why: 'Confirm release gates.' },
-            { command: 'shrk release smoke --scenario all', why: 'Validate the release smoke matrix.' },
-            { command: 'bun run release:preflight', why: 'Run the full preflight.' },
-        ],
-    },
-    {
-        match: /pack/i,
-        recommendations: [
-            { command: 'shrk packs doctor --release --require-signatures', why: 'Validate discovered packs.' },
-            { command: 'shrk packs compat <pack> --consumer-root .', why: 'Detect helper/symbol-missing issues.' },
-            { command: 'shrk packs quality <path>', why: 'Score pack maturity.' },
-        ],
-    },
-    {
-        match: /boundary|architecture|layer/i,
-        recommendations: [
-            { command: 'shrk architecture map', why: 'Layered architecture summary.' },
-            { command: 'shrk check boundaries', why: 'Boundary scan.' },
-            { command: 'shrk drift', why: 'Drift report.' },
-        ],
-    },
-    {
-        match: /code[-\s]?intel|code intelligence|code graph|graph status|graph health|import cycle|unresolved import|blast radius|callers|dependents|who calls|who uses|where is .*\bused|find usages|usages? of|is .*\bwired|wired (up|to)|wire[ds]? .*\bto\b|path (from|between)|reach(es|able)|connected to|who implements|implementations? of|subclass|subtype|load[-\s]?bearing|\bhubs?\b|most[-\s](depended|imported|referenced)|what.*change carefully|important.*\b(code|files?|symbols?)|what breaks if|what calls|call sites?|trace .*\b(symbol|function|usage)/i,
-        recommendations: [
-            { command: 'shrk graph callers <symbol>', why: 'Who calls / references a symbol, as path:line — the grep replacement for "who calls X / where is X used".' },
-            { command: 'shrk graph path <from> <to>', why: 'Is code A actually wired to code B? Shortest import/call/implements path between two files or symbols — the deterministic answer to "is X wired to Y".' },
-            { command: 'shrk graph hubs', why: 'The most-depended-on symbols/files (biggest blast radius) — what to change carefully or understand first when onboarding.' },
-            { command: 'shrk graph context <file-or-symbol>', why: 'Inspect one file or symbol with imports, callers, subtypes/supertypes, bridge context, and framework hits — answers "is X wired".' },
-            { command: 'shrk graph impact <file-or-symbol> --full', why: 'What breaks if you change it: graph-backed dependents, caller files, rules, and likely tests.' },
-            { command: 'shrk code-intel', why: 'One-shot health view across the code graph, bridge, and quality gates.' },
-            { command: 'shrk graph status', why: 'Check whether the code graph is present, fresh, and internally consistent.' },
-            { command: 'shrk graph unresolved', why: 'Find unresolved imports that undercut graph accuracy.' },
-        ],
-    },
-    {
-        match: /delegate|mechanical (edit|task|change|refactor)|grunt (work|task)|boilerplate|repetitive edit|hand (this|it|off) (off |over )?to (a |the )?(local |worker|model)|add (a |an )?(barrel )?(export|import)\b|local (llm|model) (do|handle|make)/i,
-        recommendations: [
-            { command: 'shrk delegate list', why: 'See the MECHANICAL task recipes a local-LLM worker can handle (the engine verifies the result + auto-reverts on failure). Each is fenced to specific files + op kinds.' },
-            { command: 'shrk delegate run "<task>" --recipe <id> --apply', why: 'Hand a mechanical, deterministically-verifiable edit to the LOCAL worker — you pay for a compact brief + result instead of reading the whole file and writing the edit. The edit lands only if it passes the recipe verification.' },
-            { command: 'shrk delegate explain <id>', why: 'Audit a recipe before trusting it: the allowed ops, guardrail globs, and whether its verification is bound.' },
-        ],
-    },
-];
-function safetyLevelFor(command) {
-    if (/^shrk delegate run/i.test(command))
-        return 'writes-source';
-    if (/^shrk (gen|init|apply|import|presets apply --write|packs (sign|new))/i.test(command))
-        return 'writes-source';
-    if (/^shrk (onboard|brief|dev start|handoff|export|report site|impact|ci scaffold|simulate|orchestrate)/i.test(command))
-        return 'writes-drafts';
-    if (/^shrk (session|dev report)/i.test(command))
-        return 'writes-session';
-    if (/^bun |^npm |^node |^git /i.test(command))
-        return 'runs-shell';
-    return 'read-only';
-}
-/**
- * Minimum `rankAll` template score to treat the shared ranker's top template as
- * a strong, intent-confirmed structured match. Real template matches score well
- * into double digits; unrelated templates don't match at all — so this bar
- * cleanly separates a genuine scaffold target from noise. Above it, a keyword
- * recipe that only overlapped a single word no longer gets to headline.
- */
-const RANKER_TEMPLATE_PROMOTE_THRESHOLD = 6;
-/**
- * Minimum `rankAll` pipeline score to let the matched pipeline lead. Higher than
- * the template bar: a generic catch-all pipeline scores low on noise but high on
- * a real scaffolding task, so the bar excludes that baseline.
- */
-const RANKER_PIPELINE_PROMOTE_THRESHOLD = 8;
-const SCAFFOLD_VERBS = new Set([
-    'create', 'build', 'add', 'generate', 'scaffold', 'implement', 'make', 'new', 'introduce', 'write',
-]);
-/**
- * Does the query read like create/build/scaffold work? Gate for ranker-driven
- * `gen <template>` promotion: a strong template token-overlap on a NON-scaffold
- * verb (e.g. "document the cli-command template") must not be routed to a
- * generator. Mirrors the CLI's `looksLikeCreateBuild` (kept local — the
- * inspector layer cannot import the cli layer).
- */
-function looksLikeScaffolding(query) {
-    const tokens = query
-        .toLowerCase()
-        .replace(/[^a-z0-9\s]/g, ' ')
-        .split(/\s+/)
-        .filter((t) => t.length > 0);
-    if (tokens.length === 0)
-        return false;
-    if (SCAFFOLD_VERBS.has(tokens[0]))
-        return true;
-    for (let i = 1; i < Math.min(4, tokens.length); i++) {
-        if (SCAFFOLD_VERBS.has(tokens[i]))
-            return true;
-    }
-    return false;
+/** One report row from a ranked candidate. */
+export function toCommandRecommendation(c) {
+    return {
+        command: c.command,
+        why: c.why,
+        safetyLevel: c.safetyLevel,
+        ...(c.docsLink ? { docsLink: c.docsLink } : {}),
+        source: c.source,
+        ...(c.sourceId !== undefined ? { sourceId: c.sourceId } : {}),
+        score: c.normalisedScore,
+        weak: c.weak,
+        attribution: c.attribution,
+    };
 }
-export async function recommendCommands(inspection, query, options = {}) {
-    const warnings = [];
-    const trimmed = query.trim();
-    let recommendations = [];
-    // Recipe matching by query.
-    for (const r of RECIPES) {
-        if (r.match.test(trimmed)) {
-            for (const rec of r.recommendations)
-                recommendations.push({ ...rec, safetyLevel: safetyLevelFor(rec.command) });
-        }
-    }
-    // ── Ranker arbitration ────────────────────────────────────────────────
-    // A keyword recipe matches on a single overlapping word (e.g. "release" in
-    // "create a cli command for the release tooling"), which would otherwise
-    // route a scaffolding intent to unrelated review/release tooling. Consult
-    // the SAME shared ranker that `brief`/`task` use: when it confirms a concrete
-    // template/pipeline for a create/build query, promote `shrk gen <template>`
-    // (or the pipeline packet) to the HEADLINE so the recipe keyword no longer
-    // hijacks the route. Mirrors the CLI's R1 routing-hint promotion.
-    let promotedRanker;
-    if (trimmed.length > 0 && looksLikeScaffolding(trimmed)) {
-        try {
-            const ranking = rankAll(inspection, trimmed);
-            const topTemplate = ranking.templates[0];
-            const topPipeline = ranking.pipelines[0];
-            if (topTemplate && topTemplate.score >= RANKER_TEMPLATE_PROMOTE_THRESHOLD) {
-                promotedRanker = {
-                    kind: 'template',
-                    id: topTemplate.item.id,
-                    label: topTemplate.item.name,
-                    score: topTemplate.score,
-                };
-            }
-            else if (topPipeline && topPipeline.score >= RANKER_PIPELINE_PROMOTE_THRESHOLD) {
-                promotedRanker = {
-                    kind: 'pipeline',
-                    id: topPipeline.item.id,
-                    label: topPipeline.item.title,
-                    score: topPipeline.score,
-                };
-            }
-        }
-        catch {
-            // The ranker is advisory — fall back to recipe/intent output on failure.
-        }
-    }
-    if (promotedRanker) {
-        const command = promotedRanker.kind === 'template'
-            ? `shrk gen ${promotedRanker.id} <name> --dry-run`
-            : `shrk task "${trimmed.replace(/"/g, '\\"')}"`;
-        const why = promotedRanker.kind === 'template'
-            ? `Ranker matched template "${promotedRanker.label}" (score ${promotedRanker.score}) — the project scaffold for this create/build task, ahead of the keyword recipe.`
-            : `Ranker matched pipeline "${promotedRanker.label}" (score ${promotedRanker.score}) — run the full task packet for this create/build task, ahead of the keyword recipe.`;
-        // Headline: unshift so it leads; dedup below keeps this first occurrence.
-        recommendations.unshift({ command, why, safetyLevel: safetyLevelFor(command) });
-    }
-    // If a stderr-like input was provided, do a diagnostic-suggest pass.
-    if (options.fromError && options.fromError.length > 0) {
-        for (const e of listDiagnostics()) {
-            const built = buildDiagnosticByCode(e.code, {});
-            if (new RegExp(e.code, 'i').test(options.fromError) || new RegExp(built.problem.slice(0, 20), 'i').test(options.fromError)) {
-                recommendations.push({
-                    command: built.nextCommand,
-                    why: `Diagnostic match: ${e.code}.`,
-                    safetyLevel: safetyLevelFor(built.nextCommand),
-                    ...(built.docsLink ? { docsLink: built.docsLink } : {}),
-                });
-            }
-        }
-    }
-    // Intent-driven fallback.
-    if (recommendations.length === 0) {
-        const intent = await classifyChangeIntent(trimmed, inspection);
-        recommendations.push({
-            command: intent.suggestedFirstCommand,
-            why: `Intent fallback (${intent.kind}, confidence ${intent.confidence}).`,
-            safetyLevel: safetyLevelFor(intent.suggestedFirstCommand),
-        });
-        if (intent.kind === ChangeIntentKind.Unknown) {
-            recommendations.push({ command: 'shrk start-here', why: 'No clear intent — start here.', safetyLevel: 'read-only' });
-        }
-    }
-    // Dedup by command (keep first).
-    const seen = new Set();
-    recommendations = recommendations.filter((r) => (seen.has(r.command) ? false : (seen.add(r.command), true)));
-    // Top of list = first recommendation.
-    const nextCommand = recommendations[0]?.command ?? 'shrk start-here';
-    // Build an uncertainty report from the recommendation signals.
-    const usedRecipe = RECIPES.some((r) => r.match.test(trimmed));
-    let confidence = 'medium';
-    const reasons = [];
-    const missing = [];
-    const conflicting = [];
-    const increase = [];
-    if (usedRecipe && promotedRanker) {
-        // Divergent signals: a keyword recipe fired AND a stronger ranker
-        // template/pipeline match was promoted to the headline. Keyword overlap
-        // alone is NOT enough for HIGH — emit a medium confidence + review note so
-        // the agent confirms the corrected route rather than trusting it blindly.
-        confidence = 'medium';
-        reasons.push(`Keyword recipe matched "${trimmed}", but the shared ranker found a stronger ${promotedRanker.kind} "${promotedRanker.id}" (score ${promotedRanker.score}) and now headlines it — review which fits.`);
-        conflicting.push({
-            id: 'conflict-recipe-vs-ranker',
-            message: `Recipe keyword overlap competes with ranker ${promotedRanker.kind} "${promotedRanker.id}". The headline was routed to the ranker match; confirm the intended target.`,
-        });
-        increase.push('Tighten the recipe regex or add a routing hint so the keyword stops overlapping unrelated tooling.');
-        warnings.push(`review: recipe keyword overlap was outranked by ranker ${promotedRanker.kind} "${promotedRanker.id}" — headline routed to the scaffold; confirm before applying.`);
-    }
-    else if (usedRecipe) {
-        // Pure-recipe case (no competing ranker match) — HIGH stays appropriate.
-        confidence = 'high';
-        reasons.push(`Recipe matched the query "${trimmed}".`);
-    }
-    else if (promotedRanker) {
-        // A clean, intent-confirmed structured match with no competing keyword
-        // recipe — the ranker is the engine's confident answer.
-        confidence = 'high';
-        reasons.push(`Shared ranker matched ${promotedRanker.kind} "${promotedRanker.id}" (score ${promotedRanker.score}).`);
-    }
-    else if (recommendations.length > 0 && recommendations[0]?.why.startsWith('Intent fallback')) {
-        confidence = 'low';
-        reasons.push('No recipe matched — fell back to intent classification.');
-        missing.push({ id: 'no-recipe-match', message: 'No recommender recipe matched the query.' });
-        increase.push('Add a routing hint or recommender recipe for this task class.');
-    }
-    else if (recommendations.length === 0) {
-        confidence = 'unknown';
-        reasons.push('No recommendations could be produced.');
-    }
+/** The report for a ranked list — no re-ranking, no re-derivation. */
+export function recommendationReportFromRanking(ranked, options = {}) {
+    const c = ranked.confidence;
+    const recommendations = ranked.recommendations.map(toCommandRecommendation);
     const uncertainty = buildUncertaintyReport({
-        confidence,
-        reasons,
-        missingSignals: missing,
-        conflictingSignals: conflicting,
+        confidence: c.level,
+        reasons: c.reasons,
+        missingSignals: c.missingSignals,
+        conflictingSignals: c.conflictingSignals,
         suggestedCommands: recommendations.slice(0, 3).map((r) => r.command),
         safeFallbackCommand: 'shrk start-here',
-        whatWouldIncreaseConfidence: increase,
+        whatWouldIncreaseConfidence: c.whatWouldIncreaseConfidence,
     });
     return {
         schema: COMMAND_RECOMMENDER_SCHEMA,
         generatedAt: new Date().toISOString(),
-        query: trimmed,
+        query: ranked.query,
         ...(options.role ? { role: options.role } : {}),
         recommendations,
-        nextCommand,
-        warnings,
+        nextCommand: ranked.nextCommand,
+        warnings: [...c.warnings],
         uncertainty,
+        confident: c.confident,
+        verdict: c.verdict,
+        floor: c.floor,
+        bestScore: c.bestScore,
+        ...(c.bestSource ? { bestSource: c.bestSource } : {}),
+        intent: ranked.intent,
+        ranked: ranked.candidates,
     };
 }
+export async function recommendCommands(inspection, query, options = {}) {
+    const ranked = await rankRecommendationCandidates(inspection, query, {
+        ...(options.fromError ? { fromError: options.fromError } : {}),
+        ...(options.minScore !== undefined ? { minScore: options.minScore } : {}),
+    });
+    return recommendationReportFromRanking(ranked, options.role ? { role: options.role } : {});
+}

package/dist/command-resolution-status.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The ONE vocabulary for "does this command string resolve?".
+ *
+ * The command table lives in the CLI package, above this layer, so the
+ * inspector never answers the question itself: the CLI builds its command
+ * index and injects a resolver through `warmReferenceRegistries(inspection,
+ * { commandResolver })`. The CLI resolver (`resolveCommandString`) returns
+ * these same members — there is exactly one definition, here.
+ *
+ *   - `Ok`             — the verb chain dispatches (a trie path, a declared or
+ *                        catalog-documented subverb, a meta flag), or
+ *                        `<pm> run <x>` names a real package script, or a bare
+ *                        MCP tool id names a registered tool.
+ *   - `PrefixOnly`     — the verb chain is proven, but the handler dispatches
+ *                        its tail internally and the tail cannot be proven from
+ *                        the trie + catalog (it may be a free positional).
+ *                        Counted, never flagged.
+ *   - `UnknownVerb`    — no registered verb matches the first token.
+ *   - `UnknownSubverb` — the parent is proven and provably takes no free
+ *                        positional, and the next token is not one of its
+ *                        subverbs (or a path-mode token is verb-shaped and
+ *                        names neither a subverb nor a file).
+ *   - `UnknownFlag`    — the verb chain is proven, but the dispatcher refuses a
+ *                        flag before anything runs (outside a declared set, or
+ *                        named by none of the command's documentation).
+ *   - `UnknownScript`  — `<pm> run <x>` and the root package.json has no `x`.
+ *   - `UnknownTool`    — a bare MCP-tool-shaped id that no tool registers.
+ *   - `NotShrk`        — not a command this engine can check (git, tsc, …).
+ *                        Skipped and counted.
+ *   - `Unverified`     — no resolver was injected (outside the CLI), so the
+ *                        string was NOT checked. Never read as a pass.
+ */
+export declare enum CommandResolutionStatus {
+    Ok = "ok",
+    PrefixOnly = "prefix-only",
+    UnknownVerb = "unknown-verb",
+    UnknownSubverb = "unknown-subverb",
+    UnknownFlag = "unknown-flag",
+    UnknownScript = "unknown-script",
+    UnknownTool = "unknown-tool",
+    NotShrk = "not-shrk",
+    Unverified = "unverified"
+}
+//# sourceMappingURL=command-resolution-status.d.ts.map

package/dist/command-resolution-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-resolution-status.d.ts","sourceRoot":"","sources":["../src/command-resolution-status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,oBAAY,uBAAuB;IACjC,EAAE,OAAO;IACT,UAAU,gBAAgB;IAC1B,WAAW,iBAAiB;IAC5B,cAAc,oBAAoB;IAClC,WAAW,iBAAiB;IAC5B,aAAa,mBAAmB;IAChC,WAAW,iBAAiB;IAC5B,OAAO,aAAa;IACpB,UAAU,eAAe;CAC1B"}

package/dist/command-resolution-status.js

@@ -0,0 +1,44 @@
+/**
+ * The ONE vocabulary for "does this command string resolve?".
+ *
+ * The command table lives in the CLI package, above this layer, so the
+ * inspector never answers the question itself: the CLI builds its command
+ * index and injects a resolver through `warmReferenceRegistries(inspection,
+ * { commandResolver })`. The CLI resolver (`resolveCommandString`) returns
+ * these same members — there is exactly one definition, here.
+ *
+ *   - `Ok`             — the verb chain dispatches (a trie path, a declared or
+ *                        catalog-documented subverb, a meta flag), or
+ *                        `<pm> run <x>` names a real package script, or a bare
+ *                        MCP tool id names a registered tool.
+ *   - `PrefixOnly`     — the verb chain is proven, but the handler dispatches
+ *                        its tail internally and the tail cannot be proven from
+ *                        the trie + catalog (it may be a free positional).
+ *                        Counted, never flagged.
+ *   - `UnknownVerb`    — no registered verb matches the first token.
+ *   - `UnknownSubverb` — the parent is proven and provably takes no free
+ *                        positional, and the next token is not one of its
+ *                        subverbs (or a path-mode token is verb-shaped and
+ *                        names neither a subverb nor a file).
+ *   - `UnknownFlag`    — the verb chain is proven, but the dispatcher refuses a
+ *                        flag before anything runs (outside a declared set, or
+ *                        named by none of the command's documentation).
+ *   - `UnknownScript`  — `<pm> run <x>` and the root package.json has no `x`.
+ *   - `UnknownTool`    — a bare MCP-tool-shaped id that no tool registers.
+ *   - `NotShrk`        — not a command this engine can check (git, tsc, …).
+ *                        Skipped and counted.
+ *   - `Unverified`     — no resolver was injected (outside the CLI), so the
+ *                        string was NOT checked. Never read as a pass.
+ */
+export var CommandResolutionStatus;
+(function (CommandResolutionStatus) {
+    CommandResolutionStatus["Ok"] = "ok";
+    CommandResolutionStatus["PrefixOnly"] = "prefix-only";
+    CommandResolutionStatus["UnknownVerb"] = "unknown-verb";
+    CommandResolutionStatus["UnknownSubverb"] = "unknown-subverb";
+    CommandResolutionStatus["UnknownFlag"] = "unknown-flag";
+    CommandResolutionStatus["UnknownScript"] = "unknown-script";
+    CommandResolutionStatus["UnknownTool"] = "unknown-tool";
+    CommandResolutionStatus["NotShrk"] = "not-shrk";
+    CommandResolutionStatus["Unverified"] = "unverified";
+})(CommandResolutionStatus || (CommandResolutionStatus = {}));

package/dist/command-safety-level.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The FALLBACK safety classification of a recommended command — for a surface
+ * with no command catalog (MCP `recommend_commands`, which cannot import the
+ * CLI) and for uncatalogued / free-text strings. The CLI injects the catalog's
+ * DECLARED per-command safety into the ranker (`safetyOf`, see
+ * `IRecommendationRankingOptions`), which wins over this regex; a lock
+ * (r75-safety-one-authority) holds this regex equal to the catalog on every
+ * row the catalog's own audit counts as writing source, so the not-confident
+ * withhold gate reads the same answer on both surfaces.
+ *
+ * A `shrk` invocation behind a package-manager prefix is classified by the
+ * `shrk` verb, never as a shell command.
+ */
+export declare function commandSafetyLevel(command: string): 'read-only' | 'writes-drafts' | 'writes-session' | 'writes-source' | 'runs-shell';
+//# sourceMappingURL=command-safety-level.d.ts.map

package/dist/command-safety-level.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-safety-level.d.ts","sourceRoot":"","sources":["../src/command-safety-level.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,GACd,WAAW,GAAG,eAAe,GAAG,gBAAgB,GAAG,eAAe,GAAG,YAAY,CA2BnF"}

package/dist/command-safety-level.js

@@ -0,0 +1,43 @@
+/**
+ * The FALLBACK safety classification of a recommended command — for a surface
+ * with no command catalog (MCP `recommend_commands`, which cannot import the
+ * CLI) and for uncatalogued / free-text strings. The CLI injects the catalog's
+ * DECLARED per-command safety into the ranker (`safetyOf`, see
+ * `IRecommendationRankingOptions`), which wins over this regex; a lock
+ * (r75-safety-one-authority) holds this regex equal to the catalog on every
+ * row the catalog's own audit counts as writing source, so the not-confident
+ * withhold gate reads the same answer on both surfaces.
+ *
+ * A `shrk` invocation behind a package-manager prefix is classified by the
+ * `shrk` verb, never as a shell command.
+ */
+export function commandSafetyLevel(command) {
+    const c = command
+        .trim()
+        .replace(/^\$\s+/, '')
+        .replace(/^(?:bun run|bun x|bunx|npx|pnpm exec|pnpm|yarn)\s+(?=shrk\b)/i, '');
+    if (/^shrk delegate(?:\s|$)/i.test(c))
+        return 'writes-source';
+    if (/^shrk (?:gen|init|apply|import|migrate|spike|presets apply --write|packs (?:sign|new)|(?:baseline|generated) update)(?:\s|$)/i.test(c)) {
+        return 'writes-source';
+    }
+    // `surface` and its config-mutating verbs write sharkcraft.config.ts; `surface
+    // list` / `explain` / `profiles` read.
+    if (/^shrk surface(?:\s+(?:enable|disable|hide|unhide|deny|allow|reset)(?:\s|$)|\s*$)/i.test(c))
+        return 'writes-source';
+    // `check wiring --fix` edits sink files; plain `check wiring` reads.
+    if (/^shrk check wiring\b.*\s--fix(?:\s|=|$)/i.test(c))
+        return 'writes-source';
+    // The base GitHub workflow scaffold writes source; its `--with-*` variants
+    // are declared drafts-only (the catalog rows), which the rule below keeps.
+    if (/^shrk ci scaffold github-actions(?:\s|$)/i.test(c) && !/\s--with-/i.test(c))
+        return 'writes-source';
+    if (/^shrk (?:onboard|brief|dev start|handoff|export|report site|impact|ci scaffold|simulate|orchestrate|spec)\b/i.test(c)) {
+        return 'writes-drafts';
+    }
+    if (/^shrk (?:session|dev report)\b/i.test(c))
+        return 'writes-session';
+    if (/^(?:bun|bunx|npm|npx|pnpm|yarn|node|git|nx) /i.test(c))
+        return 'runs-shell';
+    return 'read-only';
+}

package/dist/command-taxonomy.js

@@ -74,7 +74,7 @@ const GROUP_DEFS = [
         title: 'Diagnostics and troubleshooting',
         description: 'self audit, diagnostics, upgrade.',
         match: /^(self audit|diagnostics|upgrade|api)/,
-        primary: ['self audit', 'diagnostics suggest', 'upgrade check'],
+        primary: ['self audit', 'diagnostics list', 'upgrade check'],
     },
     {
         id: 'advanced',

package/dist/compliance-evidence.js

@@ -173,7 +173,7 @@ export function previewComplianceEvidencePacket(profileId) {
             '(if present) release-smoke.json',
             '(if present) self-audit.json',
         ],
-        nextCommand: `shrk compliance evidence ${profileId} --output .sharkcraft/compliance-evidence/${profileId}`,
+        nextCommand: 'shrk release readiness --report',
     };
 }
 export function verifyComplianceEvidencePacket(targetPathOrDir) {

package/dist/compliance-profiles.js

@@ -83,7 +83,7 @@ export async function runComplianceCheck(inspection, profileId) {
                     profileId,
                     ruleId: 'unknown-profile',
                     severity: 'error',
-                    message: `Compliance profile "${profileId}" not found. Use \`shrk compliance profiles\`.`,
+                    message: `Compliance profile "${profileId}" not found. Known profiles: ${listComplianceProfiles().map((p) => p.id).join(', ')}.`,
                 },
             ],
             summary: { errors: 1, warnings: 0, info: 0 },

package/dist/construct-registry.d.ts

@@ -1,5 +1,7 @@
 import type { IConstructFacetInput, IConstructFacetValue, IConstructInput } from '@shrkcrft/plugin-api';
 import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+import { type IRejectedEntry } from '@shrkcrft/core';
+import type { IContributionFileIssue } from './i-contribution-file-issue.js';
 export declare const CONSTRUCT_REGISTRY_SCHEMA = "sharkcraft.construct-registry/v1";
 export interface IConstruct extends IConstructInput {
     source: 'local' | 'pack';
@@ -8,6 +10,44 @@ export interface IConstruct extends IConstructInput {
 }
 export interface IConstructFacet extends IConstructFacetInput {
 }
+/**
+ * THE construct acceptance predicate (round 12, 12.1 / 12.1d): a non-empty
+ * string `id` and a string `type` — `[]` means accepted. An id-less construct
+ * used to be dropped silently, and one without `type` was ACCEPTED and then
+ * crashed `constructs list` (`c.type.padEnd`).
+ */
+export declare function constructRejectionReasons(raw: unknown): readonly string[];
+/**
+ * THE construct-facet SHAPE predicate: `id`, `constructId`, `kind`, `value`,
+ * each a string — `[]` means the shape is accepted. (A well-shaped facet whose
+ * `constructId` names no loaded construct is refused at fold time.)
+ */
+export declare function constructFacetRejectionReasons(raw: unknown): readonly string[];
+/**
+ * Load every local and pack construct (and fold loose facets into them), with
+ * what did not take effect: files that failed to import (they used to be
+ * swallowed — `catch { /* ignore *\/ }` — so a broken `constructs.ts` read as a
+ * smaller registry), and every declared construct / facet the loader refused
+ * (round 12, 12.1).
+ */
+export declare function loadConstructsWithIssues(inspection: ISharkcraftInspection): Promise<{
+    readonly constructs: readonly IConstruct[];
+    /** Every facet folded into a construct, attributed to its file. */
+    readonly facets: readonly {
+        readonly id: string;
+        readonly constructId: string;
+        readonly file: string;
+        readonly packageName?: string;
+    }[];
+    /** Construct files that failed to import / are missing. */
+    readonly issues: readonly IContributionFileIssue[];
+    /** Every declared construct the loader refused. */
+    readonly rejected: readonly IRejectedEntry[];
+    /** Facet files that failed to import / are missing. */
+    readonly facetIssues: readonly IContributionFileIssue[];
+    /** Every declared facet the loader refused (malformed, or its construct is not loaded). */
+    readonly facetRejected: readonly IRejectedEntry[];
+}>;
 export declare function loadConstructs(inspection: ISharkcraftInspection): Promise<readonly IConstruct[]>;
 /** Synchronous accessor — falls back to a snapshot cached from the last
  *  async load. Used by search-index which needs to be sync-friendly. */

package/dist/construct-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"construct-registry.d.ts","sourceRoot":"","sources":["../src/construct-registry.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,oBAAoB,EACpB,oBAAoB,EACpB,eAAe,EAChB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAGvE,eAAO,MAAM,yBAAyB,qCAAqC,CAAC;AAE5E,MAAM,WAAW,UAAW,SAAQ,eAAe;IACjD,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAgB,SAAQ,oBAAoB;CAAG;AA+DhE,wBAAsB,cAAc,CAClC,UAAU,EAAE,qBAAqB,GAChC,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC,CAwFhC;AAED;wEACwE;AACxE,wBAAgB,cAAc,CAAC,UAAU,EAAE,qBAAqB,GAAG,SAAS,UAAU,EAAE,CAGvF;AAED,wEAAwE;AACxE,wBAAsB,kBAAkB,CAAC,UAAU,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAEzF;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,UAAU,CAAC;IACtB,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,oBAAoB,EAAE,CAAC,CAAC;IACxD,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,UAAU,GAAG,eAAe,CAmBrE"}
+{"version":3,"file":"construct-registry.d.ts","sourceRoot":"","sources":["../src/construct-registry.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,oBAAoB,EACpB,oBAAoB,EACpB,eAAe,EAChB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AACvE,OAAO,EAKL,KAAK,cAAc,EACpB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAE7E,eAAO,MAAM,yBAAyB,qCAAqC,CAAC;AAE5E,MAAM,WAAW,UAAW,SAAQ,eAAe;IACjD,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAgB,SAAQ,oBAAoB;CAAG;AA+BhE;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,MAAM,EAAE,CAOzE;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,MAAM,EAAE,CAM9E;AA+BD;;;;;;GAMG;AACH,wBAAsB,wBAAwB,CAAC,UAAU,EAAE,qBAAqB,GAAG,OAAO,CAAC;IACzF,QAAQ,CAAC,UAAU,EAAE,SAAS,UAAU,EAAE,CAAC;IAC3C,mEAAmE;IACnE,QAAQ,CAAC,MAAM,EAAE,SAAS;QACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;KAC/B,EAAE,CAAC;IACJ,2DAA2D;IAC3D,QAAQ,CAAC,MAAM,EAAE,SAAS,sBAAsB,EAAE,CAAC;IACnD,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;IAC7C,uDAAuD;IACvD,QAAQ,CAAC,WAAW,EAAE,SAAS,sBAAsB,EAAE,CAAC;IACxD,2FAA2F;IAC3F,QAAQ,CAAC,aAAa,EAAE,SAAS,cAAc,EAAE,CAAC;CACnD,CAAC,CA0LD;AAED,wBAAsB,cAAc,CAClC,UAAU,EAAE,qBAAqB,GAChC,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC,CAEhC;AAED;wEACwE;AACxE,wBAAgB,cAAc,CAAC,UAAU,EAAE,qBAAqB,GAAG,SAAS,UAAU,EAAE,CAGvF;AAED,wEAAwE;AACxE,wBAAsB,kBAAkB,CAAC,UAAU,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAEzF;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,UAAU,CAAC;IACtB,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,oBAAoB,EAAE,CAAC,CAAC;IACxD,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,UAAU,GAAG,eAAe,CAmBrE"}