@planu/cli 4.14.1 → 5.0.0

package/dist/engine/lifecycle-reconciliation-io.js

@@ -0,0 +1,180 @@
+import { createHash } from 'node:crypto';
+import { lstat, mkdir, readFile, readdir, realpath } from 'node:fs/promises';
+import { basename, join, relative, resolve, sep } from 'node:path';
+import { projectDataDir, readJson, writeJson } from '../storage/base-store.js';
+import { ReconciliationReceiptV1Schema } from './handoff-artifacts/schemas.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 ARTIFACTS = [
+    'spec.lock.json',
+    'review_feedback.md',
+    'task-plan.json',
+    'implementation-report.json',
+    'validation-report.json',
+    'traceability-matrix.json',
+    'context-package.json',
+];
+export function reconciliationDigest(value) {
+    return `sha256:${createHash('sha256').update(value).digest('hex')}`;
+}
+function receiptDirectory(projectId, specId) {
+    return join(projectDataDir(projectId), 'handoffs', specId, 'reconciliations');
+}
+function isOutside(root, candidate) {
+    const pathFromRoot = relative(root, candidate);
+    return (pathFromRoot === '..' || pathFromRoot.startsWith(`..${sep}`) || pathFromRoot.startsWith('..'));
+}
+async function assertAncestors(projectId, specId, create) {
+    const dataRoot = projectDataDir(projectId);
+    const directory = receiptDirectory(projectId, specId);
+    const ancestors = [
+        dataRoot,
+        join(dataRoot, 'handoffs'),
+        join(dataRoot, 'handoffs', specId),
+        directory,
+    ];
+    let parentRealPath;
+    for (const [index, ancestor] of ancestors.entries()) {
+        if (create) {
+            try {
+                await mkdir(ancestor, { recursive: index === 0, mode: 0o700 });
+            }
+            catch (error) {
+                if (!(error instanceof Error && 'code' in error && error.code === 'EEXIST')) {
+                    throw error;
+                }
+            }
+        }
+        const status = await lstat(ancestor);
+        if (status.isSymbolicLink() || !status.isDirectory()) {
+            throw new Error('reconciliation directory has an unsafe ancestor');
+        }
+        const ancestorRealPath = await realpath(ancestor);
+        if (parentRealPath && isOutside(parentRealPath, ancestorRealPath)) {
+            throw new Error('reconciliation directory escapes the canonical handoff root');
+        }
+        parentRealPath = ancestorRealPath;
+    }
+    return directory;
+}
+export async function safeReceiptPath(projectId, specId, requestId) {
+    if (!REQUEST_ID.test(requestId) || basename(requestId) !== requestId) {
+        throw new Error('invalid reconciliation request ID');
+    }
+    const directory = await assertAncestors(projectId, specId, true);
+    const root = await realpath(directory);
+    const candidate = resolve(root, `${requestId}.json`);
+    if (isOutside(root, candidate)) {
+        throw new Error('reconciliation receipt path escapes its directory');
+    }
+    try {
+        const status = await lstat(candidate);
+        if (status.isSymbolicLink() || !status.isFile()) {
+            throw new Error('reconciliation receipt is not a regular file');
+        }
+    }
+    catch (error) {
+        if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) {
+            throw error;
+        }
+    }
+    return candidate;
+}
+export async function readReconciliationReceipt(path) {
+    try {
+        const candidate = await lstat(path);
+        if (candidate.isSymbolicLink() || !candidate.isFile()) {
+            throw new Error('reconciliation receipt is not a regular file');
+        }
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            return null;
+        }
+        throw error;
+    }
+    const parsed = ReconciliationReceiptV1Schema.safeParse(await readJson(path, null));
+    if (!parsed.success) {
+        throw new Error('reconciliation receipt is invalid');
+    }
+    return parsed.data;
+}
+export async function writeReconciliationReceipt(path, receipt) {
+    try {
+        const status = await lstat(path);
+        if (status.isSymbolicLink() || !status.isFile()) {
+            throw new Error('reconciliation receipt is unsafe');
+        }
+    }
+    catch (error) {
+        if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) {
+            throw error;
+        }
+    }
+    await writeJson(path, receipt);
+}
+export async function collectSupersededReconciliationArtifacts(projectId, specId) {
+    const handoff = join(projectDataDir(projectId), 'handoffs', specId);
+    const candidates = [
+        ...ARTIFACTS.map((name) => ({
+            artifactId: `handoffs/${specId}/${name}`,
+            path: join(handoff, name),
+        })),
+        {
+            artifactId: `handoffs/${specId}.md`,
+            path: join(projectDataDir(projectId), 'handoffs', `${specId}.md`),
+        },
+    ];
+    try {
+        const names = await readdir(handoff);
+        for (const artifactName of names.filter((candidate) => /^contract-validation-[A-Za-z0-9_-]+\.json$/u.test(candidate))) {
+            candidates.push({
+                artifactId: `handoffs/${specId}/${artifactName}`,
+                path: join(handoff, artifactName),
+            });
+        }
+    }
+    catch (error) {
+        if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) {
+            throw error;
+        }
+    }
+    return Promise.all(candidates.map(async ({ artifactId, path }) => {
+        try {
+            const stat = await lstat(path);
+            if (stat.isSymbolicLink() || !stat.isFile()) {
+                throw new Error(`unsafe artifact ${artifactId}`);
+            }
+            return { artifactId, sha256: reconciliationDigest(await readFile(path)) };
+        }
+        catch (error) {
+            if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+                return { artifactId };
+            }
+            throw error;
+        }
+    }));
+}
+export async function readCommittedReconciliationReceipts(projectId, specId) {
+    try {
+        const directory = await assertAncestors(projectId, specId, false);
+        const root = await realpath(directory);
+        const names = await readdir(root);
+        const receipts = await Promise.all(names
+            .filter((name) => REQUEST_ID.test(name.replace(/\.json$/u, '')) && name.endsWith('.json'))
+            .map((name) => {
+            const path = join(root, name);
+            if (isOutside(root, path)) {
+                throw new Error('reconciliation receipt path escapes its directory');
+            }
+            return readReconciliationReceipt(path);
+        }));
+        return receipts.filter((receipt) => receipt?.state === 'committed');
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=lifecycle-reconciliation-io.js.map

package/dist/engine/lifecycle-reconciliation.d.ts

@@ -0,0 +1,16 @@
+import type { ReconciliationIo, ReconciliationReceiptV1, ReconciliationSpecSync } from '../types/handoff-artifacts.js';
+import type { ReconciliationInvocationContext, ToolResult, UpdateStatusInput } from '../types/index.js';
+/** The registrar, not caller-controlled tool input, establishes local authority. */
+export declare function runWithTrustedLocalMcpContext<T>(callback: () => T): T;
+export declare function currentReconciliationInvocationContext(): ReconciliationInvocationContext;
+/** Read all committed receipts. Invalid or unsafe recovery state fails closed. */
+export declare function readCommittedReconciliations(projectId: string, specId: string): Promise<ReconciliationReceiptV1[]>;
+export declare function reconcileImplementingSpec(args: {
+    input: UpdateStatusInput;
+    projectId: string;
+    projectPath?: string;
+    context: ReconciliationInvocationContext;
+    syncSpecFiles: ReconciliationSpecSync;
+    io?: ReconciliationIo;
+}): Promise<ToolResult>;
+//# sourceMappingURL=lifecycle-reconciliation.d.ts.map

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/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

@@ -1,5 +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

@@ -1,25 +1,37 @@
+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 Error('[Planu] macOS Keychain is unavailable on this platform');
+        throw new ValidationReceiptSignerUnavailableError('PLATFORM_UNSUPPORTED');
     }
     if (overrideDefined || origin === 'override') {
-        throw new Error('[Planu] macOS Keychain rejects native path overrides');
+        throw new ValidationReceiptSignerUnavailableError('OVERRIDE_REJECTED');
+    }
+    if (disabled) {
+        throw new ValidationReceiptSignerUnavailableError('NATIVE_DISABLED');
     }
-    if (disabled || !nativeModule) {
-        throw new Error('[Planu] Verified macOS Keychain native capability is unavailable');
+    if (!nativeModule) {
+        throw new ValidationReceiptSignerUnavailableError('ARTIFACT_MISSING');
     }
     if (origin !== 'local' && origin !== 'package') {
-        throw new Error('[Planu] macOS Keychain requires a canonical native artifact origin');
+        throw new ValidationReceiptSignerUnavailableError('NONCANONICAL_ORIGIN');
     }
     if (!capabilities?.includes('macos-keychain-v1')) {
-        throw new Error('[Planu] Verified native runtime lacks 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 Error('[Planu] Verified native runtime has an incomplete macOS Keychain port');
+        throw new ValidationReceiptSignerUnavailableError('PORT_INCOMPLETE');
     }
     return { set, get, delete: remove };
 }

package/dist/engine/migrations/remove-commercial-state.d.ts

@@ -0,0 +1,3 @@
+import type { RemoveCommercialStateOptions, RemoveCommercialStateResult } from '../../types/commercial-migration.js';
+export declare function removeCommercialState(options?: RemoveCommercialStateOptions): Promise<RemoveCommercialStateResult>;
+//# sourceMappingURL=remove-commercial-state.d.ts.map