@shrkcrft/inspector 0.1.0-alpha.2

package/dist/safety-audit.js

@@ -0,0 +1,138 @@
+/**
+ * Build a deterministic safety audit report from an inspection + the CLI
+ * command catalog + the MCP tool list. Pure — no IO. The catalog/tool
+ * inputs are passed in to avoid creating a CLI → MCP-server import
+ * dependency.
+ */
+export function buildSafetyAudit(input) {
+    const writesSource = [];
+    const writesDrafts = [];
+    const writesSession = [];
+    const runsShell = [];
+    const requiresReview = [];
+    const readOnly = [];
+    for (const e of input.catalog) {
+        const summary = {
+            command: e.command,
+            description: e.description,
+            category: e.category,
+            safetyLevel: e.safetyLevel,
+        };
+        switch (e.safetyLevel) {
+            case 'writes-source':
+                writesSource.push(summary);
+                break;
+            case 'writes-drafts':
+                writesDrafts.push(summary);
+                break;
+            case 'writes-session':
+                writesSession.push(summary);
+                break;
+            case 'runs-shell':
+                runsShell.push(summary);
+                break;
+            case 'read-only':
+                readOnly.push(summary);
+                break;
+            default:
+                break;
+        }
+        if (e.requiresReview)
+            requiresReview.push(summary);
+    }
+    const mcpTools = input.mcpTools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        canWrite: false,
+    }));
+    const anyWritable = mcpTools.some((t) => t.canWrite);
+    // Verifications: split into trusted local + pack-contributed + untrusted.
+    const trusted = [];
+    const pack = [];
+    const untrusted = [];
+    const configCmds = input.inspection.config?.verificationCommands ?? [];
+    for (const v of configCmds) {
+        const item = {
+            id: v.id,
+            command: v.command,
+            trusted: v.trusted === true,
+            source: 'local',
+        };
+        if (item.trusted)
+            trusted.push(item);
+        else
+            untrusted.push(item);
+    }
+    for (const p of input.inspection.packs.validPacks) {
+        const packCmds = p.manifest?.contributions
+            ?.verificationCommands;
+        if (!Array.isArray(packCmds))
+            continue;
+        for (const v of packCmds) {
+            pack.push({
+                id: v.id,
+                command: v.command,
+                trusted: false,
+                source: 'pack',
+                packPackageName: p.packageName,
+            });
+        }
+    }
+    // Pack signature breakdown.
+    let signedAndVerified = 0;
+    let signedNotVerified = 0;
+    let unsigned = 0;
+    let invalid = 0;
+    const items = [];
+    for (const p of input.inspection.packs.discoveredPacks) {
+        const sig = p.signatureStatus ?? 'unsigned';
+        items.push({
+            packageName: p.packageName,
+            packageVersion: p.packageVersion,
+            valid: p.valid,
+            signatureStatus: sig,
+        });
+        if (!p.valid)
+            invalid += 1;
+        else if (sig === 'verified')
+            signedAndVerified += 1;
+        else if (sig === 'not-checked')
+            signedNotVerified += 1;
+        else if (sig === 'invalid-signature')
+            invalid += 1;
+        else
+            unsigned += 1;
+    }
+    const planSecretEnv = input.planSecretEnv ?? 'SHARKCRAFT_PLAN_SECRET';
+    const planSecretConfigured = input.planSecretConfigured ?? (typeof process !== 'undefined' && process.env[planSecretEnv] !== undefined);
+    const recommendations = [];
+    if (anyWritable) {
+        recommendations.push('CRITICAL: at least one MCP tool reports canWrite=true. MCP must remain read-only.');
+    }
+    if (signedNotVerified > 0) {
+        recommendations.push(`${signedNotVerified} pack(s) are signed but not verified. Run \`shrk packs verify\` with the appropriate secret.`);
+    }
+    if (unsigned > 0) {
+        recommendations.push(`${unsigned} pack(s) are unsigned. Sign packs with \`shrk pack sign\` before adopting in production.`);
+    }
+    if (untrusted.length > 0) {
+        recommendations.push(`${untrusted.length} local verification command(s) are not marked trusted. Review before relying on them in \`shrk apply --validate\`.`);
+    }
+    if (pack.length > 0) {
+        recommendations.push(`${pack.length} pack-contributed verification command(s) are NOT auto-runnable — they require explicit \`--allow-pack-commands\`.`);
+    }
+    if (!planSecretConfigured) {
+        recommendations.push(`Plan signing secret \`${planSecretEnv}\` is not set in the current environment — \`shrk apply --verify-signature\` will treat plans as unsigned unless --require-signature is used.`);
+    }
+    if (writesSource.length > 0) {
+        recommendations.push(`${writesSource.length} CLI command(s) write source. Treat them as the explicit human-approval step.`);
+    }
+    return {
+        commands: { writesSource, writesDrafts, writesSession, runsShell, requiresReview, readOnly },
+        mcp: { tools: mcpTools, anyWritable },
+        verifications: { trusted, pack, untrusted },
+        packs: { discovered: items.length, signedAndVerified, signedNotVerified, unsigned, invalid, items },
+        planSigning: { secretConfigured: planSecretConfigured, secretEnv: planSecretEnv },
+        recommendations,
+    };
+}

