@shrkcrft/inspector 0.1.0-alpha.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SharkCraft contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,15 @@
+# @shrkcrft/inspector
+
+SharkCraft inspector: project overview, doctor checks, AI-agent instructions.
+
+Part of [SharkCraft](https://github.com/shrkcrft/sharkcraft) — a deterministic, local-first toolkit that gives AI coding agents durable project context. See the main repo for documentation, examples, and the `shrk` CLI.
+
+## Install
+
+```bash
+bun add @shrkcrft/inspector
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/acceptance-replay.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Acceptance-command replay.
+ *
+ * Given a change set, decides which previous validation commands (the
+ * read-only acceptance gates from the dev-cycle / preflight planners +
+ * the changes-summary suggestions) should be re-run, and *why*. No
+ * shell execution — purely a structured "punch list".
+ *
+ * Reads:
+ *   - the changes-summary report,
+ *   - the dev-cycle preflight gate plan (static gate set).
+ *
+ * Output: `sharkcraft.acceptance-replay/v1`.
+ */
+import { type IChangesSummaryReport } from './changes-summary.js';
+export declare const ACCEPTANCE_REPLAY_SCHEMA = "sharkcraft.acceptance-replay/v1";
+export declare enum ReplayProfile {
+    ChangedOnly = "changed-only",
+    Standard = "standard",
+    Strict = "strict"
+}
+export declare enum ReplayReason {
+    Cli = "cli-touched",
+    Mcp = "mcp-tool-touched",
+    Safety = "safety-relevant-touched",
+    PackAsset = "pack-asset-touched",
+    Schema = "schema-or-schema-like-touched",
+    Boundaries = "boundary-or-config-touched",
+    Inspector = "inspector-touched",
+    Generator = "generator-or-apply-touched",
+    Docs = "docs-only-touched",
+    AlwaysOn = "baseline-gate"
+}
+export interface IReplayCommand {
+    readonly command: string;
+    readonly reasons: ReadonlyArray<ReplayReason>;
+    readonly expectedExitCode: number;
+    readonly category: 'baseline' | 'gate' | 'suggested';
+    readonly safety: 'read-only' | 'runs-shell';
+}
+export interface IAcceptanceReplayReport {
+    readonly schema: typeof ACCEPTANCE_REPLAY_SCHEMA;
+    readonly generatedAt: string;
+    readonly profile: ReplayProfile;
+    readonly roundLabel?: string;
+    readonly source: IChangesSummaryReport['source'];
+    readonly ref?: string;
+    readonly totalChangedFiles: number;
+    readonly commands: ReadonlyArray<IReplayCommand>;
+    readonly skipped: ReadonlyArray<{
+        command: string;
+        reason: string;
+    }>;
+}
+export interface IBuildAcceptanceReplayInput {
+    readonly summary: IChangesSummaryReport;
+    readonly profile?: ReplayProfile;
+    readonly roundLabel?: string;
+}
+export declare function buildAcceptanceReplay(input: IBuildAcceptanceReplayInput): IAcceptanceReplayReport;
+export declare function renderAcceptanceReplayText(report: IAcceptanceReplayReport): string;
+export declare function renderAcceptanceReplayMarkdown(report: IAcceptanceReplayReport): string;
+//# sourceMappingURL=acceptance-replay.d.ts.map

package/dist/acceptance-replay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"acceptance-replay.d.ts","sourceRoot":"","sources":["../src/acceptance-replay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAc,KAAK,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE9E,eAAO,MAAM,wBAAwB,oCAAoC,CAAC;AAE1E,oBAAY,aAAa;IACvB,WAAW,iBAAiB;IAC5B,QAAQ,aAAa;IACrB,MAAM,WAAW;CAClB;AAED,oBAAY,YAAY;IACtB,GAAG,gBAAgB;IACnB,GAAG,qBAAqB;IACxB,MAAM,4BAA4B;IAClC,SAAS,uBAAuB;IAChC,MAAM,kCAAkC;IACxC,UAAU,+BAA+B;IACzC,SAAS,sBAAsB;IAC/B,SAAS,+BAA+B;IACxC,IAAI,sBAAsB;IAC1B,QAAQ,kBAAkB;CAC3B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;IAC9C,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,UAAU,GAAG,MAAM,GAAG,WAAW,CAAC;IACrD,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,YAAY,CAAC;CAC7C;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,MAAM,EAAE,OAAO,wBAAwB,CAAC;IACjD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC,QAAQ,CAAC,CAAC;IACjD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;IACjD,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACtE;AA8GD,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,OAAO,EAAE,qBAAqB,CAAC;IACxC,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,2BAA2B,GACjC,uBAAuB,CA4EzB;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,uBAAuB,GAAG,MAAM,CAkBlF;AAED,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,uBAAuB,GAAG,MAAM,CAmBtF"}

package/dist/acceptance-replay.js

@@ -0,0 +1,240 @@
+/**
+ * Acceptance-command replay.
+ *
+ * Given a change set, decides which previous validation commands (the
+ * read-only acceptance gates from the dev-cycle / preflight planners +
+ * the changes-summary suggestions) should be re-run, and *why*. No
+ * shell execution — purely a structured "punch list".
+ *
+ * Reads:
+ *   - the changes-summary report,
+ *   - the dev-cycle preflight gate plan (static gate set).
+ *
+ * Output: `sharkcraft.acceptance-replay/v1`.
+ */
+import { ChangeArea } from "./changes-summary.js";
+export const ACCEPTANCE_REPLAY_SCHEMA = 'sharkcraft.acceptance-replay/v1';
+export var ReplayProfile;
+(function (ReplayProfile) {
+    ReplayProfile["ChangedOnly"] = "changed-only";
+    ReplayProfile["Standard"] = "standard";
+    ReplayProfile["Strict"] = "strict";
+})(ReplayProfile || (ReplayProfile = {}));
+export var ReplayReason;
+(function (ReplayReason) {
+    ReplayReason["Cli"] = "cli-touched";
+    ReplayReason["Mcp"] = "mcp-tool-touched";
+    ReplayReason["Safety"] = "safety-relevant-touched";
+    ReplayReason["PackAsset"] = "pack-asset-touched";
+    ReplayReason["Schema"] = "schema-or-schema-like-touched";
+    ReplayReason["Boundaries"] = "boundary-or-config-touched";
+    ReplayReason["Inspector"] = "inspector-touched";
+    ReplayReason["Generator"] = "generator-or-apply-touched";
+    ReplayReason["Docs"] = "docs-only-touched";
+    ReplayReason["AlwaysOn"] = "baseline-gate";
+})(ReplayReason || (ReplayReason = {}));
+const BASELINE_GATES = [
+    {
+        command: 'bun x tsc -p tsconfig.base.json --noEmit',
+        category: 'baseline',
+        reason: ReplayReason.AlwaysOn,
+        trigger: () => true,
+    },
+    {
+        command: 'bun test',
+        category: 'baseline',
+        reason: ReplayReason.AlwaysOn,
+        trigger: () => true,
+    },
+    {
+        command: 'shrk doctor',
+        category: 'baseline',
+        reason: ReplayReason.AlwaysOn,
+        trigger: () => true,
+    },
+];
+const CONDITIONAL_GATES = [
+    {
+        command: 'shrk commands doctor',
+        category: 'gate',
+        reason: ReplayReason.Cli,
+        trigger: (r) => r.touchedCommands.length > 0,
+    },
+    {
+        command: 'shrk commands ux-check',
+        category: 'gate',
+        reason: ReplayReason.Cli,
+        trigger: (r) => r.touchedCommands.length > 0,
+    },
+    {
+        command: 'shrk safety audit --deep',
+        category: 'gate',
+        reason: ReplayReason.Safety,
+        trigger: (r) => r.touchedMcpTools.length > 0 || r.safetyRelevantFiles.length > 0,
+    },
+    {
+        command: 'shrk check boundaries --changed-only',
+        category: 'gate',
+        reason: ReplayReason.Boundaries,
+        trigger: (r) => r.files.some((f) => f.area === ChangeArea.Boundaries || f.path.endsWith('tsconfig.base.json')) ||
+            r.files.some((f) => f.path.startsWith('packages/')),
+    },
+    {
+        command: 'shrk packs signature-status',
+        category: 'gate',
+        reason: ReplayReason.PackAsset,
+        trigger: (r) => r.touchedPackAssets.length > 0,
+    },
+    {
+        command: 'shrk packs doctor --require-signatures',
+        category: 'gate',
+        reason: ReplayReason.PackAsset,
+        trigger: (r) => r.touchedPackAssets.length > 0,
+    },
+    {
+        command: 'shrk self-config doctor',
+        category: 'gate',
+        reason: ReplayReason.Inspector,
+        trigger: (r) => r.files.some((f) => f.area === ChangeArea.Inspector ||
+            f.area === ChangeArea.Sharkcraft ||
+            f.path.startsWith('sharkcraft/')),
+    },
+    {
+        command: 'shrk product check',
+        category: 'gate',
+        reason: ReplayReason.Inspector,
+        trigger: (r) => r.files.some((f) => f.area === ChangeArea.Inspector),
+    },
+    {
+        command: 'shrk schemas inventory --multi-version-only',
+        category: 'gate',
+        reason: ReplayReason.Schema,
+        trigger: (r) => r.touchedSchemas.length > 0,
+    },
+    {
+        command: 'bun run release:preflight',
+        category: 'gate',
+        reason: ReplayReason.Generator,
+        trigger: (r) => r.files.some((f) => f.area === ChangeArea.Generator ||
+            f.path.startsWith('packages/cli/src/commands/apply.command') ||
+            f.path.startsWith('scripts/release')),
+    },
+];
+export function buildAcceptanceReplay(input) {
+    const profile = input.profile ?? ReplayProfile.ChangedOnly;
+    const summary = input.summary;
+    const commands = [];
+    const skipped = [];
+    // Baselines — always on, but in changed-only mode if zero files we skip
+    // type/test gates (purely a UX courtesy).
+    for (const g of BASELINE_GATES) {
+        if (profile === ReplayProfile.ChangedOnly && summary.totalFiles === 0 && g.command !== 'shrk doctor') {
+            skipped.push({ command: g.command, reason: 'no changed files; baseline skipped under changed-only profile' });
+            continue;
+        }
+        commands.push({
+            command: g.command,
+            reasons: [g.reason],
+            expectedExitCode: 0,
+            category: g.category,
+            safety: g.command.startsWith('bun ') ? 'runs-shell' : 'read-only',
+        });
+    }
+    // Conditional gates — only when the change set demands.
+    for (const g of CONDITIONAL_GATES) {
+        const fired = g.trigger(summary);
+        if (fired) {
+            commands.push({
+                command: g.command,
+                reasons: [g.reason],
+                expectedExitCode: 0,
+                category: g.category,
+                safety: g.command.startsWith('bun ') ? 'runs-shell' : 'read-only',
+            });
+        }
+        else if (profile === ReplayProfile.Strict) {
+            // Strict profile runs everything regardless.
+            commands.push({
+                command: g.command,
+                reasons: [ReplayReason.AlwaysOn],
+                expectedExitCode: 0,
+                category: g.category,
+                safety: g.command.startsWith('bun ') ? 'runs-shell' : 'read-only',
+            });
+        }
+        else if (profile === ReplayProfile.Standard) {
+            // Standard profile reports the skip with explicit reason.
+            skipped.push({
+                command: g.command,
+                reason: `not triggered by change set (reason=${g.reason})`,
+            });
+        }
+    }
+    // Bring in changes-summary suggested commands as 'suggested' category,
+    // dedup against gates already added.
+    const known = new Set(commands.map((c) => c.command));
+    for (const s of summary.suggestedValidationCommands) {
+        if (known.has(s))
+            continue;
+        commands.push({
+            command: s,
+            reasons: [ReplayReason.AlwaysOn],
+            expectedExitCode: 0,
+            category: 'suggested',
+            safety: s.startsWith('bun ') ? 'runs-shell' : 'read-only',
+        });
+    }
+    return {
+        schema: ACCEPTANCE_REPLAY_SCHEMA,
+        generatedAt: new Date().toISOString(),
+        profile,
+        ...(input.roundLabel ? { roundLabel: input.roundLabel } : summary.roundLabel ? { roundLabel: summary.roundLabel } : {}),
+        source: summary.source,
+        ...(summary.ref ? { ref: summary.ref } : {}),
+        totalChangedFiles: summary.totalFiles,
+        commands,
+        skipped,
+    };
+}
+export function renderAcceptanceReplayText(report) {
+    const lines = [];
+    lines.push(`=== Acceptance replay (profile=${report.profile}${report.roundLabel ? `, round=${report.roundLabel}` : ''}${report.ref ? `, since=${report.ref}` : ''}) ===`);
+    lines.push(`  changed files: ${report.totalChangedFiles}`);
+    lines.push(`  commands:      ${report.commands.length}`);
+    if (report.skipped.length > 0)
+        lines.push(`  skipped:       ${report.skipped.length}`);
+    for (const c of report.commands) {
+        const tag = c.category.padEnd(9);
+        lines.push(`  [${tag}] $ ${c.command}`);
+        lines.push(`            reasons: ${c.reasons.join(', ')}`);
+    }
+    if (report.skipped.length > 0) {
+        lines.push('\nSkipped:');
+        for (const s of report.skipped)
+            lines.push(`  • ${s.command}  — ${s.reason}`);
+    }
+    return lines.join('\n') + '\n';
+}
+export function renderAcceptanceReplayMarkdown(report) {
+    const lines = [];
+    lines.push('# Acceptance replay');
+    lines.push('');
+    lines.push(`- profile: \`${report.profile}\``);
+    if (report.roundLabel)
+        lines.push(`- round: \`${report.roundLabel}\``);
+    if (report.ref)
+        lines.push(`- ref: \`${report.ref}\``);
+    lines.push(`- changed files: ${report.totalChangedFiles}`);
+    lines.push('');
+    lines.push('## Commands to re-run');
+    for (const c of report.commands) {
+        lines.push(`- \`${c.command}\`  _(${c.category}, ${c.reasons.join(', ')})_`);
+    }
+    if (report.skipped.length > 0) {
+        lines.push('');
+        lines.push('## Skipped');
+        for (const s of report.skipped)
+            lines.push(`- \`${s.command}\` — ${s.reason}`);
+    }
+    return lines.join('\n') + '\n';
+}

