@planu/cli 0.63.6 → 0.64.0

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

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

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

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

@@ -0,0 +1,4 @@
+export { trackSpecAccess, trackFromArgs, extractSpecIds, extractAcRef } from './tracker.js';
+export { filterByPeriod, aggregateBySpec, buildObservabilityReport } from './metrics.js';
+export type { BuildReportOptions } from '../../types/spec-observability.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/engine/spec-observability/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5F,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AACzF,YAAY,EAAE,kBAAkB,EAAE,MAAM,mCAAmC,CAAC"}

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

@@ -0,0 +1,4 @@
+// engine/spec-observability/index.ts — Barrel export (SPEC-158)
+export { trackSpecAccess, trackFromArgs, extractSpecIds, extractAcRef } from './tracker.js';
+export { filterByPeriod, aggregateBySpec, buildObservabilityReport } from './metrics.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/engine/spec-observability/index.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5F,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC"}

package/dist/engine/spec-observability/metrics.d.ts

@@ -0,0 +1,8 @@
+import type { SpecUsageEvent, SpecUsageMetrics, SpecObservabilityReport, Period, BuildReportOptions } from '../../types/index.js';
+export declare function filterByPeriod(events: readonly SpecUsageEvent[], period: Period): SpecUsageEvent[];
+/**
+ * Aggregate a flat event list into per-spec metrics.
+ */
+export declare function aggregateBySpec(events: readonly SpecUsageEvent[]): SpecUsageMetrics[];
+export declare function buildObservabilityReport(opts: BuildReportOptions): SpecObservabilityReport;
+//# sourceMappingURL=metrics.d.ts.map

package/dist/engine/spec-observability/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../../src/engine/spec-observability/metrics.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,cAAc,EACd,gBAAgB,EAChB,uBAAuB,EACvB,MAAM,EACN,kBAAkB,EACnB,MAAM,sBAAsB,CAAC;AAgB9B,wBAAgB,cAAc,CAC5B,MAAM,EAAE,SAAS,cAAc,EAAE,EACjC,MAAM,EAAE,MAAM,GACb,cAAc,EAAE,CAGlB;AAMD;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,GAAG,gBAAgB,EAAE,CAmDrF;AAmCD,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,kBAAkB,GAAG,uBAAuB,CA0B1F"}

package/dist/engine/spec-observability/metrics.js

@@ -0,0 +1,116 @@
+// engine/spec-observability/metrics.ts — Aggregate usage data (SPEC-158)
+// Computes hot specs, cold specs, tool matrix, and hot ACs from raw events.
+function periodCutoff(period) {
+    const now = Date.now();
+    switch (period) {
+        case 'day':
+            return now - 24 * 60 * 60 * 1000;
+        case 'week':
+            return now - 7 * 24 * 60 * 60 * 1000;
+        case 'month':
+            return now - 30 * 24 * 60 * 60 * 1000;
+        case 'all':
+            return 0;
+    }
+}
+export function filterByPeriod(events, period) {
+    const cutoff = periodCutoff(period);
+    return events.filter((e) => new Date(e.timestamp).getTime() >= cutoff);
+}
+// ---------------------------------------------------------------------------
+// Per-spec aggregation
+// ---------------------------------------------------------------------------
+/**
+ * Aggregate a flat event list into per-spec metrics.
+ */
+export function aggregateBySpec(events) {
+    const bySpec = new Map();
+    for (const event of events) {
+        const existing = bySpec.get(event.specId) ?? [];
+        existing.push(event);
+        bySpec.set(event.specId, existing);
+    }
+    const results = [];
+    for (const [specId, specEvents] of bySpec.entries()) {
+        const toolMatrix = {};
+        const acCounts = {};
+        const toolsSet = new Set();
+        let firstAccess = specEvents[0]?.timestamp ?? '';
+        let lastAccess = specEvents[0]?.timestamp ?? '';
+        for (const e of specEvents) {
+            toolMatrix[e.toolName] = (toolMatrix[e.toolName] ?? 0) + 1;
+            toolsSet.add(e.toolName);
+            if (e.acRef) {
+                acCounts[e.acRef] = (acCounts[e.acRef] ?? 0) + 1;
+            }
+            if (e.timestamp < firstAccess) {
+                firstAccess = e.timestamp;
+            }
+            if (e.timestamp > lastAccess) {
+                lastAccess = e.timestamp;
+            }
+        }
+        const hotAcs = Object.entries(acCounts)
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, 5)
+            .map(([acRef, count]) => ({ acRef, count }));
+        results.push({
+            specId,
+            totalAccesses: specEvents.length,
+            toolsUsed: [...toolsSet],
+            toolMatrix,
+            hotAcs,
+            firstAccessAt: firstAccess,
+            lastAccessAt: lastAccess,
+        });
+    }
+    return results.sort((a, b) => b.totalAccesses - a.totalAccesses);
+}
+// ---------------------------------------------------------------------------
+// Top tools
+// ---------------------------------------------------------------------------
+function computeTopTools(events) {
+    const counts = {};
+    for (const e of events) {
+        counts[e.toolName] = (counts[e.toolName] ?? 0) + 1;
+    }
+    return Object.entries(counts)
+        .sort((a, b) => b[1] - a[1])
+        .map(([toolName, count]) => ({ toolName, count }));
+}
+// ---------------------------------------------------------------------------
+// Cold spec detection
+// ---------------------------------------------------------------------------
+/**
+ * Identify spec IDs that are known but had zero accesses in the period.
+ * `allKnownSpecIds` comes from the spec store (approved/implementing specs).
+ */
+function computeColdSpecs(accessedSpecIds, allKnownSpecIds) {
+    return allKnownSpecIds.filter((id) => !accessedSpecIds.has(id)).sort();
+}
+// ---------------------------------------------------------------------------
+// Full report builder
+// ---------------------------------------------------------------------------
+export function buildObservabilityReport(opts) {
+    const { projectId, period, events, allKnownSpecIds = [], filterSpecId } = opts;
+    const periodEvents = filterByPeriod(events, period);
+    const scopedEvents = filterSpecId !== undefined
+        ? periodEvents.filter((e) => e.specId === filterSpecId.toUpperCase())
+        : periodEvents;
+    const specMetrics = aggregateBySpec(scopedEvents);
+    const accessedIds = new Set(specMetrics.map((m) => m.specId));
+    const coldSpecs = filterSpecId !== undefined ? [] : computeColdSpecs(accessedIds, allKnownSpecIds);
+    const topTools = computeTopTools(scopedEvents);
+    const hotSpecs = specMetrics.slice(0, 10);
+    return {
+        projectId,
+        period,
+        generatedAt: new Date().toISOString(),
+        totalEvents: scopedEvents.length,
+        hotSpecs,
+        coldSpecs,
+        specMetrics,
+        topTools,
+    };
+}
+//# sourceMappingURL=metrics.js.map

