@devtrack-solution/codesdd 1.2.2 → 1.2.4-rc3

package/dist/core/sdd/services/finalize.service.js

@@ -1,19 +1,80 @@
 import path from "node:path";
 import { existsSync, promises as fs } from "node:fs";
-import { LENSES, validateDocumentAgainstLens } from "../lenses.js";
 import { adrFileName } from "../adr.js";
+import { evaluateAdrGovernorDocument } from "../deepagents/adr-governor.js";
+import { evaluateQualityWitnessMatrix } from "../deepagents/quality-witness.js";
 import { evaluateFeatureFinalizeGuardrails } from "../domain/lifecycle-guardrails.js";
 import { runLifecycleHooks } from "../domain/lifecycle-hooks.js";
 import { evaluateWorkspaceTraceability } from "../domain/traceability.js";
-import { validatePostActiveFeaturePlacement, validatePreFinalizeArchiveCanonicalization, } from "../domain/post-active-validation.js";
+import { normalizeArchivedFeatureActiveReferences, validatePostActiveFeaturePlacement, validatePreFinalizeArchiveCanonicalization, } from "../domain/post-active-validation.js";
 import { loadStateSnapshot, nowIso, saveStateTransaction } from "../state.js";
 import { syncSddGuideDocs } from "../docs-sync.js";
 import { mergeArchitectureNode, mergeFrontendDecisionRecord, mergeRepoMapRecord, mergeServiceRecord, mergeTechStackRecord, stableUniqueStrings, upsertByKey } from "../merge-catalog.js";
-import { getRuntime, persistAndRender, relProjectPath, coreDocRef, activeDocNamesForLayout, activeDocCandidateNames, unresolvedDependencies, updateDependencyMetadata, gitChangedFiles, detectFrontendImpactEvidence, maybeCreateAutomaticFrontendGap, buildFinalizeQueue, evaluateFeatureQuality, buildAdrMarkdown, applyLoggedTransition, gateSatisfied, pathExists, RADAR_TO_DISCOVERY_STATUS } from "../legacy-operations.js";
+import { getRuntime, persistAndRender, relProjectPath, coreDocRef, activeDocNamesForLayout, activeDocCandidateNames, unresolvedDependencies, updateDependencyMetadata, gitChangedFiles, detectFrontendImpactEvidence, maybeCreateAutomaticFrontendGap, buildFinalizeQueue, evaluateFeatureQuality, buildAdrMarkdown, applyLoggedTransition, gateSatisfied, pathExists, computeReadyFeatures, extractFeatureNumber, buildDependentsMap, scoreReadyItem, RADAR_TO_DISCOVERY_STATUS } from "../legacy-operations.js";
 import { SddWriteTransaction } from "../write-manifest.js";
 import { withStateLock } from "../state-lock.js";
 import { activeWorkspaceDeclaresMandatoryAdrImpact } from "../adr-policy.js";
