@planu/cli 4.14.1 → 5.1.1

package/dist/engine/scope-boundaries/scope-validator.js

@@ -24,10 +24,44 @@ const GENERIC_SCOPE_TOKENS = new Set([
     'tool',
     'tools',
 ]);
+const GENERIC_SEMANTIC_TOKENS = new Set([
+    'change',
+    'validation',
+    'evidence',
+    'format',
+    'semantic',
+    'schema',
+    'receipt',
+]);
+function inflectionCandidates(token) {
+    const candidates = [token];
+    if (token.endsWith('s')) {
+        candidates.push(token.slice(0, -1));
+    }
+    for (const suffix of ['ed', 'ing']) {
+        if (token.endsWith(suffix)) {
+            const stem = token.slice(0, -suffix.length);
+            candidates.push(stem, `${stem}e`);
+        }
+    }
+    return [...new Set(candidates.filter((candidate) => candidate.length >= 4))];
+}
+function semanticToken(token) {
+    const candidates = inflectionCandidates(token);
+    const generic = candidates.find((candidate) => GENERIC_SEMANTIC_TOKENS.has(candidate));
+    if (generic) {
+        return generic;
+    }
+    const singular = token.endsWith('s') ? token.slice(0, -1) : token;
+    return singular.length >= 4 ? singular : token;
+}
 function keywords(phrase) {
-    return normalize(phrase)
-        .split(' ')
-        .filter((w) => w.length > 2 && !STOP_WORDS.has(w) && !GENERIC_SCOPE_TOKENS.has(w));
+    return [
+        ...new Set(normalize(phrase)
+            .split(' ')
+            .filter((word) => word.length > 2 && !STOP_WORDS.has(word) && !GENERIC_SCOPE_TOKENS.has(word))
+            .map(semanticToken)),
+    ];
 }
 /**
  * Determine whether a file path matches an out-of-scope item.
@@ -39,9 +73,12 @@ function fileMatchesScopeItem(filePath, scopeItem) {
     if (scopeKws.length === 0) {
         return false;
     }
-    const matchCount = scopeKws.filter((kw) => normPath.includes(kw)).length;
-    // Require at least 1 keyword match for a warning
-    return matchCount >= 1;
+    const pathKeywords = new Set(keywords(normPath));
+    const specific = scopeKws.filter((token) => !GENERIC_SEMANTIC_TOKENS.has(token));
+    const matched = scopeKws.filter((token) => pathKeywords.has(token));
+    return specific.length > 0
+        ? specific.some((token) => pathKeywords.has(token))
+        : new Set(matched).size >= 2;
 }
 /**
  * Validate implementation file paths against the spec's outOfScope declarations.
@@ -52,8 +89,9 @@ export function validateScopeCompliance(outOfScope, filePaths) {
     for (const filePath of filePaths) {
         for (const scopeItem of outOfScope) {
             if (fileMatchesScopeItem(filePath, scopeItem)) {
+                const pathKeywords = new Set(keywords(filePath));
                 const matchedKws = keywords(scopeItem)
-                    .filter((kw) => normalize(filePath).includes(kw))
+                    .filter((keyword) => pathKeywords.has(keyword))
                     .join(', ');
                 warnings.push({
                     filePath,

package/dist/engine/session/checkpoint-writer.js

@@ -74,15 +74,6 @@ export async function writeCheckpoint(projectPath, snapshot) {
     const updated = replaceLatestCheckpoint(existing, newBlock);
     await mkdir(planuDir, { recursive: true });
     await writeFile(filePath, updated, 'utf8');
-    void (async () => {
-        try {
-            const { planuAutoCommit } = await import('../git/planu-autocommit.js');
-            await planuAutoCommit({ projectPath, reason: 'session-checkpoint' });
-        }
-        catch {
-            /* best-effort — never blocks checkpoint writer */
-        }
-    })();
 }
 /**
  * Fire-and-forget helper: records the tool call, then writes a checkpoint if

package/dist/engine/spec-format/acceptance-criteria.d.ts

@@ -1,5 +1,9 @@
 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 extractNormalizedAcceptanceCriteria(raw: string, options?: {
+    allowLegacyBodyFallback?: boolean;
+}): NormalizedAcceptanceCriterion[];
+export declare function extractAcceptanceCriteriaTexts(raw: string, options?: {
+    allowLegacyBodyFallback?: boolean;
+}): string[];
 export declare function normalizeAcceptanceCriterionToken(value: string): string;
 //# sourceMappingURL=acceptance-criteria.d.ts.map

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

@@ -1,12 +1,13 @@
 import { parseFrontmatterScenarios } from '../validator/spec-compliance-runner.js';
 import { stripFrontmatter } from '../frontmatter-parser.js';
-import { extractListItems, extractSection } from '../validator/extractors.js';
+import { extractListItems, extractSection } from './markdown-sections.js';
+import { stripFencedBlocks } from './text-fences.js';
 import { createCriterionIdentity, normalizeCriterionText } from '../criterion-identity.js';
-function extractSectionCriteria(section) {
-    const listItems = extractListItems(section);
-    if (listItems.length > 0) {
-        return listItems;
-    }
+const BDD_STEP = /^(GIVEN|WHEN|THEN|AND|DADO|CUANDO|ENTONCES|Y)\b/i;
+const BDD_START = /^(GIVEN|DADO)\b/i;
+const TECHNICAL_MARKER = /^(FILES|FUNCTIONS|TEST|OWNER):/i;
+const EXPLICIT_CRITERION_HEADING = /^#{3,6}\s+((?:AC|AB)\s*-?\s*\d+)\b/i;
+function extractBddBlocks(section) {
     const lines = section.split('\n').map((line) => line.trim());
     if (lines.length === 0) {
         return [];
@@ -21,16 +22,21 @@ function extractSectionCriteria(section) {
             }
             continue;
         }
-        if (/^(GIVEN|WHEN|THEN|AND|DADO|CUANDO|ENTONCES|Y)\b/i.test(line)) {
-            if (/^(GIVEN|DADO)\b/i.test(line) && current.length > 0) {
+        const withoutListMarker = line.replace(/^(?:[-*+]\s+(?:\[[ xX]\]\s*)?|\d+[.)]\s+)/, '');
+        if (TECHNICAL_MARKER.test(withoutListMarker) || /^#{1,6}\s+/.test(withoutListMarker)) {
+            if (current.length > 0) {
                 bddBlocks.push(current.join(' '));
                 current = [];
             }
-            current.push(line.replace(/^[-*+]\s*/, ''));
             continue;
         }
