@planu/cli 4.14.1 → 5.0.0

package/dist/engine/spec-migrator/canonical-deduplicator.js

@@ -0,0 +1,479 @@
+/* eslint-disable max-lines, max-lines-per-function, complexity -- one audited administrative transaction */
+import { createHash } from 'node:crypto';
+import { mkdir as mkdirFs, readFile as readFileFs } from 'node:fs/promises';
+import { join, relative, resolve } from 'node:path';
+import { atomicWriteFile } from '../safety/atomic-write-file.js';
+import { projectDataDir } from '../../storage/base-store.js';
+import { invalidateSpecsCache, validateCanonicalSpecRows, withCanonicalSpecRepairLock, } from '../../storage/spec-store.js';
+function digest(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function canonicalJson(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+function privateFailure(message) {
+    return new Error(`[Planu] Canonical repair blocked: ${message}`);
+}
+function repairPaths(projectId) {
+    const root = projectDataDir(projectId);
+    return { store: join(root, 'specs.json'), dir: join(root, 'repairs', 'spec-id-dedup') };
+}
+function isContained(parent, child) {
+    const rel = relative(resolve(parent), resolve(child));
+    return rel !== '' && !rel.startsWith('..') && !rel.includes('/../');
+}
+function artifactPath(projectId, artifactId) {
+    const { dir } = repairPaths(projectId);
+    if (!artifactId.startsWith('repairs/spec-id-dedup/')) {
+        throw privateFailure('repair artifact is outside the project repair directory');
+    }
+    const candidate = resolve(projectDataDir(projectId), artifactId);
+    if (!isContained(dir, candidate)) {
+        throw privateFailure('repair artifact is outside the project repair directory');
+    }
+    return candidate;
+}
+function parseRawStore(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw.toString('utf8'));
+    }
+    catch {
+        throw privateFailure('store is not valid JSON');
+    }
+    if (Array.isArray(parsed)) {
+        return { envelope: false, rows: parsed };
+    }
+    if (parsed && typeof parsed === 'object' && Array.isArray(parsed.data)) {
+        return { envelope: true, rows: parsed.data };
+    }
+    throw privateFailure('store shape is invalid');
+}
+function serializeStore(store, rows) {
+    return Buffer.from(canonicalJson(store.envelope ? { schemaVersion: 1, data: rows } : rows), 'utf8');
+}
+function requireString(value, label) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw privateFailure(`${label} is missing`);
+    }
+    return value;
+}
+function validateManifest(manifest, requestedProjectId) {
+    if (manifest.projectId !== requestedProjectId) {
+        throw privateFailure('manifest project does not match requested project');
+    }
+    if (!/^[a-f0-9]{64}$/.test(manifest.sourceDigest)) {
+        throw privateFailure('manifest source digest is invalid');
+    }
+    if (!manifest.sourceProjectAliases.includes(manifest.canonicalSourceProjectAlias) ||
+        manifest.canonicalSourceProjectAlias.length === 0) {
+        throw privateFailure('canonical source alias is not declared');
+    }
+    if (new Set(manifest.foreignOwnerSingletonIds).size !== manifest.foreignOwnerSingletonIds.length) {
+        throw privateFailure('foreign singleton IDs are duplicated');
+    }
+    for (const override of Object.values(manifest.lifecycleOverrides ?? {})) {
+        if (override.reason.length < 100 || !override.canonicalUuid) {
+            throw privateFailure('lifecycle override is incomplete');
+        }
+    }
+}
+function identityFieldsAgree(rows) {
+    const first = rows[0];
+    return (first !== undefined &&
+        rows.every((row) => row.id === first.id &&
+            row.title === first.title &&
+            row.slug === first.slug &&
+            row.specPath === first.specPath));
+}
+function validateRawUuidIdentities(rows) {
+    const identities = new Set();
+    for (const row of rows) {
+        const primary = requireString(row.uuid, 'primary UUID');
+        for (const identity of [primary, ...(row.uuidAliases ?? [])]) {
+            const normalized = requireString(identity, 'UUID alias');
+            if (identities.has(normalized)) {
+                throw privateFailure('raw UUID identity is repeated or ambiguous');
+            }
+            identities.add(normalized);
+        }
+    }
+}
+function planPayload(plan) {
+    return {
+        changed: plan.changed,
+        projectId: plan.projectId,
+        sourceDigest: plan.sourceDigest,
+        manifestDigest: plan.manifestDigest,
+        resultDigest: plan.resultDigest,
+        duplicateGroups: plan.duplicateGroups,
+        foreignOwnerSingletons: plan.foreignOwnerSingletons,
+        fieldChanges: plan.fieldChanges,
+        artifactId: plan.artifactId,
+    };
+}
+/** Pure planner. It does not read or write the canonical store. */
+export function buildCanonicalRepairPlan(raw, manifest, manifestDigest = digest(canonicalJson(manifest)), requestedProjectId = manifest.projectId) {
+    validateManifest(manifest, requestedProjectId);
+    const sourceDigest = digest(raw);
+    if (sourceDigest !== manifest.sourceDigest) {
+        const repaired = parseRawStore(raw);
+        try {
+            validateCanonicalSpecRows(requestedProjectId, repaired.rows);
+            const unchanged = {
+                changed: false,
+                projectId: requestedProjectId,
+                sourceDigest,
+                manifestDigest,
+                resultDigest: sourceDigest,
+                duplicateGroups: 0,
+                foreignOwnerSingletons: 0,
+                fieldChanges: [],
+                artifactId: `repairs/spec-id-dedup/${sourceDigest}.dry-run.json`,
+            };
+            return {
+                ...unchanged,
+                planDigest: digest(canonicalJson(planPayload(unchanged))),
+                resultBytes: raw,
+            };
+        }
+        catch {
+            throw privateFailure('source digest does not match manifest');
+        }
+    }
+    const store = parseRawStore(raw);
+    validateRawUuidIdentities(store.rows);
+    const groups = new Map();
+    for (const row of store.rows) {
+        const id = requireString(row.id, 'spec ID');
+        const group = groups.get(id);
+        if (group) {
+            group.push(row);
+        }
+        else {
+            groups.set(id, [row]);
+        }
+    }
+    const fieldChanges = [];
+    const nextRows = [];
+    const listedSingletons = new Set(manifest.foreignOwnerSingletonIds);
+    let duplicates = 0;
+    let singletonChanges = 0;
+    for (const [id, rows] of groups) {
+        const row = rows[0];
+        if (!row) {
+            throw privateFailure('empty duplicate group');
+        }
+        if (rows.length === 1) {
+            if (row.projectId === requestedProjectId) {
+                nextRows.push({ ...row });
+                continue;
+            }
+            if (!listedSingletons.delete(id) || !manifest.sourceProjectAliases.includes(row.projectId)) {
+                throw privateFailure('foreign singleton is not explicitly authorized');
+            }
+            nextRows.push({ ...row, projectId: requestedProjectId });
+            singletonChanges += 1;
+            fieldChanges.push({ id, field: 'projectId', from: row.projectId, to: requestedProjectId });
+            continue;
+        }
+        duplicates += 1;
+        if (!identityFieldsAgree(rows)) {
+            throw privateFailure('duplicate group has incompatible identity fields');
+        }
+        const canonicalRows = rows.filter((candidate) => candidate.projectId === manifest.canonicalSourceProjectAlias);
+        if (canonicalRows.length !== 1) {
+            throw privateFailure('duplicate group must have exactly one canonical-source row');
+        }
+        const canonical = canonicalRows[0];
+        if (!canonical) {
+            throw privateFailure('canonical-source row is missing');
+        }
+        const primaryUuid = requireString(canonical.uuid, 'canonical UUID');
+        const statuses = new Set(rows.map((candidate) => candidate.status));
+        const override = manifest.lifecycleOverrides?.[id];
+        if (statuses.size > 1) {
+            if (!override) {
+                throw privateFailure('lifecycle disagreement has no valid override');
+            }
+            if (override.canonicalUuid !== primaryUuid ||
+                override.retainedStatus !== canonical.status ||
+                override.reason.length < 100) {
+                throw privateFailure('lifecycle disagreement has no valid override');
+            }
+        }
+        const aliases = new Set(canonical.uuidAliases ?? []);
+        for (const candidate of rows) {
+            const candidateUuid = requireString(candidate.uuid, 'duplicate UUID');
+            if (candidate !== canonical) {
+                if (!manifest.sourceProjectAliases.includes(candidate.projectId)) {
+                    throw privateFailure('duplicate row has an unknown source project alias');
+                }
+                aliases.add(candidateUuid);
+                for (const alias of candidate.uuidAliases ?? []) {
+                    aliases.add(alias);
+                }
+                for (const field of ['technicalPath', 'progressPath']) {
+                    if (candidate[field] !== canonical[field]) {
+                        fieldChanges.push({
+                            id,
+                            field,
+                            from: candidate[field] ?? null,
+                            to: canonical[field] ?? null,
+                        });
+                    }
+                }
+            }
+        }
+        aliases.delete(primaryUuid);
+        nextRows.push({
+            ...canonical,
+            projectId: requestedProjectId,
+            ...(aliases.size > 0
+                ? { uuidAliases: [...aliases].sort((left, right) => left.localeCompare(right)) }
+                : {}),
+        });
+        fieldChanges.push({
+            id,
+            field: 'projectId',
+            from: canonical.projectId,
+            to: requestedProjectId,
+        });
+    }
+    if (listedSingletons.size > 0) {
+        throw privateFailure('manifest lists a missing foreign singleton');
+    }
+    validateCanonicalSpecRows(requestedProjectId, nextRows);
+    const resultBytes = serializeStore(store, nextRows);
+    const base = {
+        changed: duplicates > 0 || singletonChanges > 0,
+        projectId: requestedProjectId,
+        sourceDigest,
+        manifestDigest,
+        resultDigest: digest(resultBytes),
+        duplicateGroups: duplicates,
+        foreignOwnerSingletons: singletonChanges,
+        fieldChanges,
+        artifactId: `repairs/spec-id-dedup/${sourceDigest}.dry-run.json`,
+    };
+    return { ...base, planDigest: digest(canonicalJson(planPayload(base))), resultBytes };
+}
+function toPrivateReport(plan) {
+    return {
+        schemaVersion: 1,
+        ...planPayload(plan),
+        planDigest: plan.planDigest,
+    };
+}
+function buildReceipt(plan, raw, review, authorizationReason, manifest) {
+    const source = parseRawStore(raw).rows;
+    const groups = new Map();
+    for (const row of source) {
+        const group = groups.get(row.id);
+        if (group) {
+            group.push(row);
+        }
+        else {
+            groups.set(row.id, [row]);
+        }
+    }
+    const removedRows = [];
+    const singletonOwnershipChanges = [];
+    const retainedUuids = [];
+    const aliasesAdded = [];
+    for (const [id, rows] of groups) {
+        if (rows.length === 1) {
+            const only = rows[0];
+            if (!only) {
+                throw privateFailure('singleton row is missing');
+            }
+            if (only.projectId !== manifest.projectId) {
+                singletonOwnershipChanges.push({
+                    id,
+                    beforeProjectId: only.projectId,
+                    afterProjectId: manifest.projectId,
+                });
+            }
+            continue;
+        }
+        const canonical = rows.find((row) => row.projectId === manifest.canonicalSourceProjectAlias);
+        if (!canonical) {
+            throw privateFailure('canonical-source row is missing');
+        }
+        retainedUuids.push({ id, uuid: canonical.uuid });
+        const aliases = rows
+            .filter((row) => row !== canonical)
+            .flatMap((row) => [row.uuid, ...(row.uuidAliases ?? [])])
+            .filter((uuid) => typeof uuid === 'string' && uuid.length > 0)
+            .sort((left, right) => left.localeCompare(right));
+        aliasesAdded.push({ id, aliases });
+        removedRows.push(...rows.filter((row) => row !== canonical));
+    }
+    return {
+        schemaVersion: 1,
+        state: 'prepared',
+        projectId: manifest.projectId,
+        reviewer: review.reviewer,
+        verdict: review.verdict,
+        authorizationReason,
+        sourceDigest: plan.sourceDigest,
+        manifestDigest: plan.manifestDigest,
+        planDigest: plan.planDigest,
+        resultDigest: plan.resultDigest,
+        backupArtifactId: `repairs/spec-id-dedup/${plan.sourceDigest}.backup.json`,
+        backupDigest: digest(raw),
+        removedRows,
+        singletonOwnershipChanges,
+        retainedUuids,
+        aliasesAdded,
+        fieldChanges: plan.fieldChanges,
+    };
+}
+function validateApplyInput(plan, input, review) {
+    const authorizationReason = input.authorizationReason;
+    if (authorizationReason === undefined || authorizationReason.length < 100) {
+        throw privateFailure('authorization reason is too short');
+    }
+    if (input.expectedSourceDigest !== plan.sourceDigest ||
+        input.expectedManifestDigest !== plan.manifestDigest ||
+        input.expectedPlanDigest !== plan.planDigest ||
+        input.expectedResultDigest !== plan.resultDigest) {
+        throw privateFailure('reviewed digest does not match current plan');
+    }
+    if (review.reviewer !== 'planu-data-repair-reviewer' ||
+        review.verdict !== 'approved' ||
+        review.sourceDigest !== plan.sourceDigest ||
+        review.manifestDigest !== plan.manifestDigest ||
+        review.planDigest !== plan.planDigest ||
+        review.resultDigest !== plan.resultDigest) {
+        throw privateFailure('independent review evidence is invalid');
+    }
+    return authorizationReason;
+}
+function ioFor(io) {
+    return {
+        readFile: io?.readFile ?? ((path) => readFileFs(path)),
+        writeAtomic: io?.writeAtomic ?? ((path, bytes) => atomicWriteFile(path, bytes, { mode: 0o600 })),
+        mkdir: io?.mkdir ??
+            (async (path) => {
+                await mkdirFs(path, { recursive: true });
+            }),
+        withLock: io?.withLock ?? withCanonicalSpecRepairLock,
+    };
+}
+async function readJsonArtifact(path, label, io) {
+    try {
+        return JSON.parse((await io.readFile(path)).toString('utf8'));
+    }
+    catch {
+        throw privateFailure(`${label} is unreadable`);
+    }
+}
+/** Runs dry-run or the explicitly authorized, lock-protected repair. */
+export async function repairDuplicateSpecIds(input) {
+    const io = ioFor(input.io);
+    const manifestBytes = await io.readFile(input.manifestPath).catch(() => {
+        throw privateFailure('manifest is unreadable');
+    });
+    let manifest;
+    try {
+        manifest = JSON.parse(manifestBytes.toString('utf8'));
+    }
+    catch {
+        throw privateFailure('manifest is not valid JSON');
+    }
+    // This binding intentionally precedes every canonical store read and write.
+    validateManifest(manifest, input.projectId);
+    const manifestDigest = digest(manifestBytes);
+    const paths = repairPaths(input.projectId);
+    if (input.dryRun === true) {
+        const raw = await io.readFile(paths.store);
+        const plan = buildCanonicalRepairPlan(raw, manifest, manifestDigest, input.projectId);
+        await io.mkdir(paths.dir);
+        await io.writeAtomic(artifactPath(input.projectId, plan.artifactId), canonicalJson(toPrivateReport(plan)));
+        return plan;
+    }
+    if (!input.reviewPath) {
+        throw privateFailure('apply requires review evidence');
+    }
+    const review = await readJsonArtifact(input.reviewPath, 'review evidence', io);
+    return io.withLock(input.projectId, async () => {
+        const raw = await io.readFile(paths.store);
+        const plan = buildCanonicalRepairPlan(raw, manifest, manifestDigest, input.projectId);
+        if (!plan.changed) {
+            return plan;
+        }
+        const authorizationReason = validateApplyInput(plan, input, review);
+        const receipt = buildReceipt(plan, raw, review, authorizationReason, manifest);
+        const backupPath = artifactPath(input.projectId, receipt.backupArtifactId);
+        const receiptId = `repairs/spec-id-dedup/${plan.sourceDigest}.receipt.json`;
+        const receiptPath = artifactPath(input.projectId, receiptId);
+        await io.mkdir(paths.dir);
+        await io.writeAtomic(backupPath, raw);
+        await io.writeAtomic(receiptPath, canonicalJson(receipt));
+        await io.writeAtomic(paths.store, plan.resultBytes);
+        try {
+            await io.writeAtomic(receiptPath, canonicalJson({ ...receipt, state: 'committed' }));
+        }
+        catch {
+            invalidateSpecsCache(input.projectId);
+            return { ...plan, finalizationDegraded: true };
+        }
+        invalidateSpecsCache(input.projectId);
+        return plan;
+    });
+}
+function isValidReceipt(value, projectId) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const receipt = value;
+    return (receipt.schemaVersion === 1 &&
+        receipt.projectId === projectId &&
+        (receipt.state === 'prepared' || receipt.state === 'committed') &&
+        typeof receipt.sourceDigest === 'string' &&
+        /^[a-f0-9]{64}$/.test(receipt.sourceDigest) &&
+        typeof receipt.manifestDigest === 'string' &&
+        /^[a-f0-9]{64}$/.test(receipt.manifestDigest) &&
+        typeof receipt.planDigest === 'string' &&
+        /^[a-f0-9]{64}$/.test(receipt.planDigest) &&
+        typeof receipt.resultDigest === 'string' &&
+        /^[a-f0-9]{64}$/.test(receipt.resultDigest) &&
+        typeof receipt.backupDigest === 'string' &&
+        /^[a-f0-9]{64}$/.test(receipt.backupDigest) &&
+        typeof receipt.backupArtifactId === 'string' &&
+        receipt.backupArtifactId.length > 0);
+}
+export async function rollbackCanonicalRepair(projectId, receiptPath) {
+    const paths = repairPaths(projectId);
+    if (!isContained(paths.dir, receiptPath)) {
+        throw privateFailure('receipt is outside the project repair directory');
+    }
+    const io = ioFor(undefined);
+    const receipt = await readJsonArtifact(receiptPath, 'receipt', io);
+    if (!isValidReceipt(receipt, projectId)) {
+        throw privateFailure('receipt schema, project, state, or digest is invalid');
+    }
+    const backupPath = artifactPath(projectId, receipt.backupArtifactId);
+    return withCanonicalSpecRepairLock(projectId, async () => {
+        const current = await io.readFile(paths.store);
+        if (digest(current) !== receipt.resultDigest) {
+            throw privateFailure('rollback source does not match committed result');
+        }
+        const backup = await io.readFile(backupPath).catch(() => {
+            throw privateFailure('backup is unreadable');
+        });
+        if (digest(backup) !== receipt.backupDigest) {
+            throw privateFailure('backup digest does not match receipt');
+        }
+        await io.writeAtomic(paths.store, backup);
+        invalidateSpecsCache(projectId);
+    });
+}
+export const CANONICAL_DEDUPLICATOR_INTERNALS = {
+    digest,
+    parseRawStore,
+    artifactPath,
+    isContained,
+};
+//# sourceMappingURL=canonical-deduplicator.js.map

