@planu/cli 5.3.66 → 5.3.67

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [5.3.67] - 2026-08-28
+
+### Bug Fixes
+- fix(SPEC-1214): make readiness executable-evidence fallback reachable outside planu/specs
+- fix(SPEC-1214): align readiness and validation on one executable-evidence contract
+- fix(SPEC-1306): forward caller cwd as explicit projectPath in CLI status
+
+### Chores
+- chore(SPEC-1315): transition to implementing
+- chore: mark SPEC-1306/SPEC-1214 done and file SPEC-1664 dogfood bug
+
+
 ## [5.3.66] - 2026-08-28
 
 ### Bug Fixes

package/dist/.planu-build.json

@@ -1 +1 @@
-{"schemaVersion":1,"commit":"e6b315bb677135204b8ade0a8d43149075ba3ba4"}
+{"schemaVersion":1,"commit":"fde3438aa03084c32064ee5f7ec4179e455e6062"}

package/dist/cli/commands/status.js

@@ -58,7 +58,7 @@ export function buildSingleStatusInput(values, specId, projectId, status) {
     return {
         specId,
         projectId,
-        projectPath: values['project-path'] ? resolve(values['project-path']) : undefined,
+        projectPath: values['project-path'] ? resolve(values['project-path']) : process.cwd(),
         status: status,
         reviewNotes: values.notes,
         modelId: values['model-id'],

package/dist/engine/readiness-checker.js

@@ -1,10 +1,13 @@
 // engine/readiness-checker.ts — Spec readiness evaluation for implementation gate (SPEC-039)
+import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
 import { extractSectionBody, readSpecTechnicalSection, } from './spec-format/read-technical-section.js';
 import { stripFrontmatter } from './frontmatter-parser.js';
 import { loadReadinessConfig } from './readiness-config-loader.js';
 import { runEarsGate } from './ears-gate.js';
 import { findScenariosWithoutTests, parseFrontmatterScenarios, } from './validator/spec-compliance-runner.js';
+import { normalizeExecutableEvidence } from './validator/executable-evidence.js';
 import { evaluateImplementationContract } from './implementation-contract/index.js';
 import { extractNormalizedAcceptanceCriteria } from './spec-format/acceptance-criteria.js';
 // ── SPEC-784: Technical section quality constants ─────────────────────────────
@@ -33,6 +36,13 @@ function scoreHuCompleteness(spec) {
     }
     return { points, blockers, warnings };
 }
+function projectPathFromSpecPath(specPath) {
+    const marker = /[/\\]planu[/\\]specs[/\\]/;
+    if (!specPath || !marker.test(specPath)) {
+        return undefined;
+    }
+    return specPath.split(marker)[0];
+}
 async function readHuRaw(spec) {
     if (!spec.specPath) {
         return '';
@@ -421,6 +431,16 @@ export async function checkSpecReadiness(spec, mode, projectHash) {
             allBlockers.push(`scenarios_missing_tests: scenario "${title}" has no tests array — add tests entries (SPEC-732)`);
         }
     }
+    // SPEC-1214: BDD-criteria executable-evidence gate — when a spec has no frontmatter
+    // scenarios, its criteria must carry a TEST: marker mapping to an executable test file,
+    // or validation will later score 0 with "No executable scenarios declared".
+    if (bddScenarioCount === 0 && spec.scope !== 'trivial') {
+        const readinessProjectPath = projectPathFromSpecPath(spec.specPath);
+        const executableEvidence = normalizeExecutableEvidence(huRaw, parseFrontmatterScenarios(huRaw), (path) => (readinessProjectPath ? existsSync(join(readinessProjectPath, path)) : true));
+        for (const title of executableEvidence.unmappedCriteria) {
+            allBlockers.push(`criteria_missing_executable_test: criterion "${title}" has no TEST: marker mapping to an executable test file (SPEC-1214)`);
+        }
+    }
     // SPEC-784: Technical section quality gates — blocker-severity issues
     if (detectTechnicalPlaceholder(huContent)) {
         allBlockers.push('TECHNICAL_PLACEHOLDER_DETECTED: ## Technical section contains a placeholder pointer ' +

package/dist/engine/validator/executable-evidence.d.ts

@@ -0,0 +1,31 @@
+export interface EvidenceTestLink {
+    path: string;
+}
+export interface EvidenceScenario {
+    title: string;
+    tests: EvidenceTestLink[];
+}
+export type ExecutableEvidenceSource = 'frontmatter' | 'criteria' | 'none';
+export interface ExecutableEvidence {
+    source: ExecutableEvidenceSource;
+    scenarios: EvidenceScenario[];
+    unmappedCriteria: string[];
+    ignoredCriteriaTitles: string[];
+}
+/**
+ * Single evidence normalizer shared by spec-compliance-runner.ts and
+ * readiness-checker.ts (SPEC-1214). Frontmatter `scenarios` stay canonical when
+ * present; otherwise BDD criteria `TEST:` markers become the executable evidence,
+ * so a spec approved by readiness on `TEST:` markers cannot later validate as
+ * "no executable scenarios declared". `isValidTestPath` lets each caller reject a
+ * `TEST:` marker pointing at a file that does not exist on disk, instead of
+ * silently treating it as executable evidence; it defaults to accepting every
+ * path when a caller has no filesystem to check against.
+ */
+export declare function normalizeExecutableEvidence(raw: string, frontmatterScenarios: {
+    title: string;
+    tests?: {
+        path: string;
+    }[];
+}[], isValidTestPath?: (path: string) => boolean): ExecutableEvidence;
+//# sourceMappingURL=executable-evidence.d.ts.map

package/dist/engine/validator/executable-evidence.js

@@ -0,0 +1,104 @@
+import { extractSection } from '../spec-format/markdown-sections.js';
+import { stripFrontmatter } from '../frontmatter-parser.js';
+const CRITERION_HEADING = /^#{2,6}\s+((?:AC|AB)\s*-?\s*\d+)\b/i;
+const GIVEN_BULLET = /^-\s*GIVEN\b/i;
+const BDD_STEP = /^(?:[-*]\s+)?(GIVEN|WHEN|THEN|AND)\b/i;
+const TEST_MARKER_LINE = /^\s*TEST:\s*(.+)$/im;
+const TEST_FILE_TOKEN = /`?([\w./-]+\.(?:test|spec)\.[cm]?[jt]sx?)`?/g;
+function splitByLineStarts(lines, starts) {
+    return starts.map((start, position) => {
+        const end = starts[position + 1] ?? lines.length;
+        return lines.slice(start, end).join('\n');
+    });
+}
+function splitCriterionBlocks(section) {
+    const lines = section.split('\n');
+    const headingStarts = lines
+        .map((line, index) => (CRITERION_HEADING.test(line.trim()) ? index : -1))
+        .filter((index) => index !== -1);
+    if (headingStarts.length > 0) {
+        return splitByLineStarts(lines, headingStarts);
+    }
+    const bulletStarts = lines
+        .map((line, index) => (GIVEN_BULLET.test(line.trim()) ? index : -1))
+        .filter((index) => index !== -1);
+    if (bulletStarts.length > 0) {
+        return splitByLineStarts(lines, bulletStarts);
+    }
+    return section.split(/\n\s*\n/).filter((block) => /\bGIVEN\b/i.test(block));
+}
+function blockTitle(block) {
+    const stepLines = block
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => BDD_STEP.test(line))
+        .map((line) => line.replace(/^[-*]\s+/, ''));
+    if (stepLines.length > 0) {
+        return stepLines.join(' ');
+    }
+    const heading = /^#{2,6}\s+(.+)$/.exec(block.split('\n')[0]?.trim() ?? '');
+    return (heading?.[1] ?? block.trim()).slice(0, 200);
+}
+function blockTestLinks(block, isValidTestPath) {
+    const marker = TEST_MARKER_LINE.exec(block);
+    if (!marker?.[1]) {
+        return [];
+    }
+    return [...marker[1].matchAll(TEST_FILE_TOKEN)]
+        .map((match) => match[1])
+        .filter((path) => Boolean(path))
+        .filter(isValidTestPath)
+        .map((path) => ({ path }));
+}
+function extractCriteriaScenarios(raw, isValidTestPath) {
+    const body = stripFrontmatter(raw);
+    const section = extractSection(body, 'acceptance criteria', 'criterios de aceptaci') ?? body;
+    return splitCriterionBlocks(section).map((block) => ({
+        title: blockTitle(block),
+        tests: blockTestLinks(block, isValidTestPath),
+    }));
+}
+/**
+ * Single evidence normalizer shared by spec-compliance-runner.ts and
+ * readiness-checker.ts (SPEC-1214). Frontmatter `scenarios` stay canonical when
+ * present; otherwise BDD criteria `TEST:` markers become the executable evidence,
+ * so a spec approved by readiness on `TEST:` markers cannot later validate as
+ * "no executable scenarios declared". `isValidTestPath` lets each caller reject a
+ * `TEST:` marker pointing at a file that does not exist on disk, instead of
+ * silently treating it as executable evidence; it defaults to accepting every
+ * path when a caller has no filesystem to check against.
+ */
+export function normalizeExecutableEvidence(raw, frontmatterScenarios, isValidTestPath = () => true) {
+    const criteriaScenarios = extractCriteriaScenarios(raw, isValidTestPath);
+    if (frontmatterScenarios.length > 0) {
+        return {
+            source: 'frontmatter',
+            scenarios: frontmatterScenarios.map((scenario) => ({
+                title: scenario.title,
+                tests: (scenario.tests ?? []).map((test) => ({ path: test.path })),
+            })),
+            unmappedCriteria: [],
+            ignoredCriteriaTitles: criteriaScenarios
+                .filter((scenario) => scenario.tests.length > 0)
+                .map((scenario) => scenario.title),
+        };
+    }
+    const mapped = criteriaScenarios.filter((scenario) => scenario.tests.length > 0);
+    if (mapped.length > 0) {
+        return {
+            source: 'criteria',
+            scenarios: criteriaScenarios,
+            unmappedCriteria: criteriaScenarios
+                .filter((scenario) => scenario.tests.length === 0)
+                .map((scenario) => scenario.title),
+            ignoredCriteriaTitles: [],
+        };
+    }
+    return {
+        source: 'none',
+        scenarios: [],
+        unmappedCriteria: criteriaScenarios.map((scenario) => scenario.title),
+        ignoredCriteriaTitles: [],
+    };
+}
+//# sourceMappingURL=executable-evidence.js.map

package/dist/engine/validator/spec-compliance-runner.d.ts

@@ -27,6 +27,8 @@ export interface SpecComplianceResult {
     dimensionScore: number;
     perScenario: PerScenarioResult[];
     command: string;
+    evidenceSource?: 'frontmatter' | 'criteria' | 'none';
+    ignoredCriteriaTitles?: string[];
 }
 /** A sanitized terminal adapter failure that cannot be mistaken for a failed test verdict. */
 export declare class ComplianceCommandTerminalError extends Error {

package/dist/engine/validator/spec-compliance-runner.js

@@ -8,6 +8,7 @@ import { technologyValue } from '../technology-registry.js';
 import { readMatchingValidationEvidence } from '../validation-evidence-ledger.js';
 import { readEvidenceArtifacts, traceabilityRowHasCurrentCommandEvidence, } from '../evidence-gates/artifact-reader.js';
 import { normalizeCriterionText } from '../criterion-identity.js';
+import { normalizeExecutableEvidence } from './executable-evidence.js';
 /** A sanitized terminal adapter failure that cannot be mistaken for a failed test verdict. */
 export class ComplianceCommandTerminalError extends Error {
     code;
@@ -450,16 +451,31 @@ async function loadExactCommandRows(spec, projectPath, canonicalProjectId) {
 // eslint-disable-next-line max-lines-per-function -- coordinates validation, adapters, and isolated per-scenario evidence
 export async function runSpecCompliance(spec, projectPath, signal, canonicalProjectId) {
     const { readFile } = await import('node:fs/promises');
+    const { existsSync } = await import('node:fs');
     let raw;
     try {
         raw = await readFile(spec.specPath, 'utf-8');
     }
     catch {
-        return { dimensionScore: 0, perScenario: [], command: '' };
+        return { dimensionScore: 0, perScenario: [], command: '', evidenceSource: 'none' };
     }
-    const scenarios = parseFrontmatterScenarios(raw);
+    const frontmatterScenarios = parseFrontmatterScenarios(raw);
+    const executableEvidence = normalizeExecutableEvidence(raw, frontmatterScenarios, (path) => existsSync(join(projectPath, path)));
+    const scenarios = executableEvidence.source === 'frontmatter'
+        ? frontmatterScenarios
+        : executableEvidence.scenarios.map((scenario) => ({
+            title: scenario.title,
+            done: false,
+            tests: scenario.tests.map((test) => ({ path: test.path })).filter(isExecutableTestLink),
+        }));
     if (scenarios.length === 0) {
-        return { dimensionScore: 0, perScenario: [], command: '' };
+        return {
+            dimensionScore: 0,
+            perScenario: [],
+            command: '',
+            evidenceSource: executableEvidence.source,
+            ignoredCriteriaTitles: executableEvidence.ignoredCriteriaTitles,
+        };
     }
     const allLinks = scenarios.flatMap((scenario) => scenario.tests ?? []);
     const executableLinks = allLinks.filter(isExecutableTestLink);
@@ -570,6 +586,8 @@ export async function runSpecCompliance(spec, projectPath, signal, canonicalProj
         perScenario,
         command: commands.join(' && ') ||
             `${technologyValue('technology-vitest-a9127f')} --reporter=json --run (no test files linked)`,
+        evidenceSource: executableEvidence.source,
+        ignoredCriteriaTitles: executableEvidence.ignoredCriteriaTitles,
     };
 }
 export function findScenariosWithoutTests(raw) {

package/dist/engine/validator/validation-report-writer.js

@@ -130,12 +130,18 @@ function buildMinimalityGate(report) {
             : undefined,
     };
 }
+function ignoredCriteriaNote(result) {
+    return result.ignoredCriteriaTitles?.length
+        ? ` Ignored BDD criteria TEST: mappings (frontmatter scenarios are canonical): ${result.ignoredCriteriaTitles.join(', ')}.`
+        : '';
+}
 function buildSpecComplianceGate(result) {
+    const ignoredNote = ignoredCriteriaNote(result);
     if (result.perScenario.length === 0) {
         return {
             name: 'spec-compliance',
-            passed: true,
-            reason: 'No executable scenarios declared; spec-compliance runner skipped.',
+            passed: false,
+            reason: `No executable scenarios declared (evidence source: ${result.evidenceSource ?? 'none'}) — add BDD criteria TEST: markers or frontmatter scenarios before done.${ignoredNote}`,
         };
     }
     const passed = result.dimensionScore === 100;
@@ -143,8 +149,8 @@ function buildSpecComplianceGate(result) {
         name: 'spec-compliance',
         passed,
         reason: passed
-            ? undefined
-            : `Expected all executable scenarios to pass, got ${String(result.dimensionScore)}.`,
+            ? ignoredNote.trim() || undefined
+            : `Expected all executable scenarios to pass, got ${String(result.dimensionScore)}.${ignoredNote}`,
     };
 }
 function toValidationReportCompliance(result) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "5.3.66",
+  "version": "5.3.67",
   "description": "Planu — MCP Server for Spec Driven Development. Cross-platform (Linux/macOS/Windows, x64/arm64).",
   "type": "module",
   "main": "dist/index.js",

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": "5.3.66",
+  "version": "5.3.67",
   "icon": "assets/plugin/icon.svg",
   "command": ["npx", "@planu/cli@latest"],
   "packageName": "@planu/cli",