@planu/cli 4.3.25 → 4.4.1

package/dist/engine/spec-metrics/actionable-metrics.d.ts

@@ -0,0 +1,10 @@
+import type { ActionableSpecMetric, CriterionGroundingRecord, EvidenceGateIssue, SpecEvidenceIndex } from '../../types/index.js';
+export declare function calculateActionableSpecMetrics(args: {
+    criteria: readonly string[];
+    groundingRecords?: readonly CriterionGroundingRecord[];
+    evidenceIndex?: SpecEvidenceIndex;
+    ambiguityFindings?: readonly string[];
+    driftIssues?: readonly EvidenceGateIssue[];
+}): ActionableSpecMetric[];
+export declare function shouldExposeMetric(metric: ActionableSpecMetric): boolean;
+//# sourceMappingURL=actionable-metrics.d.ts.map

package/dist/engine/spec-metrics/actionable-metrics.js

@@ -0,0 +1,69 @@
+export function calculateActionableSpecMetrics(args) {
+    return [
+        groundingCoverage(args.criteria, args.groundingRecords ?? []),
+        verificationCoverage(args.evidenceIndex),
+        ambiguityCount(args.ambiguityFindings ?? []),
+        driftRisk(args.driftIssues ?? []),
+    ].filter((metric) => metric !== null);
+}
+export function shouldExposeMetric(metric) {
+    return metric.inputs.length > 0 && metric.nextAction.trim().length > 0;
+}
+function groundingCoverage(criteria, records) {
+    const missing = criteria.filter((criterion) => !records.some((record) => normalize(record.text) === normalize(criterion) &&
+        record.source !== 'ungrounded_advisory' &&
+        record.evidence.length > 0));
+    if (criteria.length === 0 || missing.length === 0) {
+        return null;
+    }
+    return {
+        name: 'groundingCoverage',
+        value: Math.round(((criteria.length - missing.length) / criteria.length) * 100),
+        inputs: missing,
+        nextAction: 'Add grounding evidence or move ungrounded criteria to discovery/advisory output.',
+    };
+}
+function verificationCoverage(index) {
+    if (!index) {
+        return null;
+    }
+    const missing = index.criteria.filter((entry) => !entry.evidence.some((record) => record.kind === 'validation' && record.status === 'valid'));
+    if (index.criteria.length === 0 || missing.length === 0) {
+        return null;
+    }
+    return {
+        name: 'verificationCoverage',
+        value: Math.round(((index.criteria.length - missing.length) / index.criteria.length) * 100),
+        inputs: missing.map((entry) => entry.criterion),
+        nextAction: 'Attach validation evidence mapped to each uncovered criterion.',
+    };
+}
+function ambiguityCount(findings) {
+    if (findings.length === 0) {
+        return null;
+    }
+    return {
+        name: 'ambiguityCount',
+        value: findings.length,
+        inputs: [...findings],
+        nextAction: 'Resolve each ambiguity or mark it explicitly out of scope before implementation.',
+    };
+}
+function driftRisk(issues) {
+    const driftIssues = issues.filter((issue) => issue.code.startsWith('done_drift_'));
+    if (driftIssues.length === 0) {
+        return null;
+    }
+    return {
+        name: 'driftRisk',
+        value: driftIssues.some((issue) => issue.code === 'done_drift_unapproved_scope')
+            ? 'high'
+            : 'medium',
+        inputs: driftIssues.map((issue) => issue.message),
+        nextAction: 'Reconcile scope, replace stale evidence, or map validation to the affected criteria.',
+    };
+}
+function normalize(value) {
+    return value.replace(/\s+/g, ' ').trim().toLowerCase();
+}
+//# sourceMappingURL=actionable-metrics.js.map

package/dist/engine/spec-migrator/planu-canonical-policy.d.ts

