@planu/cli 0.63.7 → 0.64.0

package/dist/engine/spec-decomposer/analyzer.js

@@ -0,0 +1,263 @@
+// engine/spec-decomposer/analyzer.ts — Analyze spec content into work units (SPEC-157)
+// Reads spec.md acceptance criteria and technical.md file lists, then groups
+// criteria into independent work units suitable for parallel agent execution.
+import { readFile } from 'node:fs/promises';
+import { extractAcceptanceCriteria } from '../shared/ac-extractor.js';
+// ---------------------------------------------------------------------------
+// Criterion classification
+// ---------------------------------------------------------------------------
+/** Keywords that suggest architecture/planning work → opus. */
+const OPUS_KEYWORDS = [
+    'architect',
+    'design',
+    'schema',
+    'interface',
+    'type',
+    'pattern',
+    'structure',
+    'strategy',
+    'dependency',
+    'integration',
+];
+/** Keywords that suggest read-only or search work → haiku. */
+const HAIKU_KEYWORDS = [
+    'list',
+    'read',
+    'search',
+    'find',
+    'query',
+    'display',
+    'show',
+    'report',
+    'summary',
+    'status',
+];
+function classifyModel(text) {
+    const lower = text.toLowerCase();
+    if (OPUS_KEYWORDS.some((kw) => lower.includes(kw))) {
+        return 'opus';
+    }
+    if (HAIKU_KEYWORDS.some((kw) => lower.includes(kw))) {
+        return 'haiku';
+    }
+    return 'sonnet';
+}
+// ---------------------------------------------------------------------------
+// File path extraction helpers
+// ---------------------------------------------------------------------------
+const FILE_PATTERN = /`((?:src|tests)\/[^`]+\.(?:ts|js|tsx|jsx))`/g;
+const MD_FILE_PATTERN = /^\s*[-*]\s+`?((?:src|tests)\/[\w./-]+\.(?:ts|js|tsx|jsx))`?/gm;
+const SECTION_PATTERN = /^#{2,4}\s+(.+)$/gm;
+function extractFilesFromText(text) {
+    const files = new Set();
+    let match;
+    const pattern1 = new RegExp(FILE_PATTERN.source, 'g');
+    while ((match = pattern1.exec(text)) !== null) {
+        if (match[1]) {
+            files.add(match[1]);
+        }
+    }
+    const pattern2 = new RegExp(MD_FILE_PATTERN.source, 'gm');
+    while ((match = pattern2.exec(text)) !== null) {
+        if (match[1]) {
+            files.add(match[1]);
+        }
+    }
+    return [...files];
+}
+// ---------------------------------------------------------------------------
+// Spec content parsers
+// ---------------------------------------------------------------------------
+/** Extract acceptance criteria lines from spec.md content. */
+export function extractCriteriaFromContent(content) {
+    return extractAcceptanceCriteria(content);
+}
+/** Extract all file paths mentioned in technical.md content. */
+export function extractFilesFromTechnical(content) {
+    return extractFilesFromText(content);
+}
+// ---------------------------------------------------------------------------
+// Work unit grouping heuristics
+// ---------------------------------------------------------------------------
+/**
+ * Categories used to cluster criteria into work units.
+ * Each entry has a label and keywords that identify it.
+ */
+const CATEGORY_RULES = [
+    {
+        id: 'types',
+        title: 'Types and interfaces',
+        keywords: ['type', 'interface', 'schema', 'model', 'struct'],
+    },
+    {
+        id: 'engine',
+        title: 'Engine / business logic',
+        keywords: ['engine', 'logic', 'algorithm', 'process', 'compute', 'analyze', 'detect'],
+    },
+    {
+        id: 'storage',
+        title: 'Storage / persistence',
+        keywords: ['storage', 'store', 'persist', 'save', 'load', 'database', 'file', 'read', 'write'],
+    },
+    {
+        id: 'tool',
+        title: 'MCP tool / handler',
+        keywords: ['tool', 'handler', 'endpoint', 'api', 'register', 'input', 'output'],
+    },
+    {
+        id: 'tests',
+        title: 'Tests',
+        keywords: ['test', 'spec', 'unit', 'coverage', 'mock', 'fixture', 'assert'],
+    },
+];
+function categorize(criterion) {
+    const lower = criterion.toLowerCase();
+    for (const rule of CATEGORY_RULES) {
+        if (rule.keywords.some((kw) => lower.includes(kw))) {
+            return rule.id;
+        }
+    }
+    return 'general';
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/** Read spec.md file and return its content, or empty string on error. */
+async function safeReadFile(filePath) {
+    try {
+        return await readFile(filePath, 'utf-8');
+        /* v8 ignore next 3 */
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Analyze spec content from disk and produce raw work units.
+ * Groups acceptance criteria by category heuristics.
+ */
+export async function analyzeSpec(specPath, technicalPath, maxTasks) {
+    const [specContent, techContent] = await Promise.all([
+        safeReadFile(specPath),
+        safeReadFile(technicalPath),
+    ]);
+    const criteria = extractCriteriaFromContent(specContent);
+    const allFiles = extractFilesFromTechnical(techContent);
+    return groupCriteriaIntoUnits(criteria, allFiles, maxTasks);
+}
+/**
+ * Group criteria lines into work units, respecting maxTasks limit.
+ * Exported for unit-testing without touching the filesystem.
+ */
+export function groupCriteriaIntoUnits(criteria, allFiles, maxTasks) {
+    if (criteria.length === 0) {
+        // Generate a single fallback unit so orchestration always has something to run
+        return [
+            {
+                id: 'unit-general',
+                title: 'General implementation',
+                criteria: [],
+                suggestedFiles: allFiles,
+                recommendedModel: 'sonnet',
+                estimatedHours: 4,
+            },
+        ];
+    }
+    // Bucket criteria by category
+    const buckets = new Map();
+    for (const criterion of criteria) {
+        const cat = categorize(criterion);
+        const existing = buckets.get(cat) ?? [];
+        existing.push(criterion);
+        buckets.set(cat, existing);
+    }
+    // Assign files by rough path matching per category
+    const filesByCategory = buildFileCategoryMap(allFiles);
+    const units = [];
+    for (const entry of buckets.entries()) {
+        const catId = entry[0];
+        const catCriteria = entry[1];
+        const categoryInfo = CATEGORY_RULES.find((r) => r.id === catId) ?? {
+            id: catId,
+            title: catId,
+        };
+        const suggestedFiles = filesByCategory.get(catId) ?? [];
+        const combinedText = catCriteria.join(' ');
+        const model = classifyModel(combinedText);
+        const hours = Math.max(1, Math.ceil(catCriteria.length * 1.5));
+        units.push({
+            id: `unit-${catId}`,
+            title: categoryInfo.title,
+            criteria: catCriteria,
+            suggestedFiles,
+            recommendedModel: model,
+            estimatedHours: hours,
+        });
+    }
+    // If fewer than 2 units were produced, add uncategorized files to general
+    if (units.length === 0) {
+        units.push({
+            id: 'unit-general',
+            title: 'General implementation',
+            criteria,
+            suggestedFiles: allFiles,
+            recommendedModel: 'sonnet',
+            estimatedHours: Math.max(2, criteria.length * 1.5),
+        });
+    }
+    // Enforce maxTasks by merging excess units into the last one
+    return mergeExcessUnits(units, maxTasks);
+}
+/** Map file paths to category IDs based on path segments. */
+function buildFileCategoryMap(files) {
+    const map = new Map();
+    for (const file of files) {
+        const lower = file.toLowerCase();
+        let assigned = false;
+        for (const rule of CATEGORY_RULES) {
+            if (rule.keywords.some((kw) => lower.includes(kw))) {
+                const existing = map.get(rule.id) ?? [];
+                existing.push(file);
+                map.set(rule.id, existing);
+                assigned = true;
+                break;
+            }
+        }
+        if (!assigned) {
+            const existing = map.get('general') ?? [];
+            existing.push(file);
+            map.set('general', existing);
+        }
+    }
+    return map;
+}
+/** Merge units beyond maxTasks into the last retained unit. */
+function mergeExcessUnits(units, maxTasks) {
+    if (units.length <= maxTasks) {
+        return units;
+    }
+    const retained = units.slice(0, maxTasks - 1);
+    const overflow = units.slice(maxTasks - 1);
+    const merged = {
+        id: 'unit-general',
+        title: 'Combined implementation',
+        criteria: overflow.flatMap((u) => u.criteria),
+        suggestedFiles: [...new Set(overflow.flatMap((u) => u.suggestedFiles))],
+        recommendedModel: 'sonnet',
+        estimatedHours: overflow.reduce((acc, u) => acc + u.estimatedHours, 0),
+    };
+    return [...retained, merged];
+}
+/** Extract section headers from markdown content (used by file-mapper). */
+export function extractSectionHeaders(content) {
+    const headers = [];
+    let match;
+    const pattern = new RegExp(SECTION_PATTERN.source, 'gm');
+    while ((match = pattern.exec(content)) !== null) {
+        if (match[1]) {
+            headers.push(match[1].trim());
+        }
+    }
+    return headers;
+}
+//# sourceMappingURL=analyzer.js.map

package/dist/engine/spec-decomposer/analyzer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyzer.js","sourceRoot":"","sources":["../../../src/engine/spec-decomposer/analyzer.ts"],"names":[],"mappings":"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"}

package/dist/engine/spec-decomposer/file-mapper.d.ts

@@ -0,0 +1,17 @@
+import type { WorkUnit, MappedUnit } from '../../types/spec-decomposer.js';
+/**
+ * Map work units to concrete file paths.
+ *
+ * Strategy:
+ * 1. Each unit starts with its suggestedFiles (from analyzer).
+ * 2. For remaining files in allFiles not yet assigned, we use path-hint scoring
+ *    to assign them to the best-matching unit.
+ * 3. Files with score 0 for all units are distributed to the last unit (fallback).
+ */
+export declare function mapUnitsToFiles(units: WorkUnit[], allFiles: string[]): MappedUnit[];
+/**
+ * De-duplicate files within each mapped unit and ensure uniqueness.
+ * Called after mapUnitsToFiles() as a clean-up step.
+ */
+export declare function deduplicateMappedFiles(units: MappedUnit[]): MappedUnit[];
+//# sourceMappingURL=file-mapper.d.ts.map

package/dist/engine/spec-decomposer/file-mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-mapper.d.ts","sourceRoot":"","sources":["../../../src/engine/spec-decomposer/file-mapper.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AAwC3E;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,UAAU,EAAE,CA+CnF;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,UAAU,EAAE,CAKxE"}

package/dist/engine/spec-decomposer/file-mapper.js

@@ -0,0 +1,96 @@
+// engine/spec-decomposer/file-mapper.ts — Map work units to specific files (SPEC-157)
+// Given work units and a full list of project files, assigns concrete file paths
+// to each unit based on path segment heuristics.
+// ---------------------------------------------------------------------------
+// Path segment heuristics
+// ---------------------------------------------------------------------------
+/** Map unit IDs to path segment patterns that indicate file relevance. */
+const UNIT_PATH_HINTS = {
+    types: ['types/', '/types.ts', 'type.ts'],
+    engine: ['engine/', 'analyzer', 'calculator', 'processor', 'resolver', 'detector'],
+    storage: ['storage/', 'store.ts', '-store.ts', 'repository', 'persistence'],
+    tool: ['tools/', 'handler.ts', 'register-'],
+    tests: ['tests/', '.test.ts', '.spec.ts'],
+    general: [],
+};
+/**
+ * Score how relevant a file path is for a given unit ID.
+ * Returns 0 for irrelevant, higher values for stronger matches.
+ */
+function scoreFilePath(filePath, unitId) {
+    const lower = filePath.toLowerCase();
+    const categoryId = unitId.replace(/^unit-/, '');
+    const hints = UNIT_PATH_HINTS[categoryId] ?? UNIT_PATH_HINTS.general ?? [];
+    let score = 0;
+    for (const hint of hints) {
+        if (lower.includes(hint)) {
+            score += 2;
+        }
+    }
+    // Bonus: file path contains a keyword from the unit's criteria (caller may inject)
+    return score;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Map work units to concrete file paths.
+ *
+ * Strategy:
+ * 1. Each unit starts with its suggestedFiles (from analyzer).
+ * 2. For remaining files in allFiles not yet assigned, we use path-hint scoring
+ *    to assign them to the best-matching unit.
+ * 3. Files with score 0 for all units are distributed to the last unit (fallback).
+ */
+export function mapUnitsToFiles(units, allFiles) {
+    if (units.length === 0) {
+        return [];
+    }
+    // Seed each mapped unit with its suggestedFiles
+    const mapped = units.map((u) => ({
+        id: u.id,
+        title: u.title,
+        criteria: u.criteria,
+        files: [...u.suggestedFiles],
+        recommendedModel: u.recommendedModel,
+        estimatedHours: u.estimatedHours,
+    }));
+    // Track which files are already covered
+    const assignedFiles = new Set(units.flatMap((u) => u.suggestedFiles));
+    // Assign remaining files to best-matching unit
+    for (const file of allFiles) {
+        if (assignedFiles.has(file)) {
+            continue;
+        }
+        let bestUnitIndex = mapped.length - 1; // fallback: last unit
+        let bestScore = -1;
+        for (let i = 0; i < mapped.length; i++) {
+            const unit = mapped[i];
+            if (!unit) {
+                continue;
+            }
+            const score = scoreFilePath(file, unit.id);
+            if (score > bestScore) {
+                bestScore = score;
+                bestUnitIndex = i;
+            }
+        }
+        const target = mapped[bestUnitIndex];
+        if (target && !target.files.includes(file)) {
+            target.files.push(file);
+            assignedFiles.add(file);
+        }
+    }
+    return mapped;
+}
+/**
+ * De-duplicate files within each mapped unit and ensure uniqueness.
+ * Called after mapUnitsToFiles() as a clean-up step.
+ */
+export function deduplicateMappedFiles(units) {
+    return units.map((unit) => ({
+        ...unit,
+        files: [...new Set(unit.files)],
+    }));
+}
+//# sourceMappingURL=file-mapper.js.map

package/dist/engine/spec-decomposer/file-mapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-mapper.js","sourceRoot":"","sources":["../../../src/engine/spec-decomposer/file-mapper.ts"],"names":[],"mappings":"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"}

package/dist/engine/spec-decomposer/index.d.ts

@@ -0,0 +1,14 @@
+export { analyzeSpec, groupCriteriaIntoUnits, extractCriteriaFromContent, extractFilesFromTechnical, } from './analyzer.js';
+export { mapUnitsToFiles, deduplicateMappedFiles } from './file-mapper.js';
+export { resolveFileOwnership } from './ownership-resolver.js';
+import type { SpecDecomposeResult } from '../../types/spec-decomposer.js';
+/**
+ * Main entry point: decompose a spec into parallelizable agent tasks.
+ *
+ * @param specPath     Absolute path to the spec's spec.md file.
+ * @param technicalPath Absolute path to the spec's technical.md file.
+ * @param specId       Spec identifier (e.g. "SPEC-042").
+ * @param maxTasks     Maximum number of tasks to generate (default: 5).
+ */
+export declare function decomposeSpec(specPath: string, technicalPath: string, specId: string, maxTasks?: number): Promise<SpecDecomposeResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/engine/spec-decomposer/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/engine/spec-decomposer/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,WAAW,EACX,sBAAsB,EACtB,0BAA0B,EAC1B,yBAAyB,GAC1B,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC3E,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAK/D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAK1E;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,EACd,QAAQ,GAAE,MAA0B,GACnC,OAAO,CAAC,mBAAmB,CAAC,CAwC9B"}

package/dist/engine/spec-decomposer/index.js

@@ -0,0 +1,50 @@
+// engine/spec-decomposer/index.ts — Barrel export + main decomposeSpec() (SPEC-157)
+export { analyzeSpec, groupCriteriaIntoUnits, extractCriteriaFromContent, extractFilesFromTechnical, } from './analyzer.js';
+export { mapUnitsToFiles, deduplicateMappedFiles } from './file-mapper.js';
+export { resolveFileOwnership } from './ownership-resolver.js';
+import { analyzeSpec } from './analyzer.js';
+import { mapUnitsToFiles, deduplicateMappedFiles } from './file-mapper.js';
+import { resolveFileOwnership } from './ownership-resolver.js';
+/** Default maximum number of agent tasks to generate. */
+const DEFAULT_MAX_TASKS = 5;
+/**
+ * Main entry point: decompose a spec into parallelizable agent tasks.
+ *
+ * @param specPath     Absolute path to the spec's spec.md file.
+ * @param technicalPath Absolute path to the spec's technical.md file.
+ * @param specId       Spec identifier (e.g. "SPEC-042").
+ * @param maxTasks     Maximum number of tasks to generate (default: 5).
+ */
+export async function decomposeSpec(specPath, technicalPath, specId, maxTasks = DEFAULT_MAX_TASKS) {
+    const clampedMax = Math.max(1, Math.min(maxTasks, 20));
+    // Step 1: Analyze spec content → raw work units
+    const workUnits = await analyzeSpec(specPath, technicalPath, clampedMax);
+    // Step 2: Map each work unit to concrete file paths
+    const allFiles = workUnits.flatMap((u) => u.suggestedFiles);
+    const rawMapped = mapUnitsToFiles(workUnits, allFiles);
+    const mapped = deduplicateMappedFiles(rawMapped);
+    // Step 3: Resolve file ownership conflicts + build tasks
+    const { tasks, fileOwnership, conflicts, executionPhases } = resolveFileOwnership(mapped);
+    // Step 4: Build warnings
+    const warnings = [];
+    for (const task of tasks) {
+        if (task.ownedFiles.length === 0) {
+            warnings.push(`Task "${task.id}" has no owned files — it may be too abstract.`);
+        }
+    }
+    if (tasks.length === 1) {
+        warnings.push('Only one task was generated — the spec may be too small for parallel execution.');
+    }
+    const orchestrationReady = tasks.length > 0 && warnings.filter((w) => w.includes('no owned')).length === 0;
+    return {
+        specId,
+        taskCount: tasks.length,
+        tasks,
+        fileOwnership,
+        conflicts,
+        executionPhases,
+        warnings,
+        orchestrationReady,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/engine/spec-decomposer/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/engine/spec-decomposer/index.ts"],"names":[],"mappings":"AAAA,oFAAoF;AAEpF,OAAO,EACL,WAAW,EACX,sBAAsB,EACtB,0BAA0B,EAC1B,yBAAyB,GAC1B,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC3E,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAE/D,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC3E,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAG/D,yDAAyD;AACzD,MAAM,iBAAiB,GAAG,CAAC,CAAC;AAE5B;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,QAAgB,EAChB,aAAqB,EACrB,MAAc,EACd,WAAmB,iBAAiB;IAEpC,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC;IAEvD,gDAAgD;IAChD,MAAM,SAAS,GAAG,MAAM,WAAW,CAAC,QAAQ,EAAE,aAAa,EAAE,UAAU,CAAC,CAAC;IAEzE,oDAAoD;IACpD,MAAM,QAAQ,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC;IAC5D,MAAM,SAAS,GAAG,eAAe,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IACvD,MAAM,MAAM,GAAG,sBAAsB,CAAC,SAAS,CAAC,CAAC;IAEjD,yDAAyD;IACzD,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,eAAe,EAAE,GAAG,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAE1F,yBAAyB;IACzB,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACjC,QAAQ,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,EAAE,gDAAgD,CAAC,CAAC;QAClF,CAAC;IACH,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,QAAQ,CAAC,IAAI,CACX,iFAAiF,CAClF,CAAC;IACJ,CAAC;IAED,MAAM,kBAAkB,GACtB,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC;IAElF,OAAO;QACL,MAAM;QACN,SAAS,EAAE,KAAK,CAAC,MAAM;QACvB,KAAK;QACL,aAAa;QACb,SAAS;QACT,eAAe;QACf,QAAQ;QACR,kBAAkB;KACnB,CAAC;AACJ,CAAC"}

package/dist/engine/spec-decomposer/ownership-resolver.d.ts

@@ -0,0 +1,7 @@
+import type { MappedUnit, OwnershipResolutionResult } from '../../types/spec-decomposer.js';
+/**
+ * Resolve file ownership and produce final AgentTask list, FileOwnership records,
+ * detected conflicts, and execution phases.
+ */
+export declare function resolveFileOwnership(units: MappedUnit[]): OwnershipResolutionResult;
+//# sourceMappingURL=ownership-resolver.d.ts.map

package/dist/engine/spec-decomposer/ownership-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ownership-resolver.d.ts","sourceRoot":"","sources":["../../../src/engine/spec-decomposer/ownership-resolver.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,UAAU,EAKV,yBAAyB,EAC1B,MAAM,gCAAgC,CAAC;AAiIxC;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,yBAAyB,CA2DnF"}

package/dist/engine/spec-decomposer/ownership-resolver.js

@@ -0,0 +1,169 @@
+// engine/spec-decomposer/ownership-resolver.ts — Resolve file ownership conflicts (SPEC-157)
+// Ensures no two agent tasks claim the same file. When conflicts exist, the task
+// with the highest file count wins ownership; other tasks receive a dependency instead.
+// ---------------------------------------------------------------------------
+// Conflict detection
+// ---------------------------------------------------------------------------
+/**
+ * Find files claimed by more than one mapped unit.
+ * Returns a map of filePath → unitIds that claim it.
+ */
+function detectConflicts(units) {
+    const fileToUnits = new Map();
+    for (const unit of units) {
+        for (const file of unit.files) {
+            const existing = fileToUnits.get(file) ?? [];
+            existing.push(unit.id);
+            fileToUnits.set(file, existing);
+        }
+    }
+    // Keep only files with >1 claimant
+    const conflicts = new Map();
+    for (const [file, unitIds] of fileToUnits) {
+        if (unitIds.length > 1) {
+            conflicts.set(file, unitIds);
+        }
+    }
+    return conflicts;
+}
+// ---------------------------------------------------------------------------
+// Ownership resolution
+// ---------------------------------------------------------------------------
+/**
+ * Resolve ownership conflicts by awarding each contested file to the unit with
+ * the most files (primary owner) and removing it from the others.
+ * Returns a clean map of unitId → Set<filePath>.
+ */
+function resolveOwnership(units, conflicts) {
+    // Start: each unit owns all its files
+    const ownership = new Map(units.map((u) => [u.id, new Set(u.files)]));
+    for (const [file, claimantIds] of conflicts) {
+        // Primary owner = unit with most files (acts as heaviest dependency)
+        const sorted = [...claimantIds].sort((a, b) => {
+            const aSize = ownership.get(a)?.size ?? 0;
+            const bSize = ownership.get(b)?.size ?? 0;
+            return bSize - aSize;
+        });
+        const winner = sorted[0];
+        if (!winner) {
+            continue;
+        }
+        // Remove file from all losers
+        for (const loserId of sorted.slice(1)) {
+            ownership.get(loserId)?.delete(file);
+        }
+    }
+    return ownership;
+}
+// ---------------------------------------------------------------------------
+// Execution phase planning
+// ---------------------------------------------------------------------------
+/**
+ * Assign tasks to execution phases.
+ * Tasks with no dependencies → phase 1 (parallel).
+ * Tasks with dependencies → subsequent phases.
+ */
+function buildExecutionPhases(tasks) {
+    if (tasks.length === 0) {
+        return [];
+    }
+    const phases = [];
+    const placed = new Set();
+    let remaining = [...tasks];
+    while (remaining.length > 0) {
+        const phaseNumber = phases.length + 1;
+        // Tasks whose dependencies are all placed
+        const ready = remaining.filter((t) => t.dependencies.every((dep) => placed.has(dep)));
+        if (ready.length === 0) {
+            // Circular dependency safety: place everything left in one phase
+            const ids = remaining.map((t) => t.id);
+            phases.push({
+                phase: phaseNumber,
+                taskIds: ids,
+                reason: 'Remaining tasks (possible circular dependency detected)',
+            });
+            break;
+        }
+        const reason = ready.length === 1
+            ? `Single task with all dependencies satisfied`
+            : `${String(ready.length)} tasks with no file conflicts — run in parallel`;
+        phases.push({
+            phase: phaseNumber,
+            taskIds: ready.map((t) => t.id),
+            reason,
+        });
+        for (const t of ready) {
+            placed.add(t.id);
+        }
+        remaining = remaining.filter((t) => !placed.has(t.id));
+    }
+    return phases;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Resolve file ownership and produce final AgentTask list, FileOwnership records,
+ * detected conflicts, and execution phases.
+ */
+export function resolveFileOwnership(units) {
+    const rawConflicts = detectConflicts(units);
+    const ownershipMap = resolveOwnership(units, rawConflicts);
+    // Build dependency edges: if unit B lost a file to unit A, B depends on A
+    const dependencyEdges = new Map();
+    for (const unit of units) {
+        dependencyEdges.set(unit.id, new Set());
+    }
+    const resolvedConflicts = [];
+    for (const [file, claimantIds] of rawConflicts) {
+        // Winner is the one that still owns the file after resolution
+        const winner = claimantIds.find((id) => ownershipMap.get(id)?.has(file));
+        if (!winner) {
+            continue;
+        }
+        const losers = claimantIds.filter((id) => id !== winner);
+        for (const loser of losers) {
+            dependencyEdges.get(loser)?.add(winner);
+        }
+        resolvedConflicts.push({
+            filePath: file,
+            conflictingTaskIds: claimantIds,
+            resolution: `Ownership awarded to ${winner}; ${losers.join(', ')} will depend on it.`,
+        });
+    }
+    // Build AgentTask array
+    const tasks = units.map((unit) => {
+        const ownedFiles = [...(ownershipMap.get(unit.id) ?? [])].sort();
+        const dependencies = [...(dependencyEdges.get(unit.id) ?? [])].sort();
+        // A task can run in parallel if it has no dependencies
+        const canRunParallel = dependencies.length === 0;
+        return {
+            id: unit.id,
+            title: unit.title,
+            description: buildDescription(unit, ownedFiles),
+            criteria: unit.criteria,
+            ownedFiles,
+            dependencies,
+            recommendedModel: unit.recommendedModel,
+            estimatedHours: unit.estimatedHours,
+            canRunParallel,
+        };
+    });
+    // Build FileOwnership records
+    const fileOwnership = tasks.flatMap((task) => task.ownedFiles.map((filePath) => ({ filePath, taskId: task.id })));
+    const executionPhases = buildExecutionPhases(tasks);
+    return { tasks, fileOwnership, conflicts: resolvedConflicts, executionPhases };
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function buildDescription(unit, ownedFiles) {
+    const criteriaLines = unit.criteria.length > 0
+        ? `\nAcceptance criteria:\n${unit.criteria.map((c) => `- ${c}`).join('\n')}`
+        : '';
+    const fileLines = ownedFiles.length > 0
+        ? `\nOwned files (exclusive):\n${ownedFiles.map((f) => `- ${f}`).join('\n')}`
+        : '';
+    return `Implement ${unit.title}.${criteriaLines}${fileLines}`;
+}
+//# sourceMappingURL=ownership-resolver.js.map