@planu/cli 5.3.67 → 5.3.68

package/CHANGELOG.md

@@ -1,3 +1,27 @@
+## [5.3.68] - 2026-08-28
+
+### Features
+- feat(SPEC-1666): produce source-quality receipt pre-bump with fail-fast gate order
+
+### Bug Fixes
+- fix(SPEC-1668): scope metric masking, byte-equality guard and uniform anchors per dual review
+- fix(SPEC-1668): bind product-proof bump regeneration fields and harden fixture commit retry
+- fix(SPEC-1666): align release-pipeline recovery suite with bump-neutral receipt contract
+- fix(SPEC-1666): byte-preserving carrier normalization with derivation checks and mode-bound masking
+- fix(SPEC-1315): classify degraded reads in portable spec-path migration
+- fix(SPEC-1315): verify canonical root and trigger migration on lifecycle reads
+- fix(SPEC-1315): keep spec paths portable across worktrees and release clones
+
+### Chores
+- chore: absorb post-done session state
+- chore(SPEC-1668): record done transition
+- chore(SPEC-1668): record approval transition
+- chore(SPEC-1666): record done transition
+- chore(SPEC-1666): record implementing transition
+- chore(SPEC-1315): record done transition and session state
+- chore(specs): approve SPEC-1660..1664 with reviewer and discovery evidence
+
+
 ## [5.3.67] - 2026-08-28
 
 ### Bug Fixes

package/dist/.planu-build.json

@@ -1 +1 @@
-{"schemaVersion":1,"commit":"fde3438aa03084c32064ee5f7ec4179e455e6062"}
+{"schemaVersion":1,"commit":"39afacbb6522be60172b8571f6c5973000936a4a"}

package/dist/config/release-policy.json

@@ -11,10 +11,10 @@
       "^src/config/release-policy\\.json$"
     ],
     "sourceQualityPlan": [
-      { "id": "validate", "executable": "pnpm", "args": ["validate"], "timeoutSeconds": 1800 },
-      { "id": "strict", "executable": "pnpm", "args": ["check:strict"], "timeoutSeconds": 1800 },
       { "id": "reliability", "executable": "pnpm", "args": ["check:reliability"], "timeoutSeconds": 1800 },
       { "id": "dependency-freshness", "executable": "pnpm", "args": ["check:deps:fresh"], "timeoutSeconds": 1800 },
+      { "id": "validate", "executable": "pnpm", "args": ["validate"], "timeoutSeconds": 1800 },
+      { "id": "strict", "executable": "pnpm", "args": ["check:strict"], "timeoutSeconds": 1800 },
       { "id": "coverage", "executable": "pnpm", "args": ["test:coverage"], "timeoutSeconds": 1800 },
       { "id": "mutation", "executable": "pnpm", "args": ["audit:mutation"], "timeoutSeconds": 1800 }
     ]

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

@@ -1,4 +1,6 @@
 import type { RegisteredProject, GlobalProjectsRegistry } from '../types/index.js';
+/** Best-effort, non-creating read of a checkout's logical project identity. */
+export declare function readLogicalProjectId(projectPath: string): Promise<string | undefined>;
 /**
  * Read the full registry from disk.
  * Returns an empty registry when the file does not exist.
@@ -15,6 +17,21 @@ export declare function saveRegistry(registry: GlobalProjectsRegistry): Promise<
  * Returns the registered project entry.
  */
 export declare function addProject(projectPath: string): Promise<RegisteredProject>;
+/** Stable, classified failure for a logical project id with no unambiguous canonical root. */
+export type CanonicalRootResult = {
+    readonly ok: true;
+    readonly root: string;
+} | {
+    readonly ok: false;
+    readonly reason: 'zero' | 'ambiguous';
+    readonly roots: readonly string[];
+};
+/**
+ * Resolve the single canonical root registered for a logical project identity.
+ * Fails closed — never guesses a first match — when zero or more than one
+ * distinct registered path claims the same `logicalProjectId`.
+ */
+export declare function getCanonicalRoot(logicalProjectId: string): Promise<CanonicalRootResult>;
 /**
  * Remove a project from the registry by path.
  * Returns true if the project was found and removed, false otherwise.

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

@@ -4,6 +4,23 @@ import { readJson, writeJson, globalDataDir, hashProjectPath } from './base-stor
 import { withFileLock } from './file-mutex.js';
 import { isEphemeralProject } from '../engine/data-projects-gc/pattern-matcher.js';
 import { reportClassifiedDegradation } from '../errors/classified-degradation.js';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+/** Best-effort, non-creating read of a checkout's logical project identity. */
+export async function readLogicalProjectId(projectPath) {
+    try {
+        const raw = JSON.parse(await readFile(join(projectPath, 'planu', 'project.json'), 'utf8'));
+        const id = raw?.logicalProjectId;
+        return typeof id === 'string' && UUID_PATTERN.test(id) ? id : undefined;
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            reportClassifiedDegradation('LOGICAL_PROJECT_ID_READ_FAILED', error);
+        }
+        return undefined;
+    }
+}
 // ---------------------------------------------------------------------------
 // File path
 // ---------------------------------------------------------------------------
@@ -46,11 +63,15 @@ export async function addProject(projectPath) {
             specCount: 0,
         };
     }
