@planu/cli 4.7.3 → 4.7.5

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+## [4.7.5] - 2026-06-24
+
+### Features
+- feat: add Planu minimal-change rule and guidance inspired by Ponytail
+
+### Bug Fixes
+- fix: keep generated Planu session artifacts stable after lifecycle close
+
+### Chores
+- chore(deps): refresh push-gate dev dependency knip
+
+
+## [4.7.4] - 2026-06-23
+
+### Bug Fixes
+- fix: implement SPEC-1091-1094 tech debt bundle
+
+### Chores
+- chore(deps): refresh push-gate dev dependencies
+
+
 ## [4.7.3] - 2026-06-19
 
 ### Features
@@ -4103,4 +4124,4 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) · Versioning:
 - Mermaid diagram generation (architecture, sequence, state machine, ER, data flow)
 - Multi-language i18n (EN/ES/PT) for generated specs
 - Clean Architecture (hexagonal) — engine, tools, storage, types layers
-- 10,857 tests with ≥95% coverage
+- 10,857 tests with ≥95% coverage

package/README.md

@@ -3,7 +3,7 @@
 **The high-performance SDD stack for AI coding agents.**
 
 [![npm version](https://img.shields.io/npm/v/@planu/cli?color=blue&label=npm)](https://www.npmjs.com/package/@planu/cli)
-![Node](https://img.shields.io/badge/node-%3E%3D22.0.0-green)
+![Node](https://img.shields.io/badge/node-%3E%3D24.0.0-green)
 ![Rust](https://img.shields.io/badge/core-rust-orange)
 ![License](https://img.shields.io/badge/license-MIT-blue)
 
@@ -41,7 +41,7 @@ Add to your MCP client config (Claude Desktop: `~/Library/Application Support/Cl
 }
 ```
 
-**Requirements:** Node.js >= 22. The native Rust core is bundled and auto-detected for macOS (Intel/M1), Linux, and Windows.
+**Requirements:** Node.js >= 24. The native Rust core is bundled and auto-detected for macOS (Intel/M1), Linux, and Windows.
 
 ---
 
@@ -112,7 +112,10 @@ data/                 # Local storage (gitignored)
 pnpm install       # Install dependencies
 pnpm build         # Compile TS + Build Rust bridge
 pnpm dev           # Watch mode
-pnpm test          # Run 31,000+ tests
+pnpm validate      # Canonical local validation contract
+pnpm check:strict  # Extended local quality gates
+pnpm test          # Run the full test suite
+pnpm release:local # Local-first release flow when shipping
 ```
 
 ---

package/dist/config/minimal-implementation-gate.json

@@ -31,7 +31,7 @@
       "tag": "stdlib",
       "severity": "warning",
       "confidence": "medium",
-      "patterns": ["custom parser", "manual parser", "hand rolled parser"],
+      "patterns": ["custom parser", "manual parser", "hand rolled parser", "hand-rolled stdlib"],
       "replacementGuidance": "Use an existing parser from the runtime or current dependency set before writing parsing code."
     },
     {
@@ -39,7 +39,7 @@
       "tag": "native",
       "severity": "warning",
       "confidence": "high",
-      "patterns": ["new public mcp tool", "new command", "new cli command"],
+      "patterns": ["new public mcp tool", "new command", "new cli command", "native platform feature"],
       "replacementGuidance": "Prefer existing Planu SDD surfaces unless the spec proves a new public surface is required."
     },
     {
@@ -55,7 +55,7 @@
       "tag": "yagni",
       "severity": "blocker",
       "confidence": "high",
-      "patterns": ["future-proof", "just in case", "might need later", "eventually support"],
+      "patterns": ["future-proof", "just in case", "might need later", "eventually support", "speculative config"],
       "replacementGuidance": "Remove speculative scope unless it is directly required by an acceptance criterion.",
       "blockWhenRiskAtLeast": "medium"
     },
@@ -64,7 +64,15 @@
       "tag": "shrink",
       "severity": "warning",
       "confidence": "medium",
-      "patterns": ["framework", "orchestration layer", "plugin architecture", "abstract factory"],
+      "patterns": [
+        "framework",
+        "orchestration layer",
+        "plugin architecture",
+        "abstract factory",
+        "wrapper that only delegates",
+        "delegate-only wrapper",
+        "shrinkable logic"
+      ],
       "replacementGuidance": "Shrink the design to the smallest correct module/function that satisfies the spec."
     },
     {

package/dist/engine/cascade-hooks/core/append-releases.d.ts

@@ -1,3 +1,4 @@
-import type { CascadeContext, CoreActionResult } from '../../../types/cascade-hooks.js';
+import type { CascadeContext, CoreActionResult, PendingReleaseEntry } from '../../../types/cascade-hooks.js';
+export declare function normalizePendingReleaseEntries(value: unknown, now?: Date): PendingReleaseEntry[];
 export declare function appendReleasesPending(ctx: CascadeContext): Promise<CoreActionResult>;
 //# sourceMappingURL=append-releases.d.ts.map

package/dist/engine/cascade-hooks/core/append-releases.js

@@ -5,6 +5,35 @@ import { join } from 'node:path';
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { specStore } from '../../../storage/index.js';
 const CORE_ACTION_BUDGET_MS = 2000;
+const PENDING_ENTRY_MAX_AGE_DAYS = 30;
+function isValidPendingReleaseEntry(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.specId === 'string' &&
+        typeof value.title === 'string' &&
+        typeof value.completedAt === 'string');
+}
+function isRecentPendingEntry(entry, now = new Date()) {
+    const completedAt = new Date(entry.completedAt);
+    if (Number.isNaN(completedAt.getTime())) {
+        return false;
+    }
+    const ageMs = now.getTime() - completedAt.getTime();
+    return ageMs <= PENDING_ENTRY_MAX_AGE_DAYS * 24 * 60 * 60 * 1000;
+}
+export function normalizePendingReleaseEntries(value, now = new Date()) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    const deduped = new Map();
+    for (const entry of value) {
+        if (!isValidPendingReleaseEntry(entry) || !isRecentPendingEntry(entry, now)) {
+            continue;
+        }
+        deduped.set(entry.specId, entry);
+    }
+    return [...deduped.values()];
+}
 async function actuallyAppendReleasesPending(ctx, opts) {
     const { projectPath, projectId, specId } = ctx;
     if (!projectPath || ctx.newStatus !== 'done') {
@@ -26,9 +55,7 @@ async function actuallyAppendReleasesPending(ctx, opts) {
             try {
                 const raw = await readFile(pendingPath, 'utf-8');
                 const parsed = JSON.parse(raw);
-                if (Array.isArray(parsed)) {
-                    pendingList = parsed;
-                }
+                pendingList = normalizePendingReleaseEntries(parsed);
             }
             catch {
                 /* file doesn't exist yet — start fresh */

package/dist/engine/context-md-generator.js

@@ -1,8 +1,9 @@
 // engine/context-md-generator.ts — SPEC-635: Live ≤800-token context briefing for any LLM
-import { writeFile, mkdir, readFile } from 'node:fs/promises';
+import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { specStore } from '../storage/index.js';
 import { stripFrontmatter } from './frontmatter-parser.js';
+import { stableWriteGeneratedFile, stripSessionMarkdownVolatileFields, } from './generated-artifact-writer.js';
 const MAX_TOKENS = 800;
 const CHARS_PER_TOKEN = 4; // rough estimate
 const MAX_CHARS = MAX_TOKENS * CHARS_PER_TOKEN;
@@ -92,9 +93,9 @@ export async function generateContextMd(projectPath, projectId) {
             }
         }
         const content = truncate(lines.join('\n'), MAX_CHARS);
-        const planuDir = join(projectPath, 'planu');
-        await mkdir(planuDir, { recursive: true });
-        await writeFile(join(planuDir, 'context.md'), content + '\n', 'utf-8');
+        await stableWriteGeneratedFile(join(projectPath, 'planu', 'context.md'), content, {
+            equivalence: stripSessionMarkdownVolatileFields,
+        });
     }
     catch {
         /* best-effort — never blocks status transition */

package/dist/engine/evidence-gates/artifact-reader.js

@@ -49,6 +49,19 @@ const ContractValidationSchema = z.object({
     reportPath: z.string().optional(),
     summary: z.string().optional(),
 });
+const ARTIFACT_HINTS = {
+    'Discovery evidence': 'Expected discovery.json with { version: 1, rules: string[], examples: [{ rule, example }], openQuestions: [{ question, status, resolution? }], outOfScope: string[], glossary: [{ term, meaning }] }.',
+    'Task plan evidence': 'Expected task-plan.json with { version: 1, tasks: [{ id, title, acceptanceCriteria: string[], status: "pending"|"doing"|"done" }] }. Acceptance criteria may be full text or stable IDs such as AC1 when they map to the canonical criteria order.',
+    'Traceability matrix evidence': 'Expected traceability-matrix.json with { version: 1, rows: [{ acceptanceCriterion, scenario?, testEvidence?, contractEvidence?, manualEvidence?, changedFiles: string[], validationEvidence?, reviewerEvidence? }] }.',
+    'contract-validation-api.json': 'Expected filename contract-validation-api.json with { version: 1, kind: "api", passed: boolean, reportPath?, summary? }.',
+    'contract-validation-graphql.json': 'Expected filename contract-validation-graphql.json with { version: 1, kind: "graphql", passed: boolean, reportPath?, summary? }.',
+    'contract-validation-event.json': 'Expected filename contract-validation-event.json with { version: 1, kind: "event", passed: boolean, reportPath?, summary? }.',
+    'contract-validation-ui.json': 'Expected filename contract-validation-ui.json with { version: 1, kind: "ui", passed: boolean, reportPath?, summary? }.',
+    'contract-validation-mcp.json': 'Expected filename contract-validation-mcp.json with { version: 1, kind: "mcp", passed: boolean, reportPath?, summary? }.',
+};
+function artifactHint(label) {
+    return ARTIFACT_HINTS[label] ?? '';
+}
 function handoffEvidencePath(projectId, specId, filename) {
     return join(projectDataDir(projectId), 'handoffs', specId, filename);
 }
@@ -78,13 +91,13 @@ async function readOptional(args) {
         }
         const parsed = args.schema.safeParse(found.value);
         if (!parsed.success) {
-            args.invalidArtifacts.push(`${args.label} is invalid at ${found.path}: ${parsed.error.issues.map((issue) => issue.message).join('; ')}`);
+            args.invalidArtifacts.push(`${args.label} is invalid at ${found.path}: ${parsed.error.issues.map((issue) => issue.message).join('; ')} ${artifactHint(args.label)}`.trim());
             return undefined;
         }
         return parsed.data;
     }
     catch (err) {
-        args.invalidArtifacts.push(`${args.label} is unreadable: ${err instanceof Error ? err.message : String(err)}`);
+        args.invalidArtifacts.push(`${args.label} is unreadable: ${err instanceof Error ? err.message : String(err)} ${artifactHint(args.label)}`.trim());
         return undefined;
     }
 }

package/dist/engine/evidence-gates/lifecycle-gate.js

@@ -11,10 +11,22 @@ function isNonTrivial(spec) {
 function normalizeCriterion(value) {
     return value
         .replace(/^-\s*\[[ x]\]\s*/i, '')
+        .replace(/^(AC\d+)\s*[:.)-]?\s*/i, '')
         .replace(/\s+/g, ' ')
         .trim()
         .toLowerCase();
 }
+function criterionAliases(value, index) {
+    const aliases = new Set([
+        normalizeCriterion(value),
+        normalizeCriterion(`AC${String(index + 1)}`),
+    ]);
+    const explicit = /^(AC\d+)\b/i.exec(value)?.[1];
+    if (explicit) {
+        aliases.add(normalizeCriterion(explicit));
+    }
+    return [...aliases].filter((alias) => alias.length > 0);
+}
 function hasText(value) {
     return value !== undefined && value.trim().length > 0;
 }
@@ -62,7 +74,7 @@ export function checkTaskPlanGate(spec, criteria, artifacts) {
         ];
     }
     const covered = new Set(artifacts.taskPlan.tasks.flatMap((task) => task.acceptanceCriteria.map(normalizeCriterion)));
-    const uncovered = criteria.filter((criterion) => !covered.has(normalizeCriterion(criterion)));
+    const uncovered = criteria.filter((criterion, index) => !criterionAliases(criterion, index).some((alias) => covered.has(alias)));
     if (uncovered.length === 0) {
         return [];
     }
@@ -90,7 +102,7 @@ export function checkDoneEvidenceGate(spec, criteria, artifacts) {
     }
     else {
         const covered = new Set(matrix.rows.map((row) => normalizeCriterion(row.acceptanceCriterion)));
-        const uncovered = criteria.filter((criterion) => !covered.has(normalizeCriterion(criterion)));
+        const uncovered = criteria.filter((criterion, index) => !criterionAliases(criterion, index).some((alias) => covered.has(alias)));
         if (uncovered.length > 0) {
             issues.push({
                 code: 'traceability_uncovered_criteria',

package/dist/engine/generated-artifact-writer.d.ts

@@ -0,0 +1,7 @@
+import type { StableWriteOptions, StableWriteResult } from '../types/generated-artifacts.js';
+export declare function withFinalNewline(content: string): string;
+export declare function stripSessionMarkdownVolatileFields(content: string): string;
+export declare function stableJsonStringify(value: unknown): string;
+export declare function stripRootUpdatedAt(content: string): string;
+export declare function stableWriteGeneratedFile(filePath: string, content: string, options?: StableWriteOptions): Promise<StableWriteResult>;
+//# sourceMappingURL=generated-artifact-writer.d.ts.map

package/dist/engine/generated-artifact-writer.js

@@ -0,0 +1,63 @@
+// engine/generated-artifact-writer.ts — stable writes for generated Planu artifacts.
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+export function withFinalNewline(content) {
+    return content.replace(/\s*$/u, '\n');
+}
+export function stripSessionMarkdownVolatileFields(content) {
+    return withFinalNewline(content)
+        .replace(/^# Planu Context — \d{4}-\d{2}-\d{2}$/mu, '# Planu Context — <date>')
+        .replace(/^> Last updated: .+$/mu, '> Last updated: <timestamp>');
+}
+export function stableJsonStringify(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+export function stripRootUpdatedAt(content) {
+    try {
+        const parsed = JSON.parse(content);
+        if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            const clone = { ...parsed };
+            delete clone.updatedAt;
+            return stableJsonStringify(clone);
+        }
+    }
+    catch {
+        // Fall back to exact normalized text comparison for invalid existing JSON.
+    }
+    return withFinalNewline(content);
+}
+export async function stableWriteGeneratedFile(filePath, content, options = {}) {
+    const next = withFinalNewline(content);
+    let existing;
+    if (options.existingContent !== undefined) {
+        if (options.existingContent === null) {
+            await mkdir(dirname(filePath), { recursive: true });
+            await writeFile(filePath, next, 'utf-8');
+            return { written: true, reason: 'missing' };
+        }
+        existing = options.existingContent;
+    }
+    else {
+        try {
+            existing = await readFile(filePath, 'utf-8');
+        }
+        catch {
+            await mkdir(dirname(filePath), { recursive: true });
+            await writeFile(filePath, next, 'utf-8');
+            return { written: true, reason: 'missing' };
+        }
+    }
+    if (existing === next) {
+        return { written: false, reason: 'unchanged' };
+    }
+    const existingHasStableNewline = existing.endsWith('\n') && !existing.endsWith('\n\n');
+    const equivalent = options.equivalence !== undefined &&
+        options.equivalence(existing) === options.equivalence(next);
+    if (equivalent && existingHasStableNewline) {
+        return { written: false, reason: 'unchanged' };
+    }
+    await mkdir(dirname(filePath), { recursive: true });
+    await writeFile(filePath, next, 'utf-8');
+    return { written: true, reason: 'changed' };
+}
+//# sourceMappingURL=generated-artifact-writer.js.map

package/dist/engine/handoff-packager.js

@@ -4,19 +4,8 @@ import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { stripFrontmatter } from './frontmatter-parser.js';
 import { hashProjectPath, projectDataDir } from '../storage/base-store.js';
+import { extractAcceptanceCriteriaTexts } from './spec-format/acceptance-criteria.js';
 // ── Parsing helpers ──────────────────────────────────────────────────────────
-async function safeReadFile(path) {
-    if (!path) {
-        return '';
-    }
-    try {
-        const raw = await readFile(path, 'utf-8');
-        return stripFrontmatter(raw);
-    }
-    catch {
-        return '';
-    }
-}
 function extractObjective(huContent, spec) {
     if (!huContent) {
         return spec.title;
@@ -40,41 +29,6 @@ function extractObjective(huContent, spec) {
     }
     return spec.title;
 }
-function extractCriteria(huContent) {
-    if (!huContent) {
-        return [];
-    }
-    const bddBlocks = extractBddCriteria(huContent);
-    if (bddBlocks.length > 0) {
-        return bddBlocks;
-    }
-    return huContent
-        .split('\n')
-        .filter((line) => /^- \[[ x]\]/.test(line.trim()))
-        .map((line) => line.trim().replace(/^- \[[ x]\]\s*/, ''));
-}
-function extractBddCriteria(content) {
-    const criteria = [];
-    let current = [];
-    for (const rawLine of content.split('\n')) {
-        const trimmed = rawLine.trim().replace(/^-+\s*/, '');
-        if (/^(GIVEN|WHEN|THEN|AND)\b/i.test(trimmed)) {
-            if (/^GIVEN\b/i.test(trimmed) && current.length > 0) {
-                criteria.push(current.join(' / '));
-                current = [];
-            }
-            current.push(trimmed);
-        }
-        else if (current.length > 0 && trimmed === '') {
-            criteria.push(current.join(' / '));
-            current = [];
-        }
-    }
-    if (current.length > 0) {
-        criteria.push(current.join(' / '));
-    }
-    return criteria.filter((criterion) => /GIVEN\b/i.test(criterion) && /WHEN\b/i.test(criterion) && /THEN\b/i.test(criterion));
-}
 function extractFilesFromFicha(fichaContent) {
     if (!fichaContent) {
         return { toModify: [], toCreate: [] };
@@ -203,13 +157,16 @@ function buildConstraints(knowledge) {
 // ── Public API ───────────────────────────────────────────────────────────────
 export async function packageHandoff(spec, knowledge) {
     const warnings = [];
-    const huContent = await safeReadFile(spec.specPath);
+    const rawSpecContent = spec.specPath
+        ? await readFile(spec.specPath, 'utf-8').catch(() => '')
+        : '';
+    const huContent = rawSpecContent ? stripFrontmatter(rawSpecContent) : '';
     const fichaContent = huContent;
     if (!huContent) {
         warnings.push('spec.md not found — using minimal package. Run create_spec to generate it.');
     }
     const objective = extractObjective(huContent, spec);
-    const criteria = extractCriteria(huContent);
+    const criteria = extractAcceptanceCriteriaTexts(rawSpecContent);
     const parsedFiles = extractFilesFromFicha(fichaContent);
     const discoveredFiles = extractBacktickedFiles(`${huContent}\n${fichaContent}`);
     const toModify = parsedFiles.toModify.length > 0 ? parsedFiles.toModify : discoveredFiles;

package/dist/engine/implementation-contract/renderer.js

@@ -21,6 +21,9 @@ export function buildImplementationContractSection(input) {
         '### File-Level Work Plan',
         ...renderFilePlan(input.files),
         '',
+        '### Minimal Change Guidance',
+        ...renderMinimalChangeGuidance(),
+        '',
         '### Acceptance-To-Verification Map',
         ...criteria.map((criterion, index) => renderVerificationRow(criterion.text, index + 1, testFiles, verificationCommands)),
         '',
@@ -45,6 +48,13 @@ export function appendImplementationContractIfMissing(specBody, input) {
     }
     return `${specBody.trimEnd()}\n\n${buildImplementationContractSection(input)}`;
 }
+function renderMinimalChangeGuidance() {
+    return [
+        '- Before implementing, check whether the work is unnecessary, already exists in this codebase, is covered by stdlib, is covered by the native platform, or is covered by an already-installed dependency.',
+        '- Add new code only after those checks, and keep the diff to the minimum that satisfies the accepted criteria.',
+        '- Do not use minimality to remove security, trust-boundary validation, data-loss handling, accessibility, explicit requirements, or required validation.',
+    ];
+}
 function fallbackCriteria() {
     return [
         {

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

@@ -1,7 +1,8 @@
 // @crash-shield-ignore-file — config/cache reader for Planu-controlled JSON; writer is this codebase, shape guaranteed by build/seed.
 // engine/next-spec-resolver/session-writer.ts — SPEC-686: Best-effort session.json writer
-import { readFile, writeFile, mkdir } from 'node:fs/promises';
-import { join, dirname } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { stableJsonStringify, stableWriteGeneratedFile, stripRootUpdatedAt, } from '../generated-artifact-writer.js';
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -68,11 +69,11 @@ export async function writeOrchestrationPlan(projectPath, plan) {
 export async function patchSessionJson(projectPath, patch) {
     try {
         const filePath = join(projectPath, 'planu', 'session.json');
-        await mkdir(dirname(filePath), { recursive: true });
+        let existingContent = null;
         let current = { activeSpecs: [], updatedAt: '' };
         try {
-            const raw = await readFile(filePath, 'utf-8');
-            current = JSON.parse(raw);
+            existingContent = await readFile(filePath, 'utf-8');
+            current = JSON.parse(existingContent);
         }
         catch {
             /* start fresh */
@@ -82,7 +83,10 @@ export async function patchSessionJson(projectPath, patch) {
             ...patch,
             updatedAt: new Date().toISOString(),
         };
-        await writeFile(filePath, JSON.stringify(updated, null, 2), 'utf-8');
+        await stableWriteGeneratedFile(filePath, stableJsonStringify(updated), {
+            equivalence: stripRootUpdatedAt,
+            existingContent,
+        });
     }
     catch {
         /* best-effort — never throw */

package/dist/engine/readiness-checker.js

@@ -6,6 +6,7 @@ import { loadReadinessConfig } from './readiness-config-loader.js';
 import { runEarsGate } from './ears-gate.js';
 import { findScenariosWithoutTests, parseFrontmatterScenarios, } from './validator/spec-compliance-runner.js';
 import { evaluateImplementationContract } from './implementation-contract/index.js';
+import { extractNormalizedAcceptanceCriteria } from './spec-format/acceptance-criteria.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
@@ -344,7 +345,8 @@ function checkSpecificityGate(spec, criteriaLines, fichaContent) {
  */
 export function checkReadinessInternal(body) {
     const bodyContent = stripFrontmatter(body);
-    const criteriaLines = extractCriteriaLines(bodyContent);
+    const normalizedCriteria = extractNormalizedAcceptanceCriteria(body);
+    const criteriaLines = normalizedCriteria.map((criterion) => criterion.text);
     const scenarioCount = criteriaLines.length === 0 ? countFrontmatterScenarios(body) : 0;
     const criteriaCount = criteriaLines.length > 0 ? criteriaLines.length : scenarioCount;
     const config = loadReadinessConfig();
@@ -402,19 +404,23 @@ export async function checkSpecReadiness(spec, mode, projectHash) {
     const huRaw = await readHuRaw(spec);
     const huContent = stripFrontmatter(huRaw);
     const fichaContent = await readFichaContent(spec);
-    const criteriaLines = extractCriteriaLines(huContent);
+    const normalizedCriteria = extractNormalizedAcceptanceCriteria(huRaw);
+    const canonicalCriteriaLines = normalizedCriteria.map((criterion) => criterion.text);
+    const usesFrontmatterAsCanonical = normalizedCriteria.length > 0 &&
+        normalizedCriteria.every((criterion) => criterion.source === 'frontmatter');
     // When a spec uses BDD format, acceptance criteria are stored as `scenarios:` in
     // the YAML frontmatter (multi-line YAML that the simple KV parser cannot handle).
-    // If no criteria were found in the body, fall back to counting frontmatter scenarios.
-    const scenarioCriteria = criteriaLines.length === 0 ? frontmatterScenarioCriteria(huRaw) : [];
-    const effectiveCriteriaLines = scenarioCriteria.length > 0 ? scenarioCriteria : criteriaLines;
+    // When those scenarios are canonical, keep their linked tests in the readiness
+    // evidence model so specificity gates still see exact test paths and line refs.
+    const scenarioCriteria = usesFrontmatterAsCanonical ? frontmatterScenarioCriteria(huRaw) : [];
+    const effectiveCriteriaLines = scenarioCriteria.length > 0 ? scenarioCriteria : canonicalCriteriaLines;
     const hu = scoreHuCompleteness(spec);
     const criteria = scoreCriteria(effectiveCriteriaLines, vagueWords);
     const files = scoreFilesIdentified(spec, fichaContent);
     const deps = scoreDependencies(spec);
     const totalScore = hu.points + criteria.points + files.points + deps.points;
     // SPEC-631: EARS gate — hard-block for vague modal verbs ("should/may/could/might") in criteria
-    const earsBlockers = runEarsGate(criteriaLines);
+    const earsBlockers = runEarsGate(effectiveCriteriaLines);
     const allBlockers = [
         ...hu.blockers,
         ...criteria.blockers,
@@ -424,7 +430,7 @@ export async function checkSpecReadiness(spec, mode, projectHash) {
     ];
     const allWarnings = [...hu.warnings, ...criteria.warnings, ...files.warnings, ...deps.warnings];
     if (mode === 'strict' && spec.scope !== 'trivial' && spec.difficulty >= 3) {
-        for (const issue of evaluateImplementationContract(huContent, effectiveCriteriaLines)) {
+        for (const issue of evaluateImplementationContract(huContent, canonicalCriteriaLines)) {
             allBlockers.push(`${issue.code}: ${issue.message}`);
         }
     }

package/dist/engine/session-context-generator.js

@@ -1,8 +1,9 @@
 // engine/session-context-generator.ts — SPEC-496: Auto-generate portable session-context.md
 // Writes planu/session-context.md so any LLM (Cursor, Windsurf, Aider…) can pick up project state.
-import { writeFile, readFile, mkdir } from 'node:fs/promises';
+import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { specStore, lessonsStore } from '../storage/index.js';
+import { stableWriteGeneratedFile, stripSessionMarkdownVolatileFields, } from './generated-artifact-writer.js';
 /** Reads the `version` field from the project's package.json, or returns 'unknown'. */
 async function readProjectVersion(projectPath) {
     try {
@@ -128,10 +129,13 @@ export async function generateSessionContext(projectPath, projectId) {
             lessonsContent: buildLessonsSection(lessons),
             generatedAt: new Date().toISOString(),
         });
-        const planuDir = join(projectPath, 'planu');
-        await mkdir(planuDir, { recursive: true });
-        const contextPath = join(planuDir, 'session-context.md');
-        await writeFile(contextPath, content, 'utf-8');
+        const contextPath = join(projectPath, 'planu', 'session-context.md');
+        const writeResult = await stableWriteGeneratedFile(contextPath, content, {
+            equivalence: stripSessionMarkdownVolatileFields,
+        });
+        if (!writeResult.written) {
+            return;
+        }
         if (process.env.PLANU_ENABLE_AUTOCOMMIT !== 'true') {
             return;
         }