@shrkcrft/inspector 0.1.0-alpha.26 → 0.1.0-alpha.28

package/dist/delegate-catalog.d.ts

@@ -8,17 +8,34 @@
  * `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';
+import { type DelegateRecipeMode, type IDelegateRecipe, type ISharkCraftConfig } from '@shrkcrft/config';
 export interface IResolvedDelegateRecipe extends IDelegateRecipe {
+    /**
+     * Recipe mode after defaulting (`'patch'` when unset). Explicit so downstream
+     * surfaces (doctor, list/explain, the analyze path) don't re-derive it.
+     */
+    mode: DelegateRecipeMode;
     /** 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`. */
+    /**
+     * (patch) The write-fence arrays, normalised to present (empty when unset) so
+     * patch consumers never juggle `undefined`. Analysis recipes leave them `[]`.
+     */
+    guardrailGlobs: readonly string[];
+    allowedOps: readonly string[];
+    verificationIds: readonly string[];
+    /** (patch) verificationIds that do NOT resolve to a `verificationCommands[].id`. */
     unboundVerificationIds: readonly string[];
-    /** True when every verificationId resolves AND at least one is declared. */
+    /** (patch) True when every verificationId resolves AND at least one is declared. */
     verificationBound: boolean;
-    /** True when the recipe is safe to delegate (verification fully bound). */
+    /** (analysis) True when `groundedOn` resolves to a known grounding report. */
+    groundingBound: boolean;
+    /**
+     * True when the recipe is safe to run — for a patch recipe, its verification is
+     * fully bound; for an analysis recipe, its grounding report is known.
+     */
     delegatable: boolean;
     /** Where the recipe came from. */
     source: 'config' | 'pack';

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

