@planu/cli 5.5.3 → 5.7.0

package/dist/engine/lifecycle-reconciliation.js

@@ -110,6 +110,41 @@ async function completeForwardReconciliation(args) {
     await args.persistReceipt(args.receiptPath, committed);
     return committed;
 }
+async function resolveReviewDigest(args) {
+    const { input, spec, reason } = args;
+    if (input.declaredDriftKind === 'architectural-premise') {
+        const reviewDigest = digest(reason.trim());
+        if (reviewDigest !== input.implementationReviewDigest) {
+            return failure('declared drift review digest does not match the declared reason', 'RECONCILIATION_STALE');
+        }
+        return { reviewDigest, driftSource: 'declared-architectural-premise' };
+    }
+    const reportPath = join(projectDataDir(args.projectId), 'handoffs', spec.id, 'validation-report.json');
+    let reportBytes;
+    try {
+        const status = await lstat(reportPath);
+        if (status.isSymbolicLink() || !status.isFile()) {
+            return failure('validation report is unsafe');
+        }
+        reportBytes = await readFile(reportPath);
+    }
+    catch {
+        return failure('validation report is missing');
+    }
+    const report = ValidationReportV1Schema.safeParse(JSON.parse(reportBytes.toString('utf8')));
+    if (!report.success ||
+        report.data.passed ||
+        report.data.reviewer.kind !== 'automation' ||
+        report.data.reviewer.agent !== AUTOMATED_VALIDATOR_AGENT ||
+        report.data.reviewer.verdict !== 'changes-requested') {
+        return failure('validation report is not an automated changes-requested finding');
+    }
+    const reviewDigest = digest(reportBytes);
+    if (reviewDigest !== input.implementationReviewDigest) {
+        return failure('implementation review digest does not match validation report', 'RECONCILIATION_STALE');
+    }
+    return { reviewDigest };
+}
 async function validateRequest(args) {
     const { input, spec, context } = args;
     if (context.surface !== 'local-mcp') {
@@ -136,42 +171,41 @@ async function validateRequest(args) {
     if (!latest?.transitionId || latest.transitionId !== input.expectedImplementingTransitionId) {
         return failure('expected implementing transition is stale', 'RECONCILIATION_STALE');
     }
-    const reportPath = join(projectDataDir(args.projectId), 'handoffs', spec.id, 'validation-report.json');
-    let reportBytes;
-    try {
-        const status = await lstat(reportPath);
-        if (status.isSymbolicLink() || !status.isFile()) {
-            return failure('validation report is unsafe');
-        }
-        reportBytes = await readFile(reportPath);
-    }
-    catch {
-        return failure('validation report is missing');
-    }
-    const report = ValidationReportV1Schema.safeParse(JSON.parse(reportBytes.toString('utf8')));
-    if (!report.success ||
-        report.data.passed ||
-        report.data.reviewer.kind !== 'automation' ||
-        report.data.reviewer.agent !== AUTOMATED_VALIDATOR_AGENT ||
-        report.data.reviewer.verdict !== 'changes-requested') {
-        return failure('validation report is not an automated changes-requested finding');
-    }
-    const reviewDigest = digest(reportBytes);
-    if (reviewDigest !== input.implementationReviewDigest) {
-        return failure('implementation review digest does not match validation report', 'RECONCILIATION_STALE');
+    const resolution = await resolveReviewDigest({
+        input,
+        spec,
+        projectId: args.projectId,
+        reason: input.reason,
+    });
+    if (!('reviewDigest' in resolution) || typeof resolution.reviewDigest !== 'string') {
+        return resolution;
     }
+    const resolved = resolution;
     return {
-        reviewDigest,
-        bindingDigest: digest([
-            args.projectId,
-            spec.id,
-            input.reconciliationRequestId,
-            latest.transitionId,
-            reviewDigest,
-            digest(input.reason.trim()),
-        ].join('\0')),
+        reviewDigest: resolved.reviewDigest,
+        driftSource: resolved.driftSource,
+        bindingDigest: computeBindingDigest({
+            projectId: args.projectId,
+            specId: spec.id,
+            requestId: input.reconciliationRequestId,
+            transitionId: latest.transitionId,
+            reviewDigest: resolved.reviewDigest,
+            reasonDigest: digest(input.reason.trim()),
+            driftSource: resolved.driftSource,
+        }),
     };
 }
+function computeBindingDigest(args) {
+    return digest([
+        args.projectId,
+        args.specId,
+        args.requestId,
+        args.transitionId,
+        args.reviewDigest,
+        args.reasonDigest,
+        ...(args.driftSource ? [args.driftSource] : []),
+    ].join('\0'));
+}
 function validateDurableReceiptBinding(args) {
     const { input, receipt } = args;
     if (input.expectedImplementingTransitionId !== receipt.sourceImplementingTransitionId ||
@@ -180,14 +214,15 @@ function validateDurableReceiptBinding(args) {
         digest(input.reason.trim()) !== receipt.reasonDigest) {
         return failure('reconciliation retry binding conflicts with the durable receipt', 'RECONCILIATION_BINDING_CONFLICT');
     }
-    const bindingDigest = digest([
-        args.projectId,
-        args.specId,
-        receipt.requestId,
-        receipt.sourceImplementingTransitionId,
-        receipt.implementationReviewDigest,
-        receipt.reasonDigest,
-    ].join('\0'));
+    const bindingDigest = computeBindingDigest({
+        projectId: args.projectId,
+        specId: args.specId,
+        requestId: receipt.requestId,
+        transitionId: receipt.sourceImplementingTransitionId,
+        reviewDigest: receipt.implementationReviewDigest,
+        reasonDigest: receipt.reasonDigest,
+        driftSource: receipt.driftSource,
+    });
     if (bindingDigest !== receipt.bindingDigest) {
         return failure('durable reconciliation binding is invalid', 'RECONCILIATION_BINDING_CONFLICT');
     }
@@ -198,6 +233,11 @@ async function validateStoredBinding(args) {
     if (durableBindingError) {
         return durableBindingError;
     }
+    if (args.receipt.driftSource === 'declared-architectural-premise') {
+        // No validation-report.json exists for a declared drift; the durable binding
+        // check above already re-derives and verifies the receipt's bindingDigest.
+        return null;
+    }
     const reportPath = join(projectDataDir(args.projectId), 'handoffs', args.specId, 'validation-report.json');
     try {
         const reportBytes = await readFile(reportPath);
@@ -220,6 +260,11 @@ async function validateStoredBinding(args) {
 export async function readCommittedReconciliations(projectId, specId) {
     return readCommittedReconciliationReceipts(projectId, specId);
 }
+function extractDriftSource(validated) {
+    return 'driftSource' in validated && validated.driftSource === 'declared-architectural-premise'
+        ? validated.driftSource
+        : undefined;
+}
 function receiptMatchesRequest(receipt, projectId, specId, requestId) {
     return (receipt.projectId === projectId && receipt.specId === specId && receipt.requestId === requestId);
 }
@@ -315,6 +360,7 @@ export async function reconcileImplementingSpec(args) {
             typeof validated.reviewDigest !== 'string') {
             return validated;
         }
+        const driftSource = extractDriftSource(validated);
         const expectedTransitionId = args.input.expectedImplementingTransitionId;
         const reason = args.input.reason;
         if (!expectedTransitionId || !reason) {
@@ -338,6 +384,7 @@ export async function reconcileImplementingSpec(args) {
                     stateHistory: [{ state: 'prepared', at: preparedAt }],
                     preparedAt,
                     phase: 'prepared',
+                    ...(driftSource ? { driftSource } : {}),
                 };
             })();
         if (!existing) {

package/dist/engine/next-spec-resolver/orchestration-planner.js

@@ -196,7 +196,7 @@ function normalizeLegacyTier(value) {
 }
 async function readPlanVersion(projectPath) {
     try {
-        const raw = await readFile(join(projectPath, 'planu', 'session.json'), 'utf-8');
+        const raw = await readFile(join(projectPath, 'planu', '.runtime', 'session.json'), 'utf-8');
         const index = JSON.parse(raw);
         return index.orchestrationPlan?.planVersion ?? 0;
     }

package/dist/engine/next-spec-resolver/session-writer.js

@@ -68,7 +68,7 @@ export async function writeOrchestrationPlan(projectPath, plan) {
  */
 export async function patchSessionJson(projectPath, patch) {
     try {
-        const filePath = join(projectPath, 'planu', 'session.json');
+        const filePath = join(projectPath, 'planu', '.runtime', 'session.json');
         let existingContent = null;
         let current = { activeSpecs: [], updatedAt: '' };
         try {

package/dist/engine/project-graph/cache.js

@@ -8,6 +8,8 @@ import { setTimeout as delay } from 'node:timers/promises';
 import { fileURLToPath } from 'node:url';
 // eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { projectDataDir, readJson, writeJson } from '../../storage/base-store.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
+import { enforceRetention } from '../../storage/retention.js';
 import { LockBusyError, withSpecLock } from '../safety/cross-process-lock.js';
 const POLICY_PATH = join(dirname(fileURLToPath(import.meta.url)), '../../config/project-knowledge-graph.json');
 const CACHE_VERSION = 2;
@@ -200,7 +202,13 @@ export async function readProjectGraph(projectId, policy) {
     return null;
 }
 export async function writeProjectGraph(projectId, policy, graph) {
-    await writeJson(projectGraphPath(projectId, policy), graph);
+    const graphPath = projectGraphPath(projectId, policy);
+    await writeJson(graphPath, graph);
+    await enforceRetention({
+        kind: 'graph-cache',
+        path: projectGraphDir(projectId, policy),
+        protectedPaths: [graphPath],
+    });
 }
 export async function readProjectGraphSourceHashes(projectId, policy) {
     const active = activeBuilds.get(projectGraphDir(projectId, policy));
@@ -217,6 +225,11 @@ export async function writeProjectGraphSourceHashes(projectId, policy, hashes) {
         records: hashes,
         fragments: current.cache?.fragments ?? {},
     });
+    await enforceRetention({
+        kind: 'graph-cache',
+        path: projectGraphDir(projectId, policy),
+        protectedPaths: [projectGraphCachePath(projectId, policy)],
+    });
 }
 export async function writeProjectGraphArtifacts(args) {
     if (args.graph.generation.length === 0 ||
@@ -225,8 +238,15 @@ export async function writeProjectGraphArtifacts(args) {
         throw new Error('[Planu] Project graph/cache generation mismatch');
     }
     // Readers verify the shared generation, so neither write order can expose a mixed snapshot.
-    await writeJson(projectGraphCachePath(args.projectId, args.policy), args.cache);
-    await writeJson(projectGraphPath(args.projectId, args.policy), args.graph);
+    const cachePath = projectGraphCachePath(args.projectId, args.policy);
+    const graphPath = projectGraphPath(args.projectId, args.policy);
+    await writeJson(cachePath, args.cache);
+    await writeJson(graphPath, args.graph);
+    await enforceRetention({
+        kind: 'graph-cache',
+        path: projectGraphDir(args.projectId, args.policy),
+        protectedPaths: [cachePath, graphPath],
+    });
 }
 export async function withProjectGraphBuildLock(projectId, policy, task) {
     const key = projectGraphDir(projectId, policy);

package/dist/engine/readiness-checker.js

@@ -10,6 +10,7 @@ import { findScenariosWithoutTests, parseFrontmatterScenarios, } from './validat
 import { normalizeExecutableEvidence } from './validator/executable-evidence.js';
 import { evaluateImplementationContract } from './implementation-contract/index.js';
 import { extractNormalizedAcceptanceCriteria } from './spec-format/acceptance-criteria.js';
+import { detectCrossSpecPremiseContradictions } from './contradiction-detector.js';
 // ── SPEC-784: Technical section quality constants ─────────────────────────────
 const TECHNICAL_MIN_CHARS = 500;
 // Detects "See technical.md", "See spec.md", or "See `<file>` technical.md" patterns
@@ -428,7 +429,7 @@ export async function checkSpecReadiness(spec, mode, projectHash) {
     if (bddScenarioCount > 0) {
         const scenariosWithoutTests = findScenariosWithoutTests(huRaw);
         for (const title of scenariosWithoutTests) {
-            allBlockers.push(`scenarios_missing_tests: scenario "${title}" has no tests array — add tests entries (SPEC-732)`);
+            allBlockers.push(`scenarios_missing_tests: scenario "${title}" has no tests array — add tests entries as a block list (tests: with one "- path" line per test) or an inline array (tests: ["path"]) (SPEC-732)`);
         }
     }
     // SPEC-1214: BDD-criteria executable-evidence gate — when a spec has no frontmatter
@@ -454,7 +455,18 @@ export async function checkSpecReadiness(spec, mode, projectHash) {
     // concrete file paths, function names, or anticipated test breaks.
     const specificityBlockers = checkSpecificityGate(spec, specificityEvidenceLines, fichaContent, anticipatedTestBreaksContent);
     allBlockers.push(...specificityBlockers);
-    const effectiveScore = specificityBlockers.length > 0 && spec.difficulty >= 3 ? Math.min(totalScore, 60) : totalScore;
+    const scoreAfterSpecificityGate = specificityBlockers.length > 0 && spec.difficulty >= 3 ? Math.min(totalScore, 60) : totalScore;
+    // SPEC-1702: strict mode cross-checks premise claims about done/approved sibling
+    // specs against those siblings' own contracts and caps the score below 100.
+    const crossSpecPremiseFindings = mode === 'strict'
+        ? await detectCrossSpecPremiseContradictions(spec.id, huRaw, projectPathFromSpecPath(spec.specPath))
+        : [];
+    for (const finding of crossSpecPremiseFindings) {
+        allBlockers.push(`cross-spec-premise: ${finding.targetSpecId} claims "${finding.targetSentence}" but ${finding.siblingSpecId} states "${finding.siblingSentence}" (shared file: ${finding.sharedFilePath})`);
+    }
+    const effectiveScore = crossSpecPremiseFindings.length > 0
+        ? Math.min(scoreAfterSpecificityGate, 90)
+        : scoreAfterSpecificityGate;
     const breakdown = {
         hu: hu.points,
         criteria: criteria.points,

package/dist/engine/sdd-flow/checkpoints.js

@@ -2,12 +2,28 @@
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1699
+import { projectRuntimeDir } from '../../storage/storage-layout.js';
+const RUN_ID_PATTERN = /^[A-Za-z0-9_-]+$/;
+function assertValidRunId(runId) {
+    if (!RUN_ID_PATTERN.test(runId)) {
+        throw new Error(`Invalid runId: "${runId}". Run IDs must match ${RUN_ID_PATTERN.source} (no path separators).`);
+    }
+}
 function getStateDir(projectPath) {
+    return projectRuntimeDir(projectPath, 'state');
+}
+function getLegacyStateDir(projectPath) {
     return join(projectPath, 'planu', 'state');
 }
 function getStatePath(projectPath, runId) {
+    assertValidRunId(runId);
     return join(getStateDir(projectPath), `sdd-flow-${runId}.json`);
 }
+function getLegacyStatePath(projectPath, runId) {
+    assertValidRunId(runId);
+    return join(getLegacyStateDir(projectPath), `sdd-flow-${runId}.json`);
+}
 export async function saveCheckpoint(projectPath, state) {
     const dir = getStateDir(projectPath);
     if (!existsSync(dir)) {
@@ -18,11 +34,22 @@ export async function saveCheckpoint(projectPath, state) {
 }
 export async function loadCheckpoint(projectPath, runId) {
     const path = getStatePath(projectPath, runId);
-    if (!existsSync(path)) {
+    if (existsSync(path)) {
+        try {
+            const raw = await readFile(path, 'utf-8');
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    // SPEC-1695: one-time legacy fallback for runs persisted before the relocation.
+    const legacyPath = getLegacyStatePath(projectPath, runId);
+    if (!existsSync(legacyPath)) {
         return null;
     }
     try {
-        const raw = await readFile(path, 'utf-8');
+        const raw = await readFile(legacyPath, 'utf-8');
         return JSON.parse(raw);
     }
     catch {

package/dist/engine/session/checkpoint-writer.d.ts

@@ -4,7 +4,7 @@ export declare function buildCheckpointBlock(snapshot: AutoSessionSnapshot): str
 /** Remove old checkpoint sections and prepend the new one to keep the file small. */
 export declare function replaceLatestCheckpoint(existing: string, newBlock: string): string;
 /**
- * Write a compact checkpoint to `<projectPath>/planu/session-context.md`.
+ * Write a compact checkpoint to `<projectPath>/planu/.runtime/session-context.md`.
  * Replaces any previous checkpoint section — idempotent.
  * May throw — callers should catch or use maybeWriteCheckpoint.
  */

package/dist/engine/session/checkpoint-writer.js

@@ -1,5 +1,6 @@
 // engine/session/checkpoint-writer.ts — Writes a compact session checkpoint to
-// planu/session-context.md (SPEC-563). Fire-and-forget safe — never throws to caller.
+// planu/.runtime/session-context.md (SPEC-563, relocated under SPEC-1699).
+// Fire-and-forget safe — never throws to caller.
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { sessionTracker } from './session-tracker.js';
@@ -56,13 +57,13 @@ export function replaceLatestCheckpoint(existing, newBlock) {
     return `${newBlock}\n${trimmed}`.trimEnd() + '\n';
 }
 /**
- * Write a compact checkpoint to `<projectPath>/planu/session-context.md`.
+ * Write a compact checkpoint to `<projectPath>/planu/.runtime/session-context.md`.
  * Replaces any previous checkpoint section — idempotent.
  * May throw — callers should catch or use maybeWriteCheckpoint.
  */
 export async function writeCheckpoint(projectPath, snapshot) {
-    const planuDir = join(projectPath, 'planu');
-    const filePath = join(planuDir, 'session-context.md');
+    const runtimeDir = join(projectPath, 'planu', '.runtime');
+    const filePath = join(runtimeDir, 'session-context.md');
     let existing = '';
     try {
         existing = await readFile(filePath, 'utf8');
@@ -72,7 +73,7 @@ export async function writeCheckpoint(projectPath, snapshot) {
     }
     const newBlock = buildCheckpointBlock(snapshot);
     const updated = replaceLatestCheckpoint(existing, newBlock);
-    await mkdir(planuDir, { recursive: true });
+    await mkdir(runtimeDir, { recursive: true });
     await writeFile(filePath, updated, 'utf8');
 }
 /**

package/dist/engine/session-state/writer.js

@@ -4,16 +4,17 @@ import { readFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { execSync } from 'node:child_process';
 import { stableJsonStringify, stableWriteGeneratedFile, stripRootUpdatedAt, } from '../generated-artifact-writer.js';
-const STATE_DIR = 'state';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1699
+import { projectRuntimeDir } from '../../storage/storage-layout.js';
 const ROOT_SESSION = 'session.json';
 function stateDir(projectPath) {
-    return join(projectPath, 'planu', STATE_DIR);
+    return projectRuntimeDir(projectPath, 'state');
 }
 function specFile(projectPath, specId) {
     return join(stateDir(projectPath), `session-${specId}.json`);
 }
 export function rootFile(projectPath) {
-    return join(projectPath, 'planu', ROOT_SESSION);
+    return join(projectPath, 'planu', '.runtime', ROOT_SESSION);
 }
 function getModifiedFiles(projectPath) {
     try {

package/dist/engine/spec-format/lean-spec-generator.js

@@ -166,7 +166,7 @@ function extractCheckboxCriteria(description) {
 function extractGivenWhenThenCriteria(description) {
     const criteria = [];
     // Single-line: GIVEN ... WHEN ... THEN ...
-    const singleLineRegex = /^[ \t]*(?:[-*>]\s*)?GIVEN\s+.+\s+WHEN\s+.+\s+THEN\s+(.+)$/gim;
+    const singleLineRegex = /^[ \t]*(?:[-*>]\s*|\d+[.)]\s*)?GIVEN\s+.+\s+WHEN\s+.+\s+THEN\s+(.+)$/gim;
     let match = singleLineRegex.exec(description);
     while (match) {
         const thenText = match[1]?.trim() ?? '';

package/dist/engine/spec-migrator/planu-canonical-policy.d.ts

@@ -5,6 +5,13 @@ export declare function isCanonicalPlanuRootDir(name: string): boolean;
 export declare function isCanonicalSpecFile(name: string): boolean;
 export declare function isCanonicalSpecDir(name: string): boolean;
 export declare function mustMergeBeforeDeleteSpecFile(name: string): boolean;
-export declare function isCanonicalReleaseFile(relativeToPlanu: string): boolean;
+/**
+ * Legacy-transition carve-out ONLY: strict-planu-cleanup.ts still walks a
+ * not-yet-migrated planu/releases/ directory and must not delete
+ * pending.json before the migration folds it into project.json's
+ * `releases` field. This is not part of the canonical contract — see
+ * canonicalContractText().
+ */
+export declare function isLegacyReleasePendingFile(relativeToPlanu: string): boolean;
 export declare function canonicalContractText(): string;
 //# sourceMappingURL=planu-canonical-policy.d.ts.map

package/dist/engine/spec-migrator/planu-canonical-policy.js

@@ -14,18 +14,12 @@ const LEGACY_CONTENT_BEARING_PATTERNS = legacyArtifactRulesLoader
     .filter((rule) => rule.classification === 'content-bearing')
     .map((rule) => rule.pattern);
 export const PLANU_CANONICAL_POLICY = {
-    canonicalRootFiles: [
-        'conventions.json',
-        'context.md',
-        'project.json',
-        'session-context.md',
-        'session.json',
-        'technology-selection.json',
-    ],
-    canonicalRootDirs: ['releases', 'specs'],
+    canonicalRootFiles: ['project.json'],
+    canonicalRootDirs: ['specs'],
     canonicalSpecFiles: ['spec.md'],
     canonicalSpecDirs: [],
     forbiddenHostAssetRootDirs: ['agents', 'skills', 'rules', 'hooks'],
+    runtimeHomeDir: 'planu/.runtime/',
     generatedRuntimePatterns: [
         'planu/index.html',
         'planu/roadmap.html',
@@ -36,6 +30,7 @@ export const PLANU_CANONICAL_POLICY = {
         'planu/handoffs/',
         'planu/data/',
         'planu/state/',
+        'planu/reports/',
         'planu/.locks/',
         'planu/specs/data/',
         'planu/specs/*/technical-report.html',
@@ -68,7 +63,14 @@ export function isCanonicalSpecDir(name) {
 export function mustMergeBeforeDeleteSpecFile(name) {
     return LEGACY_MERGE_SET.has(name);
 }
-export function isCanonicalReleaseFile(relativeToPlanu) {
+/**
+ * Legacy-transition carve-out ONLY: strict-planu-cleanup.ts still walks a
+ * not-yet-migrated planu/releases/ directory and must not delete
+ * pending.json before the migration folds it into project.json's
+ * `releases` field. This is not part of the canonical contract — see
+ * canonicalContractText().
+ */
+export function isLegacyReleasePendingFile(relativeToPlanu) {
     return relativeToPlanu === 'releases/pending.json';
 }
 export function canonicalContractText() {
@@ -76,15 +78,14 @@ export function canonicalContractText() {
         'planu/',
         '  conventions.json',
         '  context.md',
-        '  project.json',
+        '  project.json (pending release records live in its `releases` field)',
         '  session-context.md',
         '  session.json',
         '  technology-selection.json',
-        '  releases/',
-        '    pending.json',
         '  specs/',
         '    SPEC-XXX-slug/',
         '      spec.md',
+        '  .runtime/ (generated runtime home — session/index data, not committed)',
         '',
         'Evidence artifacts are Planu runtime data and are stored outside planu/specs/.',
         '',

package/dist/engine/spec-migrator/strict-planu-cleanup.js

@@ -8,8 +8,21 @@ import { dirname, isAbsolute, join, relative } from 'node:path';
 import { atomicWriteFile } from '../safety/atomic-write-file.js';
 import { safeUnlink } from './git-aware-fs.js';
 import { scanLegacyArtifacts } from './legacy-classifier.js';
-import { PLANU_CANONICAL_POLICY, canonicalContractText, isCanonicalPlanuRootDir, isCanonicalPlanuRootFile, isCanonicalReleaseFile, isCanonicalSpecDir, isCanonicalSpecFile, mustMergeBeforeDeleteSpecFile, } from './planu-canonical-policy.js';
+import { PLANU_CANONICAL_POLICY, canonicalContractText, isCanonicalPlanuRootDir, isCanonicalPlanuRootFile, isLegacyReleasePendingFile, isCanonicalSpecDir, isCanonicalSpecFile, mustMergeBeforeDeleteSpecFile, } from './planu-canonical-policy.js';
 const execFileAsync = promisify(execFile);
+// SPEC-1699: legacy planu/ root files folded into project.json by init_project's
+// migration. Destructive cleanup must never delete them outright — only the
+// migration step, which reads their content first, may retire them.
+const PENDING_ROOT_MIGRATION_FILES = new Set([
+    'conventions.json',
+    'context.md',
+    'session-context.md',
+    'session.json',
+    'technology-selection.json',
+]);
+function isPendingRootMigrationFile(entry) {
+    return PENDING_ROOT_MIGRATION_FILES.has(entry);
+}
 async function pathIsDirectory(path) {
     try {
         return (await stat(path)).isDirectory();
@@ -176,11 +189,23 @@ export async function runStrictPlanuCleanup(projectPath, authority = { mode: 're
     for (const entry of entries) {
         const full = join(planuDir, entry);
         const isDir = await pathIsDirectory(full);
+        if (isDir && entry === 'releases') {
+            // SPEC-1699: 'releases' is no longer a canonical root dir, but its
+            // pending.json still needs the dedicated fold-into-project.json
+            // migration below before its directory can be removed.
+            continue;
+        }
         if (isDir && !isCanonicalPlanuRootDir(entry)) {
             await removePath(projectPath, full);
             result.deleted.push(relative(projectPath, full));
             continue;
         }
+        if (!isDir && isPendingRootMigrationFile(entry)) {
+            // SPEC-1699: content-bearing legacy root file — init_project's migration
+            // folds it into project.json before this cleanup may delete it.
+            result.proposed.push(relative(projectPath, full));
+            continue;
+        }
         if (!isDir && !isCanonicalPlanuRootFile(entry)) {
             await removePath(projectPath, full);
             result.deleted.push(relative(projectPath, full));
@@ -189,7 +214,7 @@ export async function runStrictPlanuCleanup(projectPath, authority = { mode: 're
     const releasesDir = join(planuDir, 'releases');
     for (const entry of await readDirectory(releasesDir)) {
         const rel = `releases/${entry}`;
-        if (!isCanonicalReleaseFile(rel)) {
+        if (!isLegacyReleasePendingFile(rel)) {
             const full = join(releasesDir, entry);
             await removePath(projectPath, full);
             result.deleted.push(relative(projectPath, full));
@@ -235,7 +260,7 @@ export async function validateStrictPlanuLayout(projectPath, options = {}) {
         }
         for (const entry of await readDirectory(join(planuDir, 'releases'))) {
             const rel = `releases/${entry}`;
-            if (!isCanonicalReleaseFile(rel)) {
+            if (!isLegacyReleasePendingFile(rel)) {
                 offenders.push(`planu/${rel}`);
             }
         }

package/dist/engine/telemetry/error-reporter.d.ts

@@ -8,20 +8,20 @@ export declare function isErrorReportingEnabled(): boolean;
  */
 export declare function sanitizeErrorMessage(message: string): string;
 /**
- * Classifies a telemetry event as tool_blocked or tool_error.
- * Gate blocks (DoD, validate score, spec locked, invalid transition) → tool_blocked.
- * Unhandled exceptions → tool_error.
+ * Classifies a telemetry event as blocked or error, mapping onto the envelope's `result` field.
+ * Gate blocks (DoD, validate score, spec locked, invalid transition) → blocked.
+ * Unhandled exceptions → error.
  */
-export declare function classifyToolEvent(errorMessage: string, errorType?: string): 'tool_error' | 'tool_blocked';
+export declare function classifyToolEvent(errorMessage: string, errorType?: string): 'error' | 'blocked';
 /**
- * Sends a tool_error event to Supabase. Fire-and-forget — never throws.
+ * Emits an mcp_tool_failed envelope for an unhandled exception. Fire-and-forget — never throws.
+ * The envelope has no message field in Phase 1, so no error text is ever transmitted.
  * Call this from safe-handler catch blocks after returning isError:true to the user.
  */
-export declare function reportToolError(toolName: string, error: unknown): void;
+export declare function reportToolError(toolName: string, _error: unknown): void;
 /**
- * Sends a tool_error or tool_blocked event for business-logic validation failures.
- * Gate/policy blocks (DoD, spec locked, invalid transitions) emit tool_blocked.
- * Other expected errors (missing params, not-found, etc.) emit tool_error.
+ * Emits an mcp_tool_failed envelope for a business-logic validation failure, classifying
+ * `result` as blocked (gate/policy blocks) or error (other expected failures).
  * Fire-and-forget — never throws.
  */
 export declare function reportToolValidationError(toolName: string, message: string): void;