@planu/cli 4.3.20 → 4.3.21

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [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-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/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/register-agent-squad-tools.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { safeLicensed, safeTracked } from './safe-handler.js';
+import { SpecIdSchema } from './schemas/index.js';
 import { onAutopilotEvent } from '../engine/autopilot/event-bus.js';
 import { dispatchSquadForPhase } from '../engine/agent-squad/dispatcher.js';
 import { getSquadConfig, setAgentEnabled, getSpecRunHistory, getSquadRuns, } from '../storage/agent-squad-store.js';
@@ -143,7 +144,7 @@ export function registerAgentSquadTools(server) {
             'which agents ran, their verdict, and when.',
         inputSchema: {
             projectPath: z.string().min(1).max(4096).describe('Absolute path to the project root.'),
-            specId: z.string().min(1).max(100).describe('Spec ID to query (e.g. SPEC-550).'),
+            specId: SpecIdSchema.describe('Spec ID to query (e.g. SPEC-550).'),
         },
     }, safeTracked('agent_run_history', async (args) => {
         const { projectPath, specId } = args;

package/dist/tools/register-platform-tools/design-stack-tools.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { t } from '../../i18n/index.js';
 import { safeTracked, safeLicensed } from '../safe-handler.js';
-import { AgentPlatformEnum, SubAgentFrameworkEnum, ChallengeSpecFocusEnum, } from '../schemas/index.js';
+import { AgentPlatformEnum, SubAgentFrameworkEnum, ChallengeSpecFocusEnum, SpecIdSchema, } from '../schemas/index.js';
 import { handleGenerateADR } from '../generate-adr.js';
 import { handleDesignSchema } from '../design-schema.js';
 import { handleDefineUIContract } from '../define-ui-contract.js';
@@ -25,7 +25,7 @@ export function registerDesignStackTools(server) {
         description: t('tools.generate_adr.description'),
         annotations: { readOnlyHint: true },
         inputSchema: {
-            specId: z.string().max(500).describe('Spec ID'),
+            specId: SpecIdSchema.describe('Spec ID'),
             projectId: z.string().max(500).describe('Project ID'),
             decisions: z
                 .array(z.string().max(10_000))
@@ -39,7 +39,7 @@ export function registerDesignStackTools(server) {
         description: t('tools.design_schema.description'),
         annotations: { readOnlyHint: true },
         inputSchema: {
-            specId: z.string().max(500).describe('Spec ID'),
+            specId: SpecIdSchema.describe('Spec ID'),
             projectId: z.string().max(500).describe('Project ID'),
             description: z
                 .string()
@@ -53,7 +53,7 @@ export function registerDesignStackTools(server) {
         description: t('tools.define_ui_contract.description'),
         annotations: { readOnlyHint: true },
         inputSchema: {
-            specId: z.string().max(500).describe('Spec ID'),
+            specId: SpecIdSchema.describe('Spec ID'),
             projectId: z.string().max(500).describe('Project ID'),
             screens: z
                 .array(z.string().max(500))
@@ -67,7 +67,7 @@ export function registerDesignStackTools(server) {
         description: t('tools.challenge_spec.description'),
         annotations: { readOnlyHint: true },
         inputSchema: {
-            specId: z.string().max(500).describe('Spec ID to challenge'),
+            specId: SpecIdSchema.describe('Spec ID to challenge'),
             projectId: z
                 .string()
                 .max(500)
@@ -90,7 +90,7 @@ export function registerDesignStackTools(server) {
         description: t('tools.generate_execution_plan.description'),
         annotations: { readOnlyHint: true },
         inputSchema: {
-            specId: z.string().max(500).describe('Spec ID'),
+            specId: SpecIdSchema.describe('Spec ID'),
             projectId: z.string().max(500).describe('Project ID'),
         },
     }, safeTracked('generate_execution_plan', async (args) => handleGenerateExecutionPlan(args)));
@@ -145,7 +145,7 @@ export function registerDesignStackTools(server) {
                 .describe('Skill type: project-rules | domain-skill | workflow | convention'),
             name: z.string().max(500).describe('Skill name'),
             description: z.string().max(10_000).describe('Skill description'),
-            specId: z.string().max(500).optional().describe('Spec ID for context'),
+            specId: SpecIdSchema.optional().describe('Spec ID for context'),
         },
     }, safeLicensed('generate_skill', async (args) => handleGenerateSkill(args)));
     // 28. detect_agent
@@ -208,10 +208,10 @@ export function registerDesignStackTools(server) {
         annotations: { readOnlyHint: true },
         inputSchema: {
             specIds: z
-                .array(z.string().max(500))
+                .array(SpecIdSchema)
                 .min(1)
                 .max(100)
-                .describe('List of spec IDs to run in parallel (e.g. ["SPEC-013", "SPEC-014a"])'),
+                .describe('List of canonical spec IDs to run in parallel (e.g. ["SPEC-013", "SPEC-014"])'),
             projectPath: z.string().max(4096).describe('Absolute path to the project root'),
             mainBranch: z.string().max(500).optional().describe('Main branch name (default: main)'),
             baseBranch: z
@@ -226,7 +226,7 @@ export function registerDesignStackTools(server) {
         description: 'Adversarial review — argues against the spec from first principles before approval. Runs pre-mortem, surfaces hidden assumptions, proposes alternatives.',
         annotations: { readOnlyHint: true },
         inputSchema: {
-            specId: z.string().max(500).describe('Spec ID to red-team'),
+            specId: SpecIdSchema.describe('Spec ID to red-team'),
             projectId: z.string().max(500).describe('Project ID'),
             intensity: z
                 .enum(['light', 'full'])

package/dist/tools/register-platform-tools/lifecycle-infra-tools.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { t } from '../../i18n/index.js';
 import { safeTracked, safeLicensed } from '../safe-handler.js';
-import { DocumentationTypeEnum, GitActionEnum, DevLifecycleCategoryEnum, PMPlatformEnum, PMActionEnum, OrchestrateActionEnum, ManageContextActionEnum, ContextBudgetActionEnum, } from '../schemas/index.js';
+import { DocumentationTypeEnum, GitActionEnum, DevLifecycleCategoryEnum, PMPlatformEnum, PMActionEnum, OrchestrateActionEnum, ManageContextActionEnum, ContextBudgetActionEnum, SpecIdSchema, } from '../schemas/index.js';
 import { handleSuggestTooling } from '../suggest-tooling.js';
 import { handleGenerateTests } from '../generate-tests.js';
 import { handleGenerateDocs } from '../generate-docs.js';
@@ -21,7 +21,7 @@ export function registerLifecycleInfraTools(server) {
         annotations: { readOnlyHint: true },
         inputSchema: {
             projectId: z.string().max(500).describe('Project ID'),
-            specId: z.string().max(500).optional().describe('Spec ID for context'),
+            specId: SpecIdSchema.optional().describe('Spec ID for context'),
             categories: z
                 .array(DevLifecycleCategoryEnum)
                 .optional()
@@ -33,7 +33,7 @@ export function registerLifecycleInfraTools(server) {
         description: t('tools.generate_tests.description'),
         annotations: { readOnlyHint: true },
         inputSchema: {
-            specId: z.string().max(500).describe('Spec ID'),
+            specId: SpecIdSchema.describe('Spec ID'),
             projectId: z.string().max(500).describe('Project ID'),
             autoGenerate: z.boolean().optional().describe('Auto-generate test files (default: false)'),
         },
@@ -49,7 +49,7 @@ export function registerLifecycleInfraTools(server) {
                 .max(100)
                 .describe('Types of documentation to generate'),
             docType: DocumentationTypeEnum.optional().describe('Single documentation type for routing — shorthand for types: [docType]'),
-            specId: z.string().max(500).optional().describe('Spec ID for context'),
+            specId: SpecIdSchema.optional().describe('Spec ID for context'),
             audience: z
                 .enum(['end-user', 'developer', 'stakeholder', 'ops'])
                 .optional()
@@ -88,7 +88,7 @@ export function registerLifecycleInfraTools(server) {
         inputSchema: {
             projectId: z.string().max(500).describe('Project ID'),
             action: GitActionEnum.describe('Git action to perform'),
-            specId: z.string().max(500).optional().describe('Spec ID for context'),
+            specId: SpecIdSchema.optional().describe('Spec ID for context'),
             config: z
                 .object({
                 branchPrefix: z.record(z.string().max(500), z.string().max(500)).optional(),
@@ -113,10 +113,10 @@ export function registerLifecycleInfraTools(server) {
             projectId: z.string().max(500).describe('Project ID'),
             action: OrchestrateActionEnum.describe('Orchestration action'),
             sessionId: z.string().max(500).optional().describe('Agent session ID'),
-            specId: z.string().max(500).optional().describe('Spec ID for context'),
+            specId: SpecIdSchema.optional().describe('Spec ID for context'),
             resourcePath: z.string().max(4096).optional().describe('Resource path to lock/unlock'),
             specIds: z
-                .array(z.string().max(500))
+                .array(SpecIdSchema)
                 .max(100)
                 .optional()
                 .describe('List of spec IDs for pre-check'),
@@ -163,7 +163,7 @@ export function registerLifecycleInfraTools(server) {
             projectId: z.string().max(500).describe('Project ID'),
             platform: PMPlatformEnum.describe('PM platform'),
             action: PMActionEnum.describe('Integration action'),
-            specId: z.string().max(500).optional().describe('Spec ID'),
+            specId: SpecIdSchema.optional().describe('Spec ID'),
             config: z
                 .record(z.string().max(500), z.string().max(10_000))
                 .optional()

package/dist/tools/register-spec-tools/analysis-tools.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { t } from '../../i18n/index.js';
 import { safeTracked, safeLicensed } from '../safe-handler.js';
-import { ChecklistFocusEnum, AuditCategoryEnum } from '../schemas/index.js';
+import { ChecklistFocusEnum, AuditCategoryEnum, SpecIdSchema } from '../schemas/index.js';
 import { resolveProjectId, missingProjectIdError } from '../resolve-project-id.js';
 import { handleDetectDrift } from '../detect-drift.js';
 import { handleSummarizeSpec } from '../summarize-spec.js';
@@ -27,7 +27,7 @@ export function registerAnalysisTools(server) {
     server.registerTool('detect_drift', {
         description: t('tools.detect_drift.description'),
         inputSchema: {
-            specId: z.string().min(1).max(500).describe('Spec ID to check'),
+            specId: SpecIdSchema.describe('Spec ID to check'),
             projectId: z.string().max(500).optional().describe('Project ID hash. Prefer projectPath.'),
             projectPath: z
                 .string()
@@ -56,7 +56,7 @@ export function registerAnalysisTools(server) {
         description: t('tools.summarize_spec.description'),
         annotations: { readOnlyHint: true },
         inputSchema: {
-            specId: z.string().min(1).max(500).describe('Spec ID to summarize'),
+            specId: SpecIdSchema.describe('Spec ID to summarize'),
             projectId: z.string().max(500).optional().describe('Project ID hash. Prefer projectPath.'),
             projectPath: z
                 .string()
@@ -79,7 +79,7 @@ export function registerAnalysisTools(server) {
     server.registerTool('generate_checklist', {
         description: t('tools.generate_checklist.description'),
         inputSchema: {
-            specId: z.string().min(1).max(500).describe('Spec ID'),
+            specId: SpecIdSchema.describe('Spec ID'),
             projectId: z.string().max(500).optional().describe('Project ID hash. Prefer projectPath.'),
             projectPath: z
                 .string()
@@ -103,7 +103,7 @@ export function registerAnalysisTools(server) {
     server.registerTool('reconcile_spec', {
         description: t('tools.reconcile_spec.description'),
         inputSchema: {
-            specId: z.string().min(1).max(500).describe('Spec ID to reconcile'),
+            specId: SpecIdSchema.describe('Spec ID to reconcile'),
             projectId: z.string().max(500).optional().describe('Project ID hash. Prefer projectPath.'),
             projectPath: z
                 .string()
@@ -176,7 +176,7 @@ export function registerAnalysisTools(server) {
                 .max(100)
                 .optional()
                 .describe('Audit categories to check'),
-            specId: z.string().max(500).optional().describe('Spec ID to audit against'),
+            specId: SpecIdSchema.optional().describe('Spec ID to audit against'),
         },
     }, safeLicensed('audit', async (args) => {
         const pid = resolveProjectId(args);
@@ -231,7 +231,7 @@ export function registerAnalysisTools(server) {
                 .max(4096)
                 .optional()
                 .describe('Absolute path to project root. Derives projectId automatically.'),
-            specId: z.string().max(500).optional().describe('Spec ID for context-specific suggestions'),
+            specId: SpecIdSchema.optional().describe('Spec ID for context-specific suggestions'),
         },
     }, safeLicensed('suggest_mcps', async (args) => {
         const pid = resolveProjectId(args);

package/dist/tools/register-spec-tools/core-spec-tools.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { t } from '../../i18n/index.js';
 import { safeTracked, safeLicensed } from '../safe-handler.js';
-import { SupportedLocaleEnum, SpecStatusEnum, SpecTypeEnum, SpecScopeEnum, SpecTargetEnum, ExperienceLevelEnum, WorkModeEnum, ListSpecsOutputSchema, EstimateOutputSchema, ValidateOutputSchema, } from '../schemas/index.js';
+import { SupportedLocaleEnum, SpecStatusEnum, SpecTypeEnum, SpecScopeEnum, SpecTargetEnum, ExperienceLevelEnum, WorkModeEnum, ListSpecsOutputSchema, EstimateOutputSchema, ValidateOutputSchema, SpecIdSchema, } from '../schemas/index.js';
 import { handleSetLocale } from '../set-locale.js';
 import { handleInitProject } from '../init-project.js';
 import { handleSetWorkMode } from '../set-work-mode-handler.js';
@@ -274,7 +274,7 @@ export function registerCoreSpecTools(server) {
     server.registerTool('update_status', {
         description: t('tools.update_status.description'),
         inputSchema: {
-            specId: z.string().min(1).max(500).describe('Spec ID to update'),
+            specId: SpecIdSchema.describe('Spec ID to update'),
             projectId: z
                 .string()
                 .max(500)
@@ -379,7 +379,7 @@ export function registerCoreSpecTools(server) {
     server.registerTool('update_status_batch', {
         description: 'Batch update many specs to the same status in one MCP execution. Uses the same transition rules as update_status and reports updated/skipped/failed per spec.',
         inputSchema: {
-            specIds: z.array(z.string().min(1).max(500)).min(1).describe('Spec IDs to update'),
+            specIds: z.array(SpecIdSchema).min(1).describe('Spec IDs to update'),
             projectId: z.string().max(500).optional().describe('Project ID, if known'),
             projectPath: z
                 .string()
@@ -399,7 +399,7 @@ export function registerCoreSpecTools(server) {
     server.registerTool('estimate', {
         description: t('tools.estimate.description'),
         inputSchema: {
-            specId: z.string().max(500).describe('Spec ID to estimate'),
+            specId: SpecIdSchema.describe('Spec ID to estimate'),
             projectId: z.string().max(500).describe('Project ID'),
         },
         outputSchema: EstimateOutputSchema,
@@ -420,7 +420,7 @@ export function registerCoreSpecTools(server) {
     server.registerTool('validate', {
         description: t('tools.validate.description'),
         inputSchema: {
-            specId: z.string().max(500).describe('Spec ID to validate'),
+            specId: SpecIdSchema.describe('Spec ID to validate'),
             projectId: z
                 .string()
                 .max(500)
@@ -441,7 +441,7 @@ export function registerCoreSpecTools(server) {
             'and missing parameter type annotations. Returns a health score (0-100) and actionable suggestions.',
         inputSchema: {
             projectPath: z.string().max(4096).describe('Absolute path to the project root'),
-            specId: z.string().min(1).max(500).describe('Spec ID being validated'),
+            specId: SpecIdSchema.describe('Spec ID being validated'),
             waiver: z
                 .array(z.string().max(4096))
                 .max(100)

package/dist/tools/render-spec-for-provider.js

@@ -8,9 +8,10 @@ import { detectLLMClient } from '../engine/client-detection.js';
 import { getRegisteredProviders, getRenderer, llmClientToProvider, } from '../engine/provider-adapters/registry.js';
 import { loadSpecForRendering } from '../engine/provider-adapters/shared/spec-loader.js';
 import { compactError, compactResult, formatKeyValue } from './output-formatter.js';
+import { SpecIdSchema } from './schemas/index.js';
 const PROVIDER_VALUES = ['claude', 'gpt4', 'gemini', 'markdown'];
 export const RenderSpecForProviderInputSchema = z.object({
-    specId: z.string().describe('Spec identifier, e.g. "SPEC-670"'),
+    specId: SpecIdSchema.describe('Spec identifier, e.g. "SPEC-670"'),
     projectPath: z.string().describe('Absolute path to the project root'),
     provider: z
         .enum(PROVIDER_VALUES)

package/dist/tools/schemas/github.js

@@ -1,7 +1,8 @@
 // schemas/github.ts — Zod schemas for GitHub integration tools (SPEC-086).
 import { z } from 'zod';
+import { SpecIdSchema } from './spec-id.js';
 export const CreatePRFromSpecSchema = z.object({
-    specId: z.string().min(1).max(500).describe('ID of the spec (e.g., SPEC-086)'),
+    specId: SpecIdSchema.describe('ID of the spec (e.g., SPEC-086)'),
     baseBranch: z
         .string()
         .max(500)
@@ -11,7 +12,7 @@ export const CreatePRFromSpecSchema = z.object({
 });
 export const PRStatusSchema = z.object({
     prNumber: z.number().optional().describe('Specific PR number to query'),
-    specId: z.string().max(500).optional().describe('Spec ID to find related PRs (e.g., SPEC-086)'),
+    specId: SpecIdSchema.optional().describe('Spec ID to find related PRs (e.g., SPEC-086)'),
     view: z.enum(['prs', 'milestones']).default('prs').describe('View mode: prs | milestones'),
 });
 export const ReviewPRSchema = z.object({
@@ -55,7 +56,7 @@ export const GenerateChangelogSchema = z.object({
         .describe('Write the generated changelog to CHANGELOG.md (prepends to existing file). Default: false.'),
 });
 export const CreateIssueFromSpecSchema = z.object({
-    specId: z.string().min(1).max(500).describe('ID of the spec (e.g., SPEC-086)'),
+    specId: SpecIdSchema.describe('ID of the spec (e.g., SPEC-086)'),
     criteriaIds: z
         .array(z.string().max(500))
         .max(1000)

package/dist/tools/schemas/index.d.ts

@@ -1,4 +1,5 @@
 export { SupportedLocaleEnum, SpecStatusEnum, SpecTypeEnum, SpecScopeEnum, SpecTargetEnum, ExperienceLevelEnum, WorkModeEnum, } from './spec.js';
+export { SPEC_ID_PATTERN, SPEC_DIR_NAME_PATTERN, SpecIdSchema, SpecDirNameSchema, isCanonicalSpecId, } from './spec-id.js';
 export { AuditCategoryEnum, ChecklistFocusEnum, ChallengeSpecFocusEnum } from './analysis.js';
 export { AgentPlatformEnum, SubAgentFrameworkEnum } from './agents.js';
 export { DocumentationTypeEnum, GitActionEnum, DevLifecycleCategoryEnum, PMPlatformEnum, PMActionEnum, } from './lifecycle.js';

package/dist/tools/schemas/index.js

@@ -1,5 +1,6 @@
 // schemas/index.ts — Barrel re-export for all Zod enum schemas.
 export { SupportedLocaleEnum, SpecStatusEnum, SpecTypeEnum, SpecScopeEnum, SpecTargetEnum, ExperienceLevelEnum, WorkModeEnum, } from './spec.js';
+export { SPEC_ID_PATTERN, SPEC_DIR_NAME_PATTERN, SpecIdSchema, SpecDirNameSchema, isCanonicalSpecId, } from './spec-id.js';
 export { AuditCategoryEnum, ChecklistFocusEnum, ChallengeSpecFocusEnum } from './analysis.js';
 export { AgentPlatformEnum, SubAgentFrameworkEnum } from './agents.js';
 export { DocumentationTypeEnum, GitActionEnum, DevLifecycleCategoryEnum, PMPlatformEnum, PMActionEnum, } from './lifecycle.js';

package/dist/tools/schemas/spec-id.d.ts

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+export declare const SPEC_ID_PATTERN: RegExp;
+export declare const SPEC_DIR_NAME_PATTERN: RegExp;
+export declare const SpecIdSchema: z.ZodString;
+export declare const SpecDirNameSchema: z.ZodString;
+export declare function isCanonicalSpecId(value: string): boolean;
+//# sourceMappingURL=spec-id.d.ts.map

package/dist/tools/schemas/spec-id.js

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+export const SPEC_ID_PATTERN = /^SPEC-\d+$/;
+export const SPEC_DIR_NAME_PATTERN = /^SPEC-\d+(?:-[a-z0-9]+(?:-[a-z0-9]+)*)?$/;
+export const SpecIdSchema = z
+    .string()
+    .min(1)
+    .max(50)
+    .regex(SPEC_ID_PATTERN, 'Spec ID must use canonical numeric format like SPEC-042.');
+export const SpecDirNameSchema = z
+    .string()
+    .min(1)
+    .max(200)
+    .regex(SPEC_DIR_NAME_PATTERN, 'Spec directory must start with a canonical numeric ID like SPEC-042 or SPEC-042-my-feature.');
+export function isCanonicalSpecId(value) {
+    return SPEC_ID_PATTERN.test(value);
+}
+//# sourceMappingURL=spec-id.js.map

package/dist/tools/spec-prompt-handler.js

@@ -4,6 +4,7 @@ import { getSpec } from '../storage/spec-store.js';
 import { hashProjectPath } from '../storage/base-store.js';
 import { generatePromptFromSpec } from '../engine/spec-prompt-generator.js';
 import { compactResult } from './output-formatter.js';
+import { SpecIdSchema } from './schemas/index.js';
 // ---------------------------------------------------------------------------
 // In-memory registry of registered prompts for this session
 // ---------------------------------------------------------------------------
@@ -12,7 +13,7 @@ export const registeredPrompts = new Map();
 // Zod schemas
 // ---------------------------------------------------------------------------
 const ExposeSpecAsPromptInputSchema = {
-    specId: z.string().describe('The spec ID to expose as an MCP prompt (e.g. "SPEC-042")'),
+    specId: SpecIdSchema.describe('The spec ID to expose as an MCP prompt (e.g. "SPEC-042")'),
     projectPath: z.string().describe('Absolute path to the project root where the spec is stored'),
     promptName: z
         .string()

package/dist/tools/tool-registry/core-tools.js

@@ -10,6 +10,7 @@
 // To add a tool: import its handler + schema, add an entry to the array.
 // To read them: import coreToolsRegistry from this file.
 import { z } from 'zod';
+import { SpecIdSchema } from '../schemas/index.js';
 // ── Handlers ────────────────────────────────────────────────────────────────
 import { GenerateBatchScriptInputSchema, handleGenerateBatchScript, } from '../generate-batch-script.js';
 import { GenerateAutomationGuideInputSchema, handleGenerateAutomationGuide, } from '../generate-automation-guide.js';
@@ -373,7 +374,7 @@ const coreToolsRegistry = [
             '(structured JSON optimized for autonomous coding agents: Devin, Kiro, SWE-agent, generic). ' +
             'Writes files to .specify/specs/{slug}/ by default.',
         schema: {
-            specId: z.string().min(1).max(500).describe('Spec ID to export (e.g. "SPEC-001")'),
+            specId: SpecIdSchema.describe('Spec ID to export (e.g. "SPEC-001")'),
             projectPath: z.string().min(1).max(2000).describe('Absolute path to the project root'),
             format: z
                 .enum(['spec-kit', 'agent-ready'])
@@ -687,7 +688,7 @@ const coreToolsRegistry = [
             'detects drift, and updates the ## Progress section of spec.md with real coverage data. ' +
             'Works entirely offline — pure local file analysis.',
         schema: {
-            specId: z.string().min(1).max(500).describe('Spec ID, e.g. SPEC-042'),
+            specId: SpecIdSchema.describe('Spec ID, e.g. SPEC-042'),
             projectPath: z.string().min(1).max(4096).describe('Absolute path to project root'),
         },
         handler: async (args) => handleReconcileSpecLiving({

package/dist/tools/tool-registry/group-infra.js

@@ -13,7 +13,7 @@ import { safe, safeLicensed, safeTracked } from '../safe-handler.js';
 // ── License tools (register-license-tools.ts) ───────────────────────────────
 import { handleActivateLicense, handleDeactivateLicense } from '../activate-license.js';
 import { handleLicenseStatus } from '../license-status.js';
-import { LicenseStatusOutputSchema } from '../schemas/index.js';
+import { LicenseStatusOutputSchema, SpecIdSchema } from '../schemas/index.js';
 // ── OAuth tools (register-oauth-tools.ts / register-configure-oauth-tool.ts) ─
 import { handleStartOAuthFlow, handleOAuthStatus, StartOAuthFlowInputSchema, OAuthStatusInputSchema, } from '../oauth-handler.js';
 import { handleConfigureOAuth } from '../configure-oauth-handler.js';
@@ -386,7 +386,7 @@ export function registerInfraGroupTools(server) {
         inputSchema: {
             projectPath: z.string().min(1).describe('Absolute path to the project root'),
             provider: deployProviderEnum,
-            specId: z.string().optional().describe('Optional spec ID for traceability'),
+            specId: SpecIdSchema.optional().describe('Optional spec ID for traceability'),
             environment: z
                 .enum(['production', 'preview'])
                 .optional()
@@ -484,7 +484,7 @@ export function registerInfraGroupTools(server) {
                 .string()
                 .min(1)
                 .describe('Absolute path to the project root (e.g. "/home/user/my-app").'),
-            specId: z.string().min(1).describe('Spec ID to validate (e.g. "SPEC-042").'),
+            specId: SpecIdSchema.describe('Spec ID to validate (e.g. "SPEC-042").'),
             baseUrl: z
                 .string()
                 .min(1)

package/dist/tools/tool-registry/group-quality-compliance.js

@@ -49,7 +49,7 @@ import { handleDefineLintRule, handleListLintRules, handleRunSpecLint, handleDel
 // ── Readiness (register-readiness-tools.ts) ───────────────────────────────────
 import { handleCheckReadiness } from '../check-readiness.js';
 import { handlePackageHandoff } from '../package-handoff.js';
-import { CheckReadinessOutputSchema } from '../schemas/index.js';
+import { CheckReadinessOutputSchema, SpecIdSchema } from '../schemas/index.js';
 // ── Approval (register-approval-tools.ts) ────────────────────────────────────
 import { handleConfigureApprovalPolicy, handleApproveSpec, handleRequestChanges, handleApprovalStatus, handleIssueReviewerToken, } from '../approval-handler.js';
 // ── SPEC-961: Architecture lint ─────────────────────────────────────────────
@@ -250,7 +250,7 @@ export function registerQualityComplianceGroupTools(s) {
         description: '[DEPRECATED] Use check_compliance with mode=verify instead. Checks whether implemented code matches an approved spec. Score >=80 = compliant, 60-79 = partial, <60 = non-compliant.',
         annotations: { readOnlyHint: false },
         inputSchema: {
-            specId: z.string().max(500).describe('Spec ID to verify (e.g. SPEC-042).'),
+            specId: SpecIdSchema.describe('Spec ID to verify (e.g. SPEC-042).'),
             projectPath: z
                 .string()
                 .max(4096)
@@ -393,7 +393,7 @@ export function registerQualityComplianceGroupTools(s) {
         description: t('tools.security_check.description'),
         annotations: { readOnlyHint: true },
         inputSchema: {
-            specId: z.string().min(1).max(500).describe('Spec ID to analyze'),
+            specId: SpecIdSchema.describe('Spec ID to analyze'),
             ...projectIdSchema,
             subcommand: z
                 .enum(['analyze', 'score', 'drift'])
@@ -526,7 +526,7 @@ export function registerQualityComplianceGroupTools(s) {
             'Use library="all" to generate schemas for all three libraries at once.',
         inputSchema: {
             projectPath: z.string().min(1).max(4096).describe('Absolute path to the project root.'),
-            specId: z.string().min(1).max(500).describe('Spec ID to analyze (e.g. SPEC-042).'),
+            specId: SpecIdSchema.describe('Spec ID to analyze (e.g. SPEC-042).'),
             library: z
                 .enum(['zod', 'yup', 'valibot', 'all'])
                 .describe('Schema library. Values: zod, yup, valibot, all.'),
@@ -547,7 +547,7 @@ export function registerQualityComplianceGroupTools(s) {
             '"tanstack-query" for React Query hooks.',
         inputSchema: {
             projectPath: z.string().min(1).max(4096).describe('Absolute path to the project root.'),
-            specId: z.string().min(1).max(500).describe('Spec ID to analyze (e.g. SPEC-042).'),
+            specId: SpecIdSchema.describe('Spec ID to analyze (e.g. SPEC-042).'),
             framework: z
                 .enum(['fetch', 'tanstack-query'])
                 .describe('Client framework. Values: fetch, tanstack-query.'),
@@ -583,10 +583,7 @@ export function registerQualityComplianceGroupTools(s) {
         annotations: { readOnlyHint: true },
         inputSchema: {
             projectPath: z.string().describe('Absolute path to the project root'),
-            specId: z
-                .string()
-                .optional()
-                .describe('SPEC-XXX ID to generate acceptance criteria stubs from'),
+            specId: SpecIdSchema.optional().describe('Spec ID to generate acceptance criteria stubs from'),
             registerFile: z
                 .string()
                 .optional()
@@ -598,7 +595,7 @@ export function registerQualityComplianceGroupTools(s) {
         annotations: { readOnlyHint: true },
         inputSchema: {
             projectPath: z.string().describe('Absolute path to the project root'),
-            specId: z.string().optional().describe('SPEC-XXX ID to check readiness/completion for'),
+            specId: SpecIdSchema.optional().describe('Spec ID to check readiness/completion for'),
         },
     }, async (params) => handleTddStatus(params));
     // ── Coverage ─────────────────────────────────────────────────────────────────
@@ -841,7 +838,7 @@ export function registerQualityComplianceGroupTools(s) {
         description: t('tools.check_readiness.description'),
         inputSchema: {
             ...projectIdSchema,
-            specId: z.string().min(1).max(500).describe('Spec ID to evaluate'),
+            specId: SpecIdSchema.describe('Spec ID to evaluate'),
             mode: z
                 .enum(['strict', 'lenient'])
                 .optional()
@@ -962,7 +959,7 @@ export function registerQualityComplianceGroupTools(s) {
         description: t('tools.package_handoff.description'),
         inputSchema: {
             ...projectIdSchema,
-            specId: z.string().min(1).max(500).describe('Spec ID to generate handoff package for'),
+            specId: SpecIdSchema.describe('Spec ID to generate handoff package for'),
         },
     }, safeLicensed('package_handoff', withProject((args) => handlePackageHandoff(args))));
     // ── Approval ─────────────────────────────────────────────────────────────────
@@ -1020,7 +1017,7 @@ export function registerQualityComplianceGroupTools(s) {
             'When the required number of approvals is reached, the approval gate opens.',
         inputSchema: {
             projectPath: z.string().min(1).max(4096).describe('Absolute path to the project root.'),
-            specId: z.string().min(1).max(500).describe('Spec ID to approve (e.g. SPEC-042).'),
+            specId: SpecIdSchema.describe('Spec ID to approve (e.g. SPEC-042).'),
             reviewer: z
                 .string()
                 .describe('Name, email, or username of the reviewer approving the spec.'),
@@ -1073,7 +1070,7 @@ export function registerQualityComplianceGroupTools(s) {
             'time in review, and SLA breach warning if applicable.',
         inputSchema: {
             projectPath: z.string().min(1).max(4096).describe('Absolute path to the project root.'),
-            specId: z.string().min(1).max(500).describe('Spec ID to check (e.g. SPEC-042).'),
+            specId: SpecIdSchema.describe('Spec ID to check (e.g. SPEC-042).'),
         },
         annotations: { title: 'Approval Status', readOnlyHint: true },
     }, safeTracked('approval_status', (args) => handleApprovalStatus(args)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "4.3.20",
+  "version": "4.3.21",
   "description": "Planu — MCP Server for Spec Driven Development with native Rust acceleration for hot paths. Cross-platform (Linux/macOS/Windows, x64/arm64, glibc/musl).",
   "type": "module",
   "main": "dist/index.js",
@@ -34,14 +34,14 @@
     "packageName": "@planu/core"
   },
   "optionalDependencies": {
-    "@planu/core-darwin-arm64": "4.3.20",
-    "@planu/core-darwin-x64": "4.3.20",
-    "@planu/core-linux-arm64-gnu": "4.3.20",
-    "@planu/core-linux-arm64-musl": "4.3.20",
-    "@planu/core-linux-x64-gnu": "4.3.20",
-    "@planu/core-linux-x64-musl": "4.3.20",
-    "@planu/core-win32-arm64-msvc": "4.3.20",
-    "@planu/core-win32-x64-msvc": "4.3.20"
+    "@planu/core-darwin-arm64": "4.3.21",
+    "@planu/core-darwin-x64": "4.3.21",
+    "@planu/core-linux-arm64-gnu": "4.3.21",
+    "@planu/core-linux-arm64-musl": "4.3.21",
+    "@planu/core-linux-x64-gnu": "4.3.21",
+    "@planu/core-linux-x64-musl": "4.3.21",
+    "@planu/core-win32-arm64-msvc": "4.3.21",
+    "@planu/core-win32-x64-msvc": "4.3.21"
   },
   "engines": {
     "node": ">=24.0.0"

package/planu-native.json

@@ -1,7 +1,7 @@
 {
   "name": "dev.planu.native",
   "displayName": "Planu Native Lightweight Surface",
-  "version": "4.3.20",
+  "version": "4.3.21",
   "packageName": "@planu/cli",
   "modes": {
     "lightweight": {

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": "4.3.20",
+  "version": "4.3.21",
   "icon": "assets/plugin/icon.svg",
   "command": [
     "npx",