@planu/cli 4.7.3 → 4.7.4

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+## [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

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/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/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

package/dist/engine/spec-format/acceptance-criteria.js

@@ -0,0 +1,106 @@
+import { parseFrontmatterScenarios } from '../validator/spec-compliance-runner.js';
+import { stripFrontmatter } from '../frontmatter-parser.js';
+import { extractListItems, extractSection } from '../validator/extractors.js';
+function normalizeCriterionValue(value) {
+    return value
+        .replace(/^-\s*\[[ x]\]\s*/i, '')
+        .replace(/[`*_()[\]:]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .toLowerCase();
+}
+function stripCriterionIdPrefix(value) {
+    return value.replace(/^(AC\d+)\s*[:.)-]?\s*/i, '').trim();
+}
+function detectCriterionId(value, index) {
+    const explicit = /^(AC\d+)\b/i.exec(value)?.[1];
+    return (explicit ?? `AC${String(index + 1)}`).toUpperCase();
+}
+function extractSectionCriteria(section) {
+    const listItems = extractListItems(section);
+    if (listItems.length > 0) {
+        return listItems;
+    }
+    const lines = section.split('\n').map((line) => line.trim());
+    if (lines.length === 0) {
+        return [];
+    }
+    const bddBlocks = [];
+    let current = [];
+    for (const line of lines) {
+        if (line.length === 0) {
+            if (current.length > 0) {
+                bddBlocks.push(current.join(' '));
+                current = [];
+            }
+            continue;
+        }
+        if (/^(GIVEN|WHEN|THEN|AND|DADO|CUANDO|ENTONCES|Y)\b/i.test(line)) {
+            if (/^(GIVEN|DADO)\b/i.test(line) && current.length > 0) {
+                bddBlocks.push(current.join(' '));
+                current = [];
+            }
+            current.push(line.replace(/^[-*+]\s*/, ''));
+            continue;
+        }
+        if (current.length > 0) {
+            current.push(line);
+        }
+    }
+    if (current.length > 0) {
+        bddBlocks.push(current.join(' '));
+    }
+    return bddBlocks;
+}
+function extractBodyCriteria(raw) {
+    const body = stripFrontmatter(raw);
+    const acceptanceCriteria = extractSection(body, 'acceptance criteria', 'criterios de aceptaci');
+    if (acceptanceCriteria) {
+        const sectionCriteria = extractSectionCriteria(acceptanceCriteria);
+        if (sectionCriteria.length > 0) {
+            return sectionCriteria;
+        }
+    }
+    return body
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => /^-\s*\[[ x]\]/i.test(line) || /^- .*\bgiven\b.*\bwhen\b.*\bthen\b/i.test(line))
+        .map((line) => line.replace(/^-\s*\[[ x]\]\s*/i, '').trim());
+}
+function buildCriterion(text, source, index) {
+    const trimmed = text.trim();
+    if (trimmed.length === 0) {
+        return null;
+    }
+    const id = detectCriterionId(trimmed, index);
+    const withoutId = stripCriterionIdPrefix(trimmed);
+    const aliases = new Set([
+        normalizeCriterionValue(trimmed),
+        normalizeCriterionValue(withoutId),
+        normalizeCriterionValue(id),
+    ]);
+    return {
+        id,
+        text: withoutId,
+        source,
+        aliases: [...aliases].filter((alias) => alias.length > 0),
+    };
+}
+export function extractNormalizedAcceptanceCriteria(raw) {
+    const bodyCriteria = extractBodyCriteria(raw)
+        .map((criterion, index) => buildCriterion(criterion, 'body', index))
+        .filter((criterion) => criterion !== null);
+    if (bodyCriteria.length > 0) {
+        return bodyCriteria;
+    }
+    return parseFrontmatterScenarios(raw)
+        .map((scenario, index) => buildCriterion(scenario.title, 'frontmatter', index))
+        .filter((criterion) => criterion !== null);
+}
+export function extractAcceptanceCriteriaTexts(raw) {
+    return extractNormalizedAcceptanceCriteria(raw).map((criterion) => criterion.text);
+}
+export function normalizeAcceptanceCriterionToken(value) {
+    return normalizeCriterionValue(stripCriterionIdPrefix(value));
+}
+//# sourceMappingURL=acceptance-criteria.js.map

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

@@ -133,6 +133,13 @@ async function walkSpecDirectory(projectPath, specDir, result) {
         }
     }
 }
+async function shouldDeleteOrphanSpecDir(specDir) {
+    const entries = await readdir(specDir).catch(() => []);
+    if (entries.includes('spec.md')) {
+        return false;
+    }
+    return !entries.some((entry) => mustMergeBeforeDeleteSpecFile(entry));
+}
 export async function runStrictPlanuCleanup(projectPath) {
     const result = { deleted: [], merged: [], gitignoreUpdated: false };
     const planuDir = join(projectPath, 'planu');
@@ -170,6 +177,11 @@ export async function runStrictPlanuCleanup(projectPath) {
             result.deleted.push(relative(projectPath, full));
             continue;
         }
+        if (await shouldDeleteOrphanSpecDir(full)) {
+            await removePath(projectPath, full);
+            result.deleted.push(relative(projectPath, full));
+            continue;
+        }
         await walkSpecDirectory(projectPath, full, result);
     }
     result.gitignoreUpdated = await updateGitignore(projectPath);
@@ -210,6 +222,10 @@ export async function validateStrictPlanuLayout(projectPath, options = {}) {
             offenders.push(relative(projectPath, full));
             continue;
         }
+        if (await shouldDeleteOrphanSpecDir(full)) {
+            offenders.push(relative(projectPath, full));
+            continue;
+        }
         for (const entry of await readdir(full).catch(() => [])) {
             const entryPath = join(full, entry);
             const isDir = await pathIsDirectory(entryPath);

package/dist/engine/universal-rules/rules/planu-release-policy.js

@@ -6,23 +6,26 @@ Auto-generated by \`init_project\`. Do not edit manually.
 
 ## Rule
 
-When implementation changes are complete and validated, always address release explicitly:
+When implementation changes are complete and validated, always address release explicitly with a local-first flow:
 
-- create the release when the user has already requested shipping or publishing
-- otherwise ask before publishing, tagging, or pushing externally visible release artifacts
+- canonical local gates: \`pnpm validate\` then \`pnpm check:strict\`
+- canonical local release command: \`pnpm release:local\`
+- publish externally only when the user has explicitly requested shipping/publishing
+- use \`main\` as the default release branch; treat \`develop\` as optional gitflow compatibility only when the repository actively uses it
 
 ## Required Release Checklist
 
-- tests and validation commands passed
+- local validation commands passed
 - changelog or release notes updated when applicable
 - package version and git tag stay aligned
-- main/develop branch state is reconciled when the repository uses both
+- release metadata under \`planu/releases/pending.json\` contains only genuinely pending entries
 - published package smoke check is run after release when applicable
 
 ## Hard Blocks
 
 - Do not silently skip release discussion after completed product/runtime changes.
 - Do not publish without validation evidence.
+- Do not let hosted CI, branch protection, or release bots redefine the canonical local release contract.
 - Do not leave release notes promising capabilities that are not in the public runtime.
 `;
 }

package/dist/native/lightweight-command-catalog.d.ts

@@ -47,7 +47,7 @@ export declare const LIGHTWEIGHT_COMMANDS: readonly [{
 }, {
     readonly id: "planu.release.check";
     readonly title: "Check release readiness";
-    readonly description: "Check local branch cleanliness and main/develop/release sync readiness.";
+    readonly description: "Check local-first release readiness, branch cleanliness, and optional gitflow drift.";
     readonly invocation: "planu release check";
     readonly hosts: readonly ["codex", "claude-code"];
     readonly requiresMcp: false;

package/dist/native/lightweight-command-catalog.js

@@ -54,7 +54,7 @@ export const LIGHTWEIGHT_COMMANDS = [
     {
         id: 'planu.release.check',
         title: 'Check release readiness',
-        description: 'Check local branch cleanliness and main/develop/release sync readiness.',
+        description: 'Check local-first release readiness, branch cleanliness, and optional gitflow drift.',
         invocation: 'planu release check',
         hosts: ['codex', 'claude-code'],
         requiresMcp: false,

package/dist/resources/process.js

@@ -93,8 +93,9 @@ function getSddProcess() {
                 id: 'documenting',
                 name: '8. Document & Ship',
                 tools: ['generate_docs', 'generate_docs_site', 'integrate_pm', 'learn_pattern'],
-                description: 'Generate documentation. Sync with project management tools. ' +
-                    'Learn patterns for future estimations.',
+                description: 'Generate documentation, run the local-first release contract ' +
+                    '(`pnpm validate`, `pnpm check:strict`, `pnpm release:local` when shipping), ' +
+                    'sync with project management tools, and learn patterns for future estimations.',
             },
         ],
         specLifecycle: ['draft', 'review', 'approved', 'implementing', 'done'],

package/dist/tools/challenge-spec/event-challenge-scenarios.js

@@ -6,12 +6,8 @@ import { detectBrokers, getBrokerConfig, requiresIdempotence, } from '../../engi
  * Returns true when the spec or project has event-driven characteristics.
  */
 export function isEventDrivenSpec(spec, specContent, knowledge) {
-    const brokers = detectBrokers(knowledge.stack);
-    if (brokers.length > 0 && brokers[0] !== 'unknown') {
-        return true;
-    }
     const lower = `${spec.title} ${spec.tags.join(' ')} ${specContent}`.toLowerCase();
-    return (lower.includes('event') ||
+    const specSignals = lower.includes('event') ||
         lower.includes('kafka') ||
         lower.includes('rabbitmq') ||
         lower.includes('pubsub') ||
@@ -21,7 +17,15 @@ export function isEventDrivenSpec(spec, specContent, knowledge) {
         lower.includes('sns') ||
         lower.includes('message') ||
         lower.includes('consumer') ||
-        lower.includes('producer'));
+        lower.includes('producer');
+    if (spec.target === 'frontend' && !specSignals) {
+        return false;
+    }
+    const brokers = detectBrokers(knowledge.stack);
+    if (specSignals) {
+        return true;
+    }
+    return brokers.length > 0 && brokers[0] !== 'unknown' && spec.target !== 'frontend';
 }
 /**
  * Generate event-driven failure scenarios for challenge_spec.

package/dist/tools/git/hook-ops.js

@@ -265,7 +265,7 @@ export async function handleSetupHooks(projectId, config) {
     /* v8 ignore start */
     const protectedBranches = mergedConfig.protectedBranches ?? DEFAULT_PROTECTED_BRANCHES;
     const stalenessThreshold = mergedConfig.stalenessThreshold ?? 50;
-    const baseBranch = mergedConfig.baseBranch ?? 'develop';
+    const baseBranch = mergedConfig.baseBranch ?? 'main';
     /* v8 ignore end */
     const preCommitScript = buildPreCommitScript(
     /* v8 ignore next */ mergedConfig.requireSpecInCommit ?? true, stalenessThreshold, baseBranch);

package/dist/tools/init-project/per-client-files-writer.js

@@ -63,6 +63,7 @@ Planu enforces Spec Driven Development — spec first, then implement, then vali
 
 - NEVER write production code before spec is \`approved\`
 - NEVER skip \`validate\` after implementation
+- Specs stay \`spec.md\`-only. Do not recreate standalone \`technical.md\` or \`progress.md\`.
 `;
 const CODEX_NATIVE_SKILL_CONTENT = `# planu-native — Planu Lightweight Native Surface
 
@@ -79,7 +80,7 @@ Use Planu's lightweight CLI surface for common SDD checks without loading the fu
 - \`planu spec list\` — list specs
 - \`planu spec validate SPEC-001\` — validate one spec
 - \`planu audit debt\` — read-only technical debt audit
-- \`planu release check\` — local release readiness check
+- \`planu release check\` — local-first release readiness check
 
 ## Escalate to Full MCP
 

package/dist/tools/init-project/rules-generator.js

@@ -20,6 +20,19 @@ Auto-generated by \`init_project\`. Do not edit manually.
 
 Flow: \`facilitate → create_spec → challenge_spec → check_readiness → approve → implement → validate → done\`
 
+## Evidence Gates
+
+For non-trivial specs, Planu blocks lifecycle transitions unless evidence is present:
+
+| Transition | Required evidence |
+|------------|-------------------|
+| \`approved\` | Discovery evidence: rules, examples, open questions, out-of-scope, glossary |
+| \`implementing\` | Task plan mapped to acceptance criteria |
+| \`done\` | Traceability matrix covering every acceptance criterion |
+| \`done\` for API/UI/event/MCP work | Passing contract validation evidence |
+
+Evidence lives in the external Planu handoff store, not under \`planu/specs/<spec>/\`. Spec folders remain \`spec.md\`-only.
+
 ## When to use \`facilitate\`
 
 Any new feature, bug fix, refactor, integration, or task > 5 min.
@@ -51,6 +64,7 @@ Any new feature, bug fix, refactor, integration, or task > 5 min.
 - NEVER write code before spec is \`approved\`
 - NEVER skip \`validate\` after implementation
 - NEVER create design docs outside \`planu/specs/\`
+- NEVER recreate legacy \`technical.md\`, \`progress.md\`, or \`HU.md\` files for new specs
 
 ## Model Selection (MANDATORY)
 

package/dist/tools/update-status/evidence-gate.js

@@ -1,12 +1,12 @@
 import { readFile } from 'node:fs/promises';
 import { isAbsolute, join } from 'node:path';
-import { extractCriteria, extractListItems, extractSection, } from '../../engine/validator/extractors.js';
-import { stripFrontmatter } from '../../engine/frontmatter-parser.js';
+import { extractCriteria } from '../../engine/validator/extractors.js';
 import { readEvidenceArtifacts } from '../../engine/evidence-gates/artifact-reader.js';
 import { checkLifecycleEvidenceGate } from '../../engine/evidence-gates/lifecycle-gate.js';
 import { buildSpecEvidenceIndex } from '../../engine/evidence-index/index-builder.js';
 import { checkDoneDriftContract } from '../../engine/evidence-index/done-drift.js';
 import { parseTechnicalReferenceGroundingRecords } from '../../engine/spec-grounding/contract.js';
+import { extractAcceptanceCriteriaTexts } from '../../engine/spec-format/acceptance-criteria.js';
 /** SPEC-1054: BDD/SDD lifecycle evidence gate. */
 export async function checkLifecycleEvidenceTransitionGate(args) {
     const [criteriaResult, artifacts] = await Promise.all([
@@ -54,13 +54,9 @@ async function extractLifecycleGateCriteriaAndBody(spec, projectPath) {
     const specPath = isAbsolute(spec.specPath) || !projectPath ? spec.specPath : join(projectPath, spec.specPath);
     try {
         const raw = await readFile(specPath, 'utf-8');
-        const body = stripFrontmatter(raw);
-        const acceptanceCriteria = extractSection(body, 'acceptance criteria', 'criterios de aceptaci');
-        if (acceptanceCriteria) {
-            const items = extractListItems(acceptanceCriteria);
-            if (items.length > 0) {
-                return { criteria: [...new Set(items)], body: raw };
-            }
+        const criteria = extractAcceptanceCriteriaTexts(raw);
+        if (criteria.length > 0) {
+            return { criteria: [...new Set(criteria)], body: raw };
         }
     }
     catch {

package/dist/types/cascade-hooks.d.ts

@@ -35,6 +35,11 @@ export type CoreActionResult = {
     ok: false;
     error: string;
 };
+export interface PendingReleaseEntry {
+    specId: string;
+    title: string;
+    completedAt: string;
+}
 /** SPEC-772: Result of a single fast hook execution. */
 export interface FastHookResult {
     hookId: string;

package/dist/types/spec-format.d.ts

@@ -27,6 +27,12 @@ export interface BddScenario {
         line?: number;
     }[];
 }
+export interface NormalizedAcceptanceCriterion {
+    id: string;
+    text: string;
+    source: 'body' | 'frontmatter';
+    aliases: string[];
+}
 /** Input for lean spec generation. */
 export interface LeanSpecInput {
     spec: Spec;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "4.7.3",
+  "version": "4.7.4",
   "description": "Planu — MCP Server for Spec Driven Development with native Rust acceleration for hot paths. Cross-platform (Linux/macOS/Windows, x64/arm64, glibc/musl).",
   "type": "module",
   "main": "dist/index.js",
@@ -34,14 +34,14 @@
     "packageName": "@planu/core"
   },
   "optionalDependencies": {
-    "@planu/core-darwin-arm64": "4.7.3",
-    "@planu/core-darwin-x64": "4.7.3",
-    "@planu/core-linux-arm64-gnu": "4.7.3",
-    "@planu/core-linux-arm64-musl": "4.7.3",
-    "@planu/core-linux-x64-gnu": "4.7.3",
-    "@planu/core-linux-x64-musl": "4.7.3",
-    "@planu/core-win32-arm64-msvc": "4.7.3",
-    "@planu/core-win32-x64-msvc": "4.7.3"
+    "@planu/core-darwin-arm64": "4.7.4",
+    "@planu/core-darwin-x64": "4.7.4",
+    "@planu/core-linux-arm64-gnu": "4.7.4",
+    "@planu/core-linux-arm64-musl": "4.7.4",
+    "@planu/core-linux-x64-gnu": "4.7.4",
+    "@planu/core-linux-x64-musl": "4.7.4",
+    "@planu/core-win32-arm64-msvc": "4.7.4",
+    "@planu/core-win32-x64-msvc": "4.7.4"
   },
   "engines": {
     "node": ">=24.0.0"
@@ -168,8 +168,8 @@
     }
   },
   "devDependencies": {
-    "@commitlint/cli": "^21.0.2",
-    "@commitlint/config-conventional": "^21.0.2",
+    "@commitlint/cli": "^21.1.0",
+    "@commitlint/config-conventional": "^21.1.0",
     "@eslint/js": "^10.0.1",
     "@napi-rs/cli": "^3.7.2",
     "@secretlint/secretlint-rule-no-homedir": "^13.0.2",
@@ -183,7 +183,7 @@
     "@stryker-mutator/core": "^9.6.1",
     "@stryker-mutator/vitest-runner": "^9.6.1",
     "@supabase/supabase-js": "^2.108.2",
-    "@types/node": "^25.9.3",
+    "@types/node": "^26.0.0",
     "@vitejs/plugin-vue": "^6.0.7",
     "@vitest/coverage-v8": "^4.1.9",
     "@vue/test-utils": "^2.4.11",
@@ -194,8 +194,8 @@
     "happy-dom": "^20.10.6",
     "husky": "^9.1.7",
     "javascript-obfuscator": "^5.4.3",
-    "knip": "^6.17.1",
-    "lint-staged": "^17.0.7",
+    "knip": "^6.18.0",
+    "lint-staged": "^17.0.8",
     "madge": "^8.0.0",
     "prettier": "^3.8.4",
     "secretlint": "^13.0.2",
@@ -203,8 +203,8 @@
     "tsc-alias": "^1.8.17",
     "type-coverage": "^2.29.7",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.61.1",
-    "vite": "^8.0.16",
+    "typescript-eslint": "^8.62.0",
+    "vite": "^8.1.0",
     "vitest": "^4.1.9",
     "vue": "^3.5.38"
   }

package/planu-native.json

@@ -1,7 +1,7 @@
 {
   "name": "dev.planu.native",
   "displayName": "Planu Native Lightweight Surface",
-  "version": "4.7.3",
+  "version": "4.7.4",
   "packageName": "@planu/cli",
   "modes": {
     "lightweight": {
@@ -80,7 +80,7 @@
         {
           "id": "planu.release.check",
           "title": "Check release readiness",
-          "description": "Check local branch cleanliness and main/develop/release sync readiness.",
+          "description": "Check local-first release readiness, branch cleanliness, and optional gitflow drift.",
           "invocation": "planu release check",
           "hosts": [
             "codex",

package/planu-plugin.json

@@ -2,7 +2,7 @@
   "name": "dev.planu.cli",
   "displayName": "Planu — Spec Driven Development",
   "description": "Manage software specs, estimations, and autonomous SDD workflows. Language-agnostic MCP server for Claude Code.",
-  "version": "4.7.3",
+  "version": "4.7.4",
   "icon": "assets/plugin/icon.svg",
   "command": [
     "npx",