@planu/cli 4.13.0 → 5.0.0

package/dist/storage/compliance-gate-config-store.js

@@ -1,17 +1,20 @@
 // storage/compliance-gate-config-store.ts — Compliance gate config persistence (SPEC-447)
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
-import { safeJsonParse } from './base-store.js';
+import { projectDataDir, safeJsonParse } from './base-store.js';
 function complianceGateConfigPath(projectId) {
-    return join('data', 'projects', projectId, 'compliance-gate-config.json');
+    return join(projectDataDir(projectId), 'compliance-gate-config.json');
 }
 export async function getComplianceGateConfig(projectId) {
     try {
         const raw = await readFile(complianceGateConfigPath(projectId), 'utf-8');
         return safeJsonParse(raw, null);
     }
-    catch {
-        return null;
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return null;
+        }
+        throw error;
     }
 }
 export async function saveComplianceGateConfig(projectId, config) {

package/dist/storage/compliance-store.js

@@ -1,12 +1,12 @@
 // storage/compliance-store.ts — Compliance config persistence (SPEC-319)
 import { join } from 'node:path';
-import { hashProjectPath, readJson, writeJson } from './base-store.js';
+import { hashProjectPath, projectDataDir, readJson, writeJson } from './base-store.js';
 // ---------------------------------------------------------------------------
 // Path helpers
 // ---------------------------------------------------------------------------
 function projectDir(projectPath) {
     const id = hashProjectPath(projectPath);
-    return join('data', 'projects', id);
+    return projectDataDir(id);
 }
 function configPath(projectPath) {
     return join(projectDir(projectPath), 'compliance-config.json');

package/dist/storage/context-profile-store.js

@@ -1,6 +1,6 @@
-import { readJson, writeJson, hashProjectPath } from './base-store.js';
+import { readJson, writeJson, hashProjectPath, projectDataDir } from './base-store.js';
 function profileFile(projectId) {
-    return `data/projects/${projectId}/context-profile.json`;
+    return `${projectDataDir(projectId)}/context-profile.json`;
 }
 /**
  * Persist the active work phase for a project.

package/dist/storage/crash-shield-store.js

@@ -1,17 +1,21 @@
 // storage/crash-shield-store.ts — Crash Shield config persistence (SPEC-442)
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
-import { safeJsonParse } from './base-store.js';
+import { projectDataDir, safeJsonParse } from './base-store.js';
 function crashShieldConfigPath(projectId) {
-    return join('data', 'projects', projectId, 'crash-shield-config.json');
+    return join(projectDataDir(projectId), 'crash-shield-config.json');
 }
 export async function getCrashShieldConfig(projectId) {
     try {
         const raw = await readFile(crashShieldConfigPath(projectId), 'utf-8');
         return safeJsonParse(raw, null);
     }
-    catch {
-        return null;
+    catch (error) {
+        if (error.code === 'ENOENT' ||
+            (error instanceof Error && error.message === 'ENOENT')) {
+            return null;
+        }
+        throw error;
     }
 }
 export async function saveCrashShieldConfig(config) {

package/dist/storage/feedback-remote.d.ts

@@ -1,11 +1,10 @@
 import type { FeedbackRemoteResult, RemoteFeedbackPayload } from '../types/feedback.js';
-export declare const DEFAULT_FEEDBACK_API = "https://canusqigtzldstnjddio.supabase.co/functions/v1/license-api/feedback";
 export type { RemoteFeedbackPayload };
-export declare function resolveFeedbackEndpoint(endpoint?: string): string;
+export declare function resolveFeedbackEndpoint(endpoint?: string): string | undefined;
 export declare function sanitizeRemoteFeedbackPayload(payload: RemoteFeedbackPayload): RemoteFeedbackPayload;
 export declare function deliverFeedbackRemote(payload: RemoteFeedbackPayload, endpoint?: string): Promise<FeedbackRemoteResult>;
 /**
- * Send feedback to central Supabase store (fire-and-forget).
+ * Send feedback to the explicitly configured remote endpoint (fire-and-forget).
  * Never throws. Returns true if sent successfully, false otherwise.
  */
 export declare function sendFeedbackRemote(payload: RemoteFeedbackPayload): Promise<boolean>;

package/dist/storage/feedback-remote.js

@@ -1,8 +1,34 @@
-// storage/feedback-remote.ts — Remote feedback relay to Supabase (fire-and-forget)
+// storage/feedback-remote.ts — Configured remote feedback relay (fire-and-forget)
 // No PII is ever sent: no project paths, no user names, no emails.
-export const DEFAULT_FEEDBACK_API = 'https://canusqigtzldstnjddio.supabase.co/functions/v1/license-api/feedback';
+import { networkFetch, withNetworkConsent } from '../engine/network-policy.js';
+function resolveConfiguredFeedbackEndpoint(endpoint) {
+    const configured = endpoint ?? process.env.PLANU_FEEDBACK_ENDPOINT;
+    const trimmed = configured?.trim();
+    return trimmed === '' ? undefined : trimmed;
+}
+function isLoopbackHost(hostname) {
+    return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '[::1]';
+}
+function parseSafeFeedbackEndpoint(endpoint) {
+    const url = URL.parse(endpoint);
+    if (url === null) {
+        return undefined;
+    }
+    const safe = url.username === '' &&
+        url.password === '' &&
+        (url.protocol === 'https:' || (url.protocol === 'http:' && isLoopbackHost(url.hostname)));
+    return safe ? url : undefined;
+}
+function observableFeedbackEndpoint(url) {
+    return `${url.origin}${url.pathname}`;
+}
 export function resolveFeedbackEndpoint(endpoint) {
-    return endpoint ?? process.env.PLANU_FEEDBACK_ENDPOINT ?? DEFAULT_FEEDBACK_API;
+    const configured = resolveConfiguredFeedbackEndpoint(endpoint);
+    if (configured === undefined) {
+        return undefined;
+    }
+    const url = parseSafeFeedbackEndpoint(configured);
+    return url === undefined ? undefined : observableFeedbackEndpoint(url);
 }
 function redactSensitiveText(value) {
     return value
@@ -20,63 +46,51 @@ export function sanitizeRemoteFeedbackPayload(payload) {
     };
 }
 export async function deliverFeedbackRemote(payload, endpoint) {
-    const resolvedEndpoint = resolveFeedbackEndpoint(endpoint);
-    let url;
-    try {
-        url = new URL(resolvedEndpoint);
-    }
-    catch {
+    const configuredEndpoint = resolveConfiguredFeedbackEndpoint(endpoint);
+    if (configuredEndpoint === undefined) {
         return {
             ok: false,
             status: 'skipped',
-            endpoint: resolvedEndpoint,
-            error: 'Invalid feedback endpoint URL.',
+            error: 'Remote feedback endpoint is not configured.',
         };
     }
-    if (url.protocol !== 'https:' && url.hostname !== 'localhost' && url.hostname !== '127.0.0.1') {
+    const url = parseSafeFeedbackEndpoint(configuredEndpoint);
+    if (url === undefined) {
         return {
             ok: false,
             status: 'skipped',
-            endpoint: resolvedEndpoint,
-            error: 'Feedback endpoint must use HTTPS.',
+            error: 'Remote feedback endpoint configuration is invalid.',
         };
     }
-    const controller = new AbortController();
-    const timeout = setTimeout(() => {
-        controller.abort();
-    }, 5000);
+    const observableEndpoint = observableFeedbackEndpoint(url);
     try {
-        const res = await fetch(resolvedEndpoint, {
+        const res = await withNetworkConsent('feedback', (receipt) => networkFetch(receipt, configuredEndpoint, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify(sanitizeRemoteFeedbackPayload(payload)),
-            signal: controller.signal,
-        });
+            signal: AbortSignal.timeout(5_000),
+        }));
         if (res.ok) {
-            return { ok: true, status: 'synced', endpoint: resolvedEndpoint };
+            return { ok: true, status: 'synced', endpoint: observableEndpoint };
         }
         return {
             ok: false,
             status: 'failed',
-            endpoint: resolvedEndpoint,
+            endpoint: observableEndpoint,
             error: `Remote feedback endpoint returned HTTP ${res.status}.`,
         };
     }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
+    catch {
         return {
             ok: false,
             status: 'failed',
-            endpoint: resolvedEndpoint,
-            error: message || 'Remote feedback request failed.',
+            endpoint: observableEndpoint,
+            error: 'Remote feedback request failed.',
         };
     }
-    finally {
-        clearTimeout(timeout);
-    }
 }
 /**
- * Send feedback to central Supabase store (fire-and-forget).
+ * Send feedback to the explicitly configured remote endpoint (fire-and-forget).
  * Never throws. Returns true if sent successfully, false otherwise.
  */
 export async function sendFeedbackRemote(payload) {

package/dist/storage/feedback-store.js

@@ -3,6 +3,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { withFileLock } from './file-mutex.js';
 import { deliverFeedbackRemote } from './feedback-remote.js';
+import { reportClassifiedDegradation } from '../errors/classified-degradation.js';
 // ---------------------------------------------------------------------------
 // Path helpers
 // ---------------------------------------------------------------------------
@@ -29,8 +30,8 @@ function readLedger(filePath) {
         }
         return parsed;
     }
-    catch {
-        return [];
+    catch (error) {
+        throw new Error(`Feedback ledger is corrupt: ${filePath}`, { cause: error });
     }
 }
 function writeLedger(filePath, entries) {
@@ -121,8 +122,10 @@ function readPlanuVersion(dataDir) {
                     return pkg.version;
                 }
             }
-            catch {
-                // continue
+            catch (error) {
+                // reliability-compat: PACKAGE_VERSION_LOOKUP — continue to the next package candidate
+                reportClassifiedDegradation('PACKAGE_VERSION_LOOKUP', error);
+                continue;
             }
         }
     }
@@ -196,8 +199,9 @@ export async function submitFeedback(dataDir, entry) {
         };
         entries.push(newEntry);
         writeLedger(filePath, entries);
-        void deliverAndPersistRemote(dataDir, newEntry).catch((err) => {
-            console.error('[planu] feedback remote delivery failed:', err);
+        void deliverAndPersistRemote(dataDir, newEntry).catch((error) => {
+            // reliability-optional: FEEDBACK_REMOTE_DELIVERY — local ledger is authoritative
+            reportClassifiedDegradation('FEEDBACK_REMOTE_DELIVERY', error);
         });
         return Promise.resolve(newEntry);
     });

package/dist/storage/figma-store.js

@@ -1,11 +1,13 @@
 // storage/figma-store.ts — Figma integration persistence (SPEC-418)
 import { join } from 'node:path';
-import { hashProjectPath, readJson, writeJson } from './base-store.js';
+import { hashProjectPath, projectDataDir, readJson, writeJson } from './base-store.js';
 import { withFileLock } from './file-mutex.js';
+import { resolveSecretField, storeSecretField } from '../security/secret-field.js';
+import { writeSecureJson } from '../security/secure-json.js';
 const MAX_SYNC_LOG_ENTRIES = 50;
 function projectDir(projectPath) {
     const id = hashProjectPath(projectPath);
-    return join('data', 'projects', id);
+    return projectDataDir(id);
 }
 function configPath(projectPath) {
     return join(projectDir(projectPath), 'figma-config.json');
@@ -17,10 +19,12 @@ function generatedSpecsPath(projectPath) {
     return join(projectDir(projectPath), 'figma-generated-specs.json');
 }
 export async function getFigmaConfig(projectPath) {
-    return readJson(configPath(projectPath), null);
+    const config = await readJson(configPath(projectPath), null);
+    return config ? { ...config, accessToken: await resolveSecretField(config.accessToken) } : null;
 }
 export async function saveFigmaConfig(projectPath, config) {
-    await writeJson(configPath(projectPath), config);
+    const accessToken = await storeSecretField(`${hashProjectPath(projectPath)}/figma/access`, 'figma-pat', config.accessToken);
+    await writeSecureJson(configPath(projectPath), { ...config, accessToken });
 }
 export async function getFigmaSyncLog(projectPath) {
     return readJson(syncLogPath(projectPath), []);

package/dist/storage/file-mutex.js

@@ -1,11 +1,17 @@
 // file-mutex.ts — In-memory per-file mutex for concurrent access safety
 // Uses async promise chaining: each file path gets its own sequential queue.
+import { AsyncLocalStorage } from 'node:async_hooks';
 const locks = new Map();
+const heldLocks = new AsyncLocalStorage();
 /**
  * Execute `fn` while holding an exclusive lock on `filePath`.
  * Concurrent calls for the same path are serialized; different paths run in parallel.
  */
 export async function withFileLock(filePath, fn) {
+    const current = heldLocks.getStore();
+    if (current?.has(filePath)) {
+        return fn();
+    }
     const prev = locks.get(filePath) ?? Promise.resolve();
     let release;
     const next = new Promise((resolve) => {
@@ -14,7 +20,9 @@ export async function withFileLock(filePath, fn) {
     locks.set(filePath, next);
     try {
         await prev;
-        return await fn();
+        const nextHeld = new Set(current ?? []);
+        nextHeld.add(filePath);
+        return await heldLocks.run(nextHeld, fn);
     }
     finally {
         release();

package/dist/storage/gaps-log.js

@@ -9,6 +9,7 @@ import { appendFile, readFile, mkdir } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { fastAppendGapEntry, fastVerifyGapsChain } from '../engine/core-bridge.js';
 import { projectDataDir } from './base-store.js';
+import { reportClassifiedDegradation } from '../errors/classified-degradation.js';
 // ---------------------------------------------------------------------------
 // Path helper
 // ---------------------------------------------------------------------------
@@ -77,8 +78,8 @@ async function doAppend(filePath, input) {
             const parsed = JSON.parse(lastLine);
             prevSha = typeof parsed.sha === 'string' ? parsed.sha : '';
         }
-        catch {
-            prevSha = '';
+        catch (error) {
+            throw new Error(`Gap log chain tail is corrupt: ${filePath}`, { cause: error });
         }
     }
     const partial = {
@@ -124,8 +125,10 @@ export async function readGapsLog(projectId) {
             const entry = JSON.parse(line);
             entries.push(entry);
         }
-        catch {
-            // skip malformed lines
+        catch (error) {
+            // reliability-compat: MALFORMED_GAP_LINE — skip malformed historical lines
+            reportClassifiedDegradation('MALFORMED_GAP_LINE', error);
+            continue;
         }
     }
     return entries;

package/dist/storage/global-projects-store.js

@@ -3,6 +3,7 @@
 import { readJson, writeJson, globalDataDir, hashProjectPath } from './base-store.js';
 import { withFileLock } from './file-mutex.js';
 import { isEphemeralProject } from '../engine/data-projects-gc/pattern-matcher.js';
+import { reportClassifiedDegradation } from '../errors/classified-degradation.js';
 // ---------------------------------------------------------------------------
 // File path
 // ---------------------------------------------------------------------------
@@ -122,8 +123,9 @@ async function pruneEphemeralEntries() {
             await saveRegistry(next);
         });
     }
-    catch {
-        /* best-effort — pruning never blocks reads */
+    catch (error) {
+        /* reliability-cleanup: STALE_PROJECT_PRUNE — pruning never blocks reads */
+        reportClassifiedDegradation('STALE_PROJECT_PRUNE', error);
     }
 }
 //# sourceMappingURL=global-projects-store.js.map

package/dist/storage/global-store.d.ts

@@ -1,4 +1,4 @@
-import type { GlobalConfig, SupportedLocale, ExperienceLevel, TemplateMap, PricingMap, LearnedRegistryEntry, TokenUsage, DeveloperPreference, ImprovementOverride, LessonLearned } from '../types/index.js';
+import type { GlobalConfig, SupportedLocale, ExperienceLevel, TemplateMap, LearnedRegistryEntry, TokenUsage, DeveloperPreference, ImprovementOverride, LessonLearned } from '../types/index.js';
 /**
  * Get the global configuration. Returns defaults when no config file exists.
  */
@@ -43,22 +43,6 @@ export declare function deleteTemplate(key: string): Promise<boolean>;
  * List all template keys.
  */
 export declare function listTemplateKeys(): Promise<string[]>;
-/**
- * Get all pricing data.
- */
-export declare function getPricing(): Promise<PricingMap>;
-/**
- * Get a pricing tier by key.
- */
-export declare function getPricingTier(key: string): Promise<Record<string, number> | null>;
-/**
- * Set or overwrite a pricing tier.
- */
-export declare function setPricingTier(key: string, tier: Record<string, number>): Promise<void>;
-/**
- * Delete a pricing tier. Returns `true` if it existed.
- */
-export declare function deletePricingTier(key: string): Promise<boolean>;
 /**
  * Get all learned registry entries across all registry types.
  */

package/dist/storage/global-store.js

@@ -8,9 +8,6 @@ function configFile() {
 function templatesFile() {
     return `${globalDataDir()}/templates.json`;
 }
-function pricingFile() {
-    return `${globalDataDir()}/pricing.json`;
-}
 // --- defaults ---
 const DEFAULT_CONFIG = {
     defaultLocale: 'en',
@@ -19,7 +16,7 @@ const DEFAULT_CONFIG = {
     pricingOpusPerMToken: 15,
     pricingSonnetPerMToken: 3,
 };
-// TemplateMap and PricingMap imported from types/index.js
+// TemplateMap imported from types/index.js
 // --- Global Config ---
 /**
  * Get the global configuration. Returns defaults when no config file exists.
@@ -105,44 +102,6 @@ export async function listTemplateKeys() {
     const templates = await getTemplates();
     return Object.keys(templates);
 }
-// --- Pricing ---
-/**
- * Get all pricing data.
- */
-export async function getPricing() {
-    return readJson(pricingFile(), {});
-}
-/**
- * Get a pricing tier by key.
- */
-export async function getPricingTier(key) {
-    const pricing = await getPricing();
-    return pricing[key] ?? null;
-}
-/**
- * Set or overwrite a pricing tier.
- */
-export async function setPricingTier(key, tier) {
-    await withFileLock(pricingFile(), async () => {
-        const pricing = await getPricing();
-        pricing[key] = tier;
-        await writeJson(pricingFile(), pricing);
-    });
-}
-/**
- * Delete a pricing tier. Returns `true` if it existed.
- */
-export async function deletePricingTier(key) {
-    return withFileLock(pricingFile(), async () => {
-        const pricing = await getPricing();
-        if (!(key in pricing)) {
-            return false;
-        }
-        const { [key]: _, ...rest } = pricing;
-        await writeJson(pricingFile(), rest);
-        return true;
-    });
-}
 // --- Learned Registries (SPEC-011) ---
 function learnedRegistriesFile() {
     return `${globalDataDir()}/learned-registries.json`;

package/dist/storage/ideas-store.js

@@ -1,8 +1,8 @@
-import { readJson, writeJson, hashProjectPath } from './base-store.js';
+import { readJson, writeJson, hashProjectPath, projectDataDir } from './base-store.js';
 import { withFileLock } from './file-mutex.js';
 function ideasFile(projectPath) {
     const hash = hashProjectPath(projectPath);
-    return `data/projects/${hash}/backlog/ideas.json`;
+    return `${projectDataDir(hash)}/backlog/ideas.json`;
 }
 /**
  * Save a new idea (appends to existing list).

package/dist/storage/index.d.ts

@@ -1,14 +1,17 @@
 export { hashProjectPath, readJson, writeJson, projectDataDir, globalDataDir, } from './base-store.js';
+export * from './storage-layout.js';
+export * from './storage-catalog.js';
+export * from './project-identity.js';
+export * from './runtime-db.js';
+export * from './storage-bundle.js';
 export * as specStore from './spec-store.js';
 export * as metricsStore from './metrics-store.js';
 export * as patternStore from './pattern-store.js';
 export * as knowledgeStore from './knowledge-store.js';
 export * as globalStore from './global-store.js';
 export * as decisionStore from './decision-store.js';
-export * as licenseStore from './license-store.js';
 export * as usageStore from './usage-store.js';
 export * as hooksStore from './hooks-store.js';
-export * as sessionStore from './session-store.js';
 export * as hashSnapshotStore from './hash-snapshot-store.js';
 export * as livingDashboardStore from './living-dashboard-store.js';
 export * as syncLogStore from './sync-log-store.js';

package/dist/storage/index.js

@@ -1,15 +1,18 @@
 // storage/index.ts — Barrel export for all storage modules
 export { hashProjectPath, readJson, writeJson, projectDataDir, globalDataDir, } from './base-store.js';
+export * from './storage-layout.js';
+export * from './storage-catalog.js';
+export * from './project-identity.js';
+export * from './runtime-db.js';
+export * from './storage-bundle.js';
 export * as specStore from './spec-store.js';
 export * as metricsStore from './metrics-store.js';
 export * as patternStore from './pattern-store.js';
 export * as knowledgeStore from './knowledge-store.js';
 export * as globalStore from './global-store.js';
 export * as decisionStore from './decision-store.js';
-export * as licenseStore from './license-store.js';
 export * as usageStore from './usage-store.js';
 export * as hooksStore from './hooks-store.js';
-export * as sessionStore from './session-store.js';
 export * as hashSnapshotStore from './hash-snapshot-store.js';
 export * as livingDashboardStore from './living-dashboard-store.js';
 export * as syncLogStore from './sync-log-store.js';

package/dist/storage/knowledge-store/knowledge.js

@@ -1,13 +1,30 @@
-import { readCriticalJson, writeJson, projectDataDir } from '../base-store.js';
+import { writeJson, projectDataDir } from '../base-store.js';
+import { readCriticalSchema, registerCriticalSchema } from '../schema-registry.js';
 import { withFileLock } from '../file-mutex.js';
-import { discoverProjectDataFile } from '../data-dir-discovery.js';
-import { migrateLegacyDataDir } from '../migrations/cwd-to-absolute.js';
 function knowledgeFile(projectId) {
     return `${projectDataDir(projectId)}/knowledge.json`;
 }
 function isKnowledgeOrNull(value) {
     return value === null || (typeof value === 'object' && !Array.isArray(value));
 }
+registerCriticalSchema({
+    name: 'project-knowledge',
+    currentVersion: 1,
+    createDefault: () => null,
+    validate: isKnowledgeOrNull,
+    migrate: (value, fromVersion) => {
+        if (fromVersion === 0 && isKnowledgeOrNull(value)) {
+            return value;
+        }
+        throw new Error('[Planu] Unsupported project-knowledge schema migration');
+    },
+});
+async function readKnowledge(projectId) {
+    return (await readCriticalSchema(knowledgeFile(projectId), 'project-knowledge')).data;
+}
+async function writeKnowledge(projectId, knowledge) {
+    await writeJson(knowledgeFile(projectId), { schemaVersion: 1, data: knowledge });
+}
 /**
  * Get project knowledge. Returns `null` when no knowledge has been stored yet.
  *
@@ -17,32 +34,15 @@ function isKnowledgeOrNull(value) {
  * used during init_project.
  */
 export async function getKnowledge(projectId) {
-    // SPEC-1007: migrate legacy <cwd>/data/projects/{id} to absolute home once.
-    await migrateLegacyDataDir(projectId);
-    const direct = await readCriticalJson(knowledgeFile(projectId), null, {
-        validate: isKnowledgeOrNull,
-        expectedDescription: 'a project knowledge object or null',
-    });
-    if (direct !== null) {
-        return direct;
-    }
-    const discovered = await discoverProjectDataFile(projectId, 'knowledge.json');
-    if (discovered === null) {
-        return null;
-    }
-    return readCriticalJson(discovered, null, {
-        validate: isKnowledgeOrNull,
-        expectedDescription: 'a project knowledge object or null',
-    });
+    return readKnowledge(projectId);
 }
 /**
  * Save or overwrite the full project knowledge object.
  */
 export async function saveKnowledge(projectId, knowledge) {
-    // SPEC-1007: migrate legacy tree before first save so writes land in absolute path.
-    await migrateLegacyDataDir(projectId);
     await withFileLock(knowledgeFile(projectId), async () => {
-        await writeJson(knowledgeFile(projectId), knowledge);
+        await readKnowledge(projectId);
+        await writeKnowledge(projectId, knowledge);
     });
 }
 /**
@@ -50,10 +50,7 @@ export async function saveKnowledge(projectId, knowledge) {
  */
 export async function updateKnowledge(projectId, updates) {
     return withFileLock(knowledgeFile(projectId), async () => {
-        const existing = await readCriticalJson(knowledgeFile(projectId), null, {
-            validate: isKnowledgeOrNull,
-            expectedDescription: 'a project knowledge object or null',
-        });
+        const existing = await readKnowledge(projectId);
         if (!existing) {
             throw new Error(`No knowledge found for project "${projectId}". Use saveKnowledge first.`);
         }
@@ -63,7 +60,7 @@ export async function updateKnowledge(projectId, updates) {
             projectId, // never allow override
             lastAnalyzed: new Date().toISOString(),
         };
-        await writeJson(knowledgeFile(projectId), updated);
+        await writeKnowledge(projectId, updated);
         return updated;
     });
 }
@@ -72,15 +69,12 @@ export async function updateKnowledge(projectId, updates) {
  */
 export async function deleteKnowledge(projectId) {
     return withFileLock(knowledgeFile(projectId), async () => {
-        const existing = await readCriticalJson(knowledgeFile(projectId), null, {
-            validate: isKnowledgeOrNull,
-            expectedDescription: 'a project knowledge object or null',
-        });
+        const existing = await readKnowledge(projectId);
         if (!existing) {
             return false;
         }
         // Overwrite with null sentinel so readJson returns null on next read
-        await writeJson(knowledgeFile(projectId), null);
+        await writeKnowledge(projectId, null);
         return true;
     });
 }

package/dist/storage/lessons-store.js

@@ -1,4 +1,4 @@
-import { readJson, writeJson, hashProjectPath } from './base-store.js';
+import { readJson, writeJson, hashProjectPath, projectDataDir } from './base-store.js';
 import { withFileLock } from './file-mutex.js';
 // ---------------------------------------------------------------------------
 // Text tokenizer (Jaccard-ready) — SPEC-526
@@ -58,7 +58,7 @@ function jaccardSimilarity(a, b) {
 }
 function lessonsFile(projectPath) {
     const hash = hashProjectPath(projectPath);
-    return `data/projects/${hash}/lessons.json`;
+    return `${projectDataDir(hash)}/lessons.json`;
 }
 /** Generate a unique lesson ID from an already-loaded lessons array. */
 function generateLessonIdFromList(lessons) {

package/dist/storage/migrations/canonical-storage.d.ts

@@ -0,0 +1,15 @@
+import type { CanonicalMigrationInput, CanonicalMigrationInventory, CanonicalMigrationResult } from '../../types/migration/canonical-storage.js';
+export declare function inventoryStorageRoot(rootInput: string): Promise<CanonicalMigrationInventory>;
+declare function migrationPaths(destinationRoot: string): {
+    journalPath: string;
+    stagingRoot: string;
+    backupRoot: string;
+    lockPath: string;
+};
+/** Migrate explicit legacy roots into one canonical absolute directory. */
+export declare function migrateCanonicalStorage(input: CanonicalMigrationInput): Promise<CanonicalMigrationResult>;
+export declare const CANONICAL_MIGRATION_INTERNALS: Readonly<{
+    migrationPaths: typeof migrationPaths;
+}>;
+export {};
+//# sourceMappingURL=canonical-storage.d.ts.map