package/dist/safety-html.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Self-contained HTML rendering for the safety audit. No external assets,
+ * no JS, dark-mode aware.
+ */
+import type { ISafetyAuditReport } from './safety-audit.js';
+export declare function renderSafetyHtml(report: ISafetyAuditReport): string;
+//# sourceMappingURL=safety-html.d.ts.map

package/dist/safety-html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safety-html.d.ts","sourceRoot":"","sources":["../src/safety-html.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAqC5D,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAsDnE"}

package/dist/safety-html.js

@@ -0,0 +1,70 @@
+const CSS = `
+*{box-sizing:border-box}body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;margin:0;background:#0f1419;color:#e6e1cf;padding:2rem;line-height:1.55}
+h1,h2,h3{margin-top:1.4rem;color:#bae67e}
+table{border-collapse:collapse;width:100%;margin:.8rem 0}
+th,td{text-align:left;padding:.4rem .6rem;border-bottom:1px solid #2a3138}
+th{background:#1c2329;color:#9aa5b0}
+.badge{display:inline-block;padding:.1rem .5rem;border-radius:.25rem;font-size:.75rem;font-weight:600;text-transform:uppercase}
+.b-ok{background:#28432e;color:#bae67e}.b-warn{background:#3a3a2e;color:#ffd580}.b-bad{background:#5a1f1f;color:#ff9f9f}
+pre{background:#1c2329;padding:.8rem;border-radius:.4rem;overflow-x:auto}
+code{background:#1c2329;padding:.05rem .3rem;border-radius:.2rem}
+.note{padding:.6rem .8rem;background:#1c2329;border-left:3px solid #bae67e;border-radius:.2rem;margin:.6rem 0}
+@media (prefers-color-scheme: light){body{background:#fafaf7;color:#1f2329}h1,h2,h3{color:#266a2e}th{background:#eee;color:#222}pre,code{background:#eee}.note{background:#eee;border-left-color:#266a2e}}
+`;
+function escapeHtml(s) {
+    return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+}
+function commandTable(title, items) {
+    if (items.length === 0)
+        return '';
+    const out = [];
+    out.push(`<h3>${escapeHtml(title)} (${items.length})</h3>`);
+    out.push('<table><thead><tr><th>Command</th><th>Category</th><th>Safety</th><th>Description</th></tr></thead><tbody>');
+    for (const c of items) {
+        out.push(`<tr><td><code>${escapeHtml(c.command)}</code></td>` +
+            `<td>${escapeHtml(c.category)}</td>` +
+            `<td><code>${escapeHtml(c.safetyLevel)}</code></td>` +
+            `<td>${escapeHtml(c.description)}</td></tr>`);
+    }
+    out.push('</tbody></table>');
+    return out.join('\n');
+}
+export function renderSafetyHtml(report) {
+    const out = [];
+    out.push('<!doctype html>');
+    out.push('<html lang="en"><head><meta charset="utf-8"><title>SharkCraft safety audit</title>');
+    out.push(`<style>${CSS}</style></head><body>`);
+    out.push('<h1>SharkCraft safety audit</h1>');
+    out.push(`<p class="note"><strong>MCP read-only invariant:</strong> <span class="badge ${report.mcp.anyWritable ? 'b-bad' : 'b-ok'}">${report.mcp.anyWritable ? 'violated' : 'enforced'}</span></p>`);
+    out.push('<h2>MCP tools</h2>');
+    out.push('<table><thead><tr><th>Tool</th><th>canWrite</th><th>Description</th></tr></thead><tbody>');
+    for (const t of report.mcp.tools) {
+        out.push(`<tr><td><code>${escapeHtml(t.name)}</code></td>` +
+            `<td><span class="badge ${t.canWrite ? 'b-bad' : 'b-ok'}">${t.canWrite ? 'true' : 'false'}</span></td>` +
+            `<td>${escapeHtml(t.description)}</td></tr>`);
+    }
+    out.push('</tbody></table>');
+    out.push('<h2>Commands by safety level</h2>');
+    out.push(commandTable('writes-source', report.commands.writesSource));
+    out.push(commandTable('writes-drafts', report.commands.writesDrafts));
+    out.push(commandTable('writes-session', report.commands.writesSession));
+    out.push(commandTable('runs-shell', report.commands.runsShell));
+    out.push(commandTable('requires-review', report.commands.requiresReview));
+    out.push(commandTable('read-only', report.commands.readOnly));
+    out.push('<h2>Verifications</h2>');
+    out.push(`<p>Trusted local: <strong>${report.verifications.trusted.length}</strong> · Pack-contributed: <strong>${report.verifications.pack.length}</strong> · Untrusted local: <strong>${report.verifications.untrusted.length}</strong></p>`);
+    out.push('<h2>Packs</h2>');
+    out.push(`<p>Discovered: <strong>${report.packs.discovered}</strong>; verified <strong>${report.packs.signedAndVerified}</strong>; signed-not-verified <strong>${report.packs.signedNotVerified}</strong>; unsigned <strong>${report.packs.unsigned}</strong>; invalid <strong>${report.packs.invalid}</strong></p>`);
+    out.push('<h2>Plan signing</h2>');
+    out.push(`<p>Secret env: <code>${escapeHtml(report.planSigning.secretEnv)}</code> — ${report.planSigning.secretConfigured
+        ? '<span class="badge b-ok">configured</span>'
+        : '<span class="badge b-warn">missing</span>'}</p>`);
+    if (report.recommendations.length > 0) {
+        out.push('<h2>Recommendations</h2><ul>');
+        for (const r of report.recommendations)
+            out.push(`<li>${escapeHtml(r)}</li>`);
+        out.push('</ul>');
+    }
+    out.push('</body></html>');
+    return out.join('\n') + '\n';
+}

