@planu/cli 4.7.2 → 4.7.4

package/CHANGELOG.md

@@ -1,3 +1,21 @@
+## [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
+- feat: add reversible context compaction
+
+### Chores
+- chore(deps): update patch and minor dependencies
+
+
 ## [4.7.2] - 2026-06-16
 
 ### Features
@@ -4094,4 +4112,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/token-waste-autopilot.json

@@ -17,6 +17,22 @@
       "generic": { "maxLines": 60 }
     }
   },
+  "contextArtifacts": {
+    "enabled": true,
+    "ttlMs": 86400000,
+    "minTokens": 200
+  },
+  "contentCompaction": {
+    "strategies": {
+      "json": { "maxLines": 60, "maxSnippetChars": 240 },
+      "test-log": { "maxLines": 80, "keepFailures": true, "maxSnippetChars": 240 },
+      "runtime-log": { "maxLines": 60, "keepFailures": true, "uniqueOnly": true, "maxSnippetChars": 240 },
+      "search-results": { "maxLines": 80, "uniqueOnly": true, "maxSnippetChars": 180 },
+      "code": { "maxLines": 120, "maxSnippetChars": 240 },
+      "spec-or-handoff": { "maxLines": 120, "maxSnippetChars": 240 },
+      "generic-text": { "maxLines": 60, "maxSnippetChars": 240 }
+    }
+  },
   "tools": {
     "groups": {
       "spec": ["create_spec", "check_readiness", "challenge_spec", "update_status"],

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/compact/compact-middleware.d.ts

@@ -1,10 +1,10 @@
 import type { ToolResult } from '../../types/index.js';
-import type { CompactDecision } from '../../types/compact/compact-mode.js';
+import type { CompactDecision, CompactModeOptions } from '../../types/compact/compact-mode.js';
 /**
  * Apply compact mode formatting to a ToolResult.
  * - Truncates text content blocks to tokenBudget
  * - Preserves structuredContent (essential data: status, scores, blockers)
  * - Adds _meta.compactMode and _meta.contextUsed
  */
-export declare function applyCompactMode(result: ToolResult, decision: CompactDecision): ToolResult;
+export declare function applyCompactMode(result: ToolResult, decision: CompactDecision, options?: CompactModeOptions): ToolResult;
 //# sourceMappingURL=compact-middleware.d.ts.map

package/dist/engine/compact/compact-middleware.js

@@ -1,6 +1,47 @@
 // engine/compact/compact-middleware.ts — SPEC-922: Apply compact mode to tool responses
+import { compactContentAware } from '../token-optimizer/content-aware-compactor.js';
 /** Approximate chars per token for English text. */
 const CHARS_PER_TOKEN = 4;
+function defaultCompactPolicy(tokenBudget) {
+    return {
+        contextArtifacts: {
+            enabled: true,
+            ttlMs: 24 * 60 * 60 * 1000,
+            minTokens: tokenBudget,
+        },
+        contentCompaction: {
+            strategies: {
+                json: { maxLines: tokenBudget },
+                'test-log': { maxLines: tokenBudget },
+                'runtime-log': { maxLines: tokenBudget },
+                'search-results': { maxLines: tokenBudget },
+                code: { maxLines: tokenBudget },
+                'spec-or-handoff': { maxLines: tokenBudget },
+                'generic-text': { maxLines: tokenBudget },
+            },
+        },
+        redaction: {
+            maxSnippetChars: 240,
+            redactPatterns: ['secret', 'token', 'password', 'api_key'],
+        },
+    };
+}
+function withCompactionMeta(result, compaction) {
+    if (compaction === undefined) {
+        return result;
+    }
+    return {
+        ...result,
+        structuredContent: {
+            ...(result.structuredContent ?? {}),
+            compaction,
+        },
+        _meta: {
+            ...(typeof result._meta === 'object' && result._meta !== null ? result._meta : {}),
+            compaction,
+        },
+    };
+}
 /** Truncate a single text block to a token budget. */
 function truncateBlock(text, tokenBudget) {
     const maxChars = tokenBudget * CHARS_PER_TOKEN;
@@ -17,7 +58,7 @@ function truncateBlock(text, tokenBudget) {
  * - Preserves structuredContent (essential data: status, scores, blockers)
  * - Adds _meta.compactMode and _meta.contextUsed
  */
-export function applyCompactMode(result, decision) {
+export function applyCompactMode(result, decision, options = {}) {
     if (decision.mode !== 'compact') {
         // Still add _meta even in verbose mode if contextUsed was provided
         if (decision.contextUsed !== undefined) {
@@ -32,11 +73,31 @@ export function applyCompactMode(result, decision) {
         }
         return result;
     }
-    const truncatedContent = result.content.map((block) => ({
-        ...block,
-        text: truncateBlock(block.text, decision.tokenBudget),
-    }));
-    return {
+    let firstCompaction;
+    const truncatedContent = result.content.map((block) => {
+        if (options.projectPath !== undefined) {
+            const compacted = compactContentAware({
+                text: block.text,
+                policy: defaultCompactPolicy(decision.tokenBudget),
+                projectPath: options.projectPath,
+                sourcePath: options.sourcePath,
+                flow: options.flow,
+                kind: options.flow,
+            });
+            firstCompaction ??= compacted.artifact;
+            return {
+                ...block,
+                text: compacted.text.length < block.text.length
+                    ? `${compacted.text}\n\nArtifact: ${compacted.artifact?.artifactRef ?? 'not stored'}`
+                    : truncateBlock(block.text, decision.tokenBudget),
+            };
+        }
+        return {
+            ...block,
+            text: truncateBlock(block.text, decision.tokenBudget),
+        };
+    });
+    return withCompactionMeta({
         ...result,
         content: truncatedContent,
         _meta: {
@@ -45,6 +106,6 @@ export function applyCompactMode(result, decision) {
             contextUsed: decision.contextUsed,
             tokenBudget: decision.tokenBudget,
         },
-    };
+    }, firstCompaction);
 }
 //# sourceMappingURL=compact-middleware.js.map

package/dist/engine/context-artifacts/index.d.ts

@@ -0,0 +1,2 @@
+export { getContextArtifactStats, retrieveContextArtifact, storeContextArtifact } from './store.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/engine/context-artifacts/index.js

@@ -0,0 +1,2 @@
+export { getContextArtifactStats, retrieveContextArtifact, storeContextArtifact } from './store.js';
+//# sourceMappingURL=index.js.map

package/dist/engine/context-artifacts/store.d.ts

@@ -0,0 +1,5 @@
+import type { ContextArtifactStats, RetrieveContextArtifactResult, StoreContextArtifactInput, StoreContextArtifactResult } from '../../types/context-artifacts.js';
+export declare function storeContextArtifact(input: StoreContextArtifactInput): StoreContextArtifactResult;
+export declare function retrieveContextArtifact(projectPath: string, ref: string): RetrieveContextArtifactResult;
+export declare function getContextArtifactStats(projectPath: string): ContextArtifactStats;
+//# sourceMappingURL=store.d.ts.map

package/dist/engine/context-artifacts/store.js

@@ -0,0 +1,176 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getSensitivePathRefusal, shouldBypassLeanMode, } from '../context-intelligence/compression-guards.js';
+import { hashProjectPath, projectDataDir } from '../../storage/base-store.js';
+const REF_PREFIX = 'ctx_';
+const REF_PATTERN = /^ctx_[a-f0-9]{32}$/;
+const FORBIDDEN_METADATA_KEY = /(?:secret|token|password|credential|api[_-]?key|private[_-]?key)/i;
+function artifactDir(projectPath) {
+    return join(projectDataDir(hashProjectPath(projectPath)), 'context-artifacts');
+}
+function artifactPath(projectPath, ref) {
+    if (!REF_PATTERN.test(ref)) {
+        return null;
+    }
+    return join(artifactDir(projectPath), `${ref}.json`);
+}
+function sha256(value) {
+    return createHash('sha256').update(value, 'utf8').digest('hex');
+}
+function safeMetadata(metadata) {
+    const safe = {};
+    for (const [key, value] of Object.entries(metadata ?? {})) {
+        if (FORBIDDEN_METADATA_KEY.test(key)) {
+            continue;
+        }
+        if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+            safe[key] =
+                typeof value === 'string' && FORBIDDEN_METADATA_KEY.test(value) ? '[redacted]' : value;
+        }
+    }
+    return safe;
+}
+function compactionMetadata(artifact) {
+    return {
+        artifactRef: artifact.ref,
+        originalTokens: artifact.originalTokens,
+        compactTokens: artifact.compactTokens,
+        tokensSaved: artifact.tokensSaved,
+        strategy: artifact.strategy,
+        contentType: artifact.contentType,
+        expiresAt: artifact.expiresAt,
+        retrievalHint: `Use artifactRef ${artifact.ref} to retrieve the full local output before ${artifact.expiresAt}.`,
+    };
+}
+function readArtifactFile(path) {
+    try {
+        return JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+function writeArtifactFile(path, artifact) {
+    writeFileSync(path, JSON.stringify(artifact, null, 2), 'utf-8');
+}
+export function storeContextArtifact(input) {
+    if (input.sourcePath) {
+        const refusal = getSensitivePathRefusal(input.sourcePath);
+        if (refusal !== null) {
+            return { stored: false, refusedReason: refusal };
+        }
+    }
+    if (input.flow && shouldBypassLeanMode(input.flow)) {
+        return {
+            stored: false,
+            refusedReason: `Refusing recoverable artifact for sensitive flow ${input.flow}`,
+        };
+    }
+    const contentHash = sha256(input.originalContent);
+    const ref = `${REF_PREFIX}${contentHash.slice(0, 32)}`;
+    const path = artifactPath(input.projectPath, ref);
+    if (path === null) {
+        return { stored: false, refusedReason: 'Invalid generated artifact ref' };
+    }
+    const now = Date.now();
+    const createdAt = new Date(now).toISOString();
+    const expiresAt = new Date(now + input.ttlMs).toISOString();
+    const tokensSaved = Math.max(0, input.originalTokens - input.compactTokens);
+    const previous = existsSync(path) ? readArtifactFile(path) : null;
+    const artifact = {
+        ref,
+        contentHash,
+        createdAt: previous?.createdAt ?? createdAt,
+        expiresAt,
+        ttlMs: input.ttlMs,
+        projectId: hashProjectPath(input.projectPath),
+        contentType: input.contentType,
+        strategy: input.strategy,
+        originalTokens: input.originalTokens,
+        compactTokens: input.compactTokens,
+        tokensSaved,
+        retrievalCount: previous?.retrievalCount ?? 0,
+        metadata: safeMetadata(input.metadata),
+        originalContent: input.originalContent,
+        compactContent: input.compactContent,
+    };
+    mkdirSync(artifactDir(input.projectPath), { recursive: true });
+    writeArtifactFile(path, artifact);
+    return { stored: true, artifact, metadata: compactionMetadata(artifact) };
+}
+export function retrieveContextArtifact(projectPath, ref) {
+    const path = artifactPath(projectPath, ref);
+    if (path === null) {
+        return {
+            found: false,
+            reason: 'invalid-ref',
+            hint: 'Artifact refs are opaque ctx_<hash> identifiers.',
+        };
+    }
+    if (!existsSync(path)) {
+        return {
+            found: false,
+            reason: 'missing',
+            hint: 'The artifact is missing or belongs to a different project.',
+        };
+    }
+    const artifact = readArtifactFile(path);
+    if (artifact === null) {
+        return {
+            found: false,
+            reason: 'corrupt',
+            hint: 'The artifact payload is corrupt and cannot be recovered.',
+        };
+    }
+    if (artifact.projectId !== hashProjectPath(projectPath)) {
+        return {
+            found: false,
+            reason: 'unauthorized',
+            hint: 'The artifact does not belong to this project scope.',
+        };
+    }
+    if (Date.parse(artifact.expiresAt) <= Date.now()) {
+        return {
+            found: false,
+            reason: 'expired',
+            hint: 'The artifact expired; rerun the source operation if exact output is needed.',
+        };
+    }
+    const updated = { ...artifact, retrievalCount: artifact.retrievalCount + 1 };
+    writeArtifactFile(path, updated);
+    return {
+        found: true,
+        artifact: updated,
+        hint: 'Full artifact recovered from local Planu storage.',
+    };
+}
+export function getContextArtifactStats(projectPath) {
+    const dir = artifactDir(projectPath);
+    const stats = {
+        artifactCount: 0,
+        totalOriginalTokens: 0,
+        totalCompactTokens: 0,
+        totalTokensSaved: 0,
+        retrievalCount: 0,
+    };
+    if (!existsSync(dir)) {
+        return stats;
+    }
+    for (const entry of readdirSync(dir)) {
+        if (!entry.endsWith('.json')) {
+            continue;
+        }
+        const artifact = readArtifactFile(join(dir, entry));
+        if (artifact === null || Date.parse(artifact.expiresAt) <= Date.now()) {
+            continue;
+        }
+        stats.artifactCount += 1;
+        stats.totalOriginalTokens += artifact.originalTokens;
+        stats.totalCompactTokens += artifact.compactTokens;
+        stats.totalTokensSaved += artifact.tokensSaved;
+        stats.retrievalCount += artifact.retrievalCount;
+    }
+    return stats;
+}
+//# sourceMappingURL=store.js.map

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/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/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/spec-format/acceptance-criteria.d.ts

@@ -0,0 +1,5 @@
+import type { NormalizedAcceptanceCriterion } from '../../types/spec-format.js';
+export declare function extractNormalizedAcceptanceCriteria(raw: string): NormalizedAcceptanceCriterion[];
+export declare function extractAcceptanceCriteriaTexts(raw: string): string[];
+export declare function normalizeAcceptanceCriterionToken(value: string): string;
+//# sourceMappingURL=acceptance-criteria.d.ts.map