package/dist/engine/spec-observability/metrics.js.map

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

package/dist/engine/spec-observability/tracker.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Extract all SPEC-NNN identifiers mentioned in a string.
+ * Returns an empty array when none found.
+ */
+export declare function extractSpecIds(text: string): string[];
+/**
+ * Extract an AC reference like "AC-3" or "AC3" from a string.
+ * Returns the first match or undefined.
+ */
+export declare function extractAcRef(text: string): string | undefined;
+/**
+ * Record that `toolName` accessed `specId` (and optionally `acRef`).
+ * Fire-and-forget — errors are suppressed to avoid disrupting the caller.
+ */
+export declare function trackSpecAccess(projectId: string, toolName: string, specId: string, acRef?: string): void;
+/**
+ * Inspect a tool call's args object and record usage events for any SPEC-NNN
+ * identifiers found in string fields. Designed to be called from safe-handler
+ * or tool wrappers without any performance impact.
+ */
+export declare function trackFromArgs(projectId: string, toolName: string, args: unknown): void;
+//# sourceMappingURL=tracker.d.ts.map

package/dist/engine/spec-observability/tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracker.d.ts","sourceRoot":"","sources":["../../../src/engine/spec-observability/tracker.ts"],"names":[],"mappings":"AAYA;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAOrD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAG7D;AAMD;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,KAAK,CAAC,EAAE,MAAM,GACb,IAAI,CAWN;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CA4BtF"}

package/dist/engine/spec-observability/tracker.js

@@ -0,0 +1,77 @@
+// engine/spec-observability/tracker.ts — SpecUsageTracker (SPEC-158)
+// Records spec access events fire-and-forget — zero latency impact on callers.
+import { recordSpecAccess } from '../../storage/spec-observability-store.js';
+// ---------------------------------------------------------------------------
+// Spec ID extraction helpers
+// ---------------------------------------------------------------------------
+const SPEC_ID_PATTERN = /\bSPEC-\d+\b/gi;
+/**
+ * Extract all SPEC-NNN identifiers mentioned in a string.
+ * Returns an empty array when none found.
+ */
+export function extractSpecIds(text) {
+    const matches = text.match(SPEC_ID_PATTERN);
+    if (!matches) {
+        return [];
+    }
+    // Normalise to uppercase and deduplicate
+    return [...new Set(matches.map((m) => m.toUpperCase()))];
+}
+/**
+ * Extract an AC reference like "AC-3" or "AC3" from a string.
+ * Returns the first match or undefined.
+ */
+export function extractAcRef(text) {
+    const match = /\bAC[-\s]?(\d+)\b/i.exec(text);
+    return match ? `AC-${match[1]}` : undefined;
+}
+// ---------------------------------------------------------------------------
+// Public tracker API
+// ---------------------------------------------------------------------------
+/**
+ * Record that `toolName` accessed `specId` (and optionally `acRef`).
+ * Fire-and-forget — errors are suppressed to avoid disrupting the caller.
+ */
+export function trackSpecAccess(projectId, toolName, specId, acRef) {
+    const event = {
+        specId: specId.toUpperCase(),
+        toolName,
+        timestamp: new Date().toISOString(),
+        ...(acRef !== undefined ? { acRef } : {}),
+    };
+    recordSpecAccess(projectId, event).catch((err) => {
+        console.error('[Planu] spec-observability: failed to record event', err);
+    });
+}
+/**
+ * Inspect a tool call's args object and record usage events for any SPEC-NNN
+ * identifiers found in string fields. Designed to be called from safe-handler
+ * or tool wrappers without any performance impact.
+ */
+export function trackFromArgs(projectId, toolName, args) {
+    if (args === null || typeof args !== 'object') {
+        return;
+    }
+    const record = args;
+    // Fast-path: if specId is directly provided
+    if (typeof record.specId === 'string' && record.specId.length > 0) {
+        const specId = record.specId.toUpperCase();
+        const acRef = typeof record.acRef === 'string' ? record.acRef : undefined;
+        trackSpecAccess(projectId, toolName, specId, acRef);
+        return;
+    }
+    // Fallback: scan string values for SPEC-NNN patterns
+    for (const value of Object.values(record)) {
+        if (typeof value !== 'string') {
+            continue;
+        }
+        const ids = extractSpecIds(value);
+        for (const id of ids) {
+            trackSpecAccess(projectId, toolName, id);
+        }
+        if (ids.length > 0) {
+            return;
+        } // Only scan until we find at least one match
+    }
+}
+//# sourceMappingURL=tracker.js.map

package/dist/engine/spec-observability/tracker.js.map

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