@shrkcrft/inspector 0.1.0-alpha.2 → 0.1.0-alpha.21

package/dist/dashboard/dashboard-knowledge.js

@@ -0,0 +1,259 @@
+/**
+ * Dashboard data builders for the Knowledge explorer page. Pure, deterministic,
+ * JSON-serializable — no network, no LLM (the LLM-backed "ask" lives in the CLI
+ * dashboard layer so the inspector stays AI-free). The dashboard API server
+ * wraps these with @shrkcrft/dashboard-api envelopes.
+ */
+import { relative } from 'node:path';
+import { hasActionHints, priorityWeight, searchKnowledge, } from '@shrkcrft/knowledge';
+import { buildKnowledgeGraph, getGraphNode } from "../knowledge-graph.js";
+/** GraphSvg colours by kind — map a knowledge entry's type to one of them. */
+function nodeKindForType(type) {
+    if (type === 'rule')
+        return 'rule';
+    if (type === 'path')
+        return 'path';
+    if (type === 'template')
+        return 'template';
+    return 'knowledge';
+}
+function sourceLabel(entry, projectRoot) {
+    const origin = entry.source?.origin;
+    if (!origin)
+        return entry.source?.loader ?? 'local';
+    if (origin.startsWith('http'))
+        return origin;
+    const rel = relative(projectRoot, origin);
+    return rel && !rel.startsWith('..') ? rel : origin;
+}
+function commandHint(command, purpose) {
+    return { command, purpose, safety: 'read-only' };
+}
+function summaryOf(entry, projectRoot) {
+    const summary = {
+        id: entry.id,
+        title: entry.title,
+        type: String(entry.type),
+        priority: String(entry.priority),
+        scope: [...entry.scope],
+        tags: [...entry.tags],
+        relatedCount: (entry.related?.length ?? 0),
+        hasActionHints: hasActionHints(entry),
+        source: sourceLabel(entry, projectRoot),
+    };
+    return entry.summary ? { ...summary, summary: entry.summary } : summary;
+}
+function mapActionHints(h) {
+    return {
+        commands: (h.commands ?? []).map((c) => c.command),
+        mcpTools: (h.mcpTools ?? []).map((t) => t.tool),
+        preferredFlow: [...(h.preferredFlow ?? [])],
+        forbiddenActions: [...(h.forbiddenActions ?? [])],
+        verificationCommands: [...(h.verificationCommands ?? [])],
+        relatedTemplates: [...(h.relatedTemplates ?? [])],
+        relatedPathConventions: [...(h.relatedPathConventions ?? [])],
+        relatedKnowledge: [...(h.relatedKnowledge ?? [])],
+        ...(h.writePolicy ? { writePolicy: String(h.writePolicy) } : {}),
+    };
+}
+function detailOf(entry, projectRoot) {
+    const examples = (entry.examples ?? []).map((ex) => ({
+        ...(ex.title ? { title: ex.title } : {}),
+        ...(ex.description ? { description: ex.description } : {}),
+        ...(ex.language ? { language: ex.language } : {}),
+        ...(ex.code ? { code: ex.code } : {}),
+    }));
+    const detail = {
+        id: entry.id,
+        title: entry.title,
+        type: String(entry.type),
+        priority: String(entry.priority),
+        scope: [...entry.scope],
+        tags: [...entry.tags],
+        appliesWhen: [...entry.appliesWhen],
+        content: entry.content,
+        related: [...(entry.related ?? [])],
+        source: sourceLabel(entry, projectRoot),
+        examples,
+    };
+    const withSummary = entry.summary ? { ...detail, summary: entry.summary } : detail;
+    return entry.actionHints
+        ? { ...withSummary, actionHints: mapActionHints(entry.actionHints) }
+        : withSummary;
+}
+function facetCounts(entries, pick) {
+    const counts = new Map();
+    for (const e of entries) {
+        for (const v of pick(e)) {
+            if (!v)
+                continue;
+            counts.set(v, (counts.get(v) ?? 0) + 1);
+        }
+    }
+    return [...counts.entries()]
+        .map(([value, count]) => ({ value, count }))
+        .sort((a, b) => b.count - a.count || a.value.localeCompare(b.value));
+}
+/** Sort: highest priority first, then alphabetical by id. */
+function byPriorityThenId(a, b) {
+    const w = priorityWeight(b.priority) - priorityWeight(a.priority);
+    return w !== 0 ? w : a.id.localeCompare(b.id);
+}
+function roundScore(n) {
+    return Math.round(n * 100) / 100;
+}
+function computeInsights(entries) {
+    const byPriority = { critical: 0, high: 0, medium: 0, low: 0 };
+    let withoutActionHints = 0;
+    let withoutSummary = 0;
+    let orphans = 0;
+    for (const e of entries) {
+        const p = String(e.priority);
+        if (p === 'critical' || p === 'high' || p === 'medium' || p === 'low')
+            byPriority[p] += 1;
+        if (!hasActionHints(e))
+            withoutActionHints += 1;
+        if (!e.summary)
+            withoutSummary += 1;
+        if (!(e.related?.length) && !(e.actionHints?.relatedKnowledge?.length))
+            orphans += 1;
+    }
+    return { byPriority, withoutActionHints, withoutSummary, orphans };
+}
+export function buildDashboardKnowledgeList(inspection) {
+    const entries = inspection.knowledgeEntries;
+    const sorted = [...entries].sort(byPriorityThenId);
+    return {
+        available: entries.length > 0,
+        total: entries.length,
+        entries: sorted.map((e) => summaryOf(e, inspection.projectRoot)),
+        facets: {
+            types: facetCounts(entries, (e) => [String(e.type)]),
+            scopes: facetCounts(entries, (e) => e.scope),
+            tags: facetCounts(entries, (e) => e.tags),
+            priorities: facetCounts(entries, (e) => [String(e.priority)]),
+        },
+        insights: computeInsights(entries),
+        commandHints: [
+            commandHint('shrk knowledge list', 'List every knowledge entry'),
+            commandHint('shrk knowledge search "<query>"', 'Rank entries by relevance to a query'),
+            commandHint('shrk knowledge get <id>', 'Read a single entry in the terminal'),
+        ],
+    };
+}
+export function buildDashboardKnowledgeEntry(inspection, id) {
+    const entries = inspection.knowledgeEntries;
+    const entry = entries.find((e) => e.id === id);
+    if (!entry) {
+        return { found: false, inbound: [], outbound: [], related: [], commandHints: [] };
+    }
+    const graph = buildKnowledgeGraph(inspection);
+    const located = getGraphNode(graph, { id });
+    // Graph edge endpoints are namespaced node keys (`kind:id`), so resolve the
+    // raw id + kind through byId rather than echoing the key.
+    const toNeighbor = (endpointKey, relation, why) => {
+        const node = graph.byId.get(endpointKey);
+        // Edges only ever target nodes present in the graph, but if a lookup ever
+        // misses, strip the `kind:` prefix so a raw id (not the namespaced key)
+        // still reaches the client — `id` must be a clickable entry id.
+        const colon = endpointKey.indexOf(':');
+        const fallbackId = colon >= 0 ? endpointKey.slice(colon + 1) : endpointKey;
+        return {
+            id: node?.id ?? fallbackId,
+            kind: node?.kind ?? 'knowledge',
+            relation,
+            why,
+        };
+    };
+    const inbound = (located?.incoming ?? []).map((e) => toNeighbor(e.from, e.relation, e.why));
+    const outbound = (located?.outgoing ?? []).map((e) => toNeighbor(e.to, e.relation, e.why));
+    const relatedIds = [
+        ...new Set([...(entry.related ?? []), ...(entry.actionHints?.relatedKnowledge ?? [])]),
+    ];
+    const related = relatedIds
+        .map((rid) => entries.find((e) => e.id === rid))
+        .filter((e) => Boolean(e))
+        .map((e) => summaryOf(e, inspection.projectRoot));
+    return {
+        found: true,
+        entry: detailOf(entry, inspection.projectRoot),
+        inbound,
+        outbound,
+        related,
+        commandHints: [
+            commandHint(`shrk knowledge get ${entry.id}`, 'Read this entry in the terminal'),
+            commandHint(`shrk graph node ${entry.id}`, 'Inspect this node and its edges'),
+        ],
+    };
+}
+/** Cap the rendered graph — the ring layout stays legible up to ~120 nodes. */
+const MAX_GRAPH_NODES = 120;
+export function buildDashboardKnowledgeGraph(inspection) {
+    const all = [...inspection.knowledgeEntries].sort(byPriorityThenId);
+    const truncated = all.length > MAX_GRAPH_NODES;
+    const entries = all.slice(0, MAX_GRAPH_NODES);
+    const ids = new Set(entries.map((e) => e.id));
+    const nodes = entries.map((e) => ({
+        id: e.id,
+        kind: nodeKindForType(String(e.type)),
+        label: e.title,
+    }));
+    const edges = [];
+    const seen = new Set();
+    const addEdge = (from, to, kind) => {
+        if (from === to || !ids.has(from) || !ids.has(to))
+            return;
+        const key = from < to ? `${from}|${to}|${kind}` : `${to}|${from}|${kind}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        edges.push({ from, to, kind });
+    };
+    // Semantic edges: explicit cross-references.
+    for (const e of entries) {
+        for (const t of [...(e.related ?? []), ...(e.actionHints?.relatedKnowledge ?? [])]) {
+            addEdge(e.id, t, 'related');
+        }
+    }
+    // Scope clusters: chain entries that share a scope so the graph forms loose,
+    // legible neighbourhoods instead of an O(n²) hairball.
+    const byScope = new Map();
+    for (const e of entries) {
+        for (const s of e.scope) {
+            const list = byScope.get(s) ?? [];
+            list.push(e.id);
+            byScope.set(s, list);
+        }
+    }
+    for (const group of byScope.values()) {
+        for (let i = 1; i < group.length; i += 1) {
+            addEdge(group[i - 1], group[i], 'scope');
+        }
+    }
+    return { available: entries.length > 0, nodes, edges, truncated };
+}
+/** Relevance-ranked "more like this" for one entry (lexical, deterministic). */
+export function buildDashboardKnowledgeSimilar(inspection, id) {
+    const entries = inspection.knowledgeEntries;
+    const entry = entries.find((e) => e.id === id);
+    if (!entry)
+        return { id, available: false, similar: [] };
+    // Use the entry's own signature (title + tags + scope) as the query. With no
+    // signature there's nothing to match on — return empty rather than letting
+    // searchKnowledge fall back to a priority-only ranking of everything.
+    const query = [entry.title, ...entry.tags, ...entry.scope].join(' ').trim();
+    if (!query)
+        return { id, available: false, similar: [] };
+    const results = searchKnowledge(entries, { query, limit: 8 });
+    const similar = results
+        .filter((r) => r.entry.id !== id)
+        .slice(0, 6)
+        .map((r) => ({
+        id: r.entry.id,
+        title: r.entry.title,
+        type: String(r.entry.type),
+        score: roundScore(r.score),
+        reasons: [...new Set(r.reasons.map((x) => x.field))].slice(0, 4),
+    }));
+    return { id, available: similar.length > 0, similar };
+}

package/dist/decision-records.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decision-records.d.ts","sourceRoot":"","sources":["../src/decision-records.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,eAAO,MAAM,sBAAsB,2BAA2B,CAAC;AAE/D,oBAAY,cAAc;IACxB,QAAQ,aAAa;IACrB,QAAQ,aAAa;IACrB,QAAQ,aAAa;IACrB,UAAU,eAAe;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,OAAO,sBAAsB,CAAC;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,cAAc,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AA8CD,wBAAgB,aAAa,CAAC,UAAU,EAAE,qBAAqB,GAAG,SAAS,eAAe,EAAE,CAyD3F;AA0BD;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,UAAU,EAAE,qBAAqB,GAChC,OAAO,CAAC,SAAS,eAAe,EAAE,CAAC,CAuCrC;AAaD,wBAAgB,WAAW,CAAC,UAAU,EAAE,qBAAqB,EAAE,EAAE,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAEtG;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,CA0CvE;AAED,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAE/E"}
+{"version":3,"file":"decision-records.d.ts","sourceRoot":"","sources":["../src/decision-records.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAGvE,eAAO,MAAM,sBAAsB,2BAA2B,CAAC;AAE/D,oBAAY,cAAc;IACxB,QAAQ,aAAa;IACrB,QAAQ,aAAa;IACrB,QAAQ,aAAa;IACrB,UAAU,eAAe;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,OAAO,sBAAsB,CAAC;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,cAAc,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AA8CD,wBAAgB,aAAa,CAAC,UAAU,EAAE,qBAAqB,GAAG,SAAS,eAAe,EAAE,CA2D3F;AA0BD;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,UAAU,EAAE,qBAAqB,GAChC,OAAO,CAAC,SAAS,eAAe,EAAE,CAAC,CAuCrC;AAaD,wBAAgB,WAAW,CAAC,UAAU,EAAE,qBAAqB,EAAE,EAAE,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAEtG;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,CA0CvE;AAED,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAE/E"}

package/dist/decision-records.js

@@ -1,11 +1,3 @@
-var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
-    if (typeof path === "string" && /^\.\.?\//.test(path)) {
-        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
-            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
-        });
-    }
-    return path;
-};
 /**
  * Decision / ADR support.
  *
@@ -18,6 +10,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
  */
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import * as nodePath from 'node:path';
+import { importModuleViaLoader } from '@shrkcrft/core';
 export const DECISION_RECORD_SCHEMA = 'sharkcraft.decision/v1';
 export var DecisionStatus;
 (function (DecisionStatus) {
@@ -86,7 +79,9 @@ export function listDecisions(inspection) {
             continue;
         let entries = [];
         try {
-            entries = readdirSync(dir);
+            // Sort so the decision-record list (and the doctor findings derived from
+            // it) is deterministic, not filesystem-order-dependent.
+            entries = readdirSync(dir).sort();
         }
         catch {
             continue;
@@ -193,7 +188,7 @@ async function importDefaultArray(absPath) {
         if (!existsSync(absPath))
             return [];
         const { pathToFileURL } = await import('node:url');
-        const mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(absPath).href)));
+        const mod = (await importModuleViaLoader(absPath));
         return Array.isArray(mod.default) ? mod.default : [];
     }
     catch {

package/dist/delegate-catalog.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Resolve the delegate-recipe catalog from a loaded config (read-only, NO model).
+ *
+ * Merges the delegation-level `provider`/`model` defaults into each recipe and
+ * checks every `verificationId` against the config's `verificationCommands[]`.
+ * A recipe is `delegatable` only when ALL its verification ids are bound — a
+ * recipe with an unbound (or empty) verification has no deterministic gate, so
+ * `shrk delegate explain` can show an author the fence is real before trusting
+ * it. Pack-contributed recipes (Phase 4) will merge in here too.
+ */
+import type { IDelegateRecipe, ISharkCraftConfig } from '@shrkcrft/config';
+export interface IResolvedDelegateRecipe extends IDelegateRecipe {
+    /** Provider after applying the delegation-level default (never undefined). */
+    resolvedProvider: 'auto' | 'ollama' | 'llamacpp';
+    /** Model after applying the delegation-level default (undefined = provider default). */
+    resolvedModel?: string;
+    /** verificationIds that do NOT resolve to a `verificationCommands[].id`. */
+    unboundVerificationIds: readonly string[];
+    /** True when every verificationId resolves AND at least one is declared. */
+    verificationBound: boolean;
+    /** True when the recipe is safe to delegate (verification fully bound). */
+    delegatable: boolean;
+    /** Where the recipe came from. */
+    source: 'config' | 'pack';
+    /** Contributing pack, when `source === 'pack'`. */
+    packageName?: string;
+}
+/** A pack-contributed recipe (shape from `loadDelegateRecipesFromPacks`). */
+export interface IPackRecipeInput {
+    recipe: IDelegateRecipe;
+    packageName: string;
+}
+/**
+ * Resolve the delegate catalog from config + pack-contributed recipes.
+ *
+ * Merge order: pack recipes first, then INLINE config recipes override a pack
+ * recipe of the same id. `recipeOverrides` (by id) then patch model /
+ * verificationIds / guardrailGlobs, or drop the recipe (`enabled: false`).
+ * Finally each recipe's `verificationIds` are checked against
+ * `verificationCommands[]` — `delegatable` only when all are bound.
+ */
+export declare function resolveDelegateCatalog(config: ISharkCraftConfig, packRecipes?: readonly IPackRecipeInput[]): readonly IResolvedDelegateRecipe[];
+/** Look up one resolved recipe by id (config recipes only; no pack loading). */
+export declare function findDelegateRecipe(config: ISharkCraftConfig, recipeId: string): IResolvedDelegateRecipe | undefined;
+//# sourceMappingURL=delegate-catalog.d.ts.map

package/dist/delegate-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegate-catalog.d.ts","sourceRoot":"","sources":["../src/delegate-catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE3E,MAAM,WAAW,uBAAwB,SAAQ,eAAe;IAC9D,8EAA8E;IAC9E,gBAAgB,EAAE,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAC;IACjD,wFAAwF;IACxF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,4EAA4E;IAC5E,sBAAsB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,4EAA4E;IAC5E,iBAAiB,EAAE,OAAO,CAAC;IAC3B,2EAA2E;IAC3E,WAAW,EAAE,OAAO,CAAC;IACrB,kCAAkC;IAClC,MAAM,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC1B,mDAAmD;IACnD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,6EAA6E;AAC7E,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,eAAe,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,iBAAiB,EACzB,WAAW,GAAE,SAAS,gBAAgB,EAAO,GAC5C,SAAS,uBAAuB,EAAE,CAkCpC;AAED,gFAAgF;AAChF,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,iBAAiB,EACzB,QAAQ,EAAE,MAAM,GACf,uBAAuB,GAAG,SAAS,CAErC"}

package/dist/delegate-catalog.js

@@ -0,0 +1,50 @@
+/**
+ * Resolve the delegate catalog from config + pack-contributed recipes.
+ *
+ * Merge order: pack recipes first, then INLINE config recipes override a pack
+ * recipe of the same id. `recipeOverrides` (by id) then patch model /
+ * verificationIds / guardrailGlobs, or drop the recipe (`enabled: false`).
+ * Finally each recipe's `verificationIds` are checked against
+ * `verificationCommands[]` — `delegatable` only when all are bound.
+ */
+export function resolveDelegateCatalog(config, packRecipes = []) {
+    const delegation = config.delegation;
+    if (!delegation)
+        return [];
+    const known = new Set((config.verificationCommands ?? []).map((v) => v.id));
+    const overrides = delegation.recipeOverrides ?? {};
+    const byId = new Map();
+    for (const pr of packRecipes)
+        byId.set(pr.recipe.id, { recipe: pr.recipe, source: 'pack', packageName: pr.packageName });
+    for (const recipe of delegation.recipes ?? [])
+        byId.set(recipe.id, { recipe, source: 'config' });
+    const out = [];
+    for (const { recipe, source, packageName } of byId.values()) {
+        const ov = overrides[recipe.id];
+        if (ov?.enabled === false)
+            continue; // dropped by override
+        const merged = {
+            ...recipe,
+            ...(ov?.model !== undefined ? { model: ov.model } : {}),
+            ...(ov?.verificationIds !== undefined ? { verificationIds: ov.verificationIds } : {}),
+            ...(ov?.guardrailGlobs !== undefined ? { guardrailGlobs: ov.guardrailGlobs } : {}),
+        };
+        const unbound = (merged.verificationIds ?? []).filter((id) => !known.has(id));
+        const verificationBound = unbound.length === 0 && (merged.verificationIds ?? []).length > 0;
+        out.push({
+            ...merged,
+            resolvedProvider: merged.provider ?? delegation.provider ?? 'auto',
+            ...(merged.model ?? delegation.model ? { resolvedModel: merged.model ?? delegation.model } : {}),
+            unboundVerificationIds: unbound,
+            verificationBound,
+            delegatable: verificationBound,
+            source,
+            ...(packageName ? { packageName } : {}),
+        });
+    }
+    return out;
+}
+/** Look up one resolved recipe by id (config recipes only; no pack loading). */
+export function findDelegateRecipe(config, recipeId) {
+    return resolveDelegateCatalog(config).find((r) => r.id === recipeId);
+}

package/dist/delegate-doctor.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `shrk doctor` checks for delegate-worker recipe health.
+ *
+ * Surfaces recipes that are NOT delegatable — a recipe whose `verificationIds`
+ * don't all resolve to `verificationCommands[]` (incl. after `recipeOverrides`)
+ * has no deterministic gate, so `shrk delegate run` would refuse it. `runDoctor`
+ * has no other surface for this (it doesn't run `validateConfig`), so this is the
+ * proactive catch. Sync + config-only (pack-recipe health is `delegate explain`,
+ * which can load pack files async); silent when the repo hasn't opted into
+ * delegation.
+ */
+import type { ISharkCraftConfig } from '@shrkcrft/config';
+import { type IDoctorCheck } from './doctor-result.js';
+export declare function buildDelegateRecipeChecks(config: ISharkCraftConfig | null): IDoctorCheck[];
+//# sourceMappingURL=delegate-doctor.d.ts.map

package/dist/delegate-doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegate-doctor.d.ts","sourceRoot":"","sources":["../src/delegate-doctor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGvE,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,GAAG,YAAY,EAAE,CAiC1F"}

package/dist/delegate-doctor.js

@@ -0,0 +1,36 @@
+import { DoctorSeverity } from "./doctor-result.js";
+import { resolveDelegateCatalog } from "./delegate-catalog.js";
+export function buildDelegateRecipeChecks(config) {
+    if (!config?.delegation)
+        return []; // not opted in → silent
+    const catalog = resolveDelegateCatalog(config);
+    if (catalog.length === 0)
+        return [];
+    const out = [];
+    const broken = catalog.filter((r) => !r.delegatable);
+    for (const r of broken) {
+        const reason = r.unboundVerificationIds.length > 0
+            ? `verificationIds not in verificationCommands[]: ${r.unboundVerificationIds.join(', ')}`
+            : 'no verificationIds declared';
+        out.push({
+            id: `delegate-recipe-${r.id}`,
+            title: `Delegate recipe "${r.id}" is not delegatable`,
+            severity: DoctorSeverity.Warning,
+            message: `${reason} — \`shrk delegate run --recipe ${r.id}\` would refuse to apply an unverified edit.`,
+            category: 'delegate',
+            code: 'recipe-unverified',
+            recommendedFix: `shrk delegate explain ${r.id}`,
+            whyThisMatters: 'A recipe with an unbound verification has no deterministic gate; the worker can only run a VERIFIED edit, so the recipe is unusable until its verificationIds bind to a verificationCommands[] entry.',
+        });
+    }
+    if (broken.length === 0) {
+        out.push({
+            id: 'delegate-recipes',
+            title: 'Delegate recipes',
+            severity: DoctorSeverity.Ok,
+            message: `${catalog.length} delegate recipe(s) configured, all delegatable.`,
+            category: 'delegate',
+        });
+    }
+    return out;
+}