@@ -3,6 +3,7 @@ export declare const PLANU_CANONICAL_POLICY: PlanuCanonicalPathPolicy;
 export declare function isCanonicalPlanuRootFile(name: string): boolean;
 export declare function isCanonicalPlanuRootDir(name: string): boolean;
 export declare function isCanonicalSpecFile(name: string): boolean;
+export declare function isCanonicalSpecDir(name: string): boolean;
 export declare function mustMergeBeforeDeleteSpecFile(name: string): boolean;
 export declare function isCanonicalReleaseFile(relativeToPlanu: string): boolean;
 export declare function canonicalContractText(): string;

package/dist/engine/spec-migrator/planu-canonical-policy.js

@@ -4,6 +4,7 @@ export const PLANU_CANONICAL_POLICY = {
     canonicalRootFiles: ['conventions.json', 'context.md', 'session-context.md', 'session.json'],
     canonicalRootDirs: ['releases', 'specs'],
     canonicalSpecFiles: ['spec.md'],
+    canonicalSpecDirs: ['evidence'],
     forbiddenHostAssetRootDirs: ['agents', 'skills', 'rules', 'hooks'],
     generatedRuntimePatterns: [
         'planu/index.html',
@@ -38,6 +39,7 @@ export const PLANU_CANONICAL_POLICY = {
 const ROOT_FILE_SET = new Set(PLANU_CANONICAL_POLICY.canonicalRootFiles);
 const ROOT_DIR_SET = new Set(PLANU_CANONICAL_POLICY.canonicalRootDirs);
 const SPEC_FILE_SET = new Set(PLANU_CANONICAL_POLICY.canonicalSpecFiles);
+const SPEC_DIR_SET = new Set(PLANU_CANONICAL_POLICY.canonicalSpecDirs);
 const LEGACY_MERGE_SET = new Set(PLANU_CANONICAL_POLICY.legacyMergeBeforeDeleteFiles);
 export function isCanonicalPlanuRootFile(name) {
     return ROOT_FILE_SET.has(name);
@@ -48,6 +50,9 @@ export function isCanonicalPlanuRootDir(name) {
 export function isCanonicalSpecFile(name) {
     return SPEC_FILE_SET.has(name);
 }
+export function isCanonicalSpecDir(name) {
+    return SPEC_DIR_SET.has(name);
+}
 export function mustMergeBeforeDeleteSpecFile(name) {
     return LEGACY_MERGE_SET.has(name);
 }
@@ -66,6 +71,8 @@ export function canonicalContractText() {
         '  specs/',
         '    SPEC-XXX-slug/',
         '      spec.md',
+        '      evidence/',
+        '        *.json',
         '',
         'Host adapters are written outside planu/:',
         '  Claude Code: .claude/agents, .claude/skills, .claude/rules',

package/dist/engine/spec-migrator/strict-planu-cleanup.d.ts

@@ -1,6 +1,6 @@
-import type { StrictPlanuCleanupResult, StrictPlanuValidationResult } from '../../types/index.js';
+import type { StrictPlanuCleanupResult, StrictPlanuValidationOptions, StrictPlanuValidationResult } from '../../types/index.js';
 import { PLANU_CANONICAL_POLICY } from './planu-canonical-policy.js';
 export declare function runStrictPlanuCleanup(projectPath: string): Promise<StrictPlanuCleanupResult>;
-export declare function validateStrictPlanuLayout(projectPath: string): Promise<StrictPlanuValidationResult>;
+export declare function validateStrictPlanuLayout(projectPath: string, options?: StrictPlanuValidationOptions): Promise<StrictPlanuValidationResult>;
 export { PLANU_CANONICAL_POLICY };
 //# sourceMappingURL=strict-planu-cleanup.d.ts.map

package/dist/engine/spec-migrator/strict-planu-cleanup.js

@@ -4,10 +4,10 @@ import { readdir, readFile, rm, stat } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import { join, relative } from 'node:path';
+import { dirname, isAbsolute, join, relative } from 'node:path';
 import { atomicWriteFile } from '../safety/atomic-write-file.js';
 import { safeUnlink } from './git-aware-fs.js';
-import { PLANU_CANONICAL_POLICY, canonicalContractText, isCanonicalPlanuRootDir, isCanonicalPlanuRootFile, isCanonicalReleaseFile, isCanonicalSpecFile, mustMergeBeforeDeleteSpecFile, } from './planu-canonical-policy.js';
+import { PLANU_CANONICAL_POLICY, canonicalContractText, isCanonicalPlanuRootDir, isCanonicalPlanuRootFile, isCanonicalReleaseFile, isCanonicalSpecDir, isCanonicalSpecFile, mustMergeBeforeDeleteSpecFile, } from './planu-canonical-policy.js';
 const execFileAsync = promisify(execFile);
 async function pathIsDirectory(path) {
     try {
@@ -125,7 +125,9 @@ async function walkSpecDirectory(projectPath, specDir, result) {
             }
             continue;
         }
-        if (entry === 'reference' || !isCanonicalSpecFile(entry)) {
+        const isDir = await pathIsDirectory(full);
+        if (entry === 'reference' ||
+            (isDir ? !isCanonicalSpecDir(entry) : !isCanonicalSpecFile(entry))) {
             await removePath(projectPath, full);
             result.deleted.push(relative(projectPath, full));
         }
@@ -173,33 +175,46 @@ export async function runStrictPlanuCleanup(projectPath) {
     result.gitignoreUpdated = await updateGitignore(projectPath);
     return result;
 }
-export async function validateStrictPlanuLayout(projectPath) {
+function resolveSpecDirsForValidation(projectPath, specPath) {
+    if (!specPath?.trim()) {
+        return null;
+    }
+    const resolved = isAbsolute(specPath) ? specPath : join(projectPath, specPath);
+    return [dirname(resolved)];
+}
+export async function validateStrictPlanuLayout(projectPath, options = {}) {
     const offenders = [];
     const planuDir = join(projectPath, 'planu');
-    const entries = await readdir(planuDir).catch(() => []);
-    for (const entry of entries) {
-        const full = join(planuDir, entry);
-        const isDir = await pathIsDirectory(full);
-        if ((isDir && !isCanonicalPlanuRootDir(entry)) ||
-            (!isDir && !isCanonicalPlanuRootFile(entry))) {
-            offenders.push(relative(projectPath, full));
+    if (options.includeRoot !== false) {
+        const entries = await readdir(planuDir).catch(() => []);
+        for (const entry of entries) {
+            const full = join(planuDir, entry);
+            const isDir = await pathIsDirectory(full);
+            if ((isDir && !isCanonicalPlanuRootDir(entry)) ||
+                (!isDir && !isCanonicalPlanuRootFile(entry))) {
+                offenders.push(relative(projectPath, full));
+            }
         }
-    }
-    for (const entry of await readdir(join(planuDir, 'releases')).catch(() => [])) {
-        const rel = `releases/${entry}`;
-        if (!isCanonicalReleaseFile(rel)) {
-            offenders.push(`planu/${rel}`);
+        for (const entry of await readdir(join(planuDir, 'releases')).catch(() => [])) {
+            const rel = `releases/${entry}`;
+            if (!isCanonicalReleaseFile(rel)) {
+                offenders.push(`planu/${rel}`);
+            }
         }
     }
-    for (const specDir of await readdir(join(planuDir, 'specs')).catch(() => [])) {
-        const full = join(planuDir, 'specs', specDir);
+    const scopedSpecDirs = resolveSpecDirsForValidation(projectPath, options.specPath) ??
+        (await readdir(join(planuDir, 'specs')).catch(() => [])).map((specDir) => join(planuDir, 'specs', specDir));
+    for (const full of scopedSpecDirs) {
+        const specDir = relative(join(planuDir, 'specs'), full);
         if (!(await pathIsDirectory(full)) || specDir === 'data') {
             offenders.push(relative(projectPath, full));
             continue;
         }
         for (const entry of await readdir(full).catch(() => [])) {
-            if (!isCanonicalSpecFile(entry)) {
-                offenders.push(relative(projectPath, join(full, entry)));
+            const entryPath = join(full, entry);
+            const isDir = await pathIsDirectory(entryPath);
+            if (isDir ? !isCanonicalSpecDir(entry) : !isCanonicalSpecFile(entry)) {
+                offenders.push(relative(projectPath, entryPath));
             }
         }
     }

package/dist/engine/spec-quality/generic-output-gate.d.ts

@@ -0,0 +1,3 @@
+import type { GenericSpecOutputGateResult } from '../../types/index.js';
+export declare function checkGenericSpecOutput(content: string): GenericSpecOutputGateResult;
+//# sourceMappingURL=generic-output-gate.d.ts.map

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

@@ -0,0 +1,105 @@
+const CRITERIA_SECTION_RE = /^criteria:\n([\s\S]*?)(?=^[a-zA-Z_][\w-]*:|\n---|\s*$)/m;
+const CRITERION_TEXT_RE = /^\s+- text:\s*"?(.+?)"?\s*$/gm;
+const FILE_LINE_RE = /^-\s+(.+?)\s+\((pending|done)\)\s*$/gm;
+const GENERIC_CRITERION_RULES = [
+    {
+        pattern: /\bimplementation (is )?complete\b/i,
+        reason: 'self-certifying completion is not a testable behavior',
+    },
+    {
+        pattern: /\bcomplete and tested\b/i,
+        reason: 'completion and testing must be proven by evidence, not criteria text',
+    },
+    {
+        pattern: /\ball edge cases\b/i,
+        reason: 'edge cases must be named explicitly',
+    },
+    {
+        pattern: /\bgeneric validation\b/i,
+        reason: 'validation must identify the behavior and expected result',
+    },
+    {
+        pattern: /\bensure (adequate )?coverage\b/i,
+        reason: 'coverage claims must map to concrete validation evidence',
+    },
+    {
+        pattern: /\bautopilot could not infer testable behavior\b/i,
+        reason: 'fallback uncertainty cannot become an acceptance criterion',
+    },
+    {
+        pattern: /\bdefine acceptance criteria\b/i,
+        reason: 'a request to define criteria is not itself a criterion',
+    },
+    {
+        pattern: /\b(example only|for example|sample)\b/i,
+        reason: 'example-only references cannot become contract criteria',
+    },
+    {
+        pattern: /\b(add|create|implement)\s+(api\s+)?(endpoint|route|migration)s?\b/i,
+        reason: 'broad implementation references must name grounded behavior and evidence',
+    },
+];
+const PLACEHOLDER_REFERENCE_RULES = [
+    {
+        pattern: /\b(to be determined|tbd|placeholder|not specified)\b/i,
+        reason: 'placeholder references are not grounded implementation ownership',
+    },
+    {
+        pattern: /(^|\/)(example|sample|mock|dummy)[\w.-]*\.[a-z]+$/i,
+        reason: 'example file names must not be persisted as technical ownership',
+    },
+];
+export function checkGenericSpecOutput(content) {
+    const issues = [
+        ...checkCriteria(frontmatterCriteria(content)),
+        ...checkTechnicalReferences(content),
+    ];
+    return { passed: issues.length === 0, issues };
+}
+function frontmatterCriteria(content) {
+    const criteriaSection = CRITERIA_SECTION_RE.exec(content)?.[1] ?? '';
+    const criteria = [];
+    let match = CRITERION_TEXT_RE.exec(criteriaSection);
+    while (match) {
+        const phrase = match[1]?.replace(/\\"/g, '"').trim() ?? '';
+        if (phrase.length > 0) {
+            criteria.push(phrase);
+        }
+        match = CRITERION_TEXT_RE.exec(criteriaSection);
+    }
+    return criteria;
+}
+function checkCriteria(criteria) {
+    const issues = [];
+    for (const criterion of criteria) {
+        for (const rule of GENERIC_CRITERION_RULES) {
+            if (rule.pattern.test(criterion)) {
+                issues.push({
+                    kind: rule.reason.includes('coverage') ? 'unsupported-verification' : 'generic-criterion',
+                    phrase: criterion,
+                    reason: rule.reason,
+                });
+            }
+        }
+    }
+    return issues;
+}
+function checkTechnicalReferences(content) {
+    const issues = [];
+    let match = FILE_LINE_RE.exec(content);
+    while (match) {
+        const phrase = match[1]?.replace(/`/g, '').trim() ?? '';
+        for (const rule of PLACEHOLDER_REFERENCE_RULES) {
+            if (rule.pattern.test(phrase)) {
+                issues.push({
+                    kind: 'placeholder-reference',
+                    phrase,
+                    reason: rule.reason,
+                });
+            }
+        }
+        match = FILE_LINE_RE.exec(content);
+    }
+    return issues;
+}
+//# sourceMappingURL=generic-output-gate.js.map

package/dist/tools/create-spec.js

@@ -4,8 +4,9 @@ import { ti } from '../i18n/index.js';
 import { knowledgeStore, specStore } from '../storage/index.js';
 import { readTechnologySelectionContract } from '../storage/technology-selection-store.js';
 import { formatSuccess, addNextSteps, toolResult, interactiveResult } from './response-helpers.js';
-import { writeFile, mkdir, rm, readFile, stat } from 'node:fs/promises';
+import { writeFile, mkdir, rm, readFile, stat as fsStat } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
+import { join as pathJoin } from 'node:path';
 import { estimateSpec } from '../engine/estimator.js';
 import { checkSpecReadiness } from '../engine/readiness-checker.js';
 import { buildSpecContext, buildSplitResult } from './create-spec/spec-builder.js';
@@ -15,7 +16,7 @@ import { notifyStoreChange } from '../engine/doc-generator/portal/regen-hook.js'
 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 { extractCriteria, generateLeanSpecContent, } from '../engine/spec-format/lean-spec-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';
@@ -38,6 +39,9 @@ import { suggestOutOfScope } from '../engine/scope-boundaries/index.js';
 import { adviseSimilarSpecs } from '../engine/complexity-budget/index.js';
 import { issuePlannerToken } from '../engine/reviewer-tokens/issuer.js';
 import { generateInteractiveQuestions } from './create-spec/question-generator.js';
+import { buildCriterionGroundingRecords, filterGroundedCriteria, getAdvisoryCriteria, getContractCriteria, } from '../engine/spec-grounding/contract.js';
+import { checkGenericSpecOutput } from '../engine/spec-quality/generic-output-gate.js';
+import { calculateActionableSpecMetrics, shouldExposeMetric, } from '../engine/spec-metrics/actionable-metrics.js';
 /** SPEC-584: Persist a clarification token when interactive questions are emitted. Best-effort. */
 async function persistClarificationToken(earlyReturn, projectId, toolName) {
     try {
@@ -121,6 +125,69 @@ async function resolveTechnicalFiles(input) {
     }
     return { create: [], modify: [], test: [] };
 }
+async function groundTechnicalFiles(input) {
+    const userInput = input.userInput.toLowerCase();
+    const autopilotPaths = new Set([
+        ...input.autopilot.suggestedFiles.modify.map((file) => file.path),
+        ...input.autopilot.suggestedFiles.create.map((file) => file.path),
+        ...input.autopilot.suggestedFiles.test.map((file) => file.path),
+    ]);
+    const grounded = {
+        create: [],
+        modify: [],
+        test: [],
+    };
+    const records = [];
+    const advisoryFiles = [];
+    for (const section of ['create', 'modify', 'test']) {
+        for (const file of input.files[section]) {
+            const pathInUserInput = userInput.includes(file.path.toLowerCase());
+            const exists = await pathExists(pathJoin(input.projectPath, file.path));
+            const fromAutopilot = autopilotPaths.has(file.path);
+            const derivedTest = section === 'test' && isDerivedFromGroundedSource(file.path, input.files.modify);
+            if (pathInUserInput || exists || fromAutopilot || derivedTest) {
+                grounded[section].push(file);
+                records.push({
+                    path: file.path,
+                    section,
+                    source: pathInUserInput ? 'user_input' : 'project_evidence',
+                    evidence: [
+                        ...(pathInUserInput ? ['create_spec.description'] : []),
+                        ...(exists ? [`file:${file.path}`] : []),
+                        ...(fromAutopilot ? ['autopilot.suggestedFiles'] : []),
+                        ...(derivedTest ? ['derived-test-path'] : []),
+                    ],
+                    confidence: pathInUserInput || exists ? 'high' : 'medium',
+                });
+            }
+            else {
+                advisoryFiles.push(file);
+            }
+        }
+    }
+    return { files: grounded, records, advisoryFiles };
+}
+function isDerivedFromGroundedSource(testPath, modifyFiles) {
+    return modifyFiles.some((file) => {
+        const withoutSrc = file.path.startsWith('src/') ? file.path.slice(4) : file.path;
+        const ext = withoutSrc.replace(/^.*(\.[^.]+)$/, '$1');
+        const base = withoutSrc.slice(0, -ext.length);
+        return testPath === `tests/${base}.test${ext}` || testPath === `tests/${withoutSrc}`;
+    });
+}
+async function pathExists(path) {
+    try {
+        const fs = await import('node:fs/promises');
+        if (typeof fs.stat !== 'function') {
+            return false;
+        }
+        await fs.stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 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? ' +
@@ -304,10 +371,10 @@ async function findByIdempotencyKey(projectPath, key, projectId, windowMs = 10 *
     // Fallback: scan frontmatter in spec.md files (catches specs written before store update)
     try {
         const { glob } = await import('glob');
-        const { join: pathJoin } = await import('node:path');
-        const specFiles = await glob(pathJoin(projectPath, 'planu/specs/*/spec.md'));
+        const { join: joinPath } = await import('node:path');
+        const specFiles = await glob(joinPath(projectPath, 'planu/specs/*/spec.md'));
         for (const specFile of specFiles) {
-            const fileStat = await stat(specFile).catch(() => null);
+            const fileStat = await fsStat(specFile).catch(() => null);
             if (fileStat === null || fileStat.mtimeMs < cutoff) {
                 continue;
             }
@@ -338,12 +405,12 @@ async function findByIdempotencyKey(projectPath, key, projectId, windowMs = 10 *
 async function findRecentlyWrittenSpecs(projectPath, windowMs) {
     try {
         const { glob } = await import('glob');
-        const { join: pathJoin } = await import('node:path');
+        const { join: joinPath } = await import('node:path');
         const cutoff = Date.now() - windowMs;
-        const specFiles = await glob(pathJoin(projectPath, 'planu/specs/*/spec.md'));
+        const specFiles = await glob(joinPath(projectPath, 'planu/specs/*/spec.md'));
         const results = [];
         for (const specFile of specFiles) {
-            const fileStat = await stat(specFile).catch(() => null);
+            const fileStat = await fsStat(specFile).catch(() => null);
             if (fileStat === null || fileStat.mtimeMs < cutoff) {
                 continue;
             }
@@ -528,7 +595,7 @@ export async function handleCreateSpec(inputParams, server) {
                 }
                 // Create spec directory and write lean files (SPEC-461)
                 await measureStep('mkdir-specDir', () => mkdir(specDir, { recursive: true }));
-                const filteredCriteria = autopilot.suggestedCriteria;
+                const filteredCriteria = filterGroundedCriteria(autopilot.suggestedCriteria);
                 const technologyContract = await readTechnologySelectionContract(params.projectPath ?? '');
                 const contractNote = technologyContract
                     ? [
@@ -568,13 +635,24 @@ export async function handleCreateSpec(inputParams, server) {
                 spec.generatedWithModel = generatedSpec.generatedWithModel;
                 spec.generatedAt = generatedSpec.generatedAt;
                 spec.qualityWarnings = generatedSpec.qualityWarnings;
-                const leanSpec = generateLeanSpecContent({
-                    spec,
-                    description: generatedSpec.specBody,
-                    estimation,
-                    extraCriteria: filteredCriteria,
-                    acFormat: params.acFormat,
+                const baseCriteria = extractCriteria(generatedSpec.specBody).map((criterion) => criterion.text);
+                const groundingCriteria = buildCriterionGroundingRecords({
+                    criteria: [...baseCriteria, ...filteredCriteria],
+                    userInput: description,
+                    projectEvidence: [
+                        ...autopilot.detectedPatterns.map((pattern) => `detected-pattern:${pattern}`),
+                        ...autopilot.suggestedFiles.modify.map((file) => `file:${file.path}`),
+                        ...autopilot.suggestedFiles.create.map((file) => `file:${file.path}`),
+                        ...autopilot.suggestedFiles.test.map((file) => `file:${file.path}`),
+                    ],
+                    generatedEvidence: [generatedSpec.generatedWithModel],
                 });
+                const contractCriteria = getContractCriteria(groundingCriteria);
+                const advisoryCriteria = getAdvisoryCriteria(groundingCriteria).map((record) => record.text);
+                const actionableMetrics = calculateActionableSpecMetrics({
+                    criteria: [...baseCriteria, ...filteredCriteria],
+                    groundingRecords: groundingCriteria,
+                }).filter(shouldExposeMetric);
                 const technicalFiles = await measureStep('resolveTechnicalFiles', () => resolveTechnicalFiles({
                     generatedSpecBody: generatedSpec.specBody,
                     generatedTechnicalSection: generatedSpec.technicalSection,
@@ -582,16 +660,59 @@ export async function handleCreateSpec(inputParams, server) {
                     autopilot,
                     fallbackReason: generatedSpec.fallbackReason,
                 }));
+                const groundedTechnical = await measureStep('groundTechnicalFiles', () => groundTechnicalFiles({
+                    files: technicalFiles,
+                    projectPath: params.projectPath ?? '',
+                    userInput: description,
+                    autopilot,
+                }));
+                const leanSpec = generateLeanSpecContent({
+                    spec,
+                    description: generatedSpec.specBody,
+                    estimation,
+                    criteriaOverride: contractCriteria.map((record) => ({
+                        text: record.text,
+                        done: false,
+                    })),
+                    groundingCriteria,
+                    groundingTechnicalReferences: groundedTechnical.records,
+                    acFormat: params.acFormat,
+                });
                 const leanTechnical = generateLeanTechnicalContent({
                     specId: spec.id,
-                    filesToCreate: technicalFiles.create,
-                    filesToModify: technicalFiles.modify,
-                    filesToTest: technicalFiles.test,
+                    filesToCreate: groundedTechnical.files.create,
+                    filesToModify: groundedTechnical.files.modify,
+                    filesToTest: groundedTechnical.files.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
                 // as a `## Technical` section inside spec.md.
                 const unifiedSpec = buildUnifiedSpecContent(leanSpec, leanTechnical);
+                const genericOutputGate = checkGenericSpecOutput(unifiedSpec);
+                if (!genericOutputGate.passed) {
+                    return {
+                        ok: false,
+                        earlyReturn: {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: 'Spec quality gate blocked generic output before persistence. ' +
+                                        genericOutputGate.issues
+                                            .slice(0, 3)
+                                            .map((issue) => `${issue.phrase}: ${issue.reason}`)
+                                            .join('; '),
+                                },
+                            ],
+                            isError: true,
+                            structuredContent: {
+                                error: 'GENERIC_SPEC_OUTPUT_BLOCKED',
+                                sddConstitutionRuleId: 'sdd.no-generic-output',
+                                issues: genericOutputGate.issues,
+                                fixHint: 'Replace generic criteria or placeholder references with grounded, testable behavior.',
+                            },
+                        },
+                    };
+                }
                 try {
                     // SPEC-713: measure file write — this is the critical persistence step
                     await measureStep('writeFile-specPath', () => writeFile(specPath, unifiedSpec, 'utf-8'));
@@ -629,6 +750,11 @@ export async function handleCreateSpec(inputParams, server) {
                         constitutionCheck,
                         autopilot,
                         filteredCriteria,
+                        advisoryCriteria: [
+                            ...advisoryCriteria,
+                            ...groundedTechnical.advisoryFiles.map((file) => file.path),
+                        ],
+                        actionableMetrics,
                         outOfScopeSuggestionMsg,
                     },
                 };
@@ -659,7 +785,7 @@ export async function handleCreateSpec(inputParams, server) {
             // Destructure critical path results for use in post-creation enrichment
             const { spec, specDir: _specDir, specPath, 
             // SPEC-1010 Bug A: no longer surfaced in the response payload (SSR back-migration).
-            technicalPath: _technicalPath, estimation, splitSuggestion, duplicate, projectId, agentTeamPlan, knowledge, clarificationSession, constitutionCheck, autopilot, filteredCriteria, outOfScopeSuggestionMsg, } = criticalResult.value.data;
+            technicalPath: _technicalPath, estimation, splitSuggestion, duplicate, projectId, agentTeamPlan, knowledge, clarificationSession, constitutionCheck, autopilot, filteredCriteria, advisoryCriteria, actionableMetrics, outOfScopeSuggestionMsg, } = criticalResult.value.data;
             // -----------------------------------------------------------------------
             // Post-creation enrichment (outside 25s ceiling — best-effort, budgeted)
             // -----------------------------------------------------------------------
@@ -742,6 +868,21 @@ export async function handleCreateSpec(inputParams, server) {
                 ...(gitSetupResult ? { gitAutoSetup: gitSetupResult.data } : {}),
             };
             const advisorySignals = [];
+            if (actionableMetrics.length > 0) {
+                result.actionableMetrics = actionableMetrics;
+            }
+            if (advisoryCriteria.length > 0) {
+                advisorySignals.push(makeAdvisorySignal({
+                    key: 'ungrounded-contract-items',
+                    kind: 'quality',
+                    message: `${String(advisoryCriteria.length)} ungrounded contract item(s) kept advisory-only.`,
+                    source: 'validator',
+                    evidence: advisoryCriteria.slice(0, 10),
+                    confidence: 0.8,
+                    surface: 'structuredContent',
+                    value: advisoryCriteria,
+                }));
+            }
             const splitResult = buildSplitResult(splitSuggestion, knowledge?.experienceLevel);
             if (splitResult) {
                 result.splitSuggestion = splitResult;
@@ -810,17 +951,6 @@ export async function handleCreateSpec(inputParams, server) {
             const qualityValue = unwrapBudget(qualityResult, null, budgetWarnings);
             if (qualityValue !== null) {
                 result.qualityScore = qualityValue;
-                advisorySignals.push(makeAdvisorySignal({
-                    key: 'quality-score',
-                    kind: 'quality',
-                    message: `Quality score ${String(qualityValue.total)}/100 (${qualityValue.grade}).`,
-                    source: 'validator',
-                    evidence: ['spec-quality-scorer'],
-                    confidence: 0.7,
-                    surface: 'structuredContent',
-                    value: qualityValue,
-                    deprecatedAlias: 'qualityScore',
-                }));
             }
             // SPEC-485: Simplicity autopilot — detect over-engineering signals (best-effort, sync)
             const simplicityResult = runSimplicityCheck([params.description, ...filteredCriteria].join('\n'), estimation.devHours);