@planu/cli 5.3.33 → 5.3.35

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [5.3.35] - 2026-08-23
+
+### Bug Fixes
+- fix(spec-1488): scope marker-declared path extraction to the path-list run after each marker
+
+
+## [5.3.34] - 2026-08-22
+
+### Bug Fixes
+- fix(spec-1588): fail closed on unresolved placeholders in raw generator output
+- fix(spec-1509): stop check_readiness false positives on error-outcome and clean criteria
+- fix(spec-1551): derive Goal and User Outcome from first acceptance criterion
+
+
 ## [5.3.33] - 2026-08-21
 
 ### Bug Fixes

package/dist/config/readiness-config.json

@@ -7,7 +7,11 @@
     { "id": "quick", "word": "quick" },
     { "id": "better", "word": "better" },
     { "id": "simple", "word": "simple" },
-    { "id": "clean", "word": "clean" }
+    {
+      "id": "clean",
+      "word": "clean",
+      "exemptFollowingNouns": ["checkout", "tree", "clone", "worktree", "working tree"]
+    }
   ],
   "thresholds": {
     "strictBlocker": 50,

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

@@ -9,8 +9,7 @@ export function buildImplementationContractSection(input) {
     const lines = [
         `## ${IMPLEMENTATION_CONTRACT_SECTION}`,
         '### User Outcome',
-        firstConcreteSentence(input.description) ??
-            criteria[0]?.text ??
+        criteria[0]?.text ??
             'Needs decision: define the exact observable outcome this spec must deliver.',
         '',
         '### File-Level Work Plan',
@@ -39,18 +38,6 @@ export function appendImplementationContractIfMissing(specBody, input) {
     }
     return `${specBody.trimEnd()}\n\n${buildImplementationContractSection(input)}`;
 }
-function firstConcreteSentence(description) {
-    const body = description
-        .replace(/^---[\s\S]*?---/, '')
-        .replace(/^#{1,6}\s+.+$/gm, '')
-        .split('\n')
-        .map((line) => line.trim())
-        .find((line) => line.length >= 24 && !line.startsWith('-'));
-    if (!body) {
-        return null;
-    }
-    return body.replace(/\s+/g, ' ');
-}
 function renderFilePlan(files, hasGroundedBehavior) {
     const lines = [];
     for (const [label, entries] of [

package/dist/engine/readiness-checker.js

@@ -120,6 +120,17 @@ function frontmatterScenarioCriteria(raw) {
         return [scenario.title, tests].filter((part) => part.trim().length > 0).join(' ');
     });
 }
+function isExemptedByFollowingNoun(lower, matchEnd, exemptNouns) {
+    const remainder = lower.slice(matchEnd).replace(/^\s+/, '');
+    return exemptNouns.some((noun) => {
+        const lowerNoun = noun.toLowerCase();
+        if (!remainder.startsWith(lowerNoun)) {
+            return false;
+        }
+        const after = remainder.charAt(lowerNoun.length);
+        return after === '' || /[^a-z0-9]/i.test(after);
+    });
+}
 function scoreCriteria(criteriaLines, vagueWords) {
     const blockers = [];
     const warnings = [];
@@ -141,10 +152,25 @@ function scoreCriteria(criteriaLines, vagueWords) {
     // Vague criteria detection
     for (const line of criteriaLines) {
         const lower = line.toLowerCase();
-        const vagueFound = vagueWords.filter((word) => {
-            const pattern = new RegExp(`\\b${word}\\b`);
-            return pattern.test(lower);
-        });
+        const vagueFound = [];
+        for (const item of vagueWords) {
+            const escapedWord = item.word.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            const pattern = new RegExp(`\\b${escapedWord}\\b`, 'g');
+            let match;
+            let flagged = false;
+            while ((match = pattern.exec(lower)) !== null) {
+                const matchEnd = match.index + match[0].length;
+                if (item.exemptFollowingNouns &&
+                    isExemptedByFollowingNoun(lower, matchEnd, item.exemptFollowingNouns)) {
+                    continue;
+                }
+                flagged = true;
+                break;
+            }
+            if (flagged) {
+                vagueFound.push(item.word);
+            }
+        }
         if (vagueFound.length > 0) {
             warnings.push(`Vague criterion detected (words: ${vagueFound.join(', ')}): "${line.slice(0, 80)}"`);
         }
@@ -336,7 +362,7 @@ function checkSpecificityGate(spec, criteriaLines, fichaContent, anticipatedTest
 // ── Public API ───────────────────────────────────────────────────────────────
 export async function checkSpecReadiness(spec, mode, projectHash) {
     const config = loadReadinessConfig(projectHash);
-    const vagueWords = config.vagueWords.map((v) => v.word);
+    const vagueWords = config.vagueWords;
     const huRaw = await readHuRaw(spec);
     const huContent = stripFrontmatter(huRaw);
     const anticipatedTestBreaksContent = extractSectionBody(huRaw, 'Anticipated Test Breaks');

package/dist/engine/readiness-config-loader.d.ts

@@ -1,5 +1,20 @@
+import { z } from 'zod';
 import type { ReadinessConfig } from '../types/index.js';
+declare const readinessConfigSchema: z.ZodObject<{
+    vagueWords: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        word: z.ZodString;
+        exemptFollowingNouns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    thresholds: z.ZodObject<{
+        strictBlocker: z.ZodNumber;
+        strictCaution: z.ZodNumber;
+        lenientBlocker: z.ZodNumber;
+        lenientCaution: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
 export type { ReadinessConfig };
+export { readinessConfigSchema };
 /**
  * Load the merged readiness configuration for a given project.
  * Falls back to system defaults when no overrides exist.

package/dist/engine/readiness-config-loader.js

@@ -10,6 +10,10 @@ import { ObjectConfigLoader } from './config-loader.js';
 const vagueWordItemSchema = z.object({
     id: z.string().min(1).describe('Unique identifier for this vague word entry'),
     word: z.string().min(1).describe('The vague word to detect in acceptance criteria'),
+    exemptFollowingNouns: z
+        .array(z.string().min(1))
+        .optional()
+        .describe('Nouns that, when immediately following the word, suppress the vague-word match'),
 });
 const readinessConfigSchema = z
     .object({
@@ -46,6 +50,7 @@ const readinessConfigSchema = z
         .describe('Score thresholds for each readiness mode'),
 })
     .describe('Readiness checker configuration including vague words and thresholds');
+export { readinessConfigSchema };
 // ── Loader instance ───────────────────────────────────────────────────────────
 const loader = new ObjectConfigLoader('readiness-config', readinessConfigSchema);
 /**

package/dist/engine/spec-format/technical-md-populator.d.ts

@@ -1,4 +1,9 @@
 import type { LeanFileEntry } from '../../types/index.js';
+/**
+ * Extract the path list declared immediately after each FILES:/FILE:/TEST:/TESTS: marker.
+ * Returns null when no such marker is present (caller falls back to whole-text grounding).
+ */
+export declare function extractMarkerDeclaredPaths(description: string): Set<string> | null;
 /**
  * Attempt to extract file paths from spec body for auto-populating ## Technical.
  * Returns null when no structured file section is found (caller uses placeholder).

package/dist/engine/spec-format/technical-md-populator.js

@@ -107,6 +107,54 @@ async function isAdmissibleProseCandidate(candidate, projectPath) {
     }
     return hasLetterInitialExtension(candidate) && (await isExistingDirectory(dirname(full)));
 }
+const MARKER_KEYWORD_RE = /\b(FILES|FILE|TESTS|TEST)\s*:/gi;
+const PATH_SEPARATOR_RE = /^(?:[ \t,]+|\band\b)+/i;
+const PATH_TOKEN_RE = /^`?([^\s,`]+)`?/;
+const TRAILING_PUNCTUATION_RE = /[.,;:]+$/;
+function isPathShaped(token) {
+    return token.includes('/') && /\.[a-zA-Z0-9]+$/.test(token);
+}
+function consumePathRun(remainder) {
+    const paths = new Set();
+    let cursor = remainder;
+    for (;;) {
+        cursor = cursor.replace(PATH_SEPARATOR_RE, '');
+        const tokenMatch = PATH_TOKEN_RE.exec(cursor);
+        if (tokenMatch?.[1] === undefined) {
+            break;
+        }
+        const raw = tokenMatch[1];
+        const endsWithTerminator = /[.;:]+$/.test(raw);
+        const trimmed = raw.replace(TRAILING_PUNCTUATION_RE, '');
+        if (!isPathShaped(trimmed)) {
+            break;
+        }
+        paths.add(trimmed.toLowerCase());
+        if (endsWithTerminator) {
+            break;
+        }
+        cursor = cursor.slice(tokenMatch[0].length);
+    }
+    return paths;
+}
+/**
+ * Extract the path list declared immediately after each FILES:/FILE:/TEST:/TESTS: marker.
+ * Returns null when no such marker is present (caller falls back to whole-text grounding).
+ */
+export function extractMarkerDeclaredPaths(description) {
+    const markers = [...description.matchAll(MARKER_KEYWORD_RE)];
+    if (markers.length === 0) {
+        return null;
+    }
+    const paths = new Set();
+    for (const marker of markers) {
+        const start = marker.index + marker[0].length;
+        for (const path of consumePathRun(description.slice(start))) {
+            paths.add(path);
+        }
+    }
+    return paths;
+}
 /**
  * Attempt to extract file paths from spec body for auto-populating ## Technical.
  * Returns null when no structured file section is found (caller uses placeholder).

package/dist/engine/spec-format/unified-spec-builder.d.ts

@@ -13,6 +13,10 @@ export declare function buildCanonicalUnifiedSpecContent(input: CanonicalUnified
  * inject sections the user did not author themselves.
  */
 export declare function buildUnifiedSpecContent(leanSpecBody: string, leanTechnicalBody: string): string;
+/** Masking-aware scan for an unresolved contract placeholder in raw generator output. */
+export declare function containsUnresolvedContractPlaceholder(rawText: string, options?: {
+    excludeGeneratorMissingDecisions?: boolean;
+}): boolean;
 /** Pure pre-persistence validation for the complete unified spec candidate. */
 export declare function validateUnifiedSpecCandidate(candidate: string, options?: {
     groundedFilePaths?: Iterable<string>;

package/dist/engine/spec-format/unified-spec-builder.js

@@ -20,7 +20,7 @@ export function buildCanonicalUnifiedSpecContent(input) {
     const proseBeforeHeading = source.split(/^##[ \t]+\S.*$/m, 1)[0]?.trim() ?? '';
     const problem = firstNonEmpty(explicitProblem, proseBeforeHeading, source);
     const explicitGoal = extractTopLevelSectionBody(source, 'Goal');
-    const goal = firstNonEmpty(explicitGoal, firstSentence(problem), problem);
+    const goal = firstNonEmpty(explicitGoal, input.criteria[0]?.text, 'Needs decision: define the goal this spec must achieve.');
     const explicitTechnical = extractTopLevelSectionBody(source, 'Technical');
     const generatedNotes = extractTopLevelSectionBody(input.technicalBody, 'Implementation Notes');
     const technical = firstNonEmpty(explicitTechnical, generatedNotes, 'Implement only the grounded ownership and observable behavior declared by this contract.');
@@ -154,6 +154,27 @@ function hasUnresolvedContractPlaceholderLine(scannable) {
         return (CONTRACT_PLACEHOLDER_MARKERS.some((marker) => marker.toLowerCase() === stripped.toLowerCase()) || /^(?:needs decision|tbd|todo)\s*:/i.test(stripped));
     });
 }
+function stripMissingDecisionsSection(scannable) {
+    const heading = /^ {0,3}##[ \t]+Missing Decisions[ \t]*$/im.exec(scannable);
+    if (!heading) {
+        return scannable;
+    }
+    const start = heading.index;
+    const nextHeadingRe = /^ {0,3}##[ \t]+\S.*$/gm;
+    nextHeadingRe.lastIndex = start + heading[0].length;
+    const next = nextHeadingRe.exec(scannable);
+    const end = next ? next.index : scannable.length;
+    return scannable.slice(0, start) + scannable.slice(end);
+}
+/** Masking-aware scan for an unresolved contract placeholder in raw generator output. */
+export function containsUnresolvedContractPlaceholder(rawText, options = {}) {
+    const body = stripFrontmatter(rawText.replace(/\r\n/g, '\n'));
+    let scannable = maskFencedAndQuotedText(body);
+    if (options.excludeGeneratorMissingDecisions) {
+        scannable = stripMissingDecisionsSection(scannable);
+    }
+    return hasUnresolvedContractPlaceholderLine(scannable);
+}
 /** Pure pre-persistence validation for the complete unified spec candidate. */
 // eslint-disable-next-line max-lines-per-function -- validation order mirrors the public issue contract
 export function validateUnifiedSpecCandidate(candidate, options = {}) {
@@ -285,13 +306,6 @@ function renderSection(title, body) {
 function firstNonEmpty(...values) {
     return (values.find((value) => value !== undefined && value !== null && value.length > 0) ?? '');
 }
-function firstSentence(text) {
-    const sentence = text
-        .split(/(?<=[.!?])\s+/)
-        .map((part) => part.trim())
-        .find((part) => part.length > 0 && !part.startsWith('#'));
-    return sentence ?? null;
-}
 function fallbackCriteriaBullets(criteria) {
     return criteria
         .map((criterion) => `- GIVEN the requested change is implemented WHEN the behavior is exercised THEN ${criterion.text}`)

package/dist/engine/spec-quality/generic-output-gate.js

@@ -87,6 +87,10 @@ const PLACEHOLDER_REFERENCE_RULES = [
         pattern: /(^|\/)(example|sample|mock|dummy)[\w.-]*\.[a-z]+$/i,
         reason: 'example file names must not be persisted as technical ownership',
     },
+    {
+        pattern: /(^|\/)(foo|bar|baz)\d*(?:\.[a-z0-9]+)+$/i,
+        reason: 'example file names must not be persisted as technical ownership',
+    },
 ];
 export function checkGenericSpecOutput(content) {
     const criteria = frontmatterCriteria(content);

package/dist/engine/spec-quality-scorer.js

@@ -299,12 +299,22 @@ function scoreAmbiguity(content, criteriaLines) {
         recommendations.push('Replace all TBD/TODO/FIXME markers with concrete requirements');
     }
     // Check for edge case coverage: criteria with error/failure/invalid/empty (-4 if missing)
-    const edgeCaseKeywords = ['error', 'fail', 'invalid', 'empty', 'null', 'missing', 'timeout'];
-    const hasEdgeCases = criteriaLines.length > 0 &&
-        criteriaLines.some((line) => {
-            const l = line.toLowerCase();
-            return edgeCaseKeywords.some((k) => l.includes(k));
-        });
+    const edgeCaseKeywords = [
+        'error',
+        'fail',
+        'invalid',
+        'empty',
+        'null',
+        'missing',
+        'timeout',
+        'halt',
+        'abort',
+        'refuse',
+        'reject',
+        'exit',
+    ];
+    const edgeCasePattern = new RegExp(`\\b(${edgeCaseKeywords.join('|')})`, 'i');
+    const hasEdgeCases = criteriaLines.length > 0 && criteriaLines.some((line) => edgeCasePattern.test(line));
     if (criteriaLines.length >= 3 && !hasEdgeCases) {
         score -= 4;
         issues.push('No edge case criteria found (error, failure, invalid inputs)');

package/dist/tools/create-spec.js

@@ -14,8 +14,8 @@ import { validateConstitution } from './create-spec/constitution-validator.js';
 import { getAsyncAnalysisPath } from './create-spec/post-creation.js';
 import { extractCriteria, generateLeanSpecContent, } from '../engine/spec-format/lean-spec-generator.js';
 import { generateLeanTechnicalContent, } from '../engine/spec-format/lean-technical-generator.js';
-import { extractFilesFromSpecBody } from '../engine/spec-format/technical-md-populator.js';
-import { buildCanonicalUnifiedSpecContent, validateUnifiedSpecCandidate, } from '../engine/spec-format/unified-spec-builder.js';
+import { extractFilesFromSpecBody, extractMarkerDeclaredPaths, } from '../engine/spec-format/technical-md-populator.js';
+import { buildCanonicalUnifiedSpecContent, containsUnresolvedContractPlaceholder, validateUnifiedSpecCandidate, } from '../engine/spec-format/unified-spec-builder.js';
 import { buildImplementationContractSection } from '../engine/implementation-contract/index.js';
 import { resolveEnglishOnlySpecGate } from '../engine/spec-language/english-only.js';
 import { FallbackGenerator } from '../engine/spec-generator/index.js';
@@ -116,8 +116,25 @@ export async function groundTechnicalFiles(input) {
     };
     const records = [];
     const advisoryFiles = [];
+    const markerPaths = extractMarkerDeclaredPaths(input.userInput);
     for (const section of ['create', 'modify', 'test']) {
         for (const file of input.files[section]) {
+            if (markerPaths !== null) {
+                if (markerPaths.has(file.path.toLowerCase())) {
+                    grounded[section].push(file);
+                    records.push({
+                        path: file.path,
+                        section,
+                        source: 'user_input',
+                        evidence: ['create_spec.description'],
+                        confidence: 'high',
+                    });
+                }
+                else {
+                    advisoryFiles.push(file);
+                }
+                continue;
+            }
             const pathInUserInput = pathSurvivesNegativeClauseCheck(userInput, file.path.toLowerCase());
             const exists = await pathExists(pathJoin(input.projectPath, file.path));
             const fromAutopilot = autopilotPaths.has(file.path);
@@ -1182,6 +1199,30 @@ async function prepareCreateSpecCandidate(initialParams, server) {
             },
         });
     }
+    if (containsUnresolvedContractPlaceholder(generatedSpec.specBody, {
+        excludeGeneratorMissingDecisions: true,
+    })) {
+        return earlyPreparation({
+            content: [
+                {
+                    type: 'text',
+                    text: 'Unified spec candidate is invalid: Unified candidate contains an unresolved contract placeholder.',
+                },
+            ],
+            isError: true,
+            structuredContent: {
+                error: 'SPEC_FORMAT_INVALID',
+                code: 422,
+                persisted: false,
+                issues: [
+                    {
+                        code: 'UNRESOLVED_CONTRACT_PLACEHOLDER',
+                        message: 'Unified candidate contains an unresolved contract placeholder.',
+                    },
+                ],
+            },
+        });
+    }
     const actionableMetrics = calculateActionableSpecMetrics({
         criteria: [...baseCriteria, ...filteredCriteria],
         groundingRecords: groundingCriteria,

package/dist/types/plugin-configs.d.ts

@@ -51,6 +51,7 @@ export interface FeasibilityRule {
 export interface VagueWordItem {
     id: string;
     word: string;
+    exemptFollowingNouns?: string[];
 }
 export interface ReadinessThresholds {
     strictBlocker: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "5.3.33",
+  "version": "5.3.35",
   "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.33",
+  "version": "5.3.35",
   "icon": "assets/plugin/icon.svg",
   "command": ["npx", "@planu/cli@latest"],
   "packageName": "@planu/cli",