@shrkcrft/inspector 0.1.0-alpha.2

package/dist/bundle-replay.js

@@ -0,0 +1,273 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { getBundleDir, listFeatureBundles, readFeatureBundle, } from "./feature-bundle.js";
+export const BUNDLE_REPLAY_SCHEMA = 'sharkcraft.bundle-replay/v1';
+export var BundleReplayStatus;
+(function (BundleReplayStatus) {
+    BundleReplayStatus["Clean"] = "clean";
+    BundleReplayStatus["Warnings"] = "warnings";
+    BundleReplayStatus["Tampered"] = "tampered";
+    BundleReplayStatus["Missing"] = "missing";
+})(BundleReplayStatus || (BundleReplayStatus = {}));
+function parseAuditLog(content) {
+    const out = [];
+    for (const line of content.split('\n')) {
+        if (!line.trim())
+            continue;
+        // Expected shape: "<iso>  applied  <plan>[  note]"
+        const parts = line.split(/\s+/);
+        if (parts.length < 3)
+            continue;
+        const timestamp = parts[0];
+        const action = parts[1];
+        const planName = parts[2];
+        const note = parts.slice(3).join(' ').trim();
+        out.push({ timestamp, action, planName, raw: line, ...(note ? { note } : {}) });
+    }
+    return out;
+}
+function hashOf(file) {
+    try {
+        if (!existsSync(file))
+            return null;
+        const raw = readFileSync(file, 'utf8');
+        return createHash('sha256').update(raw).digest('hex').slice(0, 16);
+    }
+    catch {
+        return null;
+    }
+}
+function extractPlanTargets(file) {
+    try {
+        const data = JSON.parse(readFileSync(file, 'utf8'));
+        const changes = data.changes ?? data.plan?.changes ?? [];
+        return changes.map((c) => c.relativePath).filter((p) => Boolean(p));
+    }
+    catch {
+        return [];
+    }
+}
+export function replayBundle(cwd, bundleId, options = {}) {
+    const generatedAt = new Date().toISOString();
+    const bundle = readFeatureBundle(cwd, bundleId);
+    if (!bundle) {
+        return {
+            schema: BUNDLE_REPLAY_SCHEMA,
+            bundleId,
+            status: BundleReplayStatus.Missing,
+            generatedAt,
+            auditEntries: 0,
+            planEntries: [],
+            warnings: [
+                { code: 'bundle-not-found', message: `Bundle "${bundleId}" not found.` },
+            ],
+            recommendedFix: `Run \`shrk bundle list\` to confirm the id.`,
+        };
+    }
+    const dir = getBundleDir(cwd, bundleId);
+    const auditFile = nodePath.join(dir, 'reports', 'apply-audit.log');
+    const auditEntries = existsSync(auditFile)
+        ? parseAuditLog(readFileSync(auditFile, 'utf8'))
+        : [];
+    const warnings = [];
+    const planEntries = [];
+    const auditByPlan = new Map();
+    for (const e of auditEntries) {
+        const arr = auditByPlan.get(e.planName) ?? [];
+        arr.push(e);
+        auditByPlan.set(e.planName, arr);
+    }
+    // For every plan in the bundle, check on-disk state vs audit.
+    for (const plan of bundle.plans) {
+        const planFile = nodePath.join(dir, 'plans', plan.file);
+        const currentHash = hashOf(planFile);
+        const targets = extractPlanTargets(planFile);
+        const issues = [];
+        const applied = plan.status === 'applied';
+        const auditForPlan = auditByPlan.get(plan.name) ?? [];
+        if (!existsSync(planFile) && plan.status !== 'intent') {
+            issues.push('plan file missing on disk');
+        }
+        if (applied && auditForPlan.length === 0) {
+            issues.push('plan marked applied but audit log has no entry');
+        }
+        if (!applied && auditForPlan.length > 0) {
+            issues.push('audit log has apply entry but plan not marked applied');
+        }
+        if (plan.expectedTargets.length > 0 &&
+            targets.length > 0 &&
+            JSON.stringify([...plan.expectedTargets].sort()) !== JSON.stringify([...targets].sort())) {
+            issues.push('expectedTargets diverge from plan-file targets');
+        }
+        if (auditForPlan.length > 1) {
+            warnings.push({
+                code: 'multiple-apply-entries',
+                message: `plan ${plan.name} has ${auditForPlan.length} audit entries.`,
+                planName: plan.name,
+            });
+        }
+        const entry = {
+            planName: plan.name,
+            applied,
+            currentHash,
+            expectedTargets: plan.expectedTargets,
+            issues,
+        };
+        planEntries.push(entry);
+    }
+    // Audit entries referencing plans missing from the bundle.
+    for (const [planName, entries] of auditByPlan) {
+        if (bundle.plans.some((p) => p.name === planName))
+            continue;
+        warnings.push({
+            code: 'audit-orphan',
+            message: `audit log mentions plan "${planName}" not present in bundle.json (${entries.length} entries).`,
+            planName,
+        });
+    }
+    // Validation-after-apply check: applied plans without any subsequent validation.
+    const appliedCount = bundle.plans.filter((p) => p.status === 'applied').length;
+    if (appliedCount > 0 && bundle.validations.length === 0) {
+        warnings.push({
+            code: 'no-validation-after-apply',
+            message: 'plans applied but no validation entries recorded.',
+        });
+    }
+    // Detect out-of-order apply against persisted dependencies.
+    const applyOrder = auditEntries.map((e) => e.planName).filter((n) => n !== '');
+    if (applyOrder.length > 1 && bundle.dependencies.length > 0) {
+        const orderedSet = new Set();
+        for (const n of applyOrder) {
+            const incoming = bundle.dependencies.filter((e) => e.to === n);
+            for (const d of incoming) {
+                if (!orderedSet.has(d.from)) {
+                    warnings.push({
+                        code: 'out-of-order-apply',
+                        message: `plan "${n}" applied before its dependency "${d.from}".`,
+                        planName: n,
+                    });
+                }
+            }
+            orderedSet.add(n);
+        }
+    }
+    let status = BundleReplayStatus.Clean;
+    const hasIssues = planEntries.some((p) => p.issues.length > 0);
+    if (hasIssues || warnings.some((w) => w.code === 'audit-orphan' || w.code === 'out-of-order-apply')) {
+        status = BundleReplayStatus.Tampered;
+    }
+    else if (warnings.length > 0) {
+        status = BundleReplayStatus.Warnings;
+    }
+    if (options.strict && warnings.length > 0)
+        status = BundleReplayStatus.Tampered;
+    const recommendedFix = buildRecommendedFix(bundle, status, warnings, planEntries);
+    return {
+        schema: BUNDLE_REPLAY_SCHEMA,
+        bundleId,
+        status,
+        generatedAt,
+        auditEntries: auditEntries.length,
+        planEntries,
+        warnings,
+        recommendedFix,
+    };
+}
+export const BUNDLE_REPLAY_BATCH_SCHEMA = 'sharkcraft.bundle-replay-batch/v1';
+export function replayAllBundles(cwd, options = {}) {
+    const bundles = listFeatureBundles(cwd);
+    const reports = [];
+    for (const b of bundles) {
+        if (options.match && !b.id.toLowerCase().includes(options.match.toLowerCase()))
+            continue;
+        reports.push(replayBundle(cwd, b.id, { strict: Boolean(options.strict) }));
+    }
+    const counts = {
+        clean: 0,
+        warnings: 0,
+        tampered: 0,
+        missing: 0,
+    };
+    const issues = [];
+    for (const r of reports) {
+        if (r.status === BundleReplayStatus.Clean)
+            counts.clean += 1;
+        else if (r.status === BundleReplayStatus.Warnings)
+            counts.warnings += 1;
+        else if (r.status === BundleReplayStatus.Tampered)
+            counts.tampered += 1;
+        else
+            counts.missing += 1;
+        for (const p of r.planEntries) {
+            for (const issue of p.issues) {
+                issues.push({
+                    bundleId: r.bundleId,
+                    planName: p.planName,
+                    code: 'plan-issue',
+                    message: issue,
+                });
+            }
+        }
+        for (const w of r.warnings) {
+            const entry = {
+                bundleId: r.bundleId,
+                code: w.code,
+                message: w.message,
+            };
+            if (w.planName)
+                entry.planName = w.planName;
+            issues.push(entry);
+        }
+    }
+    return {
+        schema: BUNDLE_REPLAY_BATCH_SCHEMA,
+        generatedAt: new Date().toISOString(),
+        total: reports.length,
+        cleanCount: counts.clean,
+        warningsCount: counts.warnings,
+        tamperedCount: counts.tampered,
+        missingCount: counts.missing,
+        reports,
+        topIssues: issues.slice(0, 10),
+    };
+}
+export function renderBundleReplayBatchHtml(batch) {
+    const esc = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+    const parts = [];
+    parts.push('<!doctype html><html><head><meta charset="utf-8">');
+    parts.push('<title>SharkCraft bundle replay (all)</title>');
+    parts.push('<style>body{font:14px/1.5 -apple-system,sans-serif;max-width:1080px;margin:24px auto;padding:0 16px}h1{font-size:20px;border-bottom:1px solid #d0d7de;padding-bottom:8px}table{border-collapse:collapse;width:100%}th,td{border:1px solid #d0d7de;padding:6px 10px;text-align:left}th{background:#f6f8fa}.tag{display:inline-block;padding:2px 8px;border-radius:9999px;font-size:11px;font-weight:600}.tag.ok{background:#dafbe1;color:#1a7f37}.tag.warn{background:#fff8c5;color:#9a6700}.tag.fail{background:#ffebe9;color:#cf222e}</style></head><body>');
+    parts.push(`<h1>Bundle replay (${batch.total})</h1>`);
+    parts.push(`<p>Clean: <span class="tag ok">${batch.cleanCount}</span> · Warnings: <span class="tag warn">${batch.warningsCount}</span> · Tampered: <span class="tag fail">${batch.tamperedCount}</span> · Missing: ${batch.missingCount}</p>`);
+    parts.push('<table><thead><tr><th>Bundle</th><th>Status</th><th>Audit entries</th><th>Issues</th></tr></thead><tbody>');
+    for (const r of batch.reports) {
+        const tag = r.status === 'clean' ? 'ok' : r.status === 'warnings' ? 'warn' : 'fail';
+        const issuesCount = r.planEntries.reduce((acc, p) => acc + p.issues.length, 0) + r.warnings.length;
+        parts.push(`<tr><td><code>${esc(r.bundleId)}</code></td><td><span class="tag ${tag}">${esc(r.status.toUpperCase())}</span></td><td>${r.auditEntries}</td><td>${issuesCount}</td></tr>`);
+    }
+    parts.push('</tbody></table>');
+    if (batch.topIssues.length > 0) {
+        parts.push('<h2>Top issues</h2><ul>');
+        for (const i of batch.topIssues) {
+            parts.push(`<li><code>${esc(i.bundleId)}</code>${i.planName ? ` / <code>${esc(i.planName)}</code>` : ''} — ${esc(i.code)}: ${esc(i.message)}</li>`);
+        }
+        parts.push('</ul>');
+    }
+    parts.push('</body></html>');
+    return parts.join('\n') + '\n';
+}
+function buildRecommendedFix(bundle, status, warnings, planEntries) {
+    if (status === BundleReplayStatus.Clean)
+        return null;
+    if (warnings.some((w) => w.code === 'no-validation-after-apply')) {
+        return `shrk bundle validate ${bundle.id} --all-verifications --report`;
+    }
+    if (planEntries.some((p) => p.issues.includes('plan file missing on disk'))) {
+        return `Replan with \`shrk bundle plan ${bundle.id} --template <id>\` to re-create missing plan files.`;
+    }
+    if (warnings.some((w) => w.code === 'out-of-order-apply')) {
+        return 'Investigate dependency order in apply-audit.log; consider rolling back affected plans.';
+    }
+    return `Re-run \`shrk bundle replay ${bundle.id} --strict\` after addressing issues.`;
+}