-        if (current.length > 0) {
-            current.push(line);
+        if (BDD_STEP.test(withoutListMarker)) {
+            if (BDD_START.test(withoutListMarker) && current.length > 0) {
+                bddBlocks.push(current.join(' '));
+                current = [];
+            }
+            current.push(withoutListMarker);
+            continue;
         }
     }
     if (current.length > 0) {
@@ -38,8 +44,55 @@ function extractSectionCriteria(section) {
     }
     return bddBlocks;
 }
-function extractBodyCriteria(raw) {
-    const body = stripFrontmatter(raw);
+function extractExplicitCriterionBodies(section) {
+    const lines = section.split('\n');
+    const bodies = [];
+    let current = null;
+    for (const line of lines) {
+        const heading = EXPLICIT_CRITERION_HEADING.exec(line.trim());
+        if (heading?.[1]) {
+            if (current !== null) {
+                bodies.push(current);
+            }
+            current = { id: heading[1].replace(/[\s-]/g, ''), body: '' };
+            continue;
+        }
+        if (current !== null) {
+            current.body += `${current.body.length > 0 ? '\n' : ''}${line}`;
+        }
+    }
+    if (current !== null) {
+        bodies.push(current);
+    }
+    return bodies;
+}
+function extractOneCriterion(body) {
+    const bddBlocks = extractBddBlocks(body);
+    if (bddBlocks.length > 0) {
+        return bddBlocks.reduce((selected, candidate) => candidate.length > selected.length ? candidate : selected);
+    }
+    const listItem = extractListItems(body).find((item) => !TECHNICAL_MARKER.test(item));
+    return listItem ?? null;
+}
+function extractSectionCriteria(section) {
+    const explicitBodies = extractExplicitCriterionBodies(section);
+    if (explicitBodies.length > 0) {
+        return explicitBodies
+            .map(({ id, body }) => {
+            const criterion = extractOneCriterion(body);
+            return criterion === null ? null : `${id}: ${criterion}`;
+        })
+            .filter((criterion) => criterion !== null);
+    }
+    const listItems = extractListItems(section).filter((item) => !TECHNICAL_MARKER.test(item));
+    if (listItems.length > 0) {
+        const nonStepItems = listItems.filter((item) => !BDD_STEP.test(item));
+        return nonStepItems.length > 0 ? nonStepItems : extractBddBlocks(section);
+    }
+    return extractBddBlocks(section);
+}
+function extractBodyCriteria(raw, options) {
+    const body = stripFencedBlocks(stripFrontmatter(raw));
     const acceptanceCriteria = extractSection(body, 'acceptance criteria', 'criterios de aceptaci');
     if (acceptanceCriteria) {
         const sectionCriteria = extractSectionCriteria(acceptanceCriteria);
@@ -47,11 +100,18 @@ function extractBodyCriteria(raw) {
             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());
+    if (options.allowLegacyBodyFallback !== false) {
+        const checkboxCriteria = body
+            .split('\n')
+            .map((line) => line.trim())
+            .filter((line) => /^-\s*\[[ x]\]/i.test(line))
+            .map((line) => line.replace(/^-\s*\[[ x]\]\s*/i, '').trim());
+        if (checkboxCriteria.length > 0) {
+            return checkboxCriteria;
+        }
+        return extractBddBlocks(body);
+    }
+    return [];
 }
 function buildCriterion(text, source, index) {
     const trimmed = text.trim();
@@ -68,8 +128,8 @@ function buildCriterion(text, source, index) {
         aliases: identity.aliases,
     };
 }
-export function extractNormalizedAcceptanceCriteria(raw) {
-    const bodyCriteria = extractBodyCriteria(raw)
+export function extractNormalizedAcceptanceCriteria(raw, options = {}) {
+    const bodyCriteria = extractBodyCriteria(raw, options)
         .map((criterion, index) => buildCriterion(criterion, 'body', index))
         .filter((criterion) => criterion !== null);
     if (bodyCriteria.length > 0) {
@@ -79,8 +139,8 @@ export function extractNormalizedAcceptanceCriteria(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 extractAcceptanceCriteriaTexts(raw, options = {}) {
+    return extractNormalizedAcceptanceCriteria(raw, options).map((criterion) => criterion.text);
 }
 export function normalizeAcceptanceCriterionToken(value) {
     return normalizeCriterionText(value);

package/dist/engine/spec-format/markdown-sections.d.ts

@@ -0,0 +1,14 @@
+/** Locate one exact markdown section without normalizing or copying source bytes. */
+export declare function findMarkdownSectionRange(content: string, headingName: string): {
+    headingStart: number;
+    contentStart: number;
+    end: number;
+    level: number;
+} | null;
+/**
+ * Extract the text content under a markdown heading that matches any keyword.
+ */
+export declare function extractSection(content: string, ...headingKeywords: string[]): string | null;
+/** Extract bullet and numbered-list item text from a markdown block. */
+export declare function extractListItems(content: string): string[];
+//# sourceMappingURL=markdown-sections.d.ts.map

package/dist/engine/spec-format/markdown-sections.js

@@ -0,0 +1,105 @@
+function markdownLines(content) {
+    const lines = [];
+    let start = 0;
+    while (start < content.length) {
+        const newline = content.indexOf('\n', start);
+        const end = newline === -1 ? content.length : newline + 1;
+        const contentEnd = newline === -1
+            ? end
+            : newline > start && content[newline - 1] === '\r'
+                ? newline - 1
+                : newline;
+        lines.push({ start, contentEnd, end });
+        start = end;
+    }
+    return lines;
+}
+/** Locate one exact markdown section without normalizing or copying source bytes. */
+export function findMarkdownSectionRange(content, headingName) {
+    let selected = null;
+    let fence = null;
+    for (const line of markdownLines(content)) {
+        const text = content.slice(line.start, line.contentEnd);
+        const fenceMatch = /^[ \t]{0,3}(`{3,}|~{3,})/.exec(text);
+        if (fenceMatch?.[1]) {
+            const marker = fenceMatch[1][0];
+            if (fence === null) {
+                fence = { marker, length: fenceMatch[1].length };
+            }
+            else if (fence.marker === marker && fenceMatch[1].length >= fence.length) {
+                fence = null;
+            }
+            continue;
+        }
+        if (fence !== null) {
+            continue;
+        }
+        const heading = /^(#{1,6})[ \t]+(.+?)[ \t]*#*[ \t]*$/.exec(text);
+        if (!heading?.[1] || heading[2] === undefined) {
+            continue;
+        }
+        const level = heading[1].length;
+        if (selected !== null && level <= selected.level) {
+            return { ...selected, end: line.start };
+        }
+        if (selected === null && heading[2].trim().toLowerCase() === headingName.trim().toLowerCase()) {
+            selected = {
+                headingStart: line.start,
+                contentStart: line.end,
+                end: content.length,
+                level,
+            };
+        }
+    }
+    return selected;
+}
+/**
+ * Extract the text content under a markdown heading that matches any keyword.
+ */
+export function extractSection(content, ...headingKeywords) {
+    const lines = content.split('\n');
+    let capturing = false;
+    let capturedLevel = 0;
+    const captured = [];
+    for (const line of lines) {
+        const headingMatch = /^(#{1,6})\s+(.+)/.exec(line);
+        if (headingMatch?.[1] !== undefined && headingMatch[2] !== undefined) {
+            const level = headingMatch[1].length;
+            const title = headingMatch[2].toLowerCase();
+            if (capturing && level <= capturedLevel) {
+                break;
+            }
+            if (!capturing && headingKeywords.some((keyword) => title.includes(keyword))) {
+                capturing = true;
+                capturedLevel = level;
+                continue;
+            }
+        }
+        if (capturing) {
+            captured.push(line);
+        }
+    }
+    return captured.length > 0 ? captured.join('\n') : null;
+}
+/** Extract bullet and numbered-list item text from a markdown block. */
+export function extractListItems(content) {
+    const items = [];
+    for (const line of content.split('\n')) {
+        const listMatch = /^\s*[-*+]\s+\[?\s*[xX ]?\s*\]?\s*(.+)/.exec(line);
+        if (listMatch?.[1]) {
+            const item = listMatch[1].trim();
+            if (item.length > 5) {
+                items.push(item);
+            }
+        }
+        const numberedMatch = /^\s*\d+[.)]\s+(.+)/.exec(line);
+        if (numberedMatch?.[1]) {
+            const item = numberedMatch[1].trim();
+            if (item.length > 5) {
+                items.push(item);
+            }
+        }
+    }
+    return items;
+}
+//# sourceMappingURL=markdown-sections.js.map

package/dist/engine/spec-format/read-technical-section.js

@@ -60,11 +60,39 @@ export function extractSectionBody(body, sectionName) {
  * against the masked variant.
  */
 function maskFencedBlocks(body) {
-    return body.replace(/(```|~~~)[\s\S]*?\1/g, (block) => {
-        // Replace every non-newline char with a space so offsets (and line
-        // numbers) are preserved exactly. Keep newlines intact.
-        return block.replace(/[^\n]/g, ' ');
-    });
+    const masked = body.split('');
+    let activeMarker = null;
+    let minimumClosingLength = 0;
+    let lineStart = 0;
+    while (lineStart < body.length) {
+        const newlineIndex = body.indexOf('\n', lineStart);
+        const lineEnd = newlineIndex === -1 ? body.length : newlineIndex;
+        const line = body.slice(lineStart, lineEnd);
+        if (activeMarker === null) {
+            const opening = /^ {0,3}(`{3,}|~{3,})/.exec(line)?.[1];
+            if (opening !== undefined) {
+                activeMarker = opening[0];
+                minimumClosingLength = opening.length;
+            }
+        }
+        else {
+            const closing = /^ {0,3}(`+|~+)[ \t]*$/.exec(line)?.[1];
+            if (closing?.startsWith(activeMarker) === true && closing.length >= minimumClosingLength) {
+                activeMarker = null;
+                minimumClosingLength = 0;
+            }
+        }
+        if (activeMarker !== null || minimumClosingLength === 0) {
+            const isFenceBoundary = /^ {0,3}(`{3,}|~{3,})/.test(line) || /^ {0,3}(`+|~+)[ \t]*$/.test(line);
+            if (activeMarker !== null || isFenceBoundary) {
+                for (let index = lineStart; index < lineEnd; index += 1) {
+                    masked[index] = ' ';
+                }
+            }
+        }
+        lineStart = newlineIndex === -1 ? body.length : newlineIndex + 1;
+    }
+    return masked.join('');
 }
 function escapeRegex(input) {
     return input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');

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

@@ -18,7 +18,7 @@ function extractPathsFromSection(sectionText) {
     return paths;
 }
 function parseSectionedFileLists(body) {
-    const filesSection = /##\s+Files\s+likely\s+to\s+change[\s\S]*?(?=\n##\s|$)/.exec(body);
+    const filesSection = /##\s+Files(?:\s+likely\s+to\s+change)?\s*[\s\S]*?(?=\n##\s|$)/.exec(body);
     const scopedBody = filesSection?.[0] ?? body;
     const createSection = /###\s+Create[\s\S]*?(?=\n###|\n##\s|$)/.exec(scopedBody);
     const modifySection = /###\s+Modify[\s\S]*?(?=\n###|\n##\s|$)/.exec(scopedBody);
@@ -67,7 +67,8 @@ async function categorizeByExistence(paths, projectPath) {
  */
 export async function extractFilesFromSpecBody(specBody, projectPath) {
     const structured = parseSectionedFileLists(specBody);
-    if (structured !== null && (structured.create.length > 0 || structured.modify.length > 0)) {
+    if (structured !== null &&
+        (structured.create.length > 0 || structured.modify.length > 0 || structured.test.length > 0)) {
         return structured;
     }
     const allPaths = [...new Set(Array.from(specBody.matchAll(FILE_PATH_RE), (m) => m[0]))];

package/dist/engine/spec-format/text-fences.js

@@ -4,7 +4,25 @@
  * Returns the remaining prose only, preserving line structure.
  */
 export function stripFencedBlocks(md) {
-    // Match ``` or ~~~ fences (with optional language specifier) spanning multiple lines
-    return md.replace(/^(`{3,}|~{3,})[^\n]*\n[\s\S]*?^\1\s*$/gm, '');
+    const lines = md.split('\n');
+    let openFence;
+    return lines
+        .map((line) => {
+        if (openFence !== undefined) {
+            const close = new RegExp(`^ {0,3}${openFence.marker}{${String(openFence.length)},}[ \\t]*\\r?$`);
+            if (close.test(line)) {
+                openFence = undefined;
+            }
+            return '';
+        }
+        const opening = /^ {0,3}(`{3,}|~{3,})[^\r\n]*\r?$/.exec(line);
+        if (opening?.[1]) {
+            const marker = opening[1][0];
+            openFence = { marker, length: opening[1].length };
+            return '';
+        }
+        return line;
+    })
+        .join('\n');
 }
 //# sourceMappingURL=text-fences.js.map

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

@@ -1,3 +1,6 @@
+import type { CanonicalUnifiedSpecInput, UnifiedSpecCandidateValidation } from '../../types/index.js';
+/** Compose the one canonical persisted spec document from already-grounded inputs. */
+export declare function buildCanonicalUnifiedSpecContent(input: CanonicalUnifiedSpecInput): string;
 /**
  * Combine a generated lean spec.md body and a generated lean technical.md body
  * into a single unified spec.md content. The technical body's YAML frontmatter
@@ -10,4 +13,8 @@
  * inject sections the user did not author themselves.
  */
 export declare function buildUnifiedSpecContent(leanSpecBody: string, leanTechnicalBody: string): string;
+/** Pure pre-persistence validation for the complete unified spec candidate. */
+export declare function validateUnifiedSpecCandidate(candidate: string, options?: {
+    groundedFilePaths?: Iterable<string>;
+}): UnifiedSpecCandidateValidation;
 //# sourceMappingURL=unified-spec-builder.d.ts.map