@planu/cli 5.3.68 → 5.4.0

package/dist/engine/version-resolver.js

@@ -6,6 +6,7 @@ import { readFile, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { fetchLatestVersion } from './package-registry.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { getCachedVersions, saveCachedVersions, isExpired as isCachedVersionExpired, } from '../storage/version-cache-store.js';
 // -- Constants ---------------------------------------------------------------
 const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours

package/dist/engine/workers/handlers/auto-drift.js

@@ -1,8 +1,11 @@
 // engine/workers/handlers/auto-drift.ts — Auto drift detection on file changes (SPEC-225)
 import { relative, extname } from 'node:path';
 import { readdir, stat } from 'node:fs/promises';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { specStore } from '../../../storage/index.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { hashProjectPath } from '../../../storage/base-store.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { DriftCacheStore } from '../../../storage/drift-cache-store.js';
 import { emitAutopilotEvent } from '../../autopilot/event-bus.js';
 // ---------------------------------------------------------------------------

package/dist/engine/workspace-manager.js

@@ -1,8 +1,12 @@
 // engine/workspace-manager.ts — SPEC-363: Multi-tenant Workspace Dashboard
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { getProjects, addProject } from '../storage/global-projects-store.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { specStore } from '../storage/index.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { hashProjectPath, readJson } from '../storage/base-store.js';
 import { glob } from 'glob';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { resolveStorageLayout } from '../storage/storage-layout.js';
 // ---------------------------------------------------------------------------
 // SPEC-789: Project discovery fallback

package/dist/hosts/gemini/config-scaffold.js

@@ -2,11 +2,12 @@
 // Writes .gemini/conventions.md, .gemini/skills/planu-*.md, and .gemini/hooks/
 // equivalents when init_project runs inside a Gemini workspace.
 // NOTE: This function deliberately does NOT create .claude/ files.
-import { writeFile, readFile, mkdir, access } from 'node:fs/promises';
+import { writeFile, readFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { buildRulesForHost } from '../../engine/host-rules-templates/index.js';
 import { assertEnglishOnlyArtifactText } from '../../engine/spec-language/english-only.js';
 import { PLANU_VERSION } from '../../config/version.js';
+import { fileExists } from '../../core/shared/fs.js';
 // ---------------------------------------------------------------------------
 // File content generators
 // ---------------------------------------------------------------------------
@@ -188,13 +189,4 @@ async function injectRulesBlock(filePath, version) {
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
-async function fileExists(filePath) {
-    try {
-        await access(filePath);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
 //# sourceMappingURL=config-scaffold.js.map

package/dist/storage/approval-operation-lock.js

@@ -2,6 +2,7 @@ import { createHash } from 'node:crypto';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { isAbsolute, resolve } from 'node:path';
 import { withFileLock } from './file-mutex.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { LockBusyError, withSpecLock } from '../engine/safety/cross-process-lock.js';
 const heldApprovalLocks = new AsyncLocalStorage();
 function approvalLockId(specId) {

package/dist/storage/auto-promoter-config-store.js

@@ -1,6 +1,7 @@
 // storage/auto-promoter-config-store.ts — Persists auto-promoter config (SPEC-391)
 // Layout: data/projects/{hash}/config/auto-promoter.json
 import { readJson, writeJson, projectDataDir, hashProjectPath } from './base-store.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { getDefaultConfig } from '../engine/auto-promoter.js';
 function configFile(projectId) {
     return `${projectDataDir(projectId)}/config/auto-promoter.json`;

package/dist/storage/autopilot-log-store.js

@@ -1,6 +1,7 @@
 // storage/autopilot-log-store.ts — SPEC-772: Autopilot cascade log persistence
 import { readFile, mkdir } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { atomicWriteFile } from '../engine/safety/atomic-write-file.js';
 import { reportClassifiedDegradation } from '../errors/classified-degradation.js';
 import { projectDataDir } from './base-store.js';

package/dist/storage/base-store.js

@@ -3,6 +3,7 @@
 import { readFile, mkdir } from 'node:fs/promises';
 import { readFileSync } from 'node:fs';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { writeJsonSafe } from '../engine/safety/atomic-writer.js';
 import { resolveStorageLayout } from './storage-layout.js';
 import { reportClassifiedDegradation } from '../errors/classified-degradation.js';

package/dist/storage/checkpoint-store.js

@@ -3,6 +3,7 @@ import { readdir, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { readJson, writeJson, projectDataDir } from './base-store.js';
 import { withFileLock } from './file-mutex.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { writeJsonSafe } from '../engine/safety/atomic-writer.js';
 // ---------------------------------------------------------------------------
 // Helpers

package/dist/storage/feedback-remote.js

@@ -1,5 +1,6 @@
 // storage/feedback-remote.ts — Configured remote feedback relay (fire-and-forget)
 // No PII is ever sent: no project paths, no user names, no emails.
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { networkFetch, withNetworkConsent } from '../engine/network-policy.js';
 function resolveConfiguredFeedbackEndpoint(endpoint) {
     const configured = endpoint ?? process.env.PLANU_FEEDBACK_ENDPOINT;

package/dist/storage/gaps-log.js

@@ -7,6 +7,7 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { appendFile, readFile, mkdir } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { fastAppendGapEntry, fastVerifyGapsChain } from '../engine/core-bridge.js';
 import { projectDataDir } from './base-store.js';
 import { reportClassifiedDegradation } from '../errors/classified-degradation.js';

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

@@ -2,6 +2,7 @@
 // Persistence file: data/global/registered-projects.json
 import { readJson, writeJson, globalDataDir, hashProjectPath } from './base-store.js';
 import { withFileLock } from './file-mutex.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { isEphemeralProject } from '../engine/data-projects-gc/pattern-matcher.js';
 import { reportClassifiedDegradation } from '../errors/classified-degradation.js';
 import { readFile } from 'node:fs/promises';

package/dist/storage/global-store.js

@@ -1,5 +1,6 @@
 import { readJson, writeJson, globalDataDir } from './base-store.js';
 import { withFileLock } from './file-mutex.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { applyLearnedLimit, markVerified } from '../engine/registry-extender.js';
 import { readFileSync } from 'node:fs';
 import { reportClassifiedDegradation } from '../errors/classified-degradation.js';

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

@@ -1,6 +1,8 @@
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { mergeContext } from '../../engine/context-merger.js';
 import { readJson, writeJson, projectDataDir } from '../base-store.js';
 import { withFileLock } from '../file-mutex.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { addMetricsToState } from '../../engine/calibrator.js';
 import { getKnowledge, knowledgeFile } from './knowledge.js';
 // --- File paths ---

package/dist/storage/migrations/canonical-storage.js

@@ -3,7 +3,9 @@ import { copyFile, lstat, mkdir, readFile, readdir, rename, rm, writeFile } from
 import { createHash, randomUUID } from 'node:crypto';
 import { homedir, tmpdir } from 'node:os';
 import { basename, dirname, isAbsolute, join, parse, relative, resolve, sep } from 'node:path';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { acquireLock as acquireFileMutex, releaseLock as releaseFileMutex, } from '../../engine/safety/file-mutex.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { assertNoObsoleteFileLock } from '../../engine/safety/obsolete-lock-guard.js';
 function sha256(value) {
     return createHash('sha256').update(value).digest('hex');
@@ -174,10 +176,17 @@ async function readJournal(path, expected) {
         throw error;
     }
 }
+function isTerminalPhaseValue(value) {
+    return value === 'completed';
+}
+async function quarantineStaleJournal(journalPath) {
+    const quarantinePath = journalPath.replace(/\.journal\.json$/, `.journal.stale-${String(Date.now())}.json`);
+    await rename(journalPath, quarantinePath);
+}
 async function retireCompletedJournalForNewSources(journalPath, expected) {
-    let parsed;
+    let rawText;
     try {
-        parsed = JSON.parse(await readFile(journalPath, 'utf8'));
+        rawText = await readFile(journalPath, 'utf8');
     }
     catch (error) {
         if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
@@ -185,32 +194,47 @@ async function retireCompletedJournalForNewSources(journalPath, expected) {
         }
         throw error;
     }
+    const parsed = JSON.parse(rawText);
     if (!parsed || typeof parsed !== 'object' || !('legacyRoots' in parsed)) {
         throw new Error('[Planu] Invalid or unsafe migration journal');
     }
-    const rawRoots = parsed.legacyRoots;
+    const record = parsed;
+    const rawRoots = record.legacyRoots;
     if (!Array.isArray(rawRoots) || !rawRoots.every((root) => typeof root === 'string')) {
         throw new Error('[Planu] Invalid or unsafe migration journal');
     }
-    if (JSON.stringify(rawRoots) === JSON.stringify(expected.legacyRoots)) {
-        return;
+    const rootsChanged = JSON.stringify(rawRoots) !== JSON.stringify(expected.legacyRoots);
+    const previousRoots = rootsChanged
+        ? rawRoots.map((root) => assertAbsolute(root, 'journal legacyRoot'))
+        : [...expected.legacyRoots];
+    if (rootsChanged) {
+        for (const root of previousRoots) {
+            assertNarrowLegacyRoot(root);
+            if (isInside(root, expected.destinationRoot) || isInside(expected.destinationRoot, root)) {
+                throw new Error('[Planu] Invalid or unsafe migration journal');
+            }
+        }
     }
-    const previousRoots = rawRoots.map((root) => assertAbsolute(root, 'journal legacyRoot'));
-    for (const root of previousRoots) {
-        assertNarrowLegacyRoot(root);
-        if (isInside(root, expected.destinationRoot) || isInside(expected.destinationRoot, root)) {
-            throw new Error('[Planu] Invalid or unsafe migration journal');
+    try {
+        const previous = validateJournal(parsed, { ...expected, legacyRoots: previousRoots });
+        if (!rootsChanged) {
+            return;
+        }
+        if (previous.phase !== 'completed') {
+            throw new Error('[Planu] Active migration journal does not match requested roots');
         }
+        // A completed destination remains live and may legitimately receive newer
+        // canonical records. Re-inventory its real directory instead of requiring
+        // the historical generation digest to remain frozen forever.
+        await inventoryStorageRoot(expected.destinationRoot);
+        await rm(journalPath, { force: true });
     }
-    const previous = validateJournal(parsed, { ...expected, legacyRoots: previousRoots });
-    if (previous.phase !== 'completed') {
-        throw new Error('[Planu] Active migration journal does not match requested roots');
+    catch (error) {
+        if (!isTerminalPhaseValue(record.phase)) {
+            throw error;
+        }
+        await quarantineStaleJournal(journalPath);
     }
-    // A completed destination remains live and may legitimately receive newer
-    // canonical records. Re-inventory its real directory instead of requiring
-    // the historical generation digest to remain frozen forever.
-    await inventoryStorageRoot(expected.destinationRoot);
-    await rm(journalPath, { force: true });
 }
 function recordTimestamp(value) {
     if (!value || typeof value !== 'object') {

package/dist/storage/project-drift-store.js

@@ -1,6 +1,7 @@
 // storage/project-drift-store.ts — SPEC-666: Read/write drift signals from .planu/drift-commits.ndjson
 import { readFile, writeFile, unlink, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { analyzeCommitRecord } from '../engine/project-drift-detector.js';
 import { hashProjectPath, projectDataDir } from './base-store.js';
 import { reportClassifiedDegradation } from '../errors/classified-degradation.js';

package/dist/storage/project-identity.js

@@ -3,6 +3,7 @@ import { lstat, mkdir, open, readFile, realpath, rename, rm, stat } from 'node:f
 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';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 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;

package/dist/storage/project-resolver.js

@@ -2,27 +2,11 @@
 // Resolves a project from its data directory OR from disk fingerprints (planu/ + specs/).
 // Used by planu_status, challenge_spec, and snapshot_spec_hashes to avoid "Project not found"
 // when the knowledge entry is missing but the project clearly exists on disk.
-import { access } from 'node:fs/promises';
 import { join } from 'node:path';
 import { getKnowledge, saveKnowledge } from './knowledge-store/knowledge.js';
 import { hashProjectPath, projectDataDir } from './base-store.js';
 import { reportClassifiedDegradation } from '../errors/classified-degradation.js';
-/**
- * Check whether a file/directory path exists on disk (no-throw helper).
- */
-async function pathExists(p) {
-    try {
-        await access(p);
-        return true;
-    }
-    catch (error) {
-        if (error.code === 'ENOENT' ||
-            (error instanceof Error && error.message === 'ENOENT')) {
-            return false;
-        }
-        throw error;
-    }
-}
+import { pathExistsStrict as pathExists } from '../core/shared/fs.js';
 /**
  * Resolve a project from its projectPath.
  *

package/dist/storage/runtime-db.d.ts

@@ -1,4 +1,6 @@
+import { DURABLE_JOB_STATES, type DurableJobRecord, type DurableJobState } from '../types/durable-job.js';
 import { type ValidationReceiptCheckpointLimits } from '../types/durable-validation.js';
+export { DURABLE_JOB_STATES, type DurableJobRecord, type DurableJobState };
 /** Count-only process diagnostic for deterministic resource lifecycle tests. */
 export declare function getRuntimeDatabaseDiagnosticsForTests(): {
     readonly openConnections: number;
@@ -50,26 +52,6 @@ export interface RuntimeProjectBundle {
     readonly outbox: readonly Record<string, unknown>[];
     readonly audit: readonly Record<string, unknown>[];
 }
-export declare const DURABLE_JOB_STATES: readonly ['accepted', 'running', 'checkpointed', 'cancelled', 'failed', 'dead-letter', 'completed'];
-export type DurableJobState = (typeof DURABLE_JOB_STATES)[number];
-export interface DurableJobRecord {
-    readonly id: string;
-    readonly projectId: string;
-    readonly workspaceId: string;
-    readonly state: DurableJobState;
-    readonly payload: unknown;
-    readonly checkpoint?: unknown;
-    readonly result?: unknown;
-    readonly error?: string;
-    readonly attempts: number;
-    readonly maxAttempts: number;
-    readonly cancelRequested: boolean;
-    readonly leaseOwner?: string;
-    readonly leaseExpiresAt?: string;
-    readonly fencingToken: number;
-    readonly createdAt: string;
-    readonly updatedAt: string;
-}
 export interface JobLeaseInput {
     readonly id: string;
     readonly projectId: string;

package/dist/storage/runtime-db.js

@@ -2,7 +2,9 @@
 import { mkdirSync } from 'node:fs';
 import { dirname, isAbsolute, resolve } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
+import { DURABLE_JOB_STATES, } from '../types/durable-job.js';
 import { parseValidationReceiptPendingCheckpoint, } from '../types/durable-validation.js';
+export { DURABLE_JOB_STATES };
 const CURRENT_SCHEMA_VERSION = 4;
 const DEFAULT_BUSY_TIMEOUT_MS = 5_000;
 const DEFAULT_MAX_CONNECTIONS = 4;
@@ -47,15 +49,6 @@ export function getRuntimeDatabaseDiagnosticsForTests() {
     }
     return { openConnections: count, integrityCheckedOpens, integrityBypassedOpens };
 }
-export const DURABLE_JOB_STATES = [
-    'accepted',
-    'running',
-    'checkpointed',
-    'cancelled',
-    'failed',
-    'dead-letter',
-    'completed',
-];
 export class RuntimeDatabaseCorruptionError extends Error {
     databasePath;
     detail;

package/dist/storage/semantic-index-store.js

@@ -6,6 +6,7 @@
 import { createHash } from 'node:crypto';
 import { readJson, writeJson, projectDataDir } from './base-store.js';
 import { withFileLock } from './file-mutex.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { TFIDFEngine, TFIDF_SCHEMA_VERSION, tokenize } from '../engine/vector-store/tfidf.js';
 function hashContent(content) {
     return createHash('sha256').update(content).digest('hex');

package/dist/storage/sentry-store.js

@@ -1,3 +1,4 @@
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { technologyValue } from '../engine/technology-registry.js';
 // storage/sentry-store.ts — Sentry integration persistence (SPEC-435)
 import { mkdir, readFile, writeFile } from 'node:fs/promises';

package/dist/storage/session-state-store.js

@@ -4,6 +4,7 @@ import { readJson, writeJson } from './base-store.js';
 import { join } from 'node:path';
 import { execSync } from 'node:child_process';
 import { readFile } from 'node:fs/promises';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { getUniqueTopLevelFrontmatterString } from '../engine/frontmatter-parser.js';
 import { reportClassifiedDegradation } from '../errors/classified-degradation.js';
 // ---------------------------------------------------------------------------

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

@@ -20,6 +20,13 @@ export declare function validateCanonicalSpecRows(projectId: string, specs: read
 export declare function withCanonicalSpecRepairLock<T>(projectId: string, fn: () => Promise<T>): Promise<T>;
 /** Evict the cache for a project (e.g. after external file changes). */
 export declare function invalidateSpecsCache(projectId: string): void;
+/**
+ * Discover the canonical `planu/specs/<specId[-slug]>/spec.md` for a spec by ID,
+ * independent of any stale or missing registry record. Fails closed (returns
+ * `null`) on zero or ambiguous matches, matching the fail-closed contract of
+ * {@link resolveVerifiedSpecPath}.
+ */
+export declare function discoverCanonicalSpecPath(specId: string, canonicalRoot: string): Promise<string | null>;
 /**
  * List every spec for a project.
  */

package/dist/storage/spec-store.js

@@ -3,13 +3,18 @@ import { CriticalJsonReadError, readCriticalJson, readJson, writeJson, projectDa
 import { decodeCriticalSchema, registerCriticalSchema } from './schema-registry.js';
 import { BoundaryFailure } from '../errors/error-taxonomy.js';
 import { withFileLock } from './file-mutex.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { computeHealthScore } from '../engine/spec-health-scorer.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { loadSpecContent } from '../engine/validation-loop.js';
 import { createHash, randomUUID } from 'node:crypto';
-import { isAbsolute } from 'node:path';
+import { basename, dirname, isAbsolute, join } from 'node:path';
+import { glob } from 'glob';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 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';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { hashEntry } from '../engine/audit-trail/hasher.js';
 // ---------------------------------------------------------------------------
 // SPEC-720: Guard error — direct status write forbidden
@@ -201,6 +206,21 @@ async function saveAll(projectId, specs) {
 export function invalidateSpecsCache(projectId) {
     specsCache.delete(projectId);
 }
+/**
+ * Discover the canonical `planu/specs/<specId[-slug]>/spec.md` for a spec by ID,
+ * independent of any stale or missing registry record. Fails closed (returns
+ * `null`) on zero or ambiguous matches, matching the fail-closed contract of
+ * {@link resolveVerifiedSpecPath}.
+ */
+export async function discoverCanonicalSpecPath(specId, canonicalRoot) {
+    const pattern = join(canonicalRoot, 'planu', 'specs', '*', 'spec.md');
+    const matches = await glob(pattern, { absolute: true });
+    const candidates = matches.filter((path) => {
+        const dir = basename(dirname(path));
+        return dir === specId || dir.startsWith(`${specId}-`);
+    });
+    return candidates.length === 1 ? (candidates[0] ?? null) : null;
+}
 // --- public API ---
 /**
  * List every spec for a project.

package/dist/storage/status-store/atomic-status-write.js

@@ -1,6 +1,7 @@
 import { readdir, unlink } from 'node:fs/promises';
 import { basename, dirname } from 'node:path';
 import { reportClassifiedDegradation } from '../../errors/classified-degradation.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { atomicWriteFile } from '../../engine/safety/atomic-write-file.js';
 /** Publish one complete canonical status snapshot with same-directory atomic replacement. */
 export function atomicStatusWrite(statusPath, status) {

package/dist/storage/status-store/file-lock.js

@@ -3,6 +3,7 @@
 // Uses a local FIFO for fair in-process ordering and the existing SQLite fenced lease for
 // exclusion across CLI, MCP, durable-worker, and background-side-effect processes.
 import { resolve } from 'node:path';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { acquireLock, releaseLock } from '../../engine/safety/file-mutex.js';
 import { cleanupDeadStatusTemps } from './atomic-status-write.js';
 const lockQueues = new Map();

package/dist/storage/status-store/self-healing.js

@@ -110,6 +110,7 @@ export async function quarantineCorruptStatus(statusPath, projectPath) {
     }
     return { quarantinedAt: new Date().toISOString(), quarantinePath };
 }
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { fastScanSpecsAsync } from '../../engine/core-bridge.js';
 /**
  * Rebuild a fresh status.json by reading all spec.md frontmatters.

package/dist/storage/storage-bundle.d.ts

@@ -1,5 +1,15 @@
-import type { StorageBundle, StorageBundleOptions } from '../types/storage-bundle.js';
-export type { StorageBundle, StorageBundleOptions } from '../types/storage-bundle.js';
+import { RuntimeDatabase, type RuntimeProjectBundle } from './runtime-db.js';
+export interface StorageBundle {
+    readonly schemaVersion: 1;
+    readonly createdAt: string;
+    readonly runtimeSchemaVersion: number;
+    readonly projectId: string;
+    readonly payload: RuntimeProjectBundle;
+    readonly checksum: string;
+}
+export interface StorageBundleOptions {
+    readonly database?: RuntimeDatabase;
+}
 export declare function exportStorageBundle(projectId: string, outputPath: string, options?: StorageBundleOptions): Promise<StorageBundle>;
 export declare function importStorageBundle(inputPath: string, options?: StorageBundleOptions): Promise<StorageBundle>;
 //# sourceMappingURL=storage-bundle.d.ts.map

package/dist/storage/supabase-store.js

@@ -1,3 +1,4 @@
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { technologyValue } from '../engine/technology-registry.js';
 // storage/supabase-store.ts — Supabase integration persistence (SPEC-437)
 import { join } from 'node:path';

package/dist/storage/technology-selection-store.js

@@ -1,6 +1,7 @@
 // storage/technology-selection-store.ts — SPEC-1021 project-local technology contract
 import { mkdir, readFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { writeJsonSafe } from '../engine/safety/atomic-writer.js';
 import { safeJsonParse } from './base-store.js';
 import { withFileLock } from './file-mutex.js';

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

@@ -1,5 +1,7 @@
 import type { TrashItem } from '../types/index.js';
 import type { TrashCleanupConfig, TrashCleanupResult } from '../types/safety.js';
+import { pathExistsStrictByStat as pathExists } from '../core/shared/fs.js';
+export { pathExists };
 /**
  * Load the trash manifest (list of all trashed items).
  */
@@ -29,10 +31,6 @@ export declare function purgeAllTrash(projectId: string): Promise<number>;
  * Count files in a directory recursively (for project delete summary).
  */
 export declare function countFiles(dirPath: string): Promise<number>;
-/**
- * Check if a path exists.
- */
-export declare function pathExists(p: string): Promise<boolean>;
 /**
  * Recursively sum file sizes in a directory.
  */

package/dist/storage/trash-store.js

@@ -2,6 +2,8 @@ import { readJson, writeJson, projectDataDir } from './base-store.js';
 import { withFileLock } from './file-mutex.js';
 import { mkdir, cp, rm, readdir, stat } from 'node:fs/promises';
 import { join } from 'node:path';
+import { pathExistsStrictByStat as pathExists } from '../core/shared/fs.js';
+export { pathExists };
 function sanitizeId(id) {
     const sanitized = id.replace(/[/\\]/g, '_').replace(/\.\./g, '_');
     if (!sanitized || sanitized === '.' || sanitized === '..') {
@@ -176,21 +178,6 @@ export async function countFiles(dirPath) {
         throw error;
     }
 }
-/**
- * Check if a path exists.
- */
-export async function pathExists(p) {
-    try {
-        await stat(p);
-        return true;
-    }
-    catch (error) {
-        if (error.code === 'ENOENT') {
-            return false;
-        }
-        throw error;
-    }
-}
 // ---------------------------------------------------------------------------
 // Trash TTL cleanup (SPEC-094 AC-6)
 // ---------------------------------------------------------------------------

package/dist/storage/vector-store/json-fallback.js

@@ -2,6 +2,7 @@
 // SPEC-075 AC-04: Same interface as SQLite adapter, uses JSON files.
 import { readJson, writeJson, projectDataDir } from '../base-store.js';
 import { withFileLock } from '../file-mutex.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { cosineSimilarity } from '../../engine/vector-store/similarity.js';
 let warnedOnce = false;
 /**

package/dist/storage/vector-store/migrator.js

@@ -2,6 +2,7 @@
 // SPEC-075 AC-05: Idempotent, preserves JSON backup.
 import { readJson, projectDataDir } from '../base-store.js';
 import { existsSync } from 'node:fs';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { TFIDFEngine } from '../../engine/vector-store/tfidf.js';
 import { reportClassifiedDegradation } from '../../errors/classified-degradation.js';
 /** Check if a migration marker exists (idempotency). */

package/dist/storage/vector-store/sqlite-adapter.js

@@ -1,5 +1,6 @@
 // storage/vector-store/sqlite-adapter.ts — SQLite storage backend using better-sqlite3.
 // SPEC-075 AC-03: WAL mode, BLOB embeddings, optional native dependency.
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { cosineSimilarity } from '../../engine/vector-store/similarity.js';
 import { projectDataDir, safeJsonParse } from '../base-store.js';
 import { mkdirSync, existsSync } from 'node:fs';

package/dist/tools/audit-claude-config.js

@@ -1,9 +1,9 @@
 // audit-claude-config.ts — Tool handler for audit_claude_config (SPEC-092)
 // SPEC-724: Added gate='core-rules' to assert per-host rule files exist.
 import { compactResult } from './output-formatter.js';
+import { fileExists } from '../core/shared/fs.js';
 import { auditClaudeMd, auditRules, auditMemory, auditSettings, calculateScore, pickQuickWins, } from '../engine/claude-config-auditor/index.js';
 import { detectHost } from '../engine/host-detection/detect-host.js';
-import { access } from 'node:fs/promises';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 // ---------------------------------------------------------------------------
@@ -14,15 +14,6 @@ const CORE_RULES_FILES = [
     'parallelism.md',
     'token-optimization.md',
 ];
-async function fileExists(filePath) {
-    try {
-        await access(filePath);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
 async function checkCoreRulesGate(projectPath) {
     const host = detectHost();
     const blockers = [];