@planu/cli 4.3.25 → 4.4.0

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-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);

package/dist/tools/update-status/evidence-gate.js

@@ -4,10 +4,13 @@ import { extractCriteria, extractListItems, extractSection, } from '../../engine
 import { stripFrontmatter } from '../../engine/frontmatter-parser.js';
 import { readEvidenceArtifacts } from '../../engine/evidence-gates/artifact-reader.js';
 import { checkLifecycleEvidenceGate } from '../../engine/evidence-gates/lifecycle-gate.js';
+import { buildSpecEvidenceIndex } from '../../engine/evidence-index/index-builder.js';
+import { checkDoneDriftContract } from '../../engine/evidence-index/done-drift.js';
+import { parseTechnicalReferenceGroundingRecords } from '../../engine/spec-grounding/contract.js';
 /** SPEC-1054: BDD/SDD lifecycle evidence gate. */
 export async function checkLifecycleEvidenceTransitionGate(args) {
-    const [criteria, artifacts] = await Promise.all([
-        extractLifecycleGateCriteria(args.spec, args.projectPath),
+    const [criteriaResult, artifacts] = await Promise.all([
+        extractLifecycleGateCriteriaAndBody(args.spec, args.projectPath),
         readEvidenceArtifacts({
             spec: args.spec,
             projectId: args.projectId,
@@ -15,13 +18,26 @@ export async function checkLifecycleEvidenceTransitionGate(args) {
             projectPath: args.projectPath,
         }),
     ]);
+    const { criteria, body } = criteriaResult;
     const result = checkLifecycleEvidenceGate({
         transition: args.transition,
         spec: args.spec,
         criteria,
         artifacts,
     });
-    if (result.passed) {
+    if (args.transition === 'done') {
+        const index = await buildSpecEvidenceIndex({
+            specId: args.specId,
+            criteria,
+            artifacts,
+            projectPath: args.projectPath,
+        });
+        const groundedTechnicalPaths = body
+            ? parseTechnicalReferenceGroundingRecords(body).map((record) => record.path)
+            : [];
+        result.issues.push(...checkDoneDriftContract({ index, groundedTechnicalPaths }));
+    }
+    if (result.issues.length === 0) {
         return null;
     }
     return evidenceGateError({
@@ -34,7 +50,7 @@ export async function checkLifecycleEvidenceTransitionGate(args) {
         requiredContractKinds: result.requiredContractKinds,
     });
 }
-async function extractLifecycleGateCriteria(spec, projectPath) {
+async function extractLifecycleGateCriteriaAndBody(spec, projectPath) {
     const specPath = isAbsolute(spec.specPath) || !projectPath ? spec.specPath : join(projectPath, spec.specPath);
     try {
         const raw = await readFile(specPath, 'utf-8');
@@ -43,14 +59,14 @@ async function extractLifecycleGateCriteria(spec, projectPath) {
         if (acceptanceCriteria) {
             const items = extractListItems(acceptanceCriteria);
             if (items.length > 0) {
-                return [...new Set(items)];
+                return { criteria: [...new Set(items)], body: raw };
             }
         }
     }
     catch {
         // Fall back to the broader validator extractor when the canonical file is unavailable.
     }
-    return extractCriteria(spec);
+    return { criteria: await extractCriteria(spec), body: null };
 }
 function evidenceGateError(args) {
     return {
@@ -72,6 +88,7 @@ function evidenceGateError(args) {
         structuredContent: {
             error: 'lifecycle_evidence_gate_failed',
             code: 422,
+            sddConstitutionRuleId: args.transition === 'done' ? 'sdd.done-evidence-required' : 'sdd.grounded-contract',
             context: {
                 specId: args.specId,
                 transition: args.transition,

package/dist/tools/update-status/transition-guard.js

@@ -6,6 +6,8 @@ import { dispatchFeedbackEvent } from '../learn.js';
 import { scoreAmbiguityFromPath } from '../../engine/ambiguity-scorer.js';
 import { checkReadinessInternal } from '../../engine/readiness-checker.js';
 import { validateEnglishOnlySpecText } from '../../engine/spec-language/english-only.js';
+import { checkGroundedSpecContract } from '../../engine/spec-grounding/contract.js';
+import { checkGenericSpecOutput } from '../../engine/spec-quality/generic-output-gate.js';
 /**
  * Valid state transitions for spec lifecycle.
  * draft -> review -> approved -> implementing -> done
@@ -224,6 +226,53 @@ export async function checkReadinessGate(spec, newStatus, forceApprove) {
             qualityWarnings: [],
         };
     }
+    const groundingResult = checkGroundedSpecContract(spec, body);
+    if (!groundingResult.passed) {
+        return {
+            blockResult: {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Grounded spec contract blocked transition to ${newStatus}. ` +
+                            groundingResult.issues.slice(0, 3).join('; '),
+                    },
+                ],
+                isError: true,
+                structuredContent: {
+                    error: 'GROUNDED_SPEC_CONTRACT_BLOCKED',
+                    sddConstitutionRuleId: 'sdd.grounded-contract',
+                    issues: groundingResult.issues,
+                    fixHint: 'Add grounding metadata for every contract criterion or move ungrounded criteria to advisory/discovery before review or approval.',
+                },
+            },
+            qualityWarnings: [],
+        };
+    }
+    const genericOutputGate = checkGenericSpecOutput(body);
+    if (!genericOutputGate.passed) {
+        return {
+            blockResult: {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Spec quality gate blocked transition to ${newStatus}. ` +
+                            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 before review or approval.',
+                },
+            },
+            qualityWarnings: [],
+        };
+    }
     let score;
     let warnings;
     let criteriaCount;

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

@@ -0,0 +1,8 @@
+export type ActionableSpecMetricName = 'groundingCoverage' | 'verificationCoverage' | 'ambiguityCount' | 'driftRisk';
+export interface ActionableSpecMetric {
+    name: ActionableSpecMetricName;
+    value: number | 'none' | 'low' | 'medium' | 'high';
+    inputs: string[];
+    nextAction: string;
+}
+//# sourceMappingURL=actionable-spec-metrics.d.ts.map

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=actionable-spec-metrics.js.map

package/dist/types/evidence-gates.d.ts

@@ -54,7 +54,7 @@ export interface EvidenceArtifacts {
     invalidArtifacts: string[];
 }
 export interface EvidenceGateIssue {
-    code: 'discovery_missing' | 'discovery_unresolved_questions' | 'task_plan_missing' | 'task_plan_uncovered_criteria' | 'traceability_missing' | 'traceability_uncovered_criteria' | 'traceability_incomplete_rows' | 'contract_validation_missing' | 'contract_validation_failed' | 'evidence_artifact_invalid';
+    code: 'discovery_missing' | 'discovery_unresolved_questions' | 'task_plan_missing' | 'task_plan_uncovered_criteria' | 'traceability_missing' | 'traceability_uncovered_criteria' | 'traceability_incomplete_rows' | 'contract_validation_missing' | 'contract_validation_failed' | 'done_drift_uncovered_criteria' | 'done_drift_stale_evidence' | 'done_drift_unapproved_scope' | 'evidence_artifact_invalid';
     message: string;
 }
 export interface EvidenceGateResult {

package/dist/types/evidence-index.d.ts

@@ -0,0 +1,24 @@
+export type EvidenceRecordKind = 'scenario' | 'test' | 'contract' | 'manual' | 'changed-file' | 'validation' | 'reviewer';
+export type EvidenceRecordStatus = 'valid' | 'stale' | 'invalid' | 'missing';
+export interface EvidenceRecord {
+    kind: EvidenceRecordKind;
+    value: string;
+    status: EvidenceRecordStatus;
+    source: string;
+    command?: string;
+    passed?: boolean;
+    timestamp?: string;
+    reason?: string;
+}
+export interface CriterionEvidenceIndexEntry {
+    criterion: string;
+    criterionKey: string;
+    evidence: EvidenceRecord[];
+}
+export interface SpecEvidenceIndex {
+    specId: string;
+    generatedAt: string;
+    criteria: CriterionEvidenceIndexEntry[];
+    diagnostics: string[];
+}
+//# sourceMappingURL=evidence-index.d.ts.map

package/dist/types/evidence-index.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=evidence-index.js.map