@planu/cli 5.3.67 → 5.3.69

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.
  */
@@ -31,10 +38,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

@@ -3,10 +3,19 @@ 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 { 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
 // ---------------------------------------------------------------------------
@@ -197,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.
@@ -213,21 +237,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 +377,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/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 = [];

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