package/dist/scaffold-coverage.d.ts

@@ -0,0 +1,46 @@
+import { type IUncertaintyReport } from './uncertainty-report.js';
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export declare const SCAFFOLD_COVERAGE_SCHEMA = "sharkcraft.scaffold-coverage/v1";
+export declare enum CoverageGrade {
+    Full = "full",
+    Partial = "partial",
+    Weak = "weak",
+    Missing = "missing"
+}
+export interface IAxisMatch {
+    axis: string;
+    matched: boolean;
+    matchCount: number;
+    topIds: readonly string[];
+    /** Optional per-axis notes (warnings or hints). */
+    notes?: readonly string[];
+}
+export interface IScaffoldCoverageReport {
+    schema: typeof SCAFFOLD_COVERAGE_SCHEMA;
+    generatedAt: string;
+    task?: string;
+    domain?: string;
+    /** Per-axis matches. */
+    axes: readonly IAxisMatch[];
+    /** Overall confidence 0–1. */
+    confidence: number;
+    /** Grade derived from axis matches. */
+    grade: CoverageGrade;
+    /** Missing axes that have the largest impact. */
+    missing: readonly string[];
+    /** Suggested additions — concrete pack/local entries the author could add. */
+    suggestedAdditions: readonly string[];
+    /** Concrete next commands. */
+    nextCommands: readonly string[];
+    /** Uncertainty report (confidence + signals + safe fallback). */
+    uncertainty?: IUncertaintyReport;
+}
+export interface IScaffoldCoverageOptions {
+    task?: string;
+    domain?: string;
+    /** Top-N ranked items to consider per axis. Default 8. */
+    topN?: number;
+}
+export declare function buildScaffoldCoverageReport(inspection: ISharkcraftInspection, options?: IScaffoldCoverageOptions): Promise<IScaffoldCoverageReport>;
+export declare function renderScaffoldCoverageMarkdown(report: IScaffoldCoverageReport): string;
+//# sourceMappingURL=scaffold-coverage.d.ts.map