+    const logicalProjectId = await readLogicalProjectId(projectPath);
     return withFileLock(registryFile(), async () => {
         const registry = await getRegistry();
         const existing = registry.projects.find((p) => p.path === projectPath);
         if (existing !== undefined) {
             existing.hash = hash;
+            if (logicalProjectId !== undefined) {
+                existing.logicalProjectId = logicalProjectId;
+            }
             registry.updatedAt = new Date().toISOString();
             await saveRegistry(registry);
             return existing;
@@ -60,6 +81,7 @@ export async function addProject(projectPath) {
             hash,
             registeredAt: new Date().toISOString(),
             specCount: 0,
+            ...(logicalProjectId !== undefined && { logicalProjectId }),
         };
         registry.projects.push(entry);
         registry.updatedAt = new Date().toISOString();
@@ -67,6 +89,30 @@ export async function addProject(projectPath) {
         return entry;
     });
 }
+/**
+ * Resolve the single canonical root registered for a logical project identity.
+ * Fails closed — never guesses a first match — when zero or more than one
+ * distinct registered path claims the same `logicalProjectId`.
+ */
+export async function getCanonicalRoot(logicalProjectId) {
+    const projects = await getProjects();
+    const roots = [
+        ...new Set(projects
+            .filter((project) => project.logicalProjectId === logicalProjectId)
+            .map((project) => project.path)),
+    ];
+    if (roots.length === 0) {
+        return { ok: false, reason: 'zero', roots };
+    }
+    if (roots.length > 1) {
+        return { ok: false, reason: 'ambiguous', roots };
+    }
+    const [root] = roots;
+    if (root === undefined) {
+        return { ok: false, reason: 'zero', roots };
+    }
+    return { ok: true, root };
+}
 /**
  * Remove a project from the registry by path.
  * Returns true if the project was found and removed, false otherwise.

package/dist/storage/project-identity.d.ts

@@ -27,6 +27,33 @@ export declare function hashWorkspaceKey(workspaceKey: string): string;
 export declare function deriveWorkspaceKey(projectPath: string): Promise<string>;
 /** Resolve or create stable project and machine-workspace UUIDs. */
 export declare function ensureProjectIdentity(projectPath: string, options: ProjectIdentityOptions): Promise<ResolvedProjectIdentity>;
+export type PortablePathErrorCode = 'INVALID_TYPE' | 'EMPTY' | 'NUL_BYTE' | 'NOT_PORTABLE_SHAPE' | 'WRONG_SPEC' | 'ESCAPES_ROOT' | 'ROOT_NOT_FOUND' | 'ROOT_UNVERIFIED' | 'NOT_FOUND' | 'SYMLINK' | 'NOT_FILE';
+/** Stable, classified failure for a spec path that cannot be resolved as a portable identity. */
+export declare class PortablePathError extends Error {
+    readonly code: PortablePathErrorCode;
+    constructor(code: PortablePathErrorCode, message: string);
+}
+/**
+ * Extract the portable `planu/specs/<specId[-slug]>/<filename>` suffix from a stored
+ * path value, rejecting anything that is not that exact shape for the given spec.
+ * Works for both legacy absolute values and already-portable relative ones — the
+ * incoming prefix is discarded, so this doubles as the legacy-path normalizer.
+ */
+export declare function toPortableSpecPath(specId: string, storedPath: unknown): string;
+/**
+ * Resolve a stored `specPath`/`technicalPath` value against the verified canonical
+ * root, returning the realpath of the contained file. Fails closed — with a stable
+ * classified {@link PortablePathError} — for any absent, malformed, escaping,
+ * symlinked, or cross-spec value, before any content is read or written.
+ */
+export declare function resolvePortableSpecPath(specId: string, storedPath: unknown, canonicalRoot: string): Promise<string>;
+/**
+ * Lifecycle-consumer entry point: verify the candidate root against the
+ * global project registry before resolving through it, so an unregistered,
+ * ambiguous, or stale checkout never stands in for the real canonical root.
+ * Delegates to {@link resolvePortableSpecPath} once verified.
+ */
+export declare function resolveVerifiedSpecPath(specId: string, storedPath: unknown, canonicalRoot: string): Promise<string>;
 /** Explicitly turn a copied project into an independent logical project. */
 export declare function forkProjectIdentity(projectPath: string, options: ProjectIdentityOptions): Promise<ResolvedProjectIdentity>;
 //# sourceMappingURL=project-identity.d.ts.map

package/dist/storage/project-identity.js

@@ -1,7 +1,9 @@
 import { createHash, randomUUID } from 'node:crypto';
-import { mkdir, open, readFile, realpath, rename, rm, stat } from 'node:fs/promises';
-import { basename, dirname, join, normalize, resolve, sep } from 'node:path';
+import { lstat, mkdir, open, readFile, realpath, rename, rm, stat } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, normalize, relative, resolve, sep } from 'node:path';
 import { resolveStorageLayout } from './storage-layout.js';
