@planu/cli 4.3.25 → 4.4.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [4.4.0] - 2026-06-03
+
+### Features
+- feat: add grounded SDD gates and evidence metrics
+
+
 ## [4.3.24] - 2026-06-02
 
 ### Chores

package/dist/engine/constitution/sdd-rules-registry.d.ts

@@ -0,0 +1,12 @@
+import type { EffectiveSddConstitutionRule, SddConstitutionOverride, SddConstitutionRule, SddConstitutionViolation } from '../../types/index.js';
+import type { Spec } from '../../types/spec/core.js';
+export declare const DEFAULT_SDD_CONSTITUTION_RULES: readonly SddConstitutionRule[];
+export declare function loadSddConstitutionRules(overrides?: readonly SddConstitutionOverride[]): EffectiveSddConstitutionRule[];
+export declare function validateSddConstitutionOverrides(overrides: readonly SddConstitutionOverride[]): string[];
+export declare function evaluateSddConstitutionRules(args: {
+    spec: Spec;
+    content: string;
+    overrides?: readonly SddConstitutionOverride[];
+}): SddConstitutionViolation[];
+export declare function renderSddConstitutionRulesForHost(): string;
+//# sourceMappingURL=sdd-rules-registry.d.ts.map

package/dist/engine/constitution/sdd-rules-registry.js

@@ -0,0 +1,105 @@
+import { checkGenericSpecOutput } from '../spec-quality/generic-output-gate.js';
+import { checkGroundedSpecContract } from '../spec-grounding/contract.js';
+export const DEFAULT_SDD_CONSTITUTION_RULES = [
+    {
+        id: 'sdd.grounded-contract',
+        title: 'Grounded Spec Contract',
+        level: 'blocking',
+        category: 'grounding',
+        description: 'Contract criteria and technical references must be grounded in user input, project evidence, or explicit review evidence.',
+        nextAction: 'Add grounding metadata, remove ungrounded criteria from the contract, or move assumptions to advisory output.',
+    },
+    {
+        id: 'sdd.no-generic-output',
+        title: 'No Generic Spec Output',
+        level: 'blocking',
+        category: 'quality',
+        description: 'Specs must not persist self-certifying criteria, placeholder ownership, unsupported verification claims, or example-only contract language.',
+        nextAction: 'Replace generic output with grounded behavior, exact evidence, or a discovery question.',
+    },
+    {
+        id: 'sdd.no-self-approval',
+        title: 'No Self Approval',
+        level: 'blocking',
+        category: 'approval',
+        description: 'The planner, spec author, or implementation agent must not approve their own spec or completion evidence.',
+        nextAction: 'Attach independent reviewer evidence before approval or done.',
+    },
+    {
+        id: 'sdd.done-evidence-required',
+        title: 'Done Requires Evidence',
+        level: 'blocking',
+        category: 'evidence',
+        description: 'Done requires traceability, validation evidence, reviewer evidence, and no unexplained drift from the approved contract.',
+        nextAction: 'Add traceability rows, validation output, reviewer evidence, or reconcile approved scope changes.',
+    },
+    {
+        id: 'sdd.actionable-metrics-only',
+        title: 'Actionable Metrics Only',
+        level: 'advisory',
+        category: 'metrics',
+        description: 'User-facing metrics must expose inputs and a concrete next action; vanity scores stay hidden.',
+        nextAction: 'Show only metrics that identify a missing criterion, evidence gap, ambiguity, or drift risk.',
+    },
+];
+export function loadSddConstitutionRules(overrides = []) {
+    const overrideByRule = new Map(overrides.map((override) => [override.ruleId, override]));
+    return DEFAULT_SDD_CONSTITUTION_RULES.map((rule) => {
+        const override = overrideByRule.get(rule.id);
+        if (!override) {
+            return { ...rule, enabled: true };
+        }
+        return {
+            ...rule,
+            enabled: override.enabled ?? true,
+            level: override.level ?? rule.level,
+            overrideRationale: override.rationale,
+        };
+    });
+}
+export function validateSddConstitutionOverrides(overrides) {
+    const known = new Set(DEFAULT_SDD_CONSTITUTION_RULES.map((rule) => rule.id));
+    return overrides.flatMap((override) => {
+        const issues = [];
+        if (!known.has(override.ruleId)) {
+            issues.push(`Unknown SDD constitution rule override: ${override.ruleId}`);
+        }
+        if (override.rationale.trim().length < 20) {
+            issues.push(`Override ${override.ruleId} requires a rationale of at least 20 characters.`);
+        }
+        return issues;
+    });
+}
+export function evaluateSddConstitutionRules(args) {
+    const rules = loadSddConstitutionRules(args.overrides).filter((rule) => rule.enabled);
+    const violations = [];
+    if (rules.some((rule) => rule.id === 'sdd.grounded-contract')) {
+        const grounding = checkGroundedSpecContract(args.spec, args.content);
+        if (!grounding.passed) {
+            violations.push(...grounding.issues.map((issue) => violation('sdd.grounded-contract', issue, [issue], rules)));
+        }
+    }
+    if (rules.some((rule) => rule.id === 'sdd.no-generic-output')) {
+        const generic = checkGenericSpecOutput(args.content);
+        violations.push(...generic.issues.map((issue) => violation('sdd.no-generic-output', issue.reason, [issue.phrase], rules)));
+    }
+    return violations;
+}
+export function renderSddConstitutionRulesForHost() {
+    const enabled = loadSddConstitutionRules();
+    return [
+        '### Constitutional SDD rules',
+        ...enabled.map((rule) => `- ${rule.id} (${rule.level}): ${rule.description} Next action: ${rule.nextAction}`),
+    ].join('\n');
+}
+function violation(ruleId, message, evidence, rules) {
+    const rule = rules.find((candidate) => candidate.id === ruleId);
+    return {
+        ruleId,
+        level: rule?.level ?? 'blocking',
+        message,
+        evidence,
+        nextAction: rule?.nextAction ?? 'Fix the violated SDD constitution rule.',
+    };
+}
+//# sourceMappingURL=sdd-rules-registry.js.map