@@ -1 +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"}
+{"version":3,"file":"delegate-catalog.d.ts","sourceRoot":"","sources":["../src/delegate-catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAA0B,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAEjI,MAAM,WAAW,uBAAwB,SAAQ,eAAe;IAC9D;;;OAGG;IACH,IAAI,EAAE,kBAAkB,CAAC;IACzB,8EAA8E;IAC9E,gBAAgB,EAAE,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAC;IACjD,wFAAwF;IACxF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,oFAAoF;IACpF,sBAAsB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,oFAAoF;IACpF,iBAAiB,EAAE,OAAO,CAAC;IAC3B,8EAA8E;IAC9E,cAAc,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,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,CAgDpC;AAED,gFAAgF;AAChF,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,iBAAiB,EACzB,QAAQ,EAAE,MAAM,GACf,uBAAuB,GAAG,SAAS,CAErC"}

package/dist/delegate-catalog.js

@@ -1,3 +1,14 @@
+/**
+ * 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 { DELEGATE_GROUNDING_IDS } from '@shrkcrft/config';
 /**
  * Resolve the delegate catalog from config + pack-contributed recipes.
  *
@@ -29,15 +40,28 @@ export function resolveDelegateCatalog(config, packRecipes = []) {
             ...(ov?.verificationIds !== undefined ? { verificationIds: ov.verificationIds } : {}),
             ...(ov?.guardrailGlobs !== undefined ? { guardrailGlobs: ov.guardrailGlobs } : {}),
         };
+        const mode = merged.mode ?? 'patch';
         const unbound = (merged.verificationIds ?? []).filter((id) => !known.has(id));
         const verificationBound = unbound.length === 0 && (merged.verificationIds ?? []).length > 0;
+        const groundingBound = typeof merged.groundedOn === 'string' &&
+            DELEGATE_GROUNDING_IDS.includes(merged.groundedOn);
+        // A patch recipe is runnable when its verification binds; an analysis recipe
+        // when its grounding report is known. `delegatable` unifies "safe to run".
+        const delegatable = mode === 'analysis' ? groundingBound : verificationBound;
         out.push({
             ...merged,
+            mode,
+            // Normalise the write-fence arrays to present so patch consumers of the
+            // resolved recipe never juggle `undefined` (analysis recipes stay `[]`).
+            guardrailGlobs: merged.guardrailGlobs ?? [],
+            allowedOps: merged.allowedOps ?? [],
+            verificationIds: merged.verificationIds ?? [],
             resolvedProvider: merged.provider ?? delegation.provider ?? 'auto',
             ...(merged.model ?? delegation.model ? { resolvedModel: merged.model ?? delegation.model } : {}),
             unboundVerificationIds: unbound,
             verificationBound,
-            delegatable: verificationBound,
+            groundingBound,
+            delegatable,
             source,
             ...(packageName ? { packageName } : {}),
         });

package/dist/delegate-doctor.d.ts

@@ -9,7 +9,7 @@
  * which can load pack files async); silent when the repo hasn't opted into
  * delegation.
  */
-import type { ISharkCraftConfig } from '@shrkcrft/config';
+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

@@ -1 +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"}
+{"version":3,"file":"delegate-doctor.d.ts","sourceRoot":"","sources":["../src/delegate-doctor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAsB,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC9E,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGvE,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,GAAG,YAAY,EAAE,CAsE1F"}

package/dist/delegate-doctor.js

@@ -1,3 +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 { DELEGATE_QUERY_IDS } from '@shrkcrft/config';
 import { DoctorSeverity } from "./doctor-result.js";
 import { resolveDelegateCatalog } from "./delegate-catalog.js";
 export function buildDelegateRecipeChecks(config) {
@@ -9,26 +21,65 @@ export function buildDelegateRecipeChecks(config) {
     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';
+        const isAnalysis = r.mode === 'analysis';
+        const reason = isAnalysis
+            ? `groundedOn "${r.groundedOn ?? '(unset)'}" is not a known grounding report`
+            : r.unboundVerificationIds.length > 0
+                ? `verificationIds not in verificationCommands[]: ${r.unboundVerificationIds.join(', ')}`
+                : 'no verificationIds declared';
+        const consequence = isAnalysis
+            ? `\`shrk delegate analyze --recipe ${r.id}\` has no deterministic ground truth to check the model against.`
+            : `\`shrk delegate run --recipe ${r.id}\` would refuse to apply an unverified edit.`;
         out.push({
             id: `delegate-recipe-${r.id}`,
-            title: `Delegate recipe "${r.id}" is not delegatable`,
+            title: `Delegate recipe "${r.id}" is not ${isAnalysis ? 'usable' : 'delegatable'}`,
             severity: DoctorSeverity.Warning,
-            message: `${reason} — \`shrk delegate run --recipe ${r.id}\` would refuse to apply an unverified edit.`,
+            message: `${reason} — ${consequence}`,
             category: 'delegate',
-            code: 'recipe-unverified',
+            code: isAnalysis ? 'recipe-ungrounded' : '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.',
+            whyThisMatters: isAnalysis
+                ? 'An analysis recipe grounds the model on a deterministic report; without a known groundedOn there is no ground truth to cross-check findings against, so the recipe is unusable.'
+                : '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) {
+    // Analysis-recipe config health beyond grounding (validateConfig isn't run at
+    // load, so these would otherwise silently misbehave): unknown query ids and an
+    // escalateTo that doesn't resolve to a patch recipe.
+    const patchIds = new Set(catalog.filter((r) => r.mode !== 'analysis').map((r) => r.id));
+    for (const r of catalog) {
+        if (r.mode !== 'analysis')
+            continue;
+        const badQueries = (r.allowedQueries ?? []).filter((q) => !DELEGATE_QUERY_IDS.includes(q));
+        if (badQueries.length > 0) {
+            out.push({
+                id: `delegate-recipe-${r.id}-queries`,
+                title: `Delegate recipe "${r.id}" has unknown allowedQueries`,
+                severity: DoctorSeverity.Warning,
+                message: `${badQueries.join(', ')} — not in DELEGATE_QUERY_IDS (${DELEGATE_QUERY_IDS.join(', ')}); the model can never call them.`,
+                category: 'delegate',
+                code: 'recipe-unknown-query',
+                recommendedFix: `shrk delegate explain ${r.id}`,
+            });
+        }
+        if (r.escalateTo !== undefined && !patchIds.has(r.escalateTo)) {
+            out.push({
+                id: `delegate-recipe-${r.id}-escalate`,
+                title: `Delegate recipe "${r.id}" escalates to a non-patch recipe`,
+                severity: DoctorSeverity.Warning,
+                message: `escalateTo "${r.escalateTo}" is not an existing patch recipe — \`--escalate\` would be a no-op.`,
+                category: 'delegate',
+                code: 'recipe-bad-escalation',
+                recommendedFix: `shrk delegate explain ${r.id}`,
+            });
+        }
+    }
+    if (out.length === 0) {
         out.push({
             id: 'delegate-recipes',
             title: 'Delegate recipes',
             severity: DoctorSeverity.Ok,
-            message: `${catalog.length} delegate recipe(s) configured, all delegatable.`,
+            message: `${catalog.length} delegate recipe(s) configured, all healthy.`,
             category: 'delegate',
         });
     }

package/dist/delegate-grounding.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Delegate ANALYSIS grounding (read-only, deterministic — NO model).
+ *
+ * An `analysis` delegate recipe grounds a local model's judgment on a
+ * deterministic report the engine runs FIRST. This module:
+ *   1. runs that report (`runGroundingReport`) and distils it to a compact
+ *      summary + a set of known entities (files / constructs / reason codes);
+ *   2. cross-checks the model's findings against those entities
+ *      (`crossCheckFindings`) — a finding that cites an entity absent from the
+ *      ground truth is flagged `unverified` (or dropped, in strict mode), so the
+ *      model can prioritise/explain but never fabricate a fact;
+ *   3. assembles the honest, advisory `IDelegateAnalysisReport`
+ *      (`buildDelegateAnalysisReport`) — which NEVER writes.
+ *
+ * The model call itself happens in the cli orchestrator, not here (this layer is
+ * pure). MCP surfaces only the grounding, never the model — see the safety model.
+ */
+import type { DelegateGroundingId } from '@shrkcrft/core';
+import { type IBuildTaskRiskOptions } from './task-risk.js';
+import { type IUncertaintyReport } from './uncertainty-report.js';
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export declare const DELEGATE_ANALYSIS_SCHEMA = "sharkcraft.delegate-analysis/v1";
+/** The deterministic ground truth an analysis recipe is checked against. */
+export interface IGroundingFacts {
+    groundedOn: string;
+    /** Compact human-readable summary fed to the model as ground truth. */
+    summary: string;
+    /** Known entities (normalised references the model may legitimately cite). */
+    entities: readonly string[];
+    /** The underlying deterministic report (surfaced in `--json`). */
+    raw: unknown;
+}
+/** One model finding, tagged by the deterministic cross-check. */
+export interface IAnalysisFinding {
+    id: string;
+    message: string;
+    /** Entities the model cited (explicit refs, or refs inferred from the message). */
+    refs: readonly string[];
+    /** True when the finding is anchored to ground truth (via refs or a message mention). */
+    grounded: boolean;
+    /** Cited refs NOT present in the ground truth. */
+    unverifiedRefs: readonly string[];
+}
+/** The read-only advisory report an `analysis` recipe produces. */
+export interface IDelegateAnalysisReport {
+    schema: typeof DELEGATE_ANALYSIS_SCHEMA;
+    generatedAt: string;
+    recipeId: string;
+    mode: 'analysis';
+    groundedOn: string;
+    task: string;
+    /** Which provider produced the findings (`'none'` = deterministic-only). */
+    provider: string;
+    grounding: {
+        summary: string;
+        entityCount: number;
+    };
+    findings: readonly IAnalysisFinding[];
+    groundedCount: number;
+    unverifiedCount: number;
+    /** Optional free-form note from the model (informational, never grounded). */
+    modelNote?: string;
+    /** How many read-only query rounds the model ran (Phase 3 query loop). */
+    queriesRun?: number;
+    /** How many fan-out slices ran (Phase 4), when fan-out was used. */
+    fanOutSlices?: number;
+    /** Advisory escalation into a patch recipe, when the recipe declares escalateTo. */
+    escalation?: {
+        recipe: string;
+        task: string;
+        next: string;
+    };
+    markdown: string;
+    uncertainty: IUncertaintyReport;
+}
+/**
+ * A layer-neutral snapshot of a failed delegate PATCH attempt — the ground truth
+ * a `retry-analysis` recipe reasons over. Kept primitive (no dependency on the
+ * cli-layer `IExecuteDelegateRunResult`) so the cli maps its result onto this and
+ * the inspector grounds on it without an upward import.
+ */
+export interface IDelegateFailureContext {
+    /** The failing status, e.g. `verify-failed` / `conflicts` / `guardrail-refused`. */
+    status: string;
+    message: string;
+    conflicts?: readonly string[];
+    commandsFailed?: readonly string[];
+    refused?: readonly string[];
+    droppedOps?: readonly {
+        kind: string;
+        targetPath: string;
+    }[];
+    guardrailGlobs?: readonly string[];
+    allowedOps?: readonly string[];
+    /** 1-based attempt number this failure occurred on. */
+    attempt?: number;
+}
+/** Options for `runGroundingReport` — task-risk knobs plus grounding payloads. */
+export interface IRunGroundingOptions extends IBuildTaskRiskOptions {
+    /** Required when grounding on `delegate-failure`. */
+    failure?: IDelegateFailureContext;
+    /** Required when grounding on `plan-simulation` — path to a saved plan. */
+    planPath?: string;
+}
+/** Distil a delegate patch failure into ground truth for `retry-analysis`. */
+export declare function buildDelegateFailureFacts(failure: IDelegateFailureContext): IGroundingFacts;
+/**
+ * Run the deterministic report an analysis recipe grounds on, distilled to a
+ * compact summary + the entities a finding may legitimately cite. Read-only.
+ */
+export declare function runGroundingReport(groundedOn: DelegateGroundingId | string, task: string, inspection: ISharkcraftInspection, options?: IRunGroundingOptions): Promise<IGroundingFacts>;
+export interface ICrossCheckOptions {
+    /** Drop non-grounded findings instead of keeping+flagging them. */
+    strict?: boolean;
+}
+export interface ICrossCheckResult {
+    findings: IAnalysisFinding[];
+    groundedCount: number;
+    unverifiedCount: number;
+}
+/**
+ * Cross-check model findings against the deterministic ground truth. A finding is
+ * `grounded` when it cites ≥1 ref that all resolve to a report entity, OR — when
+ * it cites no explicit refs — when its MESSAGE mentions a ground-truth entity
+ * verbatim (models routinely state facts in prose without filling a refs array;
+ * the live smoke showed exactly this). A claim anchored to nothing in the ground
+ * truth stays unverified — judgment must ride on facts the model cannot fabricate.
+ */
+export declare function crossCheckFindings(rawFindings: readonly {
+    id?: string;
+    message: string;
+    refs?: readonly string[];
+}[], facts: IGroundingFacts, options?: ICrossCheckOptions): ICrossCheckResult;
+export interface IBuildAnalysisReportInput {
+    recipeId: string;
+    groundedOn: string;
+    task: string;
+    provider: string;
+    facts: IGroundingFacts;
+    crossCheck: ICrossCheckResult;
+    modelNote?: string;
+    /** True when no local model ran — the report is deterministic grounding only. */
+    modelUnavailable?: boolean;
+    /** Read-only query rounds the model ran (Phase 3), when the query loop was used. */
+    queriesRun?: number;
+    /** Fan-out slices that ran (Phase 4), when fan-out was used. */
+    fanOutSlices?: number;
+    /** A patch recipe this analysis may escalate to (Phase 4, advisory). */
+    escalateTo?: string;
+    generatedAt: string;
+}
+/** Assemble the honest, advisory analysis report. Never writes. */
+export declare function buildDelegateAnalysisReport(input: IBuildAnalysisReportInput): IDelegateAnalysisReport;
+//# sourceMappingURL=delegate-grounding.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"delegate-grounding.d.ts","sourceRoot":"","sources":["../src/delegate-grounding.ts"],"names":[],"mappings":"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"}

package/dist/delegate-grounding.js

@@ -0,0 +1,427 @@
+import { buildTaskRiskReport } from "./task-risk.js";
+import { analyzeTestImpact } from "./test-impact.js";
+import { simulatePlan } from "./plan-simulation.js";
+import { buildAgentBrief } from "./agent-brief.js";
+import * as nodePath from 'node:path';
+import { buildUncertaintyReport } from "./uncertainty-report.js";
+export const DELEGATE_ANALYSIS_SCHEMA = 'sharkcraft.delegate-analysis/v1';
+function norm(s) {
+    // Strip surrounding delimiters/punctuation so a model that echoes a ground-truth
+    // display form (`[intent-migration]`, `` `src/foo.ts` ``) still matches the bare
+    // entity — otherwise a legitimate citation is falsely flagged `unverified`.
+    return s
+        .trim()
+        .toLowerCase()
+        .replace(/^[[\](){}`'"]+/, '')
+        .replace(/[[\](){}`'".,;:]+$/, '');
+}
+function basename(s) {
+    const n = norm(s);
+    const i = n.lastIndexOf('/');
+    return i >= 0 ? n.slice(i + 1) : n;
+}
+function looksLikePath(s) {
+    return /[\/.]/.test(s) && /\.(ts|tsx|js|jsx|mjs|cjs|md|json|ya?ml)$/i.test(s.trim());
+}
+/** Distil a task-risk report into the entities a finding may legitimately cite. */
+function groundingEntitiesFromTaskRisk(r) {
+    const out = new Set();
+    const add = (xs) => {
+        for (const x of xs)
+            if (x && x.trim().length > 0)
+                out.add(x.trim());
+    };
+    add(r.affectedFiles);
+    add(r.highFanInFiles);
+    add(r.highFanOutFiles);
+    add(r.affectedConstructs);
+    add(r.reasons.map((x) => x.code));
+    add(r.ownershipGaps.filter(looksLikePath));
+    return [...out];
+}
+/** The path in a `"path: reason"` conflict string (the citable entity). */
+function conflictPath(c) {
+    const i = c.indexOf(':');
+    return (i >= 0 ? c.slice(0, i) : c).trim();
+}
+/** Distil a delegate patch failure into ground truth for `retry-analysis`. */
+export function buildDelegateFailureFacts(failure) {
+    const entities = new Set();
+    const add = (xs) => {
+        for (const x of xs ?? [])
+            if (x && x.trim().length > 0)
+                entities.add(x.trim());
+    };
+    add((failure.conflicts ?? []).map(conflictPath));
+    add(failure.refused);
+    add((failure.droppedOps ?? []).map((d) => d.targetPath));
+    add(failure.commandsFailed);
+    add(failure.allowedOps);
+    entities.add(failure.status);
+    const lines = [];
+    lines.push(`Delegate patch attempt failed: ${failure.status}${failure.attempt ? ` (attempt ${failure.attempt})` : ''}.`);
+    lines.push(`Message: ${failure.message}`);
+    if (failure.conflicts?.length)
+        lines.push(`Conflicts: ${failure.conflicts.join('; ')}.`);
+    if (failure.commandsFailed?.length)
+        lines.push(`Verification commands failed: ${failure.commandsFailed.join(', ')}.`);
+    if (failure.refused?.length)
+        lines.push(`Targets refused (outside guardrail globs): ${failure.refused.join(', ')}.`);
+    if (failure.droppedOps?.length) {
+        lines.push(`Ops dropped (kind not allowed): ${failure.droppedOps.map((d) => `${d.kind}→${d.targetPath}`).join(', ')}.`);
+    }
+    if (failure.allowedOps?.length)
+        lines.push(`Only these op kinds are allowed: ${failure.allowedOps.join(', ')}.`);
+    if (failure.guardrailGlobs?.length)
+        lines.push(`Only these globs may be touched: ${failure.guardrailGlobs.join(', ')}.`);
+    return { groundedOn: 'delegate-failure', summary: lines.join('\n'), entities: [...entities], raw: failure };
+}
+/** Entities + summary for grounding on the agent brief. */
+function groundingFromAgentBrief(b) {
+    const entities = new Set();
+    if (b.taskRisk) {
+        for (const f of b.taskRisk.affectedFiles)
+            entities.add(f);
+        for (const c of b.taskRisk.affectedConstructs)
+            entities.add(c);
+        for (const f of b.taskRisk.highFanInFiles)
+            entities.add(f);
+    }
+    const risk = b.taskRisk ? `Risk: ${b.taskRisk.riskLevel} (score ${b.taskRisk.score}). ` : '';
+    const summary = `Agent brief for: ${b.task}\n${risk}\n${b.markdown.slice(0, 1400)}`;
+    return { summary, entities: [...entities].filter((x) => x.trim().length > 0) };
+}
+/** Entities a finding may cite when grounded on a test-impact report. */
+function groundingEntitiesFromTestImpact(t) {
+    const out = new Set();
+    const add = (xs) => {
+        for (const x of xs)
+            if (x && x.trim().length > 0)
+                out.add(x.trim());
+    };
+    add(t.inputFiles);
+    add(t.likelyTestFiles);
+    add(t.missingTestFiles);
+    add(t.riskAreas);
+    return [...out];
+}
+/** Entities a finding may cite when grounded on a plan simulation. */
+function groundingEntitiesFromPlanSim(p) {
+    const out = new Set();
+    const add = (xs) => {
+        for (const x of xs)
+            if (x && x.trim().length > 0)
+                out.add(x.trim());
+    };
+    add(p.files.map((f) => f.relativePath));
+    add(p.affectedAreas);
+    add(p.affectedConstructs);
+    add(p.ownershipReviewFiles);
+    add(p.likelyTests);
+    return [...out];
+}
+/** A compact ground-truth summary of a plan simulation for the model prompt. */
+function compactPlanSimSummary(p) {
+    const lines = [];
+    lines.push(`Plan: ${p.source} (${p.templateId ?? 'no-template'}), signature ${p.signature}, readiness ${p.applyReadiness}.`);
+    if (p.files.length > 0)
+        lines.push(`Files: ${p.files.map((f) => `${f.changeType} ${f.relativePath}`).slice(0, 12).join(', ')}.`);
+    if (p.publicApiTouched)
+        lines.push('Touches a public API surface.');
+    if (p.ownershipReviewRequired)
+        lines.push(`Ownership review required: ${p.ownershipReviewFiles.slice(0, 6).join(', ')}.`);
+    if (p.potentialBoundaryConcerns.length > 0)
+        lines.push(`Boundary concerns: ${p.potentialBoundaryConcerns.length}.`);
+    if (p.policyConcerns.length > 0)
+        lines.push(`Policy concerns: ${p.policyConcerns.slice(0, 6).join('; ')}.`);
+    if (p.applyReadinessReasons.length > 0)
+        lines.push(`Readiness reasons: ${p.applyReadinessReasons.slice(0, 6).join('; ')}.`);
+    return lines.join('\n');
+}
+/** A compact ground-truth summary of a test-impact report for the model prompt. */
+function compactTestImpactSummary(t) {
+    const lines = [];
+    lines.push(`Test impact for: ${t.task || '(repo)'} (confidence ${t.confidence}).`);
+    if (t.likelyTestFiles.length > 0)
+        lines.push(`Existing tests: ${t.likelyTestFiles.slice(0, 12).join(', ')}.`);
+    if (t.missingTestFiles.length > 0)
+        lines.push(`Missing tests (expected locations): ${t.missingTestFiles.slice(0, 12).join(', ')}.`);
+    if (t.riskAreas.length > 0)
+        lines.push(`Risk areas: ${t.riskAreas.slice(0, 8).join('; ')}.`);
+    if (t.minimalCommands.length > 0)
+        lines.push(`Minimal test command(s): ${t.minimalCommands.join(' ; ')}.`);
+    return lines.join('\n');
+}
+/** A compact ground-truth summary for the model prompt (not the full report). */
+function compactTaskRiskSummary(r) {
+    const lines = [];
+    lines.push(`Task risk: ${r.riskLevel} (score ${r.score}), intent ${r.intent.kind}.`);
+    lines.push(`Human approval required: ${r.humanApprovalRequired ? 'yes' : 'no'}.`);
+    if (r.affectedFiles.length > 0)
+        lines.push(`Affected files: ${r.affectedFiles.slice(0, 12).join(', ')}.`);
+    if (r.highFanInFiles.length > 0)
+        lines.push(`High fan-in: ${r.highFanInFiles.join(', ')}.`);
+    if (r.boundaryConcerns.length > 0)
+        lines.push(`Boundary concerns: ${r.boundaryConcerns.slice(0, 6).join('; ')}.`);
+    if (r.policyConcerns.length > 0)
+        lines.push(`Policy concerns: ${r.policyConcerns.slice(0, 6).join('; ')}.`);
+    if (r.testGaps.length > 0)
+        lines.push(`Test gaps: ${r.testGaps.slice(0, 6).join('; ')}.`);
+    lines.push('Reasons:');
+    for (const reason of r.reasons.slice(0, 12))
+        lines.push(`  - [${reason.code}] ${reason.message} (+${reason.weight})`);
+    return lines.join('\n');
+}
+/**
+ * Run the deterministic report an analysis recipe grounds on, distilled to a
+ * compact summary + the entities a finding may legitimately cite. Read-only.
+ */
+export async function runGroundingReport(groundedOn, task, inspection, options = {}) {
+    switch (groundedOn) {
+        case 'task-risk': {
+            const r = await buildTaskRiskReport(task, inspection, options);
+            return {
+                groundedOn,
+                summary: compactTaskRiskSummary(r),
+                entities: groundingEntitiesFromTaskRisk(r),
+                raw: r,
+            };
+        }
+        case 'test-impact': {
+            const t = analyzeTestImpact(inspection, { task });
+            return {
+                groundedOn,
+                summary: compactTestImpactSummary(t),
+                entities: groundingEntitiesFromTestImpact(t),
+                raw: t,
+            };
+        }
+        case 'agent-brief': {
+            const b = await buildAgentBrief(inspection, { task });
+            const { summary, entities } = groundingFromAgentBrief(b);
+            return { groundedOn, summary, entities, raw: b };
+        }
+        case 'plan-simulation': {
+            // Grounded on a saved plan the cli supplies via `options.planPath`. Absent
+            // it (or on a read error) there is nothing to critique.
+            if (!options.planPath) {
+                return { groundedOn, summary: '(plan-simulation grounding needs a --plan <path>)', entities: [], raw: null };
+            }
+            try {
+                const abs = nodePath.isAbsolute(options.planPath)
+                    ? options.planPath
+                    : nodePath.resolve(inspection.projectRoot, options.planPath);
+                const p = await simulatePlan(inspection, abs, { includeBoundaries: true, includeImpact: true, includeOwnership: true });
+                return { groundedOn, summary: compactPlanSimSummary(p), entities: groundingEntitiesFromPlanSim(p), raw: p };
+            }
+            catch (e) {
+                return { groundedOn, summary: `(could not simulate plan: ${e.message})`, entities: [], raw: null };
+            }
+        }
+        case 'delegate-failure':
+            // Grounded on a failed patch attempt — the cli supplies the failure via
+            // `options.failure` (this grounding needs no inspection). Absent it, there
+            // is nothing to reason over (e.g. a standalone MCP/CLI call with no failure).
+            return options.failure
+                ? buildDelegateFailureFacts(options.failure)
+                : {
+                    groundedOn,
+                    summary: '(delegate-failure grounding needs a failure context — run it in the delegate retry loop)',
+                    entities: [],
+                    raw: null,
+                };
+        default:
+            // Config validation gates `groundedOn` to a known id, so this is a
+            // defensive fallback (empty ground truth ⇒ every claim is unverified).
+            return { groundedOn, summary: `(no grounding runner for "${groundedOn}")`, entities: [], raw: null };
+    }
+}
+/**
+ * Cross-check model findings against the deterministic ground truth. A finding is
+ * `grounded` when it cites ≥1 ref that all resolve to a report entity, OR — when
+ * it cites no explicit refs — when its MESSAGE mentions a ground-truth entity
+ * verbatim (models routinely state facts in prose without filling a refs array;
+ * the live smoke showed exactly this). A claim anchored to nothing in the ground
+ * truth stays unverified — judgment must ride on facts the model cannot fabricate.
+ */
+export function crossCheckFindings(rawFindings, facts, options = {}) {
+    const entities = new Set(facts.entities.map(norm));
+    const basenames = new Set(facts.entities.map(basename));
+    const resolves = (ref) => entities.has(norm(ref)) || basenames.has(basename(ref));
+    // Entities long enough to match unambiguously inside prose (avoid noise from
+    // very short codes). Matched case-insensitively as a substring of the message.
+    const scannable = facts.entities.filter((e) => e.trim().length >= 4);
+    const mentionedIn = (message) => {
+        const m = message.toLowerCase();
+        const hits = [];
+        for (const e of scannable) {
+            const en = e.toLowerCase();
+            const bn = basename(e);
+            if (m.includes(en) || (bn.length >= 4 && m.includes(bn)))
+                hits.push(e);
+        }
+        return hits;
+    };
+    const findings = [];
+    let groundedCount = 0;
+    let unverifiedCount = 0;
+    for (let i = 0; i < rawFindings.length; i += 1) {
+        const rf = rawFindings[i];
+        const explicit = (rf.refs ?? []).map((r) => String(r));
+        let refs = explicit;
+        let unverifiedRefs = explicit.filter((r) => !resolves(r));
+        let grounded = explicit.length > 0 && unverifiedRefs.length === 0;
+        if (!grounded && explicit.length === 0) {
+            // Fallback: the model stated facts in prose. Infer refs from the message.
+            const inferred = mentionedIn(rf.message);
+            if (inferred.length > 0) {
+                refs = inferred;
+                unverifiedRefs = [];
+                grounded = true;
+            }
+        }
+        if (options.strict && !grounded) {
+            unverifiedCount += 1;
+            continue; // dropped
+        }
+        findings.push({
+            id: rf.id?.trim() || `finding-${i + 1}`,
+            message: rf.message,
+            refs,
+            grounded,
+            unverifiedRefs,
+        });
+        if (grounded)
+            groundedCount += 1;
+        else
+            unverifiedCount += 1;
+    }
+    return { findings, groundedCount, unverifiedCount };
+}
+function buildAnalysisUncertainty(input) {
+    const { crossCheck, modelUnavailable } = input;
+    let confidence = 'medium';
+    const reasons = [];
+    const missing = [];
+    if (modelUnavailable) {
+        confidence = 'unknown';
+        reasons.push('No local LLM reachable — deterministic grounding only, no judgment layer.');
+        missing.push({ id: 'no-model', message: 'No local model produced findings.' });
+    }
+    else if (crossCheck.findings.length === 0) {
+        confidence = 'low';
+        reasons.push('The model returned no findings.');
+    }
+    else if (crossCheck.unverifiedCount > crossCheck.groundedCount) {
+        confidence = 'low';
+        reasons.push(`${crossCheck.unverifiedCount} of ${crossCheck.findings.length} finding(s) are unverified (cite entities absent from the ground truth).`);
+    }
+    if (input.facts.entities.length === 0) {
+        missing.push({ id: 'empty-grounding', message: 'The grounding report yielded no entities to check against.' });
+    }
+    return buildUncertaintyReport({
+        confidence,
+        reasons,
+        missingSignals: missing,
+        suggestedCommands: [`shrk risk "${input.task || '<task>'}"`, `shrk delegate explain ${input.recipeId}`],
+        safeFallbackCommand: `shrk risk "${input.task || '<task>'}"`,
+    });
+}
+function renderAnalysisMarkdown(input) {
+    const { crossCheck, facts } = input;
+    const lines = [];
+    lines.push(`# Delegate analysis — ${input.recipeId}`);
+    lines.push('');
+    lines.push(`- task: ${input.task || '(none)'}`);
+    lines.push(`- grounded on: **${input.groundedOn}**`);
+    lines.push(`- provider: ${input.provider}`);
+    if (input.queriesRun !== undefined)
+        lines.push(`- query rounds: ${input.queriesRun} (read-only fact-fetch loop)`);
+    if (input.fanOutSlices !== undefined)
+        lines.push(`- fan-out slices: ${input.fanOutSlices} (per-slice passes, merged)`);
+    lines.push(`- findings: ${crossCheck.findings.length} (grounded ${crossCheck.groundedCount}, unverified ${crossCheck.unverifiedCount})`);
+    lines.push('');
+    lines.push('## Ground truth');
+    lines.push('');
+    lines.push(facts.summary);
+    lines.push('');
+    lines.push('## Findings');
+    lines.push('');
+    if (crossCheck.findings.length === 0) {
+        lines.push(input.modelUnavailable
+            ? '_No local LLM reachable — deterministic grounding only. Start Ollama / set LLAMACPP_MODEL_PATH to add the judgment layer._'
+            : '_(none)_');
+    }
+    else {
+        for (const f of crossCheck.findings) {
+            const tag = f.grounded ? '✓ grounded' : '⚠ unverified';
+            lines.push(`- **[${tag}]** ${f.message}`);
+            if (f.refs.length > 0)
+                lines.push(`  - refs: ${f.refs.join(', ')}`);
+            if (f.unverifiedRefs.length > 0)
+                lines.push(`  - not in ground truth: ${f.unverifiedRefs.join(', ')}`);
+        }
+    }
+    if (input.modelNote) {
+        lines.push('');
+        lines.push('## Model note (informational)');
+        lines.push('');
+        lines.push(input.modelNote);
+    }
+    const escalation = escalationHint(input);
+    if (escalation) {
+        lines.push('');
+        lines.push('## Suggested escalation (advisory — you run it)');
+        lines.push('');
+        lines.push(`This gap can be handed to the patch recipe \`${escalation.recipe}\`:`);
+        lines.push('```');
+        lines.push(escalation.next);
+        lines.push('```');
+    }
+    lines.push('');
+    lines.push('---');
+    lines.push('_Advisory, read-only — no write performed. Findings tagged `unverified` cite entities absent from the deterministic ground truth; treat them as hypotheses, not facts._');
+    return lines.join('\n');
+}
+/** Assemble the honest, advisory analysis report. Never writes. */
+export function buildDelegateAnalysisReport(input) {
+    const report = {
+        schema: DELEGATE_ANALYSIS_SCHEMA,
+        generatedAt: input.generatedAt,
+        recipeId: input.recipeId,
+        mode: 'analysis',
+        groundedOn: input.groundedOn,
+        task: input.task,
+        provider: input.provider,
+        grounding: { summary: input.facts.summary, entityCount: input.facts.entities.length },
+        findings: input.crossCheck.findings,
+        groundedCount: input.crossCheck.groundedCount,
+        unverifiedCount: input.crossCheck.unverifiedCount,
+        markdown: renderAnalysisMarkdown(input),
+        uncertainty: buildAnalysisUncertainty(input),
+    };
+    if (input.modelNote)
+        report.modelNote = input.modelNote;
+    if (input.queriesRun !== undefined)
+        report.queriesRun = input.queriesRun;
+    if (input.fanOutSlices !== undefined)
+        report.fanOutSlices = input.fanOutSlices;
+    const escalation = escalationHint(input);
+    if (escalation)
+        report.escalation = escalation;
+    return report;
+}
+/** Advisory next-command into a patch recipe, when findings warrant escalation. */
+function escalationHint(input) {
+    if (!input.escalateTo)
+        return undefined;
+    const anchor = input.crossCheck.findings.find((f) => f.grounded) ?? input.crossCheck.findings[0];
+    if (!anchor)
+        return undefined;
+    const task = anchor.message.slice(0, 120);
+    return {
+        recipe: input.escalateTo,
+        task,
+        next: `shrk delegate run "${task}" --recipe ${input.escalateTo} --apply`,
+    };
+}

package/dist/docs-check.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs-check.d.ts","sourceRoot":"","sources":["../src/docs-check.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,eAAO,MAAM,iBAAiB,6BAA6B,CAAC;AAE5D,MAAM,WAAW,iBAAiB;IAChC,IAAI,EACA,sBAAsB,GACtB,wBAAwB,GACxB,oBAAoB,GACpB,0BAA0B,GAC1B,gCAAgC,GAChC,yBAAyB,CAAC;IAC9B,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,OAAO,iBAAiB,CAAC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACvC,aAAa,EAAE,OAAO,CAAC;IACvB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,EAAE,EAAE,OAAO,CAAC;CACb;AAwCD,MAAM,WAAW,sBAAsB;IACrC;2CACuC;IACvC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,wBAAgB,cAAc,CAC5B,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,sBAA2B,GACnC,gBAAgB,CA+IlB;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAepE"}
+{"version":3,"file":"docs-check.d.ts","sourceRoot":"","sources":["../src/docs-check.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,eAAO,MAAM,iBAAiB,6BAA6B,CAAC;AAE5D,MAAM,WAAW,iBAAiB;IAChC,IAAI,EACA,sBAAsB,GACtB,wBAAwB,GACxB,oBAAoB,GACpB,0BAA0B,GAC1B,gCAAgC,GAChC,yBAAyB,CAAC;IAC9B,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,OAAO,iBAAiB,CAAC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACvC,aAAa,EAAE,OAAO,CAAC;IACvB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,EAAE,EAAE,OAAO,CAAC;CACb;AAyCD,MAAM,WAAW,sBAAsB;IACrC;2CACuC;IACvC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,wBAAgB,cAAc,CAC5B,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,sBAA2B,GACnC,gBAAgB,CA+IlB;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAepE"}

package/dist/docs-check.js

@@ -19,6 +19,7 @@ const REQUIRED_DOCS = [
     'philosophy.md',
     'safety-model.md',
     'testing.md',
+    'exit-codes.md',
 ];
 const README_REQUIRED_KEYWORDS = ['quick demo', 'onboard', 'safety'];
 const README_SAFETY_KEYWORDS = ['mcp', 'read-only', 'never writes', 'safety'];

package/dist/git-helpers.d.ts

@@ -21,6 +21,22 @@ export declare function isGitRepo(cwd: string): boolean;
 export declare function getGitRoot(cwd: string): string | null;
 export declare function getGitBranch(cwd: string): string | null;
 export declare function getChangedFiles(cwd: string, opts?: IGitChangedOptions): string[];
+/**
+ * True when `ref` resolves to a commit in `cwd`'s repo. Lets a caller tell a
+ * genuinely-empty diff apart from a bad ref — `getChangedFiles` returns `[]` for
+ * both (a failed `git diff <bad-ref>` yields no names), so a gate that scopes on
+ * `--base <ref>` must validate the ref first or it reports "nothing changed"
+ * (a false verified-nothing) over a typo'd ref.
+ */
+export declare function refExists(cwd: string, ref: string): boolean;
+/**
+ * The content of `relPath` at `ref` (e.g. `git show HEAD:src/x.ts`), or `null`
+ * when the path did not exist at that ref (a newly-added file) or git failed.
+ * `relPath` is repo-root-relative. Used to diff a file's PAST state against the
+ * working tree without a checkout — e.g. to see what a now-edited file used to
+ * provide/register.
+ */
+export declare function gitShowFile(cwd: string, ref: string, relPath: string): string | null;
 export declare function getStatusSummary(cwd: string): IGitStatusSummary;
 export interface ICommitInfo {
     readonly hash: string;

package/dist/git-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"git-helpers.d.ts","sourceRoot":"","sources":["../src/git-helpers.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,kBAAkB;IACjC,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,gEAAgE;IAChE,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;CAChB;AAqBD,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAI9C;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKrD;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKvD;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,kBAAuB,GAAG,MAAM,EAAE,CAwBpF;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAyC/D;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,WAAW,EAAE,CA6BrF;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAKjD"}
+{"version":3,"file":"git-helpers.d.ts","sourceRoot":"","sources":["../src/git-helpers.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,kBAAkB;IACjC,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,gEAAgE;IAChE,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;CAChB;AAqBD,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAI9C;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKrD;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKvD;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,kBAAuB,GAAG,MAAM,EAAE,CAwBpF;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAI3D;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGpF;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAyC/D;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,WAAW,EAAE,CA6BrF;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAKjD"}

package/dist/git-helpers.js

@@ -67,6 +67,30 @@ export function getChangedFiles(cwd, opts = {}) {
     }
     return [...set].sort();
 }
+/**
+ * True when `ref` resolves to a commit in `cwd`'s repo. Lets a caller tell a
+ * genuinely-empty diff apart from a bad ref — `getChangedFiles` returns `[]` for
+ * both (a failed `git diff <bad-ref>` yields no names), so a gate that scopes on
+ * `--base <ref>` must validate the ref first or it reports "nothing changed"
+ * (a false verified-nothing) over a typo'd ref.
+ */
+export function refExists(cwd, ref) {
+    if (!ref)
+        return false;
+    const r = runGit(cwd, ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`]);
+    return r.ok && r.stdout.trim().length > 0;
+}
+/**
+ * The content of `relPath` at `ref` (e.g. `git show HEAD:src/x.ts`), or `null`
+ * when the path did not exist at that ref (a newly-added file) or git failed.
+ * `relPath` is repo-root-relative. Used to diff a file's PAST state against the
+ * working tree without a checkout — e.g. to see what a now-edited file used to
+ * provide/register.
+ */
+export function gitShowFile(cwd, ref, relPath) {
+    const r = runGit(cwd, ['show', `${ref}:${relPath}`]);
+    return r.ok ? r.stdout : null;
+}
 export function getStatusSummary(cwd) {
     const empty = {
         branch: null,

package/dist/import-hygiene.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"import-hygiene.d.ts","sourceRoot":"","sources":["../src/import-hygiene.ts"],"names":[],"mappings":"AAsBA,eAAO,MAAM,qBAAqB,iCAAiC,CAAC;AAEpE,oBAAY,wBAAwB;IAClC,gBAAgB,uBAAuB;IACvC,cAAc,oBAAoB;IAClC,aAAa,mBAAmB;CACjC;AAED,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;AAEjE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAAC;IACzC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,OAAO,qBAAqB,CAAC;IAC9C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACpD,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAClD,QAAQ,CAAC,OAAO,EAAE,IAAI,GAAG,UAAU,GAAG,QAAQ,CAAC;IAC/C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,qBAAqB;IACpC,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,oDAAoD;IACpD,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,gDAAgD;IAChD,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC,0FAA0F;IAC1F,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAC3C;AAED;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,UAAU,CAAC;AAEpD,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,OAAO,CAKvE;AAED,MAAM,WAAW,eAAe;IAC9B,0BAA0B;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,QAAQ,CAAC,IAAI,CAAC,EAAE,wBAAwB,CAAC;IACzC,mCAAmC;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iFAAiF;IACjF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAwOD,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,qBAA0B,GAClC,oBAAoB,CAwCtB;AAID,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,MAAM,EAAE,wCAAwC,CAAC;IAC1D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,wBAAwB,GAAG,KAAK,CAAC;IACjD,gEAAgE;IAChE,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;CACjC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,+BAA+B,CAC7C,MAAM,EAAE,oBAAoB,EAC5B,OAAO,GAAE,qBAA0B,GAClC,4BAA4B,CAyB9B;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CAiB5E"}
+{"version":3,"file":"import-hygiene.d.ts","sourceRoot":"","sources":["../src/import-hygiene.ts"],"names":[],"mappings":"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"}

package/dist/import-hygiene.js

@@ -251,6 +251,15 @@ function stripCommentsPreservingOffsets(source) {
     }
     return buf.join('');
 }
+/**
+ * Files import-hygiene never gates: test + fixture sources. Their whole PURPOSE
+ * is often to CONTAIN import-like text (`"const x = require('./y')"` as a string
+ * literal feeding a scanner test), so gating them produces false positives. The
+ * whole-tree scan has always excluded them; this constant makes the explicit
+ * `files` path (changed-only / `finish`) apply the SAME rule so the two can't
+ * drift — a change to a test file no longer spuriously fails an imports gate.
+ */
+const EXCLUDED_FROM_HYGIENE = /__tests__|\/__fixtures__/;
 function defaultRoots(projectRoot) {
     const pkgsDir = nodePath.join(projectRoot, 'packages');
     if (!existsSync(pkgsDir))
@@ -272,10 +281,11 @@ export function buildImportHygieneReport(projectRoot, options = {}) {
     if (options.files && options.files.length > 0) {
         scanned = options.files
             .map((f) => (nodePath.isAbsolute(f) ? f : nodePath.join(projectRoot, f)))
-            .filter((f) => existsSync(f) && /\.(ts|tsx)$/.test(f) && !/\.d\.ts$/.test(f));
+            .filter((f) => existsSync(f) && /\.(ts|tsx)$/.test(f) && !/\.d\.ts$/.test(f))
+            .filter((f) => !EXCLUDED_FROM_HYGIENE.test(f));
     }
     else {
-        scanned = roots.flatMap(listSourceFiles).filter((f) => !/__tests__|\/__fixtures__/.test(f));
+        scanned = roots.flatMap(listSourceFiles).filter((f) => !EXCLUDED_FROM_HYGIENE.test(f));
     }
     const findings = [];
     const strictReasons = options.strictAllowlistReasons === true;

package/dist/index.d.ts

@@ -146,6 +146,7 @@ export * from './migration-readiness.js';
 export * from './contract-file-rule.js';
 export * from './check-guardrail-globs.js';
 export * from './delegate-catalog.js';
+export * from './delegate-grounding.js';
 export * from './delegate-pack-recipes.js';
 export * from './delegate-doctor.js';
 export * from './agent-contract.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -146,6 +146,7 @@ export * from "./migration-readiness.js";
 export * from "./contract-file-rule.js";
 export * from "./check-guardrail-globs.js";
 export * from "./delegate-catalog.js";
+export * from "./delegate-grounding.js";
 export * from "./delegate-pack-recipes.js";
 export * from "./delegate-doctor.js";
 export * from "./agent-contract.js";

package/dist/resolve-project-config.d.ts

@@ -1,7 +1,7 @@
 import { type AppError, type Result } from '@shrkcrft/core';
 import { type LoadedConfig } from '@shrkcrft/config';
 /**
- * A {@link LoadedConfig} whose four data planes have had pack contributions
+ * A {@link LoadedConfig} whose data planes have had pack contributions
  * merged in (local-wins), plus the human-readable notes from that merge.
  */
 export interface IResolvedProjectConfig extends LoadedConfig {

package/dist/resolve-project-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-project-config.d.ts","sourceRoot":"","sources":["../src/resolve-project-config.ts"],"names":[],"mappings":"AAuBA,OAAO,EAGL,KAAK,QAAQ,EAMb,KAAK,MAAM,EACZ,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAOL,KAAK,YAAY,EAClB,MAAM,kBAAkB,CAAC;AAG1B;;;GAGG;AACH,MAAM,WAAW,sBAAuB,SAAQ,YAAY;IAC1D;;;;;;OAMG;IACH,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9C;AAoHD;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,MAAM,CAAC,sBAAsB,EAAE,QAAQ,CAAC,CAAC,CAoEnD"}
+{"version":3,"file":"resolve-project-config.d.ts","sourceRoot":"","sources":["../src/resolve-project-config.ts"],"names":[],"mappings":"AAwBA,OAAO,EAGL,KAAK,QAAQ,EAQb,KAAK,MAAM,EACZ,MAAM,gBAAgB,CAAC;AACxB,OAAO,EASL,KAAK,YAAY,EAClB,MAAM,kBAAkB,CAAC;AAG1B;;;GAGG;AACH,MAAM,WAAW,sBAAuB,SAAQ,YAAY;IAC1D;;;;;;OAMG;IACH,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9C;AAiID;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,MAAM,CAAC,sBAAsB,EAAE,QAAQ,CAAC,CAAC,CAqGnD"}

package/dist/resolve-project-config.js

@@ -1,8 +1,9 @@
 /**
  * Pack-aware project-config resolution.
  *
- * The four "cross-file invariant as DATA" planes — `wiringRules`, `registries`,
- * `policyRules`, `reusePrimitives` — can be authored inline in a repo's
+ * The "cross-file invariant as DATA" planes — `wiringRules`, `registries`,
+ * `registrationGraph`, `policyRules`, `baselines`, `generatedArtifacts`,
+ * `reusePrimitives` — can be authored inline in a repo's
  * `sharkcraft.config.ts`. They can ALSO be SHIPPED by a framework pack (e.g. a
  * NestJS pack contributing "every @Injectable must be registered in a module"
  * as a wiring rule) via the new `wiringRuleFiles` / `registryFiles` /
@@ -22,7 +23,7 @@
 import { existsSync } from 'node:fs';
 import * as nodePath from 'node:path';
 import { importModuleViaLoader, ok, } from '@shrkcrft/core';
-import { loadProjectConfig, PolicyRuleSchema, RegistrationIdiomSchema, RegistryDeclarationSchema, ReusePrimitiveSchema, WiringRuleSchema, } from '@shrkcrft/config';
+import { BaselineRuleSchema, GeneratedArtifactRuleSchema, loadProjectConfig, PolicyRuleSchema, RegistrationIdiomSchema, RegistryDeclarationSchema, ReusePrimitiveSchema, WiringRuleSchema, } from '@shrkcrft/config';
 import { discoverPacks } from '@shrkcrft/packs';
 /**
  * Generic per-plane load + validate + merge. Seeds the merged map from the
@@ -31,7 +32,13 @@ import { discoverPacks } from '@shrkcrft/packs';
  * elements, and key collisions all become diagnostics and are skipped — never a
  * throw.
  */
-async function mergePlane(localArr, packContribs, schema, keyOf, planeLabel, diagnostics) {
+async function mergePlane(localArr, packContribs, schema, keyOf, planeLabel, diagnostics, 
+/**
+ * Optional per-item veto applied to PACK elements only. Returns the
+ * diagnostic to record when the element must not be adopted (used by the
+ * shell-executing planes — see the call sites).
+ */
+packGuard) {
     const merged = new Map();
     const localKeys = new Set();
     for (const item of localArr) {
@@ -68,6 +75,11 @@ async function mergePlane(localArr, packContribs, schema, keyOf, planeLabel, dia
                 continue;
             }
             const item = parsed.data;
+            const veto = packGuard?.(item, contrib.packageName);
+            if (veto !== undefined) {
+                diagnostics.push(veto);
+                continue;
+            }
             const key = keyOf(item);
             if (merged.has(key)) {
                 diagnostics.push(localKeys.has(key)
@@ -120,6 +132,19 @@ export async function resolveProjectConfig(cwd) {
     const registries = await mergePlane(base.config.registries ?? [], gatherPackContribs(validPacks, 'registryFiles'), RegistryDeclarationSchema, (r) => r.name, 'registry', diagnostics);
     const registrationGraph = await mergePlane(base.config.registrationGraph ?? [], gatherPackContribs(validPacks, 'registrationGraphFiles'), RegistrationIdiomSchema, (r) => r.name, 'registrationIdiom', diagnostics);
     const policyRules = await mergePlane(base.config.policyRules ?? [], gatherPackContribs(validPacks, 'policyRuleFiles'), PolicyRuleSchema, (r) => r.id, 'policyRule', diagnostics);
+    // The two SHELL-EXECUTING planes. A pack ships code the repo did not write;
+    // letting it also ship a command that `shrk baseline check` would then RUN is
+    // the same hazard the "pack-contributed verification commands are NOT
+    // auto-run" contract already forbids. So the merge keeps the safe subset —
+    // extractor computes and header-only generated rules — and drops the rest
+    // with a diagnostic. The guarantee is structural: no downstream caller has to
+    // remember to re-check provenance.
+    const baselines = await mergePlane(base.config.baselines ?? [], gatherPackContribs(validPacks, 'baselineFiles'), BaselineRuleSchema, (r) => r.id, 'baseline', diagnostics, (item, packName) => item.compute?.kind === 'command'
+        ? `pack ${packName}: baseline "${item.id}" declares a shell \`compute.run\` — pack-contributed commands are never auto-run — skipped`
+        : undefined);
+    const generatedArtifacts = await mergePlane(base.config.generatedArtifacts ?? [], gatherPackContribs(validPacks, 'generatedArtifactFiles'), GeneratedArtifactRuleSchema, (r) => r.id, 'generatedArtifact', diagnostics, (item, packName) => item.regen !== undefined
+        ? `pack ${packName}: generatedArtifact "${item.id}" declares a \`regen\` command — pack-contributed commands are never auto-run — skipped`
+        : undefined);
     const reusePrimitives = await mergePlane(base.config.reusePrimitives ?? [], gatherPackContribs(validPacks, 'reusePrimitiveFiles'), ReusePrimitiveSchema, (r) => r.symbol, 'reusePrimitive', diagnostics);
     return ok({
         ...base,
@@ -129,6 +154,8 @@ export async function resolveProjectConfig(cwd) {
             registries,
             registrationGraph,
             policyRules,
+            baselines,
+            generatedArtifacts,
             reusePrimitives,
         },
         planeDiagnostics: diagnostics,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shrkcrft/inspector",
-  "version": "0.1.0-alpha.26",
+  "version": "0.1.0-alpha.28",
   "description": "SharkCraft inspector: project overview, doctor checks, AI-agent instructions.",
   "license": "MIT",
   "author": "SharkCraft contributors",
@@ -42,22 +42,22 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@shrkcrft/core": "^0.1.0-alpha.26",
-    "@shrkcrft/config": "^0.1.0-alpha.26",
-    "@shrkcrft/workspace": "^0.1.0-alpha.26",
-    "@shrkcrft/knowledge": "^0.1.0-alpha.26",
-    "@shrkcrft/rules": "^0.1.0-alpha.26",
-    "@shrkcrft/paths": "^0.1.0-alpha.26",
-    "@shrkcrft/templates": "^0.1.0-alpha.26",
-    "@shrkcrft/context": "^0.1.0-alpha.26",
-    "@shrkcrft/pipelines": "^0.1.0-alpha.26",
-    "@shrkcrft/packs": "^0.1.0-alpha.26",
-    "@shrkcrft/presets": "^0.1.0-alpha.26",
-    "@shrkcrft/boundaries": "^0.1.0-alpha.26",
-    "@shrkcrft/generator": "^0.1.0-alpha.26",
-    "@shrkcrft/importer": "^0.1.0-alpha.26",
-    "@shrkcrft/plugin-api": "^0.1.0-alpha.26",
-    "@shrkcrft/dashboard-api": "^0.1.0-alpha.26",
+    "@shrkcrft/core": "^0.1.0-alpha.28",
+    "@shrkcrft/config": "^0.1.0-alpha.28",
+    "@shrkcrft/workspace": "^0.1.0-alpha.28",
+    "@shrkcrft/knowledge": "^0.1.0-alpha.28",
+    "@shrkcrft/rules": "^0.1.0-alpha.28",
+    "@shrkcrft/paths": "^0.1.0-alpha.28",
+    "@shrkcrft/templates": "^0.1.0-alpha.28",
+    "@shrkcrft/context": "^0.1.0-alpha.28",
+    "@shrkcrft/pipelines": "^0.1.0-alpha.28",
+    "@shrkcrft/packs": "^0.1.0-alpha.28",
+    "@shrkcrft/presets": "^0.1.0-alpha.28",
+    "@shrkcrft/boundaries": "^0.1.0-alpha.28",
+    "@shrkcrft/generator": "^0.1.0-alpha.28",
+    "@shrkcrft/importer": "^0.1.0-alpha.28",
+    "@shrkcrft/plugin-api": "^0.1.0-alpha.28",
+    "@shrkcrft/dashboard-api": "^0.1.0-alpha.28",
     "typescript": "^5.6.0"
   },
   "publishConfig": {