@planu/cli 3.9.13 → 4.0.0

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

@@ -13,4 +13,5 @@ export { findLegacyMultiFileSpecs } from './find-legacy-multifile-specs.js';
 export { foldTechnicalIntoSpec } from './fold-technical.js';
 export { foldProgressIntoSpec, isBoilerplateProgress } from './fold-progress.js';
 export { runSsrBackMigration } from './ssr-back-migration.js';
+export { PLANU_CANONICAL_POLICY, runStrictPlanuCleanup, validateStrictPlanuLayout, } from './strict-planu-cleanup.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -26,4 +26,5 @@ export { findLegacyMultiFileSpecs } from './find-legacy-multifile-specs.js';
 export { foldTechnicalIntoSpec } from './fold-technical.js';
 export { foldProgressIntoSpec, isBoilerplateProgress } from './fold-progress.js';
 export { runSsrBackMigration } from './ssr-back-migration.js';
+export { PLANU_CANONICAL_POLICY, runStrictPlanuCleanup, validateStrictPlanuLayout, } from './strict-planu-cleanup.js';
 //# sourceMappingURL=index.js.map

package/dist/engine/spec-migrator/planu-canonical-policy.d.ts

@@ -0,0 +1,9 @@
+import type { PlanuCanonicalPathPolicy } from '../../types/index.js';
+export declare const PLANU_CANONICAL_POLICY: PlanuCanonicalPathPolicy;
+export declare function isCanonicalPlanuRootFile(name: string): boolean;
+export declare function isCanonicalPlanuRootDir(name: string): boolean;
+export declare function isCanonicalSpecFile(name: string): boolean;
+export declare function mustMergeBeforeDeleteSpecFile(name: string): boolean;
+export declare function isCanonicalReleaseFile(relativeToPlanu: string): boolean;
+export declare function canonicalContractText(): string;
+//# sourceMappingURL=planu-canonical-policy.d.ts.map

package/dist/engine/spec-migrator/planu-canonical-policy.js

@@ -0,0 +1,62 @@
+// engine/spec-migrator/planu-canonical-policy.ts — SPEC-1017
+// Single source of truth for the strict Planu managed directory contract.
+export const PLANU_CANONICAL_POLICY = {
+    canonicalRootFiles: ['conventions.json', 'context.md', 'session-context.md', 'session.json'],
+    canonicalRootDirs: ['releases', 'specs'],
+    canonicalSpecFiles: ['spec.md'],
+    generatedRuntimePatterns: [
+        'planu/index.html',
+        'planu/roadmap.html',
+        'planu/status.json',
+        'planu/CHANGELOG.md',
+        'planu/.housekeeping-history.jsonl',
+        'planu/audits/',
+        'planu/handoffs/',
+        'planu/data/',
+        'planu/state/',
+        'planu/.locks/',
+        'planu/specs/data/',
+        'planu/specs/*/technical-report.html',
+        'planu/specs/*/reference/',
+        'planu/specs/*/test-stubs.ts',
+        'planu/specs/*/.analysis.json',
+        'planu/specs/*/prompt.md',
+        'planu/specs/*/implementation-brief.md',
+        'planu/specs/*/risk-register.md',
+    ],
+    legacyMergeBeforeDeleteFiles: ['technical.md', 'plan.md', 'PLAN.md', 'progress.md'],
+};
+const ROOT_FILE_SET = new Set(PLANU_CANONICAL_POLICY.canonicalRootFiles);
+const ROOT_DIR_SET = new Set(PLANU_CANONICAL_POLICY.canonicalRootDirs);
+const SPEC_FILE_SET = new Set(PLANU_CANONICAL_POLICY.canonicalSpecFiles);
+const LEGACY_MERGE_SET = new Set(PLANU_CANONICAL_POLICY.legacyMergeBeforeDeleteFiles);
+export function isCanonicalPlanuRootFile(name) {
+    return ROOT_FILE_SET.has(name);
+}
+export function isCanonicalPlanuRootDir(name) {
+    return ROOT_DIR_SET.has(name);
+}
+export function isCanonicalSpecFile(name) {
+    return SPEC_FILE_SET.has(name);
+}
+export function mustMergeBeforeDeleteSpecFile(name) {
+    return LEGACY_MERGE_SET.has(name);
+}
+export function isCanonicalReleaseFile(relativeToPlanu) {
+    return relativeToPlanu === 'releases/pending.json';
+}
+export function canonicalContractText() {
+    return [
+        'planu/',
+        '  conventions.json',
+        '  context.md',
+        '  session-context.md',
+        '  session.json',
+        '  releases/',
+        '    pending.json',
+        '  specs/',
+        '    SPEC-XXX-slug/',
+        '      spec.md',
+    ].join('\n');
+}
+//# sourceMappingURL=planu-canonical-policy.js.map