package/dist/scaffold-coverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold-coverage.d.ts","sourceRoot":"","sources":["../src/scaffold-coverage.ts"],"names":[],"mappings":"AAmBA,OAAO,EAA0B,KAAK,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC1F,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,eAAO,MAAM,wBAAwB,oCAAoC,CAAC;AAE1E,oBAAY,aAAa;IACvB,IAAI,SAAS;IACb,OAAO,YAAY;IACnB,IAAI,SAAS;IACb,OAAO,YAAY;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,mDAAmD;IACnD,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,OAAO,wBAAwB,CAAC;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wBAAwB;IACxB,IAAI,EAAE,SAAS,UAAU,EAAE,CAAC;IAC5B,8BAA8B;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,KAAK,EAAE,aAAa,CAAC;IACrB,iDAAiD;IACjD,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,8EAA8E;IAC9E,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,8BAA8B;IAC9B,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,iEAAiE;IACjE,WAAW,CAAC,EAAE,kBAAkB,CAAC;CAClC;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAmGD,wBAAsB,2BAA2B,CAC/C,UAAU,EAAE,qBAAqB,EACjC,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,uBAAuB,CAAC,CAqHlC;AAsCD,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,uBAAuB,GAAG,MAAM,CA+BtF"}

package/dist/scaffold-coverage.js

