@planu/cli 3.9.12 → 3.9.14

package/dist/config/hook-templates/planu-spec-sanctity.sh

@@ -21,7 +21,6 @@ set -euo pipefail
 ALLOWED_FILES=(
   "spec.md"
   "progress.json"
-  "implementation-brief.md"
 )
 
 # ---------------------------------------------------------------------------
@@ -104,9 +103,9 @@ EOF
 Allowed files inside planu/specs/SPEC-*/ are:
   - spec.md
   - progress.json
-  - implementation-brief.md
 
-Do NOT create technical.md, progress.md, PLAN.md, NOTES.md, ADRs, or other files here.
+Do NOT create technical.md, progress.md, implementation-brief.md, prompt.md,
+risk-register.md, PLAN.md, NOTES.md, ADRs, or other files here.
 Keep implementation notes in conversation context or in src/.
 EOF
   exit 2

package/dist/engine/autopilot/bootstrap.js

@@ -24,140 +24,6 @@ function registerSessionContextFreshnessListener() {
         })();
     });
 }
-/**
- * SPEC-586: Fire-and-forget implementation-brief generation + impact detector
- * on spec:status:approved. Errors are silently logged and never block the parent tool.
- */
-function registerImplementationReadyListener() {
-    onAutopilotEvent('spec:status:approved', (event) => {
-        if (!event.specId) {
-            return;
-        }
-        const { specId, projectPath, projectId } = event;
-        void (async () => {
-            try {
-                const { glob } = await import('glob');
-                const [specFiles, techFiles] = await Promise.all([
-                    glob(`planu/specs/${specId}-*/spec.md`, { cwd: projectPath, absolute: true }),
-                    glob(`planu/specs/${specId}-*/technical.md`, { cwd: projectPath, absolute: true }),
-                ]);
-                const specPath = specFiles[0];
-                const technicalPath = techFiles[0];
-                if (!specPath) {
-                    return;
-                }
-                const { readFile } = await import('node:fs/promises');
-                const specBody = await readFile(specPath, 'utf-8').catch(() => '');
-                const tagsMatch = /^tags:\s*\[([^\]]*)\]/m.exec(specBody);
-                const targetMatch = /^target:\s*(.+)$/m.exec(specBody);
-                const scopeMatch = /^scope:\s*(.+)$/m.exec(specBody);
-                const tags = tagsMatch?.[1] !== undefined
-                    ? tagsMatch[1].split(',').map((t) => t.trim().replace(/^["']|["']$/g, ''))
-                    : [];
-                const target = targetMatch?.[1]?.trim() ?? 'backend';
-                const scope = scopeMatch?.[1]?.trim() ?? 'cross-module';
-                void projectId;
-                const { generateImplementationBrief } = await import('../implementation-brief/generator.js');
-                generateImplementationBrief({
-                    specId,
-                    specPath,
-                    projectPath,
-                    description: specBody,
-                    tags,
-                    target,
-                    scope,
-                }).catch((err) => {
-                    const msg = err instanceof Error ? err.message : String(err);
-                    console.error(`[autopilot] implementation-brief failed for ${specId}: ${msg}`);
-                });
-                if (technicalPath) {
-                    const { runImpactDetector } = await import('../impact-detector/index.js');
-                    runImpactDetector({
-                        specId,
-                        specPath,
-                        technicalPath,
-                        projectPath,
-                    }).catch((err) => {
-                        const msg = err instanceof Error ? err.message : String(err);
-                        console.error(`[autopilot] impact-detector failed for ${specId}: ${msg}`);
-                    });
-                }
-            }
-            catch {
-                /* best-effort — never surface to user */
-            }
-        })();
-    });
-}
-/**
- * SPEC-627: Fire-and-forget risk-register generation on spec:status:approved.
- * Writes planu/specs/SPEC-XXX/risk-register.md from spec metadata.
- */
-function registerRiskAnalyzerListener() {
-    onAutopilotEvent('spec:status:approved', (event) => {
-        if (!event.specId) {
-            return;
-        }
-        const { specId, projectPath } = event;
-        void (async () => {
-            try {
-                const { glob } = await import('glob');
-                const specFiles = await glob(`planu/specs/${specId}-*/spec.md`, { cwd: projectPath, absolute: true });
-                const specPath = specFiles[0];
-                if (!specPath) {
-                    return;
-                }
-                const { readFile, writeFile } = await import('node:fs/promises');
-                const specBody = await readFile(specPath, 'utf-8');
-                const typeMatch = /^type:\s*(.+)$/m.exec(specBody);
-                const scopeMatch = /^scope:\s*(.+)$/m.exec(specBody);
-                const difficultyMatch = /^difficulty:\s*(\d+)/m.exec(specBody);
-                const riskMatch = /^risk:\s*(.+)$/m.exec(specBody);
-                const tagsMatch = /^tags:\s*\[([^\]]*)\]/m.exec(specBody);
-                const tags = tagsMatch?.[1] !== undefined
-                    ? tagsMatch[1].split(',').map((t) => t.trim().replace(/^["']|["']$/g, ''))
-                    : [];
-                const { generateRiskRegister } = await import('../risk-analyzer/risk-generator.js');
-                const rawDifficulty = parseInt(difficultyMatch?.[1] ?? '2', 10);
-                const difficulty = (rawDifficulty >= 1 && rawDifficulty <= 5 ? rawDifficulty : 2);
-                const rawRisk = riskMatch?.[1]?.trim() ?? 'low';
-                const riskLevel = (['low', 'medium', 'high', 'critical'].includes(rawRisk) ? rawRisk : 'low');
-                const ctx = {
-                    specId,
-                    title: specId,
-                    type: (typeMatch?.[1]?.trim() ?? 'feature'),
-                    scope: (scopeMatch?.[1]?.trim() ?? 'feature'),
-                    difficulty,
-                    risk: riskLevel,
-                    tags,
-                    language: 'TypeScript',
-                    framework: null,
-                    dependencyCount: 0,
-                    fileCount: 0,
-                };
-                const register = generateRiskRegister(ctx);
-                const lines = [
-                    `# Risk Register — ${specId}`,
-                    `_Generated ${new Date().toISOString()}_`,
-                    '',
-                    `**Aggregate score:** ${register.aggregateRiskScore}/100`,
-                    '',
-                    '## Risks',
-                ];
-                for (const r of register.risks) {
-                    lines.push(`- **${r.category}** (${r.probability}% probability, ${r.impactDays}d impact): ${r.description}`);
-                    lines.push(`  Mitigation: ${r.mitigationPlan}`);
-                }
-                const { dirname, join } = await import('node:path');
-                const registerPath = join(dirname(specPath), 'risk-register.md');
-                await writeFile(registerPath, lines.join('\n'), 'utf-8');
-            }
-            catch {
-                /* best-effort — never surface to user */
-            }
-        })();
-    });
-}
 /**
  * SPEC-600: Fire-and-forget cascade on approved→implementing.
  * Auto-recommends model + generates orchestration plan for complex specs.
@@ -260,10 +126,6 @@ export function bootstrapAutopilotHandlers() {
     }
     // SPEC-585: Register session-context freshness listener
     registerSessionContextFreshnessListener();
-    // SPEC-586: Register implementation-brief + impact-detector on spec:status:approved
-    registerImplementationReadyListener();
-    // SPEC-627: Register risk-register generator on spec:status:approved
-    registerRiskAnalyzerListener();
     // SPEC-600: Register cascade listener for implementing transition
     // SPEC-649: registerDoneCascadeListener removed — optimize_context no longer auto-runs on done
     registerImplementingCascadeListener();

package/dist/engine/housekeeping/ephemeral-artifacts-cleaner.d.ts

@@ -1,7 +1,7 @@
 import type { EphemeralArtifactsResult, CleanEphemeralArtifactsInput } from '../../types/housekeeping.js';
 /**
- * Scan all planu/specs/SPEC-* directories. For each spec whose status is
- * `done` or `discarded`, delete (or report) the ephemeral artifact files.
+ * Scan all planu/specs/SPEC-* directories and delete (or report) obsolete
+ * sidecar artifact files.
  */
 export declare function cleanEphemeralArtifacts(input: CleanEphemeralArtifactsInput): Promise<EphemeralArtifactsResult>;
 //# sourceMappingURL=ephemeral-artifacts-cleaner.d.ts.map

package/dist/engine/housekeeping/ephemeral-artifacts-cleaner.js

@@ -1,25 +1,16 @@
 // engine/housekeeping/ephemeral-artifacts-cleaner.ts — SPEC-762
-// Removes ephemeral planning artifacts (risk-register.md, implementation-brief.md,
-// prompt.md) from spec directories where the spec is done or discarded.
-import { readdir, readFile, unlink } from 'node:fs/promises';
+// Removes obsolete per-spec sidecar planning artifacts (risk-register.md,
+// implementation-brief.md, prompt.md). Current Planu specs keep durable content
+// in spec.md; these files are no longer generated or preserved.
+import { access, readdir, unlink } from 'node:fs/promises';
 import { join } from 'node:path';
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
 const EPHEMERAL_FILENAMES = ['risk-register.md', 'implementation-brief.md', 'prompt.md'];
-const TERMINAL_STATUSES = new Set(['done', 'discarded']);
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
-/** Extract the `status:` field from a spec.md YAML frontmatter block. */
-function extractStatus(raw) {
-    const frontmatterMatch = /^---\r?\n([\s\S]*?)\r?\n---/m.exec(raw);
-    if (!frontmatterMatch?.[1]) {
-        return null;
-    }
-    const statusMatch = /^status:\s*(\S+)/m.exec(frontmatterMatch[1]);
-    return statusMatch?.[1] ?? null;
-}
 /** Return true when the directory name looks like a Planu spec folder. */
 function isSpecDir(name) {
     return /^SPEC-\d+/.test(name);
@@ -28,8 +19,8 @@ function isSpecDir(name) {
 // Public API
 // ---------------------------------------------------------------------------
 /**
- * Scan all planu/specs/SPEC-* directories. For each spec whose status is
- * `done` or `discarded`, delete (or report) the ephemeral artifact files.
+ * Scan all planu/specs/SPEC-* directories and delete (or report) obsolete
+ * sidecar artifact files.
  */
 export async function cleanEphemeralArtifacts(input) {
     const specsRoot = join(input.projectPath, 'planu', 'specs');
@@ -50,22 +41,10 @@ export async function cleanEphemeralArtifacts(input) {
         return result; // planu/specs/ doesn't exist — nothing to clean
     }
     for (const specDir of specDirs) {
-        const specMdPath = join(specDir, 'spec.md');
-        let status;
-        try {
-            const raw = await readFile(specMdPath, 'utf-8');
-            status = extractStatus(raw);
-        }
-        catch {
-            continue; // no spec.md — skip this directory
-        }
-        if (status === null || !TERMINAL_STATUSES.has(status)) {
-            continue; // spec is still active
-        }
         for (const filename of EPHEMERAL_FILENAMES) {
             const filePath = join(specDir, filename);
             try {
-                await readFile(filePath, 'utf-8'); // probe existence
+                await access(filePath); // probe existence
             }
             catch {
                 continue; // file doesn't exist — skip

package/dist/engine/living-specs/index.d.ts

@@ -1,8 +1,8 @@
 import type { LivingSpecReconcileResult } from '../../types/index.js';
 /**
  * Auto-reconcile a spec against its actual implementation files.
- * Reads technical.md for file paths, spec.md for criteria,
- * scans files, matches criteria, updates progress.md.
+ * Reads spec.md for file paths and criteria, scans files, matches criteria,
+ * and writes the auto-reconcile summary into the inline ## Progress section.
  * Never throws -- returns partial result on error.
  */
 export declare function reconcileSpec(specId: string, projectPath: string): Promise<LivingSpecReconcileResult>;

package/dist/engine/living-specs/index.js

@@ -1,9 +1,10 @@
 // engine/living-specs/index.ts -- Main auto-reconcile entry point (SPEC-330)
-import { readFile, writeFile, access } from 'node:fs/promises';
+import { readFile, access } from 'node:fs/promises';
 import { join } from 'node:path';
 import { glob } from 'glob';
 import { scanFile, extractFilePaths } from './file-scanner.js';
 import { extractCriteriaLines, matchCriteria } from './criteria-matcher.js';
+import { replaceSectionInSpec } from '../spec-format/replace-section.js';
 /**
  * Find the spec directory for a given specId within the project.
  * Looks for planu/specs/{specId}-SLUG pattern via glob.
@@ -32,24 +33,12 @@ async function readSafe(filePath) {
 function buildDriftFlags(fileResults) {
     return fileResults.filter((f) => !f.exists).map((f) => 'DRIFT: ' + f.path + ' missing');
 }
-/**
- * Append or update the Auto-Reconcile section in progress.md.
- * SPEC-461: Only updates if the file already exists (lean specs don't have progress.md).
- */
-async function updateProgressMd(progressPath, result) {
-    // SPEC-461: Don't create progress.md for lean specs — only update if it already exists
-    try {
-        await access(progressPath);
-    }
-    catch {
-        return; // File doesn't exist — lean format spec, skip silently
-    }
-    const existing = await readSafe(progressPath);
+function buildAutoReconcileProgressBody(result) {
     const coveragePct = result.criteriaTotal > 0 ? Math.round((result.criteriaMet / result.criteriaTotal) * 100) : 0;
     const driftSection = result.driftFlags.length > 0
         ? '\n### Drift Flags\n\n' + result.driftFlags.map((f) => '- ' + f).join('\n') + '\n'
         : '';
-    const section = '\n## Auto-Reconcile\n\n' +
+    return ('### Auto-Reconcile\n\n' +
         '> Last reconciled: ' +
         result.reconciledAt +
         '\n\n' +
@@ -67,21 +56,12 @@ async function updateProgressMd(progressPath, result) {
         String(coveragePct) +
         '%)' +
         driftSection +
-        '\n';
-    const AUTO_RECONCILE_MARKER = '## Auto-Reconcile';
-    let newContent;
-    if (existing.includes(AUTO_RECONCILE_MARKER)) {
-        newContent = existing.replace(/\n## Auto-Reconcile[\s\S]*?(?=\n## |\n$|$)/, section);
-    }
-    else {
-        newContent = existing + section;
-    }
-    await writeFile(progressPath, newContent, 'utf-8');
+        '\n');
 }
 /**
  * Auto-reconcile a spec against its actual implementation files.
- * Reads technical.md for file paths, spec.md for criteria,
- * scans files, matches criteria, updates progress.md.
+ * Reads spec.md for file paths and criteria, scans files, matches criteria,
+ * and writes the auto-reconcile summary into the inline ## Progress section.
  * Never throws -- returns partial result on error.
  */
 export async function reconcileSpec(specId, projectPath) {
@@ -103,14 +83,9 @@ export async function reconcileSpec(specId, projectPath) {
             empty.driftFlags.push('DRIFT: spec directory for ' + specId + ' not found');
             return empty;
         }
-        const technicalPath = join(specDir, 'technical.md');
         const specMdPath = join(specDir, 'spec.md');
-        const progressPath = join(specDir, 'progress.md');
-        const [technicalContent, specMdContent] = await Promise.all([
-            readSafe(technicalPath),
-            readSafe(specMdPath),
-        ]);
-        const relativePaths = extractFilePaths(technicalContent);
+        const specMdContent = await readSafe(specMdPath);
+        const relativePaths = extractFilePaths(specMdContent);
         const absolutePaths = relativePaths.map((p) => join(projectPath, p));
         const fileResults = await Promise.all(absolutePaths.map((p) => scanFile(p)));
         const fileResultsWithRelative = fileResults.map((fr, i) => ({
@@ -134,7 +109,7 @@ export async function reconcileSpec(specId, projectPath) {
             fileResults: fileResultsWithRelative,
             criteriaResults,
         };
-        await updateProgressMd(progressPath, result);
+        await replaceSectionInSpec(specMdPath, 'Progress', buildAutoReconcileProgressBody(result));
         return result;
     }
     catch (err) {

package/dist/engine/progress-writer.d.ts

@@ -1,10 +1,10 @@
 import type { Spec } from '../types/index.js';
 /**
- * Generate initial progress.md content for a newly created spec.
+ * Generate initial ## Progress content for a newly created spec.
  */
 export declare function generateProgressContent(spec: Spec): string;
 /**
- * Generate an updated progress.md reflecting a status change.
+ * Generate updated ## Progress content reflecting a status change.
  */
 export declare function generateProgressUpdate(spec: Spec, previousStatus: string, existingContent: string): string;
 //# sourceMappingURL=progress-writer.d.ts.map

package/dist/engine/progress-writer.js

@@ -1,5 +1,5 @@
 /**
- * Generate initial progress.md content for a newly created spec.
+ * Generate initial ## Progress content for a newly created spec.
  */
 export function generateProgressContent(spec) {
     const sections = [
@@ -10,7 +10,7 @@ export function generateProgressContent(spec) {
     return sections.map((s) => `## ${s.title}\n\n${s.content}`).join('\n\n---\n\n');
 }
 /**
- * Generate an updated progress.md reflecting a status change.
+ * Generate updated ## Progress content reflecting a status change.
  */
 export function generateProgressUpdate(spec, previousStatus, existingContent) {
     const timestamp = new Date().toISOString();

package/dist/engine/spec-format/lean-technical-generator.d.ts

@@ -1,5 +1,5 @@
 import type { LeanFileEntry, LeanTechnicalInput } from '../../types/index.js';
 export type { LeanFileEntry, LeanTechnicalInput };
-/** Generate lean technical.md content: YAML frontmatter + files section only. */
+/** Generate lean ## Technical content: YAML-like metadata + files section only. */
 export declare function generateLeanTechnicalContent(input: LeanTechnicalInput): string;
 //# sourceMappingURL=lean-technical-generator.d.ts.map

package/dist/engine/spec-format/lean-technical-generator.js

@@ -1,6 +1,6 @@
-// engine/spec-format/lean-technical-generator.ts — Generates lean technical.md (SPEC-461)
+// engine/spec-format/lean-technical-generator.ts — Generates lean ## Technical content (SPEC-461)
 // Output: ~15-20 lines. Only files section with create/modify/test and pending/done status.
-/** Generate lean technical.md content: YAML frontmatter + files section only. */
+/** Generate lean ## Technical content: YAML-like metadata + files section only. */
 export function generateLeanTechnicalContent(input) {
     const { specId, filesToCreate = [], filesToModify = [], filesToTest = [] } = input;
     const lines = ['---', `spec: ${specId}`, '---', '', '## Files', ''];

package/dist/engine/spec-format/technical-md-populator.d.ts

@@ -1,6 +1,6 @@
 import type { LeanFileEntry } from '../../types/index.js';
 /**
- * Attempt to extract file paths from spec body for auto-populating technical.md.
+ * Attempt to extract file paths from spec body for auto-populating ## Technical.
  * Returns null when no structured file section is found (caller uses placeholder).
  */
 export declare function extractFilesFromSpecBody(specBody: string, projectPath: string): Promise<{

package/dist/engine/spec-format/technical-md-populator.js

@@ -1,4 +1,4 @@
-// engine/spec-format/technical-md-populator.ts — SPEC-586: Parse spec body to populate technical.md
+// engine/spec-format/technical-md-populator.ts — SPEC-586: Parse spec body to populate ## Technical
 import { stat } from 'node:fs/promises';
 import { join } from 'node:path';
 const FILE_PATH_RE = /\b(src|tests)\/[\w/-]+\.[a-z]+\b/g;
@@ -52,7 +52,7 @@ async function categorizeByExistence(paths, projectPath) {
     return { create, modify, test: [] };
 }
 /**
- * Attempt to extract file paths from spec body for auto-populating technical.md.
+ * Attempt to extract file paths from spec body for auto-populating ## Technical.
  * Returns null when no structured file section is found (caller uses placeholder).
  */
 export async function extractFilesFromSpecBody(specBody, projectPath) {

package/dist/tools/sync-spec-state-handler.js

@@ -11,6 +11,7 @@ import { handleUpdateStatus } from './update-status/index.js';
 import { parseFrontmatter } from '../engine/frontmatter-parser.js';
 import { verifyTerminalFrontmatter } from '../engine/frontmatter-sha/index.js';
 import { appendTransitionEvent } from '../storage/transition-log.js';
+import { cleanEphemeralArtifacts } from '../engine/housekeeping/index.js';
 import { readFile } from 'node:fs/promises';
 // ---------------------------------------------------------------------------
 // Sync helpers (exported for startup use)
@@ -155,6 +156,12 @@ export async function startupSync() {
         catch (err) {
             console.error(`[Planu] startupSync: failed to sync project ${project.path}:`, err);
         }
+        try {
+            await cleanEphemeralArtifacts({ projectPath: project.path, dryRun: false });
+        }
+        catch (err) {
+            console.error(`[Planu] startupSync: failed to clean spec artifacts ${project.path}:`, err);
+        }
     }));
 }
 // ---------------------------------------------------------------------------

package/dist/tools/update-status/index.js

@@ -788,7 +788,7 @@ export async function handleUpdateStatus(params, server) {
                 }
                 // SPEC-694: Auto-orchestration plan for cross-module/architectural specs on approved
                 const orchestrationPlan = await resolveOrchestrationPlan(newStatus, spec.scope, specId, effectiveGatePath);
-                // Sync spec.md frontmatter and progress.md
+                // Sync spec.md frontmatter and inline ## Progress section.
                 // SPEC-698: capture warning so it surfaces in the tool response (was silent before)
                 const syncResult = await syncSpecFiles(updatedSpec, originalStatus, newStatus, effectiveGatePath);
                 const frontmatterSyncWarnings = syncResult.warning ? [syncResult.warning] : [];

package/dist/types/impact-detection.d.ts

@@ -13,6 +13,12 @@ export interface TestBreakHit {
     matchedPattern: 'tool-count' | 'snapshot' | 'license-plans-sync' | 'streams-anchor';
     linePreview: string;
 }
+export type AnticipatedBreakPattern = 'tool-count' | 'snapshot' | 'license-plans-sync' | 'streams-anchor' | 'other';
+export interface AnticipatedBreak {
+    testPath: string;
+    pattern: AnticipatedBreakPattern;
+    remediation: string;
+}
 export interface ImpactDetectorInput {
     specId: string;
     specPath: string;

package/dist/types/index.d.ts

@@ -235,7 +235,6 @@ export * from './storage.js';
 export * from './observatory.js';
 export * from './orphan-spec-refs.js';
 export * from './session-safeguard.js';
-export * from './implementation-brief.js';
 export * from './impact-detection.js';
 export * from './criteria-injection.js';
 export * from './gemini.js';

package/dist/types/index.js

@@ -232,7 +232,6 @@ export * from './storage.js';
 export * from './observatory.js';
 export * from './orphan-spec-refs.js';
 export * from './session-safeguard.js';
-export * from './implementation-brief.js';
 export * from './impact-detection.js';
 export * from './criteria-injection.js';
 export * from './gemini.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "3.9.12",
+  "version": "3.9.14",
   "description": "Planu — MCP Server for Spec Driven Development with native Rust acceleration for hot paths. Cross-platform (Linux/macOS/Windows, x64/arm64, glibc/musl).",
   "type": "module",
   "main": "dist/index.js",
@@ -32,12 +32,12 @@
     "packageName": "@planu/core"
   },
   "optionalDependencies": {
-    "@planu/core-darwin-arm64": "3.9.10",
-    "@planu/core-darwin-x64": "3.9.10",
-    "@planu/core-linux-arm64-gnu": "3.9.10",
-    "@planu/core-linux-arm64-musl": "3.9.10",
-    "@planu/core-linux-x64-gnu": "3.9.10",
-    "@planu/core-linux-x64-musl": "3.9.10"
+    "@planu/core-darwin-arm64": "3.9.14",
+    "@planu/core-darwin-x64": "3.9.14",
+    "@planu/core-linux-arm64-gnu": "3.9.14",
+    "@planu/core-linux-arm64-musl": "3.9.14",
+    "@planu/core-linux-x64-gnu": "3.9.14",
+    "@planu/core-linux-x64-musl": "3.9.14"
   },
   "engines": {
     "node": ">=24.0.0"

package/dist/engine/implementation-brief/convention-extractor.d.ts

@@ -1,5 +0,0 @@
-import type { ConventionExcerpt } from '../../types/index.js';
-export declare function extractConventions(projectPath: string, tags: string[], target: string, scope: string): Promise<{
-    excerpts: ConventionExcerpt[];
-}>;
-//# sourceMappingURL=convention-extractor.d.ts.map

package/dist/engine/implementation-brief/convention-extractor.js

@@ -1,75 +0,0 @@
-// engine/implementation-brief/convention-extractor.ts — SPEC-586: Filter .claude/rules/ by tags
-import { readdir, readFile } from 'node:fs/promises';
-import { join } from 'node:path';
-const MAX_EXCERPT_CHARS = 400;
-const MAX_RULES = 3;
-const TAG_TO_RULE = {
-    backend: ['typescript-eslint.md', 'architecture.md'],
-    frontend: ['typescript-eslint.md'],
-    testing: ['testing.md'],
-    test: ['testing.md'],
-    git: ['git-workflow.md'],
-    autopilot: ['autopilot-first.md'],
-    spec: ['sdd-methodology.md'],
-    parallel: ['parallel-sessions.md'],
-};
-function rulesForTags(tags, target, scope) {
-    const selected = new Set();
-    const combined = [...tags, target, scope].map((t) => t.toLowerCase());
-    for (const term of combined) {
-        for (const [key, rules] of Object.entries(TAG_TO_RULE)) {
-            if (term.includes(key)) {
-                for (const r of rules) {
-                    selected.add(r);
-                }
-            }
-        }
-    }
-    if (combined.some((t) => t === 'backend' || t === 'fullstack')) {
-        selected.add('architecture.md');
-    }
-    return [...selected].slice(0, MAX_RULES);
-}
-async function readExcerpt(rulesDir, ruleFile) {
-    try {
-        const content = await readFile(join(rulesDir, ruleFile), 'utf-8');
-        const lines = content.split('\n');
-        let excerpt = '';
-        for (const line of lines) {
-            if (excerpt.length + line.length > MAX_EXCERPT_CHARS) {
-                break;
-            }
-            excerpt += line + '\n';
-        }
-        return excerpt.trim();
-    }
-    catch {
-        return '';
-    }
-}
-async function listRuleFiles(rulesDir) {
-    try {
-        const entries = await readdir(rulesDir);
-        return entries.filter((e) => e.endsWith('.md'));
-    }
-    catch {
-        return [];
-    }
-}
-export async function extractConventions(projectPath, tags, target, scope) {
-    const rulesDir = join(projectPath, '.claude', 'rules');
-    const available = await listRuleFiles(rulesDir);
-    if (available.length === 0) {
-        return { excerpts: [] };
-    }
-    const wanted = rulesForTags(tags, target, scope).filter((r) => available.includes(r));
-    const excerpts = [];
-    for (const ruleFile of wanted) {
-        const excerpt = await readExcerpt(rulesDir, ruleFile);
-        if (excerpt) {
-            excerpts.push({ rule: ruleFile, excerpt });
-        }
-    }
-    return { excerpts };
-}
-//# sourceMappingURL=convention-extractor.js.map

package/dist/engine/implementation-brief/extension-points.d.ts

@@ -1,2 +0,0 @@
-export declare function enumerateExtensionPoints(projectPath: string): Promise<string[]>;
-//# sourceMappingURL=extension-points.d.ts.map

package/dist/engine/implementation-brief/extension-points.js

@@ -1,32 +0,0 @@
-// engine/implementation-brief/extension-points.ts — SPEC-586: Enumerate plugin registry paths
-import { stat } from 'node:fs/promises';
-import { join } from 'node:path';
-const REGISTRY_PATHS = [
-    'src/tools/create-spec/adapters',
-    'src/engine/detectors',
-    'src/tools/generate-tests/generators',
-    'src/config',
-    'src/engine/autopilot',
-    'src/engine/implementation-brief',
-    'src/engine/impact-detector',
-];
-async function exists(p) {
-    try {
-        await stat(p);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-export async function enumerateExtensionPoints(projectPath) {
-    const found = [];
-    for (const rel of REGISTRY_PATHS) {
-        const full = join(projectPath, rel);
-        if (await exists(full)) {
-            found.push(rel);
-        }
-    }
-    return found;
-}
-//# sourceMappingURL=extension-points.js.map

package/dist/engine/implementation-brief/generator.d.ts

@@ -1,3 +0,0 @@
-import type { ImplementationBriefInput } from '../../types/index.js';
-export declare function generateImplementationBrief(input: ImplementationBriefInput): Promise<void>;
-//# sourceMappingURL=generator.d.ts.map

package/dist/engine/implementation-brief/generator.js

@@ -1,139 +0,0 @@
-// engine/implementation-brief/generator.ts — SPEC-586: Orchestrate implementation brief generation
-import { writeFile, mkdir } from 'node:fs/promises';
-import { join, dirname } from 'node:path';
-import { scanReusableHelpers } from './helpers-scanner.js';
-import { findTestPatterns } from './test-pattern-matcher.js';
-import { extractConventions } from './convention-extractor.js';
-import { enumerateExtensionPoints } from './extension-points.js';
-import { predictTestBreaks } from '../impact-detector/test-break-predictor.js';
-const MAX_HELPERS = 10;
-function renderBrief(brief) {
-    const lines = [];
-    lines.push(`# Implementation Brief — ${brief.specId}`);
-    lines.push(`_Generated ${brief.generatedAt}_`);
-    lines.push('');
-    lines.push('## Reusable helpers');
-    if (brief.reusableHelpers.length === 0) {
-        lines.push('_None found._');
-    }
-    else {
-        for (const h of brief.reusableHelpers) {
-            lines.push(`- **${h.symbol}** — \`${h.path}:${h.line}\` — ${h.purpose}`);
-        }
-    }
-    lines.push('');
-    lines.push('## Test patterns');
-    if (brief.testPatterns.length === 0) {
-        lines.push('_No similar tests found._');
-    }
-    else {
-        for (const t of brief.testPatterns) {
-            lines.push(`- \`${t.testPath}\` — ${t.whyRelevant}`);
-        }
-    }
-    lines.push('');
-    lines.push('## Applicable conventions');
-    if (brief.conventions.excerpts.length === 0) {
-        lines.push('_No matching rules found._');
-    }
-    else {
-        for (const e of brief.conventions.excerpts) {
-            lines.push(`### ${e.rule}`);
-            lines.push('');
-            lines.push(e.excerpt);
-            lines.push('');
-        }
-    }
-    lines.push('## Existing extension points');
-    if (brief.extensionPoints.length === 0) {
-        lines.push('_None detected._');
-    }
-    else {
-        for (const ep of brief.extensionPoints) {
-            lines.push(`- \`${ep}\``);
-        }
-    }
-    lines.push('');
-    lines.push('## Anticipated test breaks');
-    if (brief.anticipatedBreaks.length === 0) {
-        lines.push('_No anticipated breaks detected._');
-    }
-    else {
-        for (const b of brief.anticipatedBreaks) {
-            lines.push(`- \`${b.testPath}\` — pattern: **${b.pattern}** — ${b.remediation}`);
-        }
-    }
-    lines.push('');
-    return lines.join('\n');
-}
-function renderPrompt(specId, description, brief) {
-    const lines = [];
-    lines.push(`# Implementation prompt — ${specId}`);
-    lines.push('');
-    // What to build — first non-empty line of description (up to 120 chars)
-    const goal = description
-        .split('\n')
-        .find((l) => l.trim().length > 0)
-        ?.slice(0, 120) ?? specId;
-    lines.push('## What to build');
-    lines.push(goal.trim());
-    lines.push('');
-    /* v8 ignore start */
-    // Files to CREATE — infer from helpers/extension points
-    if (brief.extensionPoints.length > 0) {
-        lines.push('## Files to CREATE (exact paths)');
-        for (const ep of brief.extensionPoints.slice(0, 5)) {
-            lines.push(`- ${ep}`);
-        }
-        lines.push('');
-    }
-    // Reusable helpers — key symbols to import (avoids discovery)
-    if (brief.reusableHelpers.length > 0) {
-        lines.push('## Reusable helpers (import, do not rewrite)');
-        for (const h of brief.reusableHelpers.slice(0, 5)) {
-            lines.push(`- \`${h.symbol}\` from \`${h.path}\` — ${h.purpose}`);
-        }
-        lines.push('');
-    }
-    // Anticipated test breaks
-    if (brief.anticipatedBreaks.length > 0) {
-        lines.push('## Tests that will break (exact fixes)');
-        for (const b of brief.anticipatedBreaks) {
-            lines.push(`- \`${b.testPath}\` — ${b.remediation}`);
-        }
-        lines.push('');
-    }
-    /* v8 ignore stop */
-    lines.push('## Verify with');
-    lines.push('```');
-    lines.push('pnpm typecheck && pnpm lint && pnpm test');
-    lines.push('```');
-    return lines.join('\n');
-}
-export async function generateImplementationBrief(input) {
-    const { specId, specPath, projectPath, description, tags, target, scope } = input;
-    const [helpers, testPatterns, conventions, extensionPoints, anticipatedBreaks] = await Promise.all([
-        scanReusableHelpers(projectPath, description, tags).catch(() => []),
-        findTestPatterns(projectPath, description, tags, scope).catch(() => []),
-        extractConventions(projectPath, tags, target, scope).catch(() => ({ excerpts: [] })),
-        enumerateExtensionPoints(projectPath).catch(() => []),
-        predictTestBreaks(projectPath).catch(() => []),
-    ]);
-    const brief = {
-        specId,
-        generatedAt: new Date().toISOString(),
-        reusableHelpers: helpers.slice(0, MAX_HELPERS),
-        testPatterns,
-        conventions,
-        extensionPoints,
-        anticipatedBreaks,
-    };
-    const specDir = dirname(specPath);
-    await mkdir(specDir, { recursive: true });
-    // Write both implementation-brief.md and prompt.md (SPEC-629) in parallel
-    await Promise.all([
-        writeFile(join(specDir, 'implementation-brief.md'), renderBrief(brief), 'utf-8'),
-        writeFile(join(specDir, 'prompt.md'), renderPrompt(specId, description, brief), 'utf-8'),
-    ]);
-}
-//# sourceMappingURL=generator.js.map

package/dist/engine/implementation-brief/helpers-scanner.d.ts

@@ -1,3 +0,0 @@
-import type { ReusableHelper } from '../../types/index.js';
-export declare function scanReusableHelpers(projectPath: string, description: string, tags: string[]): Promise<ReusableHelper[]>;
-//# sourceMappingURL=helpers-scanner.d.ts.map

package/dist/engine/implementation-brief/helpers-scanner.js

@@ -1,163 +0,0 @@
-// engine/implementation-brief/helpers-scanner.ts — SPEC-586: Semantic search for reusable helpers
-import { readdir, readFile, stat } from 'node:fs/promises';
-import { join, relative, extname } from 'node:path';
-const MAX_FILES = 300;
-const MAX_DEPTH = 4;
-const TOP_N = 10;
-const CODE_EXT = new Set(['.ts', '.js', '.py', '.go', '.rs', '.java', '.kt', '.rb', '.cs']);
-function extractKeywords(text) {
-    return text
-        .toLowerCase()
-        .replace(/[^a-z0-9\s-]/g, ' ')
-        .split(/\s+/)
-        .filter((w) => w.length > 3)
-        .filter((w) => !STOP_WORDS.has(w));
-}
-const STOP_WORDS = new Set([
-    'this',
-    'that',
-    'with',
-    'from',
-    'have',
-    'will',
-    'when',
-    'then',
-    'given',
-    'spec',
-    'planu',
-    'tool',
-    'file',
-    'path',
-    'type',
-    'into',
-    'also',
-    'each',
-    'only',
-    'over',
-    'such',
-    'more',
-    'some',
-    'after',
-    'must',
-]);
-function scoreText(text, keywords) {
-    const lower = text.toLowerCase();
-    let score = 0;
-    for (const kw of keywords) {
-        if (lower.includes(kw)) {
-            score += kw.length;
-        }
-    }
-    return score;
-}
-async function scanDir(dir, projectPath, keywords, results, depth, budget) {
-    if (depth > MAX_DEPTH || budget.remaining <= 0) {
-        return;
-    }
-    let entries;
-    try {
-        entries = await readdir(dir);
-    }
-    catch {
-        return;
-    }
-    for (const entry of entries) {
-        if (budget.remaining <= 0) {
-            break;
-        }
-        if (entry.startsWith('.') || entry === 'node_modules' || entry === 'dist') {
-            continue;
-        }
-        const full = join(dir, entry);
-        let s;
-        try {
-            s = await stat(full);
-        }
-        catch {
-            continue;
-        }
-        if (s.isDirectory()) {
-            await scanDir(full, projectPath, keywords, results, depth + 1, budget);
-        }
-        else if (CODE_EXT.has(extname(entry))) {
-            const b = budget;
-            b.remaining -= 1;
-            const rel = relative(projectPath, full);
-            const score = scoreText(rel, keywords);
-            if (score > 0) {
-                results.push({ path: rel, score });
-            }
-        }
-    }
-}
-function parseFunctionSymbol(line) {
-    const match = /export\s+(?:async\s+)?function\s+(\w+)|export\s+const\s+(\w+)\s*=|export\s+(?:type|interface|class)\s+(\w+)/.exec(line);
-    if (!match) {
-        return null;
-    }
-    return match[1] ?? match[2] ?? match[3] ?? null;
-}
-function extractPurpose(lines, exportLine) {
-    for (let i = exportLine - 1; i >= Math.max(0, exportLine - 3); i--) {
-        const line = lines[i]?.trim() ?? '';
-        if (line.startsWith('//') || line.startsWith('*') || line.startsWith('/**')) {
-            return line.replace(/^[/*\s]+/, '').slice(0, 80);
-        }
-    }
-    return 'helper function';
-}
-async function extractHelpers(filePath, keywords, projectPath) {
-    let content;
-    try {
-        content = await readFile(filePath, 'utf-8');
-    }
-    catch {
-        return [];
-    }
-    const lines = content.split('\n');
-    const helpers = [];
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i] ?? '';
-        if (!line.includes('export')) {
-            continue;
-        }
-        const symbol = parseFunctionSymbol(line);
-        if (!symbol) {
-            continue;
-        }
-        const symbolScore = scoreText(symbol, keywords);
-        if (symbolScore === 0) {
-            continue;
-        }
-        helpers.push({
-            symbol,
-            path: relative(projectPath, filePath),
-            line: i + 1,
-            purpose: extractPurpose(lines, i),
-        });
-    }
-    return helpers;
-}
-export async function scanReusableHelpers(projectPath, description, tags) {
-    const srcDir = join(projectPath, 'src');
-    const keywords = extractKeywords(`${description} ${tags.join(' ')}`);
-    if (keywords.length === 0) {
-        return [];
-    }
-    const candidates = [];
-    const budget = { remaining: MAX_FILES };
-    await scanDir(srcDir, projectPath, keywords, candidates, 0, budget);
-    candidates.sort((a, b) => b.score - a.score);
-    const top = candidates.slice(0, 20);
-    const helpers = [];
-    for (const c of top) {
-        const full = join(projectPath, c.path);
-        const extracted = await extractHelpers(full, keywords, projectPath);
-        helpers.push(...extracted);
-        if (helpers.length >= TOP_N) {
-            break;
-        }
-    }
-    return helpers.slice(0, TOP_N);
-}
-//# sourceMappingURL=helpers-scanner.js.map

package/dist/engine/implementation-brief/test-pattern-matcher.d.ts

@@ -1,3 +0,0 @@
-import type { TestPatternMatch } from '../../types/index.js';
-export declare function findTestPatterns(projectPath: string, description: string, tags: string[], scope: string): Promise<TestPatternMatch[]>;
-//# sourceMappingURL=test-pattern-matcher.d.ts.map

package/dist/engine/implementation-brief/test-pattern-matcher.js

@@ -1,90 +0,0 @@
-// engine/implementation-brief/test-pattern-matcher.ts — SPEC-586: Find similar test patterns
-import { readdir, stat } from 'node:fs/promises';
-import { join, relative } from 'node:path';
-const MAX_TEST_FILES = 200;
-const TOP_N = 3;
-function extractKeywords(text) {
-    return text
-        .toLowerCase()
-        .replace(/[^a-z0-9\s]/g, ' ')
-        .split(/\s+/)
-        .filter((w) => w.length > 3);
-}
-function scoreMatch(filePath, keywords) {
-    const lower = filePath.toLowerCase();
-    let score = 0;
-    for (const kw of keywords) {
-        if (lower.includes(kw)) {
-            score += kw.length;
-        }
-    }
-    return score;
-}
-async function collectTestFiles(dir, results, budget, depth) {
-    if (budget.remaining <= 0 || depth > 5) {
-        return;
-    }
-    let entries;
-    try {
-        entries = await readdir(dir);
-    }
-    catch {
-        return;
-    }
-    for (const entry of entries) {
-        if (budget.remaining <= 0) {
-            break;
-        }
-        if (entry.startsWith('.') || entry === 'node_modules') {
-            continue;
-        }
-        const full = join(dir, entry);
-        let s;
-        try {
-            s = await stat(full);
-        }
-        catch {
-            continue;
-        }
-        if (s.isDirectory()) {
-            await collectTestFiles(full, results, budget, depth + 1);
-        }
-        else if (entry.endsWith('.test.ts') || entry.endsWith('.test.js')) {
-            const b = budget;
-            b.remaining -= 1;
-            results.push(full);
-        }
-    }
-}
-function explainRelevance(filePath, keywords) {
-    const matched = [];
-    const lower = filePath.toLowerCase();
-    for (const kw of keywords) {
-        if (lower.includes(kw)) {
-            matched.push(kw);
-        }
-    }
-    return matched.length > 0
-        ? `matches keywords: ${matched.slice(0, 3).join(', ')}`
-        : 'structural similarity';
-}
-export async function findTestPatterns(projectPath, description, tags, scope) {
-    const testsDir = join(projectPath, 'tests');
-    const keywords = extractKeywords(`${description} ${tags.join(' ')} ${scope}`);
-    if (keywords.length === 0) {
-        return [];
-    }
-    const testFiles = [];
-    const budget = { remaining: MAX_TEST_FILES };
-    await collectTestFiles(testsDir, testFiles, budget, 0);
-    const scored = testFiles
-        .map((f) => ({ path: f, score: scoreMatch(relative(projectPath, f), keywords) }))
-        .filter((x) => x.score > 0)
-        .sort((a, b) => b.score - a.score)
-        .slice(0, TOP_N);
-    return scored.map((s) => ({
-        testPath: relative(projectPath, s.path),
-        whyRelevant: explainRelevance(relative(projectPath, s.path), keywords),
-    }));
-}
-//# sourceMappingURL=test-pattern-matcher.js.map

package/dist/engine/risk-analyzer/risk-generator.d.ts

@@ -1,6 +0,0 @@
-import type { RiskAnalysisContext, RiskRegister } from '../../types/index.js';
-/**
- * Generate an initial risk register from spec metadata.
- */
-export declare function generateRiskRegister(ctx: RiskAnalysisContext, totalBudget?: number): RiskRegister;
-//# sourceMappingURL=risk-generator.d.ts.map

package/dist/engine/risk-analyzer/risk-generator.js

@@ -1,94 +0,0 @@
-function buildRiskTemplates(ctx) {
-    const templates = [];
-    if (ctx.difficulty >= 4) {
-        templates.push({
-            description: 'High complexity may lead to estimation overrun',
-            category: 'technical',
-            probability: 40,
-            impactDays: 3,
-            mitigationPlan: 'Break down into smaller tasks and reassess estimates',
-        });
-    }
-    if (ctx.scope === 'cross-module' || ctx.scope === 'architectural') {
-        templates.push({
-            description: 'Cross-module changes risk breaking existing integrations',
-            category: 'integration',
-            probability: 35,
-            impactDays: 2,
-            mitigationPlan: 'Add integration tests covering all affected modules before merging',
-        });
-    }
-    if (ctx.dependencyCount > 3) {
-        templates.push({
-            description: 'Multiple dependencies increase coordination overhead',
-            category: 'dependency',
-            probability: 30,
-            impactDays: 2,
-            mitigationPlan: 'Establish dependency contracts early and monitor for version conflicts',
-        });
-    }
-    if (ctx.risk === 'high' || ctx.risk === 'critical') {
-        templates.push({
-            description: 'Spec flagged as high-risk requires extra review',
-            category: 'organizational',
-            probability: 50,
-            impactDays: 3,
-            mitigationPlan: 'Schedule mandatory peer review and add approval gates before deployment',
-        });
-    }
-    if (ctx.tags.includes('security')) {
-        templates.push({
-            description: 'Security-sensitive changes require audit',
-            category: 'security',
-            probability: 25,
-            impactDays: 4,
-            mitigationPlan: 'Engage security team for review and run SAST/DAST tools',
-        });
-    }
-    if (ctx.fileCount > 10) {
-        templates.push({
-            description: 'Large number of files increases merge conflict risk',
-            category: 'technical',
-            probability: 30,
-            impactDays: 1,
-            mitigationPlan: 'Use feature flags and incremental PRs to reduce merge surface',
-        });
-    }
-    return templates;
-}
-function buildRisks(ctx, templates) {
-    return templates.map((t, index) => ({
-        id: `R${index + 1}`,
-        description: t.description,
-        category: t.category,
-        probability: t.probability,
-        impactUsd: 0,
-        impactDays: t.impactDays,
-        owner: '',
-        status: 'identified',
-        mitigationPlan: t.mitigationPlan,
-        specId: ctx.specId,
-    }));
-}
-function computeAggregateScore(risks, totalBudgetDays) {
-    const rawScore = risks.reduce((acc, r) => acc + (r.probability / 100) * r.impactDays, 0);
-    const denominator = Math.max(totalBudgetDays, 1);
-    const score = (rawScore / denominator) * 100;
-    return Math.min(score, 100);
-}
-/**
- * Generate an initial risk register from spec metadata.
- */
-export function generateRiskRegister(ctx, totalBudget) {
-    const budgetDays = totalBudget ?? 30;
-    const templates = buildRiskTemplates(ctx);
-    const risks = buildRisks(ctx, templates);
-    const aggregateRiskScore = computeAggregateScore(risks, budgetDays);
-    return {
-        specId: ctx.specId,
-        risks,
-        aggregateRiskScore,
-        generatedAt: new Date().toISOString(),
-    };
-}
-//# sourceMappingURL=risk-generator.js.map

package/dist/types/implementation-brief.d.ts

@@ -1,41 +0,0 @@
-export interface ReusableHelper {
-    symbol: string;
-    path: string;
-    line: number;
-    purpose: string;
-}
-export interface TestPatternMatch {
-    testPath: string;
-    whyRelevant: string;
-}
-export interface ConventionExcerpt {
-    rule: string;
-    excerpt: string;
-}
-export type AnticipatedBreakPattern = 'tool-count' | 'snapshot' | 'license-plans-sync' | 'streams-anchor' | 'other';
-export interface AnticipatedBreak {
-    testPath: string;
-    pattern: AnticipatedBreakPattern;
-    remediation: string;
-}
-export interface ImplementationBrief {
-    specId: string;
-    generatedAt: string;
-    reusableHelpers: ReusableHelper[];
-    testPatterns: TestPatternMatch[];
-    conventions: {
-        excerpts: ConventionExcerpt[];
-    };
-    extensionPoints: string[];
-    anticipatedBreaks: AnticipatedBreak[];
-}
-export interface ImplementationBriefInput {
-    specId: string;
-    specPath: string;
-    projectPath: string;
-    description: string;
-    tags: string[];
-    target: string;
-    scope: string;
-}
-//# sourceMappingURL=implementation-brief.d.ts.map

package/dist/types/implementation-brief.js

@@ -1,3 +0,0 @@
-// types/implementation-brief.ts — SPEC-586: Implementation brief types
-export {};
-//# sourceMappingURL=implementation-brief.js.map