@planu/cli 5.3.66 → 5.3.68

package/CHANGELOG.md

@@ -1,3 +1,39 @@
+## [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
+- fix(SPEC-1214): make readiness executable-evidence fallback reachable outside planu/specs
+- fix(SPEC-1214): align readiness and validation on one executable-evidence contract
+- fix(SPEC-1306): forward caller cwd as explicit projectPath in CLI status
+
+### Chores
+- chore(SPEC-1315): transition to implementing
+- chore: mark SPEC-1306/SPEC-1214 done and file SPEC-1664 dogfood bug
+
+
 ## [5.3.66] - 2026-08-28
 
 ### Bug Fixes

package/dist/.planu-build.json

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

package/dist/cli/commands/status.js

@@ -58,7 +58,7 @@ export function buildSingleStatusInput(values, specId, projectId, status) {
     return {
         specId,
         projectId,
-        projectPath: values['project-path'] ? resolve(values['project-path']) : undefined,
+        projectPath: values['project-path'] ? resolve(values['project-path']) : process.cwd(),
         status: status,
         reviewNotes: values.notes,
         modelId: values['model-id'],

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/engine/readiness-checker.js

@@ -1,10 +1,13 @@
 // engine/readiness-checker.ts — Spec readiness evaluation for implementation gate (SPEC-039)
+import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
 import { extractSectionBody, readSpecTechnicalSection, } from './spec-format/read-technical-section.js';
 import { stripFrontmatter } from './frontmatter-parser.js';
 import { loadReadinessConfig } from './readiness-config-loader.js';
 import { runEarsGate } from './ears-gate.js';
 import { findScenariosWithoutTests, parseFrontmatterScenarios, } from './validator/spec-compliance-runner.js';
+import { normalizeExecutableEvidence } from './validator/executable-evidence.js';
 import { evaluateImplementationContract } from './implementation-contract/index.js';
 import { extractNormalizedAcceptanceCriteria } from './spec-format/acceptance-criteria.js';
 // ── SPEC-784: Technical section quality constants ─────────────────────────────
@@ -33,6 +36,13 @@ function scoreHuCompleteness(spec) {
     }
     return { points, blockers, warnings };
 }
+function projectPathFromSpecPath(specPath) {
+    const marker = /[/\\]planu[/\\]specs[/\\]/;
+    if (!specPath || !marker.test(specPath)) {
+        return undefined;
+    }
+    return specPath.split(marker)[0];
+}
 async function readHuRaw(spec) {
     if (!spec.specPath) {
         return '';
@@ -421,6 +431,16 @@ export async function checkSpecReadiness(spec, mode, projectHash) {
             allBlockers.push(`scenarios_missing_tests: scenario "${title}" has no tests array — add tests entries (SPEC-732)`);
         }
     }
+    // SPEC-1214: BDD-criteria executable-evidence gate — when a spec has no frontmatter
+    // scenarios, its criteria must carry a TEST: marker mapping to an executable test file,
+    // or validation will later score 0 with "No executable scenarios declared".
+    if (bddScenarioCount === 0 && spec.scope !== 'trivial') {
+        const readinessProjectPath = projectPathFromSpecPath(spec.specPath);
+        const executableEvidence = normalizeExecutableEvidence(huRaw, parseFrontmatterScenarios(huRaw), (path) => (readinessProjectPath ? existsSync(join(readinessProjectPath, path)) : true));
+        for (const title of executableEvidence.unmappedCriteria) {
+            allBlockers.push(`criteria_missing_executable_test: criterion "${title}" has no TEST: marker mapping to an executable test file (SPEC-1214)`);
+        }
+    }
     // SPEC-784: Technical section quality gates — blocker-severity issues
     if (detectTechnicalPlaceholder(huContent)) {
         allBlockers.push('TECHNICAL_PLACEHOLDER_DETECTED: ## Technical section contains a placeholder pointer ' +

package/dist/engine/validator/executable-evidence.d.ts

@@ -0,0 +1,31 @@
+export interface EvidenceTestLink {
+    path: string;
+}
+export interface EvidenceScenario {
+    title: string;
+    tests: EvidenceTestLink[];
+}
+export type ExecutableEvidenceSource = 'frontmatter' | 'criteria' | 'none';
+export interface ExecutableEvidence {
+    source: ExecutableEvidenceSource;
+    scenarios: EvidenceScenario[];
+    unmappedCriteria: string[];
+    ignoredCriteriaTitles: string[];
+}
+/**
+ * Single evidence normalizer shared by spec-compliance-runner.ts and
+ * readiness-checker.ts (SPEC-1214). Frontmatter `scenarios` stay canonical when
+ * present; otherwise BDD criteria `TEST:` markers become the executable evidence,
+ * so a spec approved by readiness on `TEST:` markers cannot later validate as
+ * "no executable scenarios declared". `isValidTestPath` lets each caller reject a
+ * `TEST:` marker pointing at a file that does not exist on disk, instead of
+ * silently treating it as executable evidence; it defaults to accepting every
+ * path when a caller has no filesystem to check against.
+ */
+export declare function normalizeExecutableEvidence(raw: string, frontmatterScenarios: {
+    title: string;
+    tests?: {
+        path: string;
+    }[];
+}[], isValidTestPath?: (path: string) => boolean): ExecutableEvidence;
+//# sourceMappingURL=executable-evidence.d.ts.map

package/dist/engine/validator/executable-evidence.js

@@ -0,0 +1,104 @@
+import { extractSection } from '../spec-format/markdown-sections.js';
+import { stripFrontmatter } from '../frontmatter-parser.js';
+const CRITERION_HEADING = /^#{2,6}\s+((?:AC|AB)\s*-?\s*\d+)\b/i;
+const GIVEN_BULLET = /^-\s*GIVEN\b/i;
+const BDD_STEP = /^(?:[-*]\s+)?(GIVEN|WHEN|THEN|AND)\b/i;
+const TEST_MARKER_LINE = /^\s*TEST:\s*(.+)$/im;
+const TEST_FILE_TOKEN = /`?([\w./-]+\.(?:test|spec)\.[cm]?[jt]sx?)`?/g;
+function splitByLineStarts(lines, starts) {
+    return starts.map((start, position) => {
+        const end = starts[position + 1] ?? lines.length;
+        return lines.slice(start, end).join('\n');
+    });
+}
+function splitCriterionBlocks(section) {
+    const lines = section.split('\n');
+    const headingStarts = lines
+        .map((line, index) => (CRITERION_HEADING.test(line.trim()) ? index : -1))
+        .filter((index) => index !== -1);
+    if (headingStarts.length > 0) {
+        return splitByLineStarts(lines, headingStarts);
+    }
+    const bulletStarts = lines
+        .map((line, index) => (GIVEN_BULLET.test(line.trim()) ? index : -1))
+        .filter((index) => index !== -1);
+    if (bulletStarts.length > 0) {
+        return splitByLineStarts(lines, bulletStarts);
+    }
+    return section.split(/\n\s*\n/).filter((block) => /\bGIVEN\b/i.test(block));
+}
+function blockTitle(block) {
+    const stepLines = block
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => BDD_STEP.test(line))
+        .map((line) => line.replace(/^[-*]\s+/, ''));
+    if (stepLines.length > 0) {
+        return stepLines.join(' ');
+    }
+    const heading = /^#{2,6}\s+(.+)$/.exec(block.split('\n')[0]?.trim() ?? '');
+    return (heading?.[1] ?? block.trim()).slice(0, 200);
+}
+function blockTestLinks(block, isValidTestPath) {
+    const marker = TEST_MARKER_LINE.exec(block);
+    if (!marker?.[1]) {
+        return [];
+    }
+    return [...marker[1].matchAll(TEST_FILE_TOKEN)]
+        .map((match) => match[1])
+        .filter((path) => Boolean(path))
+        .filter(isValidTestPath)
+        .map((path) => ({ path }));
+}
+function extractCriteriaScenarios(raw, isValidTestPath) {
+    const body = stripFrontmatter(raw);
+    const section = extractSection(body, 'acceptance criteria', 'criterios de aceptaci') ?? body;
+    return splitCriterionBlocks(section).map((block) => ({
+        title: blockTitle(block),
+        tests: blockTestLinks(block, isValidTestPath),
+    }));
+}
+/**
+ * Single evidence normalizer shared by spec-compliance-runner.ts and
+ * readiness-checker.ts (SPEC-1214). Frontmatter `scenarios` stay canonical when
+ * present; otherwise BDD criteria `TEST:` markers become the executable evidence,
+ * so a spec approved by readiness on `TEST:` markers cannot later validate as
+ * "no executable scenarios declared". `isValidTestPath` lets each caller reject a
+ * `TEST:` marker pointing at a file that does not exist on disk, instead of
+ * silently treating it as executable evidence; it defaults to accepting every
+ * path when a caller has no filesystem to check against.
+ */
+export function normalizeExecutableEvidence(raw, frontmatterScenarios, isValidTestPath = () => true) {
+    const criteriaScenarios = extractCriteriaScenarios(raw, isValidTestPath);
+    if (frontmatterScenarios.length > 0) {
+        return {
+            source: 'frontmatter',
+            scenarios: frontmatterScenarios.map((scenario) => ({
+                title: scenario.title,
+                tests: (scenario.tests ?? []).map((test) => ({ path: test.path })),
+            })),
+            unmappedCriteria: [],
+            ignoredCriteriaTitles: criteriaScenarios
+                .filter((scenario) => scenario.tests.length > 0)
+                .map((scenario) => scenario.title),
+        };
+    }
+    const mapped = criteriaScenarios.filter((scenario) => scenario.tests.length > 0);
+    if (mapped.length > 0) {
+        return {
+            source: 'criteria',
+            scenarios: criteriaScenarios,
+            unmappedCriteria: criteriaScenarios
+                .filter((scenario) => scenario.tests.length === 0)
+                .map((scenario) => scenario.title),
+            ignoredCriteriaTitles: [],
+        };
+    }
+    return {
+        source: 'none',
+        scenarios: [],
+        unmappedCriteria: criteriaScenarios.map((scenario) => scenario.title),
+        ignoredCriteriaTitles: [],
+    };
+}
+//# sourceMappingURL=executable-evidence.js.map

package/dist/engine/validator/spec-compliance-runner.d.ts

@@ -27,6 +27,8 @@ export interface SpecComplianceResult {
     dimensionScore: number;
     perScenario: PerScenarioResult[];
     command: string;
+    evidenceSource?: 'frontmatter' | 'criteria' | 'none';
+    ignoredCriteriaTitles?: string[];
 }
 /** A sanitized terminal adapter failure that cannot be mistaken for a failed test verdict. */
 export declare class ComplianceCommandTerminalError extends Error {

package/dist/engine/validator/spec-compliance-runner.js

@@ -8,6 +8,7 @@ import { technologyValue } from '../technology-registry.js';
 import { readMatchingValidationEvidence } from '../validation-evidence-ledger.js';
 import { readEvidenceArtifacts, traceabilityRowHasCurrentCommandEvidence, } from '../evidence-gates/artifact-reader.js';
 import { normalizeCriterionText } from '../criterion-identity.js';
+import { normalizeExecutableEvidence } from './executable-evidence.js';
 /** A sanitized terminal adapter failure that cannot be mistaken for a failed test verdict. */
 export class ComplianceCommandTerminalError extends Error {
     code;
@@ -450,16 +451,31 @@ async function loadExactCommandRows(spec, projectPath, canonicalProjectId) {
 // eslint-disable-next-line max-lines-per-function -- coordinates validation, adapters, and isolated per-scenario evidence
 export async function runSpecCompliance(spec, projectPath, signal, canonicalProjectId) {
     const { readFile } = await import('node:fs/promises');
+    const { existsSync } = await import('node:fs');
     let raw;
     try {
         raw = await readFile(spec.specPath, 'utf-8');
     }
     catch {
-        return { dimensionScore: 0, perScenario: [], command: '' };
+        return { dimensionScore: 0, perScenario: [], command: '', evidenceSource: 'none' };
     }
-    const scenarios = parseFrontmatterScenarios(raw);
+    const frontmatterScenarios = parseFrontmatterScenarios(raw);
+    const executableEvidence = normalizeExecutableEvidence(raw, frontmatterScenarios, (path) => existsSync(join(projectPath, path)));
+    const scenarios = executableEvidence.source === 'frontmatter'
+        ? frontmatterScenarios
+        : executableEvidence.scenarios.map((scenario) => ({
+            title: scenario.title,
+            done: false,
+            tests: scenario.tests.map((test) => ({ path: test.path })).filter(isExecutableTestLink),
+        }));
     if (scenarios.length === 0) {
-        return { dimensionScore: 0, perScenario: [], command: '' };
+        return {
+            dimensionScore: 0,
+            perScenario: [],
+            command: '',
+            evidenceSource: executableEvidence.source,
+            ignoredCriteriaTitles: executableEvidence.ignoredCriteriaTitles,
+        };
     }
     const allLinks = scenarios.flatMap((scenario) => scenario.tests ?? []);
     const executableLinks = allLinks.filter(isExecutableTestLink);
@@ -570,6 +586,8 @@ export async function runSpecCompliance(spec, projectPath, signal, canonicalProj
         perScenario,
         command: commands.join(' && ') ||
             `${technologyValue('technology-vitest-a9127f')} --reporter=json --run (no test files linked)`,
+        evidenceSource: executableEvidence.source,
+        ignoredCriteriaTitles: executableEvidence.ignoredCriteriaTitles,
     };
 }
 export function findScenariosWithoutTests(raw) {

package/dist/engine/validator/validation-report-writer.js

@@ -130,12 +130,18 @@ function buildMinimalityGate(report) {
             : undefined,
     };
 }
+function ignoredCriteriaNote(result) {
+    return result.ignoredCriteriaTitles?.length
+        ? ` Ignored BDD criteria TEST: mappings (frontmatter scenarios are canonical): ${result.ignoredCriteriaTitles.join(', ')}.`
+        : '';
+}
 function buildSpecComplianceGate(result) {
+    const ignoredNote = ignoredCriteriaNote(result);
     if (result.perScenario.length === 0) {
         return {
             name: 'spec-compliance',
-            passed: true,
-            reason: 'No executable scenarios declared; spec-compliance runner skipped.',
+            passed: false,
+            reason: `No executable scenarios declared (evidence source: ${result.evidenceSource ?? 'none'}) — add BDD criteria TEST: markers or frontmatter scenarios before done.${ignoredNote}`,
         };
     }
     const passed = result.dimensionScore === 100;
@@ -143,8 +149,8 @@ function buildSpecComplianceGate(result) {
         name: 'spec-compliance',
         passed,
         reason: passed
-            ? undefined
-            : `Expected all executable scenarios to pass, got ${String(result.dimensionScore)}.`,
+            ? ignoredNote.trim() || undefined
+            : `Expected all executable scenarios to pass, got ${String(result.dimensionScore)}.${ignoredNote}`,
     };
 }
 function toValidationReportCompliance(result) {

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);