@planu/cli 4.10.12 → 4.11.0

package/dist/engine/provider-adapters/adapters/claude.js

@@ -1,8 +1,9 @@
 // engine/provider-adapters/adapters/claude.ts — SPEC-670: Claude Code renderer.
 //
-// Emits MCP-shaped output: full canonical markdown plus model hint, budget hint and
-// `mcp__planu__*` tool callouts. Tag-driven enrichment is a follow-up; for v1 we use
-// a static map of spec-tag → recommended Planu MCP tools.
+// Emits MCP-shaped output: full canonical markdown plus evidence-backed execution
+// hints and `mcp__planu__*` tool callouts.
+import { resolveModelId } from '../../model-tier-resolver.js';
+import { resolveExecutionBudget, resolveExecutionTier, } from '../../next-spec-resolver/orchestration-planner.js';
 import { estimateTokens } from '../shared/token-estimator.js';
 /**
  * Static map of spec tag → recommended `mcp__planu__*` tool callouts. A tag-driven
@@ -20,17 +21,31 @@ export const CLAUDE_TOOL_CALLOUT_MAP = Object.freeze({
 });
 export class ClaudeRenderer {
     kind = 'claude';
-    render(input) {
-        const { loadedSpec } = input;
+    async render(input) {
+        const { loadedSpec, projectPath } = input;
         const { spec, specBody, warnings } = loadedSpec;
-        const modelHint = spec.model ?? 'sonnet';
-        const budget = spec.budget ?? 2000;
+        const modelTier = resolveExecutionTier(spec);
+        const model = modelTier ? await resolveModelId(projectPath, modelTier, 'anthropic') : undefined;
+        const budget = resolveExecutionBudget(spec);
+        const explicitLegacyTier = resolveExplicitLegacyTier(spec);
         const toolCallouts = pickToolCallouts(spec.tags);
         const lines = [];
         lines.push(`# ${spec.title}`);
         lines.push('');
-        lines.push(`> Model hint: \`${modelHint}\` — Token budget: \`${budget}\``);
-        lines.push('');
+        const routingHints = [];
+        if (model && modelTier) {
+            routingHints.push(`Model hint: \`${model}\` (tier: \`${modelTier}\`)`);
+        }
+        else if (explicitLegacyTier) {
+            routingHints.push(`Legacy model constraint: \`${explicitLegacyTier}\``);
+        }
+        if (budget !== undefined) {
+            routingHints.push(`Token budget constraint: \`${budget}\``);
+        }
+        if (routingHints.length > 0) {
+            lines.push(`> ${routingHints.join(' — ')}`);
+            lines.push('');
+        }
         lines.push('## Recommended Planu MCP tools');
         for (const callout of toolCallouts) {
             lines.push(`- Run \`${callout}\` to drive this spec forward.`);
@@ -44,19 +59,28 @@ export class ClaudeRenderer {
         }
         const content = lines.join('\n');
         const tokenEstimate = estimateTokens(content);
-        return Promise.resolve({
+        return {
             provider: 'claude',
             content,
             tokenEstimate,
             extras: {
-                modelHint,
-                model: modelHint,
-                budget,
+                ...(model ? { modelHint: model, model } : {}),
+                ...(modelTier && (model || explicitLegacyTier) ? { modelTier } : {}),
+                ...(budget !== undefined ? { budget } : {}),
                 toolCallouts: [...toolCallouts],
                 ...(warnings.length > 0 ? { warnings } : {}),
             },
-        });
+        };
+    }
+}
+function resolveExplicitLegacyTier(spec) {
+    const legacyRecord = spec;
+    const hasCurrentContext = legacyRecord.difficulty !== undefined || legacyRecord.scope !== undefined;
+    if (hasCurrentContext) {
+        return undefined;
     }
+    const value = legacyRecord.model;
+    return value === 'haiku' || value === 'sonnet' || value === 'opus' ? value : undefined;
 }
 function pickToolCallouts(tags) {
     const collected = new Set();

package/dist/engine/scan-project/index.js

@@ -1,7 +1,8 @@
 // engine/scan-project/index.ts — 4-phase orchestrator for scan_project (SPEC-134)
 import { join } from 'node:path';
-import { mkdir, readdir, writeFile } from 'node:fs/promises';
-import { replaceSectionInSpec } from '../spec-format/replace-section.js';
+import { mkdir, readdir } from 'node:fs/promises';
+import { atomicWriteFile } from '../safety/atomic-write-file.js';
+import { serializeValueOnlySpecContent } from '../spec-format/value-only-spec-serializer.js';
 import { discoverModules } from './module-discoverer.js';
 import { analyzeCrossModuleDependencies } from './cross-module-analyzer.js';
 import { calculateProjectHealth } from './health-scorer.js';
@@ -9,7 +10,6 @@ import { generateProjectOverview } from './overview-generator.js';
 import { generateTeamPlan } from './team-planner.js';
 import { runDeepAnalysis } from '../reverse-engineer/index.js';
 import { createSpec, listSpecs } from '../../storage/spec-store.js';
-import { generateProgressContent } from '../progress-writer.js';
 // Re-export submodules for barrel access
 export { discoverModules } from './module-discoverer.js';
 export { analyzeCrossModuleDependencies } from './cross-module-analyzer.js';
@@ -69,14 +69,11 @@ async function analyzeModulesInParallel(projectPath, modules, concurrency) {
 // Phase 4: Spec generation
 // ---------------------------------------------------------------------------
 const SPEC_LOCATION = 'planu/specs';
-async function writeSpecFiles(specDir, spec, body) {
+async function writeSpecFile(specDir, spec, description, criteria, technical) {
     await mkdir(specDir, { recursive: true });
     const specMdPath = join(specDir, 'spec.md');
-    await writeFile(specMdPath, body, 'utf-8');
-    // SPEC-1010 PR-C: embed Technical and Progress into unified spec.md instead of
-    // writing standalone technical.md / progress.md files.
-    await replaceSectionInSpec(specMdPath, 'Technical', `Auto-generated by scan_project.\n`);
-    await replaceSectionInSpec(specMdPath, 'Progress', generateProgressContent(spec));
+    const content = serializeValueOnlySpecContent({ spec, description, criteria, technical });
+    await atomicWriteFile(specMdPath, content);
 }
 async function generateSpecs(input, modules, moduleResults, crossAnalysis, healthScore) {
     const specsGenerated = [];
@@ -102,8 +99,10 @@ async function generateSpecs(input, modules, moduleResults, crossAnalysis, healt
         const specDir = join(input.path, SPEC_LOCATION, `${specId}-${slug}`);
         spec.specPath = join(specDir, 'spec.md');
         spec.technicalPath = spec.specPath;
-        const body = `# ${spec.title}\n\nAuto-generated by scan_project.\n`;
-        await writeSpecFiles(specDir, spec, body);
+        const description = buildModuleDescription(mod, result);
+        const criteria = buildModuleCriteria(mod.name, result, crossAnalysis);
+        const technical = buildModuleTechnical(mod, result, deps);
+        await writeSpecFile(specDir, spec, description, criteria, technical);
         await createSpec(input.projectId, spec);
         specsGenerated.push(specId);
         currentId++;
@@ -128,10 +127,8 @@ async function generateSpecs(input, modules, moduleResults, crossAnalysis, healt
     const overviewDir = join(input.path, SPEC_LOCATION, `${overviewSpecId}-${overviewSlug}`);
     overviewSpec.specPath = join(overviewDir, 'spec.md');
     overviewSpec.technicalPath = overviewSpec.specPath;
-    const overviewBody = overviewContent
-        ? `# Project Overview — Automated Scan\n\n${overviewContent}\n`
-        : `# Project Overview — Automated Scan\n\nAuto-generated by scan_project.\n`;
-    await writeSpecFiles(overviewDir, overviewSpec, overviewBody);
+    const overviewDescription = overviewContent || buildOverviewDescription(modules, healthScore);
+    await writeSpecFile(overviewDir, overviewSpec, overviewDescription, buildOverviewCriteria(crossAnalysis), buildOverviewTechnical(modules));
     await createSpec(input.projectId, overviewSpec);
     return { specsGenerated, overviewSpecId };
 }
@@ -177,8 +174,84 @@ function buildScanSpec(params) {
         gitBranch: params.gitBranch,
         impactAnalysis: null,
         reviewNotes: params.reviewNotes,
+        generation: {
+            method: 'deterministic',
+            generatedAt: now,
+        },
     };
 }
+function buildModuleDescription(module, result) {
+    const lines = [
+        `# Module: ${module.name}`,
+        '',
+        '## Description',
+        '',
+        `\`${module.path}\` contains approximately ${String(module.estimatedFiles)} ${module.language} files.`,
+    ];
+    if (result?.status === 'failed' && result.error) {
+        lines.push('', `Analysis failed: ${result.error}`);
+    }
+    return lines.join('\n');
+}
+function buildModuleCriteria(moduleName, result, crossAnalysis) {
+    const findings = [];
+    for (const path of result?.analysis.testCoverage.untestedModules ?? []) {
+        findings.push(`Add automated coverage for \`${path}\`.`);
+    }
+    for (const antipattern of crossAnalysis.antipatterns) {
+        if (antipattern.modules.includes(moduleName)) {
+            findings.push(antipattern.suggestion);
+        }
+    }
+    for (const cycle of crossAnalysis.circularDeps) {
+        if (cycle.includes(moduleName)) {
+            findings.push(`Remove the detected circular dependency: ${cycle.join(' -> ')}.`);
+        }
+    }
+    if (result?.status === 'failed' && result.error) {
+        findings.push(`Restore static analysis for \`${moduleName}\`: ${result.error}`);
+    }
+    return [...new Set(findings)].map((text) => ({ text, done: false }));
+}
+function buildModuleTechnical(module, result, dependencies) {
+    const lines = [
+        '### Scan Evidence',
+        '',
+        `- Path: \`${module.path}\``,
+        `- Language: ${module.language}`,
+        `- Files: ${String(module.estimatedFiles)}`,
+        `- Analysis status: ${result?.status ?? 'missing'}`,
+    ];
+    if (result?.status === 'success') {
+        lines.push(`- Test/source ratio: ${result.analysis.testCoverage.testToSourceRatio.toFixed(2)}`);
+    }
+    if (dependencies.length > 0) {
+        lines.push('', '### Incoming Dependencies', '', ...dependencies.map((name) => `- ${name}`));
+    }
+    return lines.join('\n');
+}
+function buildOverviewDescription(modules, healthScore) {
+    return [
+        '# Project Overview',
+        '',
+        '## Description',
+        '',
+        `${String(modules.length)} modules were detected with health score ${String(healthScore.score)}/100 (${healthScore.grade}).`,
+    ].join('\n');
+}
+function buildOverviewCriteria(crossAnalysis) {
+    return crossAnalysis.antipatterns.map((finding) => ({
+        text: finding.suggestion,
+        done: false,
+    }));
+}
+function buildOverviewTechnical(modules) {
+    return [
+        '### Scanned Modules',
+        '',
+        ...modules.map((module) => `- \`${module.path}\` (${module.language})`),
+    ].join('\n');
+}
 /**
  * Extract the numeric part of a SPEC-NNN string. Returns 0 if no match.
  */