package/dist/delegate-pack-recipes.d.ts

@@ -0,0 +1,29 @@
+import { type IDelegateRecipe } from '@shrkcrft/core';
+import type { ISharkCraftConfig } from '@shrkcrft/config';
+import { type IDiscoveredPack } from '@shrkcrft/packs';
+import { type IResolvedDelegateRecipe } from './delegate-catalog.js';
+export interface IPackDelegateRecipe {
+    recipe: IDelegateRecipe;
+    packageName: string;
+    /** The contributed file's relative path (for diagnostics). */
+    sourceFile: string;
+}
+export interface IPackRecipeIssue {
+    severity: 'warning' | 'error';
+    message: string;
+    source?: string;
+}
+export interface ILoadPackRecipesResult {
+    recipes: readonly IPackDelegateRecipe[];
+    issues: readonly IPackRecipeIssue[];
+}
+export declare function loadDelegateRecipesFromPacks(validPacks: readonly IDiscoveredPack[]): Promise<ILoadPackRecipesResult>;
+/**
+ * One-shot: discover packs under `projectRoot`, load their delegate recipes, and
+ * resolve the full catalog (pack recipes + config recipes + `recipeOverrides`).
+ * Pack discovery is best-effort — a missing/odd `node_modules` degrades to the
+ * config-only catalog. Keeps `discoverPacks` inside `inspector` so the cli stays
+ * decoupled from `@shrkcrft/packs`.
+ */
+export declare function resolveDelegateCatalogForProject(config: ISharkCraftConfig, projectRoot: string): Promise<readonly IResolvedDelegateRecipe[]>;
+//# sourceMappingURL=delegate-pack-recipes.d.ts.map

