@planu/cli 5.7.4 → 5.7.6

package/dist/engine/spec-format/bdd-parser.js

@@ -1,4 +1,20 @@
 // engine/spec-format/bdd-parser.ts — BDD/Gherkin parser and emitter (SPEC-481)
+import { consumePathRunPreservingCase } from './technical-md-populator.js';
+const TEST_MARKER_RE = /\bTESTS?\s*:/gi;
+export function extractInlineTestPaths(text) {
+    const paths = [];
+    const seen = new Set();
+    for (const marker of text.matchAll(TEST_MARKER_RE)) {
+        const start = marker.index + marker[0].length;
+        for (const path of consumePathRunPreservingCase(text.slice(start))) {
+            if (!seen.has(path)) {
+                seen.add(path);
+                paths.push(path);
+            }
+        }
+    }
+    return paths;
+}
 const KEYWORD_MAP = {
     given: 'given',
     when: 'when',
@@ -17,22 +33,37 @@ const KEYWORD_MAP = {
  *     And ...
  *     But ...
  */
+const THEN_WORD_RE = /\bTHEN\b/i;
+const WHEN_WORD_RE = /\bWHEN\b/i;
+function hasThenSignal(scenario) {
+    return scenario.steps.some((step) => step.keyword === 'then' || THEN_WORD_RE.test(step.text));
+}
+function isSingleLineGivenWhenThenText(text) {
+    return WHEN_WORD_RE.test(text) && THEN_WORD_RE.test(text);
+}
+function opensHeaderlessScenario(rawKeyword, text) {
+    return rawKeyword === 'given' || isSingleLineGivenWhenThenText(text);
+}
 export function parseBddScenarios(markdown) {
     const scenarios = [];
     const lines = markdown.split('\n');
     let current = null;
     // Tracks whether the current scenario was auto-created (no Scenario: header)
     let currentIsHeaderless = false;
+    const closeCurrent = () => {
+        if (current && hasThenSignal(current)) {
+            scenarios.push(current);
+        }
+        current = null;
+        currentIsHeaderless = false;
+    };
     for (const raw of lines) {
         const line = raw.trim();
         // Detect scenario header
         const scenarioMatch = /^scenario:\s*(.+)$/i.exec(line);
         if (scenarioMatch) {
-            if (current) {
-                scenarios.push(current);
-            }
+            closeCurrent();
             current = { title: (scenarioMatch[1] ?? '').trim(), steps: [], done: false };
-            currentIsHeaderless = false;
             continue;
         }
         // Detect step keywords
@@ -47,12 +78,12 @@ export function parseBddScenarios(markdown) {
         // steps. This handles both multiple headerless blocks and headerless blocks following
         // an explicit Scenario: header block.
         if (rawKeyword === 'given' && current !== null && current.steps.length > 0) {
-            scenarios.push(current);
-            current = null;
-            currentIsHeaderless = false;
+            closeCurrent();
         }
-        // Auto-create a scenario when a step is found without a preceding Scenario header
         if (!current) {
+            if (!opensHeaderlessScenario(rawKeyword, text)) {
+                continue;
+            }
             current = { title: text, steps: [], done: false };
             currentIsHeaderless = true;
         }
@@ -62,9 +93,7 @@ export function parseBddScenarios(markdown) {
             current.title = text;
         }
     }
-    if (current) {
-        scenarios.push(current);
-    }
+    closeCurrent();
     return scenarios;
 }
 /**

package/dist/engine/spec-format/lean-spec-generator.js

@@ -1,6 +1,6 @@
 // engine/spec-format/lean-spec-generator.ts — Generates lean spec.md with YAML frontmatter (SPEC-461)
 // Output: ~30-50 lines. No generic sections, no OWASP, no STRIDE, no resilience criteria.
-import { parseBddScenarios, renderBddScenariosYaml, convertCheckboxToBdd } from './bdd-parser.js';
+import { parseBddScenarios, renderBddScenariosYaml, convertCheckboxToBdd, extractInlineTestPaths, } from './bdd-parser.js';
 import { decideMetadataSerialization, } from './metadata-value-policy.js';
 import { renderGroundingFrontmatter, renderTechnicalReferenceGroundingFrontmatter, } from '../spec-grounding/contract.js';
 /** Strip a redundant spec-ID prefix from spec titles.
@@ -117,15 +117,21 @@ function buildBddLines(description, extraCriteria, criteriaOverride, scenarioTes
                 done: false,
             });
         }
+        appendUncoveredCheckboxCriteria(scenarios, description);
     }
-    if (scenarioTestPaths.length > 0) {
-        scenarios = scenarios.map((scenario) => ({
-            ...scenario,
-            tests: scenario.tests && scenario.tests.length > 0
-                ? scenario.tests
-                : scenarioTestPaths.map((path) => ({ path })),
-        }));
-    }
+    scenarios = scenarios.map((scenario) => {
+        const inlinePaths = extractInlineTestPaths([scenario.title, ...scenario.steps.map((step) => step.text)].join('\n'));
+        if (inlinePaths.length > 0) {
+            return { ...scenario, tests: inlinePaths.map((path) => ({ path })) };
+        }
+        if (scenario.tests && scenario.tests.length > 0) {
+            return scenario;
+        }
+        if (scenarioTestPaths.length > 0) {
+            return { ...scenario, tests: scenarioTestPaths.map((path) => ({ path })) };
+        }
+        return scenario;
+    });
     return renderBddScenariosYaml(scenarios);
 }
 /** Extract acceptance criteria explicitly present in the description.
@@ -166,7 +172,7 @@ function extractCheckboxCriteria(description) {
 function extractGivenWhenThenCriteria(description) {
     const criteria = [];
     // Single-line: GIVEN ... WHEN ... THEN ...
-    const singleLineRegex = /^[ \t]*(?:[-*>]\s*|\d+[.)]\s*)?GIVEN\s+.+\s+WHEN\s+.+\s+THEN\s+(.+)$/gim;
+    const singleLineRegex = /^[ \t]*(?:[-*+>]\s*|\d+[.)]\s*)?GIVEN\s+.+\s+WHEN\s+.+\s+THEN\s+(.+)$/gim;
     let match = singleLineRegex.exec(description);
     while (match) {
         const thenText = match[1]?.trim() ?? '';
@@ -214,4 +220,18 @@ function extractPlainListCriteria(description) {
 function escapeYaml(value) {
     return value.replace(/"/g, '\\"');
 }
+function normalizeForDedupe(value) {
+    return value.trim().toLowerCase();
+}
+function appendUncoveredCheckboxCriteria(scenarios, description) {
+    const existingTexts = new Set(scenarios.flatMap((scenario) => [
+        normalizeForDedupe(scenario.title),
+        ...scenario.steps.map((step) => normalizeForDedupe(step.text)),
+    ]));
+    for (const criterion of extractCheckboxCriteria(description)) {
+        if (!existingTexts.has(normalizeForDedupe(criterion.text))) {
+            scenarios.push(...convertCheckboxToBdd([criterion]));
+        }
+    }
+}
 //# sourceMappingURL=lean-spec-generator.js.map

package/dist/engine/spec-format/retired-scaffold.d.ts

@@ -0,0 +1,3 @@
+export declare const RETIRED_SCAFFOLD_PREFIX = "GIVEN the requested change is implemented WHEN the behavior is exercised";
+export declare function isRetiredScaffoldText(text: string): boolean;
+//# sourceMappingURL=retired-scaffold.d.ts.map

package/dist/engine/spec-format/retired-scaffold.js

@@ -0,0 +1,5 @@
+export const RETIRED_SCAFFOLD_PREFIX = 'GIVEN the requested change is implemented WHEN the behavior is exercised';
+export function isRetiredScaffoldText(text) {
+    return text.toLowerCase().includes(RETIRED_SCAFFOLD_PREFIX.toLowerCase());
+}
+//# sourceMappingURL=retired-scaffold.js.map

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

@@ -1,4 +1,5 @@
 import type { LeanFileEntry } from '../../types/index.js';
+export declare function consumePathRunPreservingCase(remainder: string): string[];
 /**
  * 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).

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

@@ -137,6 +137,33 @@ function consumePathRun(remainder) {
     }
     return paths;
 }
+export function consumePathRunPreservingCase(remainder) {
+    const paths = [];
+    const seen = 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;
+        }
+        if (!seen.has(trimmed)) {
+            seen.add(trimmed);
+            paths.push(trimmed);
+        }
+        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).

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

@@ -21,4 +21,5 @@ export declare function containsUnresolvedContractPlaceholder(rawText: string, o
 export declare function validateUnifiedSpecCandidate(candidate: string, options?: {
     groundedFilePaths?: Iterable<string>;
 }): UnifiedSpecCandidateValidation;
+export declare function maskFencedAndQuotedText(body: string): string;
 //# sourceMappingURL=unified-spec-builder.d.ts.map

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

@@ -3,6 +3,7 @@
 // two-file spec.md + technical.md pair only to be merged on the next list_specs run.
 import { stripFrontmatter } from '../frontmatter-parser.js';
 import { extractAcceptanceCriteriaTexts } from './acceptance-criteria.js';
+import { isRetiredScaffoldText } from './retired-scaffold.js';
 import { escapeRegex } from '../../core/shared/strings.js';
 const REQUIRED_SECTIONS = [
     'Problem',
@@ -24,7 +25,7 @@ export function buildCanonicalUnifiedSpecContent(input) {
     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.');
+    const technical = firstNonEmpty(explicitTechnical, generatedNotes, groundedTechnicalFallback(input.files, input.criteria));
     const acceptance = extractExecutableCriteria(source, input.criteria);
     const explicitOutOfScope = extractTopLevelSectionBody(source, 'Out of scope');
     const outOfScope = input.outOfScope.length > 0
@@ -224,8 +225,12 @@ export function validateUnifiedSpecCandidate(candidate, options = {}) {
         });
     }
     const acceptanceSection = extractTopLevelSectionBody(scannable, 'Acceptance Criteria');
-    if (acceptanceSection === null ||
-        !/\bGIVEN\b[\s\S]*\bWHEN\b[\s\S]*\bTHEN\b/i.test(acceptanceSection)) {
+    const acceptanceSectionForBddCheck = acceptanceSection
+        ?.split('\n')
+        .filter((line) => !isRetiredScaffoldText(line))
+        .join('\n');
+    if (!acceptanceSectionForBddCheck ||
+        !/\bGIVEN\b[\s\S]*\bWHEN\b[\s\S]*\bTHEN\b/i.test(acceptanceSectionForBddCheck)) {
         issues.push({
             code: 'MISSING_EXECUTABLE_CRITERIA',
             section: 'Acceptance Criteria',
@@ -248,7 +253,7 @@ export function validateUnifiedSpecCandidate(candidate, options = {}) {
     }
     return { valid: issues.length === 0, issues };
 }
-function maskFencedAndQuotedText(body) {
+export function maskFencedAndQuotedText(body) {
     const lines = body.split('\n');
     let fence = null;
     return lines
@@ -305,27 +310,18 @@ function firstNonEmpty(...values) {
     return (values.find((value) => value !== undefined && value !== null && value.length > 0) ?? '');
 }
 function fallbackCriteriaBullets(criteria) {
-    return criteria
-        .map((criterion) => `- GIVEN the requested change is implemented WHEN the behavior is exercised THEN ${criterion.text}`)
-        .join('\n');
+    return criteria.map((criterion) => `- ${criterion.text}`).join('\n');
 }
-// Same BDD step vocabulary `acceptance-criteria.ts` recognizes (English + Spanish).
-// A criterion already starting with one of these is a genuine BDD fragment
-// (a full GIVEN/WHEN/THEN block, or an AND continuation of one) — leave it as-is.
-const BDD_STEP_START = /^(GIVEN|WHEN|THEN|AND|DADO|CUANDO|ENTONCES|Y)\b/i;
 /**
- * Render one real criterion as an executable bullet. Criteria already
- * written in BDD form pass through untouched; plain-text criteria (e.g.
- * checkbox items) are wrapped in the same GIVEN/WHEN/THEN scaffold
- * `fallbackCriteriaBullets` uses, so every bullet stays BDD-executable
- * without ever discarding a real criterion.
+ * Render one real criterion as a bullet. Criteria already written in BDD form
+ * pass through untouched; plain-text criteria (e.g. checkbox items) render as
+ * plain bullets — SPEC-1435 retires the constant GIVEN/WHEN/THEN scaffold that
+ * used to wrap them, since it satisfied `MISSING_EXECUTABLE_CRITERIA` without
+ * adding any spec-specific content.
  */
 function toExecutableBullet(text) {
     const cleaned = text.trim().replace(/[.\s]+$/, '.');
-    if (BDD_STEP_START.test(cleaned)) {
-        return `- ${cleaned}`;
-    }
-    return `- GIVEN the requested change is implemented WHEN the behavior is exercised THEN ${cleaned}`;
+    return `- ${cleaned}`;
 }
 /**
  * Criteria resolve through the canonical parser in `acceptance-criteria.ts`
@@ -339,6 +335,20 @@ function extractExecutableCriteria(source, criteria) {
     }
     return parsed.map(toExecutableBullet).join('\n');
 }
+/**
+ * SPEC-1435: replaces the constant Technical fallback sentence. When neither an
+ * author-written `## Technical` body nor generated implementation notes exist, compose
+ * the section from the spec's own grounded material instead of a fixed sentence that
+ * never varies with the spec: the grounded file records when present, otherwise the
+ * criteria texts.
+ */
+function groundedTechnicalFallback(files, criteria) {
+    const groundedFiles = [...files.create, ...files.modify, ...files.test];
+    if (groundedFiles.length > 0) {
+        return groundedFiles.map((entry) => `- \`${entry.path}\``).join('\n');
+    }
+    return criteria.map((criterion) => `- ${criterion.text}`).join('\n');
+}
 function renderOwnedFiles(files) {
     const sections = [];
     for (const [title, entries] of [

package/dist/engine/spec-grounding/contract.js

@@ -1,4 +1,17 @@
+import YAML from 'yaml';
 import { createCriterionIdentity, normalizeCriterionText } from '../criterion-identity.js';
+const GROUNDING_SOURCES = [
+    'user_input',
+    'project_evidence',
+    'documented_assumption',
+    'ungrounded_advisory',
+];
+const GROUNDING_CONFIDENCES = ['low', 'medium', 'high'];
+const TECHNICAL_REFERENCE_SECTIONS = [
+    'create',
+    'modify',
+    'test',
+];
 export { normalizeCriterionText } from '../criterion-identity.js';
 const GENERIC_CRITERION_PATTERNS = [
     /\bimplementation complete\b/i,
@@ -135,6 +148,107 @@ export function checkGroundedSpecContract(spec, content) {
     };
 }
 export function parseCriterionGroundingRecords(frontmatter) {
+    const outcome = parseFrontmatterYaml(frontmatter);
+    if (!outcome.parsed) {
+        return parseCriterionGroundingRecordsLegacy(frontmatter);
+    }
+    const grounding = readGroundingSection(outcome.document);
+    const entries = Array.isArray(grounding?.criteria) ? grounding.criteria : [];
+    const records = [];
+    for (const entry of entries) {
+        const record = toCriterionGroundingRecord(entry);
+        if (record) {
+            records.push(record);
+        }
+    }
+    return records;
+}
+export function parseTechnicalReferenceGroundingRecords(frontmatter) {
+    const outcome = parseFrontmatterYaml(frontmatter);
+    if (!outcome.parsed) {
+        return parseTechnicalReferenceGroundingRecordsLegacy(frontmatter);
+    }
+    const grounding = readGroundingSection(outcome.document);
+    const entries = grounding
+        ? Array.isArray(grounding.technicalReferences)
+            ? grounding.technicalReferences
+            : []
+        : Array.isArray(outcome.document?.technicalReferences)
+            ? outcome.document.technicalReferences
+            : [];
+    const records = [];
+    for (const entry of entries) {
+        const record = toTechnicalReferenceGroundingRecord(entry);
+        if (record) {
+            records.push(record);
+        }
+    }
+    return records;
+}
+function parseFrontmatterYaml(frontmatter) {
+    let value;
+    try {
+        value = YAML.parse(frontmatter);
+    }
+    catch {
+        return { parsed: false };
+    }
+    return { parsed: true, document: isRecord(value) ? value : undefined };
+}
+function readGroundingSection(document) {
+    const grounding = document?.grounding;
+    return isRecord(grounding) ? grounding : undefined;
+}
+function toCriterionGroundingRecord(entry) {
+    if (!isRecord(entry)) {
+        return null;
+    }
+    const text = typeof entry.text === 'string' && entry.text.length > 0 ? entry.text : null;
+    const source = toGroundingSource(entry.source);
+    const confidence = toGroundingConfidence(entry.confidence);
+    if (!text || !source || !confidence) {
+        return null;
+    }
+    return { text, source, evidence: toStringArray(entry.evidence), confidence };
+}
+function toTechnicalReferenceGroundingRecord(entry) {
+    if (!isRecord(entry)) {
+        return null;
+    }
+    const path = typeof entry.path === 'string' && entry.path.length > 0 ? entry.path : null;
+    const section = toTechnicalReferenceSection(entry.section);
+    const source = toGroundingSource(entry.source);
+    const confidence = toGroundingConfidence(entry.confidence);
+    if (!path || !section || !source || !confidence) {
+        return null;
+    }
+    return { path, section, source, evidence: toStringArray(entry.evidence), confidence };
+}
+function toGroundingSource(value) {
+    return typeof value === 'string' && GROUNDING_SOURCES.includes(value)
+        ? value
+        : null;
+}
+function toGroundingConfidence(value) {
+    return typeof value === 'string' && GROUNDING_CONFIDENCES.includes(value)
+        ? value
+        : null;
+}
+function toTechnicalReferenceSection(value) {
+    return typeof value === 'string' &&
+        TECHNICAL_REFERENCE_SECTIONS.includes(value)
+        ? value
+        : null;
+}
+function toStringArray(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === 'string')
+        : [];
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function parseCriterionGroundingRecordsLegacy(frontmatter) {
     const records = [];
     const chunks = frontmatter.split(/\n\s{4}- text:\s*/).slice(1);
     for (const chunk of chunks) {
@@ -154,7 +268,7 @@ export function parseCriterionGroundingRecords(frontmatter) {
     }
     return records;
 }
-export function parseTechnicalReferenceGroundingRecords(frontmatter) {
+function parseTechnicalReferenceGroundingRecordsLegacy(frontmatter) {
     const records = [];
     const chunks = frontmatter.split(/\n\s{4}- path:\s*/).slice(1);
     for (const chunk of chunks) {

package/dist/engine/spec-migrator/fold-technical.js

@@ -1,10 +1,47 @@
 // engine/spec-migrator/fold-technical.ts — SPEC-752
 // Folds legacy technical.md body into spec.md's ## Technical section, then deletes technical.md.
 // Uses the same pattern as unified-migration.ts (SPEC-630).
-import { readFile } from 'node:fs/promises';
+import { readFile, unlink } from 'node:fs/promises';
 import { join } from 'node:path';
 import { atomicWriteFile } from '../safety/atomic-write-file.js';
 import { safeUnlink } from './git-aware-fs.js';
+import { isPlaceholderTechnical } from './placeholder-technical.js';
+const FOLDED_HEADING = '### Folded from legacy technical.md';
+/**
+ * Insert `techBody` under a `### Folded from legacy technical.md` subsection,
+ * placed right after the existing `## Technical` section (before the next
+ * top-level `## ` heading, or at the end of the document when none follows).
+ */
+function foldIntoTechnicalSection(specContent, techBody) {
+    const headingMatch = /\n## Technical(\n|$)/.exec(specContent);
+    const insertion = `\n${FOLDED_HEADING}\n\n${techBody}\n`;
+    if (!headingMatch) {
+        return `${specContent.trimEnd()}\n\n## Technical\n${insertion}`;
+    }
+    const afterHeading = headingMatch.index + headingMatch[0].length;
+    const nextHeadingMatch = /\n## /.exec(specContent.slice(afterHeading));
+    if (!nextHeadingMatch) {
+        return `${specContent.trimEnd()}\n${insertion}`;
+    }
+    const insertAt = afterHeading + nextHeadingMatch.index;
+    return specContent.slice(0, insertAt) + insertion + specContent.slice(insertAt);
+}
+async function removeResidualTechnicalMd(techPath, projectPath) {
+    if (projectPath) {
+        // safeUnlink is already idempotent for a missing file (git rm --ignore-unmatch,
+        // unlink swallows ENOENT) and rethrows every other failure.
+        await safeUnlink(projectPath, techPath);
+        return;
+    }
+    try {
+        await unlink(techPath);
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT') {
+            throw err;
+        }
+    }
+}
 /**
  * Fold technical.md content into spec.md under a `## Technical` section.
  * Idempotent: returns already_unified if spec.md already has `## Technical`.
@@ -20,22 +57,32 @@ export async function foldTechnicalIntoSpec(specDir, projectPath) {
         const specContent = await readFile(specPath, 'utf-8');
         // Idempotency check: already has ## Technical section.
         // SPEC-1008: also delete any residual technical.md so the spec dir ends
-        // up in the canonical single-file layout. Previously the early-return
-        // left the legacy file behind forever.
+        // up in the canonical single-file layout.
+        // SPEC-1716: before deleting, read the residual — divergent content is
+        // folded under a "Folded from legacy technical.md" subsection instead of
+        // silently dropped.
         if (/\n## Technical(\n|$)/.test(specContent)) {
+            let residualContent;
             try {
-                if (projectPath) {
-                    await safeUnlink(projectPath, techPath);
-                }
-                else {
-                    const { unlink } = await import('node:fs/promises');
-                    await unlink(techPath);
-                }
+                residualContent = await readFile(techPath, 'utf-8');
             }
             catch {
-                /* technical.md already absent — nothing to clean up */
+                return { ok: true, reason: 'already_unified' };
             }
-            return { ok: true, reason: 'already_unified' };
+            const residualBody = residualContent.replace(/^---\n[\s\S]*?\n---\n?/, '').trim();
+            const alreadyContained = residualBody.length === 0 ||
+                specContent.includes(residualBody) ||
+                isPlaceholderTechnical(residualBody);
+            if (alreadyContained) {
+                await removeResidualTechnicalMd(techPath, projectPath);
+                return { ok: true, reason: 'already_unified' };
+            }
+            const unified = foldIntoTechnicalSection(specContent, residualBody);
+            const before = Buffer.byteLength(specContent, 'utf-8');
+            const after = Buffer.byteLength(unified, 'utf-8');
+            await atomicWriteFile(specPath, unified);
+            await removeResidualTechnicalMd(techPath, projectPath);
+            return { ok: true, reason: 'folded_residual', byteDelta: after - before };
         }
         // Try reading technical.md
         let techContent;
@@ -51,13 +98,7 @@ export async function foldTechnicalIntoSpec(specDir, projectPath) {
         const before = Buffer.byteLength(specContent, 'utf-8');
         const after = Buffer.byteLength(unified, 'utf-8');
         await atomicWriteFile(specPath, unified);
-        if (projectPath) {
-            await safeUnlink(projectPath, techPath);
-        }
-        else {
-            const { unlink } = await import('node:fs/promises');
-            await unlink(techPath);
-        }
+        await removeResidualTechnicalMd(techPath, projectPath);
         return { ok: true, reason: 'ok', byteDelta: after - before };
     }
     catch (err) {

package/dist/engine/spec-migrator/placeholder-technical.d.ts

@@ -0,0 +1,2 @@
+export declare function isPlaceholderTechnical(content: string): boolean;
+//# sourceMappingURL=placeholder-technical.d.ts.map

package/dist/engine/spec-migrator/placeholder-technical.js

@@ -0,0 +1,18 @@
+// engine/spec-migrator/placeholder-technical.ts — SPEC-1716
+// Shared placeholder-stub detector for technical.md bodies. Lives in engine/ so
+// both engine (fold-technical.ts) and tools (heal-spec-docs.ts) can import it —
+// engine/ must never import from tools/.
+export function isPlaceholderTechnical(content) {
+    if (content.includes('(pending)')) {
+        return true;
+    }
+    if (/--[a-z]/.test(content)) {
+        return true;
+    }
+    if (content.includes('(to be determined)') &&
+        !/\.(ts|tsx|js|jsx|py|rb|go|java|cs)/.test(content)) {
+        return true;
+    }
+    return false;
+}
+//# sourceMappingURL=placeholder-technical.js.map

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

@@ -1,3 +1,5 @@
+import { maskFencedAndQuotedText } from '../spec-format/unified-spec-builder.js';
+import { RETIRED_SCAFFOLD_PREFIX } from '../spec-format/retired-scaffold.js';
 /** Bounds the search for criteria to the frontmatter block only (between the two `---`
  * delimiters), so criterion-shaped lines never leak in from the rendered body below it. */
 const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---/;
@@ -21,7 +23,8 @@ const CRITERION_TEXT_RE = /^\s+- text:\s*"?(.+?)"?\s*$/gm;
  * the criterion-equivalent for `scenarios:`-format specs, which have no `- text:` entries. */
 const SCENARIO_TITLE_RE = /^\s+- title:\s*"?(.+?)"?\s*$/gm;
 const FILE_LINE_RE = /^-\s+(.+?)\s+\((pending|done)\)\s*$/gm;
-const H3_HEADING_RE = /^###[ \t]+(.+?)[ \t]*$/gm;
+const SECTION_HEADING_RE = /^#{1,3}[ \t]+(.+?)[ \t]*$/gm;
+const H3_HEADING_PREFIX_RE = /^###[ \t]/;
 const BULLET_LINE_RE = /^[-*][ \t]+(.+)$/;
 /** A bullet that, once a leading `Label:`, wrapping backticks, and a trailing `(status)`
  * marker are stripped, is just a file path: contains a `/` and ends in a short extension.
@@ -98,9 +101,40 @@ export function checkGenericSpecOutput(content) {
         ...checkCriteria(criteria),
         ...checkTechnicalReferences(content),
         ...checkInterpolatedSections(content, criteria),
+        ...checkRetiredFillerVocabulary(content),
     ];
     return { passed: issues.length === 0, issues };
 }
+/**
+ * SPEC-1435: dedicated scan for the constant filler sentences the renderer and the
+ * unified spec builder used to emit whenever nothing was grounded. Those sentences
+ * satisfied structural checks (a non-empty subsection, an executable-criteria match)
+ * without carrying any spec-specific content, and no existing rule matched their exact
+ * wording. Scans the whole body — prose and bullets, any heading level — with fenced
+ * code blocks and quoted text masked the same way `unified-spec-builder.ts` masks them,
+ * so a legitimate example inside a fence or blockquote is never flagged.
+ */
+const RETIRED_FILLER_SENTENCES = [
+    'Implement only the grounded ownership and observable behavior declared by this contract.',
+    'No repository-supported verification command was grounded for this candidate.',
+    'No file ownership was grounded for this behavior.',
+    'No repository-supported verification evidence was grounded for these criteria.',
+    RETIRED_SCAFFOLD_PREFIX,
+];
+function checkRetiredFillerVocabulary(content) {
+    const scannable = maskFencedAndQuotedText(content);
+    const issues = [];
+    for (const sentence of RETIRED_FILLER_SENTENCES) {
+        if (scannable.includes(sentence)) {
+            issues.push({
+                kind: 'generic-technical-reference',
+                phrase: sentence,
+                reason: `retired filler text must not appear in a persisted spec: "${sentence}"`,
+            });
+        }
+    }
+    return issues;
+}
 /**
  * SPEC-1406 (DEFECT 2, round 2 — detector rebuilt around CRITERION RESTATEMENT): the
  * previous prefix/suffix-length rule flagged `### File-Level Work Plan` (whose bullets
@@ -115,10 +149,10 @@ export function checkGenericSpecOutput(content) {
  */
 function checkInterpolatedSections(content, criteria) {
     const issues = [];
-    const headingMatches = [...content.matchAll(H3_HEADING_RE)];
+    const headingMatches = [...content.matchAll(SECTION_HEADING_RE)];
     for (let i = 0; i < headingMatches.length; i += 1) {
         const heading = headingMatches[i];
-        if (!heading?.[1]) {
+        if (!heading?.[1] || !H3_HEADING_PREFIX_RE.test(heading[0])) {
             continue;
         }
         const start = heading.index + heading[0].length;

package/dist/engine/technical-enricher/index.js

@@ -65,7 +65,10 @@ async function runEnricherFromSpecSection(opts) {
     if (result.enriched && result.enrichedContent) {
         const updated = `${specRaw.slice(0, section.contentStart)}${result.enrichedContent}${specRaw.slice(section.end)}`;
         assertEnrichmentPreservesContract(specRaw, updated, 'review-enricher');
-        await atomicWriteFile(physicalSpecPath, updated);
+        const relativeProposalPath = join('planu', '.runtime', 'enrichment-proposals', `${opts.specId}.md`);
+        const proposalPath = join(opts.projectPath, relativeProposalPath);
+        await atomicWriteFile(proposalPath, updated);
+        console.error(`Review enrichment proposal written to ${relativeProposalPath}`);
     }
 }
 //# sourceMappingURL=index.js.map