package/dist/action-hint-diagnostics.d.ts

@@ -0,0 +1,32 @@
+import { type IKnowledgeEntry } from '@shrkcrft/knowledge';
+export interface IActionHintQualityIssue {
+    entryId: string;
+    severity: 'warning';
+    code: 'missing-hints' | 'missing-commands-or-mcp' | 'missing-forbidden-actions' | 'missing-verification' | 'missing-write-policy' | 'missing-related-templates' | 'missing-related-path-conventions';
+    message: string;
+    /** Free-form suggestion the doctor can show next to the warning. */
+    suggestion?: string;
+}
+export interface IActionHintQualityReport {
+    /** Entries that were evaluated (matched the heuristics for "should have hints"). */
+    evaluatedEntryCount: number;
+    /** Subset that has at least one hint. */
+    entriesWithHints: number;
+    issues: IActionHintQualityIssue[];
+    /** Top N entry ids by issue count for quick prioritization. */
+    topMissing: Array<{
+        entryId: string;
+        missingFields: string[];
+    }>;
+}
+/**
+ * Inspect knowledge entries for action-hint quality. Only critical / high
+ * priority entries whose appliesWhen mentions generate/create/refactor/etc.
+ * are evaluated — other entries (project overview, glossary, tech stack)
+ * are not expected to carry hints.
+ *
+ * All issues are warnings (severity 'warning'). The doctor surfaces them as
+ * "soft" findings.
+ */
+export declare function diagnoseActionHints(entries: readonly IKnowledgeEntry[]): IActionHintQualityReport;
+//# sourceMappingURL=action-hint-diagnostics.d.ts.map