@@ -0,0 +1,273 @@
+/**
+ * Scaffold / template / playbook coverage gaps.
+ *
+ * For a task or domain, surface what the engine already has wired up and
+ * what is missing — knowledge, rules, path conventions, templates, scaffold
+ * patterns, playbooks, helpers, validation commands, contract templates —
+ * with a coverage grade and concrete additions to consider.
+ *
+ * Pure, deterministic, read-only. Schema: sharkcraft.scaffold-coverage/v1.
+ */
+import { listAllContractTemplates } from "./contract-template-registry.js";
+import { listConstructs } from "./construct-registry.js";
+import { HELPERS } from "./helper-registry.js";
+import { listPlaybooks } from "./playbook-registry.js";
+import { loadScaffoldPatternsFromInspection, } from "./scaffold-patterns.js";
+import { rankAll } from "./task-ranker.js";
+import { buildUncertaintyReport } from "./uncertainty-report.js";
+export const SCAFFOLD_COVERAGE_SCHEMA = 'sharkcraft.scaffold-coverage/v1';
+export var CoverageGrade;
+(function (CoverageGrade) {
+    CoverageGrade["Full"] = "full";
+    CoverageGrade["Partial"] = "partial";
+    CoverageGrade["Weak"] = "weak";
+    CoverageGrade["Missing"] = "missing";
+})(CoverageGrade || (CoverageGrade = {}));
+function lower(s) {
+    return (s ?? '').toLowerCase();
+}
+function makeAxis(axis, ranked, threshold = 1) {
+    const filtered = ranked.filter((r) => r.score >= threshold);
+    return {
+        axis,
+        matched: filtered.length > 0,
+        matchCount: filtered.length,
+        topIds: filtered.slice(0, 5).map((r) => r.id),
+    };
+}
+function scoreAxis(items, taskLower, domain) {
+    const tokens = taskLower.split(/[^a-z0-9]+/).filter((t) => t.length >= 3);
+    const out = [];
+    for (const item of items) {
+        let score = 0;
+        const idLower = item.id.toLowerCase();
+        for (const t of tokens)
+            if (idLower.includes(t))
+                score += 2;
+        if (domain && idLower.includes(domain.toLowerCase()))
+            score += 3;
+        if (item.tags) {
+            for (const tag of item.tags) {
+                if (tokens.includes(tag.toLowerCase()))
+                    score += 2;
+                if (domain && tag.toLowerCase() === domain.toLowerCase())
+                    score += 3;
+            }
+        }
+        if (score > 0)
+            out.push({ id: item.id, score });
+    }
+    out.sort((a, b) => b.score - a.score);
+    return out;
+}
+function gradeFromCounts(matchedCount, totalAxes) {
+    const ratio = totalAxes === 0 ? 0 : matchedCount / totalAxes;
+    if (ratio >= 0.85)
+        return CoverageGrade.Full;
+    if (ratio >= 0.55)
+        return CoverageGrade.Partial;
+    if (ratio >= 0.25)
+        return CoverageGrade.Weak;
+    return CoverageGrade.Missing;
+}
+function suggestAdditions(missing, taskOrDomain) {
+    const out = [];
+    const tokens = taskOrDomain.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+    const hint = tokens.slice(0, 3).join('-') || 'this-task';
+    for (const axis of missing) {
+        switch (axis) {
+            case 'templates':
+                out.push(`Add a template (e.g. \`<scope>.${hint}\`) under sharkcraft/ or the relevant pack.`);
+                break;
+            case 'scaffold-patterns':
+                out.push(`Add a scaffold pattern matching the relevant paths for \`${hint}\`.`);
+                break;
+            case 'playbooks':
+                out.push(`Add a playbook documenting the canonical sequence for \`${hint}\`.`);
+                break;
+            case 'helpers':
+                out.push(`Add a helper plan generator if this task involves repeatable plan-only steps.`);
+                break;
+            case 'path-conventions':
+                out.push(`Add a path convention for \`${hint}\` so templates can target a canonical path.`);
+                break;
+            case 'knowledge':
+                out.push(`Add a knowledge entry explaining \`${hint}\` (verifiable references).`);
+                break;
+            case 'rules':
+                out.push(`Add a rule with actionHints and verificationCommands for \`${hint}\`.`);
+                break;
+            case 'validation-commands':
+                out.push(`Declare verificationCommands on the related rules / templates / playbooks.`);
+                break;
+            case 'contract-templates':
+                out.push(`Add an agent-contract template for the \`${hint}\` workflow.`);
+                break;
+        }
+    }
+    return out;
+}
+function buildNextCommands(taskOrDomain) {
+    return [
+        `shrk why-not <id> --for-task "${taskOrDomain}"`,
+        `shrk search "${taskOrDomain}" --explain`,
+        `shrk task "${taskOrDomain}" --show-coverage-gaps`,
+        `shrk fix preview --template-drift`,
+    ];
+}
+export async function buildScaffoldCoverageReport(inspection, options = {}) {
+    const task = options.task ?? '';
+    const domain = options.domain;
+    const taskOrDomain = task || domain || '';
+    if (!taskOrDomain) {
+        return emptyReport();
+    }
+    const taskLower = taskOrDomain.toLowerCase();
+    // Ranker output (rules / paths / templates / pipelines).
+    const ranking = rankAll(inspection, taskOrDomain, options.topN ?? 8);
+    const constructs = listConstructs(inspection);
+    const playbooks = listPlaybooks(inspection);
+    const helpers = HELPERS;
+    const contractTemplates = await listAllContractTemplates(inspection);
+    const scaffoldsLoad = await loadScaffoldPatternsFromInspection(inspection);
+    const scaffolds = scaffoldsLoad.patterns;
+    const knowledgeMatches = scoreAxis(inspection.knowledgeEntries.map((k) => ({
+        id: k.id,
+        ...(k.tags ? { tags: k.tags } : {}),
+    })), taskLower, domain);
+    const helperMatches = scoreAxis(helpers.map((h) => ({ id: h.id, tags: [h.description] })), taskLower, domain);
+    const playbookMatches = scoreAxis(playbooks.map((p) => ({ id: p.id, tags: p.tags ?? [] })), taskLower, domain);
+    const scaffoldMatches = scoreAxis(scaffolds.map((s) => ({ id: s.pattern.id })), taskLower, domain);
+    const contractMatches = scoreAxis(contractTemplates.map((c) => ({
+        id: c.id,
+        tags: c.tags ?? [],
+    })), taskLower, domain);
+    const validationCmds = collectVerificationCommands(inspection);
+    const axes = [
+        makeAxis('knowledge', knowledgeMatches),
+        makeAxis('rules', ranking.rules.map((r) => ({ id: r.item.id, score: r.score }))),
+        makeAxis('path-conventions', ranking.paths.map((r) => ({ id: r.item.id, score: r.score }))),
+        makeAxis('templates', ranking.templates.map((r) => ({ id: r.item.id, score: r.score }))),
+        makeAxis('scaffold-patterns', scaffoldMatches),
+        makeAxis('playbooks', playbookMatches),
+        makeAxis('helpers', helperMatches),
+        makeAxis('validation-commands', validationCmds.map((v, i) => ({ id: `verification[${i}]:${v}`, score: tokenScore(v, taskLower) })).filter((x) => x.score > 0)),
+        makeAxis('contract-templates', contractMatches),
+    ];
+    // Also report which constructs match.
+    if (constructs.length > 0) {
+        const constructMatches = scoreAxis(constructs.map((c) => ({ id: c.id, tags: c.tags ?? [] })), taskLower, domain);
+        axes.push(makeAxis('constructs', constructMatches));
+    }
+    const matchedAxes = axes.filter((a) => a.matched).length;
+    const grade = gradeFromCounts(matchedAxes, axes.length);
+    const missing = axes.filter((a) => !a.matched).map((a) => a.axis);
+    const confidence = Math.min(1, Math.max(0, matchedAxes / axes.length));
+    let coverageConfidence = 'high';
+    if (confidence < 0.5)
+        coverageConfidence = 'low';
+    else if (confidence < 0.8)
+        coverageConfidence = 'medium';
+    const reasons = [];
+    const missingSignals = [];
+    for (const m of missing) {
+        missingSignals.push({ id: `axis-missing-${m}`, message: `Axis "${m}" has no matching scaffold entry.` });
+    }
+    if (missing.length > 0) {
+        reasons.push(`${missing.length} of ${axes.length} coverage axis/axes are missing.`);
+    }
+    const uncertainty = buildUncertaintyReport({
+        confidence: coverageConfidence,
+        reasons,
+        missingSignals,
+        suggestedCommands: buildNextCommands(taskOrDomain),
+        safeFallbackCommand: 'shrk feedback actions',
+        whatWouldIncreaseConfidence: suggestAdditions(missing, taskOrDomain),
+    });
+    return {
+        schema: SCAFFOLD_COVERAGE_SCHEMA,
+        generatedAt: new Date().toISOString(),
+        ...(task ? { task } : {}),
+        ...(domain ? { domain } : {}),
+        axes,
+        confidence,
+        grade,
+        missing,
+        suggestedAdditions: suggestAdditions(missing, taskOrDomain),
+        nextCommands: buildNextCommands(taskOrDomain),
+        uncertainty,
+    };
+}
+function tokenScore(text, taskLower) {
+    const t = text.toLowerCase();
+    const tokens = taskLower.split(/[^a-z0-9]+/).filter((x) => x.length >= 3);
+    let score = 0;
+    for (const tk of tokens)
+        if (t.includes(tk))
+            score += 1;
+    return score;
+}
+function collectVerificationCommands(inspection) {
+    const out = [];
+    for (const r of inspection.knowledgeEntries) {
+        const ah = r.actionHints;
+        if (!ah)
+            continue;
+        const list = (ah.verificationCommands ?? []);
+        for (const v of list) {
+            out.push(typeof v === 'string' ? v : v.command);
+        }
+    }
+    return out;
+}
+function emptyReport() {
+    return {
+        schema: SCAFFOLD_COVERAGE_SCHEMA,
+        generatedAt: new Date().toISOString(),
+        axes: [],
+        confidence: 0,
+        grade: CoverageGrade.Missing,
+        missing: [],
+        suggestedAdditions: [],
+        nextCommands: [
+            'Usage: shrk coverage scaffolds --task "<task>" | --domain <domain>',
+        ],
+    };
+}
+export function renderScaffoldCoverageMarkdown(report) {
+    const lines = [];
+    lines.push('# Scaffold coverage');
+    if (report.task)
+        lines.push(`Task: \`${report.task}\``);
+    if (report.domain)
+        lines.push(`Domain: \`${report.domain}\``);
+    lines.push('');
+    lines.push(`- grade: **${report.grade}**`);
+    lines.push(`- confidence: ${(report.confidence * 100).toFixed(0)}%`);
+    lines.push(`- matched axes: ${report.axes.filter((a) => a.matched).length} / ${report.axes.length}`);
+    lines.push('');
+    lines.push('## Axes');
+    for (const a of report.axes) {
+        const mark = a.matched ? 'yes' : 'no';
+        lines.push(`- **${a.axis}**: ${mark} (count=${a.matchCount}${a.topIds.length > 0 ? ', top=' + a.topIds.slice(0, 3).join(', ') : ''})`);
+    }
+    if (report.missing.length > 0) {
+        lines.push('');
+        lines.push('## Missing pieces');
+        for (const m of report.missing)
+            lines.push(`- ${m}`);
+    }
+    if (report.suggestedAdditions.length > 0) {
+        lines.push('');
+        lines.push('## Suggested additions');
+        for (const s of report.suggestedAdditions)
+            lines.push(`- ${s}`);
+    }
+    if (report.nextCommands.length > 0) {
+        lines.push('');
+        lines.push('## Next commands');
+        for (const c of report.nextCommands)
+            lines.push(`- \`${c}\``);
+    }
+    return lines.join('\n') + '\n';
+}