-import { parseWorkspaceYamlDocument, } from "../workspace-schemas.js";
+import { normalizeFeatRef } from "../entity-reference.js";
+import { parseWorkspaceYamlDocument, stringifyWorkspaceYamlDocument, } from "../workspace-schemas.js";
+function recordFinalizeHistory(history, item) {
+    const index = history.findIndex((entry) => entry.feature_id === item.feature_id);
+    if (index >= 0) {
+        history[index] = item;
+        return;
+    }
+    history.push(item);
+    history.sort((a, b) => a.feature_id.localeCompare(b.feature_id));
+}
+function moveCompletedFinalizeItemsToHistory(state) {
+    const activeItems = [];
+    for (const item of state.items) {
+        if (item.status === 'DONE') {
+            recordFinalizeHistory(state.history, {
+                feature_id: item.feature_id,
+                status: 'DONE',
+                summary: item.summary,
+                created_at: item.created_at,
+                completed_at: item.completed_at || item.created_at || '',
+            });
+        }
+        else {
+            activeItems.push(item);
+        }
+    }
+    state.items = activeItems;
+}
+function buildPostFinalizeReplan(items, finalized, unlocked, generatedAt) {
+    const rank = 'impact';
+    const computed = computeReadyFeatures(items, { rank });
+    const dependentsMap = buildDependentsMap(items);
+    const ready = computed.ready
+        .map((item) => {
+        const scored = scoreReadyItem(item, items, dependentsMap, rank);
+        return {
+            id: item.id,
+            title: item.title,
+            recommended_skills: item.recommended_skills.slice(0, 3),
+            score: scored.score,
+            reasons: scored.reasons,
+        };
+    })
+        .sort((left, right) => {
+        if (right.score !== left.score)
+            return right.score - left.score;
+        return extractFeatureNumber(left.id) - extractFeatureNumber(right.id);
+    })
+        .slice(0, 10);
+    return {
+        rank,
+        generated_at: generatedAt,
+        finalized,
+        unlocked,
+        ready,
+        waves: computed.waves,
+        blocked_count: computed.blocked.length,
+        conflicts_count: computed.conflicts.length,
+    };
+}
 export class FinalizeService {
     stores;
     constructor(stores) {
@@ -23,6 +84,7 @@ export class FinalizeService {
         const { config, paths } = await getRuntime(projectRoot);
         return withStateLock(paths.stateDir, async () => {
             const snapshot = await loadStateSnapshot(paths, config);
+            moveCompletedFinalizeItemsToHistory(snapshot.finalizeQueue);
             snapshot.finalizeQueue.items = await buildFinalizeQueue(paths, snapshot.backlog.items, snapshot.finalizeQueue.items);
             const pending = snapshot.finalizeQueue.items.filter((item) => item.status === 'PENDING');
             const inferredRef = options?.allReady
@@ -45,6 +107,7 @@ export class FinalizeService {
                     finalized: [],
                     unblocked: [],
                     pending: pending.length,
+                    post_finalize_replan: buildPostFinalizeReplan(snapshot.backlog.items, [], [], nowIso()),
                     updated_core_docs: [],
                     updated_readme: false,
                     updated_agent_guide: false,
@@ -197,6 +260,14 @@ export class FinalizeService {
                     }
                     docWarnings.push(`${feature.id} finalized with --force-transition despite privacy compliance guardrail warnings.`);
                 }
+                const devtrackApiPolicyGuardrail = await evaluateDevTrackApiPolicyGates(paths, config, feature);
+                if (!devtrackApiPolicyGuardrail.ok) {
+                    docWarnings.push(`${feature.id} devtrack-api policy gate blocked finalize: ${devtrackApiPolicyGuardrail.reasons.join(' | ')}`);
+                    if (!options?.forceTransition) {
+                        continue;
+                    }
+                    docWarnings.push(`${feature.id} finalized with --force-transition despite devtrack-api policy gate warnings.`);
+                }
                 if (!feature.requires_adr && (await activeWorkspaceDeclaresMandatoryAdrImpact(paths, feature))) {
                     feature.requires_adr = true;
                 }
@@ -204,20 +275,14 @@ export class FinalizeService {
                     const requiredAdrPath = path.join(paths.coreDir, 'adrs', adrFileName(feature.id));
                     const adrContent = await fs.readFile(requiredAdrPath, 'utf-8').catch(() => '');
                     if (!adrContent.trim()) {
-                        docWarnings.push(`${feature.id} exige ADR obrigatório ausente: ${relProjectPath(paths, requiredAdrPath)}`);
-                        if (!options?.forceTransition) {
-                            continue;
-                        }
-                        docWarnings.push(`${feature.id} finalizada com --force-transition sem ADR obrigatório preenchido.`);
+                        docWarnings.push(`${feature.id} adr governor blocked finalize: ADR obrigatório ausente: ${relProjectPath(paths, requiredAdrPath)}`);
+                        continue;
                     }
                     else {
-                        const adrViolations = validateDocumentAgainstLens(adrContent, LENSES.adr);
+                        const adrViolations = evaluateAdrGovernorDocument(adrContent);
                         if (adrViolations.length > 0) {
-                            docWarnings.push(`${feature.id} ADR obrigatório inválido: ${adrViolations.join(' | ')}`);
-                            if (!options?.forceTransition) {
-                                continue;
-                            }
-                            docWarnings.push(`${feature.id} finalizada com --force-transition apesar de violações no ADR obrigatório.`);
+                            docWarnings.push(`${feature.id} adr governor blocked finalize: ADR obrigatório inválido: ${adrViolations.join(' | ')}`);
+                            continue;
                         }
                     }
                 }
@@ -261,6 +326,7 @@ export class FinalizeService {
                         afterTransition: (currentFeature) => {
                             currentFeature.current_stage = 'consolidacao';
                             currentFeature.done_at = now;
+                            currentFeature.archived_at = now;
                             currentFeature.last_sync_at = now;
                         },
                     });
@@ -270,19 +336,14 @@ export class FinalizeService {
                     continue;
                 }
                 const queue = snapshot.finalizeQueue.items.find((item) => item.feature_id === featureId);
-                if (queue) {
-                    queue.status = 'DONE';
-                    queue.completed_at = now;
-                }
-                else {
-                    snapshot.finalizeQueue.items.push({
-                        feature_id: featureId,
-                        status: 'DONE',
-                        summary: `Finalizado manualmente: ${featureId}`,
-                        created_at: now,
-                        completed_at: now,
-                    });
-                }
+                snapshot.finalizeQueue.items = snapshot.finalizeQueue.items.filter((item) => item.feature_id !== featureId);
+                recordFinalizeHistory(snapshot.finalizeQueue.history, {
+                    feature_id: featureId,
+                    status: 'DONE',
+                    summary: queue?.summary || `Finalizado manualmente: ${featureId}`,
+                    created_at: queue?.created_at || now,
+                    completed_at: now,
+                });
                 if ((feature.origin_type === 'radar' || feature.origin_type === 'epic') && feature.origin_ref) {
                     const siblings = snapshot.backlog.items.filter((item) => (item.origin_type === 'radar' || item.origin_type === 'epic') && item.origin_ref === feature.origin_ref);
                     if (siblings.every((item) => item.status === 'DONE' || item.status === 'ARCHIVED')) {
@@ -395,6 +456,7 @@ export class FinalizeService {
                 }
                 await fs.mkdir(paths.archivedDir, { recursive: true });
                 await fs.rename(activeDirPath, archivedDirPath);
+                await normalizeArchivedFeatureActiveReferences(paths, feature.id);
                 const postActiveValidation = await validatePostActiveFeaturePlacement(paths, feature.id);
                 if (!postActiveValidation.ok) {
                     if (!(await pathExists(activeDirPath)) && (await pathExists(archivedDirPath))) {
@@ -415,6 +477,7 @@ export class FinalizeService {
                 });
             }
             updateDependencyMetadata(snapshot.backlog.items);
+            const postFinalizeReplan = buildPostFinalizeReplan(snapshot.backlog.items, finalized, Array.from(unblocked).sort(), now);
             const stateUpdates = {
                 discoveryIndex: snapshot.discoveryIndex,
                 backlog: snapshot.backlog,
@@ -448,6 +511,7 @@ export class FinalizeService {
                 finalized,
                 unblocked: Array.from(unblocked).sort(),
                 pending: remaining,
+                post_finalize_replan: postFinalizeReplan,
                 updated_core_docs: Array.from(updatedCoreDocs).sort(),
                 updated_readme: syncResult.updatedReadme,
                 updated_agent_guide: syncResult.updatedAgentGuide || syncResult.updatedRootAgents,
@@ -458,9 +522,9 @@ export class FinalizeService {
         });
     }
 }
-async function inferFinalizeTarget(paths, pending, explicitRef, cwd) {
+export async function inferFinalizeTarget(paths, pending, explicitRef, cwd) {
     if (explicitRef)
-        return explicitRef;
+        return normalizeFeatRef(explicitRef) ?? explicitRef;
     const activeEntries = await fs.readdir(paths.activeDir, { withFileTypes: true }).catch(() => []);
     const activeFeatures = activeEntries
         .filter((entry) => entry.isDirectory() && /^FEAT-\d{4}$/.test(entry.name))
@@ -483,13 +547,13 @@ async function inferFinalizeTarget(paths, pending, explicitRef, cwd) {
     }
     return undefined;
 }
-function isPrivacyComplianceFeature(feature) {
+export function isPrivacyComplianceFeature(feature) {
     if (feature.origin_ref === 'EPIC-0020' || feature.origin_ref === 'EPIC-0021')
         return true;
     const refs = new Set(feature.acceptance_refs || []);
     return refs.has('EPIC-0020') || refs.has('EPIC-0021') || refs.has('DEB-0021') || refs.has('INS-0021');
 }
-async function evaluatePrivacyFinalizeGuardrail(paths, config, feature) {
+export async function evaluatePrivacyFinalizeGuardrail(paths, config, feature) {
     if (!isPrivacyComplianceFeature(feature)) {
         return { ok: true, reasons: [] };
     }
@@ -576,7 +640,46 @@ async function evaluatePrivacyFinalizeGuardrail(paths, config, feature) {
     }
     return { ok: reasons.length === 0, reasons };
 }
-async function evaluateWorkspaceQualityFeedback(paths, config, feature) {
+export async function evaluateDevTrackApiPolicyGates(paths, config, feature) {
+    const activePath = path.join(paths.activeDir, feature.id);
+    const names = activeDocNamesForLayout(config);
+    const qualityPath = path.join(activePath, names.quality);
+    const qualityContent = await fs.readFile(qualityPath, 'utf-8').catch(() => '');
+    if (!qualityContent.trim()) {
+        return { ok: true, reasons: [] };
+    }
+    let quality;
+    try {
+        quality = parseWorkspaceYamlDocument('5-quality.yaml', qualityContent);
+    }
+    catch {
+        return { ok: true, reasons: [] };
+    }
+    const reasons = evaluateDevTrackApiPolicyEvidence(quality);
+    return { ok: reasons.length === 0, reasons };
+}
+export function evaluateDevTrackApiPolicyEvidence(quality) {
+    const policyRequirements = [
+        ...(quality.skill_evidence?.policy_requirements ?? []),
+        ...(quality.policy_injection?.required_policies ?? []),
+    ];
+    if (policyRequirements.length === 0) {
+        return [];
+    }
+    const evidenceEntries = quality.skill_evidence?.evidence ?? [];
+    const hasDevTrackApiEvidence = evidenceEntries.some((entry) => entry.skill_id === 'devtrack-api');
+    const reasons = new Set();
+    for (const policy of policyRequirements) {
+        if (policy.skill_id !== 'devtrack-api' || policy.enforcement !== 'blocking') {
+            continue;
+        }
+        if (!hasDevTrackApiEvidence) {
+            reasons.add(`devtrack-api policy gate: blocking skill "devtrack-api" lacks evidence in skill_evidence (required rules: ${policy.required_rule_refs.join(', ')})`);
+        }
+    }
+    return Array.from(reasons);
+}
+export async function evaluateWorkspaceQualityFeedback(paths, config, feature) {
     const activePath = path.join(paths.activeDir, feature.id);
     const names = activeDocNamesForLayout(config);
     const artifactName = [names.quality, ...activeDocCandidateNames(config)].find((name) => name === '5-quality.yaml' && existsSync(path.join(activePath, name))) || '';
@@ -598,9 +701,13 @@ async function evaluateWorkspaceQualityFeedback(paths, config, feature) {
     }
     const missingTargets = missingCoverageTargets(document);
     const missingSkills = missingSkillEvidence(document);
+    const matrixReasons = evaluateQualityWitnessMatrix(document);
     const reasons = [];
     const maxRounds = document.remediation_policy.max_rounds;
     const rounds = countQualityEvidenceRounds(document);
+    const q95Ledger = await computeQ95Ledger(paths, config, feature, document);
+    document.q95_ledger = q95Ledger;
+    await fs.writeFile(artifactPath, stringifyWorkspaceYamlDocument('5-quality.yaml', document), 'utf-8');
     if (rounds > maxRounds && document.exceptions.length === 0) {
         reasons.push(`quality remediation max_rounds exceeded (${rounds}/${maxRounds}); formal exception required in ${artifact}`);
     }
@@ -621,9 +728,15 @@ async function evaluateWorkspaceQualityFeedback(paths, config, feature) {
     if (missingSkills.length > 0) {
         reasons.push(`required skill evidence missing for ${missingSkills.join(', ')}`);
     }
+    if (matrixReasons.length > 0) {
+        reasons.push(`quality-witness matrix blocked finalize: ${matrixReasons.join(' | ')}`);
+    }
+    if (q95Ledger.score < q95Ledger.threshold && document.exceptions.length === 0) {
+        reasons.push(`Q95 composite score below threshold (${q95Ledger.score.toFixed(2)} < ${q95Ledger.threshold}); next best action: ${q95Ledger.next_best_action}`);
+    }
     return { ok: reasons.length === 0, reasons, artifact };
 }
-async function evaluateWorkspaceTraceabilityFeedback(paths, config, feature) {
+export async function evaluateWorkspaceTraceabilityFeedback(paths, config, feature) {
     const activePath = path.join(paths.activeDir, feature.id);
     const names = activeDocNamesForLayout(config);
     const specPath = path.join(activePath, names.spec);
@@ -666,14 +779,362 @@ async function evaluateWorkspaceTraceabilityFeedback(paths, config, feature) {
         artifact,
     };
 }
-function missingCoverageTargets(document) {
+export async function computeQ95Ledger(paths, config, feature, document) {
+    const threshold = document.q95_ledger?.threshold ?? 95;
+    const weights = {
+        coverage: document.q95_ledger?.weights?.coverage ?? 30,
+        traceability: document.q95_ledger?.weights?.traceability ?? 20,
+        integrity: document.q95_ledger?.weights?.integrity ?? 20,
+        naming: document.q95_ledger?.weights?.naming ?? 10,
+        token: document.q95_ledger?.weights?.token ?? 20,
+    };
+    const coverage = computeCoverageAxis(document);
+    const traceability = await computeTraceabilityAxis(paths, config, feature, document);
+    const integrity = computeIntegrityAxis(document);
+    const naming = computeNamingAxis(feature, document);
+    const token = computeTokenAxis(document);
+    const axes = {
+        coverage: weightedAxis(coverage, weights.coverage),
+        traceability: weightedAxis(traceability, weights.traceability),
+        integrity: weightedAxis(integrity, weights.integrity),
+        naming: weightedAxis(naming, weights.naming),
+        token: weightedAxis(token, weights.token),
+    };
+    const score = round2(axes.coverage.weighted_score +
+        axes.traceability.weighted_score +
+        axes.integrity.weighted_score +
+        axes.naming.weighted_score +
+        axes.token.weighted_score);
+    const status = score >= threshold ? 'pass' : 'fail';
+    return {
+        threshold,
+        score,
+        status,
+        computed_at: nowIso(),
+        weights,
+        axes,
+        next_best_action: inferQ95NextAction(axes),
+    };
+}
+export function weightedAxis(input, weight) {
+    return {
+        raw_score: clampPercent(input.raw_score),
+        weighted_score: round2((clampPercent(input.raw_score) * weight) / 100),
+        rationale: input.rationale,
+    };
+}
+export function computeCoverageAxis(document) {
+    const unit = extractCoveragePerformance(document, 'unit');
+    const integration = extractCoveragePerformance(document, 'integration');
+    const raw = round2((unit + integration) / 2);
+    return {
+        raw_score: raw,
+        rationale: `unit=${unit.toFixed(2)} integration=${integration.toFixed(2)} derived from evidence_log`,
+    };
+}
+export async function computeTraceabilityAxis(paths, config, feature, document) {
+    if ((document.traceability?.requirements?.length ?? 0) === 0) {
+        return {
+            raw_score: 100,
+            rationale: 'no requirement matrix declared yet; dedicated traceability guardrail remains authoritative',
+        };
+    }
+    const activePath = path.join(paths.activeDir, feature.id);
+    const names = activeDocNamesForLayout(config);
+    const specPath = path.join(activePath, names.spec);
+    const changelogPath = path.join(activePath, names.changelog);
+    const [specContent, changelogContent] = await Promise.all([
+        fs.readFile(specPath, 'utf-8').catch(() => ''),
+        fs.readFile(changelogPath, 'utf-8').catch(() => ''),
+    ]);
+    if (!specContent.trim() || !changelogContent.trim()) {
+        return {
+            raw_score: 70,
+            rationale: 'traceability matrix exists but spec/changelog evidence is unavailable for Q95 composite scoring',
+        };
+    }
+    try {
+        const spec = parseWorkspaceYamlDocument('1-spec.yaml', specContent);
+        const changelog = parseWorkspaceYamlDocument('4-changelog.yaml', changelogContent);
+        const result = evaluateWorkspaceTraceability(paths.projectRoot, spec, changelog, document);
+        return result.ok
+            ? { raw_score: 100, rationale: 'traceability closure validated successfully' }
+            : { raw_score: 70, rationale: result.reasons.join(' | ') };
+    }
+    catch (error) {
+        return {
+            raw_score: 70,
+            rationale: `traceability parse error: ${error.message}`,
+        };
+    }
+}
+export function computeIntegrityAxis(document) {
+    const requiredSkillIds = Array.from(new Set((document.skill_evidence?.required_skill_ids ?? []).map((value) => value.trim()).filter(Boolean)));
+    const providedSkills = new Set((document.skill_evidence?.evidence ?? [])
+        .map((entry) => entry.skill_id.trim().toLowerCase())
+        .filter(Boolean));
+    const coveredSkills = requiredSkillIds.filter((id) => providedSkills.has(id.toLowerCase())).length;
+    const skillScore = requiredSkillIds.length === 0 ? 100 : round2((coveredSkills / requiredSkillIds.length) * 100);
+    const security = document.security_integrity;
+    const securityScore = !security
+        ? 100
+        : round2([
+            integritySignalScore(security.endpoint_auth_review),
+            integritySignalScore(security.sensitive_data_exposure_review),
+            integritySignalScore(security.incident_response_review),
+        ].reduce((acc, value) => acc + value, 0) / 3);
+    const runtimeQuality = computeRuntimeQualityAxis(document);
+    const raw = round2(skillScore * 0.55 + securityScore * 0.25 + runtimeQuality.raw_score * 0.2);
+    return {
+        raw_score: raw,
+        rationale: `skill_evidence=${skillScore.toFixed(2)} security_integrity=${securityScore.toFixed(2)} runtime_quality=${runtimeQuality.raw_score.toFixed(2)} (${runtimeQuality.rationale})`,
+    };
+}
+export function computeRuntimeQualityAxis(document) {
+    const gates = document.runtime_quality_gates;
+    const performance = gates?.performance ?? [];
+    const flakiness = gates?.flakiness ?? [];
+    const entries = [
+        ...performance.map((entry) => ({ kind: 'performance', gate: entry.gate, evidence: entry.evidence_ref, score: runtimePerformanceScore(entry) })),
+        ...flakiness.map((entry) => ({ kind: 'flakiness', gate: entry.gate, evidence: entry.evidence_ref, score: runtimeFlakinessScore(entry) })),
+    ];
+    if (entries.length === 0) {
+        return {
+            raw_score: 100,
+            rationale: 'runtime quality telemetry not provided; neutral score applied',
+        };
+    }
+    const scores = entries.map((entry) => {
+        if (entry.gate === 'fail')
+            return Math.min(entry.score, 70);
+        if (entry.gate === 'warn')
+            return Math.min(entry.score, 85);
+        return entry.score;
+    });
+    const worst = Math.min(...scores);
+    const failed = entries.filter((entry) => entry.gate === 'fail').map((entry) => `${entry.kind}:${entry.evidence ?? 'runtime evidence'}`);
+    const warned = entries.filter((entry) => entry.gate === 'warn').map((entry) => `${entry.kind}:${entry.evidence ?? 'runtime evidence'}`);
+    const notes = [...failed.map((value) => `${value} failed`), ...warned.map((value) => `${value} warned`)];
+    return {
+        raw_score: worst,
+        rationale: `runtime quality gate scored ${worst.toFixed(2)}${notes.length > 0 ? `; ${notes.join('; ')}` : ''}`,
+    };
+}
+function runtimePerformanceScore(entry) {
+    if (entry.actual !== undefined && entry.threshold !== undefined && entry.threshold > 0) {
+        return clampPercent((entry.threshold / Math.max(entry.actual, 1)) * 100);
+    }
+    return entry.gate === 'pass' ? 100 : entry.gate === 'warn' ? 85 : 70;
+}
+function runtimeFlakinessScore(entry) {
+    let failureRate = entry.failure_rate_percent;
+    if (failureRate === undefined && entry.attempts !== undefined && entry.failures !== undefined && entry.attempts > 0) {
+        failureRate = clampPercent((entry.failures / entry.attempts) * 100);
+    }
+    if (failureRate === undefined) {
+        return entry.gate === 'pass' ? 100 : entry.gate === 'warn' ? 85 : 70;
+    }
+    return clampPercent(100 - failureRate);
+}
+const LEGACY_NAMING_PATTERNS = [
+    /\bcoachsdd\b/u,
+    /\bcoach\s+sdd\b/u,
+    /\bcoach-sdd\b/u,
+    /\bcoach_sdd\b/u,
+    /\bsdd\s+coach\b/u,
+    /\.codesdd\b/u,
+];
+export function computeNamingAxis(feature, document) {
+    let score = 100;
+    const rationale = [];
+    if (!/^FEAT-\d{4,}$/.test(feature.id)) {
+        score -= 40;
+        rationale.push('feature id not canonical FEAT-####');
+    }
+    if (!feature.title || feature.title.trim().length < 10) {
+        score -= 30;
+        rationale.push('feature title too short');
+    }
+    const combined = JSON.stringify({ title: feature.title || '', quality: document }).toLowerCase();
+    if (LEGACY_NAMING_PATTERNS.some((pattern) => pattern.test(combined))) {
+        score -= 30;
+        rationale.push('legacy naming detected in active quality context by naming-contract forbidden terms');
+    }
+    return {
+        raw_score: clampPercent(score),
+        rationale: rationale.length > 0 ? rationale.join('; ') : 'canonical naming and state metadata checks passed',
+    };
+}
+export function computeTokenAxis(document) {
+    const structuredTelemetry = document.token_budget_gates?.telemetry ?? [];
+    if (structuredTelemetry.length > 0) {
+        return computeStructuredTokenAxis(document);
+    }
+    const tokenEntries = document.evidence_log.filter((entry) => {
+        const label = `${entry.kind} ${entry.result}`.toLowerCase();
+        return label.includes('token');
+    });
+    if (tokenEntries.length === 0) {
+        return {
+            raw_score: 100,
+            rationale: 'token telemetry not provided; neutral score applied until FEAT token harness evidence is recorded',
+        };
+    }
+    const percents = [];
+    for (const entry of tokenEntries) {
+        const matches = entry.result.match(/(\d+(?:\.\d+)?)\s*%/g) ?? [];
+        for (const match of matches) {
+            const value = Number(match.replace('%', '').trim());
+            if (Number.isFinite(value)) {
+                percents.push(clampPercent(value));
+            }
+        }
+    }
+    if (percents.length > 0) {
+        const best = Math.max(...percents);
+        return {
+            raw_score: best,
+            rationale: `token efficiency evidence detected (${best.toFixed(2)}%)`,
+        };
+    }
+    return {
+        raw_score: 70,
+        rationale: 'token evidence found but no numeric percentage; conservative score applied',
+    };
+}
+export function computeStructuredTokenAxis(document) {
+    const gates = document.token_budget_gates;
+    const telemetry = gates?.telemetry ?? [];
+    const requireNumeric = gates?.require_numeric_efficiency ?? true;
+    const failBelow = gates?.fail_below_percent ?? 95;
+    const scores = [];
+    const reasons = [];
+    let hardFailure = false;
+    for (const entry of telemetry) {
+        let score = entry.efficiency_percent;
+        if (score === undefined && entry.budget_chars !== undefined && entry.actual_chars !== undefined) {
+            score = entry.actual_chars === 0 ? 100 : clampPercent((entry.budget_chars / entry.actual_chars) * 100);
+        }
+        if (score === undefined && entry.actual_chars !== undefined && gates?.max_context_chars !== undefined) {
+            score = entry.actual_chars === 0 ? 100 : clampPercent((gates.max_context_chars / entry.actual_chars) * 100);
+        }
+        if (score === undefined) {
+            if (requireNumeric) {
+                scores.push(70);
+                reasons.push(`${entry.evidence_ref ?? 'token telemetry'} lacks numeric efficiency`);
+            }
+            continue;
+        }
+        const normalized = clampPercent(score);
+        scores.push(normalized);
+        if (entry.gate === 'fail' || normalized < failBelow) {
+            hardFailure = true;
+            reasons.push(`${entry.evidence_ref ?? 'token telemetry'} below ${failBelow}%`);
+        }
+        else if (entry.gate === 'warn') {
+            reasons.push(`${entry.evidence_ref ?? 'token telemetry'} warned at ${normalized.toFixed(2)}%`);
+        }
+    }
+    if (scores.length === 0) {
+        return {
+            raw_score: requireNumeric ? 70 : 100,
+            rationale: requireNumeric
+                ? 'token budget gate requires numeric efficiency but no numeric telemetry was provided'
+                : 'token budget telemetry provided without numeric scoring requirement',
+        };
+    }
+    const worst = Math.min(...scores);
+    if (hardFailure) {
+        return {
+            raw_score: Math.min(worst, 70),
+            rationale: `token budget gate failed: ${reasons.join('; ')}`,
+        };
+    }
+    return {
+        raw_score: worst,
+        rationale: `token budget gate satisfied (${worst.toFixed(2)}% worst-case efficiency)${reasons.length > 0 ? `; ${reasons.join('; ')}` : ''}`,
+    };
+}
+export function extractCoveragePerformance(document, kind) {
+    const target = kind === 'unit' ? document.coverage_targets.unit : document.coverage_targets.integration;
+    const relevant = document.evidence_log.filter((entry) => {
+        const evidenceKind = entry.kind.toLowerCase();
+        return (evidenceKind.includes(kind) ||
+            evidenceKind.includes('coverage') ||
+            (kind === 'integration' && evidenceKind.includes('e2e')));
+    });
+    if (relevant.length === 0)
+        return 0;
+    const values = relevant.flatMap((entry) => {
+        const matches = entry.result.match(/\d+(?:\.\d+)?/g) ?? [];
+        return matches.map(Number).filter((value) => Number.isFinite(value) && value >= 0 && value <= 100);
+    });
+    if (values.length === 0)
+        return 0;
+    const best = Math.max(...values);
+    if (target <= 0)
+        return 100;
+    return clampPercent((best / target) * 100);
+}
+export function integritySignalScore(value) {
+    if (value === 'passed' || value === 'not_applicable')
+        return 100;
+    if (value === 'pending')
+        return 50;
+    return 0;
+}
+export function inferQ95NextAction(axes) {
+    const ranking = [
+        { axis: 'coverage', weightedGap: 30 - axes.coverage.weighted_score, rawGap: 100 - axes.coverage.raw_score },
+        {
+            axis: 'traceability',
+            weightedGap: 20 - axes.traceability.weighted_score,
+            rawGap: 100 - axes.traceability.raw_score,
+        },
+        { axis: 'integrity', weightedGap: 20 - axes.integrity.weighted_score, rawGap: 100 - axes.integrity.raw_score },
+        { axis: 'naming', weightedGap: 10 - axes.naming.weighted_score, rawGap: 100 - axes.naming.raw_score },
+        { axis: 'token', weightedGap: 20 - axes.token.weighted_score, rawGap: 100 - axes.token.raw_score },
+    ];
+    ranking.sort((a, b) => b.weightedGap - a.weightedGap || b.rawGap - a.rawGap);
+    const primary = ranking[0];
+    if (!primary || primary.weightedGap <= 0) {
+        return 'Q95 satisfied. Keep evidence_log and traceability synchronized for future rounds.';
+    }
+    switch (primary.axis) {
+        case 'coverage':
+            return 'Add or update unit/integration evidence entries with numeric percentages that meet coverage_targets.';
+        case 'traceability':
+            return 'Complete traceability.spec_anchor and traceability.requirements links across spec, changelog, code, and tests.';
+        case 'integrity':
+            return 'Record required skill evidence and close pending security_integrity reviews when applicable.';
+        case 'naming':
+            return 'Fix canonical naming drift in FEAT metadata and avoid legacy governance aliases in quality artifacts.';
+        case 'token':
+            return 'Record token efficiency telemetry (percentage) in evidence_log to score the token axis explicitly.';
+        default:
+            return 'Record missing evidence to raise the lowest weighted axis.';
+    }
+}
+export function clampPercent(value) {
+    if (!Number.isFinite(value))
+        return 0;
+    if (value < 0)
+        return 0;
+    if (value > 100)
+        return 100;
+    return value;
+}
+export function round2(value) {
+    return Math.round(value * 100) / 100;
+}
+export function missingCoverageTargets(document) {
     const targets = [
         { kind: 'unit', target: document.coverage_targets.unit },
         { kind: 'integration', target: document.coverage_targets.integration },
     ];
     return targets.filter((target) => !coverageTargetMet(document, target.kind, target.target));
 }
-function coverageTargetMet(document, kind, target) {
+export function coverageTargetMet(document, kind, target) {
     return document.evidence_log.some((entry) => {
         const evidenceKind = entry.kind.toLowerCase();
         const result = entry.result.toLowerCase();
@@ -687,14 +1148,14 @@ function coverageTargetMet(document, kind, target) {
         return percentages.some((value) => value >= target);
     });
 }
-function countQualityEvidenceRounds(document) {
+export function countQualityEvidenceRounds(document) {
     const roundKinds = ['round', 'unit', 'integration', 'e2e', 'coverage', 'validation', 'test', 'build'];
     return document.evidence_log.filter((entry) => {
         const kind = entry.kind.toLowerCase();
         return roundKinds.some((token) => kind.includes(token));
     }).length;
 }
-function missingSkillEvidence(document) {
+export function missingSkillEvidence(document) {
     const required = Array.from(new Set((document.skill_evidence?.required_skill_ids ?? []).map((value) => value.trim()).filter(Boolean)));
     if (required.length === 0) {
         return [];