package/dist/engine/evidence-index/done-drift.d.ts

@@ -0,0 +1,6 @@
+import type { EvidenceGateIssue, SpecEvidenceIndex } from '../../types/index.js';
+export declare function checkDoneDriftContract(args: {
+    index: SpecEvidenceIndex;
+    groundedTechnicalPaths: readonly string[];
+}): EvidenceGateIssue[];
+//# sourceMappingURL=done-drift.d.ts.map

package/dist/engine/evidence-index/done-drift.js

@@ -0,0 +1,44 @@
+export function checkDoneDriftContract(args) {
+    const issues = [];
+    const uncovered = args.index.criteria.filter((entry) => {
+        const hasChangedFile = entry.evidence.some((record) => record.kind === 'changed-file' &&
+            (record.status === 'valid' || record.status === 'missing'));
+        const hasValidation = entry.evidence.some((record) => record.kind === 'validation' && record.status === 'valid');
+        return !hasChangedFile || !hasValidation;
+    });
+    if (uncovered.length > 0) {
+        issues.push({
+            code: 'done_drift_uncovered_criteria',
+            message: `Done drift check found criteria without mapped changed files or validation evidence: ${uncovered.map((entry) => entry.criterion).join('; ')}`,
+        });
+    }
+    const staleOrInvalid = args.index.criteria.flatMap((entry) => entry.evidence
+        .filter((record) => record.status === 'stale' || record.status === 'invalid')
+        .map((record) => `${entry.criterion}: ${record.value} (${record.status})`));
+    if (staleOrInvalid.length > 0) {
+        issues.push({
+            code: 'done_drift_stale_evidence',
+            message: `Done drift check found stale or invalid evidence: ${staleOrInvalid.join('; ')}`,
+        });
+    }
+    const grounded = new Set(args.groundedTechnicalPaths);
+    if (grounded.size > 0) {
+        const unapproved = args.index.criteria.flatMap((entry) => {
+            const hasScopeAmendment = entry.evidence.some((record) => record.kind === 'reviewer' && /scope amendment|approved scope/i.test(record.value));
+            if (hasScopeAmendment) {
+                return [];
+            }
+            return entry.evidence
+                .filter((record) => record.kind === 'changed-file' && !grounded.has(record.value))
+                .map((record) => `${entry.criterion}: ${record.value}`);
+        });
+        if (unapproved.length > 0) {
+            issues.push({
+                code: 'done_drift_unapproved_scope',
+                message: `Done drift check found changed files outside grounded spec scope: ${unapproved.join('; ')}`,
+            });
+        }
+    }
+    return issues;
+}
+//# sourceMappingURL=done-drift.js.map

