@shrkcrft/inspector 0.1.0-alpha.6 → 0.1.0-alpha.8

package/dist/agent-brief.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-brief.d.ts","sourceRoot":"","sources":["../src/agent-brief.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAS3E,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC3E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,eAAO,MAAM,kBAAkB,8BAA8B,CAAC;AAE9D,oBAAY,SAAS;IACnB,OAAO,YAAY;IACnB,IAAI,SAAS;IACb,MAAM,WAAW;IACjB,cAAc,mBAAmB;IACjC,OAAO,YAAY;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,OAAO,kBAAkB,CAAC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,SAAS,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACxC,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,kEAAkE;IAClE,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,oDAAoD;IACpD,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,8CAA8C;IAC9C,MAAM,EAAE;QACN,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;QACzB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QACrB,MAAM,EAAE,OAAO,CAAC;QAChB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QACxB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;KAC1B,CAAC;IACF,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,sEAAsE;IACtE,kBAAkB,EAAE,MAAM,CAAC;IAC3B,iDAAiD;IACjD,MAAM,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACtC;AAmVD,wBAAsB,eAAe,CACnC,UAAU,EAAE,qBAAqB,EACjC,KAAK,EAAE,gBAAgB,GACtB,OAAO,CAAC,WAAW,CAAC,CAqItB"}
+{"version":3,"file":"agent-brief.d.ts","sourceRoot":"","sources":["../src/agent-brief.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAS3E,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC3E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,eAAO,MAAM,kBAAkB,8BAA8B,CAAC;AAE9D,oBAAY,SAAS;IACnB,OAAO,YAAY;IACnB,IAAI,SAAS;IACb,MAAM,WAAW;IACjB,cAAc,mBAAmB;IACjC,OAAO,YAAY;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,OAAO,kBAAkB,CAAC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,SAAS,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACxC,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,kEAAkE;IAClE,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,oDAAoD;IACpD,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,8CAA8C;IAC9C,MAAM,EAAE;QACN,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;QACzB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QACrB,MAAM,EAAE,OAAO,CAAC;QAChB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QACxB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;KAC1B,CAAC;IACF,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,sEAAsE;IACtE,kBAAkB,EAAE,MAAM,CAAC;IAC3B,iDAAiD;IACjD,MAAM,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACtC;AA+XD,wBAAsB,eAAe,CACnC,UAAU,EAAE,qBAAqB,EACjC,KAAK,EAAE,gBAAgB,GACtB,OAAO,CAAC,WAAW,CAAC,CAyItB"}

package/dist/agent-brief.js

@@ -149,15 +149,23 @@ function pipelineSection(packet) {
 function actionHintsSection(packet) {
     const lines = [];
     const h = packet.actionHints;
+    // h.commands is IActionHintCommand[] (objects with .command + optional
+    // .purpose); h.mcpTools is IActionHintMcpTool[] (.tool + .purpose).
+    // Earlier versions string-interpolated the whole object, producing
+    // `- [object Object]` in the rendered brief.
     if (h.commands.length > 0) {
         lines.push('**Commands:**');
-        for (const c of h.commands.slice(0, 5))
-            lines.push(`- \`${c}\``);
+        for (const c of h.commands.slice(0, 5)) {
+            const purpose = c.purpose ? ` — ${c.purpose}` : '';
+            lines.push(`- \`${c.command}\`${purpose}`);
+        }
     }
     if (h.mcpTools.length > 0) {
         lines.push('**MCP tools:**');
-        for (const m of h.mcpTools.slice(0, 5))
-            lines.push(`- \`${m}\``);
+        for (const m of h.mcpTools.slice(0, 5)) {
+            const purpose = m.purpose ? ` — ${m.purpose}` : '';
+            lines.push(`- \`${m.tool}\`${purpose}`);
+        }
     }
     if (h.verificationCommands.length > 0) {
         lines.push('**Verification:**');
@@ -233,8 +241,14 @@ function boundarySection(impact) {
     }
     return section('boundary', 'Boundary concerns', lines.join('\n'));
 }
+/**
+ * Compute the deduplicated suggested-commands list. The result lands
+ * in `IAgentBrief.suggestedCommands` (JSON contract preserved); a
+ * markdown section is rendered ONLY if the list isn't already
+ * covered by action-hints + verification (which it usually is — the
+ * duplication was a major source of the ~100-line brief bloat).
+ */
 function suggestedCommandsSection(impact, packet) {
-    const lines = [];
     const commands = new Set();
     for (const c of impact?.suggestedTestCommands ?? [])
         commands.add(c);
@@ -242,10 +256,21 @@ function suggestedCommandsSection(impact, packet) {
         commands.add(c);
     for (const c of packet.recommendedCliCommands ?? [])
         commands.add(c);
-    for (const c of [...commands].slice(0, 10))
-        lines.push(`- \`${c}\``);
+    // Already-shown set: verification commands + action-hint commands
+    // that are about to render in the actionHintsSection. Anything in
+    // that set should NOT also appear in "Suggested commands".
+    const alreadyShown = new Set();
+    for (const v of packet.actionHints.verificationCommands ?? [])
+        alreadyShown.add(v);
+    for (const c of packet.actionHints.commands ?? [])
+        alreadyShown.add(c.command);
+    const uniqueNew = [...commands].filter((c) => !alreadyShown.has(c));
+    if (uniqueNew.length === 0) {
+        return { section: null, commands: [...commands] };
+    }
+    const lines = uniqueNew.slice(0, 10).map((c) => `- \`${c}\``);
     return {
-        section: section('suggested-commands', 'Suggested commands', lines.join('\n') || '_None._'),
+        section: section('suggested-commands', 'Suggested commands (not already listed above)', lines.join('\n')),
         commands: [...commands],
     };
 }
@@ -313,12 +338,31 @@ async function qualitySection(inspection, baselineFile) {
     ];
     return section('quality', 'Quality baseline', lines.join('\n'));
 }
+/**
+ * Empty-section detector. A section is "empty" when its body is just
+ * an italicized placeholder like `_None._` / `_No impact analysis
+ * available._` / `_No ownership data._`. Suppressing these compresses
+ * the typical brief from ~100 lines to ~40 — Claude doesn't need to
+ * read "Policy concerns: _None detected._" to make a decision.
+ */
+function isEmptyBody(body) {
+    const trimmed = body.trim();
+    if (!trimmed)
+        return true;
+    // Pure single-line italicized placeholder, e.g. `_None._` / `_No X data._`.
+    return /^_[^_]+_$/.test(trimmed);
+}
 function sectionsToMarkdown(task, mode, sections) {
     const lines = [];
     lines.push(`# SharkCraft brief: ${task || '(no task)'}`);
     lines.push('');
-    lines.push(`_Mode: \`${mode}\` — ${new Date().toISOString()}_`);
+    // Mode only — timestamp adds noise to a "single page Claude reads
+    // first" doc. The IAgentBrief.generatedAt field still carries it
+    // for tooling that needs the timestamp.
+    lines.push(`_Mode: \`${mode}\`_`);
     for (const s of sections) {
+        if (isEmptyBody(s.body))
+            continue;
         lines.push('');
         lines.push(`## ${s.title}`);
         lines.push('');
@@ -398,7 +442,12 @@ export async function buildAgentBrief(inspection, input) {
     }
     // Always include suggested commands + safety.
     const { section: cmdSection, commands } = suggestedCommandsSection(impact, packet);
-    sections.push(cmdSection);
+    // Only push when the section returns one — most briefs no longer
+    // include this section because everything it would list is already
+    // in action-hints / verification. The `commands` array still ships
+    // in IAgentBrief.suggestedCommands for tooling that consumes it.
+    if (cmdSection)
+        sections.push(cmdSection);
     sections.push(safetySection());
     // Apply per-section budgets when requested.
     const trimmedSections = input.sectionBudgets && Object.keys(input.sectionBudgets).length > 0

package/dist/agent-task-prep.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-task-prep.d.ts","sourceRoot":"","sources":["../src/agent-task-prep.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,eAAO,MAAM,sBAAsB,kCAAkC,CAAC;AAEtE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,OAAO,sBAAsB,CAAC;IAC/C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IAC/C,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/C,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/C,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/C,QAAQ,CAAC,gBAAgB,EAAE,SAAS;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACpE,QAAQ,CAAC,mBAAmB,EAAE,SAAS;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACvE,QAAQ,CAAC,YAAY,EAAE,SAAS;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;IAC5F,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,qBAAqB,EACjC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,oBAAoB,CAAC,CAqD/B"}
+{"version":3,"file":"agent-task-prep.d.ts","sourceRoot":"","sources":["../src/agent-task-prep.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,eAAO,MAAM,sBAAsB,kCAAkC,CAAC;AAEtE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,OAAO,sBAAsB,CAAC;IAC/C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IAC/C,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/C,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/C,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/C,QAAQ,CAAC,gBAAgB,EAAE,SAAS;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACpE,QAAQ,CAAC,mBAAmB,EAAE,SAAS;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACvE,QAAQ,CAAC,YAAY,EAAE,SAAS;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;IAC5F,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,qBAAqB,EACjC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,oBAAoB,CAAC,CAoD/B"}

package/dist/agent-task-prep.js

@@ -13,7 +13,6 @@
  * Read-only. Never writes; never executes commands.
  */
 import { buildTaskPacket } from "./task-packet.js";
-import { listPluginLifecycleProfiles } from "./plugin-lifecycle-profile-registry.js";
 import { listConventions } from "./convention-registry.js";
 import { listTaskRoutingHints, explainTaskRouting } from "./task-routing-hint-registry.js";
 import { buildUncertaintySummary } from "./uncertainty.js";
@@ -21,7 +20,6 @@ export const AGENT_TASK_PREP_SCHEMA = 'sharkcraft.agent-task-prep/v1';
 export async function prepareAgentTask(inspection, task) {
     const packet = buildTaskPacket(inspection, task);
     const uncertaintyReport = buildUncertaintySummary(packet);
-    const lifecycle = await listPluginLifecycleProfiles(inspection);
     const conventions = await listConventions(inspection);
     const routing = await explainTaskRouting(inspection, task);
     await listTaskRoutingHints(inspection); // warm cache
@@ -60,7 +58,7 @@ export async function prepareAgentTask(inspection, task) {
         inspectionCommands,
         generationCommands,
         validationCommands,
-        relevantProfiles: lifecycle.slice(0, 5).map((e) => ({ id: e.profile.id, title: e.profile.title })),
+        relevantProfiles: [],
         relevantConventions: conventions.slice(0, 5).map((e) => ({ id: e.convention.id, title: e.convention.title })),
         routingHints: routing.slice(0, 5).map((m) => ({ id: m.hint.id, title: m.hint.title, reasons: m.reasons })),
         safetyNotes: [

package/dist/ai-readiness.d.ts

@@ -1,30 +1,105 @@
 import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+/**
+ * Per-dimension applies-to status.
+ *
+ *   - `core` — dimension applies to this workspace shape; counted in the
+ *     aggregate score.
+ *   - `advisory` — dimension applies but is not load-bearing for the
+ *     shape; shown in output, NOT counted in the aggregate, and does NOT
+ *     produce a recommendation. Lets the user see "you could add this"
+ *     without dragging the score down for a perfectly-shaped repo.
+ *   - `n/a-for-shape` — dimension is irrelevant to this workspace shape
+ *     (e.g. "templates" for a CLI library that doesn't scaffold
+ *     anything). Hidden from default output, NOT counted, NO
+ *     recommendation. Surfaced with `--show-na`.
+ */
+export type DimensionAppliesTo = 'core' | 'advisory' | 'n/a-for-shape';
 export interface IReadinessDimension {
     id: string;
     title: string;
     /** 0–10 score. */
     score: number;
-    /** Weight applied to the score in the final aggregate. */
+    /** Weight applied to the score in the final aggregate (only used when applies === 'core'). */
     weight: number;
     /** Free-form note explaining the score. */
     note: string;
+    /** Does this dimension apply to the detected workspace shape? */
+    applies: DimensionAppliesTo;
+    /** When applies !== 'core', a one-line reason the dimension was skipped. */
+    appliesReason?: string;
 }
 export type ReadinessGrade = 'excellent' | 'good' | 'partial' | 'poor';
+/**
+ * One of four binary verdicts surfaced in the doctor output. Replaces
+ * the older "look at the 0-100 score" UX with a clear yes/no for the
+ * two questions users actually want answered.
+ */
+export interface IReadinessVerdicts {
+    /** Can an AI agent rely on shrk to apply changes safely? */
+    readyForAgentWrites: boolean;
+    /** Can an AI agent use shrk's read-only surface (context / task)? */
+    readyForAgentReads: boolean;
+    /** Concrete things blocking `readyForAgentWrites`. */
+    blockers: readonly string[];
+}
 export interface IReadinessReport {
-    /** 0..100 weighted score. */
+    /** 0..100 weighted score, counting only `core` dimensions. */
     score: number;
     grade: ReadinessGrade;
     dimensions: IReadinessDimension[];
-    /** Up to 5 prioritized actions to improve the score. */
+    /** Up to 5 prioritized actions to improve the score (only from core dims). */
     topRecommendations: string[];
+    /** Honest binary verdicts that don't depend on softcap scoring. */
+    verdicts: IReadinessVerdicts;
+    /** Detected workspace shape — drives which dimensions count as core. */
+    workspaceShape: IWorkspaceShape;
+}
+/**
+ * Coarse classification of the workspace, used to decide which readiness
+ * dimensions are load-bearing. Derived from `WorkspaceProfile[]`.
+ */
+export interface IWorkspaceShape {
+    /** Best-effort one-line description of the shape. */
+    label: string;
+    /** True if the workspace publishes a library (no user-facing scaffolding). */
+    isLibrary: boolean;
+    /** True if the workspace runs a service (HTTP / queue / daemon). */
+    isService: boolean;
+    /** True if the workspace is a monorepo (Nx / Turborepo / pnpm-workspaces). */
+    isMonorepo: boolean;
+    /** True if the workspace owns end-user code (Angular app / Next.js app / Nest service / generic frontend / backend). */
+    isApplication: boolean;
 }
 /**
- * Deterministic 0..100 AI-readiness score. Penalties are explicit:
- *  - Quantity-only "stuff a registry full of entries" is capped via softCap.
- *  - Duplicate-id warnings reduce data-quality dimension.
- *  - Placeholder docs (TODO / TBD / "fill in") reduce docs dimension.
- *  - Critical/high workflow entries missing actionHints reduce safety dim.
- *  - Doctor health stays a hard gate.
+ * Deterministic AI-readiness report.
+ *
+ * Replaces the original "single 0-100 score" UX with a shape-aware
+ * report. Each dimension is classified as:
+ *
+ *   - `core` — counts in the aggregate score; produces a recommendation
+ *     when below threshold.
+ *   - `advisory` — shown but doesn't drag the score down; no
+ *     recommendation. Used for dimensions that are nice-to-have but
+ *     not load-bearing for the detected workspace shape (e.g. docs in
+ *     a CLI library).
+ *   - `n/a-for-shape` — irrelevant to this workspace; hidden by
+ *     default. Lets a CLI library skip "add templates" without
+ *     manually suppressing every release.
+ *
+ * Two binary verdicts ride alongside the score:
+ *   - `readyForAgentWrites` — every gate an autonomous agent would need
+ *     before issuing `shrk apply` (config + cli-only safety + clean
+ *     doctor).
+ *   - `readyForAgentReads` — every gate a read-only agent (e.g. an MCP
+ *     context lookup) would need (knowledge entries loaded + doctor
+ *     clean).
+ *
+ * Numerical penalties stay explicit:
+ *   - Quantity-only "stuff a registry full of entries" is capped via softCap.
+ *   - Duplicate-id warnings reduce data-quality dimension.
+ *   - Placeholder docs (TODO / TBD / "fill in") reduce docs dimension.
+ *   - Critical/high workflow entries missing actionHints reduce safety dim.
+ *   - Doctor health stays a hard gate.
  */
 export declare function buildAiReadinessReport(inspection: ISharkcraftInspection): IReadinessReport;
 //# sourceMappingURL=ai-readiness.d.ts.map

package/dist/ai-readiness.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ai-readiness.d.ts","sourceRoot":"","sources":["../src/ai-readiness.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAIvE,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,kBAAkB;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;IACf,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;AAEvE,MAAM,WAAW,gBAAgB;IAC/B,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,cAAc,CAAC;IACtB,UAAU,EAAE,mBAAmB,EAAE,CAAC;IAClC,wDAAwD;IACxD,kBAAkB,EAAE,MAAM,EAAE,CAAC;CAC9B;AAmCD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,qBAAqB,GAAG,gBAAgB,CAqQ1F"}
+{"version":3,"file":"ai-readiness.d.ts","sourceRoot":"","sources":["../src/ai-readiness.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAIvE;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,UAAU,GAAG,eAAe,CAAC;AAEvE,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,kBAAkB;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,8FAA8F;IAC9F,MAAM,EAAE,MAAM,CAAC;IACf,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,OAAO,EAAE,kBAAkB,CAAC;IAC5B,4EAA4E;IAC5E,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;AAEvE;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,4DAA4D;IAC5D,mBAAmB,EAAE,OAAO,CAAC;IAC7B,qEAAqE;IACrE,kBAAkB,EAAE,OAAO,CAAC;IAC5B,sDAAsD;IACtD,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,gBAAgB;IAC/B,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,cAAc,CAAC;IACtB,UAAU,EAAE,mBAAmB,EAAE,CAAC;IAClC,8EAA8E;IAC9E,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,mEAAmE;IACnE,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,wEAAwE;IACxE,cAAc,EAAE,eAAe,CAAC;CACjC;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,SAAS,EAAE,OAAO,CAAC;IACnB,oEAAoE;IACpE,SAAS,EAAE,OAAO,CAAC;IACnB,8EAA8E;IAC9E,UAAU,EAAE,OAAO,CAAC;IACpB,wHAAwH;IACxH,aAAa,EAAE,OAAO,CAAC;CACxB;AAyED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,qBAAqB,GAAG,gBAAgB,CA2U1F"}

package/dist/ai-readiness.js

@@ -1,4 +1,5 @@
 import { KnowledgeType, hasActionHints } from '@shrkcrft/knowledge';
+import { WorkspaceProfile } from '@shrkcrft/workspace';
 import { diagnoseActionHints } from "./action-hint-diagnostics.js";
 import { runDoctor } from "./sharkcraft-inspector.js";
 function gradeOf(score) {
@@ -37,17 +38,97 @@ function isCriticalOrHighWorkflow(entry) {
     return p === 'critical' || p === 'high';
 }
 /**
- * Deterministic 0..100 AI-readiness score. Penalties are explicit:
- *  - Quantity-only "stuff a registry full of entries" is capped via softCap.
- *  - Duplicate-id warnings reduce data-quality dimension.
- *  - Placeholder docs (TODO / TBD / "fill in") reduce docs dimension.
- *  - Critical/high workflow entries missing actionHints reduce safety dim.
- *  - Doctor health stays a hard gate.
+ * Classify the workspace from its profile flags. Used to mark dimensions
+ * core / advisory / n/a so the aggregate score reflects what actually
+ * matters for this repo.
+ */
+function classifyShape(profiles) {
+    const has = (p) => profiles.includes(p);
+    const isLibrary = has(WorkspaceProfile.IsLibrary);
+    const isService = has(WorkspaceProfile.IsService);
+    const isMonorepo = has(WorkspaceProfile.IsMonorepo) ||
+        has(WorkspaceProfile.HasNx) ||
+        has(WorkspaceProfile.HasTurborepo) ||
+        has(WorkspaceProfile.HasPackageWorkspaces);
+    const isApplication = !isLibrary &&
+        (has(WorkspaceProfile.IsFrontend) ||
+            has(WorkspaceProfile.IsBackend) ||
+            isService);
+    let label;
+    if (isMonorepo) {
+        label = isLibrary ? 'library monorepo' : 'monorepo';
+    }
+    else if (isLibrary) {
+        label = 'library';
+    }
+    else if (isService) {
+        label = 'service';
+    }
+    else if (has(WorkspaceProfile.IsFrontend)) {
+        label = 'frontend app';
+    }
+    else if (has(WorkspaceProfile.IsBackend)) {
+        label = 'backend app';
+    }
+    else if (has(WorkspaceProfile.HasTypeScript)) {
+        label = 'TypeScript project';
+    }
+    else {
+        label = 'unclassified';
+    }
+    return { label, isLibrary, isService, isMonorepo, isApplication };
+}
+/**
+ * Deterministic AI-readiness report.
+ *
+ * Replaces the original "single 0-100 score" UX with a shape-aware
+ * report. Each dimension is classified as:
+ *
+ *   - `core` — counts in the aggregate score; produces a recommendation
+ *     when below threshold.
+ *   - `advisory` — shown but doesn't drag the score down; no
+ *     recommendation. Used for dimensions that are nice-to-have but
+ *     not load-bearing for the detected workspace shape (e.g. docs in
+ *     a CLI library).
+ *   - `n/a-for-shape` — irrelevant to this workspace; hidden by
+ *     default. Lets a CLI library skip "add templates" without
+ *     manually suppressing every release.
+ *
+ * Two binary verdicts ride alongside the score:
+ *   - `readyForAgentWrites` — every gate an autonomous agent would need
+ *     before issuing `shrk apply` (config + cli-only safety + clean
+ *     doctor).
+ *   - `readyForAgentReads` — every gate a read-only agent (e.g. an MCP
+ *     context lookup) would need (knowledge entries loaded + doctor
+ *     clean).
+ *
+ * Numerical penalties stay explicit:
+ *   - Quantity-only "stuff a registry full of entries" is capped via softCap.
+ *   - Duplicate-id warnings reduce data-quality dimension.
+ *   - Placeholder docs (TODO / TBD / "fill in") reduce docs dimension.
+ *   - Critical/high workflow entries missing actionHints reduce safety dim.
+ *   - Doctor health stays a hard gate.
  */
 export function buildAiReadinessReport(inspection) {
     const dims = [];
     const recs = [];
-    // 1) Config present
+    const shape = classifyShape(inspection.workspace.profiles);
+    // Reusable applies-to predicates.
+    const templatesApply = shape.isLibrary && !shape.isMonorepo
+        ? 'n/a-for-shape'
+        : shape.isApplication
+            ? 'core'
+            : 'advisory';
+    const pipelinesApply = shape.isLibrary && !shape.isMonorepo
+        ? 'n/a-for-shape'
+        : 'advisory';
+    const pathsApply = shape.isMonorepo || shape.isApplication
+        ? 'core'
+        : 'advisory';
+    const docsApply = shape.isApplication || shape.isMonorepo
+        ? 'core'
+        : 'advisory';
+    // 1) Config present — always core (this is the "did you opt in?" signal).
     dims.push({
         id: 'config',
         title: 'sharkcraft.config.ts present',
@@ -56,6 +137,7 @@ export function buildAiReadinessReport(inspection) {
         note: inspection.configFile
             ? `loaded from ${inspection.configFile}`
             : 'missing — using defaults',
+        applies: 'core',
     });
     if (!inspection.configFile) {
         recs.push('Create sharkcraft/sharkcraft.config.ts to opt in to project-specific config.');
@@ -68,6 +150,7 @@ export function buildAiReadinessReport(inspection) {
         weight: 1.0,
         score: softCapScore(k, 15),
         note: `${k} entries (softcap 15, full at 22)`,
+        applies: 'core',
     });
     if (k < 10)
         recs.push('Add more structured knowledge entries (target: 10+).');
@@ -79,10 +162,11 @@ export function buildAiReadinessReport(inspection) {
         weight: 1.0,
         score: softCapScore(rules.length, 8),
         note: `${rules.length} rules (softcap 8)`,
+        applies: 'core',
     });
     if (rules.length < 5)
         recs.push('Add at least 5 rules describing coding/architecture conventions.');
-    // 4) Path conventions — softcap at 6.
+    // 4) Path conventions — core for monorepos / applications, advisory otherwise.
     const paths = inspection.pathService.list();
     dims.push({
         id: 'paths',
@@ -90,10 +174,16 @@ export function buildAiReadinessReport(inspection) {
         weight: 0.8,
         score: softCapScore(paths.length, 6),
         note: `${paths.length} path conventions (softcap 6)`,
+        applies: pathsApply,
+        appliesReason: pathsApply === 'advisory'
+            ? 'Path conventions matter most for monorepos and applications with explicit src/ layouts.'
+            : undefined,
     });
-    if (paths.length < 4)
+    if (pathsApply === 'core' && paths.length < 4) {
         recs.push('Add path conventions for src/, services/, utils/, tests/ etc.');
-    // 5) Templates — softcap at 4.
+    }
+    // 5) Templates — n/a for pure libraries; core for applications;
+    //    advisory for monorepos (often useful but not load-bearing).
     const t = inspection.templates.length;
     dims.push({
         id: 'templates',
@@ -101,10 +191,18 @@ export function buildAiReadinessReport(inspection) {
         weight: 0.8,
         score: softCapScore(t, 4),
         note: `${t} templates (softcap 4)`,
+        applies: templatesApply,
+        appliesReason: templatesApply === 'n/a-for-shape'
+            ? 'Libraries don\'t scaffold downstream code — templates are not load-bearing here.'
+            : templatesApply === 'advisory'
+                ? 'Templates help generate consistent constructs, but the repo can be agent-ready without them.'
+                : undefined,
     });
-    if (t < 3)
+    if (templatesApply === 'core' && t < 3) {
         recs.push('Define templates for the constructs you generate most often.');
-    // 6) Pipelines — softcap at 3.
+    }
+    // 6) Pipelines — n/a for pure libraries; advisory for everything else.
+    //    Pipelines are nice but rarely block agent workflows.
     const p = inspection.pipelines.length;
     dims.push({
         id: 'pipelines',
@@ -112,9 +210,13 @@ export function buildAiReadinessReport(inspection) {
         weight: 0.8,
         score: softCapScore(p, 3),
         note: `${p} pipelines (softcap 3)`,
+        applies: pipelinesApply,
+        appliesReason: pipelinesApply === 'n/a-for-shape'
+            ? 'Libraries don\'t orchestrate feature pipelines — this dimension does not apply.'
+            : 'Pipelines describe preferred flows; a repo can be agent-ready with just rules + path conventions.',
     });
-    if (p < 2)
-        recs.push('Add at least one feature-dev or safe-generation pipeline.');
+    // No recommendation when pipelines is advisory — the old "add a pipeline"
+    // exhortation fired on libraries it shouldn't have.
     // 7) Action-hint coverage — fraction of entries that carry hints.
     const withHints = inspection.knowledgeEntries.filter((e) => hasActionHints(e)).length;
     const hintsScore = k === 0 ? 0 : Math.min(10, Math.round((withHints / Math.max(k, 1)) * 20));
@@ -124,6 +226,7 @@ export function buildAiReadinessReport(inspection) {
         weight: 1.2,
         score: hintsScore,
         note: `${withHints} of ${k} entries carry actionHints`,
+        applies: 'core',
     });
     if (hintsScore < 7)
         recs.push('Add actionHints to high-priority rules (commands, mcpTools, forbiddenActions).');
@@ -135,6 +238,7 @@ export function buildAiReadinessReport(inspection) {
         weight: 0.6,
         score: haveVerify ? 10 : 0,
         note: haveVerify ? 'at least one entry lists verification commands' : 'no entry lists verification commands',
+        applies: 'core',
     });
     if (!haveVerify)
         recs.push('Add verificationCommands to safety/generation rules (e.g. typecheck + tests).');
@@ -146,10 +250,11 @@ export function buildAiReadinessReport(inspection) {
         weight: 0.6,
         score: haveForbidden ? 10 : 0,
         note: haveForbidden ? 'at least one entry lists forbiddenActions' : 'no entry lists forbiddenActions',
+        applies: 'core',
     });
     if (!haveForbidden)
         recs.push('Add forbiddenActions to clarify what agents must NOT do.');
-    // 10) Docs — softcap at 4. Penalize placeholder docs.
+    // 10) Docs — softcap at 4. Penalize placeholder docs. Advisory for libraries.
     const docFiles = inspection.sourceFiles.filter((s) => s.endsWith('.md'));
     let placeholderDocCount = 0;
     for (const entry of inspection.knowledgeEntries) {
@@ -169,19 +274,17 @@ export function buildAiReadinessReport(inspection) {
         note: placeholderDocCount > 0
             ? `${docFiles.length} markdown files (-${docsPenalty} for ${placeholderDocCount} placeholder markers)`
             : `${docFiles.length} markdown files`,
+        applies: docsApply,
+        appliesReason: docsApply === 'advisory'
+            ? 'Standalone libraries communicate via README + API docs more than per-task markdown.'
+            : undefined,
     });
     if (placeholderDocCount > 0) {
         recs.push(`Replace TODO/placeholder markers in ${placeholderDocCount} doc/task file(s).`);
     }
     // 11) Doctor health — passes is a near-required gate.
-    //
-    // Action-hint quality warnings are also surfaced by the doctor, but the
-    // dedicated `hint-quality` dimension below already scores them. Counting
-    // them here too would punish the same warning twice and crush the score
-    // once a repo crosses ten hint warnings. Exclude them from this dimension.
     const doctor = runDoctor(inspection);
-    const structuralWarnings = doctor.checks.filter((c) => c.severity === 'warning' &&
-        !c.id.startsWith('actionhints-')).length;
+    const structuralWarnings = doctor.checks.filter((c) => c.severity === 'warning' && !c.id.startsWith('actionhints-')).length;
     const doctorScore = doctor.passed ? Math.max(0, 10 - structuralWarnings) : 0;
     dims.push({
         id: 'doctor',
@@ -191,13 +294,16 @@ export function buildAiReadinessReport(inspection) {
         note: doctor.passed
             ? `passed (${structuralWarnings} structural warnings, ${doctor.summary.warnings} total)`
             : `${doctor.summary.errors} errors`,
+        applies: 'core',
     });
     if (!doctor.passed)
         recs.push('Fix doctor errors before relying on agent workflows.');
-    // 12) Pack discovery health
+    // 12) Pack discovery health — n/a when no packs are installed (don't
+    //     reward inaction with a neutral 5).
     const packs = inspection.packs;
+    const packsApply = packs.discoveredPacks.length === 0 ? 'n/a-for-shape' : 'core';
     const packsScore = packs.discoveredPacks.length === 0
-        ? 5 // neutral when no packs are installed
+        ? 0 // would-be neutral 5 was masking how often this dim doesn't apply
         : packs.invalidPacks.length === 0
             ? 10
             : 4;
@@ -209,14 +315,17 @@ export function buildAiReadinessReport(inspection) {
         note: packs.discoveredPacks.length === 0
             ? 'no packs discovered'
             : `${packs.validPacks.length}/${packs.discoveredPacks.length} packs valid`,
+        applies: packsApply,
+        appliesReason: packsApply === 'n/a-for-shape'
+            ? 'No SharkCraft packs installed — pack-discovery health does not apply.'
+            : undefined,
     });
-    if (packs.invalidPacks.length > 0) {
+    if (packsApply === 'core' && packs.invalidPacks.length > 0) {
         recs.push('Fix invalid pack manifests (see `shrk packs doctor`).');
     }
     // 13) Generation safety — flagship cli-only write policy rule required.
     const hasDryRunDefault = inspection.knowledgeEntries.some((e) => e.actionHints?.writePolicy === 'cli-only' ||
         (e.actionHints?.forbiddenActions ?? []).some((f) => /write through mcp/i.test(f)));
-    // Additionally penalize when any critical/high workflow entry lacks hints.
     const workflowMissingHints = inspection.knowledgeEntries.filter((e) => isCriticalOrHighWorkflow(e) && !hasActionHints(e)).length;
     let safetyScore = hasDryRunDefault ? 10 : 3;
     if (workflowMissingHints > 0) {
@@ -232,6 +341,7 @@ export function buildAiReadinessReport(inspection) {
                 ? `cli-only write policy present, but ${workflowMissingHints} critical/high workflow entry/entries lack actionHints`
                 : 'cli-only write policy + forbidden-actions present'
             : 'no entry declares cli-only write policy',
+        applies: 'core',
     });
     if (!hasDryRunDefault) {
         recs.push('Add a critical safety rule with writePolicy:"cli-only" and "do not write through MCP".');
@@ -251,6 +361,7 @@ export function buildAiReadinessReport(inspection) {
         weight: 0.6,
         score: hintIssueScore,
         note: `${hintReport.issues.length} quality warnings across ${hintReport.evaluatedEntryCount} relevant entries`,
+        applies: 'core',
     });
     // 15) Data quality — duplicate ids surface as warnings.
     const dupCount = inspection.validationIssues.filter((v) => v.code === 'duplicate-id').length;
@@ -263,17 +374,37 @@ export function buildAiReadinessReport(inspection) {
         note: dupCount === 0
             ? 'no duplicate knowledge ids'
             : `${dupCount} duplicate id(s) — first occurrence kept`,
+        applies: 'core',
     });
     if (dupCount > 0)
         recs.push(`Resolve ${dupCount} duplicate knowledge id(s).`);
-    // Aggregate.
-    const totalWeight = dims.reduce((sum, d) => sum + d.weight, 0);
-    const weightedSum = dims.reduce((sum, d) => sum + d.score * d.weight, 0);
-    const score = Math.round((weightedSum / totalWeight) * 10);
+    // Aggregate over `core` dimensions only — advisory + n/a do not count.
+    const coreDims = dims.filter((d) => d.applies === 'core');
+    const totalWeight = coreDims.reduce((sum, d) => sum + d.weight, 0);
+    const weightedSum = coreDims.reduce((sum, d) => sum + d.score * d.weight, 0);
+    const score = totalWeight > 0 ? Math.round((weightedSum / totalWeight) * 10) : 0;
+    // Binary verdicts — honest yes/no rather than a fuzzy score.
+    const blockers = [];
+    if (!doctor.passed)
+        blockers.push('doctor reports errors');
+    if (!inspection.configFile)
+        blockers.push('sharkcraft.config.ts missing');
+    if (!hasDryRunDefault)
+        blockers.push('no cli-only write policy rule');
+    if (k === 0)
+        blockers.push('no knowledge entries loaded');
+    const readyForAgentWrites = blockers.length === 0;
+    const readyForAgentReads = doctor.passed && k > 0;
     return {
         score,
         grade: gradeOf(score),
         dimensions: dims,
         topRecommendations: recs.slice(0, 5),
+        verdicts: {
+            readyForAgentWrites,
+            readyForAgentReads,
+            blockers,
+        },
+        workspaceShape: shape,
     };
 }

package/dist/apply-dispatch-trace.d.ts

@@ -15,12 +15,11 @@ export declare const APPLY_DISPATCH_TRACE_SCHEMA = "sharkcraft.apply-dispatch-tr
 export declare enum DispatchKind {
     Template = "template",
     Helper = "helper",
-    PluginLifecycle = "plugin-lifecycle",
     RegistrationHint = "registration-hint",
     Synthetic = "synthetic",
     Unknown = "unknown"
 }
-export type DispatchSource = 'registry/template' | 'registry/helper' | 'registry/plugin-lifecycle-profile' | 'registry/registration-hint' | 'synthetic' | 'unknown';
+export type DispatchSource = 'registry/template' | 'registry/helper' | 'registry/registration-hint' | 'synthetic' | 'unknown';
 export interface IDispatchFileOpCounts {
     readonly create: number;
     readonly update: number;