package/dist/engine/spec-migrator/filesystem-import.d.ts

@@ -1,14 +1,10 @@
-import type { Spec } from '../../types/index.js';
+import type { FilesystemImportDeps, FilesystemImportResult } from '../../types/index.js';
 /**
  * Import specs that exist on disk (planu/specs/) but are missing from the store.
  * Reads frontmatter from each spec.md and creates a minimal Spec record in the store.
  * This ensures list_specs returns ALL specs, not just those created via create_spec.
  */
-export declare function importFilesystemSpecs(projectPath: string, deps: {
-    listSpecs: (projectId: string) => Promise<Spec[]>;
-    createSpec: (projectId: string, spec: Spec) => Promise<Spec>;
-}, projectId: string): Promise<{
-    importedCount: number;
-    errors: string[];
-}>;
+export declare function importFilesystemSpecs(projectPath: string, deps: FilesystemImportDeps, projectId: string, options?: {
+    strictPortableContract?: boolean;
+}): Promise<FilesystemImportResult>;
 //# sourceMappingURL=filesystem-import.d.ts.map

package/dist/engine/spec-migrator/filesystem-import.js

@@ -3,16 +3,74 @@ import { readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { parseFrontmatterLocal, validSpecType, validSpecScope, validSpecStatus, validRiskLevel, validSpecTarget, validDifficulty, } from './frontmatter-parser.js';
 const SPEC_FOLDER_ID_RE = /^(SPEC-\d{3,})/;
+function optionalString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function compatibleIdentity(existing, candidate) {
+    return (existing.id === candidate.id &&
+        existing.title === candidate.title &&
+        existing.slug === candidate.slug &&
+        (existing.uuid === undefined ||
+            candidate.uuid === undefined ||
+            existing.uuid === candidate.uuid));
+}
+function hasUuidIdentity(spec, uuid) {
+    return uuid !== undefined && (spec.uuid === uuid || spec.uuidAliases?.includes(uuid) === true);
+}
+function hasAnyUuidIdentity(existing, candidate) {
+    return [candidate.uuid, ...(candidate.uuidAliases ?? [])].some((uuid) => hasUuidIdentity(existing, uuid));
+}
+function isValidPortableMetadata(specId, metadata) {
+    return (metadata.id === specId &&
+        typeof metadata.title === 'string' &&
+        metadata.title.trim().length > 0 &&
+        validSpecType(metadata.type) !== null &&
+        validSpecScope(metadata.scope) !== null &&
+        validSpecStatus(metadata.status) !== null &&
+        validRiskLevel(metadata.risk) !== null &&
+        validSpecTarget(metadata.target) !== null &&
+        validDifficulty(metadata.difficulty) !== null);
+}
+function generationFromMetadata(metadata, fallbackGeneratedAt) {
+    const value = metadata.generation;
+    if (typeof value !== 'object' || value === null) {
+        return undefined;
+    }
+    const generationMetadata = value;
+    const method = generationMetadata.method;
+    if (method !== 'deterministic' && method !== 'internal-model' && method !== 'host') {
+        return undefined;
+    }
+    const host = optionalString(generationMetadata.host);
+    const modelId = optionalString(generationMetadata.modelId);
+    return {
+        method,
+        generatedAt: optionalString(generationMetadata.generatedAt) ?? fallbackGeneratedAt,
+        ...(host ? { host } : {}),
+        ...(modelId ? { modelId } : {}),
+    };
+}
+// eslint-disable-next-line max-lines-per-function, complexity -- portable metadata is normalized at one boundary
 function buildSpecFromMetadata(specId, entryName, projectPath, projectId, metadata) {
     const now = new Date().toISOString();
     const folder = join(projectPath, 'planu', 'specs', entryName);
     const specPath = join(folder, 'spec.md');
     const slug = entryName.replace(/^SPEC-\d{3,}-/, '');
     const stringList = (value) => Array.isArray(value) ? value.filter((item) => typeof item === 'string') : [];
+    const generation = generationFromMetadata(metadata, now);
     return {
         id: specId,
+        ...(optionalString(metadata.uuid) ? { uuid: optionalString(metadata.uuid) } : {}),
+        ...(Array.isArray(metadata.uuidAliases)
+            ? {
+                uuidAliases: metadata.uuidAliases
+                    .filter((value) => typeof value === 'string' && value.length > 0)
+                    .sort((left, right) => left.localeCompare(right)),
+            }
+            : {}),
         title: typeof metadata.title === 'string' ? metadata.title : specId,
         slug,
+        ...(optionalString(metadata.feature) ? { feature: optionalString(metadata.feature) } : {}),
         type: validSpecType(metadata.type) ?? 'feature',
         scope: validSpecScope(metadata.scope) ?? 'feature',
         status: validSpecStatus(metadata.status) ?? 'draft',
@@ -46,6 +104,21 @@ function buildSpecFromMetadata(specId, entryName, projectPath, projectId, metada
         tags: stringList(metadata.tags),
         dependencies: stringList(metadata.dependencies),
         blockedBy: stringList(metadata.blockedBy),
+        outOfScope: stringList(metadata.outOfScope),
+        ...(metadata.priority === 'P0'
+            ? { priority: 'high' }
+            : metadata.priority === 'high' ||
+                metadata.priority === 'medium' ||
+                metadata.priority === 'low'
+                ? { priority: metadata.priority }
+                : {}),
+        ...(metadata.spec_format_version === '0.x' || metadata.spec_format_version === '1.0'
+            ? { spec_format_version: metadata.spec_format_version }
+            : {}),
+        ...(optionalString(metadata.spec_version)
+            ? { spec_version: optionalString(metadata.spec_version) }
+            : {}),
+        ...(generation ? { generation } : {}),
         gitBranch: typeof metadata.branch === 'string'
             ? metadata.branch
             : `feat/${specId.toLowerCase()}-${slug}`,
@@ -57,18 +130,18 @@ function buildSpecFromMetadata(specId, entryName, projectPath, projectId, metada
  * Reads frontmatter from each spec.md and creates a minimal Spec record in the store.
  * This ensures list_specs returns ALL specs, not just those created via create_spec.
  */
-export async function importFilesystemSpecs(projectPath, deps, projectId) {
+export async function importFilesystemSpecs(projectPath, deps, projectId, options = {}) {
     const specsRoot = join(projectPath, 'planu/specs');
-    const errors = [];
-    let importedCount = 0;
+    const failures = [];
+    const importedSpecIds = [];
     const storeSpecs = await deps.listSpecs(projectId);
-    const storeIds = new Set(storeSpecs.map((s) => s.id));
+    const specsById = new Map(storeSpecs.map((spec) => [spec.id, spec]));
     let entries;
     try {
         entries = await readdir(specsRoot, { withFileTypes: true });
     }
     catch {
-        return { importedCount: 0, errors: [] };
+        return { importedCount: 0, importedSpecIds, failures, errors: [] };
     }
     for (const entry of entries) {
         if (!entry.isDirectory()) {
@@ -79,22 +152,56 @@ export async function importFilesystemSpecs(projectPath, deps, projectId) {
             continue;
         }
         const specId = idMatch[1];
-        if (storeIds.has(specId)) {
-            continue;
-        }
         const specMdPath = join(specsRoot, entry.name, 'spec.md');
+        const relativeSpecPath = `planu/specs/${entry.name}/spec.md`;
+        let spec;
         try {
             const content = await readFile(specMdPath, 'utf-8');
             const { metadata } = parseFrontmatterLocal(content);
-            const spec = buildSpecFromMetadata(specId, entry.name, projectPath, projectId, metadata);
+            if (options.strictPortableContract === true && !isValidPortableMetadata(specId, metadata)) {
+                failures.push({ specId, path: relativeSpecPath, code: 'INVALID_CONTRACT' });
+                continue;
+            }
+            spec = buildSpecFromMetadata(specId, entry.name, projectPath, projectId, metadata);
+        }
+        catch {
+            failures.push({ specId, path: relativeSpecPath, code: 'READ_FAILED' });
+            continue;
+        }
+        const existing = specsById.get(specId);
+        if (existing !== undefined) {
+            if (!compatibleIdentity(existing, spec)) {
+                failures.push({ specId, path: relativeSpecPath, code: 'INCOMPATIBLE_IDENTITY' });
+            }
+            continue;
+        }
+        if (storeSpecs.some((stored) => hasAnyUuidIdentity(stored, spec))) {
+            failures.push({ specId, path: relativeSpecPath, code: 'INCOMPATIBLE_IDENTITY' });
+            continue;
+        }
+        try {
             await deps.createSpec(projectId, spec);
-            storeIds.add(specId);
-            importedCount++;
+            specsById.set(specId, spec);
+            importedSpecIds.push(specId);
         }
-        catch (err) {
-            errors.push(`${specId}: ${err instanceof Error ? err.message : String(err)}`);
+        catch {
+            const winner = await deps.getSpecFresh?.(projectId, specId).catch(() => null);
+            if (winner !== undefined && winner !== null && compatibleIdentity(winner, spec)) {
+                specsById.set(specId, winner);
+                continue;
+            }
+            failures.push({
+                specId,
+                path: relativeSpecPath,
+                code: winner ? 'INCOMPATIBLE_IDENTITY' : 'CREATE_FAILED',
+            });
         }
     }
-    return { importedCount, errors };
+    return {
+        importedCount: importedSpecIds.length,
+        importedSpecIds,
+        failures,
+        errors: failures.map((failure) => `${failure.specId}: ${failure.code}`),
+    };
 }
 //# sourceMappingURL=filesystem-import.js.map