package/dist/delegate-pack-recipes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegate-pack-recipes.d.ts","sourceRoot":"","sources":["../src/delegate-pack-recipes.ts"],"names":[],"mappings":"AAWA,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC7E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAiB,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACtE,OAAO,EAA0B,KAAK,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAE7F,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,eAAe,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,SAAS,GAAG,OAAO,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACxC,MAAM,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACrC;AAaD,wBAAsB,4BAA4B,CAChD,UAAU,EAAE,SAAS,eAAe,EAAE,GACrC,OAAO,CAAC,sBAAsB,CAAC,CA8BjC;AAED;;;;;;GAMG;AACH,wBAAsB,gCAAgC,CACpD,MAAM,EAAE,iBAAiB,EACzB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,SAAS,uBAAuB,EAAE,CAAC,CAY7C"}

package/dist/delegate-pack-recipes.js

@@ -0,0 +1,77 @@
+/**
+ * Load delegate-worker recipes contributed by discovered packs.
+ *
+ * A pack declares `contributions.delegateRecipeFiles[]`, each default-exporting
+ * `readonly IDelegateRecipe[]` (via `defineDelegateRecipe`). This loads them
+ * read-only (no model, no writes) so `resolveDelegateCatalog(config, packRecipes)`
+ * can merge them with the project's inline recipes + `recipeOverrides`. Mirrors
+ * the other pack registries (e.g. task-routing-hint-registry).
+ */
+import { existsSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { importModuleViaLoader } from '@shrkcrft/core';
+import { discoverPacks } from '@shrkcrft/packs';
+import { resolveDelegateCatalog } from "./delegate-catalog.js";
+async function importRecipes(file) {
+    const mod = (await importModuleViaLoader(file));
+    if (Array.isArray(mod.default))
+        return mod.default;
+    if (mod.default && typeof mod.default === 'object')
+        return [mod.default];
+    if (Array.isArray(mod.delegateRecipes))
+        return mod.delegateRecipes;
+    return [];
+}
+export async function loadDelegateRecipesFromPacks(validPacks) {
+    const recipes = [];
+    const issues = [];
+    for (const pack of validPacks) {
+        const files = pack.manifest?.contributions?.delegateRecipeFiles ?? [];
+        for (const rel of files) {
+            const file = nodePath.resolve(pack.packageRoot, rel);
+            if (!existsSync(file)) {
+                issues.push({
+                    severity: 'warning',
+                    message: `Pack ${pack.packageName} declares ${rel} but the file is missing.`,
+                    source: file,
+                });
+                continue;
+            }
+            try {
+                const list = await importRecipes(file);
+                for (const recipe of list) {
+                    recipes.push({ recipe, packageName: pack.packageName, sourceFile: rel });
+                }
+            }
+            catch (e) {
+                issues.push({
+                    severity: 'warning',
+                    message: `Pack ${pack.packageName} (${rel}): ${e.message}`,
+                    source: file,
+                });
+            }
+        }
+    }
+    return { recipes, issues };
+}
+/**
+ * One-shot: discover packs under `projectRoot`, load their delegate recipes, and
+ * resolve the full catalog (pack recipes + config recipes + `recipeOverrides`).
+ * Pack discovery is best-effort — a missing/odd `node_modules` degrades to the
+ * config-only catalog. Keeps `discoverPacks` inside `inspector` so the cli stays
+ * decoupled from `@shrkcrft/packs`.
+ */
+export async function resolveDelegateCatalogForProject(config, projectRoot) {
+    let packRecipes = [];
+    try {
+        const disc = await discoverPacks({ projectRoot });
+        packRecipes = (await loadDelegateRecipesFromPacks(disc.validPacks)).recipes.map((p) => ({
+            recipe: p.recipe,
+            packageName: p.packageName,
+        }));
+    }
+    catch {
+        // best-effort; configured recipes still resolve
+    }
+    return resolveDelegateCatalog(config, packRecipes);
+}

package/dist/demo-script.d.ts

@@ -1,7 +1,6 @@
 export declare const DEMO_SCRIPT_SCHEMA = "sharkcraft.demo-script/v1";
 export declare enum DemoScenario {
     UnconfiguredRepo = "unconfigured-repo",
-    PlatformPlugin = "platform-plugin",
     PrReview = "pr-review",
     Governance = "governance"
 }

package/dist/demo-script.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"demo-script.d.ts","sourceRoot":"","sources":["../src/demo-script.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,kBAAkB,8BAA8B,CAAC;AAE9D,oBAAY,YAAY;IACtB,gBAAgB,sBAAsB;IACtC,cAAc,oBAAoB;IAClC,QAAQ,cAAc;IACtB,UAAU,eAAe;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,OAAO,kBAAkB,CAAC;IAClC,QAAQ,EAAE,YAAY,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,SAAS,eAAe,EAAE,CAAC;CACnC;AAsKD,wBAAgB,iBAAiB,IAAI,SAAS,YAAY,EAAE,CAE3D;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,YAAY,GAAG,WAAW,CAEjE;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAsBjE"}
+{"version":3,"file":"demo-script.d.ts","sourceRoot":"","sources":["../src/demo-script.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,kBAAkB,8BAA8B,CAAC;AAE9D,oBAAY,YAAY;IACtB,gBAAgB,sBAAsB;IACtC,QAAQ,cAAc;IACtB,UAAU,eAAe;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,OAAO,kBAAkB,CAAC;IAClC,QAAQ,EAAE,YAAY,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,SAAS,eAAe,EAAE,CAAC;CACnC;AA2HD,wBAAgB,iBAAiB,IAAI,SAAS,YAAY,EAAE,CAE3D;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,YAAY,GAAG,WAAW,CAEjE;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAsBjE"}

package/dist/demo-script.js

@@ -2,7 +2,6 @@ export const DEMO_SCRIPT_SCHEMA = 'sharkcraft.demo-script/v1';
 export var DemoScenario;
 (function (DemoScenario) {
     DemoScenario["UnconfiguredRepo"] = "unconfigured-repo";
-    DemoScenario["PlatformPlugin"] = "platform-plugin";
     DemoScenario["PrReview"] = "pr-review";
     DemoScenario["Governance"] = "governance";
 })(DemoScenario || (DemoScenario = {}));
@@ -52,48 +51,6 @@ const SCRIPTS = {
             },
         ],
     },