package/dist/action-hint-diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-hint-diagnostics.d.ts","sourceRoot":"","sources":["../src/action-hint-diagnostics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3E,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,SAAS,CAAC;IACpB,IAAI,EACA,eAAe,GACf,yBAAyB,GACzB,2BAA2B,GAC3B,sBAAsB,GACtB,sBAAsB,GACtB,2BAA2B,GAC3B,kCAAkC,CAAC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,wBAAwB;IACvC,oFAAoF;IACpF,mBAAmB,EAAE,MAAM,CAAC;IAC5B,yCAAyC;IACzC,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,uBAAuB,EAAE,CAAC;IAClC,+DAA+D;IAC/D,UAAU,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;CACjE;AAiBD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,GAAG,wBAAwB,CAkHjG"}

package/dist/action-hint-diagnostics.js

@@ -0,0 +1,133 @@
+import { hasActionHints } from '@shrkcrft/knowledge';
+const GEN_KEYWORDS = ['generate', 'create', 'add', 'refactor', 'test', 'review'];
+function appliesToGeneration(entry) {
+    for (const a of entry.appliesWhen ?? []) {
+        const lower = a.toLowerCase();
+        if (GEN_KEYWORDS.some((k) => lower.includes(k)))
+            return true;
+    }
+    return false;
+}
+function isCriticalOrHigh(entry) {
+    const p = String(entry.priority);
+    return p === 'critical' || p === 'high';
+}
+/**
+ * Inspect knowledge entries for action-hint quality. Only critical / high
+ * priority entries whose appliesWhen mentions generate/create/refactor/etc.
+ * are evaluated — other entries (project overview, glossary, tech stack)
+ * are not expected to carry hints.
+ *
+ * All issues are warnings (severity 'warning'). The doctor surfaces them as
+ * "soft" findings.
+ */
+export function diagnoseActionHints(entries) {
+    const issues = [];
+    const missingByEntry = new Map();
+    let evaluated = 0;
+    let withHints = 0;
+    for (const entry of entries) {
+        if (!isCriticalOrHigh(entry))
+            continue;
+        if (!appliesToGeneration(entry))
+            continue;
+        // Path / overview / technical entries describe location or facts — not actions.
+        const type = String(entry.type);
+        if (type === 'path' || type === 'overview' || type === 'technical')
+            continue;
+        evaluated += 1;
+        const recordMissing = (field) => {
+            const list = missingByEntry.get(entry.id) ?? [];
+            list.push(field);
+            missingByEntry.set(entry.id, list);
+        };
+        if (!hasActionHints(entry)) {
+            issues.push({
+                entryId: entry.id,
+                severity: 'warning',
+                code: 'missing-hints',
+                message: `Entry "${entry.id}" is high/critical and applies to generation but has no actionHints.`,
+                suggestion: 'Add at least mcpTools/commands and forbiddenActions.',
+            });
+            recordMissing('all');
+            continue;
+        }
+        withHints += 1;
+        const h = entry.actionHints;
+        const hasCommandsOrTools = (h.commands?.length ?? 0) > 0 || (h.mcpTools?.length ?? 0) > 0;
+        if (!hasCommandsOrTools) {
+            issues.push({
+                entryId: entry.id,
+                severity: 'warning',
+                code: 'missing-commands-or-mcp',
+                message: `"${entry.id}" should list at least one CLI command or MCP tool.`,
+            });
+            recordMissing('commands/mcpTools');
+        }
+        // Generation-related entries should have forbiddenActions.
+        if ((h.forbiddenActions?.length ?? 0) === 0) {
+            issues.push({
+                entryId: entry.id,
+                severity: 'warning',
+                code: 'missing-forbidden-actions',
+                message: `"${entry.id}" should list at least one forbiddenActions item.`,
+            });
+            recordMissing('forbiddenActions');
+        }
+        // Verification commands matter for review/refactor/generate scopes.
+        if ((h.verificationCommands?.length ?? 0) === 0) {
+            issues.push({
+                entryId: entry.id,
+                severity: 'warning',
+                code: 'missing-verification',
+                message: `"${entry.id}" should list verificationCommands so the agent can validate the result.`,
+            });
+            recordMissing('verificationCommands');
+        }
+        // Write-related rules should declare writePolicy explicitly.
+        const tagsLower = new Set(entry.tags.map((t) => t.toLowerCase()));
+        const looksWriteRelated = tagsLower.has('safety') ||
+            tagsLower.has('generator') ||
+            (entry.appliesWhen ?? []).some((a) => /write|apply|generate/i.test(a));
+        if (looksWriteRelated && !h.writePolicy) {
+            issues.push({
+                entryId: entry.id,
+                severity: 'warning',
+                code: 'missing-write-policy',
+                message: `"${entry.id}" looks write-related but does not declare a writePolicy.`
+            });
+            recordMissing('writePolicy');
+        }
+        // Template rules should link relatedTemplates.
+        if (tagsLower.has('template') &&
+            (h.relatedTemplates?.length ?? 0) === 0) {
+            issues.push({
+                entryId: entry.id,
+                severity: 'warning',
+                code: 'missing-related-templates',
+                message: `"${entry.id}" is template-related but does not list relatedTemplates.`
+            });
+            recordMissing('relatedTemplates');
+        }
+        if ((tagsLower.has('path') || tagsLower.has('paths')) &&
+            (h.relatedPathConventions?.length ?? 0) === 0) {
+            issues.push({
+                entryId: entry.id,
+                severity: 'warning',
+                code: 'missing-related-path-conventions',
+                message: `"${entry.id}" is path-related but does not list relatedPathConventions.`,
+            });
+            recordMissing('relatedPathConventions');
+        }
+    }
+    const topMissing = [...missingByEntry.entries()]
+        .map(([entryId, missingFields]) => ({ entryId, missingFields }))
+        .sort((a, b) => b.missingFields.length - a.missingFields.length)
+        .slice(0, 5);
+    return {
+        evaluatedEntryCount: evaluated,
+        entriesWithHints: withHints,
+        issues,
+        topMissing,
+    };
+}