+import { getCanonicalRoot, readLogicalProjectId } from './global-projects-store.js';
+import { isEphemeralProject } from '../engine/data-projects-gc/pattern-matcher.js';
 const IDENTITY_VERSION = 1;
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 function isProjectIdentity(value) {
@@ -156,6 +158,133 @@ export async function ensureProjectIdentity(projectPath, options) {
     const workspace = await ensureWorkspaceDocument(options.layout ?? resolveStorageLayout(), options.workspaceKey, project.logicalProjectId);
     return { project, workspace, canonicalProjectPath };
 }
+/** Stable, classified failure for a spec path that cannot be resolved as a portable identity. */
+export class PortablePathError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'PortablePathError';
+        this.code = code;
+    }
+}
+/**
+ * Extract the portable `planu/specs/<specId[-slug]>/<filename>` suffix from a stored
+ * path value, rejecting anything that is not that exact shape for the given spec.
+ * Works for both legacy absolute values and already-portable relative ones — the
+ * incoming prefix is discarded, so this doubles as the legacy-path normalizer.
+ */
+export function toPortableSpecPath(specId, storedPath) {
+    if (typeof storedPath !== 'string') {
+        throw new PortablePathError('INVALID_TYPE', '[Planu] specPath must be a string');
+    }
+    if (storedPath.includes('\0')) {
+        throw new PortablePathError('NUL_BYTE', '[Planu] specPath must not contain a NUL byte');
+    }
+    if (storedPath.trim().length === 0) {
+        throw new PortablePathError('EMPTY', '[Planu] specPath must not be empty or whitespace-only');
+    }
+    const segments = normalize(storedPath).split(sep).filter(Boolean);
+    const planuIndex = segments.lastIndexOf('planu');
+    const dir = segments[planuIndex + 2];
+    const filename = segments[planuIndex + 3];
+    const isPortableShape = planuIndex >= 0 &&
+        segments[planuIndex + 1] === 'specs' &&
+        dir !== undefined &&
+        filename !== undefined &&
+        planuIndex + 4 === segments.length;
+    if (!isPortableShape) {
+        throw new PortablePathError('NOT_PORTABLE_SHAPE', '[Planu] specPath is not a portable planu/specs/<dir>/<file> contract');
+    }
+    if (dir !== specId && !dir.startsWith(`${specId}-`)) {
+        throw new PortablePathError('WRONG_SPEC', `[Planu] specPath directory "${dir}" does not belong to ${specId}`);
+    }
+    return join('planu', 'specs', dir, filename);
+}
+function rejectsRootEscape(root, candidate) {
+    const rel = relative(root, candidate);
+    return rel.startsWith(`..${sep}`) || rel === '..' || isAbsolute(rel);
+}
+async function realpathClassified(path, notFoundCode) {
+    try {
+        return await realpath(path);
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            throw new PortablePathError(notFoundCode, `[Planu] path not found: ${notFoundCode}`);
+        }
+        throw error;
+    }
+}
+/**
+ * Reject a candidate root that carries a tracked logical project identity but
+ * is not the single registry-confirmed canonical root for it — a checkout
+ * left over from a rename/fork, or an ambiguous/unregistered project never
+ * resolves specs against an arbitrary directory. A candidate with no tracked
+ * identity (`planu/project.json` absent) is untracked, not unverified, and
+ * passes through unchanged — as does an ephemeral checkout (test fixture,
+ * scratch clone), since the global registry deliberately excludes those
+ * (SPEC-581) and can never confirm a root for them.
+ */
+async function rejectsUnverifiedRoot(root) {
+    if (isEphemeralProject(root)) {
+        return false;
+    }
+    const logicalProjectId = await readLogicalProjectId(root);
+    if (logicalProjectId === undefined) {
+        return false;
+    }
+    const canonical = await getCanonicalRoot(logicalProjectId);
+    return !canonical.ok || resolve(canonical.root) !== root;
+}
+/**
+ * Resolve a stored `specPath`/`technicalPath` value against the verified canonical
+ * root, returning the realpath of the contained file. Fails closed — with a stable
+ * classified {@link PortablePathError} — for any absent, malformed, escaping,
+ * symlinked, or cross-spec value, before any content is read or written.
+ */
+export async function resolvePortableSpecPath(specId, storedPath, canonicalRoot) {
+    const suffix = toPortableSpecPath(specId, storedPath);
+    const root = resolve(canonicalRoot);
+    const candidate = resolve(root, suffix);
+    if (rejectsRootEscape(root, candidate)) {
+        throw new PortablePathError('ESCAPES_ROOT', '[Planu] specPath escapes the canonical root');
+    }
+    const rootReal = await realpathClassified(root, 'ROOT_NOT_FOUND');
+    let candidateReal;
+    let candidateStat;
+    try {
+        candidateReal = await realpathClassified(candidate, 'NOT_FOUND');
+        candidateStat = await lstat(candidate);
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            throw new PortablePathError('NOT_FOUND', '[Planu] spec file not found under canonical root');
+        }
+        throw error;
+    }
+    if (candidateStat.isSymbolicLink()) {
+        throw new PortablePathError('SYMLINK', '[Planu] specPath must not resolve through a symlink');
+    }
+    if (!candidateStat.isFile()) {
+        throw new PortablePathError('NOT_FILE', '[Planu] specPath must resolve to a regular file');
+    }
+    if (rejectsRootEscape(rootReal, candidateReal)) {
+        throw new PortablePathError('ESCAPES_ROOT', '[Planu] specPath escapes the canonical root');
+    }
+    return candidateReal;
+}
+/**
+ * Lifecycle-consumer entry point: verify the candidate root against the
+ * global project registry before resolving through it, so an unregistered,
+ * ambiguous, or stale checkout never stands in for the real canonical root.
+ * Delegates to {@link resolvePortableSpecPath} once verified.
+ */
+export async function resolveVerifiedSpecPath(specId, storedPath, canonicalRoot) {
+    if (await rejectsUnverifiedRoot(resolve(canonicalRoot))) {
+        throw new PortablePathError('ROOT_UNVERIFIED', '[Planu] canonical root is not the single registry-confirmed root for this project');
+    }
+    return resolvePortableSpecPath(specId, storedPath, canonicalRoot);
+}
 /** Explicitly turn a copied project into an independent logical project. */
 export async function forkProjectIdentity(projectPath, options) {
     const canonicalProjectPath = await canonicalizeProjectPath(projectPath);

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

@@ -31,10 +31,31 @@ export declare function listSpecs(projectId: string): Promise<Spec[]>;
 export declare function withFreshSpecsLock<T>(projectId: string, fn: (specs: Spec[]) => Promise<T>): Promise<T>;
 /**
  * Get a single spec by ID. Returns `null` when not found.
- */
-export declare function getSpec(projectId: string, specId: string): Promise<Spec | null>;
+ *
+ * When `canonicalRoot` is supplied, a legacy absolute `specPath`/`technicalPath`
+ * for this spec is migrated to its portable project-relative identity first
+ * (best-effort — a failed migration attempt never blocks the read).
+ */
+export declare function getSpec(projectId: string, specId: string, canonicalRoot?: string): Promise<Spec | null>;
+/** Result of a {@link migrateLegacySpecPaths} run. */
+export interface SpecPathMigrationResult {
+    readonly migrated: number;
+    readonly specIds: readonly string[];
+}
+/**
+ * Atomically migrate every eligible legacy absolute `specPath`/`technicalPath`
+ * in this project to its portable project-relative identity.
+ *
+ * Runs under the existing cross-process spec-store lock. A record migrates only
+ * when its normalized relative suffix identifies the same spec and the file
+ * exists under the verified `canonicalRoot` — never by guessing. Migration
+ * changes only the stored path identity; it never touches spec content.
+ * Idempotent: a spec already holding a portable path is a no-op. Emits at
+ * most one audit event per call, regardless of how many specs migrated.
+ */
+export declare function migrateLegacySpecPaths(projectId: string, canonicalRoot: string, specIds?: readonly string[]): Promise<SpecPathMigrationResult>;
 /** Reload a spec from disk after the caller acquires its cross-process lock. */
-export declare function getSpecFresh(projectId: string, specId: string): Promise<Spec | null>;
+export declare function getSpecFresh(projectId: string, specId: string, canonicalRoot?: string): Promise<Spec | null>;
 /** SPEC-601: Lookup a spec by its globally unique UUID. */
 export declare function getSpecByUuid(projectId: string, uuid: string): Promise<Spec | null>;
 /**

package/dist/storage/spec-store.js

@@ -6,7 +6,11 @@ import { withFileLock } from './file-mutex.js';
 import { computeHealthScore } from '../engine/spec-health-scorer.js';
 import { loadSpecContent } from '../engine/validation-loop.js';
 import { createHash, randomUUID } from 'node:crypto';
+import { isAbsolute } from 'node:path';
 import { acquireLock, releaseLock } from '../engine/safety/cross-process-lock.js';
+import { resolvePortableSpecPath, toPortableSpecPath, PortablePathError, } from './project-identity.js';
+import { appendEntry, getLastHash } from './audit-trail-store.js';
+import { hashEntry } from '../engine/audit-trail/hasher.js';
 // ---------------------------------------------------------------------------
 // SPEC-720: Guard error — direct status write forbidden
 // ---------------------------------------------------------------------------
@@ -213,21 +217,136 @@ export async function withFreshSpecsLock(projectId, fn) {
 }
 /**
  * Get a single spec by ID. Returns `null` when not found.
+ *
+ * When `canonicalRoot` is supplied, a legacy absolute `specPath`/`technicalPath`
+ * for this spec is migrated to its portable project-relative identity first
+ * (best-effort — a failed migration attempt never blocks the read).
  */
-export async function getSpec(projectId, specId) {
+export async function getSpec(projectId, specId, canonicalRoot) {
+    if (canonicalRoot !== undefined) {
+        await migrateLegacySpecPaths(projectId, canonicalRoot, [specId]).catch((error) => {
+            reportClassifiedDegradation('SPEC_PATH_MIGRATION_DEFERRED', error);
+        });
+    }
     const specs = await loadAll(projectId);
     return specs.find((s) => s.id === specId) ?? null;
 }
+/**
+ * Record one hash-chained audit event for a legacy specPath migration batch.
+ * Best-effort: an audit failure never rolls back an already-persisted migration.
+ */
+function recordSpecPathMigrationAudit(projectId, specIds) {
+    try {
+        const partial = {
+            id: randomUUID(),
+            timestamp: new Date().toISOString(),
+            toolName: 'spec-store.migrateLegacySpecPaths',
+            inputSummary: `projectId=${projectId} specIds=${specIds.join(',')}`.slice(0, 200),
+            outputType: 'success',
+            durationMs: 0,
+            prevHash: getLastHash(),
+        };
+        appendEntry({ ...partial, hash: hashEntry(partial) });
+    }
+    catch (error) {
+        reportClassifiedDegradation('SPEC_PATH_MIGRATION_AUDIT', error);
+    }
+}
+/**
+ * Atomically migrate every eligible legacy absolute `specPath`/`technicalPath`
+ * in this project to its portable project-relative identity.
+ *
+ * Runs under the existing cross-process spec-store lock. A record migrates only
+ * when its normalized relative suffix identifies the same spec and the file
+ * exists under the verified `canonicalRoot` — never by guessing. Migration
+ * changes only the stored path identity; it never touches spec content.
+ * Idempotent: a spec already holding a portable path is a no-op. Emits at
+ * most one audit event per call, regardless of how many specs migrated.
+ */
+export async function migrateLegacySpecPaths(projectId, canonicalRoot, specIds) {
+    return withSpecMutationLock(projectId, async () => {
+        const specs = await loadAll(projectId);
+        const scope = specIds ? new Set(specIds) : null;
+        const migratedIds = [];
+        const next = await Promise.all(specs.map(async (spec) => {
+            if (scope && !scope.has(spec.id)) {
+                return spec;
+            }
+            if (typeof spec.specPath !== 'string' || !isAbsolute(spec.specPath)) {
+                return spec;
+            }
+            try {
+                await resolvePortableSpecPath(spec.id, spec.specPath, canonicalRoot);
+            }
+            catch (error) {
+                reportClassifiedDegradation('SPEC_PATH_MIGRATION_SKIPPED', error);
+                return spec;
+            }
+            const portableSpecPath = toPortableSpecPath(spec.id, spec.specPath);
+            let portableTechnicalPath = spec.technicalPath;
+            if (typeof spec.technicalPath === 'string' && isAbsolute(spec.technicalPath)) {
+                try {
+                    portableTechnicalPath = toPortableSpecPath(spec.id, spec.technicalPath);
+                }
+                catch (error) {
+                    reportClassifiedDegradation('TECHNICAL_PATH_MIGRATION_SKIPPED', error);
+                    portableTechnicalPath = spec.technicalPath;
+                }
+            }
+            migratedIds.push(spec.id);
+            return { ...spec, specPath: portableSpecPath, technicalPath: portableTechnicalPath };
+        }));
+        if (migratedIds.length > 0) {
+            await saveAll(projectId, next);
+            recordSpecPathMigrationAudit(projectId, migratedIds);
+        }
+        return { migrated: migratedIds.length, specIds: migratedIds };
+    });
+}
 /** Reload a spec from disk after the caller acquires its cross-process lock. */
-export async function getSpecFresh(projectId, specId) {
+export async function getSpecFresh(projectId, specId, canonicalRoot) {
     specsCache.delete(projectId);
-    return getSpec(projectId, specId);
+    return getSpec(projectId, specId, canonicalRoot);
 }
 /** SPEC-601: Lookup a spec by its globally unique UUID. */
 export async function getSpecByUuid(projectId, uuid) {
     const specs = await loadAll(projectId);
     return (specs.find((spec) => spec.uuid === uuid || spec.uuidAliases?.includes(uuid) === true) ?? null);
 }
+/**
+ * Normalize an incoming absolute `specPath`/`technicalPath` — rooted in whatever
+ * checkout the caller invoked from — to its portable project-relative identity
+ * before it ever reaches disk. A value that is not the standard
+ * `planu/specs/<specId[-slug]>/<file>` shape is left untouched (best-effort):
+ * the shared resolver still fails closed for it at read time.
+ */
+function portableizeSpecPaths(spec) {
+    let specPath = spec.specPath;
+    let technicalPath = spec.technicalPath;
+    if (typeof specPath === 'string' && isAbsolute(specPath)) {
+        try {
+            specPath = toPortableSpecPath(spec.id, specPath);
+        }
+        catch (error) {
+            if (!(error instanceof PortablePathError)) {
+                throw error;
+            }
+        }
+    }
+    if (typeof technicalPath === 'string' && isAbsolute(technicalPath)) {
+        try {
+            technicalPath = toPortableSpecPath(spec.id, technicalPath);
+        }
+        catch (error) {
+            if (!(error instanceof PortablePathError)) {
+                throw error;
+            }
+        }
+    }
+    return specPath === spec.specPath && technicalPath === spec.technicalPath
+        ? spec
+        : { ...spec, specPath, technicalPath };
+}
 /**
  * Create a new spec. Throws if a spec with the same ID already exists.
  */
@@ -238,9 +357,11 @@ export async function createSpec(projectId, spec) {
             throw new Error(`Spec "${spec.id}" already exists in project "${projectId}"`);
         }
         const { criteria } = await loadSpecContent(spec);
+        const portableSpec = portableizeSpecPaths(spec);
         const specWithScore = {
-            ...spec,
-            healthScore: computeHealthScore(spec, criteria.length > 0 ? criteria : undefined).score,
+            ...portableSpec,
+            healthScore: computeHealthScore(portableSpec, criteria.length > 0 ? criteria : undefined)
+                .score,
         };
         const nextSpecs = [...specs, specWithScore];
         await saveAll(projectId, nextSpecs);

package/dist/tools/challenge-spec-helpers.d.ts

@@ -11,5 +11,5 @@ export interface ConcurrencyAnalysisResult extends ConcurrencyAnalysis {
 export declare function generateConcurrencyAnalysis(_spec: Spec, content: string, _knowledge: ProjectKnowledge): ConcurrencyAnalysisResult;
 export declare function buildScalabilityAssessment(spec: Spec, knowledge: ProjectKnowledge, scenarios: FailureScenario[], hasRolloutEvidence?: boolean): string;
 export declare function calculateOverallRisk(scenarios: FailureScenario[], concurrency: ConcurrencyAnalysis): RiskLevel;
-export declare function readSpecContent(spec: Spec): Promise<string>;
+export declare function readSpecContent(spec: Spec, projectPath?: string): Promise<string>;
 //# sourceMappingURL=challenge-spec-helpers.d.ts.map

package/dist/tools/challenge-spec-helpers.js

@@ -1,5 +1,7 @@
 // tools/challenge-spec-helpers.ts — Concurrency, risk, and spec-reader helpers for challenge-spec
 import { readFile } from 'node:fs/promises';
+import { isAbsolute } from 'node:path';
+import { resolveVerifiedSpecPath } from '../storage/project-identity.js';
 import { readSpecTechnicalSection } from '../engine/spec-format/read-technical-section.js';
 import { hasAffirmedMatch, stripMetaAnalysisText, stripNonContractText, } from '../engine/text-signal-boundaries.js';
 // Bare keyword matches (counter, status, draft, ...) are common in unrelated
@@ -131,11 +133,14 @@ export function calculateOverallRisk(scenarios, concurrency) {
     return 'low';
 }
 // --- Spec content reader ---
-export async function readSpecContent(spec) {
+export async function readSpecContent(spec, projectPath) {
     let content = `${spec.title} ${spec.type} ${spec.scope} ${spec.target} ${spec.tags.join(' ')}`;
     try {
         if (spec.specPath) {
-            content += ' ' + (await readFile(spec.specPath, 'utf-8'));
+            const resolvedPath = !isAbsolute(spec.specPath) && projectPath
+                ? await resolveVerifiedSpecPath(spec.id, spec.specPath, projectPath)
+                : spec.specPath;
+            content += ' ' + (await readFile(resolvedPath, 'utf-8'));
         }
     }
     catch {

package/dist/tools/challenge-spec.js

@@ -2,11 +2,13 @@
 // Analyzes a spec from adversarial perspectives: failure scenarios,
 // concurrency issues, scale limits, security holes, and data consistency.
 import { readFile } from 'node:fs/promises';
+import { isAbsolute } from 'node:path';
 import { createHash } from 'node:crypto';
 import { specStore, knowledgeStore } from '../storage/index.js';
 // SPEC-1011 Bug F: fallback resolver using disk fingerprints
 import { resolveProjectFromPath } from '../storage/project-resolver.js';
 import { updateSpec } from '../storage/spec-store.js';
+import { resolveVerifiedSpecPath } from '../storage/project-identity.js';
 import { resolveProjectId, missingProjectIdError } from './resolve-project-id.js';
 import { elicitOrFallback, buildEnumSchema } from '../engine/elicitation/elicit-helper.js';
 import { t, ti } from '../i18n/index.js';
@@ -83,13 +85,16 @@ function extractOutOfScopeSection(content) {
     }
     return found ? captured.join('\n') : null;
 }
-async function resolveDocumentOutOfScope(spec) {
+async function resolveDocumentOutOfScope(spec, projectPath) {
     if (!spec.specPath) {
         return [];
     }
     let fileContent;
     try {
-        fileContent = await readFile(spec.specPath, 'utf-8');
+        const resolvedPath = !isAbsolute(spec.specPath) && projectPath
+            ? await resolveVerifiedSpecPath(spec.id, spec.specPath, projectPath)
+            : spec.specPath;
+        fileContent = await readFile(resolvedPath, 'utf-8');
     }
     catch {
         return [];
@@ -97,8 +102,8 @@ async function resolveDocumentOutOfScope(spec) {
     const sectionContent = extractOutOfScopeSection(fileContent);
     return sectionContent === null ? [] : extractListItems(sectionContent);
 }
-async function resolveOutOfScopeItems(spec) {
-    const documentItems = await resolveDocumentOutOfScope(spec);
+async function resolveOutOfScopeItems(spec, projectPath) {
+    const documentItems = await resolveDocumentOutOfScope(spec, projectPath);
     return documentItems.length > 0 ? documentItems : (spec.outOfScope ?? []);
 }
 /**
@@ -192,7 +197,7 @@ export async function handleChallengeSpec(args, server) {
     // 2b. Load Constitution for compliance context
     const constitution = await knowledgeStore.getConstitution(projectId);
     // 3. Read spec content
-    const specContent = await readSpecContent(spec);
+    const specContent = await readSpecContent(spec, knowledge.projectPath);
     const capabilities = detectChallengeCapabilities(spec, specContent);
     // 4. Determine focus areas
     const focusAreas = focus && focus.length > 0 ? focus : ALL_FOCUS_AREAS;
@@ -224,7 +229,7 @@ export async function handleChallengeSpec(args, server) {
     }
     failureScenarios.push(...collectCapabilityScenarios({ spec, specContent, knowledge, focusAreas, capabilities }));
     // SPEC-612: Check for contradictions between outOfScope and acceptance criteria
-    const resolvedOutOfScope = await resolveOutOfScopeItems(spec);
+    const resolvedOutOfScope = await resolveOutOfScopeItems(spec, knowledge.projectPath);
     if (resolvedOutOfScope.length > 0) {
         const criteriaRange = findMarkdownSectionRange(specContent, 'Acceptance Criteria');
         const criteriaTexts = criteriaRange === null

package/dist/tools/check-readiness.js

@@ -1,6 +1,8 @@
 // tools/check-readiness.ts — Completeness checkpoint tool (SPEC-039, SPEC-314, SPEC-716)
 import { readFile } from 'node:fs/promises';
+import { isAbsolute } from 'node:path';
 import { specStore } from '../storage/index.js';
+import { resolveVerifiedSpecPath } from '../storage/project-identity.js';
 import { buildCheckReadinessSummary } from '../engine/human-summary.js';
 import { validateSpecFormat } from '../core/spec-validator.js';
 import { parseFrontmatter } from '../engine/frontmatter-parser.js';
@@ -18,9 +20,12 @@ function asSpecScope(value) {
  * readiness gate honors on-disk edits instead of the specs.json snapshot that
  * `specStore` caches in memory.
  */
-async function readFreshDifficultyAndScope(specPath) {
+async function readFreshDifficultyAndScope(specId, specPath, projectPath) {
     try {
-        const raw = await readFile(specPath, 'utf-8');
+        const resolvedPath = projectPath
+            ? await resolveVerifiedSpecPath(specId, specPath, projectPath)
+            : specPath;
+        const raw = await readFile(resolvedPath, 'utf-8');
         const { metadata } = parseFrontmatter(raw);
         return {
             difficulty: asDifficulty(metadata.difficulty),
@@ -31,6 +36,17 @@ async function readFreshDifficultyAndScope(specPath) {
         return {};
     }
 }
+async function resolveEffectiveSpecPath(specId, specPath, projectPath) {
+    if (!projectPath || isAbsolute(specPath)) {
+        return specPath;
+    }
+    try {
+        return await resolveVerifiedSpecPath(specId, specPath, projectPath);
+    }
+    catch {
+        return specPath;
+    }
+}
 // ── Formatting helpers ───────────────────────────────────────────────────────
 const MAX_VISIBLE_BLOCKERS = 8;
 const MAX_VISIBLE_WARNINGS = 8;
@@ -148,7 +164,7 @@ export async function handleCheckReadiness(args) {
         };
     }
     const { specId, mode = 'strict' } = args;
-    const spec = await specStore.getSpecFresh(projectId, specId);
+    const spec = await specStore.getSpecFresh(projectId, specId, args.projectPath);
     if (!spec) {
         return {
             content: [
@@ -160,9 +176,16 @@ export async function handleCheckReadiness(args) {
             isError: true,
         };
     }
-    const fresh = spec.specPath ? await readFreshDifficultyAndScope(spec.specPath) : {};
+    const fresh = spec.specPath
+        ? await readFreshDifficultyAndScope(spec.id, spec.specPath, args.projectPath)
+        : {};
+    const resolvedSpecPath = spec.specPath
+        ? await resolveEffectiveSpecPath(spec.id, spec.specPath, args.projectPath)
+        : spec.specPath;
     const effectiveSpec = {
         ...spec,
+        specPath: resolvedSpecPath,
+        technicalPath: resolvedSpecPath,
         difficulty: fresh.difficulty ?? spec.difficulty,
         scope: fresh.scope ?? spec.scope,
     };

package/dist/tools/generate-execution-plan.js

@@ -1,5 +1,5 @@
 import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
+import { join, isAbsolute } from 'node:path';
 import { specStore, knowledgeStore, patternStore } from '../storage/index.js';
 import { ti } from '../i18n/index.js';
 import { generatePlanMarkdown, EXECUTION_PLAN_MARKER } from '../engine/dor-dod.js';
@@ -9,10 +9,14 @@ import { generateMobileDistributionPhase, isMobileDistributionSpec, } from '../e
 import { isDesktopReleaseSpec, generateDesktopDistributionPhase, } from '../engine/execution-plan/desktop-distribution.js';
 import { determineCriticalPath, findParallelizable, validateExecutionPlanGraph, } from '../engine/execution-plan/plan-utils.js';
 import { projectDataDir } from '../storage/base-store.js';
+import { resolveVerifiedSpecPath } from '../storage/project-identity.js';
 import { atomicWriteFile } from '../engine/safety/atomic-write-file.js';
-async function readSpecBody(spec) {
+async function readSpecBody(spec, projectPath) {
     try {
-        return await readFile(spec.specPath, 'utf-8');
+        const resolvedPath = !isAbsolute(spec.specPath) && projectPath
+            ? await resolveVerifiedSpecPath(spec.id, spec.specPath, projectPath)
+            : spec.specPath;
+        return await readFile(resolvedPath, 'utf-8');
     }
     catch {
         return null;
@@ -29,8 +33,8 @@ function invalidTaskPlanEntry(taskPlan) {
     const trimmedId = task.id.trim();
     return trimmedId.length > 0 ? trimmedId : '(missing id)';
 }
-async function loadGroundedContract(spec, projectId, specId) {
-    const body = await readSpecBody(spec);
+async function loadGroundedContract(spec, projectId, specId, projectPath) {
+    const body = await readSpecBody(spec, projectPath);
     const ownership = body
         ? extractCanonicalFileOwnership(body)
         : { present: false, toCreate: [], toModify: [], toTest: [], toTestDeclared: [], blockers: [] };
@@ -141,7 +145,7 @@ export async function handleGenerateExecutionPlan(args) {
             ],
         };
     }
-    const contract = await loadGroundedContract(spec, projectId, specId);
+    const contract = await loadGroundedContract(spec, projectId, specId, knowledge.projectPath);
     if (!contract.ok) {
         return {
             content: [

package/dist/tools/update-status/evidence-gate.js

@@ -51,7 +51,7 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
 import { readFile } from 'node:fs/promises';
-import { isAbsolute, join } from 'node:path';
+import { resolvePortableSpecPath } from '../../storage/project-identity.js';
 import { extractCriteria } from '../../engine/validator/extractors.js';
 import { readEvidenceArtifacts } from '../../engine/evidence-gates/artifact-reader.js';
 import { checkLifecycleEvidenceGate } from '../../engine/evidence-gates/lifecycle-gate.js';
@@ -290,9 +290,7 @@ async function currentBindingsAreFresh(identity, currentBindings) {
         return false;
     }
     try {
-        const specPath = isAbsolute(identity.specPath)
-            ? identity.specPath
-            : join(identity.projectPath, identity.specPath);
+        const specPath = await resolvePortableSpecPath(identity.specId, identity.specPath, identity.projectPath);
         const observed = await computeDurableValidationBindings({
             canonicalProjectId: identity.projectId,
             specId: identity.specId,
@@ -311,8 +309,10 @@ async function currentBindingsAreFresh(identity, currentBindings) {
     }
 }
 async function extractLifecycleGateCriteriaAndBody(spec, projectPath) {
-    const specPath = isAbsolute(spec.specPath) || !projectPath ? spec.specPath : join(projectPath, spec.specPath);
     try {
+        const specPath = projectPath
+            ? await resolvePortableSpecPath(spec.id, spec.specPath, projectPath)
+            : spec.specPath;
         const raw = await readFile(specPath, 'utf-8');
         const criteria = extractAcceptanceCriteriaTexts(raw);
         if (criteria.length > 0) {

package/dist/tools/update-status/file-sync.js

@@ -3,12 +3,12 @@ import { metricsStore } from '../../storage/index.js';
 import { addLesson, getLessons } from '../../storage/lessons-store.js';
 import { dispatchFeedbackEvent } from '../learn.js';
 import { autoReconcileOnDone } from '../update-status-reconcile.js';
-import { lstat, readFile, realpath } from 'node:fs/promises';
+import { readFile } from 'node:fs/promises';
 import { parseFrontmatter } from '../../engine/frontmatter-parser.js';
 import { computeFrontmatterSha } from '../../engine/frontmatter-sha/index.js';
 import { appendTransitionEvent } from '../../storage/transition-log.js';
 import { atomicWriteFile } from '../../engine/safety/atomic-write-file.js';
-import { isAbsolute, normalize, relative, resolve, sep } from 'node:path';
+import { resolvePortableSpecPath, PortablePathError } from '../../storage/project-identity.js';
 import { redactFailureMessage, reportClassifiedDegradation, } from '../../errors/classified-degradation.js';
 export async function recordDoneMetrics(projectId, specId, spec, actuals, projectPath) {
     if (actuals.devHours + actuals.reviewHours === 0) {
@@ -97,46 +97,18 @@ async function resolveSpecPathForTransition(spec, projectPath) {
     if (!projectPath) {
         return spec.specPath;
     }
-    const normalizedPath = normalize(spec.specPath);
-    const segments = normalizedPath.split(sep).filter(Boolean);
-    const planuIndex = segments.lastIndexOf('planu');
-    const specDirectory = segments[planuIndex + 2];
-    const isPortableContract = planuIndex >= 0 &&
-        segments[planuIndex + 1] === 'specs' &&
-        segments[planuIndex + 3] === 'spec.md' &&
-        planuIndex + 4 === segments.length &&
-        specDirectory !== undefined &&
-        (specDirectory === spec.id || specDirectory.startsWith(`${spec.id}-`));
-    if (!isPortableContract) {
-        throw new Error('SPEC_PATH_RELOCALIZATION_FAILED: specPath is not a portable spec contract');
-    }
-    const selectedRoot = resolve(projectPath);
-    const candidate = resolve(selectedRoot, 'planu', 'specs', specDirectory, 'spec.md');
-    const relativeCandidate = relative(selectedRoot, candidate);
-    if (relativeCandidate.startsWith(`..${sep}`) ||
-        relativeCandidate === '..' ||
-        isAbsolute(relativeCandidate)) {
-        throw new Error('SPEC_PATH_RELOCALIZATION_FAILED: specPath escapes the selected root');
+    try {
+        return await resolvePortableSpecPath(spec.id, spec.specPath, projectPath);
     }
-    const rootRealpath = await realpath(selectedRoot);
-    const [candidateRealpath, candidateStat] = await Promise.all([
-        realpath(candidate),
-        lstat(candidate),
-    ]).catch((err) => {
-        if (err instanceof Error && err.code === 'ENOENT') {
-            throw specArtifactAbsentError();
+    catch (error) {
+        if (error instanceof PortablePathError) {
+            if (error.code === 'NOT_FOUND') {
+                throw specArtifactAbsentError();
+            }
+            throw new Error(`SPEC_PATH_RELOCALIZATION_FAILED: ${error.message}`, { cause: error });
         }
-        throw err;
-    });
-    const realRelative = relative(rootRealpath, candidateRealpath);
-    if (candidateStat.isSymbolicLink() ||
-        !candidateStat.isFile() ||
-        realRelative.startsWith(`..${sep}`) ||
-        realRelative === '..' ||
-        isAbsolute(realRelative)) {
-        throw new Error('SPEC_PATH_RELOCALIZATION_FAILED: specPath is not a contained regular file');
+        throw error;
     }
-    return candidateRealpath;
 }
 function bodyWithoutFrontmatter(content) {
     return parseFrontmatter(content).body;

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

@@ -932,7 +932,7 @@ export async function handleUpdateStatus(params, server) {
                         return ambiguityError;
                     }
                     // SPEC-769: Readiness gate — block 'approved' if spec has 0 criteria or score < 70
-                    const readinessGate = await checkReadinessGate(spec, approvalGateStatus, params.forceApprove);
+                    const readinessGate = await checkReadinessGate(spec, approvalGateStatus, params.forceApprove, transitionProjectPath);
                     if (readinessGate.blockResult) {
                         return readinessGate.blockResult;
                     }

package/dist/tools/update-status/transition-guard.d.ts

@@ -73,7 +73,7 @@ export declare function checkSpecArtifactCommittedGate(spec: Spec, newStatus: Sp
  * - non-English prose → hard block
  * - score >= 70 → proceed, no warnings
  */
-export declare function checkReadinessGate(spec: Spec, newStatus: SpecStatus, forceApprove: boolean | undefined): Promise<ReadinessGateOutput>;
+export declare function checkReadinessGate(spec: Spec, newStatus: SpecStatus, forceApprove: boolean | undefined, projectPath?: string): Promise<ReadinessGateOutput>;
 /**
  * SPEC-964: Challenge gate — block 'review' if challenge_spec was never run
  * or does not contain enough explicit resolution evidence.

package/dist/tools/update-status/transition-guard.js

@@ -1,6 +1,7 @@
 // tools/update-status/transition-guard.ts — Valid state transitions and DoR gate
 import { readFile } from 'node:fs/promises';
 import { isAbsolute, join } from 'node:path';
+import { toPortableSpecPath, resolveVerifiedSpecPath, PortablePathError, } from '../../storage/project-identity.js';
 import { ti } from '../../i18n/index.js';
 import { validateDoR } from '../../engine/dor-dod.js';
 import { dispatchFeedbackEvent } from '../learn.js';
@@ -237,9 +238,30 @@ export async function checkSpecArtifactCommittedGate(spec, newStatus, projectPat
     if (newStatus !== 'implementing' || !projectPath || !spec.specPath) {
         return null;
     }
-    const absoluteSpecPath = isAbsolute(spec.specPath)
-        ? spec.specPath
-        : join(projectPath, spec.specPath);
+    let absoluteSpecPath;
+    try {
+        absoluteSpecPath = join(projectPath, toPortableSpecPath(spec.id, spec.specPath));
+    }
+    catch (error) {
+        if (!(error instanceof PortablePathError)) {
+            throw error;
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: formatKeyValue({
+                        error: 'SPEC_PATH_UNRESOLVABLE',
+                        message: `spec.md for ${spec.id} could not be resolved under the canonical project root (${error.code}).`,
+                        specId: spec.id,
+                        fixHint: 'Run reconcile_spec to re-link this spec to its file, then retry update_status.',
+                    }),
+                },
+            ],
+            isError: true,
+            structuredContent: { error: 'SPEC_PATH_UNRESOLVABLE', code: error.code, specId: spec.id },
+        };
+    }
     try {
         const { git } = await import('../git/git-helpers.js');
         const { stdout } = await git(projectPath, ['status', '--porcelain', '--', absoluteSpecPath]);
@@ -286,13 +308,18 @@ export async function checkSpecArtifactCommittedGate(spec, newStatus, projectPat
  * - non-English prose → hard block
  * - score >= 70 → proceed, no warnings
  */
-export async function checkReadinessGate(spec, newStatus, forceApprove) {
+export async function checkReadinessGate(spec, newStatus, forceApprove, projectPath) {
     if ((newStatus !== 'review' && newStatus !== 'approved') || !spec.specPath) {
         return { blockResult: null, qualityWarnings: [] };
     }
     let body;
+    let resolvedPath;
     try {
-        body = await readFile(spec.specPath, 'utf-8');
+        resolvedPath =
+            !isAbsolute(spec.specPath) && projectPath
+                ? await resolveVerifiedSpecPath(spec.id, spec.specPath, projectPath)
+                : spec.specPath;
+        body = await readFile(resolvedPath, 'utf-8');
     }
     catch (error) {
         /* reliability-optional: READINESS_SPEC_UNREADABLE — transition fails closed below */
@@ -301,10 +328,12 @@ export async function checkReadinessGate(spec, newStatus, forceApprove) {
         // situation — surface an actionable message instead of the raw fs error
         // ("ENOENT: no such file or directory, open '<path>'") that update_status
         // was previously appending "Transition blocked..." to verbatim.
-        const isMissingFile = typeof error === 'object' &&
+        const isMissingFile = (typeof error === 'object' &&
             error !== null &&
             'code' in error &&
-            error.code === 'ENOENT';
+            error.code === 'ENOENT') ||
+            (error instanceof PortablePathError &&
+                (error.code === 'NOT_FOUND' || error.code === 'ROOT_NOT_FOUND'));
         return readinessUnavailable('READINESS_SPEC_UNREADABLE', isMissingFile
             ? `spec.md is missing at ${spec.specPath}. Recreate the spec via create_spec or restore spec.md from git/backup before retrying this transition.`
             : error instanceof Error
@@ -397,9 +426,12 @@ export async function checkReadinessGate(spec, newStatus, forceApprove) {
             qualityWarnings: structuralInterpolationWarnings,
         };
     }
+    const specWithResolvedPath = resolvedPath === spec.specPath
+        ? spec
+        : { ...spec, specPath: resolvedPath, technicalPath: resolvedPath };
     let readiness;
     try {
-        readiness = await checkSpecReadiness(spec, 'strict');
+        readiness = await checkSpecReadiness(specWithResolvedPath, 'strict');
     }
     catch (error) {
         /* reliability-optional: READINESS_EVALUATION_FAILED — transition fails closed below */

package/dist/types/cross-repo-search.d.ts

@@ -13,6 +13,8 @@ export interface RegisteredProject {
     specCount: number;
     /** ISO timestamp of the last spec scan, if any */
     lastScanAt?: string;
+    /** Logical project identity from planu/project.json, when the checkout has one */
+    logicalProjectId?: string;
 }
 /**
  * Global registry persisted at data/global/registered-projects.json.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "5.3.67",
+  "version": "5.3.68",
   "description": "Planu — MCP Server for Spec Driven Development. Cross-platform (Linux/macOS/Windows, x64/arm64).",
   "type": "module",
   "main": "dist/index.js",
@@ -56,7 +56,7 @@
     "check": "pnpm typecheck && pnpm lint:gate && pnpm format:check && pnpm check:destructive-ops && pnpm check:commercial-surfaces && pnpm check:tool-registration && pnpm check:public-privacy && pnpm check:website-proof && pnpm check:donation-assets && pnpm check:website-public-assets",
     "check:destructive-ops": "bash scripts/check-no-automatic-destructive-ops.sh",
     "check:strict": "pnpm check && pnpm generate:host-tool-registry -- --check && pnpm check:environment-schema && pnpm audit:hardcodes && pnpm audit:deadcode && pnpm audit:circular && pnpm audit:types && pnpm audit:security && pnpm audit:i18n",
-    "check:preflight": "pnpm typecheck && pnpm lint:gate && pnpm format:check && node scripts/check-public-privacy.mjs && node scripts/check-preflight.mjs",
+    "check:preflight": "pnpm typecheck && pnpm lint:gate && pnpm format:check && node scripts/check-public-privacy.mjs && node scripts/check-preflight.mjs && bash scripts/release-preflight.sh --run-and-write && bash scripts/release-preflight.sh --verify",
     "check:reliability": "node scripts/check-reliability-policies.mjs",
     "check:environment-schema": "node scripts/check-environment-schema.mjs",
     "test:contracts": "vitest run tests/contracts tests/integration/package-consumer-hono.test.ts",

package/planu-plugin.json

@@ -2,7 +2,7 @@
   "name": "dev.planu.cli",
   "displayName": "Planu — Spec Driven Development",
   "description": "Manage software specs, estimations, and autonomous SDD workflows. Language-agnostic MCP server for Claude Code.",
-  "version": "5.3.67",
+  "version": "5.3.68",
   "icon": "assets/plugin/icon.svg",
   "command": ["npx", "@planu/cli@latest"],
   "packageName": "@planu/cli",