-    [DemoScenario.PlatformPlugin]: {
-        schema: DEMO_SCRIPT_SCHEMA,
-        scenario: DemoScenario.PlatformPlugin,
-        title: 'Add a plugin to a platform-adopter project',
-        description: 'Uses a pack-contributed plugin construct + playbook + lifecycle profile. SharkCraft does not embed any platform-specific assumptions; everything comes from the pack.',
-        steps: [
-            {
-                title: 'Confirm packs loaded',
-                commands: ['shrk packs doctor --require-signatures'],
-                notes: 'Set SHARKCRAFT_PACK_SECRET so signature verification can run.',
-            },
-            {
-                title: 'Inspect the plugin construct contributed by the pack',
-                commands: ['shrk constructs list --filter plugin', 'shrk constructs get <pack>.plugin'],
-            },
-            {
-                title: 'Walk the add-plugin playbook',
-                commands: [
-                    'shrk playbooks recommend "add a profile plugin"',
-                    'shrk playbooks list --filter plugin',
-                ],
-            },
-            {
-                title: 'Use the lifecycle profile (rename / remove preview)',
-                commands: [
-                    'shrk plugin lifecycle profiles',
-                    'shrk plugin lifecycle list --profile <id>',
-                    'shrk plugin rename old new --profile <id> --dry-run',
-                ],
-            },
-            {
-                title: 'Render a chunked agent brief',
-                commands: [
-                    'shrk brief "create a user profile plugin" --mode implementation --chunk --output-dir .sharkcraft/briefs/profile-plugin',
-                ],
-            },
-            {
-                title: 'Start a dev session and let an agent take it from here',
-                commands: ['shrk dev start "create a user profile plugin" --brief'],
-            },
-        ],
-    },
     [DemoScenario.PrReview]: {
         schema: DEMO_SCRIPT_SCHEMA,
         scenario: DemoScenario.PrReview,

package/dist/docs-check.js

@@ -101,7 +101,7 @@ export function buildDocsCheck(projectRoot, options = {}) {
                 severity: 'warning',
                 message: 'README does not explicitly state that MCP is read-only.',
                 file: 'README.md',
-                suggestion: 'Include the phrase "MCP is read-only" so adopters can scan-find it.',
+                suggestion: 'Include the phrase "MCP is read-only" so consumers can scan-find it.',
             });
         }
         // Validate internal links.