@shrkcrft/inspector 0.1.0-alpha.2

package/dist/symbol-index.js

@@ -0,0 +1,483 @@
+/**
+ * Lightweight AST-backed symbol index.
+ *
+ * Uses the TypeScript compiler API (single-file `createSourceFile`, no
+ * full program type-checking) to identify exported / local declarations
+ * and re-exports in a TS / TSX / JS / JSX file. Falls back to a text
+ * scan when the file cannot be parsed.
+ *
+ * The index is intentionally per-file (no whole-program graph). Callers
+ * that need cross-file resolution stitch results together themselves.
+ *
+ * Schema: sharkcraft.symbol-index/v1
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import * as ts from 'typescript';
+export const SYMBOL_INDEX_SCHEMA = 'sharkcraft.symbol-index/v1';
+export var SymbolDeclarationKind;
+(function (SymbolDeclarationKind) {
+    SymbolDeclarationKind["Class"] = "class";
+    SymbolDeclarationKind["Function"] = "function";
+    SymbolDeclarationKind["Interface"] = "interface";
+    SymbolDeclarationKind["TypeAlias"] = "type-alias";
+    SymbolDeclarationKind["Enum"] = "enum";
+    SymbolDeclarationKind["Const"] = "const";
+    SymbolDeclarationKind["Let"] = "let";
+    SymbolDeclarationKind["Var"] = "var";
+    SymbolDeclarationKind["Module"] = "module";
+    SymbolDeclarationKind["Namespace"] = "namespace";
+    SymbolDeclarationKind["Unknown"] = "unknown";
+})(SymbolDeclarationKind || (SymbolDeclarationKind = {}));
+export var SymbolVisibility;
+(function (SymbolVisibility) {
+    SymbolVisibility["Export"] = "export";
+    SymbolVisibility["Local"] = "local";
+    SymbolVisibility["ReExport"] = "re-export";
+    SymbolVisibility["Default"] = "default";
+})(SymbolVisibility || (SymbolVisibility = {}));
+export var SymbolResolution;
+(function (SymbolResolution) {
+    SymbolResolution["ExactExport"] = "exact-export";
+    SymbolResolution["ExactLocal"] = "exact-local";
+    SymbolResolution["ExactReExport"] = "exact-reexport";
+    SymbolResolution["ProbableText"] = "probable-text";
+    SymbolResolution["Missing"] = "missing";
+    SymbolResolution["Unknown"] = "unknown";
+})(SymbolResolution || (SymbolResolution = {}));
+function pickKindFromNode(node) {
+    if (ts.isClassDeclaration(node))
+        return SymbolDeclarationKind.Class;
+    if (ts.isFunctionDeclaration(node))
+        return SymbolDeclarationKind.Function;
+    if (ts.isInterfaceDeclaration(node))
+        return SymbolDeclarationKind.Interface;
+    if (ts.isTypeAliasDeclaration(node))
+        return SymbolDeclarationKind.TypeAlias;
+    if (ts.isEnumDeclaration(node))
+        return SymbolDeclarationKind.Enum;
+    if (ts.isVariableStatement(node)) {
+        const flags = node.declarationList.flags;
+        if (flags & ts.NodeFlags.Const)
+            return SymbolDeclarationKind.Const;
+        if (flags & ts.NodeFlags.Let)
+            return SymbolDeclarationKind.Let;
+        return SymbolDeclarationKind.Var;
+    }
+    if (ts.isModuleDeclaration(node)) {
+        if (node.flags & ts.NodeFlags.Namespace)
+            return SymbolDeclarationKind.Namespace;
+        return SymbolDeclarationKind.Module;
+    }
+    return SymbolDeclarationKind.Unknown;
+}
+function isExported(node) {
+    if (!ts.canHaveModifiers(node))
+        return false;
+    const mods = ts.getModifiers(node);
+    return !!mods && mods.some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
+}
+function isDefault(node) {
+    if (!ts.canHaveModifiers(node))
+        return false;
+    const mods = ts.getModifiers(node);
+    return !!mods && mods.some((m) => m.kind === ts.SyntaxKind.DefaultKeyword);
+}
+function lineOf(sf, node) {
+    return sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
+}
+export function buildSymbolIndex(fileAbsPath, content, options = {}) {
+    const filePath = options.virtualPath ?? fileAbsPath;
+    let text;
+    if (content !== undefined) {
+        text = content;
+    }
+    else {
+        if (!existsSync(fileAbsPath)) {
+            return {
+                schema: SYMBOL_INDEX_SCHEMA,
+                file: filePath,
+                parsed: false,
+                parseError: 'file not found',
+                exports: [],
+                locals: [],
+                reExports: [],
+                hasDefaultExport: false,
+            };
+        }
+        try {
+            text = readFileSync(fileAbsPath, 'utf8');
+        }
+        catch (e) {
+            return {
+                schema: SYMBOL_INDEX_SCHEMA,
+                file: filePath,
+                parsed: false,
+                parseError: e.message,
+                exports: [],
+                locals: [],
+                reExports: [],
+                hasDefaultExport: false,
+            };
+        }
+    }
+    const ext = nodePath.extname(filePath).toLowerCase();
+    const scriptKind = pickScriptKind(ext);
+    let sf;
+    try {
+        sf = ts.createSourceFile(filePath, text, ts.ScriptTarget.Latest, true, scriptKind);
+    }
+    catch (e) {
+        return {
+            schema: SYMBOL_INDEX_SCHEMA,
+            file: filePath,
+            parsed: false,
+            parseError: e.message,
+            exports: [],
+            locals: [],
+            reExports: [],
+            hasDefaultExport: false,
+        };
+    }
+    const exportsList = [];
+    const localsList = [];
+    const reExportsList = [];
+    let hasDefaultExport = false;
+    let defaultExportName;
+    for (const stmt of sf.statements) {
+        // export { foo, bar } from "./mod"  /  export * from "./mod"
+        if (ts.isExportDeclaration(stmt)) {
+            const fromSpec = stmt.moduleSpecifier && ts.isStringLiteral(stmt.moduleSpecifier)
+                ? stmt.moduleSpecifier.text
+                : '';
+            const star = !stmt.exportClause;
+            if (star && fromSpec) {
+                reExportsList.push({
+                    name: '*',
+                    from: fromSpec,
+                    star: true,
+                    line: lineOf(sf, stmt),
+                });
+                continue;
+            }
+            if (stmt.exportClause && ts.isNamedExports(stmt.exportClause)) {
+                for (const spec of stmt.exportClause.elements) {
+                    const name = spec.name.text;
+                    if (fromSpec) {
+                        reExportsList.push({
+                            name,
+                            from: fromSpec,
+                            star: false,
+                            line: lineOf(sf, spec),
+                        });
+                    }
+                    else {
+                        // `export { foo }` — local re-export of a name imported above.
+                        exportsList.push({
+                            name,
+                            kind: SymbolDeclarationKind.Unknown,
+                            visibility: SymbolVisibility.Export,
+                            line: lineOf(sf, spec),
+                        });
+                    }
+                }
+                continue;
+            }
+        }
+        // export default …
+        if (ts.isExportAssignment(stmt)) {
+            hasDefaultExport = true;
+            if (ts.isIdentifier(stmt.expression)) {
+                defaultExportName = stmt.expression.text;
+            }
+            continue;
+        }
+        // export default function/class …
+        if ((ts.isFunctionDeclaration(stmt) || ts.isClassDeclaration(stmt)) &&
+            isDefault(stmt)) {
+            hasDefaultExport = true;
+            const name = stmt.name?.text;
+            if (name)
+                defaultExportName = name;
+            // Also surface the name (if any) in exportsList for findability.
+            if (name) {
+                exportsList.push({
+                    name,
+                    kind: pickKindFromNode(stmt),
+                    visibility: SymbolVisibility.Default,
+                    line: lineOf(sf, stmt),
+                });
+            }
+            continue;
+        }
+        const exported = isExported(stmt);
+        // export const / let / var …
+        if (ts.isVariableStatement(stmt)) {
+            const kind = pickKindFromNode(stmt);
+            for (const d of stmt.declarationList.declarations) {
+                if (!ts.isIdentifier(d.name))
+                    continue;
+                const entry = {
+                    name: d.name.text,
+                    kind,
+                    visibility: exported ? SymbolVisibility.Export : SymbolVisibility.Local,
+                    line: lineOf(sf, d),
+                };
+                (exported ? exportsList : localsList).push(entry);
+            }
+            continue;
+        }
+        if (ts.isClassDeclaration(stmt) ||
+            ts.isFunctionDeclaration(stmt) ||
+            ts.isInterfaceDeclaration(stmt) ||
+            ts.isTypeAliasDeclaration(stmt) ||
+            ts.isEnumDeclaration(stmt)) {
+            const name = stmt.name?.text;
+            if (!name)
+                continue;
+            const entry = {
+                name,
+                kind: pickKindFromNode(stmt),
+                visibility: exported ? SymbolVisibility.Export : SymbolVisibility.Local,
+                line: lineOf(sf, stmt),
+            };
+            (exported ? exportsList : localsList).push(entry);
+            continue;
+        }
+        if (ts.isModuleDeclaration(stmt) && stmt.name && ts.isIdentifier(stmt.name)) {
+            const entry = {
+                name: stmt.name.text,
+                kind: pickKindFromNode(stmt),
+                visibility: exported ? SymbolVisibility.Export : SymbolVisibility.Local,
+                line: lineOf(sf, stmt),
+            };
+            (exported ? exportsList : localsList).push(entry);
+        }
+    }
+    return {
+        schema: SYMBOL_INDEX_SCHEMA,
+        file: filePath,
+        parsed: true,
+        exports: exportsList,
+        locals: localsList,
+        reExports: reExportsList,
+        hasDefaultExport,
+        ...(defaultExportName ? { defaultExportName } : {}),
+    };
+}
+function pickScriptKind(ext) {
+    switch (ext) {
+        case '.tsx':
+            return ts.ScriptKind.TSX;
+        case '.jsx':
+            return ts.ScriptKind.JSX;
+        case '.js':
+        case '.mjs':
+        case '.cjs':
+            return ts.ScriptKind.JS;
+        default:
+            return ts.ScriptKind.TS;
+    }
+}
+/**
+ * Resolve a symbol within a single file using the AST index. Returns the
+ * resolution kind + a small explanation. No cross-file traversal.
+ */
+export function resolveSymbolInFile(fileAbsPath, symbol) {
+    if (!symbol) {
+        return { resolution: SymbolResolution.Unknown, message: 'No symbol provided.' };
+    }
+    const idx = buildSymbolIndex(fileAbsPath);
+    if (!idx.parsed) {
+        // Text-scan fallback.
+        try {
+            const text = readFileSync(fileAbsPath, 'utf8');
+            if (text.includes(symbol)) {
+                return {
+                    resolution: SymbolResolution.ProbableText,
+                    message: `\`${symbol}\` appears in the file text but the AST could not be parsed.`,
+                };
+            }
+            return { resolution: SymbolResolution.Missing, message: `\`${symbol}\` not found.` };
+        }
+        catch {
+            return { resolution: SymbolResolution.Unknown, message: 'Could not read file.' };
+        }
+    }
+    const exp = idx.exports.find((e) => e.name === symbol);
+    if (exp) {
+        return {
+            resolution: SymbolResolution.ExactExport,
+            message: `Exact exported declaration of \`${symbol}\` (${exp.kind}) at line ${exp.line}.`,
+            entry: exp,
+        };
+    }
+    const local = idx.locals.find((e) => e.name === symbol);
+    if (local) {
+        return {
+            resolution: SymbolResolution.ExactLocal,
+            message: `Local (non-exported) declaration of \`${symbol}\` (${local.kind}) at line ${local.line}.`,
+            entry: local,
+        };
+    }
+    const re = idx.reExports.find((r) => r.name === symbol || (r.star && r.from.length > 0));
+    if (re) {
+        return {
+            resolution: SymbolResolution.ExactReExport,
+            message: `Re-exported via \`export${re.star ? ' *' : ` { ${symbol} }`} from "${re.from}"\` at line ${re.line}.`,
+        };
+    }
+    return {
+        resolution: SymbolResolution.Missing,
+        message: `Symbol \`${symbol}\` not declared or re-exported in this file.`,
+    };
+}
+// ── Project-wide symbol resolution ──────────────────────────────────────
+import { readdirSync, statSync } from 'node:fs';
+const DEFAULT_SKIP_DIRS = new Set([
+    'node_modules',
+    'dist',
+    'build',
+    '.git',
+    '.sharkcraft',
+    'coverage',
+    'target',
+    'out',
+]);
+const TS_EXTS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs']);
+function walk(dir, accept, out) {
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    for (const name of names) {
+        if (DEFAULT_SKIP_DIRS.has(name))
+            continue;
+        const full = nodePath.join(dir, name);
+        let stat;
+        try {
+            stat = statSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (stat.isDirectory())
+            walk(full, accept, out);
+        else if (stat.isFile() && accept(full))
+            out.push(full);
+    }
+}
+export function findSymbolInProject(projectRoot, symbol, options = {}) {
+    const language = options.language ?? 'auto';
+    const accept = (file) => {
+        const ext = nodePath.extname(file).toLowerCase();
+        if (language === 'auto' || language === 'typescript')
+            return TS_EXTS.has(ext);
+        if (language === 'java')
+            return ext === '.java';
+        if (language === 'csharp')
+            return ext === '.cs';
+        if (language === 'python')
+            return ext === '.py';
+        if (language === 'go')
+            return ext === '.go';
+        if (language === 'rust')
+            return ext === '.rs';
+        return false;
+    };
+    const files = [];
+    walk(projectRoot, accept, files);
+    const limited = files.slice(0, options.maxFiles ?? 4000);
+    const exactMatches = [];
+    const textMatches = [];
+    const diagnostics = [];
+    for (const f of limited) {
+        let text;
+        try {
+            text = readFileSync(f, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        if (!text.includes(symbol))
+            continue;
+        const rel = nodePath.relative(projectRoot, f);
+        if (TS_EXTS.has(nodePath.extname(f).toLowerCase())) {
+            const idx = buildSymbolIndex(f);
+            if (!idx.parsed) {
+                textMatches.push({
+                    file: f,
+                    relativePath: rel,
+                    resolution: SymbolResolution.ProbableText,
+                    message: idx.parseError ?? 'parse error',
+                });
+                continue;
+            }
+            const exp = idx.exports.find((e) => e.name === symbol);
+            if (exp) {
+                exactMatches.push({
+                    file: f,
+                    relativePath: rel,
+                    resolution: SymbolResolution.ExactExport,
+                    message: `exported ${exp.kind} at line ${exp.line}`,
+                    kind: exp.kind,
+                    visibility: exp.visibility,
+                    line: exp.line,
+                });
+                continue;
+            }
+            const local = idx.locals.find((e) => e.name === symbol);
+            if (local) {
+                exactMatches.push({
+                    file: f,
+                    relativePath: rel,
+                    resolution: SymbolResolution.ExactLocal,
+                    message: `local ${local.kind} at line ${local.line} — not exported`,
+                    kind: local.kind,
+                    visibility: local.visibility,
+                    line: local.line,
+                });
+                continue;
+            }
+            textMatches.push({
+                file: f,
+                relativePath: rel,
+                resolution: SymbolResolution.ProbableText,
+                message: 'token appears in file text',
+            });
+        }
+        else {
+            // Non-TS: text-only.
+            textMatches.push({
+                file: f,
+                relativePath: rel,
+                resolution: SymbolResolution.ProbableText,
+                message: 'token appears in file text (no AST scanner for this language)',
+            });
+        }
+    }
+    if (files.length > limited.length) {
+        diagnostics.push(`scanned the first ${limited.length} files (${files.length - limited.length} skipped — bump --max-files to increase)`);
+    }
+    // Primary file: only if exactly one exported declaration.
+    const exportedMatches = exactMatches.filter((m) => m.resolution === SymbolResolution.ExactExport);
+    let primaryFile;
+    if (exportedMatches.length === 1) {
+        primaryFile = exportedMatches[0].relativePath;
+    }
+    else if (exportedMatches.length === 0 && exactMatches.length === 1) {
+        primaryFile = exactMatches[0].relativePath;
+    }
+    return {
+        schema: 'sharkcraft.symbol-impact/v1',
+        symbol,
+        language,
+        exactMatches,
+        textMatches,
+        ...(primaryFile ? { primaryFile } : {}),
+        diagnostics,
+    };
+}

package/dist/task-decompose.d.ts

@@ -0,0 +1,38 @@
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export declare const TASK_DECOMPOSE_SCHEMA = "sharkcraft.task-decomposition/v1";
+export declare enum TaskVerb {
+    Create = "create",
+    Add = "add",
+    Refactor = "refactor",
+    Fix = "fix",
+    Test = "test",
+    Document = "document",
+    Review = "review",
+    Migrate = "migrate",
+    Remove = "remove",
+    Unknown = "unknown"
+}
+export interface ITaskSubtask {
+    id: string;
+    title: string;
+    reason: string;
+    relatedTemplateIds: readonly string[];
+    relatedPipelineIds: readonly string[];
+    riskLevel: 'low' | 'medium' | 'high';
+}
+export interface ITaskDecomposition {
+    schema: typeof TASK_DECOMPOSE_SCHEMA;
+    task: string;
+    verb: TaskVerb;
+    domainHints: readonly string[];
+    subtasks: readonly ITaskSubtask[];
+    suggestedTemplateIds: readonly string[];
+    suggestedPipelineIds: readonly string[];
+    requiredVariables: readonly string[];
+    riskAreas: readonly string[];
+    validationSuggestions: readonly string[];
+    recommendedOrder: readonly string[];
+}
+export declare function detectVerb(task: string): TaskVerb;
+export declare function decomposeTask(inspection: ISharkcraftInspection, task: string): ITaskDecomposition;
+//# sourceMappingURL=task-decompose.d.ts.map

package/dist/task-decompose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-decompose.d.ts","sourceRoot":"","sources":["../src/task-decompose.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAGvE,eAAO,MAAM,qBAAqB,qCAAqC,CAAC;AAExE,oBAAY,QAAQ;IAClB,MAAM,WAAW;IACjB,GAAG,QAAQ;IACX,QAAQ,aAAa;IACrB,GAAG,QAAQ;IACX,IAAI,SAAS;IACb,QAAQ,aAAa;IACrB,MAAM,WAAW;IACjB,OAAO,YAAY;IACnB,MAAM,WAAW;IACjB,OAAO,YAAY;CACpB;AAkCD,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,SAAS,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;CACtC;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,OAAO,qBAAqB,CAAC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,CAAC;IACf,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;IAClC,oBAAoB,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,oBAAoB,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,qBAAqB,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAMjD;AAOD,wBAAgB,aAAa,CAC3B,UAAU,EAAE,qBAAqB,EACjC,IAAI,EAAE,MAAM,GACX,kBAAkB,CAqFpB"}

package/dist/task-decompose.js

@@ -0,0 +1,154 @@
+import { rankAll } from "./task-ranker.js";
+export const TASK_DECOMPOSE_SCHEMA = 'sharkcraft.task-decomposition/v1';
+export var TaskVerb;
+(function (TaskVerb) {
+    TaskVerb["Create"] = "create";
+    TaskVerb["Add"] = "add";
+    TaskVerb["Refactor"] = "refactor";
+    TaskVerb["Fix"] = "fix";
+    TaskVerb["Test"] = "test";
+    TaskVerb["Document"] = "document";
+    TaskVerb["Review"] = "review";
+    TaskVerb["Migrate"] = "migrate";
+    TaskVerb["Remove"] = "remove";
+    TaskVerb["Unknown"] = "unknown";
+})(TaskVerb || (TaskVerb = {}));
+const VERB_PATTERNS = [
+    { verb: TaskVerb.Create, words: ['create', 'generate', 'scaffold', 'build', 'implement', 'new'] },
+    { verb: TaskVerb.Add, words: ['add', 'introduce', 'extend', 'expose'] },
+    { verb: TaskVerb.Refactor, words: ['refactor', 'rewrite', 'rename', 'extract'] },
+    { verb: TaskVerb.Fix, words: ['fix', 'patch', 'repair', 'bug'] },
+    { verb: TaskVerb.Test, words: ['test', 'spec', 'coverage'] },
+    { verb: TaskVerb.Document, words: ['document', 'doc', 'readme'] },
+    { verb: TaskVerb.Review, words: ['review', 'audit'] },
+    { verb: TaskVerb.Migrate, words: ['migrate', 'upgrade', 'port'] },
+    { verb: TaskVerb.Remove, words: ['remove', 'delete', 'drop'] },
+];
+const DOMAIN_HINTS = [
+    'plugin',
+    'policy',
+    'capability',
+    'adapter',
+    'service',
+    'component',
+    'api',
+    'table',
+    'auth',
+    'route',
+    'controller',
+    'middleware',
+    'queue',
+    'job',
+    'worker',
+    'cli',
+    'mcp',
+];
+export function detectVerb(task) {
+    const lower = task.toLowerCase();
+    for (const { verb, words } of VERB_PATTERNS) {
+        if (words.some((w) => new RegExp(`\\b${w}`).test(lower)))
+            return verb;
+    }
+    return TaskVerb.Unknown;
+}
+function detectDomainHints(task) {
+    const lower = task.toLowerCase();
+    return DOMAIN_HINTS.filter((d) => lower.includes(d));
+}
+export function decomposeTask(inspection, task) {
+    const verb = detectVerb(task);
+    const domainHints = detectDomainHints(task);
+    const ranking = rankAll(inspection, task, 6);
+    const subtasks = [];
+    if (verb === TaskVerb.Create || verb === TaskVerb.Add) {
+        if (domainHints.includes('plugin') || domainHints.includes('capability')) {
+            subtasks.push(stepFor('contract', 'Create plugin contract / interface', ranking, 'low'));
+            subtasks.push(stepFor('cross-impl', 'Create cross / shared implementation', ranking, 'medium'));
+            subtasks.push(stepFor('defaults', 'Wire defaults / registration', ranking, 'medium'));
+        }
+        else if (domainHints.includes('adapter')) {
+            subtasks.push(stepFor('adapter-iface', 'Define adapter interface', ranking, 'low'));
+            subtasks.push(stepFor('adapter-impl', 'Implement adapter', ranking, 'medium'));
+        }
+        else if (domainHints.includes('service') || domainHints.includes('controller')) {
+            subtasks.push(stepFor('service', 'Implement service', ranking, 'medium'));
+            subtasks.push(stepFor('service-tests', 'Add unit tests', ranking, 'low'));
+        }
+        else if (domainHints.includes('component') || domainHints.includes('cli')) {
+            subtasks.push(stepFor('feature', 'Implement primary unit', ranking, 'medium'));
+        }
+        else {
+            subtasks.push(stepFor('feature', 'Implement primary unit', ranking, 'medium'));
+        }
+    }
+    else if (verb === TaskVerb.Refactor || verb === TaskVerb.Migrate) {
+        subtasks.push(stepFor('analyze', 'Map current behavior', ranking, 'low'));
+        subtasks.push(stepFor('plan', 'Plan the refactor / migration steps', ranking, 'medium'));
+        subtasks.push(stepFor('apply', 'Apply changes', ranking, 'high'));
+    }
+    else if (verb === TaskVerb.Fix) {
+        subtasks.push(stepFor('reproduce', 'Reproduce the bug locally', ranking, 'low'));
+        subtasks.push(stepFor('fix', 'Apply the fix', ranking, 'medium'));
+        subtasks.push(stepFor('regression', 'Add regression test', ranking, 'low'));
+    }
+    else if (verb === TaskVerb.Test) {
+        subtasks.push(stepFor('cases', 'Enumerate cases', ranking, 'low'));
+        subtasks.push(stepFor('spec', 'Write tests', ranking, 'low'));
+    }
+    else if (verb === TaskVerb.Remove) {
+        subtasks.push(stepFor('locate', 'Locate all references', ranking, 'low'));
+        subtasks.push(stepFor('delete', 'Delete', ranking, 'high'));
+    }
+    else {
+        subtasks.push(stepFor('explore', 'Explore + plan', ranking, 'low'));
+    }
+    subtasks.push({
+        id: `${subtasks.length + 1}-validate`,
+        title: 'Validate (boundaries, types, tests)',
+        reason: 'Required by policy: changes must pass boundary check and tests.',
+        relatedTemplateIds: [],
+        relatedPipelineIds: [],
+        riskLevel: 'low',
+    });
+    const suggestedTemplateIds = ranking.templates.slice(0, 5).map((t) => t.item.id);
+    const suggestedPipelineIds = ranking.pipelines.slice(0, 3).map((p) => p.item.id);
+    const requiredVariables = uniqueStrings(ranking.templates
+        .slice(0, 5)
+        .flatMap((t) => (t.item.variables ?? []).filter((v) => v.required).map((v) => v.name)));
+    const riskAreas = uniqueStrings(ranking.paths.slice(0, 5).map((p) => p.item.id));
+    const validationSuggestions = uniqueStrings([
+        'shrk doctor',
+        'shrk check boundaries',
+        'bun x tsc -p tsconfig.base.json --noEmit',
+        'bun test',
+    ]);
+    const recommendedOrder = subtasks.map((s) => s.id);
+    return {
+        schema: TASK_DECOMPOSE_SCHEMA,
+        task,
+        verb,
+        domainHints,
+        subtasks,
+        suggestedTemplateIds,
+        suggestedPipelineIds,
+        requiredVariables,
+        riskAreas,
+        validationSuggestions,
+        recommendedOrder,
+    };
+}
+function stepFor(slug, title, ranking, risk) {
+    const tpl = ranking.templates[0]?.item.id;
+    const pipe = ranking.pipelines[0]?.item.id;
+    return {
+        id: `${slug}`,
+        title,
+        reason: 'derived from verb + domain hints',
+        relatedTemplateIds: tpl ? [tpl] : [],
+        relatedPipelineIds: pipe ? [pipe] : [],
+        riskLevel: risk,
+    };
+}
+function uniqueStrings(xs) {
+    return [...new Set(xs)];
+}