package/dist/adoption-check.d.ts

@@ -0,0 +1,28 @@
+export declare enum AdoptionCheckResult {
+    CanApply = "can-apply",
+    CannotApply = "cannot-apply",
+    Unknown = "unknown"
+}
+export interface IAdoptionCheck {
+    id: string;
+    passed: boolean;
+    severity: 'error' | 'warning' | 'info';
+    message: string;
+}
+export interface IAdoptionCheckReport {
+    schema: 'sharkcraft.adoption-check/v1';
+    projectRoot: string;
+    patchPath: string | null;
+    patchFormat: 'pseudo' | 'unified' | 'unknown';
+    canApply: AdoptionCheckResult;
+    checks: readonly IAdoptionCheck[];
+    warnings: readonly string[];
+    nextCommand: string;
+}
+export interface IBuildAdoptionCheckInput {
+    projectRoot: string;
+    /** When provided, override the default adoption-state-derived patch path. */
+    patchPath?: string;
+}
+export declare function buildAdoptionCheck(input: IBuildAdoptionCheckInput): IAdoptionCheckReport;
+//# sourceMappingURL=adoption-check.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"adoption-check.d.ts","sourceRoot":"","sources":["../src/adoption-check.ts"],"names":[],"mappings":"AAcA,oBAAY,mBAAmB;IAC7B,QAAQ,cAAc;IACtB,WAAW,iBAAiB;IAC5B,OAAO,YAAY;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;IACvC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,8BAA8B,CAAC;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,EAAE,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;IAC9C,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,MAAM,EAAE,SAAS,cAAc,EAAE,CAAC;IAClC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,WAAW,EAAE,MAAM,CAAC;CACrB;AA6BD,MAAM,WAAW,wBAAwB;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,wBAAwB,GAAG,oBAAoB,CAwIxF"}