package/dist/engine/spec-migrator/planu-root-cleaner.js

@@ -1,101 +1,25 @@
-// engine/spec-migrator/planu-root-cleaner.ts — SPEC-464: Clean non-canonical files from planu/
-// Canonical structure: specs/ + status.json + conventions.json + index.html + roadmap.html
-import { readdir, stat } from 'node:fs/promises';
-import { execFileSync } from 'node:child_process';
-import { join, relative } from 'node:path';
-import { safeUnlink } from './git-aware-fs.js';
-/** Files allowed in planu/ root. Everything else gets deleted. */
-const CANONICAL_ROOT_FILES = new Set([
-    'status.json',
-    'conventions.json',
-    'index.html',
-    'roadmap.html',
-]);
-/** Directories allowed in planu/ root. */
-const CANONICAL_ROOT_DIRS = new Set(['specs']);
-/** Files allowed inside each planu/specs/SPEC-XXX/ directory. */
-const CANONICAL_SPEC_FILES = new Set(['spec.md']);
-/** Remove a file from git tracking (best-effort, silent if not a git repo or file not tracked). */
-function gitRmCached(absolutePath, cwd) {
-    try {
-        const rel = relative(cwd, absolutePath);
-        execFileSync('git', ['rm', '--cached', '--quiet', '--force', rel], {
-            cwd,
-            stdio: ['pipe', 'pipe', 'pipe'],
-            timeout: 3_000,
-        });
-    }
-    catch {
-        // Not a git repo, file not tracked, or git not available — ignore
-    }
-}
+// engine/spec-migrator/planu-root-cleaner.ts — SPEC-1017 strict wrapper
+import { dirname } from 'node:path';
+import { runStrictPlanuCleanup } from './strict-planu-cleanup.js';
 /** Remove all non-canonical files from planu/ root and per-spec directories. */
 export async function cleanPlanuRoot(planuDir, projectPath) {
-    const result = {
-        deletedRootFiles: [],
-        deletedSpecFiles: [],
-        totalDeleted: 0,
-    };
-    // 1. Clean planu/ root
-    let entries;
-    try {
-        entries = await readdir(planuDir);
-    }
-    catch {
-        return result; // Dir doesn't exist — nothing to clean
-    }
-    for (const entry of entries) {
-        const fullPath = join(planuDir, entry);
-        try {
-            const info = await stat(fullPath);
-            if (info.isDirectory()) {
-                if (!CANONICAL_ROOT_DIRS.has(entry)) {
-                    // Non-canonical directory — skip (don't delete dirs recursively for safety)
-                    continue;
-                }
-            }
-            else if (!CANONICAL_ROOT_FILES.has(entry)) {
-                gitRmCached(fullPath, planuDir);
-                await safeUnlink(projectPath ?? planuDir, fullPath);
-                result.deletedRootFiles.push(entry);
-            }
+    const root = projectPath ?? dirname(planuDir);
+    const strict = await runStrictPlanuCleanup(root);
+    const deletedRootFiles = [];
+    const deletedSpecFiles = [];
+    for (const path of [...strict.deleted, ...strict.merged]) {
+        const normalized = path.replace(/^planu\//, '');
+        if (normalized.startsWith('specs/')) {
+            deletedSpecFiles.push(normalized.replace(/^specs\//, ''));
         }
-        catch {
-            // File disappeared between readdir and stat — ignore
+        else {
+            deletedRootFiles.push(normalized);
         }
     }
-    // 2. Clean per-spec directories
-    const specsDir = join(planuDir, 'specs');
-    let specDirs;
-    try {
-        specDirs = await readdir(specsDir);
-    }
-    catch {
-        result.totalDeleted = result.deletedRootFiles.length;
-        return result;
-    }
-    for (const specDir of specDirs) {
-        const specPath = join(specsDir, specDir);
-        try {
-            const info = await stat(specPath);
-            if (!info.isDirectory()) {
-                continue;
-            }
-            const files = await readdir(specPath);
-            for (const file of files) {
-                if (!CANONICAL_SPEC_FILES.has(file)) {
-                    const filePath = join(specPath, file);
-                    gitRmCached(filePath, planuDir);
-                    await safeUnlink(projectPath ?? planuDir, filePath);
-                    result.deletedSpecFiles.push(`${specDir}/${file}`);
-                }
-            }
-        }
-        catch {
-            // Spec dir issue — skip
-        }
-    }
-    result.totalDeleted = result.deletedRootFiles.length + result.deletedSpecFiles.length;
-    return result;
+    return {
+        deletedRootFiles,
+        deletedSpecFiles,
+        totalDeleted: strict.deleted.length + strict.merged.length,
+    };
 }
 //# sourceMappingURL=planu-root-cleaner.js.map

package/dist/engine/spec-migrator/strict-planu-cleanup.d.ts

@@ -0,0 +1,6 @@
+import type { StrictPlanuCleanupResult, StrictPlanuValidationResult } from '../../types/index.js';
+import { PLANU_CANONICAL_POLICY } from './planu-canonical-policy.js';
+export declare function runStrictPlanuCleanup(projectPath: string): Promise<StrictPlanuCleanupResult>;
+export declare function validateStrictPlanuLayout(projectPath: string): Promise<StrictPlanuValidationResult>;
+export { PLANU_CANONICAL_POLICY };
+//# sourceMappingURL=strict-planu-cleanup.d.ts.map

package/dist/engine/spec-migrator/strict-planu-cleanup.js

@@ -0,0 +1,199 @@
+// engine/spec-migrator/strict-planu-cleanup.ts — SPEC-1017
+// Destructive cleanup for non-canonical files under planu/.
+import { readdir, readFile, rm, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { join, relative } from 'node:path';
+import { atomicWriteFile } from '../safety/atomic-write-file.js';
+import { safeUnlink } from './git-aware-fs.js';
+import { PLANU_CANONICAL_POLICY, canonicalContractText, isCanonicalPlanuRootDir, isCanonicalPlanuRootFile, isCanonicalReleaseFile, isCanonicalSpecFile, mustMergeBeforeDeleteSpecFile, } from './planu-canonical-policy.js';
+const execFileAsync = promisify(execFile);
+async function pathIsDirectory(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function gitRmCached(projectPath, relPath) {
+    if (!existsSync(join(projectPath, '.git'))) {
+        return;
+    }
+    try {
+        await execFileAsync('git', ['rm', '--cached', '--quiet', '--ignore-unmatch', relPath], {
+            cwd: projectPath,
+            timeout: 5_000,
+        });
+    }
+    catch {
+        /* best-effort */
+    }
+}
+function stripFrontmatter(content) {
+    return content.replace(/^---\n[\s\S]*?\n---\n?/, '').trim();
+}
+function appendSectionIfMissing(specContent, heading, body) {
+    if (body.trim().length === 0 || new RegExp(`\\n## ${heading}(\\n|$)`).test(specContent)) {
+        return specContent;
+    }
+    return `${specContent.trimEnd()}\n\n## ${heading}\n\n${body.trim()}\n`;
+}
+async function mergeLegacySpecFile(projectPath, specDir, fileName) {
+    const specPath = join(specDir, 'spec.md');
+    const legacyPath = join(specDir, fileName);
+    if (!existsSync(legacyPath) || !existsSync(specPath)) {
+        return false;
+    }
+    const [specContent, legacyContent] = await Promise.all([
+        readFile(specPath, 'utf-8'),
+        readFile(legacyPath, 'utf-8'),
+    ]);
+    const body = stripFrontmatter(legacyContent);
+    const section = fileName === 'progress.md' ? 'Progress' : fileName === 'technical.md' ? 'Technical' : 'Files';
+    const merged = appendSectionIfMissing(specContent, section, body);
+    if (merged !== specContent) {
+        await atomicWriteFile(specPath, merged, {
+            forceEdit: {
+                reason: `SPEC-1017 strict cleanup is merging legacy ${fileName} into canonical spec.md.`,
+            },
+        });
+    }
+    await safeUnlink(projectPath, legacyPath);
+    return true;
+}
+async function removePath(projectPath, absolutePath) {
+    const rel = relative(projectPath, absolutePath);
+    if (await pathIsDirectory(absolutePath)) {
+        await gitRmCached(projectPath, rel);
+        await rm(absolutePath, { recursive: true, force: true });
+        return;
+    }
+    await safeUnlink(projectPath, absolutePath);
+    await rm(absolutePath, { force: true });
+}
+async function updateGitignore(projectPath) {
+    const gitignorePath = join(projectPath, '.gitignore');
+    let current = '';
+    try {
+        current = await readFile(gitignorePath, 'utf-8');
+    }
+    catch {
+        /* missing .gitignore is fine */
+    }
+    const required = [
+        'planu/*.html',
+        'planu/status.json',
+        'planu/CHANGELOG.md',
+        'planu/.housekeeping-history.jsonl',
+        'planu/audits/',
+        'planu/handoffs/',
+        'planu/data/',
+        'planu/state/',
+        'planu/.locks/',
+        'planu/specs/data/',
+        'planu/specs/**/.analysis.json',
+        'planu/specs/**/technical-report.html',
+        'planu/specs/**/reference/',
+        'planu/specs/**/*.bak.*',
+    ];
+    const missing = required.filter((entry) => !current.split('\n').includes(entry));
+    if (missing.length === 0) {
+        return false;
+    }
+    const separator = current === '' || current.endsWith('\n') ? '' : '\n';
+    await atomicWriteFile(gitignorePath, `${current}${separator}# Planu generated/runtime\n${missing.join('\n')}\n`);
+    return true;
+}
+async function walkSpecDirectory(projectPath, specDir, result) {
+    const entries = await readdir(specDir).catch(() => []);
+    for (const entry of entries) {
+        const full = join(specDir, entry);
+        if (mustMergeBeforeDeleteSpecFile(entry)) {
+            if (await mergeLegacySpecFile(projectPath, specDir, entry)) {
+                result.merged.push(relative(projectPath, full));
+            }
+            continue;
+        }
+        if (entry === 'reference' || !isCanonicalSpecFile(entry)) {
+            await removePath(projectPath, full);
+            result.deleted.push(relative(projectPath, full));
+        }
+    }
+}
+export async function runStrictPlanuCleanup(projectPath) {
+    const result = { deleted: [], merged: [], gitignoreUpdated: false };
+    const planuDir = join(projectPath, 'planu');
+    if (!existsSync(planuDir)) {
+        return result;
+    }
+    const entries = await readdir(planuDir).catch(() => []);
+    for (const entry of entries) {
+        const full = join(planuDir, entry);
+        const isDir = await pathIsDirectory(full);
+        if (isDir && !isCanonicalPlanuRootDir(entry)) {
+            await removePath(projectPath, full);
+            result.deleted.push(relative(projectPath, full));
+            continue;
+        }
+        if (!isDir && !isCanonicalPlanuRootFile(entry)) {
+            await removePath(projectPath, full);
+            result.deleted.push(relative(projectPath, full));
+        }
+    }
+    const releasesDir = join(planuDir, 'releases');
+    for (const entry of await readdir(releasesDir).catch(() => [])) {
+        const rel = `releases/${entry}`;
+        if (!isCanonicalReleaseFile(rel)) {
+            const full = join(releasesDir, entry);
+            await removePath(projectPath, full);
+            result.deleted.push(relative(projectPath, full));
+        }
+    }
+    const specsDir = join(planuDir, 'specs');
+    for (const entry of await readdir(specsDir).catch(() => [])) {
+        const full = join(specsDir, entry);
+        if (!(await pathIsDirectory(full)) || entry === 'data') {
+            await removePath(projectPath, full);
+            result.deleted.push(relative(projectPath, full));
+            continue;
+        }
+        await walkSpecDirectory(projectPath, full, result);
+    }
+    result.gitignoreUpdated = await updateGitignore(projectPath);
+    return result;
+}
+export async function validateStrictPlanuLayout(projectPath) {
+    const offenders = [];
+    const planuDir = join(projectPath, 'planu');
+    const entries = await readdir(planuDir).catch(() => []);
+    for (const entry of entries) {
+        const full = join(planuDir, entry);
+        const isDir = await pathIsDirectory(full);
+        if ((isDir && !isCanonicalPlanuRootDir(entry)) || (!isDir && !isCanonicalPlanuRootFile(entry))) {
+            offenders.push(relative(projectPath, full));
+        }
+    }
+    for (const entry of await readdir(join(planuDir, 'releases')).catch(() => [])) {
+        const rel = `releases/${entry}`;
+        if (!isCanonicalReleaseFile(rel)) {
+            offenders.push(`planu/${rel}`);
+        }
+    }
+    for (const specDir of await readdir(join(planuDir, 'specs')).catch(() => [])) {
+        const full = join(planuDir, 'specs', specDir);
+        if (!(await pathIsDirectory(full)) || specDir === 'data') {
+            offenders.push(relative(projectPath, full));
+            continue;
+        }
+        for (const entry of await readdir(full).catch(() => [])) {
+            if (!isCanonicalSpecFile(entry)) {
+                offenders.push(relative(projectPath, join(full, entry)));
+            }
+        }
+    }
+    return { ok: offenders.length === 0, offenders, contract: canonicalContractText() };
+}
+export { PLANU_CANONICAL_POLICY };
+//# sourceMappingURL=strict-planu-cleanup.js.map

package/dist/engine/spec-summary-html.d.ts

@@ -1,10 +1,10 @@
 import type { Spec } from '../types/index.js';
 /**
- * Generate planu/index.html with specs overview + regenerate per-spec reports.
- * Merges store specs with filesystem specs to ensure all specs appear.
- * Designed to be called from list_specs, update_status, create_spec.
- * Best-effort: never throws, never blocks the caller.
- * Skips writing the file when spec data has not changed (hash comparison).
+ * Legacy compatibility entrypoint.
+ *
+ * SPEC-1017 makes `planu/index.html` and generated per-spec reports forbidden
+ * project-tree artifacts. Keep this function for old call sites, but make it
+ * a best-effort read-only refresh so callers stop reintroducing legacy files.
  */
 export declare function regenerateSpecSummaryHtml(projectPath: string, specs: Spec[], _changedSpecIds?: string[]): Promise<void>;
 //# sourceMappingURL=spec-summary-html.d.ts.map

package/dist/engine/spec-summary-html.js

@@ -1,9 +1,6 @@
-import { writeFile, mkdir, readFile, readdir } from 'node:fs/promises';
+import { readFile, readdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { parseFrontmatter } from './frontmatter-parser.js';
-import { generateDashboardHtml } from './spec-summary-html/dashboard-renderer.js';
-import { computeSpecDataHash, extractEmbeddedHash, HASH_MARKER, } from './spec-summary-html/hash-utils.js';
-import { detectAvailablePages } from './doc-generator/portal/portal-page-detector.js';
 /**
  * Scan planu/specs/ filesystem for spec.md files and build minimal Spec objects
  * from frontmatter. This catches specs not tracked in the JSON store.
@@ -87,38 +84,16 @@ function mergeSpecs(storeSpecs, fsSpecs) {
     return merged;
 }
 /**
- * Generate planu/index.html with specs overview + regenerate per-spec reports.
- * Merges store specs with filesystem specs to ensure all specs appear.
- * Designed to be called from list_specs, update_status, create_spec.
- * Best-effort: never throws, never blocks the caller.
- * Skips writing the file when spec data has not changed (hash comparison).
+ * Legacy compatibility entrypoint.
+ *
+ * SPEC-1017 makes `planu/index.html` and generated per-spec reports forbidden
+ * project-tree artifacts. Keep this function for old call sites, but make it
+ * a best-effort read-only refresh so callers stop reintroducing legacy files.
  */
 export async function regenerateSpecSummaryHtml(projectPath, specs, _changedSpecIds) {
-    const portalPath = join(projectPath, 'planu');
-    const outputPath = join(portalPath, 'index.html');
     try {
         const fsSpecs = await scanFilesystemSpecs(projectPath);
-        const allSpecs = mergeSpecs(specs, fsSpecs);
-        await mkdir(portalPath, { recursive: true });
-        // Detect available portal pages before generating to populate navbar + quick links
-        const availablePages = await detectAvailablePages(portalPath);
-        // Skip writing if spec data has not changed (avoids git noise on every tool call)
-        const newHash = computeSpecDataHash(allSpecs, availablePages);
-        try {
-            const existing = await readFile(outputPath, 'utf-8');
-            if (extractEmbeddedHash(existing) === newHash) {
-                return; // data unchanged — skip write
-            }
-        }
-        catch {
-            // file does not exist yet — proceed to write
-        }
-        const html = generateDashboardHtml(allSpecs, availablePages);
-        const htmlWithHash = html.replace('<!DOCTYPE html>', `<!DOCTYPE html>\n<!-- ${HASH_MARKER} ${newHash} -->`);
-        await writeFile(outputPath, htmlWithHash, 'utf-8');
-        // SPEC-466: Per-spec reports are legacy and no longer regenerated.
-        // Only the global index.html is generated. Remove this block entirely once
-        // all clients have migrated (regeneratePerSpecReports stays as dead code for now).
+        void mergeSpecs(specs, fsSpecs);
     }
     catch {
         /* best-effort — never fail the caller */

package/dist/storage/gaps-log.js

@@ -1,6 +1,6 @@
 // storage/gaps-log.ts — SPEC-739: Hash-chained gaps log (JSONL per project)
 //
-// Layout: planu/research/gaps.jsonl
+// Layout: ~/.planu/data/projects/<projectId>/research/gaps.jsonl
 //
 // Each entry is a JSON object on its own line. The `sha` field is a SHA-256 hash
 // of the entry's canonical JSON (excluding `sha`), chained via `prevSha`.
@@ -8,12 +8,12 @@ import { createHash, randomUUID } from 'node:crypto';
 import { appendFile, readFile, mkdir } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { isNativeActive, fastAppendGapEntry, fastVerifyGapsChain } from '../engine/core-bridge.js';
+import { projectDataDir } from './base-store.js';
 // ---------------------------------------------------------------------------
 // Path helper
 // ---------------------------------------------------------------------------
-function gapsLogPath(_projectId) {
-    // Per-spec: stored in planu/research/gaps.jsonl (project-level, not per-spec-id)
-    return join('planu', 'research', 'gaps.jsonl');
+function gapsLogPath(projectId) {
+    return join(projectDataDir(projectId), 'research', 'gaps.jsonl');
 }
 // ---------------------------------------------------------------------------
 // Node error type guard

package/dist/storage/transition-log.js

@@ -1,17 +1,18 @@
 // storage/transition-log.ts — SPEC-723: Hash-chained transition log (JSONL per project)
 //
-// Layout: planu/data/projects/<projectId>/transition-log.jsonl
+// Layout: ~/.planu/data/projects/<projectId>/transition-log.jsonl
 //
 // Each entry is a JSON object on its own line. The `sha` field is a SHA-256 hash
 // of the entry's canonical JSON (excluding `sha`), chained via `prevSha`.
 import { createHash, randomUUID } from 'node:crypto';
 import { appendFile, readFile, mkdir } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
+import { projectDataDir } from './base-store.js';
 // ---------------------------------------------------------------------------
 // Path helper
 // ---------------------------------------------------------------------------
 function transitionLogPath(projectId) {
-    return join('planu', 'data', 'projects', projectId, 'transition-log.jsonl');
+    return join(projectDataDir(projectId), 'transition-log.jsonl');
 }
 // ---------------------------------------------------------------------------
 // Node error type guard

package/dist/tools/audit-specs-drift.js

@@ -7,8 +7,8 @@ export function registerAuditSpecsDriftTool(server) {
         description: 'Run a two-tier drift audit over all done specs. ' +
             'Tier-1: deterministic checks (missing files, broken refs). ' +
             'Tier-2: LLM-based semantic drift for ambiguous cases (budget-capped). ' +
-            'Produces a prioritised P0/P1/P2 markdown report at planu/research/audit-full-<ts>.md ' +
-            'and appends a drift_review entry to planu/pending.json. ' +
+            'Produces a prioritised P0/P1/P2 markdown report in external Planu project data ' +
+            'and appends a drift_review entry to external pending state. ' +
             'Specs superseded by newer specs (per SPEC-746 graph) are excluded.',
         inputSchema: {
             projectPath: z.string().min(1).max(4096).describe('Absolute path to project root.'),
@@ -50,7 +50,7 @@ export function registerAuditSpecsDriftTool(server) {
                         ``,
                         p0 + p1 + p2 === 0
                             ? '✓ No drift detected.'
-                            : `⚠ ${p0 + p1 + p2} total issues found. Review \`planu/pending.json\` for the drift_review entry.`,
+                            : `⚠ ${p0 + p1 + p2} total issues found. Review external Planu pending state for the drift_review entry.`,
                     ].join('\n'),
                 },
             ],

package/dist/tools/create-spec/post-creation.d.ts

@@ -1,4 +1,5 @@
 import type { Spec, PostCreationSuggestion, ProjectKnowledge } from '../../types/index.js';
+export declare function getAsyncAnalysisPath(projectPath: string, specId: string): string;
 /** Auto-setup git branch (non-blocking). Returns branch info or undefined. */
 export declare function setupGitBranch(projectId: string, specId: string): Promise<{
     branch: string;
@@ -13,7 +14,7 @@ export declare function generatePostCreationSuggestions(projectPath: string, des
 /**
  * SPEC-781: Run heavy analysis (contradiction detection, complexity advice) in a
  * fire-and-forget fashion after the spec has already been persisted synchronously.
- * Writes results to `planu/specs/SPEC-XXX/.analysis.json` and appends an
+ * Writes results to Planu's external project data dir and appends an
  * autopilot-log entry on completion. Never throws — fully best-effort.
  */
 export declare function runAutopilotAsync(specId: string, projectPath: string, _description: string): void;

package/dist/tools/create-spec/post-creation.js

@@ -10,9 +10,13 @@ import { emitAutopilotEvent } from '../../engine/autopilot/event-bus.js';
 import { incrementSpecCount } from '../../engine/autopilot/state-updater.js';
 import { writeFile, mkdir } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
-import { hashProjectPath } from '../../storage/base-store.js';
+import { hashProjectPath, projectDataDir } from '../../storage/base-store.js';
 import { appendAutopilotLogEntry } from '../../storage/autopilot-log-store.js';
 const ASYNC_ANALYSIS_HOOK = 'create-spec-async-analysis';
+export function getAsyncAnalysisPath(projectPath, specId) {
+    const projectId = hashProjectPath(projectPath);
+    return join(projectDataDir(projectId), 'analysis', `${specId}.json`);
+}
 /** Auto-setup git branch (non-blocking). Returns branch info or undefined. */
 export async function setupGitBranch(projectId, specId) {
     const result = await tryAutoSetupGit(projectId, specId);
@@ -161,7 +165,7 @@ export async function generatePostCreationSuggestions(projectPath, description,
 /**
  * SPEC-781: Run heavy analysis (contradiction detection, complexity advice) in a
  * fire-and-forget fashion after the spec has already been persisted synchronously.
- * Writes results to `planu/specs/SPEC-XXX/.analysis.json` and appends an
+ * Writes results to Planu's external project data dir and appends an
  * autopilot-log entry on completion. Never throws — fully best-effort.
  */
 export function runAutopilotAsync(specId, projectPath, _description) {
@@ -169,20 +173,14 @@ export function runAutopilotAsync(specId, projectPath, _description) {
     const start = Date.now();
     void (async () => {
         try {
-            const { glob } = await import('glob');
-            const specFiles = await glob(join(projectPath, 'planu/specs', `${specId}-*`, 'spec.md'));
-            const specDir = specFiles[0] !== undefined ? dirname(specFiles[0]) : null;
             const analysisResult = {
                 specId,
                 completedAt: new Date().toISOString(),
                 pendingAnalysis: false,
             };
-            // Write .analysis.json to spec directory
-            if (specDir !== null) {
-                const analysisPath = join(specDir, '.analysis.json');
-                await mkdir(dirname(analysisPath), { recursive: true });
-                await writeFile(analysisPath, JSON.stringify(analysisResult, null, 2), 'utf-8');
-            }
+            const analysisPath = getAsyncAnalysisPath(projectPath, specId);
+            await mkdir(dirname(analysisPath), { recursive: true });
+            await writeFile(analysisPath, JSON.stringify(analysisResult, null, 2), 'utf-8');
             await appendAutopilotLogEntry(projectId, {
                 specId,
                 hookName: ASYNC_ANALYSIS_HOOK,

package/dist/tools/create-spec/spec-builder.js

@@ -26,7 +26,7 @@ export async function buildSpecContext(params) {
     const knowledge = await knowledgeStore.getKnowledge(projectId);
     const existingSpecs = await specStore.listSpecs(projectId);
     // License: check active spec limit (exclude completed specs)
-    const activeSpecs = existingSpecs.filter((s) => s.status !== 'done');
+    const activeSpecs = existingSpecs.filter((s) => s.status !== 'done' && s.status !== 'discarded');
     const tier = await getCurrentTier();
     const specLimit = checkLimits(tier, activeSpecs.length, 'maxActiveSpecs');
     /* v8 ignore start -- license limit requires paid tier test env */