package/dist/scaffold-patterns.d.ts

@@ -0,0 +1,38 @@
+import { type IScaffoldPattern } from '@shrkcrft/plugin-api';
+import type { ISharkcraftInspection, ISourceInfo } from './sharkcraft-inspector.js';
+export interface IScaffoldPatternWithSource {
+    pattern: IScaffoldPattern;
+    source: ISourceInfo;
+}
+export interface IScaffoldPatternsLoadResult {
+    patterns: IScaffoldPatternWithSource[];
+    warnings: string[];
+}
+export declare function loadScaffoldPatternsFromFile(file: string): Promise<{
+    patterns: IScaffoldPattern[];
+    warnings: string[];
+}>;
+/**
+ * Walk the inspection's discovered packs and load every `scaffoldPatternFiles`
+ * entry. Returns the patterns + source map.
+ */
+export declare function loadScaffoldPatternsFromInspection(inspection: ISharkcraftInspection): Promise<IScaffoldPatternsLoadResult>;
+export interface IScaffoldPatternIssue {
+    patternId: string;
+    field: string;
+    severity: 'error' | 'warning' | 'info';
+    message: string;
+}
+export declare function doctorScaffoldPatterns(patterns: readonly IScaffoldPatternWithSource[], inspection: ISharkcraftInspection): readonly IScaffoldPatternIssue[];
+/**
+ * Convert a glob-like pattern (only `*` and `**` are recognized) into a
+ * RegExp. Kept tiny — we don't depend on `minimatch`.
+ */
+export declare function globToRegExp(glob: string): RegExp;
+export declare function matchScaffoldPattern(pattern: IScaffoldPattern, relativePath: string): boolean;
+export interface IExtractedVariables {
+    values: Record<string, string>;
+    warnings: string[];
+}
+export declare function extractVariablesForFile(pattern: IScaffoldPattern, filePath: string, inspection: ISharkcraftInspection): IExtractedVariables;
+//# sourceMappingURL=scaffold-patterns.d.ts.map

package/dist/scaffold-patterns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold-patterns.d.ts","sourceRoot":"","sources":["../src/scaffold-patterns.ts"],"names":[],"mappings":"AAUA,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAEpF,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,gBAAgB,CAAC;IAC1B,MAAM,EAAE,WAAW,CAAC;CACrB;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,0BAA0B,EAAE,CAAC;IACvC,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,wBAAsB,4BAA4B,CAChD,IAAI,EAAE,MAAM,GACX,OAAO,CAAC;IAAE,QAAQ,EAAE,gBAAgB,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CA0C/D;AAED;;;GAGG;AACH,wBAAsB,kCAAkC,CACtD,UAAU,EAAE,qBAAqB,GAChC,OAAO,CAAC,2BAA2B,CAAC,CAiDtC;AAID,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;IACvC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,SAAS,0BAA0B,EAAE,EAC/C,UAAU,EAAE,qBAAqB,GAChC,SAAS,qBAAqB,EAAE,CA6DlC;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAwBjD;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,gBAAgB,EACzB,YAAY,EAAE,MAAM,GACnB,OAAO,CAST;AAID,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,gBAAgB,EACzB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,qBAAqB,GAChC,mBAAmB,CAuCrB"}