package/dist/engine/evidence-index/index-builder.d.ts

@@ -0,0 +1,10 @@
+import type { EvidenceArtifacts, SpecEvidenceIndex } from '../../types/index.js';
+export declare function criterionKey(criterion: string): string;
+export declare function buildSpecEvidenceIndex(args: {
+    specId: string;
+    criteria: string[];
+    artifacts: EvidenceArtifacts;
+    projectPath?: string;
+    now?: string;
+}): Promise<SpecEvidenceIndex>;
+//# sourceMappingURL=index-builder.d.ts.map

package/dist/engine/evidence-index/index-builder.js

@@ -0,0 +1,138 @@
+import { createHash } from 'node:crypto';
+import { stat } from 'node:fs/promises';
+import { isAbsolute, join, normalize } from 'node:path';
+export function criterionKey(criterion) {
+    const normalized = normalizeCriterion(criterion);
+    return createHash('sha256').update(normalized).digest('hex').slice(0, 16);
+}
+export async function buildSpecEvidenceIndex(args) {
+    const diagnostics = [...args.artifacts.invalidArtifacts];
+    const matrixRows = args.artifacts.traceabilityMatrix?.rows ?? [];
+    const contractValidations = args.artifacts.contractValidations;
+    const entries = await Promise.all(args.criteria.map(async (criterion) => {
+        const rows = matrixRows.filter((row) => normalizeCriterion(row.acceptanceCriterion) === normalizeCriterion(criterion));
+        const evidence = await collectEvidence({
+            rows,
+            contractValidations,
+            projectPath: args.projectPath,
+            diagnostics,
+        });
+        return {
+            criterion,
+            criterionKey: criterionKey(criterion),
+            evidence,
+        };
+    }));
+    return {
+        specId: args.specId,
+        generatedAt: args.now ?? new Date().toISOString(),
+        criteria: entries,
+        diagnostics,
+    };
+}
+async function collectEvidence(args) {
+    const records = [];
+    for (const row of args.rows) {
+        if (row.scenario) {
+            records.push(record('scenario', row.scenario, 'valid', 'traceability-matrix'));
+        }
+        for (const test of row.testEvidence ?? []) {
+            records.push(await pathRecord('test', test, 'traceability-matrix', args));
+        }
+        for (const contract of row.contractEvidence ?? []) {
+            records.push(await pathRecord('contract', contract, 'traceability-matrix', args));
+        }
+        if (row.manualEvidence) {
+            records.push(record('manual', row.manualEvidence, 'valid', 'traceability-matrix'));
+        }
+        for (const changedFile of row.changedFiles) {
+            records.push(await pathRecord('changed-file', changedFile, 'traceability-matrix', args));
+        }
+        if (row.validationEvidence) {
+            records.push(validationRecord(row.validationEvidence));
+        }
+        if (row.reviewerEvidence) {
+            records.push(record('reviewer', row.reviewerEvidence, 'valid', 'traceability-matrix'));
+        }
+    }
+    for (const validation of args.contractValidations) {
+        if (validation.reportPath) {
+            records.push(await pathRecord('contract', validation.reportPath, `contract-validation:${validation.kind}`, args));
+        }
+        if (validation.summary) {
+            records.push({
+                ...record('contract', validation.summary, validation.passed ? 'valid' : 'invalid', `contract-validation:${validation.kind}`),
+                passed: validation.passed,
+            });
+        }
+    }
+    return records;
+}
+function validationRecord(value) {
+    const parsed = parseValidationEvidence(value);
+    return {
+        kind: 'validation',
+        value,
+        status: parsed.passed === false ? 'invalid' : 'valid',
+        source: 'traceability-matrix',
+        ...parsed,
+    };
+}
+function parseValidationEvidence(value) {
+    try {
+        const parsed = JSON.parse(value);
+        if (typeof parsed !== 'object' || parsed === null) {
+            return { command: value };
+        }
+        const parsedRecord = parsed;
+        return {
+            command: typeof parsedRecord.command === 'string' ? parsedRecord.command : value,
+            passed: typeof parsedRecord.passed === 'boolean' ? parsedRecord.passed : undefined,
+            timestamp: typeof parsedRecord.timestamp === 'string' ? parsedRecord.timestamp : undefined,
+        };
+    }
+    catch {
+        return { command: value };
+    }
+}
+async function pathRecord(kind, value, source, args) {
+    const safe = resolveSafeProjectPath(value, args.projectPath);
+    if (!safe.ok) {
+        args.diagnostics.push(`${value}: ${safe.reason}`);
+        return record(kind, value, 'invalid', source, safe.reason);
+    }
+    if (!args.projectPath) {
+        return record(kind, value, 'missing', source, 'projectPath unavailable');
+    }
+    const exists = await stat(safe.path)
+        .then(() => true)
+        .catch(() => false);
+    return record(kind, value, exists ? 'valid' : 'stale', source, exists ? undefined : 'file missing');
+}
+function resolveSafeProjectPath(value, projectPath) {
+    if (value.trim().length === 0) {
+        return { ok: false, reason: 'empty evidence path' };
+    }
+    if (isAbsolute(value)) {
+        return { ok: false, reason: 'absolute evidence paths are not allowed' };
+    }
+    const normalized = normalize(value);
+    if (normalized.startsWith('..') || normalized.includes('/../')) {
+        return { ok: false, reason: 'path traversal is not allowed' };
+    }
+    if (!projectPath) {
+        return { ok: true, path: normalized };
+    }
+    return { ok: true, path: join(projectPath, normalized) };
+}
+function record(kind, value, status, source, reason) {
+    return { kind, value, status, source, ...(reason ? { reason } : {}) };
+}
+function normalizeCriterion(value) {
+    return value
+        .replace(/^-\s*\[[ x]\]\s*/i, '')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .toLowerCase();
+}
+//# sourceMappingURL=index-builder.js.map

