@planu/cli 4.13.0 → 5.0.0

package/dist/engine/lifecycle-reconciliation.js

@@ -0,0 +1,406 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { lstat, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { projectDataDir } from '../storage/base-store.js';
+import { specStore } from '../storage/index.js';
+import { ValidationReportV1Schema } from './handoff-artifacts/schemas.js';
+import { rollbackTransitionSpec, transitionSpec, } from './spec-state-machine/transition-spec.js';
+import { acquireLock, releaseLock } from './safety/cross-process-lock.js';
+import { appendTransitionEvent, readTransitionLog } from '../storage/transition-log.js';
+import { collectSupersededReconciliationArtifacts, readCommittedReconciliationReceipts, readReconciliationReceipt, reconciliationDigest as digest, safeReceiptPath, writeReconciliationReceipt, } from './lifecycle-reconciliation-io.js';
+const REQUEST_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
+const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+const invocationStore = new AsyncLocalStorage();
+/** The registrar, not caller-controlled tool input, establishes local authority. */
+export function runWithTrustedLocalMcpContext(callback) {
+    return invocationStore.run({ surface: 'local-mcp' }, callback);
+}
+export function currentReconciliationInvocationContext() {
+    return invocationStore.getStore() ?? { surface: 'direct' };
+}
+function failure(message, code = 'RECONCILIATION_REJECTED') {
+    return {
+        content: [{ type: 'text', text: `${code}: ${message}` }],
+        isError: true,
+        structuredContent: { error: code, code: 422 },
+    };
+}
+function appendState(receipt, state, reason) {
+    const at = new Date().toISOString();
+    return {
+        ...receipt,
+        state,
+        stateHistory: [...receipt.stateHistory, { state, at, ...(reason ? { reason } : {}) }],
+        ...(state === 'committed' ? { committedAt: at } : {}),
+        ...(state === 'aborted' ? { abortedAt: at } : {}),
+    };
+}
+async function appendTransitionEventOnce(args) {
+    const existing = await readTransitionLog(args.projectId, args.specId);
+    const alreadyAppended = existing.some((entry) => {
+        const meta = entry.meta;
+        if (meta === undefined) {
+            return false;
+        }
+        return (meta.reconciliationRequestId === args.requestId &&
+            meta.reconciliationBindingDigest === args.bindingDigest);
+    });
+    if (alreadyAppended) {
+        return;
+    }
+    await appendTransitionEvent({
+        projectId: args.projectId,
+        specId: args.specId,
+        eventType: 'transition',
+        from: 'implementing',
+        to: 'review',
+        actor: 'local-mcp',
+        reason: args.reason,
+        meta: {
+            trigger: 'reconciliation',
+            reconciliationRequestId: args.requestId,
+            reconciliationBindingDigest: args.bindingDigest,
+            transitionId: args.transitionId,
+        },
+    });
+}
+async function completeForwardReconciliation(args) {
+    let next = args.receipt;
+    if (next.phase !== 'spec-synced' && next.phase !== 'audit-appended') {
+        const syncResult = await args.syncSpecFiles(args.spec, 'implementing', 'review', args.projectPath);
+        if (syncResult.warning) {
+            throw new Error(`portable spec sync failed: ${syncResult.warning.reason}`);
+        }
+        next = { ...next, transitionId: args.transitionId, phase: 'spec-synced', auditPending: true };
+        await args.persistReceipt(args.receiptPath, next);
+    }
+    if (next.phase !== 'audit-appended') {
+        // The audit append may have reached disk even when the caller receives an error.
+        // From this point recovery is forward-only, never rollback.
+        args.markAppendOnly();
+        await appendTransitionEventOnce({
+            projectId: args.projectId,
+            specId: args.spec.id,
+            requestId: next.requestId,
+            bindingDigest: next.bindingDigest,
+            transitionId: args.transitionId,
+            reason: args.reason,
+        });
+        next = {
+            ...next,
+            transitionId: args.transitionId,
+            phase: 'audit-appended',
+            auditPending: false,
+        };
+        await args.persistReceipt(args.receiptPath, next);
+    }
+    const committed = {
+        ...appendState(next, 'committed'),
+        transitionId: args.transitionId,
+        committedTransitionId: args.transitionId,
+        auditPending: false,
+    };
+    await args.persistReceipt(args.receiptPath, committed);
+    return committed;
+}
+async function validateRequest(args) {
+    const { input, spec, context } = args;
+    if (context.surface !== 'local-mcp') {
+        return failure('reconciliation is available only through local MCP', 'RECONCILIATION_UNTRUSTED_SURFACE');
+    }
+    if (input.status !== 'review') {
+        return failure('reconciliation target must be review');
+    }
+    if (!input.reconciliationRequestId || !REQUEST_ID.test(input.reconciliationRequestId)) {
+        return failure('reconciliationRequestId must be a lowercase RFC 4122 UUID');
+    }
+    if (!input.expectedImplementingTransitionId ||
+        !input.implementationReviewDigest ||
+        !DIGEST.test(input.implementationReviewDigest)) {
+        return failure('expected transition and sha256 implementation review digest are required');
+    }
+    if (!input.reason || input.reason.trim().length < 100) {
+        return failure('reason must contain at least 100 characters');
+    }
+    if (spec.status !== 'implementing') {
+        return failure('spec is no longer implementing', 'RECONCILIATION_STALE');
+    }
+    const latest = spec.statusHistory?.at(-1);
+    if (!latest?.transitionId || latest.transitionId !== input.expectedImplementingTransitionId) {
+        return failure('expected implementing transition is stale', 'RECONCILIATION_STALE');
+    }
+    const reportPath = join(projectDataDir(args.projectId), 'handoffs', spec.id, 'validation-report.json');
+    let reportBytes;
+    try {
+        const status = await lstat(reportPath);
+        if (status.isSymbolicLink() || !status.isFile()) {
+            return failure('validation report is unsafe');
+        }
+        reportBytes = await readFile(reportPath);
+    }
+    catch {
+        return failure('validation report is missing');
+    }
+    const report = ValidationReportV1Schema.safeParse(JSON.parse(reportBytes.toString('utf8')));
+    if (!report.success ||
+        report.data.passed ||
+        report.data.reviewer.kind !== 'implementation-review-agent' ||
+        report.data.reviewer.agent !== 'planu-implementation-reviewer' ||
+        report.data.reviewer.verdict !== 'changes-requested') {
+        return failure('validation report is not an independent changes-requested finding');
+    }
+    const reviewDigest = digest(reportBytes);
+    if (reviewDigest !== input.implementationReviewDigest) {
+        return failure('implementation review digest does not match validation report', 'RECONCILIATION_STALE');
+    }
+    return {
+        reviewDigest,
+        bindingDigest: digest([
+            args.projectId,
+            spec.id,
+            input.reconciliationRequestId,
+            latest.transitionId,
+            reviewDigest,
+            digest(input.reason.trim()),
+        ].join('\0')),
+    };
+}
+function validateDurableReceiptBinding(args) {
+    const { input, receipt } = args;
+    if (input.expectedImplementingTransitionId !== receipt.sourceImplementingTransitionId ||
+        input.implementationReviewDigest !== receipt.implementationReviewDigest ||
+        !input.reason ||
+        digest(input.reason.trim()) !== receipt.reasonDigest) {
+        return failure('reconciliation retry binding conflicts with the durable receipt', 'RECONCILIATION_BINDING_CONFLICT');
+    }
+    const bindingDigest = digest([
+        args.projectId,
+        args.specId,
+        receipt.requestId,
+        receipt.sourceImplementingTransitionId,
+        receipt.implementationReviewDigest,
+        receipt.reasonDigest,
+    ].join('\0'));
+    if (bindingDigest !== receipt.bindingDigest) {
+        return failure('durable reconciliation binding is invalid', 'RECONCILIATION_BINDING_CONFLICT');
+    }
+    return null;
+}
+async function validateStoredBinding(args) {
+    const durableBindingError = validateDurableReceiptBinding(args);
+    if (durableBindingError) {
+        return durableBindingError;
+    }
+    const reportPath = join(projectDataDir(args.projectId), 'handoffs', args.specId, 'validation-report.json');
+    try {
+        const reportBytes = await readFile(reportPath);
+        const report = ValidationReportV1Schema.safeParse(JSON.parse(reportBytes.toString('utf8')));
+        if (!report.success ||
+            report.data.passed ||
+            report.data.reviewer.kind !== 'implementation-review-agent' ||
+            report.data.reviewer.agent !== 'planu-implementation-reviewer' ||
+            report.data.reviewer.verdict !== 'changes-requested' ||
+            digest(reportBytes) !== args.receipt.implementationReviewDigest) {
+            return failure('implementation review no longer matches the durable receipt', 'RECONCILIATION_BINDING_CONFLICT');
+        }
+    }
+    catch {
+        return failure('implementation review is unavailable for reconciliation recovery', 'RECONCILIATION_BINDING_CONFLICT');
+    }
+    return null;
+}
+/** Read all committed receipts. Invalid or unsafe recovery state fails closed. */
+export async function readCommittedReconciliations(projectId, specId) {
+    return readCommittedReconciliationReceipts(projectId, specId);
+}
+function receiptMatchesRequest(receipt, projectId, specId, requestId) {
+    return (receipt.projectId === projectId && receipt.specId === specId && receipt.requestId === requestId);
+}
+// eslint-disable-next-line max-lines-per-function -- transaction recovery keeps rollback and forward-only phases in one auditable boundary
+export async function reconcileImplementingSpec(args) {
+    const requestId = args.input.reconciliationRequestId;
+    if (!requestId || !REQUEST_ID.test(requestId)) {
+        return failure('reconciliationRequestId must be a lowercase RFC 4122 UUID');
+    }
+    if (args.context.surface !== 'local-mcp') {
+        return failure('reconciliation is available only through local MCP', 'RECONCILIATION_UNTRUSTED_SURFACE');
+    }
+    const lock = await acquireLock(args.projectPath ?? args.projectId, args.input.specId, {
+        reason: 'implementing to review reconciliation',
+    });
+    if (!lock) {
+        return failure('reconciliation is already running', 'RECONCILIATION_BUSY');
+    }
+    try {
+        const appendOnlyEffect = { value: false };
+        const persistReceipt = (path, receipt) => args.io?.writeReceipt?.(path, receipt) ?? writeReconciliationReceipt(path, receipt);
+        const receiptPath = await safeReceiptPath(args.projectId, args.input.specId, requestId);
+        const existing = await readReconciliationReceipt(receiptPath);
+        const spec = await specStore.getSpecFresh(args.projectId, args.input.specId);
+        if (!spec) {
+            return failure(`spec ${args.input.specId} not found`);
+        }
+        if (existing && !receiptMatchesRequest(existing, args.projectId, spec.id, requestId)) {
+            return failure('reconciliation receipt identity does not match the request');
+        }
+        if (existing?.state === 'committed') {
+            const bindingError = validateDurableReceiptBinding({
+                input: args.input,
+                receipt: existing,
+                projectId: args.projectId,
+                specId: spec.id,
+            });
+            if (bindingError) {
+                return bindingError;
+            }
+            return {
+                content: [{ type: 'text', text: `Reconciliation ${requestId} already committed.` }],
+                structuredContent: { receipt: existing },
+            };
+        }
+        if (existing) {
+            const bindingError = await validateStoredBinding({
+                input: args.input,
+                receipt: existing,
+                projectId: args.projectId,
+                specId: spec.id,
+            });
+            if (bindingError) {
+                return bindingError;
+            }
+        }
+        if (existing?.state === 'aborted') {
+            return failure('an aborted reconciliation request cannot be reused', 'RECONCILIATION_ABORTED');
+        }
+        const recoveredBinding = existing
+            ? spec.statusHistory?.find((entry) => entry.reconciliationRequestId === requestId &&
+                entry.reconciliationBindingDigest === existing.bindingDigest &&
+                entry.trigger === 'reconciliation')
+            : undefined;
+        if (existing && recoveredBinding) {
+            const committed = await completeForwardReconciliation({
+                receipt: existing,
+                spec,
+                transitionId: recoveredBinding.transitionId ?? '',
+                projectId: args.projectId,
+                projectPath: args.projectPath,
+                reason: args.input.reason,
+                receiptPath,
+                persistReceipt,
+                markAppendOnly: () => {
+                    appendOnlyEffect.value = true;
+                },
+                syncSpecFiles: args.syncSpecFiles,
+            });
+            return {
+                content: [{ type: 'text', text: `Reconciliation ${requestId} recovered.` }],
+                structuredContent: { receipt: committed },
+            };
+        }
+        const validated = await validateRequest({
+            input: args.input,
+            spec,
+            projectId: args.projectId,
+            context: args.context,
+        });
+        if (!('bindingDigest' in validated) ||
+            typeof validated.bindingDigest !== 'string' ||
+            typeof validated.reviewDigest !== 'string') {
+            return validated;
+        }
+        const expectedTransitionId = args.input.expectedImplementingTransitionId;
+        const reason = args.input.reason;
+        if (!expectedTransitionId || !reason) {
+            return failure('validated reconciliation request is incomplete');
+        }
+        let receipt = existing ??
+            (() => {
+                const preparedAt = new Date().toISOString();
+                return {
+                    schema_version: '1.0.0',
+                    projectId: args.projectId,
+                    specId: spec.id,
+                    requestId,
+                    sourceImplementingTransitionId: expectedTransitionId,
+                    sourceUpdatedAt: spec.updatedAt,
+                    bindingDigest: validated.bindingDigest,
+                    reasonDigest: digest(reason.trim()),
+                    implementationReviewDigest: validated.reviewDigest,
+                    supersededArtifacts: [],
+                    state: 'prepared',
+                    stateHistory: [{ state: 'prepared', at: preparedAt }],
+                    preparedAt,
+                    phase: 'prepared',
+                };
+            })();
+        if (!existing) {
+            receipt.supersededArtifacts = await collectSupersededReconciliationArtifacts(args.projectId, spec.id);
+            await persistReceipt(receiptPath, receipt);
+        }
+        if (spec.status !== 'implementing' || spec.updatedAt !== receipt.sourceUpdatedAt) {
+            return failure('prepared receipt cannot be safely resumed after state drift', 'RECONCILIATION_RECOVERY_REQUIRED');
+        }
+        let transition;
+        try {
+            transition = await transitionSpec(args.projectId, spec.id, 'review', {
+                trigger: 'reconciliation',
+                actor: 'local-mcp',
+                reason: args.input.reason,
+                expectedSpec: spec,
+                reconciliationRequestId: requestId,
+                reconciliationBindingDigest: receipt.bindingDigest,
+            });
+            receipt = { ...receipt, transitionId: transition.transitionId, phase: 'status-committed' };
+            await persistReceipt(receiptPath, receipt);
+            const committed = await completeForwardReconciliation({
+                receipt,
+                spec: transition.spec,
+                transitionId: transition.transitionId,
+                projectId: args.projectId,
+                projectPath: args.projectPath,
+                reason: args.input.reason,
+                receiptPath,
+                persistReceipt,
+                markAppendOnly: () => {
+                    appendOnlyEffect.value = true;
+                },
+                syncSpecFiles: args.syncSpecFiles,
+            });
+            return {
+                content: [{ type: 'text', text: `Reconciliation ${requestId} committed.` }],
+                structuredContent: { receipt: committed, transitionId: transition.transitionId },
+            };
+        }
+        catch (error) {
+            if (appendOnlyEffect.value || receipt.phase === 'audit-appended') {
+                return failure('reconciliation requires forward recovery after append-only audit', 'RECONCILIATION_RECOVERY_REQUIRED');
+            }
+            if (transition) {
+                try {
+                    await rollbackTransitionSpec(transition);
+                    const rollbackSync = await args.syncSpecFiles(transition.previousSpec, 'review', 'implementing', args.projectPath);
+                    if (rollbackSync.warning) {
+                        const recoverable = appendState(receipt, 'prepared', `portable rollback sync failed: ${rollbackSync.warning.reason}`);
+                        await persistReceipt(receiptPath, recoverable);
+                        return failure('reconciliation rollback sync failed; receipt remains prepared for operator recovery', 'RECONCILIATION_RECOVERY_REQUIRED');
+                    }
+                }
+                catch (rollbackError) {
+                    const recoverable = appendState(receipt, 'prepared', `rollback failed: ${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}`);
+                    await persistReceipt(receiptPath, recoverable);
+                    return failure('reconciliation rollback failed; receipt remains prepared for operator recovery', 'RECONCILIATION_RECOVERY_REQUIRED');
+                }
+            }
+            const aborted = appendState(receipt, 'aborted', error instanceof Error ? error.message : 'transition failed');
+            await persistReceipt(receiptPath, aborted);
+            return failure('reconciliation failed and was compensated', 'RECONCILIATION_ABORTED');
+        }
+    }
+    catch (error) {
+        return failure(error instanceof Error ? error.message : 'reconciliation failed');
+    }
+    finally {
+        await releaseLock(lock);
+    }
+}
+//# sourceMappingURL=lifecycle-reconciliation.js.map

package/dist/engine/local-first/storage-advisor.js

@@ -1,7 +1,4 @@
-// SPEC-597-EXEMPT: canonical mapping (npm-package↔framework, keyword catalogue)
-// — must enumerate framework names by design; no detection logic to migrate.
-// engine/local-first/storage-advisor.ts — SPEC-047
-// Generates offline storage recommendations and schema evolution criteria.
+import { technologyValue } from '../technology-registry.js';
 /** Detect the target platform from framework and stack information. */
 export function detectTargetPlatform(framework, stack) {
     const stackLower = stack.map((s) => s.toLowerCase()).join(' ');
@@ -9,13 +6,15 @@ export function detectTargetPlatform(framework, stack) {
     if (fw.includes('react-native') || fw.includes('expo') || stackLower.includes('react-native')) {
         return 'mobile-rn';
     }
-    if (fw.includes('flutter') || stackLower.includes('flutter')) {
+    if (fw.includes(technologyValue('technology-flutter-be1396')) ||
+        stackLower.includes(technologyValue('technology-flutter-be1396'))) {
         return 'mobile-flutter';
     }
     if (fw.includes('tauri') || stackLower.includes('tauri')) {
         return 'desktop-tauri';
     }
-    if (fw.includes('electron') || stackLower.includes('electron')) {
+    if (fw.includes(technologyValue('technology-electron-88b1de')) ||
+        stackLower.includes(technologyValue('technology-electron-88b1de'))) {
         return 'desktop-electron';
     }
     return 'web';

package/dist/engine/local-first/tool-classification.js

@@ -1,3 +1,4 @@
+import { OFFICIAL_SDD_TOOL_NAMES } from '../../config/official-sdd-tools.js';
 const REGISTERED_TOOL_NAMES = [
     'agent_run_history',
     'analyze_spec_dependencies',
@@ -244,6 +245,7 @@ const NO_LLM_LOCAL_TOOL_NAMES = [
     'worker_status',
 ];
 const EXPLICIT_TOOL_NAMES = new Set([
+    ...OFFICIAL_SDD_TOOL_NAMES,
     ...REGISTERED_TOOL_NAMES,
     ...LEGACY_OR_RUNTIME_TOOL_NAMES,
 ]);

package/dist/engine/macos-keychain-native-port.d.ts

@@ -0,0 +1,10 @@
+import type { PlanuCore } from '../types/core-bridge.js';
+import type { MacOSKeychainNativePort } from '../types/security.js';
+export declare class ValidationReceiptSignerUnavailableError extends Error {
+    readonly reason: 'PLATFORM_UNSUPPORTED' | 'NATIVE_DISABLED' | 'ARTIFACT_MISSING' | 'NONCANONICAL_ORIGIN' | 'CAPABILITY_MISSING' | 'PORT_INCOMPLETE' | 'OVERRIDE_REJECTED' | 'PROVIDER_NONCANONICAL' | 'PROVIDER_UNAVAILABLE';
+    readonly code: 'VALIDATION_RECEIPT_SIGNER_UNAVAILABLE';
+    constructor(reason: 'PLATFORM_UNSUPPORTED' | 'NATIVE_DISABLED' | 'ARTIFACT_MISSING' | 'NONCANONICAL_ORIGIN' | 'CAPABILITY_MISSING' | 'PORT_INCOMPLETE' | 'OVERRIDE_REJECTED' | 'PROVIDER_NONCANONICAL' | 'PROVIDER_UNAVAILABLE');
+}
+/** Build the privileged main-thread port only from a canonical, verified native module. */
+export declare function createMacOSKeychainNativePort(platform: NodeJS.Platform, overrideDefined: boolean, disabled: boolean, nativeModule: PlanuCore | null, origin: 'override' | 'local' | 'package' | undefined, capabilities: readonly string[] | undefined): MacOSKeychainNativePort;
+//# sourceMappingURL=macos-keychain-native-port.d.ts.map

package/dist/engine/macos-keychain-native-port.js

@@ -0,0 +1,38 @@
+export class ValidationReceiptSignerUnavailableError extends Error {
+    reason;
+    code = 'VALIDATION_RECEIPT_SIGNER_UNAVAILABLE';
+    constructor(reason) {
+        super(`[Planu] VALIDATION_RECEIPT_SIGNER_UNAVAILABLE:${reason} Restart the MCP host and retry.`);
+        this.reason = reason;
+        this.name = 'ValidationReceiptSignerUnavailableError';
+    }
+}
+/** Build the privileged main-thread port only from a canonical, verified native module. */
+export function createMacOSKeychainNativePort(platform, overrideDefined, disabled, nativeModule, origin, capabilities) {
+    if (platform !== 'darwin') {
+        throw new ValidationReceiptSignerUnavailableError('PLATFORM_UNSUPPORTED');
+    }
+    if (overrideDefined || origin === 'override') {
+        throw new ValidationReceiptSignerUnavailableError('OVERRIDE_REJECTED');
+    }
+    if (disabled) {
+        throw new ValidationReceiptSignerUnavailableError('NATIVE_DISABLED');
+    }
+    if (!nativeModule) {
+        throw new ValidationReceiptSignerUnavailableError('ARTIFACT_MISSING');
+    }
+    if (origin !== 'local' && origin !== 'package') {
+        throw new ValidationReceiptSignerUnavailableError('NONCANONICAL_ORIGIN');
+    }
+    if (!capabilities?.includes('macos-keychain-v1')) {
+        throw new ValidationReceiptSignerUnavailableError('CAPABILITY_MISSING');
+    }
+    const set = nativeModule.macosKeychainSet?.bind(nativeModule);
+    const get = nativeModule.macosKeychainGet?.bind(nativeModule);
+    const remove = nativeModule.macosKeychainDelete?.bind(nativeModule);
+    if (!set || !get || !remove) {
+        throw new ValidationReceiptSignerUnavailableError('PORT_INCOMPLETE');
+    }
+    return { set, get, delete: remove };
+}
+//# sourceMappingURL=macos-keychain-native-port.js.map

package/dist/engine/marketplace-fetcher/cache.js

@@ -2,6 +2,8 @@
 // Reads/writes to .planu/skill-cache/{source}/{skillName}.md (NOT planu/ — internal cache).
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
+import { hashProjectPath } from '../../storage/base-store.js';
+import { resolveStorageLayout } from '../../storage/storage-layout.js';
 // ---------------------------------------------------------------------------
 // Constants — single exported location (no per-call literals)
 // ---------------------------------------------------------------------------
@@ -11,7 +13,7 @@ export const FETCHED_HEADER_PREFIX = '<!-- fetched:';
 // Helpers
 // ---------------------------------------------------------------------------
 function cachePath(projectPath, source, skillName) {
-    return join(projectPath, '.planu', 'skill-cache', source, `${skillName}.md`);
+    return join(resolveStorageLayout().cache, 'skills', hashProjectPath(projectPath), source, `${skillName}.md`);
 }
 /** Parse the fetchedAt ISO timestamp from the header comment in a cached file. */
 function parseFetchedAt(content) {

package/dist/engine/mcp-config/mcp-config-writer.d.ts

@@ -9,9 +9,9 @@ import type { CheckAndFixResult } from '../../types/mcp-config.js';
  */
 export declare function findMcpConfigPath(projectPath: string): Promise<string>;
 /**
- * Returns true if the config already has a safe `planu` entry pointing to @planu/cli@latest.
+ * Returns true if the config already has a safe, exact-version `planu` entry.
  */
-export declare function isPlanuDirectlyConfigured(configPath: string): Promise<boolean>;
+export declare function isPlanuDirectlyConfigured(configPath: string, expectedVersion?: string): Promise<boolean>;
 /**
  * Merges the direct Planu entry into the config file.
  * Does not overwrite unrelated keys.

package/dist/engine/mcp-config/mcp-config-writer.js

@@ -4,12 +4,11 @@
 import { readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
-import { buildNpxLatestEntry } from '../auto-updater/config-patcher.js';
+import { buildPinnedEntry } from '../auto-updater/config-patcher.js';
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
 const PLANU_KEY = 'planu';
-const PLANU_LATEST_ARG = '@planu/cli@latest';
 const MIN_STARTUP_TIMEOUT_SEC = 60;
 // ---------------------------------------------------------------------------
 // Helpers
@@ -62,9 +61,9 @@ export async function findMcpConfigPath(projectPath) {
     return join(projectPath, '.mcp.json');
 }
 /**
- * Returns true if the config already has a safe `planu` entry pointing to @planu/cli@latest.
+ * Returns true if the config already has a safe, exact-version `planu` entry.
  */
-export async function isPlanuDirectlyConfigured(configPath) {
+export async function isPlanuDirectlyConfigured(configPath, expectedVersion) {
     const config = await readJsonFile(configPath);
     const servers = config.mcpServers;
     if (servers === undefined) {
@@ -78,7 +77,10 @@ export async function isPlanuDirectlyConfigured(configPath) {
     if (!Array.isArray(args)) {
         return false;
     }
-    return (args.includes(PLANU_LATEST_ARG) &&
+    const expected = expectedVersion ? `@planu/cli@${expectedVersion}` : undefined;
+    const pinned = args.find((value) => /^@planu\/cli@\d+\.\d+\.\d+(?:[-+][\w.-]+)?$/.test(value));
+    return Boolean(pinned &&
+        (expected === undefined || pinned === expected) &&
         (planuEntry.startup_timeout_sec ?? 0) >= MIN_STARTUP_TIMEOUT_SEC);
 }
 /**
@@ -88,7 +90,7 @@ export async function isPlanuDirectlyConfigured(configPath) {
 export async function injectDirectPlanuEntry(configPath, currentVersion, latestVersion) {
     const existing = await readJsonFile(configPath);
     const mcpServers = existing.mcpServers !== undefined ? { ...existing.mcpServers } : {};
-    mcpServers[PLANU_KEY] = buildNpxLatestEntry();
+    mcpServers[PLANU_KEY] = buildPinnedEntry(latestVersion);
     const updated = {
         ...existing,
         mcpServers,
@@ -110,9 +112,9 @@ export async function injectDirectPlanuEntry(configPath, currentVersion, latestV
  */
 export async function checkAndFixBundledVersion(projectPath, currentVersion, latestVersion) {
     const configPath = await findMcpConfigPath(projectPath);
-    const alreadyConfigured = await isPlanuDirectlyConfigured(configPath);
+    const alreadyConfigured = await isPlanuDirectlyConfigured(configPath, latestVersion);
     if (alreadyConfigured) {
-        return { configured: false, reason: 'already configured with @planu/cli@latest' };
+        return { configured: false, reason: `already configured with @planu/cli@${latestVersion}` };
     }
     await injectDirectPlanuEntry(configPath, currentVersion, latestVersion);
     /* c8 ignore next — `?? configPath` fallback is unreachable (split always produces at least one element) */

package/dist/engine/migration/db-migrator.js

@@ -1,7 +1,4 @@
-// SPEC-597-EXEMPT: canonical mapping (npm-package↔framework, keyword catalogue)
-// — must enumerate framework names by design; no detection logic to migrate.
-// engine/migration/db-migrator.ts — Database migration planning (SPEC-028a)
-// analyze-db, map-db, plan-db actions
+import { technologyValue } from '../technology-registry.js';
 // --- Type mapping knowledge base ---
 const POSTGRES_TO_MONGO = [
     { sourceType: 'TEXT', targetType: 'String', dataLossRisk: false },
@@ -93,7 +90,7 @@ function detectMigrationType(source, target) {
     ]);
     const newSqlEngines = new Set(['cockroachdb', 'spanner', 'tidb', 'alloydb']);
     const cloudManaged = new Set([
-        'supabase',
+        technologyValue('technology-supabase-4d7594'),
         'aurora',
         'neon',
         'planetscale',