@devtrack-solution/codesdd 1.2.2

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

@@ -0,0 +1,707 @@
+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 { 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 { 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 { SddWriteTransaction } from "../write-manifest.js";
+import { withStateLock } from "../state-lock.js";
+import { activeWorkspaceDeclaresMandatoryAdrImpact } from "../adr-policy.js";
+import { parseWorkspaceYamlDocument, } from "../workspace-schemas.js";
+export class FinalizeService {
+    stores;
+    constructor(stores) {
+        this.stores = stores;
+    }
+    async execute(projectRoot, options) {
+        const { config, paths } = await getRuntime(projectRoot);
+        return withStateLock(paths.stateDir, async () => {
+            const snapshot = await loadStateSnapshot(paths, config);
+            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
+                ? undefined
+                : await inferFinalizeTarget(paths, pending, options?.ref, options?.cwd || process.cwd());
+            const targets = options?.allReady
+                ? pending.map((item) => item.feature_id)
+                : inferredRef
+                    ? [inferredRef]
+                    : pending.slice(0, 1).map((item) => item.feature_id);
+            if (targets.length === 0) {
+                await saveStateTransaction(paths, {
+                    finalizeQueue: snapshot.finalizeQueue,
+                    backlog: snapshot.backlog,
+                    unblockEvents: snapshot.unblockEvents,
+                    transitionLog: snapshot.transitionLog,
+                });
+                await persistAndRender(paths, config, options?.render);
+                return {
+                    finalized: [],
+                    unblocked: [],
+                    pending: pending.length,
+                    updated_core_docs: [],
+                    updated_readme: false,
+                    updated_agent_guide: false,
+                    doc_warnings: [],
+                    auto_frontend_gaps: [],
+                    frontend_guardrails: [],
+                };
+            }
+            const finalized = [];
+            const unblocked = new Set();
+            const updatedCoreDocs = new Set();
+            const docWarnings = [];
+            const autoFrontendGaps = [];
+            const frontendGuardrails = [];
+            const now = nowIso();
+            const existingEvents = new Set(snapshot.unblockEvents.events.map((event) => `${event.feature_id}:${event.unblocked_by}`));
+            for (const featureId of targets) {
+                const feature = snapshot.backlog.items.find((item) => item.id === featureId);
+                if (!feature)
+                    continue;
+                const plannedDirPath = path.join(paths.plannedDir, feature.id);
+                const activeDirPath = path.join(paths.activeDir, feature.id);
+                const archivedDirPath = path.join(paths.archivedDir, feature.id);
+                const plannedWorkspaceExists = await pathExists(plannedDirPath);
+                const activeWorkspaceExists = await pathExists(activeDirPath);
+                const archivedWorkspaceExists = await pathExists(archivedDirPath);
+                if (archivedWorkspaceExists) {
+                    throw new Error(`${feature.id} ja foi finalizada`);
+                }
+                if (plannedWorkspaceExists && !activeWorkspaceExists) {
+                    throw new Error(`${feature.id} nao foi iniciada, use sdd start primeiro`);
+                }
+                if (!activeWorkspaceExists) {
+                    throw new Error(`Workspace ativo de ${feature.id} nao encontrado para finalize.`);
+                }
+                const archiveCanonicalization = await validatePreFinalizeArchiveCanonicalization(paths, feature.id);
+                if (!archiveCanonicalization.ok) {
+                    throw new Error(`${feature.id} post-active lifecycle validation failed: ${archiveCanonicalization.reasons.join(' | ')}`);
+                }
+                const finalizeGuardrails = evaluateFeatureFinalizeGuardrails(feature, snapshot.backlog.items, !!options?.forceTransition);
+                if (!finalizeGuardrails.dependency_check.ok) {
+                    docWarnings.push(`${feature.id} finalize dependency guardrail blocked: ${finalizeGuardrails.reasons.join(' | ')}`);
+                    if (!options?.forceTransition) {
+                        continue;
+                    }
+                    docWarnings.push(`${feature.id} finalized with --force-transition despite unresolved blocked_by dependencies.`);
+                }
+                await runLifecycleHooks('before-finalize', {
+                    projectRoot,
+                    featureId: feature.id,
+                    entityId: feature.id,
+                    options: options,
+                    metadata: {
+                        finalize_guardrails: finalizeGuardrails,
+                        current_status: feature.status,
+                    },
+                });
+                if (feature.flow_mode === 'rigoroso' &&
+                    (!gateSatisfied(feature.gates.proposta.status) ||
+                        !gateSatisfied(feature.gates.planejamento.status) ||
+                        !gateSatisfied(feature.gates.tarefas.status))) {
+                    docWarnings.push(`${feature.id} em modo rigoroso sem gates aprovados (proposta=${feature.gates.proposta.status}, planejamento=${feature.gates.planejamento.status}, tarefas=${feature.gates.tarefas.status})`);
+                    continue;
+                }
+                if (config.frontend.enabled) {
+                    const changed = await gitChangedFiles(projectRoot, feature.start_commit_sha || '');
+                    const evidence = detectFrontendImpactEvidence(feature, changed.files);
+                    const declaredStatus = feature.frontend_impact_status || 'unknown';
+                    const reasons = [];
+                    let autoGapId = '';
+                    if (declaredStatus === 'unknown') {
+                        reasons.push('frontend_impact_status=unknown');
+                    }
+                    if (declaredStatus === 'none') {
+                        const reason = (feature.frontend_impact_reason || '').trim();
+                        if (reason.length < 20) {
+                            reasons.push('frontend_impact_status=none sem justificativa minima (20 chars)');
+                        }
+                        if (evidence.has_frontend_evidence) {
+                            reasons.push('frontend_impact_status=none contradiz evidencias (metadata/diff)');
+                        }
+                    }
+                    if (declaredStatus === 'required' && feature.frontend_gap_refs.length === 0) {
+                        autoGapId = await maybeCreateAutomaticFrontendGap(paths, snapshot, feature, {
+                            force: true,
+                            routeTargets: evidence.metadata_routes,
+                            detectionSources: evidence.evidence_sources.length > 0
+                                ? [...evidence.evidence_sources]
+                                : ['metadata'],
+                        });
+                        if (autoGapId) {
+                            autoFrontendGaps.push(autoGapId);
+                            docWarnings.push(`${feature.id} gerou ${autoGapId} automaticamente (cobertura frontend pendente).`);
+                        }
+                        reasons.push(`frontend_impact_status=required exige FGAP vinculado antes do finalize (${autoGapId || 'nao criado'})`);
+                    }
+                    if (changed.warning) {
+                        docWarnings.push(`${feature.id}: deteccao diff com baixa confianca (${changed.warning}).`);
+                    }
+                    const blockedByGuardrail = reasons.length > 0;
+                    const forcedByGuardrail = blockedByGuardrail && !!options?.forceFrontend;
+                    frontendGuardrails.push({
+                        feature_id: feature.id,
+                        declared_status: declaredStatus,
+                        evidence_sources: evidence.evidence_sources,
+                        auto_gap_created: autoGapId,
+                        blocked: blockedByGuardrail,
+                        forced: forcedByGuardrail,
+                        reasons,
+                    });
+                    if (blockedByGuardrail && !options?.forceFrontend) {
+                        docWarnings.push(`${feature.id} bloqueada pelos guardrails de frontend: ${reasons.join(' | ')}`);
+                        continue;
+                    }
+                    if (forcedByGuardrail) {
+                        docWarnings.push(`${feature.id} finalizada com --force-frontend apesar de guardrails: ${reasons.join(' | ')}`);
+                    }
+                }
+                const qualityGuardrail = await evaluateFeatureQuality(paths, config, feature);
+                if (!qualityGuardrail.ok) {
+                    docWarnings.push(`${feature.id} quality contract warnings: ${qualityGuardrail.reasons.join(' | ')}`);
+                    if (qualityGuardrail.blocking && !options?.forceTransition) {
+                        continue;
+                    }
+                    if (qualityGuardrail.blocking && options?.forceTransition) {
+                        docWarnings.push(`${feature.id} finalized with --force-transition despite quality contract warnings.`);
+                    }
+                }
+                const qualityFeedbackGuardrail = await evaluateWorkspaceQualityFeedback(paths, config, feature);
+                if (!qualityFeedbackGuardrail.ok) {
+                    docWarnings.push(`${feature.id} quality feedback loop blocked finalize: ${qualityFeedbackGuardrail.reasons.join(' | ')}`);
+                    if (!options?.forceTransition) {
+                        continue;
+                    }
+                    docWarnings.push(`${feature.id} finalized with --force-transition despite quality feedback loop warnings.`);
+                }
+                const traceabilityGuardrail = await evaluateWorkspaceTraceabilityFeedback(paths, config, feature);
+                if (!traceabilityGuardrail.ok) {
+                    docWarnings.push(`${feature.id} traceability guardrail blocked finalize: ${traceabilityGuardrail.reasons.join(' | ')}`);
+                    if (!options?.forceTransition) {
+                        continue;
+                    }
+                    docWarnings.push(`${feature.id} finalized with --force-transition despite traceability guardrail warnings.`);
+                }
+                const privacyFinalizeGuardrail = await evaluatePrivacyFinalizeGuardrail(paths, config, feature);
+                if (!privacyFinalizeGuardrail.ok) {
+                    docWarnings.push(`${feature.id} privacy compliance guardrail blocked finalize: ${privacyFinalizeGuardrail.reasons.join(' | ')}`);
+                    if (!options?.forceTransition) {
+                        continue;
+                    }
+                    docWarnings.push(`${feature.id} finalized with --force-transition despite privacy compliance guardrail warnings.`);
+                }
+                if (!feature.requires_adr && (await activeWorkspaceDeclaresMandatoryAdrImpact(paths, feature))) {
+                    feature.requires_adr = true;
+                }
+                if (feature.requires_adr) {
+                    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.`);
+                    }
+                    else {
+                        const adrViolations = validateDocumentAgainstLens(adrContent, LENSES.adr);
+                        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.`);
+                        }
+                    }
+                }
+                // Validate active workspace docs with the canonical YAML/Zod contract.
+                const activePath = path.join(paths.activeDir, feature.id);
+                const docNames = activeDocNamesForLayout(config);
+                const specPath = path.join(activePath, docNames.spec);
+                const planPath = path.join(activePath, docNames.plan);
+                let lensViolations = [];
+                const specContent = await fs.readFile(specPath, 'utf8').catch(() => '');
+                if (specContent) {
+                    try {
+                        parseWorkspaceYamlDocument('1-spec.yaml', specContent);
+                    }
+                    catch (error) {
+                        lensViolations.push(`Spec: ${error.message}`);
+                    }
+                }
+                else {
+                    lensViolations.push(`Arquivo de especificação YAML não encontrado ou vazio: ${docNames.spec}.`);
+                }
+                const planContent = await fs.readFile(planPath, 'utf8').catch(() => '');
+                if (planContent) {
+                    try {
+                        parseWorkspaceYamlDocument('2-plan.yaml', planContent);
+                    }
+                    catch (error) {
+                        lensViolations.push(`Plan: ${error.message}`);
+                    }
+                }
+                else {
+                    lensViolations.push(`Arquivo de plano YAML não encontrado ou vazio: ${docNames.plan}.`);
+                }
+                try {
+                    applyLoggedTransition(snapshot.transitionLog.events, 'FEAT', feature, 'DONE', {
+                        sourceCommand: 'sdd finalize',
+                        forceTransition: options?.forceTransition,
+                        lensViolations,
+                        reason: `Finalize consolidado para ${feature.id}`,
+                        timestamp: now,
+                        afterTransition: (currentFeature) => {
+                            currentFeature.current_stage = 'consolidacao';
+                            currentFeature.done_at = now;
+                            currentFeature.last_sync_at = now;
+                        },
+                    });
+                }
+                catch (err) {
+                    docWarnings.push(`${feature.id} ${err.message}`);
+                    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,
+                    });
+                }
+                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')) {
+                        const radar = snapshot.discoveryIndex.records.find((r) => r.id === feature.origin_ref);
+                        if (radar && (radar.type === 'RAD' || radar.type === 'EPIC')) {
+                            const targetStatus = RADAR_TO_DISCOVERY_STATUS.DONE;
+                            if (radar.status !== targetStatus) {
+                                applyLoggedTransition(snapshot.transitionLog.events, radar.type, radar, targetStatus, {
+                                    sourceCommand: 'sdd finalize',
+                                    reason: `Todas as features derivadas de ${radar.id} foram concluídas`,
+                                    timestamp: now,
+                                    afterTransition: (currentRadar) => {
+                                        currentRadar.updated_at = now;
+                                    },
+                                });
+                            }
+                        }
+                    }
+                }
+                // Consolida memória macro canônica com dados objetivos da feature finalizada.
+                upsertByKey(snapshot.architecture.nodes, {
+                    id: feature.id,
+                    name: feature.title,
+                    kind: feature.execution_kind,
+                    description: feature.summary || '',
+                    repo_paths: feature.worktree_path ? [feature.worktree_path] : [],
+                    depends_on: feature.blocked_by,
+                }, (node) => node.id, mergeArchitectureNode);
+                updatedCoreDocs.add(coreDocRef(paths, 'arquitetura.md'));
+                const serviceId = feature.touches[0] || feature.execution_kind;
+                upsertByKey(snapshot.serviceCatalog.services, {
+                    id: serviceId,
+                    name: serviceId,
+                    responsibility: feature.summary || '',
+                    owner_refs: [feature.id],
+                    repo_paths: feature.worktree_path ? [feature.worktree_path] : [],
+                    contracts: feature.consumes,
+                    external_dependencies: [],
+                }, (service) => service.id, mergeServiceRecord);
+                updatedCoreDocs.add(coreDocRef(paths, 'servicos.md'));
+                for (const tech of feature.touches) {
+                    upsertByKey(snapshot.techStack.items, {
+                        layer: tech,
+                        technology: tech,
+                        version: '',
+                        purpose: `Area impactada por ${feature.id}`,
+                        constraints: feature.lock_domains,
+                    }, (entry) => `${entry.layer}::${entry.technology}`, mergeTechStackRecord);
+                }
+                updatedCoreDocs.add(coreDocRef(paths, 'spec-tecnologica.md'));
+                const contractTokens = Array.from(new Set([...feature.consumes, ...feature.produces]));
+                snapshot.integrationContracts.contracts = stableUniqueStrings([
+                    ...snapshot.integrationContracts.contracts,
+                    ...contractTokens.map((token) => `${token}::${feature.id}`),
+                ]);
+                upsertByKey(snapshot.repoMap.items, {
+                    path: `.sdd/archived/${feature.id}`,
+                    kind: 'sdd-feature-archive',
+                    service_ref: serviceId,
+                    notes: feature.summary || `Finalize ${feature.id}`,
+                }, (item) => item.path, mergeRepoMapRecord);
+                updatedCoreDocs.add(coreDocRef(paths, 'repo-map.md'));
+                if (config.frontend.enabled && snapshot.frontendDecisions && feature.execution_kind === 'frontend_coverage') {
+                    upsertByKey(snapshot.frontendDecisions.items, {
+                        id: `FD-${feature.id}`,
+                        title: `Decisao de frontend para ${feature.id}`,
+                        status: 'APPROVED',
+                        decision: `Cobrir frontend da feature ${feature.id}`,
+                        rationale: feature.summary || '',
+                        related_refs: [feature.id, feature.origin_ref || ''].filter(Boolean),
+                        route_refs: [],
+                        adr_refs: [`ADR-${feature.id}`],
+                    }, (entry) => entry.id, mergeFrontendDecisionRecord);
+                    updatedCoreDocs.add(coreDocRef(paths, 'frontend-decisions.md'));
+                }
+                const unlockedByFeature = [];
+                for (const dependant of snapshot.backlog.items) {
+                    if (dependant.id === feature.id)
+                        continue;
+                    if (!dependant.blocked_by.includes(feature.id))
+                        continue;
+                    if (dependant.status === 'DONE' || dependant.status === 'ARCHIVED')
+                        continue;
+                    const unresolved = unresolvedDependencies(dependant, snapshot.backlog.items);
+                    if (unresolved.length > 0)
+                        continue;
+                    if (dependant.status === 'BLOCKED') {
+                        dependant.status = 'READY';
+                    }
+                    dependant.unblocked_at = now;
+                    dependant.last_sync_at = now;
+                    unblocked.add(dependant.id);
+                    unlockedByFeature.push(dependant.id);
+                    const eventKey = `${dependant.id}:${feature.id}`;
+                    if (!existingEvents.has(eventKey)) {
+                        snapshot.unblockEvents.events.push({
+                            feature_id: dependant.id,
+                            unblocked_by: feature.id,
+                            created_at: now,
+                            status: 'NEW',
+                        });
+                        existingEvents.add(eventKey);
+                    }
+                }
+                if (!options?.noAdr && !feature.requires_adr) {
+                    const adrPath = path.join(paths.coreDir, 'adrs', `ADR-${feature.id}.md`);
+                    const tx = new SddWriteTransaction();
+                    tx.writeFile(adrPath, buildAdrMarkdown(feature, unlockedByFeature, now));
+                    await tx.commit(paths.projectRoot, paths.memoryRoot, 'finalize.service (ADR)');
+                }
+                await fs.mkdir(paths.archivedDir, { recursive: true });
+                await fs.rename(activeDirPath, archivedDirPath);
+                const postActiveValidation = await validatePostActiveFeaturePlacement(paths, feature.id);
+                if (!postActiveValidation.ok) {
+                    if (!(await pathExists(activeDirPath)) && (await pathExists(archivedDirPath))) {
+                        await fs.rename(archivedDirPath, activeDirPath).catch(() => undefined);
+                    }
+                    throw new Error(`${feature.id} post-active lifecycle validation failed: ${postActiveValidation.reasons.join(' | ')}`);
+                }
+                finalized.push(featureId);
+                await runLifecycleHooks('after-finalize', {
+                    projectRoot,
+                    featureId: feature.id,
+                    entityId: feature.id,
+                    options: options,
+                    metadata: {
+                        finalized: true,
+                        unblocked: Array.from(unblocked).sort(),
+                    },
+                });
+            }
+            updateDependencyMetadata(snapshot.backlog.items);
+            const stateUpdates = {
+                discoveryIndex: snapshot.discoveryIndex,
+                backlog: snapshot.backlog,
+                finalizeQueue: snapshot.finalizeQueue,
+                unblockEvents: snapshot.unblockEvents,
+                transitionLog: snapshot.transitionLog,
+                architecture: snapshot.architecture,
+                serviceCatalog: snapshot.serviceCatalog,
+                techStack: snapshot.techStack,
+                integrationContracts: snapshot.integrationContracts,
+                repoMap: snapshot.repoMap,
+            };
+            if (config.frontend.enabled && snapshot.frontendDecisions) {
+                await saveStateTransaction(paths, {
+                    ...stateUpdates,
+                    frontendDecisions: snapshot.frontendDecisions,
+                    frontendGaps: snapshot.frontendGaps,
+                    frontendMap: snapshot.frontendMap,
+                });
+            }
+            else {
+                if (config.frontend.enabled) {
+                    docWarnings.push('frontend.enabled=true sem frontend-decisions carregado');
+                }
+                await saveStateTransaction(paths, stateUpdates);
+            }
+            await persistAndRender(paths, config, options?.render);
+            const syncResult = await syncSddGuideDocs(projectRoot, paths, config);
+            const remaining = snapshot.finalizeQueue.items.filter((item) => item.status === 'PENDING').length;
+            return {
+                finalized,
+                unblocked: Array.from(unblocked).sort(),
+                pending: remaining,
+                updated_core_docs: Array.from(updatedCoreDocs).sort(),
+                updated_readme: syncResult.updatedReadme,
+                updated_agent_guide: syncResult.updatedAgentGuide || syncResult.updatedRootAgents,
+                doc_warnings: docWarnings,
+                auto_frontend_gaps: autoFrontendGaps,
+                frontend_guardrails: frontendGuardrails,
+            };
+        });
+    }
+}
+async function inferFinalizeTarget(paths, pending, explicitRef, cwd) {
+    if (explicitRef)
+        return explicitRef;
+    const activeEntries = await fs.readdir(paths.activeDir, { withFileTypes: true }).catch(() => []);
+    const activeFeatures = activeEntries
+        .filter((entry) => entry.isDirectory() && /^FEAT-\d{4}$/.test(entry.name))
+        .map((entry) => entry.name);
+    if (cwd) {
+        const normalizedCwd = path.resolve(cwd);
+        const cwdMatch = activeFeatures.find((featureId) => {
+            const featureRoot = path.join(paths.activeDir, featureId);
+            return normalizedCwd === featureRoot || normalizedCwd.startsWith(`${featureRoot}${path.sep}`);
+        });
+        if (cwdMatch) {
+            return cwdMatch;
+        }
+    }
+    if (pending.length === 1) {
+        return pending[0].feature_id;
+    }
+    if (activeFeatures.length === 1) {
+        return activeFeatures[0];
+    }
+    return undefined;
+}
+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) {
+    if (!isPrivacyComplianceFeature(feature)) {
+        return { ok: true, reasons: [] };
+    }
+    const activePath = path.join(paths.activeDir, feature.id);
+    const names = activeDocNamesForLayout(config);
+    const specPath = path.join(activePath, names.spec);
+    const planPath = path.join(activePath, names.plan);
+    const qualityPath = path.join(activePath, names.quality);
+    const reasons = [];
+    const [specContent, planContent, qualityContent] = await Promise.all([
+        fs.readFile(specPath, 'utf-8').catch(() => ''),
+        fs.readFile(planPath, 'utf-8').catch(() => ''),
+        fs.readFile(qualityPath, 'utf-8').catch(() => ''),
+    ]);
+    if (!specContent.trim())
+        reasons.push(`missing spec YAML: ${relProjectPath(paths, specPath)}`);
+    if (!planContent.trim())
+        reasons.push(`missing plan YAML: ${relProjectPath(paths, planPath)}`);
+    if (!qualityContent.trim())
+        reasons.push(`missing quality YAML: ${relProjectPath(paths, qualityPath)}`);
+    if (reasons.length > 0)
+        return { ok: false, reasons };
+    let spec;
+    let plan;
+    let quality;
+    try {
+        spec = parseWorkspaceYamlDocument('1-spec.yaml', specContent);
+        plan = parseWorkspaceYamlDocument('2-plan.yaml', planContent);
+        quality = parseWorkspaceYamlDocument('5-quality.yaml', qualityContent);
+    }
+    catch (error) {
+        return { ok: false, reasons: [`privacy guardrail parse failure: ${error.message}`] };
+    }
+    const complianceContext = spec.compliance_context;
+    const privacyControls = plan.privacy_controls;
+    const securityIntegrity = quality.security_integrity;
+    if (!complianceContext || complianceContext.source_refs.length === 0) {
+        reasons.push('spec.compliance_context.source_refs must include at least one canonical source reference');
+    }
+    if (!complianceContext || complianceContext.jurisdictions.length === 0) {
+        reasons.push('spec.compliance_context.jurisdictions must list at least one jurisdiction profile');
+    }
+    if (!privacyControls || privacyControls.source_registry_refs.length === 0) {
+        reasons.push('plan.privacy_controls.source_registry_refs must include at least one source registry link');
+    }
+    if (!privacyControls || privacyControls.jurisdiction_profiles.length === 0) {
+        reasons.push('plan.privacy_controls.jurisdiction_profiles must include at least one profile');
+    }
+    if (!privacyControls || privacyControls.control_ids.length === 0) {
+        reasons.push('plan.privacy_controls.control_ids must include at least one control');
+    }
+    const skillConformance = plan.skill_conformance;
+    if (!skillConformance || skillConformance.selected_skills.length === 0) {
+        reasons.push('plan.skill_conformance.selected_skills must list at least one selected skill');
+    }
+    if (feature.execution_kind !== 'documentation' &&
+        (!skillConformance || !(skillConformance.architecture_tree_ascii || '').trim())) {
+        reasons.push('plan.skill_conformance.architecture_tree_ascii is required for code-impacting features');
+    }
+    if (skillConformance &&
+        skillConformance.detected_conflicts.length > 0 &&
+        !(skillConformance.resolution_adr_ref || '').trim()) {
+        reasons.push('plan.skill_conformance.detected_conflicts requires resolution_adr_ref');
+    }
+    if (!securityIntegrity) {
+        reasons.push('quality.security_integrity block is required for privacy-compliance finalize');
+        return { ok: false, reasons };
+    }
+    const reviewStates = [
+        ['endpoint_auth_review', securityIntegrity.endpoint_auth_review],
+        ['sensitive_data_exposure_review', securityIntegrity.sensitive_data_exposure_review],
+        ['incident_response_review', securityIntegrity.incident_response_review],
+    ];
+    for (const [name, value] of reviewStates) {
+        if (value === 'pending') {
+            reasons.push(`quality.security_integrity.${name} cannot stay pending at finalize`);
+        }
+        if (value === 'failed') {
+            reasons.push(`quality.security_integrity.${name} is failed and requires remediation or formal exception`);
+        }
+    }
+    if (privacyControls?.legal_review_gate === 'required' && !complianceContext?.legal_review_required) {
+        reasons.push('plan.privacy_controls.legal_review_gate=required requires spec.compliance_context.legal_review_required=true');
+    }
+    return { ok: reasons.length === 0, reasons };
+}
+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))) || '';
+    if (!artifactName) {
+        return { ok: true, reasons: [], artifact: '' };
+    }
+    const artifactPath = path.join(activePath, artifactName);
+    const artifact = relProjectPath(paths, artifactPath);
+    const content = await fs.readFile(artifactPath, 'utf-8').catch(() => '');
+    if (!content.trim()) {
+        return { ok: false, reasons: [`quality artifact empty: ${artifact}`], artifact };
+    }
+    let document;
+    try {
+        document = parseWorkspaceYamlDocument('5-quality.yaml', content);
+    }
+    catch (err) {
+        return { ok: false, reasons: [`quality artifact YAML invalid: ${err.message}`], artifact };
+    }
+    const missingTargets = missingCoverageTargets(document);
+    const missingSkills = missingSkillEvidence(document);
+    const reasons = [];
+    const maxRounds = document.remediation_policy.max_rounds;
+    const rounds = countQualityEvidenceRounds(document);
+    if (rounds > maxRounds && document.exceptions.length === 0) {
+        reasons.push(`quality remediation max_rounds exceeded (${rounds}/${maxRounds}); formal exception required in ${artifact}`);
+    }
+    if (missingTargets.length > 0) {
+        const targetSummary = missingTargets
+            .map((target) => `${target.kind} >= ${target.target}`)
+            .join(', ');
+        if (document.remediation_policy.on_coverage_miss === 're_task') {
+            reasons.push(`coverage targets not met for ${targetSummary}; create a new task round before finalize`);
+        }
+        else if (document.remediation_policy.on_coverage_miss === 'block') {
+            reasons.push(`coverage targets not met for ${targetSummary}`);
+        }
+        else if (document.exceptions.length === 0) {
+            reasons.push(`coverage targets not met for ${targetSummary}; remediation_policy=exception requires exceptions[]`);
+        }
+    }
+    if (missingSkills.length > 0) {
+        reasons.push(`required skill evidence missing for ${missingSkills.join(', ')}`);
+    }
+    return { ok: reasons.length === 0, reasons, artifact };
+}
+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);
+    const changelogPath = path.join(activePath, names.changelog);
+    const qualityPath = path.join(activePath, names.quality);
+    const artifact = relProjectPath(paths, qualityPath);
+    const [specContent, changelogContent, qualityContent] = await Promise.all([
+        fs.readFile(specPath, 'utf-8').catch(() => ''),
+        fs.readFile(changelogPath, 'utf-8').catch(() => ''),
+        fs.readFile(qualityPath, 'utf-8').catch(() => ''),
+    ]);
+    if (!specContent.trim() || !changelogContent.trim() || !qualityContent.trim()) {
+        return {
+            ok: false,
+            artifact,
+            reasons: [
+                `traceability requires 1-spec.yaml, 4-changelog.yaml, and 5-quality.yaml in ${relProjectPath(paths, activePath)}`,
+            ],
+        };
+    }
+    let spec;
+    let changelog;
+    let quality;
+    try {
+        spec = parseWorkspaceYamlDocument('1-spec.yaml', specContent);
+        changelog = parseWorkspaceYamlDocument('4-changelog.yaml', changelogContent);
+        quality = parseWorkspaceYamlDocument('5-quality.yaml', qualityContent);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            artifact,
+            reasons: [`traceability workspace YAML invalid: ${error.message}`],
+        };
+    }
+    const result = evaluateWorkspaceTraceability(paths.projectRoot, spec, changelog, quality);
+    return {
+        ok: result.ok,
+        reasons: result.reasons,
+        artifact,
+    };
+}
+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) {
+    return document.evidence_log.some((entry) => {
+        const evidenceKind = entry.kind.toLowerCase();
+        const result = entry.result.toLowerCase();
+        const relevant = evidenceKind.includes(kind) ||
+            evidenceKind.includes('coverage') ||
+            (kind === 'integration' && evidenceKind.includes('e2e'));
+        if (!relevant) {
+            return false;
+        }
+        const percentages = result.match(/\d+(?:\.\d+)?/g)?.map(Number) ?? [];
+        return percentages.some((value) => value >= target);
+    });
+}
+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) {
+    const required = Array.from(new Set((document.skill_evidence?.required_skill_ids ?? []).map((value) => value.trim()).filter(Boolean)));
+    if (required.length === 0) {
+        return [];
+    }
+    const provided = new Set((document.skill_evidence?.evidence ?? [])
+        .map((entry) => entry.skill_id.trim().toLowerCase())
+        .filter(Boolean));
+    return required.filter((skillId) => !provided.has(skillId.toLowerCase()));
+}
+//# sourceMappingURL=finalize.service.js.map