package/dist/engine/spec-format/lean-spec-generator.d.ts

@@ -1,5 +1,5 @@
-import type { LeanCriterion, LeanHistoryEntry, LeanSpecInput } from '../../types/index.js';
-export type { LeanCriterion, LeanHistoryEntry, LeanSpecInput };
+import type { LeanCriterion, LeanSpecInput } from '../../types/index.js';
+export type { LeanCriterion, LeanHistoryEntry, LeanSpecInput } from '../../types/index.js';
 /** Generate lean spec.md content: YAML frontmatter + user description only. */
 export declare function generateLeanSpecContent(input: LeanSpecInput): string;
 /** Extract acceptance criteria from description. Looks for checkbox patterns or generates a default.

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

@@ -1,57 +1,41 @@
 // 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 { deriveModelBudget } from './model-budget-deriver.js';
+import { decideMetadataSerialization, } from './metadata-value-policy.js';
 import { renderGroundingFrontmatter, renderTechnicalReferenceGroundingFrontmatter, } from '../spec-grounding/contract.js';
-/** Strip redundant "SPEC-XXX — " or "SPEC-XXX: " prefix from spec titles.
+/** Strip a redundant spec-ID prefix from spec titles.
  * Titles must not repeat the ID since it is already stored in the `id` field. */
 function sanitizeTitle(title, specId) {
-    // Match "SPEC-123 — ", "SPEC-123: ", "SPEC-123 - " at the start
+    // Match common spec ID separators at the start.
     const prefixRegex = new RegExp(`^${specId}\\s*[—:\\-]\\s*`, 'i');
     return title.replace(prefixRegex, '').trim();
 }
 /** Generate lean spec.md content: YAML frontmatter + user description only. */
 export function generateLeanSpecContent(input) {
-    const { spec, description, estimation, extraCriteria = [], acFormat = 'checkbox' } = input;
+    const { spec, description, extraCriteria = [], acFormat = 'checkbox' } = input;
     const now = spec.createdAt.slice(0, 10); // YYYY-MM-DD
     const cleanTitle = sanitizeTitle(spec.title, spec.id);
-    const history = [{ date: now, event: 'created' }];
-    const { model, budget } = deriveModelBudget(spec.difficulty, estimation.devHours);
-    const frontmatterBase = [
-        '---',
-        `id: ${spec.id}`,
-        ...(spec.uuid ? [`uuid: ${spec.uuid}`] : []),
-        ...(spec.idempotencyKey ? [`idempotencyKey: ${spec.idempotencyKey}`] : []),
-        `title: "${escapeYaml(cleanTitle)}"`,
-        `status: ${spec.status}`,
-        `type: ${spec.type}`,
-        `target: ${spec.target}`,
-        `scope: ${spec.scope}`,
+    const frontmatterBase = ['---'];
+    appendMetadata(frontmatterBase, 'id', spec.id, [`id: ${spec.id}`]);
+    appendMetadata(frontmatterBase, 'title', cleanTitle, [`title: "${escapeYaml(cleanTitle)}"`]);
+    appendMetadata(frontmatterBase, 'status', spec.status, [`status: ${spec.status}`]);
+    appendMetadata(frontmatterBase, 'type', spec.type, [`type: ${spec.type}`]);
+    appendMetadata(frontmatterBase, 'target', spec.target, [`target: ${spec.target}`]);
+    appendMetadata(frontmatterBase, 'scope', spec.scope, [`scope: ${spec.scope}`]);
+    appendMetadata(frontmatterBase, 'difficulty', spec.difficulty, [
         `difficulty: ${String(spec.difficulty)}`,
-        `risk: ${spec.risk}`,
-        `tags: [${spec.tags.join(', ')}]`,
-        `branch: ${spec.gitBranch}`,
-        `created: ${now}`,
-        // SPEC-717: spec format versioning fields
-        `spec_format_version: "1.0"`,
-        `spec_version: "1.0.0"`,
-        `estimation:`,
-        `  devHours: ${String(estimation.devHours)}`,
-        `  reviewHours: ${String(estimation.reviewHours)}`,
-        `  cost: ${String(estimation.totalCostUsd)}`,
-        `  model: ${estimation.recommendedModel}`,
-        `model: ${model}`,
-        `budget: ${String(budget)}`,
-        ...(spec.generatedWithModel ? [`generatedWithModel: ${spec.generatedWithModel}`] : []),
-        ...(spec.generatedAt ? [`generatedAt: ${spec.generatedAt}`] : []),
-        ...(spec.qualityWarnings && spec.qualityWarnings.length > 0
-            ? [`qualityWarnings: ${JSON.stringify(spec.qualityWarnings)}`]
-            : []),
-        ...(input.groundingCriteria ? renderGroundingFrontmatter(input.groundingCriteria) : []),
-        ...(input.groundingTechnicalReferences
-            ? renderTechnicalReferenceGroundingFrontmatter(input.groundingTechnicalReferences)
-            : []),
-    ];
+    ]);
+    appendMetadata(frontmatterBase, 'risk', spec.risk, [`risk: ${spec.risk}`]);
+    appendMetadata(frontmatterBase, 'tags', spec.tags, [`tags: [${spec.tags.join(', ')}]`]);
+    appendMetadata(frontmatterBase, 'branch', spec.gitBranch, [`branch: ${spec.gitBranch}`]);
+    appendMetadata(frontmatterBase, 'created', now, [`created: ${now}`]);
+    appendMetadata(frontmatterBase, 'spec_format_version', '1.0', [`spec_format_version: "1.0"`]);
+    appendMetadata(frontmatterBase, 'spec_version', '1.0.0', [`spec_version: "1.0.0"`]);
+    appendMetadata(frontmatterBase, 'generation', spec.generation, renderGeneration(spec.generation));
+    appendMetadata(frontmatterBase, 'qualityWarnings', spec.qualityWarnings, [
+        `qualityWarnings: ${JSON.stringify(spec.qualityWarnings)}`,
+    ]);
+    appendGroundingMetadata(frontmatterBase, input);
     let acLines;
     if (acFormat === 'bdd') {
         acLines = buildBddLines(description, extraCriteria, input.criteriaOverride, input.scenarioTestPaths ?? []);
@@ -59,18 +43,49 @@ export function generateLeanSpecContent(input) {
     else {
         acLines = buildCheckboxLines(description, extraCriteria, input.criteriaOverride);
     }
-    const lines = [
-        ...frontmatterBase,
-        ...acLines,
-        'history:',
-        ...history.map((h) => `  - date: ${h.date}\n    event: ${h.event}`),
-        '---',
-        '',
-        description.trim(),
-        '',
-    ];
+    appendMetadata(frontmatterBase, acFormat === 'bdd' ? 'scenarios' : 'criteria', acLines.slice(1), acLines);
+    const lines = [...frontmatterBase, '---', '', description.trim(), ''];
     return lines.join('\n');
 }
+function appendMetadata(lines, field, value, rendered) {
+    if (decideMetadataSerialization(field, value).persist) {
+        lines.push(...rendered);
+    }
+}
+function renderGeneration(generation) {
+    if (!generation) {
+        return [];
+    }
+    return [
+        'generation:',
+        `  method: ${generation.method}`,
+        ...(generation.host ? [`  host: "${escapeYaml(generation.host)}"`] : []),
+        ...(generation.modelId && generation.method !== 'deterministic'
+            ? [`  modelId: "${escapeYaml(generation.modelId)}"`]
+            : []),
+        `  generatedAt: "${escapeYaml(generation.generatedAt)}"`,
+    ];
+}
+function appendGroundingMetadata(lines, input) {
+    const criteria = input.groundingCriteria ?? [];
+    const technicalReferences = input.groundingTechnicalReferences ?? [];
+    const hasGrounding = criteria.length > 0 || technicalReferences.length > 0;
+    appendMetadata(lines, 'grounding_required', hasGrounding, ['grounding_required: true']);
+    if (!decideMetadataSerialization('grounding', hasGrounding ? { evidence: true } : undefined).persist) {
+        return;
+    }
+    if (criteria.length > 0) {
+        const [requiredLine, ...groundingLines] = renderGroundingFrontmatter(criteria);
+        void requiredLine;
+        lines.push(...groundingLines);
+    }
+    else {
+        lines.push('grounding:');
+    }
+    if (technicalReferences.length > 0) {
+        lines.push(...renderTechnicalReferenceGroundingFrontmatter(technicalReferences));
+    }
+}
 /** Build checkbox-format criteria lines. */
 function buildCheckboxLines(description, extraCriteria, criteriaOverride) {
     const criteria = criteriaOverride ?? [

package/dist/engine/spec-format/metadata-value-policy.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Single source of truth for metadata written by the new-spec serializer.
+ * Keys match the root YAML fields so adding a writer requires an explicit policy decision.
+ */
+export declare const SPEC_METADATA_VALUE_POLICY: {
+    readonly id: {
+        readonly classification: "required";
+        readonly consumers: readonly [string, ...string[]];
+        readonly purpose: string;
+    };
+    readonly title: {
+        readonly classification: "required";
+        readonly consumers: readonly [string, ...string[]];
+        readonly purpose: string;
+    };
+    readonly status: {
+        readonly classification: "required";
+        readonly consumers: readonly [string, ...string[]];
+        readonly purpose: string;
+    };
+    readonly type: {
+        readonly classification: "required";
+        readonly consumers: readonly [string, ...string[]];
+        readonly purpose: string;
+    };
+    readonly target: {
+        readonly classification: "required";
+        readonly consumers: readonly [string, ...string[]];
+        readonly purpose: string;
+    };
+    readonly scope: {
+        readonly classification: "required";
+        readonly consumers: readonly [string, ...string[]];
+        readonly purpose: string;
+    };
+    readonly difficulty: {
+        readonly classification: "required";
+        readonly consumers: readonly [string, ...string[]];
+        readonly purpose: string;
+    };
+    readonly risk: {
+        readonly classification: "required";
+        readonly consumers: readonly [string, ...string[]];
+        readonly purpose: string;
+    };
+    readonly branch: {
+        readonly classification: "required";
+        readonly consumers: readonly [string, ...string[]];
+        readonly purpose: string;
+    };
+    readonly created: {
+        readonly classification: "required";
+        readonly consumers: readonly [string, ...string[]];
+        readonly purpose: string;
+    };
+    readonly spec_format_version: {
+        readonly classification: "required";
+        readonly consumers: readonly [string, ...string[]];
+        readonly purpose: string;
+    };
+    readonly spec_version: {
+        readonly classification: "required";
+        readonly consumers: readonly [string, ...string[]];
+        readonly purpose: string;
+    };
+    readonly tags: {
+        readonly classification: "conditional";
+        readonly consumers: readonly [string, ...string[]];
+        readonly purpose: string;
+    };
+    readonly generation: {
+        readonly classification: "conditional";
+        readonly consumers: readonly [string, ...string[]];
+        readonly purpose: string;
+    };
+    readonly qualityWarnings: {
+        readonly classification: "conditional";
+        readonly consumers: readonly [string, ...string[]];
+        readonly purpose: string;
+    };
+    readonly grounding_required: {
+        readonly classification: "conditional";
+        readonly consumers: readonly [string, ...string[]];
+        readonly purpose: string;
+    };
+    readonly grounding: {
+        readonly classification: "conditional";
+        readonly consumers: readonly [string, ...string[]];
+        readonly purpose: string;
+    };
+    readonly criteria: {
+        readonly classification: "conditional";
+        readonly consumers: readonly [string, ...string[]];
+        readonly purpose: string;
+    };
+    readonly scenarios: {
+        readonly classification: "conditional";
+        readonly consumers: readonly [string, ...string[]];
+        readonly purpose: string;
+    };
+    readonly history: {
+        readonly classification: "conditional";
+        readonly consumers: readonly [string, ...string[]];
+        readonly purpose: string;
+    };
+    readonly plannerToken: {
+        readonly classification: "external-only";
+        readonly consumers: readonly [];
+        readonly purpose: string;
+    };
+    readonly uuid: {
+        readonly classification: "external-only";
+        readonly consumers: readonly [];
+        readonly purpose: string;
+    };
+    readonly idempotencyKey: {
+        readonly classification: "external-only";
+        readonly consumers: readonly [];
+        readonly purpose: string;
+    };
+    readonly estimation: {
+        readonly classification: "external-only";
+        readonly consumers: readonly [];
+        readonly purpose: string;
+    };
+    readonly model: {
+        readonly classification: "derived-at-execution";
+        readonly consumers: readonly [];
+        readonly purpose: string;
+    };
+    readonly budget: {
+        readonly classification: "derived-at-execution";
+        readonly consumers: readonly [];
+        readonly purpose: string;
+    };
+    readonly generatedWithModel: {
+        readonly classification: "legacy-read-only";
+        readonly consumers: readonly [];
+        readonly purpose: string;
+    };
+    readonly generatedAt: {
+        readonly classification: "legacy-read-only";
+        readonly consumers: readonly [];
+        readonly purpose: string;
+    };
+};
+export declare function getMetadataFieldPolicy(field: keyof typeof SPEC_METADATA_VALUE_POLICY): (typeof SPEC_METADATA_VALUE_POLICY)[keyof typeof SPEC_METADATA_VALUE_POLICY];
+export declare function decideMetadataSerialization(field: keyof typeof SPEC_METADATA_VALUE_POLICY, value: unknown): {
+    readonly field: keyof typeof SPEC_METADATA_VALUE_POLICY;
+    readonly classification: (typeof SPEC_METADATA_VALUE_POLICY)[keyof typeof SPEC_METADATA_VALUE_POLICY]['classification'];
+    readonly persist: boolean;
+    readonly consumers: readonly string[];
+    readonly purpose: string;
+};
+export declare function listMetadataFieldPolicies(): readonly {
+    readonly field: keyof typeof SPEC_METADATA_VALUE_POLICY;
+    readonly classification: (typeof SPEC_METADATA_VALUE_POLICY)[keyof typeof SPEC_METADATA_VALUE_POLICY]['classification'];
+    readonly consumers: readonly string[];
+    readonly purpose: string;
+}[];
+//# sourceMappingURL=metadata-value-policy.d.ts.map

package/dist/engine/spec-format/metadata-value-policy.js

@@ -0,0 +1,87 @@
+const required = (consumers, purpose) => ({ classification: 'required', consumers, purpose });
+const conditional = (consumers, purpose) => ({ classification: 'conditional', consumers, purpose });
+const omitted = (classification, purpose) => ({ classification, consumers: [], purpose });
+/**
+ * Single source of truth for metadata written by the new-spec serializer.
+ * Keys match the root YAML fields so adding a writer requires an explicit policy decision.
+ */
+export const SPEC_METADATA_VALUE_POLICY = {
+    id: required(['spec-store', 'lifecycle-tools'], 'Canonical spec identity.'),
+    title: required(['spec-store', 'list-specs'], 'Human-readable spec identity.'),
+    status: required(['transition-guard', 'spec-store'], 'Lifecycle gate state.'),
+    type: required(['spec-store', 'spec-filters'], 'Work classification.'),
+    target: required(['agent-planner', 'spec-store'], 'Implementation target.'),
+    scope: required(['readiness-gate', 'agent-planner'], 'Implementation breadth.'),
+    difficulty: required(['readiness-gate', 'runtime-routing'], 'Current complexity signal.'),
+    risk: required(['readiness-gate', 'challenge-spec'], 'Delivery risk signal.'),
+    branch: required(['git-manager', 'spec-store'], 'Lifecycle branch association.'),
+    created: required(['spec-store', 'audit-trail'], 'Creation evidence.'),
+    spec_format_version: required(['spec-migrator', 'spec-parser'], 'Schema compatibility.'),
+    spec_version: required(['version-gate', 'bump-spec-version'], 'Content version lifecycle.'),
+    tags: conditional(['spec-search', 'spec-filters'], 'Non-empty discovery labels.'),
+    generation: conditional(['spec-parser', 'provenance-audit'], 'Truthful provenance for the component that produced the current body.'),
+    qualityWarnings: conditional(['readiness-gate', 'spec-health-scorer'], 'Non-empty generator diagnostics that affect review.'),
+    grounding_required: conditional(['grounding-gate'], 'Signals that persisted grounding evidence must pass approval gates.'),
+    grounding: conditional(['grounding-gate'], 'Non-empty criterion or technical evidence.'),
+    criteria: conditional(['readiness-gate', 'validate'], 'Checkbox acceptance contract.'),
+    scenarios: conditional(['readiness-gate', 'validate'], 'BDD acceptance contract.'),
+    history: conditional(['version-gate', 'bump-spec-version'], 'Non-creation content version events.'),
+    plannerToken: omitted('external-only', 'Signed planner identity belongs to lifecycle state.'),
+    uuid: omitted('external-only', 'Operational identity belongs to the project store.'),
+    idempotencyKey: omitted('external-only', 'Retry deduplication belongs to the project store.'),
+    estimation: omitted('external-only', 'Advisory estimation telemetry belongs to tool state.'),
+    model: omitted('derived-at-execution', 'Provider routing uses current execution context.'),
+    budget: omitted('derived-at-execution', 'Token budgets use current execution context.'),
+    generatedWithModel: omitted('legacy-read-only', 'Ambiguous legacy generator provenance.'),
+    generatedAt: omitted('legacy-read-only', 'Legacy timestamp superseded by generation.'),
+};
+export function getMetadataFieldPolicy(field) {
+    return lookupMetadataFieldPolicy(field);
+}
+function lookupMetadataFieldPolicy(field) {
+    if (!Object.hasOwn(SPEC_METADATA_VALUE_POLICY, field)) {
+        throw new Error(`Unknown spec metadata field: ${field}`);
+    }
+    return SPEC_METADATA_VALUE_POLICY[field];
+}
+export function decideMetadataSerialization(field, value) {
+    const policy = lookupMetadataFieldPolicy(field);
+    const hasValue = hasMeaningfulValue(value);
+    if (policy.classification === 'required' && !hasValue) {
+        throw new Error(`Missing required spec metadata value: ${field}`);
+    }
+    return {
+        field,
+        classification: policy.classification,
+        persist: policy.classification === 'required' || (policy.classification === 'conditional' && hasValue),
+        consumers: policy.consumers,
+        purpose: policy.purpose,
+    };
+}
+export function listMetadataFieldPolicies() {
+    return Object.entries(SPEC_METADATA_VALUE_POLICY).map(([field, policy]) => ({
+        field: field,
+        classification: policy.classification,
+        consumers: policy.consumers,
+        purpose: policy.purpose,
+    }));
+}
+function hasMeaningfulValue(value) {
+    if (value === undefined || value === null || value === false) {
+        return false;
+    }
+    if (typeof value === 'string') {
+        return value.trim().length > 0;
+    }
+    if (typeof value === 'number') {
+        return Number.isFinite(value) && value !== 0;
+    }
+    if (Array.isArray(value)) {
+        return value.length > 0;
+    }
+    if (typeof value === 'object') {
+        return Object.keys(value).length > 0;
+    }
+    return true;
+}
+//# sourceMappingURL=metadata-value-policy.js.map

package/dist/engine/spec-format/value-only-spec-serializer.d.ts

@@ -0,0 +1,12 @@
+import type { LeanCriterion, Spec } from '../../types/index.js';
+/**
+ * Authority for secondary new-spec writers. Frontmatter always flows through
+ * the value-only serializer; callers may add only source-backed body content.
+ */
+export declare function serializeValueOnlySpecContent(input: {
+    spec: Spec;
+    description: string;
+    criteria?: readonly LeanCriterion[];
+    technical?: string;
+}): string;
+//# sourceMappingURL=value-only-spec-serializer.d.ts.map