package/dist/bundle-validate-html.d.ts

@@ -0,0 +1,11 @@
+import type { IFeatureBundle, IFeatureBundleValidation } from './feature-bundle.js';
+export interface IRenderBundleValidationHtmlOptions {
+    baselineComparison?: unknown;
+}
+/**
+ * Render an HTML validation report for a bundle. Self-contained (inline
+ * styles); no external assets. Designed to be uploaded by CI as a build
+ * artifact and viewed offline.
+ */
+export declare function renderBundleValidationHtml(bundle: IFeatureBundle, validation: IFeatureBundleValidation, options?: IRenderBundleValidationHtmlOptions): string;
+//# sourceMappingURL=bundle-validate-html.d.ts.map

package/dist/bundle-validate-html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle-validate-html.d.ts","sourceRoot":"","sources":["../src/bundle-validate-html.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAEpF,MAAM,WAAW,kCAAkC;IACjD,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAUD;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,cAAc,EACtB,UAAU,EAAE,wBAAwB,EACpC,OAAO,GAAE,kCAAuC,GAC/C,MAAM,CA6DR"}

package/dist/bundle-validate-html.js

@@ -0,0 +1,60 @@
+function esc(s) {
+    return s
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+/**
+ * Render an HTML validation report for a bundle. Self-contained (inline
+ * styles); no external assets. Designed to be uploaded by CI as a build
+ * artifact and viewed offline.
+ */
+export function renderBundleValidationHtml(bundle, validation, options = {}) {
+    const parts = [];
+    parts.push('<!doctype html>');
+    parts.push('<html><head><meta charset="utf-8">');
+    parts.push(`<title>SharkCraft bundle validation — ${esc(bundle.id)}</title>`);
+    parts.push('<style>');
+    parts.push('body{font:14px/1.4 -apple-system,BlinkMacSystemFont,sans-serif;max-width:1080px;margin:24px auto;padding:0 16px;color:#1f2328;}');
+    parts.push('h1{font-size:20px;border-bottom:1px solid #d0d7de;padding-bottom:8px;}');
+    parts.push('h2{font-size:16px;margin-top:24px;}');
+    parts.push('table{border-collapse:collapse;width:100%;margin:8px 0;}');
+    parts.push('th,td{border:1px solid #d0d7de;padding:6px 10px;text-align:left;}');
+    parts.push('th{background:#f6f8fa;}');
+    parts.push('code,pre{background:#f6f8fa;padding:1px 4px;border-radius:4px;font-size:12px;}');
+    parts.push('.tag{display:inline-block;padding:2px 8px;border-radius:9999px;font-size:11px;font-weight:600;}');
+    parts.push('.tag.ok{background:#dafbe1;color:#1a7f37;}');
+    parts.push('.tag.fail{background:#ffebe9;color:#cf222e;}');
+    parts.push('.tag.warn{background:#fff8c5;color:#9a6700;}');
+    parts.push('</style></head><body>');
+    parts.push(`<h1>Bundle validation — ${esc(bundle.id)}</h1>`);
+    parts.push(`<p><strong>Task:</strong> ${esc(bundle.task)}</p>`);
+    parts.push(`<p><strong>Result:</strong> <span class="tag ${validation.passed ? 'ok' : 'fail'}">${validation.passed ? 'PASSED' : 'FAILED'}</span></p>`);
+    parts.push(`<p>Started: ${esc(validation.startedAt)} — Finished: ${esc(validation.finishedAt)} — Warnings: ${validation.warnings}</p>`);
+    parts.push(`<h2>Gate matrix (${validation.commandsRun.length})</h2>`);
+    parts.push('<table><thead><tr><th>Gate</th><th>Result</th><th>Note</th></tr></thead><tbody>');
+    for (const c of validation.commandsRun) {
+        parts.push(`<tr><td><code>${esc(c.command)}</code></td><td><span class="tag ${c.passed ? 'ok' : 'fail'}">${c.passed ? 'OK' : 'FAIL'}</span></td><td>${esc(c.note ?? '')}</td></tr>`);
+    }
+    parts.push('</tbody></table>');
+    parts.push(`<h2>Plans (${bundle.plans.length})</h2>`);
+    parts.push('<table><thead><tr><th>Name</th><th>Template</th><th>Status</th><th>Targets</th></tr></thead><tbody>');
+    for (const p of bundle.plans) {
+        parts.push(`<tr><td><code>${esc(p.name)}</code></td><td>${esc(p.templateId)}</td><td>${esc(p.status)}</td><td>${esc(p.expectedTargets.join(', '))}</td></tr>`);
+    }
+    parts.push('</tbody></table>');
+    if (bundle.dependencies.length > 0) {
+        parts.push(`<h2>Dependencies (${bundle.dependencies.length})</h2><ul>`);
+        for (const d of bundle.dependencies)
+            parts.push(`<li><code>${esc(d.from)}</code> → <code>${esc(d.to)}</code> — ${esc(d.reason)}</li>`);
+        parts.push(`</ul>`);
+    }
+    if (options.baselineComparison) {
+        parts.push('<h2>Quality baseline comparison</h2>');
+        parts.push(`<pre>${esc(JSON.stringify(options.baselineComparison, null, 2))}</pre>`);
+    }
+    parts.push('<p><em>Generated by SharkCraft bundle validate v2.</em></p>');
+    parts.push('</body></html>');
+    return parts.join('\n') + '\n';
+}

package/dist/change-intent.d.ts

@@ -0,0 +1,36 @@
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export declare const CHANGE_INTENT_SCHEMA = "sharkcraft.change-intent/v1";
+export declare enum ChangeIntentKind {
+    Feature = "feature",
+    Bugfix = "bugfix",
+    Refactor = "refactor",
+    Test = "test",
+    Docs = "docs",
+    Migration = "migration",
+    Architecture = "architecture",
+    Policy = "policy",
+    Release = "release",
+    Unknown = "unknown"
+}
+export declare enum ChangeIntentConfidence {
+    Low = "low",
+    Medium = "medium",
+    High = "high"
+}
+export interface IChangeIntent {
+    schema: typeof CHANGE_INTENT_SCHEMA;
+    task: string;
+    kind: ChangeIntentKind;
+    domains: readonly string[];
+    likelyConstructs: readonly string[];
+    likelyTemplates: readonly string[];
+    likelyPipelines: readonly string[];
+    riskHints: readonly string[];
+    requiredHumanReview: boolean;
+    suggestedFirstCommand: string;
+    confidence: ChangeIntentConfidence;
+    reasons: readonly string[];
+}
+export declare function classifyChangeIntent(task: string, inspection: ISharkcraftInspection): Promise<IChangeIntent>;
+export declare function renderChangeIntentText(intent: IChangeIntent): string;
+//# sourceMappingURL=change-intent.d.ts.map

package/dist/change-intent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"change-intent.d.ts","sourceRoot":"","sources":["../src/change-intent.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,eAAO,MAAM,oBAAoB,gCAAgC,CAAC;AAElE,oBAAY,gBAAgB;IAC1B,OAAO,YAAY;IACnB,MAAM,WAAW;IACjB,QAAQ,aAAa;IACrB,IAAI,SAAS;IACb,IAAI,SAAS;IACb,SAAS,cAAc;IACvB,YAAY,iBAAiB;IAC7B,MAAM,WAAW;IACjB,OAAO,YAAY;IACnB,OAAO,YAAY;CACpB;AAED,oBAAY,sBAAsB;IAChC,GAAG,QAAQ;IACX,MAAM,WAAW;IACjB,IAAI,SAAS;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,OAAO,oBAAoB,CAAC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,gBAAgB,CAAC;IACvB,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,mBAAmB,EAAE,OAAO,CAAC;IAC7B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,UAAU,EAAE,sBAAsB,CAAC;IACnC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B;AA2ID,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,qBAAqB,GAChC,OAAO,CAAC,aAAa,CAAC,CAiFxB;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAsBpE"}

package/dist/change-intent.js

@@ -0,0 +1,259 @@
+/**
+ * Deterministic change-intent classifier.
+ *
+ * Given a task string + the loaded SharkCraft inspection, classify the
+ * intent (feature / bugfix / refactor / test / docs / migration /
+ * architecture / policy / release) plus likely constructs / templates /
+ * pipelines, risk hints, and a suggested first command.
+ *
+ * No AI. Heuristics only — verbs, known construct/template/pipeline
+ * names + tags, action-hint command surface, and the search index when
+ * available.
+ */
+import { listConstructs, loadConstructs } from "./construct-registry.js";
+export const CHANGE_INTENT_SCHEMA = 'sharkcraft.change-intent/v1';
+export var ChangeIntentKind;
+(function (ChangeIntentKind) {
+    ChangeIntentKind["Feature"] = "feature";
+    ChangeIntentKind["Bugfix"] = "bugfix";
+    ChangeIntentKind["Refactor"] = "refactor";
+    ChangeIntentKind["Test"] = "test";
+    ChangeIntentKind["Docs"] = "docs";
+    ChangeIntentKind["Migration"] = "migration";
+    ChangeIntentKind["Architecture"] = "architecture";
+    ChangeIntentKind["Policy"] = "policy";
+    ChangeIntentKind["Release"] = "release";
+    ChangeIntentKind["Unknown"] = "unknown";
+})(ChangeIntentKind || (ChangeIntentKind = {}));
+export var ChangeIntentConfidence;
+(function (ChangeIntentConfidence) {
+    ChangeIntentConfidence["Low"] = "low";
+    ChangeIntentConfidence["Medium"] = "medium";
+    ChangeIntentConfidence["High"] = "high";
+})(ChangeIntentConfidence || (ChangeIntentConfidence = {}));
+const MATCHERS = [
+    {
+        kind: ChangeIntentKind.Bugfix,
+        patterns: [/\bfix\b/i, /\bbug\b/i, /\bbroken\b/i, /\bcrash/i, /\bregress/i, /\berror\b/i, /\bdoesn'?t work/i],
+        riskHints: ['Reproduce the issue with a failing test before patching.'],
+    },
+    {
+        kind: ChangeIntentKind.Refactor,
+        patterns: [/\brefactor/i, /\brename\b/i, /\bextract\b/i, /\bcleanup\b/i, /\btidy\b/i, /\bsimplif/i],
+        riskHints: ['Keep behaviour identical; rely on the existing test suite.'],
+    },
+    {
+        kind: ChangeIntentKind.Test,
+        patterns: [/\btest\b/i, /\bspec\b/i, /\bcoverage\b/i, /\bsnapshot\b/i, /\bgolden\b/i],
+    },
+    {
+        kind: ChangeIntentKind.Docs,
+        patterns: [/\bdocs?\b/i, /\bdocument\b/i, /\breadme/i, /\bchangelog\b/i, /\bguide\b/i],
+    },
+    {
+        kind: ChangeIntentKind.Migration,
+        patterns: [/\bmigrat/i, /\bbackfill/i, /\bschema\b/i, /\bdata\b.*\bmove/i, /\bupgrade\b/i],
+        riskHints: ['Migrations require an explicit human-approval step.'],
+        requiresReview: true,
+    },
+    {
+        kind: ChangeIntentKind.Architecture,
+        patterns: [/\barchitecture/i, /\bboundar/i, /\blayer/i, /\bmodul/i, /\bpackag/i, /\bdepend/i, /\bimport\b/i],
+        riskHints: ['Surface boundary/layer changes via `shrk check boundaries` and `shrk drift`.'],
+        requiresReview: true,
+    },
+    {
+        kind: ChangeIntentKind.Policy,
+        patterns: [/\bpolicy\b/i, /\bcompliance/i, /\bgovernance/i, /\bownership\b/i, /\bsafety\b/i, /\baudit\b/i],
+        requiresReview: true,
+    },
+    {
+        kind: ChangeIntentKind.Release,
+        patterns: [/\brelease\b/i, /\btag\b/i, /\bpublish\b/i, /\bchangelog\b/i, /\balpha\b/i, /\bbeta\b/i, /\bsmoke\b/i],
+        riskHints: ['Release work must not auto-publish. Run preflight + readiness gates.'],
+        requiresReview: true,
+    },
+    {
+        kind: ChangeIntentKind.Feature,
+        patterns: [
+            /\badd\b/i,
+            /\bnew\b/i,
+            /\bcreate\b/i,
+            /\bbuild\b/i,
+            /\bimplement\b/i,
+            /\bsupport\b/i,
+            /\benable\b/i,
+            /\bplugin\b/i,
+            /\bcapability\b/i,
+        ],
+    },
+];
+const DOMAIN_KEYWORDS = new Map([
+    ['plugin', ['plugin', 'extension']],
+    ['mcp', ['mcp', 'tool', 'agent']],
+    ['cli', ['cli', 'command', 'subcommand', 'shrk']],
+    ['ci', ['ci', 'pipeline', 'workflow', 'github-actions', 'gitlab', 'bitbucket']],
+    ['docs', ['doc', 'docs', 'readme', 'guide']],
+    ['safety', ['safety', 'audit', 'policy', 'governance']],
+    ['boundaries', ['boundary', 'boundaries', 'layer', 'import-graph']],
+    ['release', ['release', 'tag', 'publish', 'alpha', 'beta', 'smoke', 'preflight']],
+    ['report', ['report', 'site', 'dashboard']],
+    ['pack', ['pack', 'manifest', 'sign', 'plugin-api']],
+    ['onboard', ['onboard', 'adopt', 'drafts']],
+    ['intelligence', ['graph', 'map', 'intelligence']],
+    ['orchestrate', ['orchestrate', 'plan', 'session', 'brief', 'handoff']],
+    ['intent', ['intent', 'classify']],
+]);
+const SUGGESTED_COMMAND = new Map([
+    [ChangeIntentKind.Feature, 'shrk brief "<task>"'],
+    [ChangeIntentKind.Bugfix, 'shrk impact --since main'],
+    [ChangeIntentKind.Refactor, 'shrk check boundaries --json'],
+    [ChangeIntentKind.Test, 'shrk tests missing --since main'],
+    [ChangeIntentKind.Docs, 'shrk docs check'],
+    [ChangeIntentKind.Migration, 'shrk brief "<task>" && shrk orchestrate "<task>" --mode conservative'],
+    [ChangeIntentKind.Architecture, 'shrk architecture map'],
+    [ChangeIntentKind.Policy, 'shrk policy run --explain-overrides'],
+    [ChangeIntentKind.Release, 'shrk release readiness --strict'],
+    [ChangeIntentKind.Unknown, 'shrk start-here'],
+]);
+function lc(s) {
+    return s.toLowerCase();
+}
+function detectDomains(task) {
+    const lower = lc(task);
+    const out = [];
+    for (const [domain, keywords] of DOMAIN_KEYWORDS) {
+        for (const kw of keywords) {
+            if (lower.includes(kw)) {
+                out.push(domain);
+                break;
+            }
+        }
+    }
+    return [...new Set(out)];
+}
+function matchKind(task) {
+    let best = {
+        kind: ChangeIntentKind.Unknown,
+        riskHints: [],
+        requiresReview: false,
+        matchedPatterns: 0,
+    };
+    for (const m of MATCHERS) {
+        let count = 0;
+        for (const p of m.patterns) {
+            if (p.test(task))
+                count++;
+        }
+        if (count > best.matchedPatterns) {
+            best = {
+                kind: m.kind,
+                riskHints: m.riskHints ? [...m.riskHints] : [],
+                requiresReview: m.requiresReview === true,
+                matchedPatterns: count,
+            };
+        }
+    }
+    return best;
+}
+export async function classifyChangeIntent(task, inspection) {
+    await loadConstructs(inspection);
+    const trimmed = task.trim();
+    if (trimmed.length === 0) {
+        return {
+            schema: CHANGE_INTENT_SCHEMA,
+            task: trimmed,
+            kind: ChangeIntentKind.Unknown,
+            domains: [],
+            likelyConstructs: [],
+            likelyTemplates: [],
+            likelyPipelines: [],
+            riskHints: ['Empty task — provide a one-sentence description.'],
+            requiredHumanReview: true,
+            suggestedFirstCommand: 'shrk start-here',
+            confidence: ChangeIntentConfidence.Low,
+            reasons: ['Empty task string.'],
+        };
+    }
+    const { kind, riskHints, requiresReview, matchedPatterns } = matchKind(trimmed);
+    const domains = detectDomains(trimmed);
+    // Likely constructs: any construct id whose tokens appear in the task.
+    const constructs = listConstructs(inspection).map((c) => c.id);
+    const likelyConstructs = constructs.filter((id) => {
+        const tokens = id.split(/[.\-_/]/).filter((t) => t.length >= 3);
+        return tokens.some((t) => lc(trimmed).includes(lc(t)));
+    });
+    // Likely templates / pipelines: by id token match.
+    const templates = inspection.templates.map((t) => t.id);
+    const likelyTemplates = templates.filter((id) => {
+        const tokens = id.split(/[.\-_/]/).filter((t) => t.length >= 3);
+        return tokens.some((t) => lc(trimmed).includes(lc(t)));
+    });
+    const pipelines = inspection.pipelines.map((p) => p.id);
+    const likelyPipelines = pipelines.filter((id) => {
+        const tokens = id.split(/[.\-_/]/).filter((t) => t.length >= 3);
+        return tokens.some((t) => lc(trimmed).includes(lc(t)));
+    });
+    const reasons = [];
+    if (matchedPatterns > 0) {
+        reasons.push(`Matched ${matchedPatterns} pattern(s) for kind "${kind}".`);
+    }
+    else {
+        reasons.push('No strong verb match; defaulted by domain hints.');
+    }
+    if (domains.length > 0)
+        reasons.push(`Domains: ${domains.join(', ')}.`);
+    if (likelyConstructs.length > 0)
+        reasons.push(`Construct id tokens matched: ${likelyConstructs.slice(0, 4).join(', ')}.`);
+    let confidence = ChangeIntentConfidence.Low;
+    const signals = matchedPatterns + domains.length + (likelyConstructs.length > 0 ? 1 : 0) + (likelyTemplates.length > 0 ? 1 : 0);
+    if (signals >= 4)
+        confidence = ChangeIntentConfidence.High;
+    else if (signals >= 2)
+        confidence = ChangeIntentConfidence.Medium;
+    const requiredHumanReview = requiresReview ||
+        kind === ChangeIntentKind.Architecture ||
+        kind === ChangeIntentKind.Policy ||
+        kind === ChangeIntentKind.Release ||
+        kind === ChangeIntentKind.Migration;
+    const suggestedFirstCommand = SUGGESTED_COMMAND.get(kind) ?? 'shrk start-here';
+    return {
+        schema: CHANGE_INTENT_SCHEMA,
+        task: trimmed,
+        kind,
+        domains,
+        likelyConstructs,
+        likelyTemplates,
+        likelyPipelines,
+        riskHints,
+        requiredHumanReview,
+        suggestedFirstCommand,
+        confidence,
+        reasons,
+    };
+}
+export function renderChangeIntentText(intent) {
+    const lines = [];
+    lines.push('=== Change intent ===');
+    lines.push(`  task           ${intent.task}`);
+    lines.push(`  kind           ${intent.kind}`);
+    lines.push(`  confidence     ${intent.confidence}`);
+    lines.push(`  domains        ${intent.domains.length === 0 ? '(none)' : intent.domains.join(', ')}`);
+    lines.push(`  review needed  ${intent.requiredHumanReview ? 'yes' : 'no'}`);
+    lines.push(`  first command  ${intent.suggestedFirstCommand}`);
+    if (intent.likelyConstructs.length > 0)
+        lines.push(`  constructs     ${intent.likelyConstructs.slice(0, 8).join(', ')}`);
+    if (intent.likelyTemplates.length > 0)
+        lines.push(`  templates      ${intent.likelyTemplates.slice(0, 8).join(', ')}`);
+    if (intent.likelyPipelines.length > 0)
+        lines.push(`  pipelines      ${intent.likelyPipelines.slice(0, 8).join(', ')}`);
+    if (intent.riskHints.length > 0) {
+        lines.push('Risk hints:');
+        for (const r of intent.riskHints)
+            lines.push(`  • ${r}`);
+    }
+    lines.push('Reasons:');
+    for (const r of intent.reasons)
+        lines.push(`  • ${r}`);
+    return lines.join('\n') + '\n';
+}