@devtrack-solution/codesdd 1.2.2 → 1.2.3

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

@@ -1,11 +1,12 @@
 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";
@@ -13,7 +14,8 @@ import { getRuntime, persistAndRender, relProjectPath, coreDocRef, activeDocName
 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";
 export class FinalizeService {
     stores;
     constructor(stores) {
@@ -197,6 +199,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 +214,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 +265,7 @@ export class FinalizeService {
                         afterTransition: (currentFeature) => {
                             currentFeature.current_stage = 'consolidacao';
                             currentFeature.done_at = now;
+                            currentFeature.archived_at = now;
                             currentFeature.last_sync_at = now;
                         },
                     });
@@ -395,6 +400,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))) {
@@ -458,9 +464,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 +489,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 +582,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 +643,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 +670,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 +721,258 @@ 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 raw = round2(skillScore * 0.7 + securityScore * 0.3);
+    return {
+        raw_score: raw,
+        rationale: `skill_evidence=${skillScore.toFixed(2)} security_integrity=${securityScore.toFixed(2)}`,
+    };
+}
+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 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 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 +986,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 [];

package/dist/core/sdd/services/frontend-gap.service.js

@@ -2,6 +2,12 @@ import { CLI_NAME } from "../../branding.js";
 import { allocateEntityId, loadStateSnapshot, nowIso, saveStateTransaction } from "../state.js";
 import { slugify, getRuntime, persistAndRender } from "../legacy-operations.js";
 import { withStateLock } from "../state-lock.js";