package/dist/engine/host-rules-templates/templates.js

@@ -1,6 +1,7 @@
 // engine/host-rules-templates/templates.ts — SPEC-708: Per-host rules + question directives.
 // Each LLM host has its own native interactive-input mechanism. We adapt the rule
 // text + the runtime directive emitted by withInteractiveQuestions() per host.
+import { renderSddConstitutionRulesForHost } from '../constitution/sdd-rules-registry.js';
 /** Native interactive-input mechanism for a given host (used in rule wording). */
 const HOST_QUESTIONS_RULE = {
     'claude-code': 'In Claude Code: use `AskUserQuestion`. Never present questions as plain text.',
@@ -62,6 +63,8 @@ function buildSharedRules() {
         '- The implementation reviewer must be different from the implementation agent.',
         '- User pressure, shortcut requests, or force-approval language do not bypass reviewer evidence; stop and produce the missing review first.',
         '',
+        renderSddConstitutionRulesForHost(),
+        '',
         '### External integrations',
         '| Trigger | Automatic action |',
         '|---------|-----------------|',

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

@@ -3,6 +3,7 @@
 import { parseBddScenarios, renderBddScenariosYaml, convertCheckboxToBdd } from './bdd-parser.js';
 import { deriveModelBudget } from './model-budget-deriver.js';
 import { renderHistoryYaml } from '../spec-versioning/render-history.js';
+import { renderGroundingFrontmatter, renderTechnicalReferenceGroundingFrontmatter, } from '../spec-grounding/contract.js';
 /** Strip redundant "SPEC-XXX — " or "SPEC-XXX: " prefix from spec titles.
  * Titles must not repeat the ID since it is already stored in the `id` field. */
 function sanitizeTitle(title, specId) {
@@ -47,13 +48,17 @@ export function generateLeanSpecContent(input) {
         ...(spec.qualityWarnings && spec.qualityWarnings.length > 0
             ? [`qualityWarnings: ${JSON.stringify(spec.qualityWarnings)}`]
             : []),
+        ...(input.groundingCriteria ? renderGroundingFrontmatter(input.groundingCriteria) : []),
+        ...(input.groundingTechnicalReferences
+            ? renderTechnicalReferenceGroundingFrontmatter(input.groundingTechnicalReferences)
+            : []),
     ];
     let acLines;
     if (acFormat === 'bdd') {
-        acLines = buildBddLines(description, extraCriteria);
+        acLines = buildBddLines(description, extraCriteria, input.criteriaOverride);
     }
     else {
-        acLines = buildCheckboxLines(description, extraCriteria);
+        acLines = buildCheckboxLines(description, extraCriteria, input.criteriaOverride);
     }
     // SPEC-717: render empty version history for new specs
     const historyYaml = renderHistoryYaml([]);
@@ -72,25 +77,25 @@ export function generateLeanSpecContent(input) {
     return lines.join('\n');
 }
 /** Build checkbox-format criteria lines. */
-function buildCheckboxLines(description, extraCriteria) {
-    const criteria = extractCriteria(description);
-    for (const text of extraCriteria) {
-        criteria.push({ text, done: false });
-    }
+function buildCheckboxLines(description, extraCriteria, criteriaOverride) {
+    const criteria = criteriaOverride ?? [
+        ...extractCriteria(description),
+        ...extraCriteria.map((text) => ({ text, done: false })),
+    ];
     return [
         'criteria:',
         ...criteria.map((c) => `  - text: "${escapeYaml(c.text)}"\n    done: ${String(c.done)}`),
     ];
 }
 /** Build BDD scenario lines. */
-function buildBddLines(description, extraCriteria) {
+function buildBddLines(description, extraCriteria, criteriaOverride) {
     let scenarios = parseBddScenarios(description);
     // Fallback: convert checkbox criteria to BDD scenarios
     if (scenarios.length === 0) {
-        const checkboxCriteria = extractCriteria(description);
-        for (const text of extraCriteria) {
-            checkboxCriteria.push({ text, done: false });
-        }
+        const checkboxCriteria = criteriaOverride ?? [
+            ...extractCriteria(description),
+            ...extraCriteria.map((text) => ({ text, done: false })),
+        ];
         scenarios = convertCheckboxToBdd(checkboxCriteria);
     }
     else {

package/dist/engine/spec-grounding/contract.d.ts

@@ -0,0 +1,19 @@
+import type { Spec } from '../../types/index.js';
+import type { CriterionGroundingRecord, GroundingGateResult, TechnicalReferenceGroundingRecord } from '../../types/spec-grounding.js';
+export declare function normalizeCriterionText(text: string): string;
+export declare function isGenericCriterion(text: string): boolean;
+export declare function filterGroundedCriteria(criteria: string[]): string[];
+export declare function buildCriterionGroundingRecords(args: {
+    criteria: string[];
+    userInput: string;
+    projectEvidence?: string[];
+    generatedEvidence?: string[];
+}): CriterionGroundingRecord[];
+export declare function getContractCriteria(records: CriterionGroundingRecord[]): CriterionGroundingRecord[];
+export declare function getAdvisoryCriteria(records: CriterionGroundingRecord[]): CriterionGroundingRecord[];
+export declare function renderGroundingFrontmatter(records: CriterionGroundingRecord[]): string[];
+export declare function renderTechnicalReferenceGroundingFrontmatter(records: TechnicalReferenceGroundingRecord[]): string[];
+export declare function checkGroundedSpecContract(spec: Spec, content: string): GroundingGateResult;
+export declare function parseCriterionGroundingRecords(frontmatter: string): CriterionGroundingRecord[];
+export declare function parseTechnicalReferenceGroundingRecords(frontmatter: string): TechnicalReferenceGroundingRecord[];
+//# sourceMappingURL=contract.d.ts.map

package/dist/engine/spec-grounding/contract.js

@@ -0,0 +1,186 @@
+const GENERIC_CRITERION_PATTERNS = [
+    /\bimplementation complete\b/i,
+    /\bcomplete and tested\b/i,
+    /\bensure (adequate )?coverage\b/i,
+    /\ball edge cases\b/i,
+    /\bgeneric validation\b/i,
+    /\bautopilot could not infer testable behavior\b/i,
+    /\bdefine acceptance criteria\b/i,
+];
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---/;
+export function normalizeCriterionText(text) {
+    return text
+        .replace(/^[-*]\s*\[[ xX]\]\s*/, '')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .toLowerCase();
+}
+export function isGenericCriterion(text) {
+    return GENERIC_CRITERION_PATTERNS.some((pattern) => pattern.test(text));
+}
+export function filterGroundedCriteria(criteria) {
+    return criteria.filter((criterion) => criterion.trim().length > 0 && !isGenericCriterion(criterion));
+}
+export function buildCriterionGroundingRecords(args) {
+    const userInput = normalizeCriterionText(args.userInput);
+    const projectEvidence = args.projectEvidence ?? [];
+    const generatedEvidence = args.generatedEvidence ?? [];
+    return args.criteria.map((criterion) => {
+        const normalized = normalizeCriterionText(criterion);
+        if (isGenericCriterion(criterion)) {
+            return {
+                text: criterion,
+                source: 'ungrounded_advisory',
+                evidence: [],
+                confidence: 'low',
+            };
+        }
+        if (normalized.length > 0 && userInput.includes(normalized)) {
+            return {
+                text: criterion,
+                source: 'user_input',
+                evidence: ['create_spec.description'],
+                confidence: 'high',
+            };
+        }
+        if (projectEvidence.length > 0) {
+            return {
+                text: criterion,
+                source: 'project_evidence',
+                evidence: projectEvidence.slice(0, 8),
+                confidence: 'medium',
+            };
+        }
+        return {
+            text: criterion,
+            source: 'documented_assumption',
+            evidence: generatedEvidence.length > 0 ? generatedEvidence.slice(0, 4) : ['generated-spec-body'],
+            confidence: 'medium',
+        };
+    });
+}
+export function getContractCriteria(records) {
+    return records.filter((record) => record.source === 'user_input' || record.source === 'project_evidence');
+}
+export function getAdvisoryCriteria(records) {
+    return records.filter((record) => record.source === 'documented_assumption' || record.source === 'ungrounded_advisory');
+}
+export function renderGroundingFrontmatter(records) {
+    if (records.length === 0) {
+        return ['grounding_required: true', 'grounding:', '  criteria: []'];
+    }
+    return [
+        'grounding_required: true',
+        'grounding:',
+        '  criteria:',
+        ...records.flatMap((record) => [
+            `    - text: "${escapeYaml(record.text)}"`,
+            `      source: ${record.source}`,
+            `      evidence: [${record.evidence.map((item) => `"${escapeYaml(item)}"`).join(', ')}]`,
+            `      confidence: ${record.confidence}`,
+        ]),
+    ];
+}
+export function renderTechnicalReferenceGroundingFrontmatter(records) {
+    if (records.length === 0) {
+        return ['  technicalReferences: []'];
+    }
+    return [
+        '  technicalReferences:',
+        ...records.flatMap((record) => [
+            `    - path: "${escapeYaml(record.path)}"`,
+            `      section: ${record.section}`,
+            `      source: ${record.source}`,
+            `      evidence: [${record.evidence.map((item) => `"${escapeYaml(item)}"`).join(', ')}]`,
+            `      confidence: ${record.confidence}`,
+        ]),
+    ];
+}
+export function checkGroundedSpecContract(spec, content) {
+    const frontmatter = FRONTMATTER_RE.exec(content)?.[1] ?? '';
+    const required = /^grounding_required:\s*true\s*$/m.test(frontmatter);
+    const records = parseCriterionGroundingRecords(frontmatter);
+    if (!required) {
+        return { passed: true, required: false, issues: [], records };
+    }
+    const issues = [];
+    if (records.length === 0 && spec.scope !== 'trivial') {
+        issues.push(`Spec ${spec.id} requires grounding metadata but has no grounded criteria records.`);
+    }
+    for (const record of records) {
+        if (record.source === 'ungrounded_advisory') {
+            issues.push(`Criterion is advisory-only and cannot be approved as contract: ${record.text}`);
+        }
+        if (record.evidence.length === 0 && record.source !== 'ungrounded_advisory') {
+            issues.push(`Criterion has no grounding evidence: ${record.text}`);
+        }
+    }
+    const technicalRecords = parseTechnicalReferenceGroundingRecords(frontmatter);
+    for (const record of technicalRecords) {
+        if (record.source === 'ungrounded_advisory') {
+            issues.push(`Technical reference is advisory-only and cannot be contract: ${record.path}`);
+        }
+        if (record.evidence.length === 0 && record.source !== 'ungrounded_advisory') {
+            issues.push(`Technical reference has no grounding evidence: ${record.path}`);
+        }
+    }
+    return {
+        passed: issues.length === 0,
+        required: true,
+        issues,
+        records,
+    };
+}
+export function parseCriterionGroundingRecords(frontmatter) {
+    const records = [];
+    const chunks = frontmatter.split(/\n\s{4}- text:\s*/).slice(1);
+    for (const chunk of chunks) {
+        const text = /^"((?:\\"|[^"])*)"/.exec(chunk)?.[1]?.replace(/\\"/g, '"') ?? '';
+        const source = /^\s{6}source:\s*(\S+)/m.exec(chunk)?.[1];
+        const confidence = /^\s{6}confidence:\s*(\S+)/m.exec(chunk)?.[1];
+        const evidenceRaw = /^\s{6}evidence:\s*\[(.*)\]/m.exec(chunk)?.[1] ?? '';
+        if (!text || !source || !confidence) {
+            continue;
+        }
+        records.push({
+            text,
+            source,
+            evidence: parseYamlInlineStringArray(evidenceRaw),
+            confidence,
+        });
+    }
+    return records;
+}
+export function parseTechnicalReferenceGroundingRecords(frontmatter) {
+    const records = [];
+    const chunks = frontmatter.split(/\n\s{4}- path:\s*/).slice(1);
+    for (const chunk of chunks) {
+        const path = /^"((?:\\"|[^"])*)"/.exec(chunk)?.[1]?.replace(/\\"/g, '"') ?? '';
+        const section = /^\s{6}section:\s*(\S+)/m.exec(chunk)?.[1];
+        const source = /^\s{6}source:\s*(\S+)/m.exec(chunk)?.[1];
+        const confidence = /^\s{6}confidence:\s*(\S+)/m.exec(chunk)?.[1];
+        const evidenceRaw = /^\s{6}evidence:\s*\[(.*)\]/m.exec(chunk)?.[1] ?? '';
+        if (!path || !section || !source || !confidence) {
+            continue;
+        }
+        records.push({
+            path,
+            section,
+            source,
+            evidence: parseYamlInlineStringArray(evidenceRaw),
+            confidence,
+        });
+    }
+    return records;
+}
+function parseYamlInlineStringArray(raw) {
+    if (raw.trim().length === 0) {
+        return [];
+    }
+    const matches = raw.matchAll(/"((?:\\"|[^"])*)"/g);
+    return [...matches].map((match) => match[1]?.replace(/\\"/g, '"') ?? '').filter(Boolean);
+}
+function escapeYaml(value) {
+    return value.replace(/"/g, '\\"');
+}
+//# sourceMappingURL=contract.js.map

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