@planu/cli 4.3.20 → 4.3.22

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [4.3.22] - 2026-06-02
+
+### Bug Fixes
+- fix: stop fabricating spec and test artifacts
+
+
+## [4.3.21] - 2026-06-02
+
+### Bug Fixes
+- fix: enforce canonical spec ids and harden fallback specs
+
+
 ## [4.3.20] - 2026-05-27
 
 ### Bug Fixes

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

@@ -3,7 +3,11 @@
 /** Generate lean ## Technical content: YAML-like metadata + files section only. */
 export function generateLeanTechnicalContent(input) {
     const { specId, filesToCreate = [], filesToModify = [], filesToTest = [] } = input;
-    const lines = ['---', `spec: ${specId}`, '---', '', '## Files', ''];
+    const lines = ['---', `spec: ${specId}`, '---'];
+    if (filesToCreate.length === 0 && filesToModify.length === 0 && filesToTest.length === 0) {
+        return lines.join('\n');
+    }
+    lines.push('', '## Files', '');
     if (filesToCreate.length > 0) {
         lines.push('### Create', '');
         for (const f of filesToCreate) {
@@ -25,12 +29,6 @@ export function generateLeanTechnicalContent(input) {
         }
         lines.push('');
     }
-    // If no files specified, add placeholder
-    if (filesToCreate.length === 0 && filesToModify.length === 0 && filesToTest.length === 0) {
-        lines.push('### Create', '', '- (to be determined)', '');
-        lines.push('### Modify', '', '- (to be determined)', '');
-        lines.push('### Test', '', '- (to be determined)', '');
-    }
     return lines.join('\n');
 }
 //# sourceMappingURL=lean-technical-generator.js.map

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

@@ -13,7 +13,7 @@
  * inject sections the user did not author themselves.
  */
 export function buildUnifiedSpecContent(leanSpecBody, leanTechnicalBody) {
-    const technicalBodyRaw = leanTechnicalBody.replace(/^---\n[\s\S]*?\n---\n/, '').trim();
+    const technicalBodyRaw = leanTechnicalBody.replace(/^---\n[\s\S]*?\n---(?:\n|$)/, '').trim();
     if (technicalBodyRaw.length === 0) {
         return leanSpecBody.endsWith('\n') ? leanSpecBody : `${leanSpecBody}\n`;
     }

package/dist/engine/spec-generator/fallback-generator.js

@@ -2,17 +2,14 @@ export class FallbackGenerator {
     generate(request) {
         const sourceDescription = normalizeSourceDescription(request.description, request.title);
         const contextLine = buildContextLine(request);
-        const technicalSection = buildTechnicalSection(contextLine);
+        const technicalSection = '';
         const specBody = [
             '## Problem',
             sourceDescription,
             '',
             '## Solution',
-            'Use the preserved source description above as the authoritative requirements body. ' +
-                'Do not infer implementation ownership beyond details explicitly provided in the source. ' +
-                contextLine,
-            '',
-            technicalSection,
+            'Use the preserved source description above as the authoritative requirements body.',
+            contextLine,
         ].join('\n');
         return Promise.resolve({
             specBody,
@@ -20,7 +17,7 @@ export class FallbackGenerator {
             generatedWithModel: 'deterministic-fallback',
             generatedAt: new Date().toISOString(),
             qualityWarnings: [
-                'Fallback generator used. Source description was preserved; no implementation files, type signatures, or ownership were inferred.',
+                'Fallback generator used. Source description was preserved; technical ownership must come from explicit source paths or local project analysis.',
             ],
             fallbackReason: 'No external model generator is configured for create_spec.',
         });
@@ -44,27 +41,4 @@ function buildContextLine(request) {
     }
     return `Use the existing ${parts.join(' / ')} project conventions.`;
 }
-function buildTechnicalSection(contextLine) {
-    return [
-        '## Technical',
-        '',
-        '### Implementation Notes',
-        `- ${contextLine}`,
-        '- Preserve the source requirements as the contract until a reviewer or agent adds exact implementation ownership.',
-        '',
-        '## Files',
-        '',
-        '### Create',
-        '- _Not specified in source description._',
-        '### Modify',
-        '- _Not specified in source description._',
-        '### Test',
-        '- _Not specified in source description._',
-        '',
-        '## Verification',
-        '- pnpm typecheck',
-        '- pnpm lint',
-        '- pnpm test',
-    ].join('\n');
-}
 //# sourceMappingURL=fallback-generator.js.map

package/dist/engine/test-generators/contract-test-generator.d.ts

@@ -5,9 +5,10 @@ import type { ContractFormat, ContractSpec, ContractSpecEndpoint, ProjectKnowled
  */
 export declare function detectContractFormat(knowledge: ProjectKnowledge): ContractFormat;
 /**
- * Build a sample set of endpoints from a spec title (for scaffolding purposes).
+ * Legacy helper retained for API compatibility. Contract generation must not
+ * infer endpoints from a title; callers must pass observed endpoints instead.
  */
-export declare function buildSampleEndpoints(specTitle: string): ContractSpecEndpoint[];
+export declare function buildSampleEndpoints(_specTitle: string): ContractSpecEndpoint[];
 /**
  * Generate a contract spec for the given spec title and knowledge.
  * Format is auto-detected from project stack.

package/dist/engine/test-generators/contract-test-generator.js

@@ -21,49 +21,11 @@ export function detectContractFormat(knowledge) {
 }
 // === Contract generation functions ===
 /**
- * Build a sample set of endpoints from a spec title (for scaffolding purposes).
+ * Legacy helper retained for API compatibility. Contract generation must not
+ * infer endpoints from a title; callers must pass observed endpoints instead.
  */
-export function buildSampleEndpoints(specTitle) {
-    const resource = specTitle
-        .toLowerCase()
-        .replace(/[^a-z0-9]/g, '-')
-        .replace(/-+/g, '-');
-    return [
-        {
-            path: `/api/${resource}`,
-            method: 'GET',
-            requestSchema: {},
-            responseSchema: {
-                type: 'array',
-                items: { type: 'object', properties: { id: { type: 'string' } } },
-            },
-            statusCodes: [200, 401, 500],
-        },
-        {
-            path: `/api/${resource}`,
-            method: 'POST',
-            requestSchema: {
-                type: 'object',
-                required: ['name'],
-                properties: { name: { type: 'string' } },
-            },
-            responseSchema: {
-                type: 'object',
-                properties: { id: { type: 'string' }, name: { type: 'string' } },
-            },
-            statusCodes: [201, 400, 401, 422, 500],
-        },
-        {
-            path: `/api/${resource}/{id}`,
-            method: 'GET',
-            requestSchema: {},
-            responseSchema: {
-                type: 'object',
-                properties: { id: { type: 'string' }, name: { type: 'string' } },
-            },
-            statusCodes: [200, 401, 404, 500],
-        },
-    ];
+export function buildSampleEndpoints(_specTitle) {
+    return [];
 }
 // === OpenAPI contract generation ===
 function buildOpenApiYaml(specTitle, endpoints) {
@@ -244,7 +206,10 @@ export const ${name}Router = router({
  */
 export function generateContractSpec(specTitle, knowledge) {
     const format = detectContractFormat(knowledge);
-    const endpoints = buildSampleEndpoints(specTitle);
+    const endpoints = [];
+    if (endpoints.length === 0) {
+        return { format, content: '', endpoints };
+    }
     let content;
     switch (format) {
         case 'pact':

package/dist/engine/test-generators/mock-generator.d.ts

@@ -2,7 +2,7 @@ import type { ApiMockDefinition, ContractSpecEndpoint, MockServerTool } from '..
 /**
  * Generate mock definitions from a list of endpoints.
  */
-export declare function generateMockDefinitions(endpoints: ContractSpecEndpoint[], specTitle: string): ApiMockDefinition[];
+export declare function generateMockDefinitions(endpoints: ContractSpecEndpoint[], _specTitle: string): ApiMockDefinition[];
 /**
  * Generate mock server content for the given tool.
  */

package/dist/engine/test-generators/mock-generator.js

@@ -1,23 +1,5 @@
 // engine/test-generators/mock-generator.ts
 // SPEC-018: Mock generation for API endpoints (realistic data, delays, error responses)
-// === Realistic sample data generators ===
-function generateSampleId() {
-    return '550e8400-e29b-41d4-a716-446655440000';
-}
-function generateSampleData(resource) {
-    return {
-        id: generateSampleId(),
-        name: `Sample ${resource}`,
-        description: `Auto-generated sample for ${resource} (Planu SPEC-018)`,
-        status: 'active',
-        createdAt: '2025-01-15T10:30:00.000Z',
-        updatedAt: '2025-01-15T10:30:00.000Z',
-        email: `user@example.com`,
-        count: 42,
-        tags: ['sample', 'generated'],
-        metadata: { source: 'planu', version: '1.0' },
-    };
-}
 const ERROR_RESPONSES = [
     {
         status: 400,
@@ -56,16 +38,11 @@ function getErrorResponsesForEndpoint(statusCodes) {
 /**
  * Build an ApiMockDefinition from a ContractSpecEndpoint.
  */
-function buildMockFromEndpoint(endpoint, resource) {
-    const sampleData = endpoint.method === 'GET' && endpoint.path.endsWith('}')
-        ? generateSampleData(resource)
-        : endpoint.method === 'GET'
-            ? { items: [generateSampleData(resource)], total: 1, page: 1, pageSize: 20 }
-            : generateSampleData(resource);
+function buildMockFromEndpoint(endpoint) {
     return {
         endpoint: endpoint.path,
         method: endpoint.method,
-        sampleData,
+        sampleData: endpoint.responseSchema ?? {},
         delayMs: 250,
         errorResponses: getErrorResponsesForEndpoint(endpoint.statusCodes),
     };
@@ -73,15 +50,14 @@ function buildMockFromEndpoint(endpoint, resource) {
 /**
  * Generate mock definitions from a list of endpoints.
  */
-export function generateMockDefinitions(endpoints, specTitle) {
-    const resource = specTitle
-        .toLowerCase()
-        .replace(/[^a-z0-9]/g, '-')
-        .replace(/-+/g, '-');
-    return endpoints.map((ep) => buildMockFromEndpoint(ep, resource));
+export function generateMockDefinitions(endpoints, _specTitle) {
+    return endpoints.map((ep) => buildMockFromEndpoint(ep));
 }
 // === MSW (Mock Service Worker) content generation ===
 function buildMswMockContent(mocks, specTitle) {
+    if (mocks.length === 0) {
+        return '';
+    }
     const handlerLines = [];
     for (const mock of mocks) {
         const method = mock.method.toLowerCase();
@@ -109,6 +85,9 @@ ${mocks
 }
 // === json-server content generation ===
 function buildJsonServerContent(mocks, specTitle) {
+    if (mocks.length === 0) {
+        return '';
+    }
     const db = {};
     const resource = specTitle
         .toLowerCase()
@@ -133,6 +112,9 @@ ${JSON.stringify(db, null, 2)}
 }
 // === WireMock content generation ===
 function buildWiremockContent(mocks, _specTitle) {
+    if (mocks.length === 0) {
+        return '';
+    }
     const stubs = mocks.map((mock) => ({
         request: {
             method: mock.method,

package/dist/tools/bump-spec-version.js

@@ -7,6 +7,7 @@ import { getSpec } from '../storage/spec-store.js';
 import { safeTracked } from './safe-handler.js';
 import { bumpSpecVersion } from '../engine/spec-versioning/bump-version.js';
 import { resolveProjectId } from './resolve-project-id.js';
+import { SpecIdSchema } from './schemas/index.js';
 // SPEC-747: Grant unlock token after successful bump
 import { grantUnlock } from '../engine/freeze/unlock-token.js';
 // ---------------------------------------------------------------------------
@@ -25,7 +26,7 @@ const BumpSpecVersionSchema = {
         .max(500)
         .optional()
         .describe('Project ID (hash). Required if projectPath is not provided.'),
-    specId: z.string().min(1).max(500).describe('Spec ID to bump, e.g. SPEC-042.'),
+    specId: SpecIdSchema.describe('Spec ID to bump, e.g. SPEC-042.'),
     kind: z
         .enum(['patch', 'minor', 'major'])
         .describe('Bump kind: patch (typo/format), minor (new criterion/scope expansion), major (breaking change).'),

package/dist/tools/create-spec.js

@@ -16,7 +16,8 @@ import { compactObj } from '../engine/compact-obj.js';
 import { buildCreateSpecSummary } from '../engine/human-summary.js';
 import { runAutoPostCreatePipeline } from './create-spec/auto-pipeline.js';
 import { generateLeanSpecContent } from '../engine/spec-format/lean-spec-generator.js';
-import { generateLeanTechnicalContent } from '../engine/spec-format/lean-technical-generator.js';
+import { generateLeanTechnicalContent, } from '../engine/spec-format/lean-technical-generator.js';
+import { extractFilesFromSpecBody } from '../engine/spec-format/technical-md-populator.js';
 import { buildUnifiedSpecContent } from '../engine/spec-format/unified-spec-builder.js';
 import { validateEnglishOnlySpecText } from '../engine/spec-language/english-only.js';
 import { ApiKeyResolver, FallbackGenerator, OpusGenerator, } from '../engine/spec-generator/index.js';
@@ -104,6 +105,22 @@ function handleClarification(_server, description, knowledge, autopilot, params)
         earlyReturn: interactiveResult(questions, 'The description needs more detail before a spec can be created. Answer the questions, then retry create_spec with clarificationAnswers or an enriched description.', 'universal'),
     };
 }
+function hasFileEntries(files) {
+    return files.create.length + files.modify.length + files.test.length > 0;
+}
+async function resolveTechnicalFiles(input) {
+    const generatedSource = [input.generatedTechnicalSection, input.generatedSpecBody]
+        .filter((part) => part.trim().length > 0)
+        .join('\n\n');
+    const extracted = await extractFilesFromSpecBody(generatedSource, input.projectPath);
+    if (extracted !== null && hasFileEntries(extracted)) {
+        return extracted;
+    }
+    if (input.fallbackReason !== undefined && hasFileEntries(input.autopilot.suggestedFiles)) {
+        return input.autopilot.suggestedFiles;
+    }
+    return { create: [], modify: [], test: [] };
+}
 const HIGH_RISK_WARNING = 'High-risk spec — consider: ' +
     '1) Is the approach technically feasible within the project constraints? ' +
     '2) What edge cases (network failure, concurrent writes, empty state) could break this? ' +
@@ -558,15 +575,18 @@ export async function handleCreateSpec(inputParams, server) {
                     extraCriteria: filteredCriteria,
                     acFormat: params.acFormat,
                 });
-                // SPEC-1011 Bug E: only inject autopilot-guessed files into ## Files body when the
-                // description explicitly contains a ## Files section. Otherwise, keep the spec body
-                // at the placeholder. Suggestions surface only in autopilotSummary.suggestedFiles[].
-                const descriptionHasFilesSection = /^##\s+Files\b/m.test(description);
+                const technicalFiles = await measureStep('resolveTechnicalFiles', () => resolveTechnicalFiles({
+                    generatedSpecBody: generatedSpec.specBody,
+                    generatedTechnicalSection: generatedSpec.technicalSection,
+                    projectPath: params.projectPath ?? '',
+                    autopilot,
+                    fallbackReason: generatedSpec.fallbackReason,
+                }));
                 const leanTechnical = generateLeanTechnicalContent({
                     specId: spec.id,
-                    filesToCreate: descriptionHasFilesSection ? autopilot.suggestedFiles.create : [],
-                    filesToModify: descriptionHasFilesSection ? autopilot.suggestedFiles.modify : [],
-                    filesToTest: descriptionHasFilesSection ? autopilot.suggestedFiles.test : [],
+                    filesToCreate: technicalFiles.create,
+                    filesToModify: technicalFiles.modify,
+                    filesToTest: technicalFiles.test,
                 });
                 // SPEC-709: write unified spec.md from origin — no separate technical.md.
                 // The legacy two-file output is preserved by appending the technical body
@@ -1071,8 +1091,8 @@ export async function handleCreateSpec(inputParams, server) {
             catch {
                 // best-effort — token issuance failure must not block spec creation
             }
-            // SPEC-1011 Bug E: surface autopilot-guessed files in response payload (the ONLY surface
-            // for guesses when description omits ## Files). Never written into spec.md body.
+            // SPEC-1011 Bug E / fallback hardening: surface local file analysis in the response payload.
+            // Those paths are also written into ## Files only when used as technical evidence.
             const suggestedFilesPayload = autopilot.suggestedFiles.create.length +
                 autopilot.suggestedFiles.modify.length +
                 autopilot.suggestedFiles.test.length >

package/dist/tools/generate-batch-script.js

@@ -1,11 +1,12 @@
 // tools/generate-batch-script.ts — Handle generate_batch_script tool calls (SPEC-253)
 import { z } from 'zod';
 import { generateBatchScript } from '../engine/batch-script-generator/index.js';
+import { SpecIdSchema } from './schemas/index.js';
 export const GenerateBatchScriptInputSchema = z.object({
     projectPath: z.string().describe('Absolute path to the project root'),
     taskDescription: z.string().describe('What claude -p should do to each file'),
     fileGlob: z.string().describe("Glob pattern for files, e.g. 'src/**/*.ts'"),
-    specId: z.string().optional().describe('SPEC ID for naming the output script, e.g. SPEC-253'),
+    specId: SpecIdSchema.optional().describe('SPEC ID for naming the output script, e.g. SPEC-253'),
     allowedTools: z
         .array(z.string())
         .optional()

package/dist/tools/generate-proposal.js

@@ -6,10 +6,11 @@ import { hashProjectPath, projectDataDir } from '../storage/base-store.js';
 import { specStore, knowledgeStore, decisionStore, metricsStore } from '../storage/index.js';
 import { loadAllRiskRegisters } from '../storage/risk-store.js';
 import { generateProposal } from '../engine/doc-generator/proposal/proposal-generator.js';
+import { SpecIdSchema } from './schemas/index.js';
 // ── Zod schema ────────────────────────────────────────────────────────────────
 const PhaseSchema = z.object({
     name: z.string().describe('Phase name (e.g. "Phase 1 — Core", "MVP")'),
-    specIds: z.array(z.string()).describe('List of spec IDs included in this phase'),
+    specIds: z.array(SpecIdSchema).describe('List of spec IDs included in this phase'),
     color: z
         .string()
         .optional()

package/dist/tools/generate-tests/adapters/contract-testing-adapter.js

@@ -56,10 +56,16 @@ export function buildContractMockSummaryLines(specTitle, knowledge) {
         '### Mock Server',
         '',
         `**Tool:** ${tool} (auto-detected)`,
-        `**Mocks:** ${endpoints.length} endpoint mocks with realistic sample data`,
-        '**Features:** Simulated delay (250ms), error scenarios (400/401/403/404/500)',
+        `**Mocks:** ${endpoints.length} endpoint mocks generated from explicit contracts`,
+        ...(endpoints.length === 0
+            ? [
+                '> No endpoints were provided; Planu did not fabricate API paths, status codes, or mock payloads.',
+            ]
+            : []),
         '',
-        '> Frontend developers can use these mocks to work independently of the backend.',
+        ...(endpoints.length > 0
+            ? ['> Frontend developers can use these mocks to work independently of the backend.']
+            : []),
         '',
     ];
     return lines;

package/dist/tools/heal-spec-docs.js

@@ -2,7 +2,7 @@
 // SPEC-715: heal_spec_docs is now the SINGLE tool that performs migrations.
 //           list_specs is read-only; migrations were moved here.
 // SPEC-724: Added dryRun, backup flags and Jaccard goal-scenario drift warning.
-import { readFile, readdir } from 'node:fs/promises';
+import { readFile, readdir, rm } from 'node:fs/promises';
 import { atomicWriteFile } from '../engine/safety/atomic-write-file.js';
 import { join } from 'node:path';
 import { hashProjectPath } from '../storage/base-store.js';
@@ -46,33 +46,13 @@ function isPlaceholderTechnical(content) {
     }
     return false;
 }
-// ---------------------------------------------------------------------------
-// File entry generation
-// ---------------------------------------------------------------------------
-function buildFileEntries(type, isDone) {
-    const status = isDone ? '(done)' : '(pending)';
-    // SPEC-579: never fabricate paths from title slug — produces garbage like
-    // `src/tools/<spanish-title-slug>.ts` for paths that do not exist.
-    // Always return placeholders; real paths are populated manually or by
-    // detection tools (scan_project, link_pr_to_spec, sync_spec_from_code).
-    if (type === 'refactor') {
-        return [
-            `- modify: (to be determined by implementation) ${status}`,
-            `- test: (to be determined) ${status}`,
-        ];
-    }
-    if (type === 'bugfix' || type === 'fix') {
-        return [
-            `- modify: (affected files TBD) ${status}`,
-            `- test: tests/ (regression test) ${status}`,
-        ];
-    }
-    return [`- modify: (to be determined) ${status}`];
+function hasInlineTechnicalFilesPlaceholder(content) {
+    return /^##\s+Technical\b[\s\S]*?^##\s+Files\b[\s\S]*?(?:\(pending\)|\(to be determined\)|\bTBD\b|--[a-z])/im.test(content);
 }
 // ---------------------------------------------------------------------------
-// Technical section writer (SPEC-1010 PR-C: writes into spec.md ## Technical)
+// File entry generation
 // ---------------------------------------------------------------------------
-async function writeTechnicalMd(specDir, specId, type, isDone, projectPath, specBody) {
+async function writeTechnicalMd(specDir, isDone, projectPath, specBody) {
     // SPEC-586: Try to extract real file paths from spec body before using placeholders
     let extractedBody = null;
     if (projectPath && specBody !== undefined) {
@@ -102,18 +82,13 @@ async function writeTechnicalMd(specDir, specId, type, isDone, projectPath, spec
             // best-effort — fall through to placeholder
         }
     }
-    const fileEntries = buildFileEntries(type, isDone);
-    // Build the body for the ## Technical section (no outer heading — replaceSectionInSpec adds it)
-    const technicalBody = extractedBody ??
-        [
-            `## Files — ${specId}`,
-            ...fileEntries,
-            '',
-            '## Notes',
-            `> Auto-generated by heal_spec_docs (SPEC-493). Review and update paths as needed.`,
-            '',
-        ].join('\n');
     const specMdPath = join(specDir, 'spec.md');
+    if (extractedBody === null) {
+        const removedInline = await removeTechnicalSectionIfPlaceholder(specMdPath);
+        const removedLegacy = await removeLegacyTechnicalPlaceholder(join(specDir, 'technical.md'));
+        return removedInline || removedLegacy;
+    }
+    const technicalBody = extractedBody;
     // SPEC-579: idempotency check — skip write if section already matches.
     try {
         const existing = await readFile(specMdPath, 'utf-8');
@@ -128,13 +103,74 @@ async function writeTechnicalMd(specDir, specId, type, isDone, projectPath, spec
     await replaceSectionInSpec(specMdPath, 'Technical', technicalBody);
     return true;
 }
+async function removeLegacyTechnicalPlaceholder(technicalPath) {
+    let legacy;
+    try {
+        legacy = await readFile(technicalPath, 'utf-8');
+    }
+    catch {
+        return false;
+    }
+    if (!isPlaceholderTechnical(legacy)) {
+        return false;
+    }
+    await rm(technicalPath, { force: true });
+    return true;
+}
+async function removeTechnicalSectionIfPlaceholder(specMdPath) {
+    let existing;
+    try {
+        existing = await readFile(specMdPath, 'utf-8');
+    }
+    catch {
+        return false;
+    }
+    const currentTechnical = extractTechnicalBodyLocal(existing);
+    if (currentTechnical === '' || !isPlaceholderTechnical(currentTechnical)) {
+        return false;
+    }
+    const updated = removeTopLevelSection(existing, 'Technical');
+    if (updated === existing) {
+        return false;
+    }
+    await atomicWriteFile(specMdPath, updated);
+    return true;
+}
+function removeTopLevelSection(content, sectionName) {
+    const normalized = content.replace(/\r\n/g, '\n');
+    const masked = normalized.replace(/(```|~~~)[\s\S]*?\1/g, (block) => block.replace(/[^\n]/g, ' '));
+    const headingRe = new RegExp(`^##\\s+${escapeRegex(sectionName)}\\b.*$`, 'm');
+    const match = headingRe.exec(masked);
+    if (!match) {
+        return content;
+    }
+    const afterHeading = match.index + match[0].length;
+    const nextRe = /^##\s+\S/gm;
+    nextRe.lastIndex = afterHeading;
+    const next = nextRe.exec(masked);
+    const before = normalized.slice(0, match.index).trimEnd();
+    const after = next ? normalized.slice(next.index).trimStart() : '';
+    if (before.length === 0) {
+        return after.length > 0 ? `${after.trimEnd()}\n` : '';
+    }
+    if (after.length === 0) {
+        return `${before}\n`;
+    }
+    return `${before}\n\n${after.trimEnd()}\n`;
+}
+function escapeRegex(input) {
+    return input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
 /** Local extraction of ## Technical body to avoid circular imports. */
 function extractTechnicalBodyLocal(content) {
+    return extractSectionBodyLocal(content, 'Technical') ?? '';
+}
+function extractSectionBodyLocal(content, sectionName) {
     const normalized = content.replace(/\r\n/g, '\n');
     const masked = normalized.replace(/(```|~~~)[\s\S]*?\1/g, (block) => block.replace(/[^\n]/g, ' '));
-    const headingMatch = /^##\s+Technical\b.*$/m.exec(masked);
+    const headingMatch = new RegExp(`^##\\s+${escapeRegex(sectionName)}\\b.*$`, 'm').exec(masked);
     if (!headingMatch) {
-        return '';
+        return null;
     }
     const afterHeading = headingMatch.index + headingMatch[0].length;
     const nextRe = /^##\s+\S/gm;
@@ -271,9 +307,11 @@ export async function handleHealSpecDocs(params) {
         let legacyContent = null;
         // Determine whether healing is needed
         let needsHeal;
+        const inlinePlaceholder = technicalInSpecMd !== null &&
+            (isPlaceholderTechnical(technicalInSpecMd) || hasInlineTechnicalFilesPlaceholder(spec.body));
         if (technicalInSpecMd !== null) {
             // Check if the inline section is a placeholder
-            needsHeal = isPlaceholderTechnical(technicalInSpecMd);
+            needsHeal = inlinePlaceholder;
         }
         else {
             // No inline section — try standalone technical.md (legacy)
@@ -326,9 +364,27 @@ export async function handleHealSpecDocs(params) {
                 }
             }
         }
+        if (inlinePlaceholder) {
+            const specContent = await readFile(specMdPath, 'utf-8').catch(() => '');
+            let updated = removeTopLevelSection(specContent, 'Technical');
+            const filesBody = extractSectionBodyLocal(updated, 'Files');
+            if (filesBody !== null && isPlaceholderTechnical(filesBody)) {
+                updated = removeTopLevelSection(updated, 'Files');
+            }
+            if (updated !== specContent) {
+                await atomicWriteFile(specMdPath, updated);
+                healed += 1;
+            }
+            continue;
+        }
+        if (legacyContent !== null && isPlaceholderTechnical(legacyContent)) {
+            await rm(technicalPath, { force: true });
+            healed += 1;
+            continue;
+        }
         const isDone = spec.status === 'done' || spec.status === 'implemented';
         try {
-            const wrote = await writeTechnicalMd(spec.dir, spec.specId, spec.type, isDone, projectPath, spec.body);
+            const wrote = await writeTechnicalMd(spec.dir, isDone, projectPath, spec.body);
             if (wrote) {
                 healed += 1;
             }