+function firstNonEmpty(values) {
+    return (values || []).map((value) => value.trim()).find(Boolean) || '';
+}
+function routeLabelFromGap(title, routePath) {
+    return title.trim() || routePath;
+}
 export class FrontendGapService {
     stores;
     constructor(stores) {
@@ -41,17 +47,20 @@ export class FrontendGapService {
             for (const routePath of options?.routes || []) {
                 const routeId = `route-${slugify(routePath) || 'root'}`;
                 const existing = snapshot.frontendMap.routes.find((route) => route.id === routeId);
+                const navSurface = firstNonEmpty(options?.menu);
                 if (existing) {
                     existing.ui_status = existing.ui_status === 'OK' ? 'PARTIAL' : existing.ui_status;
                     existing.source_gap_ids = Array.from(new Set([...existing.source_gap_ids, id]));
+                    existing.label = existing.label || routeLabelFromGap(title, routePath);
+                    existing.nav_surface = existing.nav_surface || navSurface;
                 }
                 else {
                     snapshot.frontendMap.routes.push({
                         id: routeId,
                         path: routePath,
                         parent_id: '',
-                        label: '',
-                        nav_surface: '',
+                        label: routeLabelFromGap(title, routePath),
+                        nav_surface: navSurface,
                         ui_status: 'GAP',
                         source_gap_ids: [id],
                         implemented_files: [],
@@ -83,17 +92,20 @@ export class FrontendGapService {
             gap.resolved_by_feature = options?.feature || '';
             gap.implemented_files = options?.files || [];
             gap.updated_at = now;
-            const routeTargets = new Set([...(gap.route_targets || []), ...(options?.routes || [])]);
+            const routeTargets = new Set([...gap.route_targets, ...(options?.routes || [])]);
+            const relatedRouteIds = new Set(gap.related_route_ids);
+            const navSurface = firstNonEmpty(gap.menu_targets);
             for (const routePath of routeTargets) {
                 const routeId = `route-${slugify(routePath) || 'root'}`;
+                relatedRouteIds.add(routeId);
                 const route = snapshot.frontendMap.routes.find((entry) => entry.id === routeId);
                 if (!route) {
                     snapshot.frontendMap.routes.push({
                         id: routeId,
                         path: routePath,
                         parent_id: '',
-                        label: '',
-                        nav_surface: '',
+                        label: routeLabelFromGap(gap.title, routePath),
+                        nav_surface: navSurface,
                         ui_status: 'OK',
                         source_gap_ids: [gap.id],
                         implemented_files: options?.files || [],
@@ -102,9 +114,12 @@ export class FrontendGapService {
                     continue;
                 }
                 route.ui_status = 'OK';
-                route.implemented_files = Array.from(new Set([...(route.implemented_files || []), ...(options?.files || [])]));
-                route.source_gap_ids = Array.from(new Set([...(route.source_gap_ids || []), gap.id]));
+                route.label = route.label || routeLabelFromGap(gap.title, routePath);
+                route.nav_surface = route.nav_surface || navSurface;
+                route.implemented_files = Array.from(new Set([...route.implemented_files, ...(options?.files || [])]));
+                route.source_gap_ids = Array.from(new Set([...route.source_gap_ids, gap.id]));
             }
+            gap.related_route_ids = Array.from(relatedRouteIds);
             await saveStateTransaction(paths, {
                 frontendGaps: snapshot.frontendGaps,
                 frontendMap: snapshot.frontendMap,

package/dist/core/sdd/services/governance-control-plane-runtime-adapters.d.ts

@@ -0,0 +1,17 @@
+export type GovernanceControlPlaneRuntimeMode = 'native' | 'contract';
+export type GovernanceControlPlaneRuntimeDependencyResolver = (packageName: string) => string;
+export interface GovernanceControlPlaneRuntimeAdapterStatus<TRuntime extends string = string> {
+    runtime: TRuntime;
+    package: string;
+    available: boolean;
+    mode: GovernanceControlPlaneRuntimeMode;
+    reason: string;
+}
+export interface GovernanceControlPlaneRuntimeAdapters {
+    ui_write_policy: 'cli-shell-out-only';
+    canonical_state: '.sdd/state/*.yaml';
+    frontend: GovernanceControlPlaneRuntimeAdapterStatus<'angular-spa'>;
+    realtime: GovernanceControlPlaneRuntimeAdapterStatus<'socket.io'>;
+}
+export declare function resolveGovernanceControlPlaneRuntimeAdapters(resolver?: GovernanceControlPlaneRuntimeDependencyResolver): GovernanceControlPlaneRuntimeAdapters;
+//# sourceMappingURL=governance-control-plane-runtime-adapters.d.ts.map

package/dist/core/sdd/services/governance-control-plane-runtime-adapters.js

@@ -0,0 +1,38 @@
+import { createRequire } from 'node:module';
+const FRONTEND_RUNTIME_PACKAGE = '@angular/core';
+const REALTIME_RUNTIME_PACKAGE = 'socket.io';
+export function resolveGovernanceControlPlaneRuntimeAdapters(resolver = defaultRuntimeDependencyResolver) {
+    return {
+        ui_write_policy: 'cli-shell-out-only',
+        canonical_state: '.sdd/state/*.yaml',
+        frontend: resolveAdapterStatus('angular-spa', FRONTEND_RUNTIME_PACKAGE, resolver),
+        realtime: resolveAdapterStatus('socket.io', REALTIME_RUNTIME_PACKAGE, resolver),
+    };
+}
+function resolveAdapterStatus(runtime, packageName, resolver) {
+    try {
+        resolver(packageName);
+        return {
+            runtime,
+            package: packageName,
+            available: true,
+            mode: 'native',
+            reason: `${packageName} resolved; native runtime adapter is available.`,
+        };
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : `Unable to resolve ${packageName}`;
+        return {
+            runtime,
+            package: packageName,
+            available: true,
+            mode: 'contract',
+            reason: `${packageName} unresolved; using internal contract adapter (${detail}).`,
+        };
+    }
+}
+function defaultRuntimeDependencyResolver(packageName) {
+    const runtimeRequire = createRequire(import.meta.url);
+    return runtimeRequire.resolve(packageName);
+}
+//# sourceMappingURL=governance-control-plane-runtime-adapters.js.map

package/dist/core/sdd/services/governance-control-plane.service.d.ts

@@ -0,0 +1,66 @@
+import { type SddStateSnapshot } from '../state.js';
+export type ControlPlaneMutationAction = 'frontend-impact' | 'finalize';
+export interface GovernanceControlPlaneManifest {
+    protocol: 'codesdd-governance-control-plane/v1';
+    architecture: {
+        frontend: 'angular-spa';
+        api: 'rest';
+        realtime: 'socket.io';
+        ui_write_policy: 'cli-shell-out-only';
+        canonical_state: '.sdd/state/*.yaml';
+    };
+    rest: {
+        read_endpoints: Array<{
+            method: 'GET';
+            path: string;
+            description: string;
+        }>;
+        write_intent_endpoint: {
+            method: 'POST';
+            path: '/api/intents/cli-shell-out';
+            behavior: 'intent-only-by-default';
+            allowed_actions: ControlPlaneMutationAction[];
+        };
+    };
+    realtime: {
+        transport: 'socket.io';
+        available: boolean;
+        channel: 'codesdd.state.changed';
+        reason: string;
+    };
+    blockers: string[];
+}
+export interface GovernanceProjection {
+    generated_at: string;
+    backlog: SddStateSnapshot['backlog'];
+    finalize_queue: SddStateSnapshot['finalizeQueue'];
+    frontend_decisions: SddStateSnapshot['frontendDecisions'];
+}
+export interface GovernanceMutationIntent {
+    action: ControlPlaneMutationAction;
+    command: {
+        bin: string;
+        args: string[];
+        cwd: string;
+    };
+    gate: {
+        executes_immediately: false;
+        required_flag: '--allow-mutation-execution';
+        ui_can_write_state_directly: false;
+    };
+}
+export declare class GovernanceControlPlaneService {
+    manifest(projectRoot: string): Promise<GovernanceControlPlaneManifest>;
+    readProjection(projectRoot: string): Promise<GovernanceProjection>;
+    readBacklogFeature(projectRoot: string, featureId: string): Promise<Record<string, unknown>>;
+    planMutationIntent(projectRoot: string, action: ControlPlaneMutationAction, params: Record<string, string>): GovernanceMutationIntent;
+    executeMutationIntent(intent: GovernanceMutationIntent, options?: {
+        allowMutationExecution?: boolean;
+    }): Promise<{
+        executed: boolean;
+        stdout: string;
+        stderr: string;
+    }>;
+    private buildActionArgs;
+}
+//# sourceMappingURL=governance-control-plane.service.d.ts.map