@devtrack-solution/codesdd 1.2.2

package/dist/core/sdd/legacy-operations.js

@@ -0,0 +1,2175 @@
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { SddWriteTransaction } from './write-manifest.js';
+import { existsSync, promises as fs } from 'node:fs';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import * as yaml from 'yaml';
+import { CLI_NAME } from '../branding.js';
+import { LENSES, validateDocumentAgainstLens } from './lenses.js';
+import { TransitionEngine } from './domain/transition-engine.js';
+import { resolveOpenSpecSubpath } from './services/legacy-capability.service.js';
+import { allocateEntityId, loadProjectSddConfig, loadStateSnapshot, nowIso, resolveSddPaths, } from './state.js';
+import { BUILT_IN_SDD_SKILLS } from './default-skills.js';
+import { renderViews } from './views.js';
+import { normalizeSemanticText } from './dedup.js';
+import { stringifyWorkspaceYamlDocument } from './workspace-schemas.js';
+export const execFileAsync = promisify(execFile);
+export const RADAR_TO_DISCOVERY_STATUS = {
+    READY: 'READY',
+    PLANNED: 'PLANNED',
+    SPLIT: 'SPLIT',
+    IN_PROGRESS: 'IN_PROGRESS',
+    DONE: 'DONE',
+    CANCELLED: 'CANCELLED',
+};
+export function slugify(value) {
+    return value
+        .toLowerCase()
+        .normalize('NFD')
+        .replace(/[\u0300-\u036f]/g, '')
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .replace(/-{2,}/g, '-');
+}
+export function stripFunctionalTitlePrefixes(value) {
+    return value
+        .replace(/^\s*debate:\s*/i, '')
+        .replace(/^\s*insight:\s*/i, '')
+        .trim();
+}
+export function computeCanonicalTitle(value) {
+    const normalized = stripFunctionalTitlePrefixes(value)
+        .replace(/\s+/g, ' ')
+        .trim();
+    const fallback = normalized || 'Untitled canonical item';
+    return fallback.slice(0, 60).trim();
+}
+export function ensureMemoryInitialized(paths) {
+    return fs.access(paths.memoryRoot).catch(() => {
+        throw new Error(`Directory ${paths.memoryRoot} not found. Run "${CLI_NAME} sdd init".`);
+    });
+}
+export function findDiscoveryRecord(records, id) {
+    return records.find((record) => record.id === id);
+}
+export function markdownDebateTemplate(insight, debateId) {
+    const now = nowIso();
+    return `# Debate ${debateId}
+
+## 1) Decision Question (Required)
+Decide ____ instead of ____ to solve ____.
+
+## 2) Decision Criteria (Required)
+- User impact
+- Implementation complexity
+- Technical risk
+- Operational cost
+- Delivery time
+
+## 3) Options Considered (Minimum 2)
+### Option A
+- Proposal:
+- Pros:
+- Cons:
+
+### Option B
+- Proposal:
+- Pros:
+- Cons:
+
+### Option C (Optional)
+- Proposal:
+- Pros:
+- Cons:
+
+## 4) Evidence-Based Argument Round
+### Agent A (Defends A)
+- Argument:
+- Evidence:
+
+### Agent B (Defends B)
+- Argument:
+- Evidence:
+
+## 5) Cross-Critique Round
+### A Critiques B
+- Concrete risks:
+
+### B Critiques A
+- Concrete risks:
+
+## 6) Scoring Matrix (0-5)
+| Criterion | Weight | A | B | C |
+| --- | --- | --- | --- | --- |
+| User impact | 3 |  |  |  |
+| Implementation complexity | 2 |  |  |  |
+| Technical risk | 3 |  |  |  |
+| Operational cost | 2 |  |  |  |
+| Delivery time | 2 |  |  |  |
+
+## 7) Mediator Decision (Required)
+- Choice (A/B/C):
+- Rationale:
+- Accepted risks:
+- Reversal conditions:
+
+## 8) Quality Contract (Required)
+- Touched scope target: 95% unit coverage and 95% integration/e2e coverage when applicable.
+- Required evidence:
+  - Unit coverage:
+  - Integration/e2e or equivalent:
+  - Acceptance and risk matrix:
+- Exceptions:
+  - None, or formal exception with scope, reason, accepted risk, compensating control, review deadline, and approver.
+
+## 9) Output
+- APPROVED -> EPIC-####
+- DISCARDED -> Record in discarded
+
+## Metadata
+- Source insight: ${insight.id}
+- Insight title: ${insight.title}
+- Created at: ${insight.created_at || now}
+- Debate opened at: ${now}
+`;
+}
+export function markdownInsightTemplate(id, title, text) {
+    return `# Insight ${id}
+
+## Title
+${title}
+
+## Description
+${text}
+`;
+}
+export function markdownRadarTemplate(debate, radarId, rationale) {
+    return `# Epic ${radarId}
+
+## Origin
+- Debate: ${debate.id}
+- Base title: ${debate.title}
+
+## Approved Summary
+${rationale || 'Approved summary pending explicit expansion from the source debate.'}
+
+## Quality Contract
+- Default scope: touched_scope.
+- Unit target: 95%.
+- Integration/e2e target: 95% when applicable.
+- Evidence mode: hybrid coverage plus equivalence matrix.
+- Exceptions require scope, reason, accepted risk, compensating control, review deadline, and approver.
+
+## Status
+READY
+`;
+}
+export function markdownRadarFromDepositoTemplate(radarId, title, sourceCount, rationale) {
+    return `# Epic ${radarId}
+
+## Origin
+- Origin: source intake
+- Indexed sources: ${sourceCount}
+
+## Approved Summary
+${rationale || 'Initial planning generated from source inputs.'}
+
+## Quality Contract
+- Default scope: touched_scope.
+- Unit target: 95%.
+- Integration/e2e target: 95% when applicable.
+- Evidence mode: hybrid coverage plus equivalence matrix.
+- Exceptions require scope, reason, accepted risk, compensating control, review deadline, and approver.
+
+## Title
+${title}
+
+## Status
+READY
+`;
+}
+export function markdownDiscardTemplate(debate, rationale) {
+    return `# Discarded ${debate.id}
+
+## Origin
+- Debate: ${debate.id}
+- Title: ${debate.title}
+
+## Discard Reason
+${rationale || '(reason not provided)'}
+`;
+}
+export const DEFAULT_META_EVOLUTION_CONFIG = {
+    enabled: true,
+    audit_interval_days: 180,
+    placeholder_markers: ['(fill in', '(placeholder', 'TODO:', 'TBD:'],
+    health_alert_threshold: 75,
+};
+export function buildDefaultQualityContract(options) {
+    return {
+        version: 1,
+        enabled: true,
+        inherited_from: options?.inheritedFrom || '',
+        scope: options?.scope || 'touched_scope',
+        unit_target_percent: 95,
+        integration_target_percent: 95,
+        evidence_mode: options?.evidenceMode || 'hybrid',
+        enforcement: options?.enforcement || 'blocking',
+        stack_profile: options?.stackProfile || 'default',
+        required_axes: [
+            'requirements',
+            'critical_flows',
+            'contracts',
+            'acceptance_criteria',
+            'risks',
+        ],
+        required_evidence: [
+            {
+                kind: 'unit_coverage',
+                required: true,
+                status: 'planned',
+                command: 'project-specific unit coverage command',
+                artifact: 'coverage report for touched scope',
+                notes: 'Default target is 95% unless a formal exception is recorded.',
+            },
+            {
+                kind: 'integration_or_e2e',
+                required: true,
+                status: 'planned',
+                command: 'project-specific integration/e2e command or equivalent matrix',
+                artifact: 'integration/e2e result or equivalence matrix',
+                notes: 'Required for applicable critical flows in the touched scope.',
+            },
+            {
+                kind: 'acceptance_risk_matrix',
+                required: true,
+                status: 'planned',
+                command: 'manual review recorded in quality.md',
+                artifact: 'requirements, acceptance criteria, and risk traceability matrix',
+                notes: 'Used when numeric coverage cannot express the main risk.',
+            },
+        ],
+        exceptions: [],
+        updated_at: nowIso(),
+    };
+}
+export function ensureFeatureQualityContract(feature, inheritedFrom) {
+    if (!feature.quality_contract) {
+        feature.quality_contract = buildDefaultQualityContract({
+            inheritedFrom: inheritedFrom || feature.origin_ref || feature.id,
+        });
+        return feature.quality_contract;
+    }
+    feature.quality_contract.required_axes = Array.from(new Set([
+        ...((feature.quality_contract.required_axes || []).filter(Boolean)),
+        'requirements',
+        'critical_flows',
+        'contracts',
+        'acceptance_criteria',
+        'risks',
+    ]));
+    if (feature.quality_contract.required_evidence.length === 0) {
+        feature.quality_contract.required_evidence = buildDefaultQualityContract({
+            inheritedFrom: inheritedFrom || feature.quality_contract.inherited_from || feature.origin_ref || feature.id,
+        }).required_evidence;
+    }
+    if (feature.quality_contract.enforcement === 'advisory' && feature.quality_contract.exceptions.length === 0) {
+        feature.quality_contract.enforcement = 'blocking';
+    }
+    feature.quality_contract.updated_at = feature.quality_contract.updated_at || nowIso();
+    return feature.quality_contract;
+}
+export const FORCED_TRANSITION_MARKERS = [
+    '--force-transition',
+    'forced_transition',
+    'transição forçada',
+    'transicao forcada',
+];
+export function normalizePercent(part, total) {
+    if (total <= 0)
+        return 100;
+    return Math.round((part / total) * 10000) / 100;
+}
+export async function readMetaEvolutionConfig(paths) {
+    try {
+        const raw = yaml.parse(await fs.readFile(paths.configFile, 'utf-8'));
+        const candidate = raw && typeof raw === 'object' && raw.meta_evolution && typeof raw.meta_evolution === 'object'
+            ? raw.meta_evolution
+            : {};
+        const placeholderMarkers = Array.isArray(candidate.placeholder_markers)
+            ? candidate.placeholder_markers
+                .map((value) => String(value).trim().toLowerCase())
+                .filter((value) => value.length > 0)
+            : DEFAULT_META_EVOLUTION_CONFIG.placeholder_markers;
+        return {
+            enabled: typeof candidate.enabled === 'boolean'
+                ? candidate.enabled
+                : DEFAULT_META_EVOLUTION_CONFIG.enabled,
+            audit_interval_days: typeof candidate.audit_interval_days === 'number' &&
+                Number.isFinite(candidate.audit_interval_days) &&
+                candidate.audit_interval_days > 0
+                ? candidate.audit_interval_days
+                : DEFAULT_META_EVOLUTION_CONFIG.audit_interval_days,
+            placeholder_markers: placeholderMarkers.length > 0
+                ? placeholderMarkers
+                : DEFAULT_META_EVOLUTION_CONFIG.placeholder_markers,
+            health_alert_threshold: typeof candidate.health_alert_threshold === 'number' &&
+                Number.isFinite(candidate.health_alert_threshold) &&
+                candidate.health_alert_threshold >= 0 &&
+                candidate.health_alert_threshold <= 100
+                ? candidate.health_alert_threshold
+                : DEFAULT_META_EVOLUTION_CONFIG.health_alert_threshold,
+        };
+    }
+    catch {
+        return { ...DEFAULT_META_EVOLUTION_CONFIG };
+    }
+}
+export async function listFilesRecursive(rootDir) {
+    const files = [];
+    async function walk(currentDir) {
+        const entries = await fs.readdir(currentDir, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries) {
+            const full = path.join(currentDir, entry.name);
+            if (entry.isDirectory()) {
+                await walk(full);
+            }
+            else {
+                files.push(full);
+            }
+        }
+    }
+    await walk(rootDir);
+    return files;
+}
+export function hasPlaceholder(content, markers) {
+    const normalized = content.toLowerCase();
+    return markers.some((marker) => {
+        const normalizedMarker = marker.toLowerCase().trim();
+        if (!normalizedMarker)
+            return false;
+        if (/^[a-z0-9_-]+$/i.test(normalizedMarker)) {
+            const escaped = normalizedMarker.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            return new RegExp(`\\b${escaped}\\b`, 'i').test(content);
+        }
+        return normalized.includes(normalizedMarker);
+    });
+}
+export async function collectAuditArtifacts(paths) {
+    const roots = [paths.activeDir, paths.archivedDir, paths.discoveryDir, path.join(paths.coreDir, 'adrs')];
+    const artifactFiles = [];
+    for (const root of roots) {
+        const files = await listFilesRecursive(root);
+        for (const filePath of files) {
+            if (filePath.endsWith('.md') || filePath.endsWith('.yaml'))
+                artifactFiles.push(filePath);
+        }
+    }
+    return artifactFiles;
+}
+export function debateHasRealDeliberation(content) {
+    const lower = content.toLowerCase();
+    const sectionIndexCandidates = [
+        lower.indexOf('## 7) decisao do mediador'),
+        lower.indexOf('## 7) decisão do mediador'),
+        lower.indexOf('## 7) mediator decision'),
+    ].filter((index) => index >= 0);
+    const sectionIndex = sectionIndexCandidates.length > 0 ? Math.min(...sectionIndexCandidates) : -1;
+    if (sectionIndex < 0)
+        return false;
+    const tail = content.slice(sectionIndex);
+    const choiceMatch = tail.match(/- Escolha \(A\/B\/C\):\s*(.+)/i) ||
+        tail.match(/- \*\*Escolha \(A\/B\/C\):\*\*\s*(.+)/i) ||
+        tail.match(/- Escolha:\s*(?:op(?:ç|c)[aã]o\s*)?([ABC])\b/i) ||
+        tail.match(/- Op(?:ç|c)[aã]o escolhida:\s*([ABC])\b/i) ||
+        tail.match(/- Choice \(A\/B\/C\):\s*(.+)/i) ||
+        tail.match(/- \*\*Choice \(A\/B\/C\):\*\*\s*(.+)/i) ||
+        tail.match(/- Choice:\s*(?:option\s*)?([ABC])\b/i) ||
+        tail.match(/- Selected option:\s*([ABC])\b/i);
+    const rationaleMatch = tail.match(/- Justificativa:\s*(.+)/i) ||
+        tail.match(/- \*\*Justificativa:\*\*\s*([\s\S]+?)(?:\n\s*-\s|\n##|\n---|$)/i) ||
+        tail.match(/- Rationale:\s*(.+)/i) ||
+        tail.match(/- \*\*Rationale:\*\*\s*([\s\S]+?)(?:\n\s*-\s|\n##|\n---|$)/i);
+    const approvedOutcome = /\bAPPROVED\b|aprovad[ao]/i.test(tail);
+    if ((!choiceMatch && !approvedOutcome) || !rationaleMatch)
+        return false;
+    const choice = (choiceMatch?.[1] || 'approved').trim().toLowerCase();
+    const rationale = rationaleMatch[1].trim().toLowerCase();
+    if (!choice || !rationale)
+        return false;
+    const invalidTokens = ['(preencher', '(fill in', '____', '-'];
+    const isInvalid = (value, token) => value === token || (token !== '-' && value.includes(token));
+    const choiceInvalid = invalidTokens.some((token) => isInvalid(choice, token));
+    const rationaleInvalid = invalidTokens.some((token) => isInvalid(rationale, token));
+    return !choiceInvalid && !rationaleInvalid;
+}
+export async function collectForcedTransitions(paths) {
+    const roots = [paths.activeDir, paths.archivedDir];
+    let count = 0;
+    const featureRefs = new Set();
+    for (const root of roots) {
+        const files = await listFilesRecursive(root);
+        for (const filePath of files) {
+            if (!/4-(changelog|historico)\.(md|yaml)$/i.test(filePath))
+                continue;
+            const content = (await fs.readFile(filePath, 'utf-8').catch(() => '')).toLowerCase();
+            if (FORCED_TRANSITION_MARKERS.some((marker) => content.includes(marker))) {
+                count += 1;
+                const match = filePath.match(/FEAT-\d{3,}/);
+                if (match?.[0])
+                    featureRefs.add(match[0]);
+            }
+        }
+    }
+    return { total: count, featureRefs: Array.from(featureRefs).sort() };
+}
+export function sourceTypeFromRelativePath(relativePath) {
+    const normalized = relativePath.replace(/\\/g, '/').toLowerCase();
+    if (normalized.includes('/prds/'))
+        return 'prd';
+    if (normalized.includes('/rfcs/'))
+        return 'rfc';
+    if (normalized.includes('/briefings/'))
+        return 'briefing';
+    if (normalized.includes('/historias/'))
+        return 'historia';
+    if (normalized.includes('/wireframes/'))
+        return 'wireframe';
+    if (normalized.includes('/html-mocks/'))
+        return 'html_mock';
+    if (normalized.includes('/referencias-visuais/'))
+        return 'referencia_visual';
+    if (normalized.includes('/entrevistas/'))
+        return 'entrevista';
+    if (normalized.includes('/anexos/'))
+        return 'anexo';
+    if (normalized.includes('/legado/'))
+        return 'legado';
+    return 'outro';
+}
+export function defaultConsolidationTargets(type) {
+    switch (type) {
+        case 'prd':
+        case 'briefing':
+        case 'historia':
+            return ['contexto', 'epic', 'backlog'];
+        case 'wireframe':
+        case 'html_mock':
+        case 'referencia_visual':
+            return ['frontend-map', 'frontend-gaps', 'frontend-decisions', 'backlog'];
+        case 'rfc':
+            return ['arquitetura', 'servicos', 'integration-contracts', 'backlog'];
+        case 'legado':
+            return ['repo-map', 'arquitetura', 'backlog'];
+        case 'entrevista':
+            return ['insights', 'epic'];
+        default:
+            return ['contexto'];
+    }
+}
+export function deriveInitialFeatureTitles(sources, frontendEnabled) {
+    const types = new Set(sources.map((source) => source.type));
+    const titles = [];
+    if (types.has('prd') || types.has('historia') || types.has('briefing') || types.has('rfc')) {
+        titles.push('Initial business core and primary contracts');
+    }
+    if (frontendEnabled &&
+        (types.has('wireframe') || types.has('html_mock') || types.has('referencia_visual'))) {
+        titles.push('Initial frontend structure based on references');
+    }
+    if (types.has('legado')) {
+        titles.push('Legacy mapping and adaptation to current architecture');
+    }
+    titles.push('Consolidate operational documentation and handoff trail');
+    return Array.from(new Set(titles));
+}
+export async function listFilesRecursively(rootDir) {
+    const entries = await fs.readdir(rootDir, { withFileTypes: true }).catch(() => []);
+    const files = [];
+    for (const entry of entries) {
+        const absolute = path.join(rootDir, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...(await listFilesRecursively(absolute)));
+            continue;
+        }
+        if (!entry.isFile())
+            continue;
+        files.push(absolute);
+    }
+    return files;
+}
+export function sourceTitleFromPath(filePath) {
+    const base = path.basename(filePath, path.extname(filePath));
+    const cleaned = base.replace(/[-_]+/g, ' ').trim();
+    if (!cleaned)
+        return base || 'fonte sem titulo';
+    return cleaned.charAt(0).toUpperCase() + cleaned.slice(1);
+}
+export function normalizeSourceStatus(current, desired) {
+    const order = {
+        RAW: 0,
+        INDEXED: 1,
+        NORMALIZED: 2,
+        PLANNED: 3,
+        ARCHIVED: 4,
+    };
+    return order[current] >= order[desired] ? current : desired;
+}
+export function nextSourceId(existingIds) {
+    let max = 0;
+    for (const id of existingIds) {
+        const match = /^SRC-(\d+)$/.exec(id);
+        if (!match)
+            continue;
+        const numeric = Number(match[1]);
+        if (Number.isFinite(numeric)) {
+            max = Math.max(max, numeric);
+        }
+    }
+    return `SRC-${String(max + 1).padStart(4, '0')}`;
+}
+export async function extractSourceSummary(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    const textLike = new Set([
+        '.md',
+        '.txt',
+        '.rst',
+        '.adoc',
+        '.json',
+        '.yaml',
+        '.yml',
+        '.html',
+        '.htm',
+        '.csv',
+    ]);
+    if (!textLike.has(ext)) {
+        return '';
+    }
+    const raw = await fs.readFile(filePath, 'utf-8').catch(() => '');
+    if (!raw.trim())
+        return '';
+    const lines = raw
+        .split(/\r?\n/)
+        .map((line) => line.replace(/^#+\s*/, '').replace(/<[^>]+>/g, '').trim())
+        .filter((line) => line.length > 0);
+    const candidate = lines.find((line) => line.length > 20) || lines[0] || '';
+    return candidate.slice(0, 220);
+}
+export async function findDebateFile(paths, debateId) {
+    const debateDir = paths.discoveryDebatesDir;
+    const entries = await fs.readdir(debateDir, { withFileTypes: true }).catch(() => []);
+    const found = entries.find((entry) => entry.isFile() && entry.name.startsWith(`${debateId}-`));
+    if (!found)
+        return null;
+    return path.join(debateDir, found.name);
+}
+export function validateDebateDocument(content) {
+    const missing = validateDocumentAgainstLens(content, LENSES.debate);
+    if (content.includes('Decidir ____ em vez de ____ para resolver ____.') ||
+        content.includes('Decide ____ instead of ____ to solve ____.')) {
+        missing.push('Fill the decision question with real context');
+    }
+    if (/\- (?:Escolha|Choice) \(A\/B\/C\):\s*$/m.test(content)) {
+        missing.push('Inform the mediator choice in "Choice (A/B/C)"');
+    }
+    if (/\- (?:Justificativa|Rationale):\s*$/m.test(content)) {
+        missing.push('Inform the mediator decision rationale');
+    }
+    if (/\- Unit coverage:\s*$/m.test(content)) {
+        missing.push('Inform required unit coverage evidence in the quality contract');
+    }
+    if (/\- Integration\/e2e or equivalent:\s*$/m.test(content)) {
+        missing.push('Inform integration/e2e or equivalence evidence in the quality contract');
+    }
+    if (/\- Acceptance and risk matrix:\s*$/m.test(content)) {
+        missing.push('Inform acceptance and risk matrix evidence in the quality contract');
+    }
+    if (/\- Exceptions:\s*\n\s+- None, or formal exception/m.test(content)) {
+        missing.push('Confirm there is no quality exception or document the formal exception');
+    }
+    return missing;
+}
+export function pickTopSkills(catalogSkills, ids, max = 3) {
+    if (!ids || ids.length === 0)
+        return [];
+    const known = new Set(catalogSkills.map((skill) => skill.id));
+    return ids.filter((id) => known.has(id)).slice(0, max);
+}
+export function bundlesForSkills(catalog, skillIds) {
+    return Array.from(new Set(catalog.skills
+        .filter((skill) => skillIds.includes(skill.id))
+        .flatMap((skill) => skill.bundle_ids)));
+}
+export function syncCounterFromId(discoveryIndex, id) {
+    const [prefix, numeric] = id.split('-');
+    if (!prefix || !numeric)
+        return;
+    if (!['INS', 'DEB', 'RAD', 'EPIC', 'FEAT', 'FGAP', 'TD'].includes(prefix))
+        return;
+    const value = Number(numeric);
+    if (!Number.isFinite(value))
+        return;
+    const counterKey = prefix;
+    discoveryIndex.counters[counterKey] = Math.max(discoveryIndex.counters[counterKey] || 0, value);
+}
+export async function getRuntime(projectRoot) {
+    const { resolveProjectRoot } = await import('./resolve-project-root.js');
+    const resolved = resolveProjectRoot(projectRoot === '.' ? undefined : projectRoot);
+    const config = await loadProjectSddConfig(resolved);
+    const paths = resolveSddPaths(resolved, config);
+    await ensureMemoryInitialized(paths);
+    return { config, paths };
+}
+export async function persistAndRender(paths, config, render) {
+    if (!render && render !== undefined)
+        return;
+    if (!config.views.autoRender && render === undefined)
+        return;
+    const snapshot = await loadStateSnapshot(paths, config);
+    await renderViews(paths, config, snapshot);
+}
+export function relProjectPath(paths, absolutePath) {
+    return path.relative(paths.projectRoot, absolutePath).replace(/\\/g, '/');
+}
+export function coreDocRef(paths, name) {
+    return relProjectPath(paths, path.join(paths.coreDir, name));
+}
+export function planningDocRef(paths, name) {
+    return relProjectPath(paths, path.join(paths.pendenciasDir, name));
+}
+export function activeFeatureRef(paths, featureId, fileName) {
+    return relProjectPath(paths, path.join(paths.activeDir, featureId, fileName));
+}
+export function featureActiveDir(paths, featureId) {
+    return path.join(paths.activeDir, featureId);
+}
+export function featurePlannedDir(paths, featureId) {
+    return path.join(paths.plannedDir, featureId);
+}
+export function activeDocNamesForLayout(config) {
+    return {
+        spec: '1-spec.yaml',
+        plan: '2-plan.yaml',
+        quality: '5-quality.yaml',
+        tasks: '3-tasks.yaml',
+        changelog: '4-changelog.yaml',
+    };
+}
+export function activeDocCandidateNames(config) {
+    const preferred = activeDocNamesForLayout(config);
+    const canonical = ['1-spec.yaml', '2-plan.yaml', '5-quality.yaml', '3-tasks.yaml', '4-changelog.yaml'];
+    const english = ['1-spec.md', '2-plan.md', 'quality.md', '3-tasks.md', '4-changelog.md'];
+    const portuguese = ['1-especificacao.md', '2-planejamento.md', 'quality.md', '3-tarefas.md', '4-historico.md'];
+    return Array.from(new Set([preferred.spec, preferred.plan, preferred.quality, preferred.tasks, preferred.changelog, ...canonical, ...english, ...portuguese]));
+}
+export async function resolveActiveDocRefs(paths, featureId, config) {
+    const activePath = featureActiveDir(paths, featureId);
+    const names = activeDocCandidateNames(config);
+    const refs = [];
+    for (const name of names) {
+        const filePath = path.join(activePath, name);
+        if (await pathExists(filePath)) {
+            refs.push(activeFeatureRef(paths, featureId, name));
+        }
+    }
+    return refs;
+}
+function workspaceYamlDoc(fileName, value) {
+    return stringifyWorkspaceYamlDocument(fileName, value);
+}
+function ensureMinLength(value, fallback, minLength) {
+    const text = (value || fallback).trim();
+    if (text.length >= minLength) {
+        return text;
+    }
+    return `${text} ${fallback}`.trim().padEnd(minLength, '.');
+}
+function workspaceOriginType(feature) {
+    if (feature.origin_type === 'frontend_gap')
+        return 'fgap';
+    if (feature.origin_type === 'tech_debt')
+        return 'td';
+    if (feature.origin_type === 'fast_track')
+        return 'direct';
+    if (feature.origin_type === 'radar')
+        return 'radar';
+    if (feature.origin_type === 'epic')
+        return 'epic';
+    return 'direct';
+}
+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');
+}
+export function stackContextTokens(snapshot) {
+    return (snapshot.techStack?.items || [])
+        .flatMap((item) => [item.layer, item.technology])
+        .map((value) => value.trim())
+        .filter(Boolean);
+}
+function featureTokenText(feature) {
+    return [
+        feature.title,
+        feature.summary || '',
+        feature.execution_kind,
+        feature.planning_mode,
+        ...feature.touches,
+        ...feature.lock_domains,
+        ...feature.produces,
+        ...feature.consumes,
+        ...feature.recommended_skills,
+        ...(feature.quality_contract?.required_axes || []),
+        feature.quality_contract?.stack_profile || '',
+    ]
+        .join(' ')
+        .toLowerCase();
+}
+function workspaceExecutionProfileForFeature(feature) {
+    const tokens = featureTokenText(feature);
+    const isDevTrackTypescript = includesAny(tokens, ['devtrack', 'nestjs', 'nest.js', 'nest js', 'typeorm']) ||
+        feature.quality_contract?.stack_profile === 'typescript_node';
+    const hasPythonAgenticStack = feature.quality_contract?.stack_profile === 'python_agentic_backend' ||
+        includesAny(tokens, ['api-clean-flask-langgraph', 'python', 'flask', 'langgraph', 'langchain']);
+    const hasApiSurface = includesAny(tokens, ['/api', 'api/', 'endpoint']);
+    const hasAgentApiSurface = hasApiSurface && includesAny(tokens, ['agent', 'agente']);
+    const isPythonAgentic = !isDevTrackTypescript &&
+        (hasPythonAgenticStack || hasAgentApiSurface);
+    if (isPythonAgentic) {
+        return {
+            id: 'python_agentic_backend',
+            label: 'Python Flask/LangGraph backend workflow',
+            description: 'Python/Flask/LangGraph API routes, application services, adapters, and tests',
+            implementationFiles: ['app/', 'src/', 'tests/', 'pyproject.toml'],
+            unitCommand: 'python -m pytest tests -q',
+            integrationCommand: 'python -m pytest tests -q',
+            buildCommand: 'python -m compileall .',
+            buildExpected: 'Python sources compile and pytest validation passes for the touched scope.',
+            architectureTreeAscii: `project/\n  app/\n    api/\n    application/\n    domain/\n    infrastructure/\n  tests/\n  .sdd/\n    active/${feature.id}/`,
+        };
+    }
+    if (includesAny(tokens, ['frontend', 'ui', 'route']) && !includesAny(tokens, ['/api', 'api/'])) {
+        return {
+            id: 'frontend_typescript',
+            label: 'frontend workflow',
+            description: 'frontend routes, UI coverage, and OpenSDD frontend guardrails',
+            implementationFiles: ['src/', 'app/', 'pages/', 'components/', 'tests/'],
+            unitCommand: 'pnpm test -- test/core/sdd-operations.test.ts',
+            integrationCommand: 'pnpm test -- test/core/sdd-operations.test.ts',
+            buildCommand: 'pnpm run build',
+            buildExpected: 'TypeScript build completes successfully after the scoped changes.',
+            architectureTreeAscii: `project/\n  src/\n  app/\n  components/\n  .sdd/\n    active/${feature.id}/`,
+        };
+    }
+    return {
+        id: 'opensdd_typescript',
+        label: 'OpenSDD backend workflow',
+        description: 'OpenSDD state, command services, and backend validation flows',
+        implementationFiles: ['src/core/sdd/legacy-operations.ts'],
+        unitCommand: 'pnpm test -- test/core/sdd-operations.test.ts',
+        integrationCommand: 'pnpm test -- test/core/sdd-operations.test.ts',
+        buildCommand: 'pnpm run build',
+        buildExpected: 'TypeScript build completes successfully after the scoped changes.',
+        architectureTreeAscii: `project/\n  src/\n  .sdd/\n    active/${feature.id}/`,
+    };
+}
+export function buildActiveSpecDoc(feature) {
+    const now = nowIso();
+    const title = ensureMinLength(feature.title, `Workspace execution for ${feature.id}`, 10);
+    const objective = ensureMinLength(feature.summary, `Deliver ${feature.title} with traceability from SDD state to implementation evidence, preserving the planned scope, dependencies, quality gates, and handoff requirements for ${feature.id}.`, 100);
+    const baseDocument = {
+        schema_version: 1,
+        feature_id: feature.id,
+        title,
+        origin: {
+            type: workspaceOriginType(feature),
+            ref: feature.origin_ref || '',
+        },
+        objective,
+        expected_outcome: ensureMinLength(`${feature.title} is implemented with acceptance refs, dependencies, and quality evidence visible to the next agent.`, `Feature ${feature.id} reaches a verifiable done state with generated workspace artifacts and canonical SDD state in sync.`, 50),
+        system_impact: ensureMinLength('Preserve canonical SDD state, generated views, documentation sync, and handoff context without hidden operational memory.', `System impact for ${feature.id} remains visible in OpenSDD state and workspace artifacts.`, 30),
+        acceptance_refs: feature.acceptance_refs.length > 0 ? feature.acceptance_refs : [feature.origin_ref || feature.id],
+        gates: feature.gates,
+        created_at: now,
+        updated_at: now,
+    };
+    if (isPrivacyComplianceFeature(feature)) {
+        baseDocument.compliance_context = {
+            jurisdictions: ['BR-LGPD', 'EU-GDPR', 'US-MULTI-STATE'],
+            data_classes: ['personal_data', 'sensitive_data', 'children_data', 'online_identifiers'],
+            source_refs: ['SRC-0001'],
+            legal_review_required: true,
+            legal_review_notes: 'Human legal validation is required before final legal interpretation or jurisdiction-specific enforcement decisions.',
+        };
+    }
+    return workspaceYamlDoc('1-spec.yaml', baseDocument);
+}
+export function buildActivePlanDoc(feature, recommendedBundles) {
+    const profile = workspaceExecutionProfileForFeature(feature);
+    const affectedContracts = [
+        ...feature.consumes.map((name) => ({ name, change_type: 'consumes' })),
+        ...feature.produces.map((name) => ({ name, change_type: 'produces' })),
+    ];
+    const baseDocument = {
+        schema_version: 1,
+        feature_id: feature.id,
+        architectural_impact: {
+            description: `Touches ${feature.touches.join(', ') || 'the active SDD workspace'} with lock domains ${feature.lock_domains.join(', ') || 'none declared'}.`,
+            affected_modules: feature.touches,
+        },
+        frontend_impact: {
+            status: feature.frontend_impact_status,
+            description: feature.frontend_impact_reason || 'Frontend impact must be declared before finalize when applicable.',
+        },
+        affected_contracts: affectedContracts,
+        quality_strategy: {
+            unit_target: feature.quality_contract?.unit_target_percent ?? 95,
+            integration_target: feature.quality_contract?.integration_target_percent ?? 95,
+            approach: feature.quality_contract?.evidence_mode || 'hybrid',
+        },
+        suggested_skills: Array.from(new Set([...feature.recommended_skills, ...recommendedBundles])),
+        skill_conformance: {
+            selected_skills: feature.recommended_skills,
+            required_skills: feature.recommended_skills,
+            detected_conflicts: [],
+            architecture_tree_ascii: profile.architectureTreeAscii,
+        },
+    };
+    if (isPrivacyComplianceFeature(feature)) {
+        baseDocument.privacy_controls = {
+            source_registry_refs: ['SRC-0001'],
+            jurisdiction_profiles: ['JP-BR-LGPD', 'JP-EU-GDPR', 'JP-US-PRIVACY-MODEL'],
+            control_ids: ['CTRL-TRANSPARENCY-001', 'CTRL-LEGAL-BASIS-001', 'CTRL-SECURITY-001'],
+            legal_review_gate: 'required',
+            unresolved_legal_questions: [
+                'Confirm lawful basis fit for each jurisdiction before production go-live.',
+            ],
+        };
+    }
+    return workspaceYamlDoc('2-plan.yaml', baseDocument);
+}
+export function buildActiveQualityDoc(feature) {
+    const contract = ensureFeatureQualityContract(feature);
+    const profile = workspaceExecutionProfileForFeature(feature);
+    const targetedTestCommand = testCommandForFeature(feature);
+    const requiredSkillIds = Array.from(new Set(feature.recommended_skills.filter(Boolean)));
+    const baseDocument = {
+        schema_version: 1,
+        feature_id: feature.id,
+        coverage_targets: {
+            unit: contract.unit_target_percent,
+            integration: contract.integration_target_percent,
+        },
+        validation_strategies: [
+            {
+                name: 'Targeted tests',
+                command: targetedTestCommand,
+                expected: 'Changed behavior passes targeted validation for the touched scope.',
+            },
+            {
+                name: 'Build',
+                command: profile.buildCommand,
+                expected: profile.buildExpected,
+            },
+        ],
+        evidence_log: [],
+        skill_evidence: {
+            required_skill_ids: requiredSkillIds,
+            evidence: [],
+            verification_rule: requiredSkillIds.length > 0
+                ? `Record one evidence entry per required skill before finalize: ${requiredSkillIds.join(', ')}.`
+                : 'No skill evidence required for this feature.',
+        },
+        acceptance_matrix: contract.required_axes.map((axis) => ({
+            criterion: axis,
+            status: 'not_met',
+            evidence: 'Evidence must be recorded before finalize.',
+        })),
+        exceptions: contract.exceptions.map((exception) => ({
+            scope: exception.scope,
+            reason: exception.reason,
+            accepted_risk: exception.accepted_risk,
+            compensating_control: exception.compensating_control,
+        })),
+        remediation_policy: {
+            on_coverage_miss: contract.exceptions.length > 0 ? 'exception' : 'block',
+            max_rounds: 3,
+        },
+        traceability: {
+            spec_anchor: {
+                spec_updated_at: '',
+                changelog_refs: [],
+            },
+            requirements: [],
+        },
+    };
+    if (isPrivacyComplianceFeature(feature)) {
+        baseDocument.security_integrity = {
+            endpoint_auth_review: 'pending',
+            sensitive_data_exposure_review: 'pending',
+            incident_response_review: 'pending',
+            notes: 'Record explicit evidence for exposed endpoints, sensitive-data handling, and incident response readiness before finalize.',
+        };
+    }
+    return workspaceYamlDoc('5-quality.yaml', baseDocument);
+}
+export function buildActiveTasksDoc(feature, paths) {
+    const memoryAgentGuide = relProjectPath(paths, path.join(paths.memoryRoot, 'AGENT.md'));
+    const coreDocsDir = relProjectPath(paths, paths.coreDir);
+    const scope = taskScopeForFeature(feature);
+    const touchedFiles = filesForFeatureScope(feature, paths);
+    const targetedTestCommand = testCommandForFeature(feature);
+    const profile = workspaceExecutionProfileForFeature(feature);
+    const skills = feature.recommended_skills.length > 0
+        ? feature.recommended_skills.join(', ')
+        : 'architecture and api-design-principles';
+    const summary = feature.summary || `Deliver ${feature.title} for ${scope.description}.`;
+    return workspaceYamlDoc('3-tasks.yaml', {
+        schema_version: 1,
+        feature_id: feature.id,
+        tasks: [
+            {
+                id: `${feature.id}-T1`,
+                phase: 'preparation',
+                title: `Frame ${feature.title}`,
+                description: `Run ${CLI_NAME} sdd context ${feature.id}, confirm ${scope.description}, review ${skills}, and turn the feature summary into concrete acceptance checks: ${summary}`,
+                files_touched: ['.sdd/state/backlog.yaml', '.sdd/state/discovery-index.yaml'],
+                test_scripts: [],
+                acceptance: `The implementation plan names the ${scope.description} files, expected validation commands, and any dependency or lock-domain risk before edits begin.`,
+                status: 'pending',
+            },
+            {
+                id: `${feature.id}-T2`,
+                phase: 'implementation',
+                title: `Implement ${scope.label}`,
+                description: `Apply the ${feature.title} changes in ${touchedFiles.join(', ')} while preserving existing public contracts and SDD state transitions.`,
+                files_touched: touchedFiles,
+                test_scripts: [],
+                acceptance: `The ${scope.label} behavior is implemented, uses existing OpenSDD patterns, and keeps generated workspace/state artifacts valid.`,
+                status: 'pending',
+            },
+            {
+                id: `${feature.id}-T3`,
+                phase: 'testing',
+                title: `Validate ${scope.label}`,
+                description: `Run focused validation for ${scope.description}, then record unit and integration evidence in 5-quality.yaml so coverage targets can be evaluated before finalize.`,
+                files_touched: ['.sdd/active/<FEAT-ID>/5-quality.yaml', ...touchedFiles],
+                test_scripts: [
+                    {
+                        command: targetedTestCommand,
+                        type: 'unit',
+                        expected: `Targeted tests for ${scope.description} pass and provide evidence for unit coverage.`,
+                    },
+                    {
+                        command: profile.buildCommand,
+                        type: 'build',
+                        expected: profile.buildExpected,
+                    },
+                ],
+                acceptance: 'Testing task includes executable commands and produces evidence entries for unit and integration coverage targets.',
+                status: 'pending',
+            },
+            {
+                id: `${feature.id}-T4`,
+                phase: 'documentation',
+                title: `Document ${scope.label}`,
+                description: `Update README.md, ${memoryAgentGuide}, AGENTS.md, AGENT.md, and affected docs under ${coreDocsDir} when ${feature.title} changes workflow, validation, or contributor expectations.`,
+                files_touched: ['README.md', memoryAgentGuide, 'AGENTS.md', 'AGENT.md', coreDocsDir],
+                test_scripts: [],
+                acceptance: `Docs either describe the ${scope.label} behavior and validation loop or record a clear no-doc-impact rationale.`,
+                status: 'pending',
+            },
+            {
+                id: `${feature.id}-T5`,
+                phase: 'finalization',
+                title: `Finalize ${feature.id}`,
+                description: `Declare frontend impact, ensure 5-quality.yaml has evidence meeting coverage targets or a formal exception, then finalize with ${CLI_NAME} sdd finalize --ref ${feature.id}.`,
+                files_touched: ['.sdd/active/<FEAT-ID>/5-quality.yaml', '.sdd/state/backlog.yaml', '.sdd/state/transition-log.yaml'],
+                test_scripts: [
+                    {
+                        command: profile.buildCommand,
+                        type: 'build',
+                        expected: profile.buildExpected,
+                    },
+                ],
+                acceptance: 'Frontend impact is declared, quality coverage targets are met or formally excepted, and SDD finalize succeeds without unresolved re-task rounds.',
+                status: 'pending',
+            },
+        ],
+    });
+}
+function taskScopeForFeature(feature) {
+    const tokens = [
+        ...feature.touches,
+        ...feature.recommended_skills,
+        feature.title,
+        feature.summary || '',
+    ].join(' ').toLowerCase();
+    const profile = workspaceExecutionProfileForFeature(feature);
+    if (profile.id !== 'opensdd_typescript') {
+        return { label: profile.label, description: profile.description };
+    }
+    if (tokens.includes('skill')) {
+        return { label: 'skill distribution workflow', description: 'built-in skills, skill catalog state, and distribution templates' };
+    }
+    if (tokens.includes('schema') || tokens.includes('yaml') || tokens.includes('workspace')) {
+        return { label: 'workspace schema workflow', description: 'workspace YAML documents, schemas, and SDD write validation' };
+    }
+    if (tokens.includes('sdd') || tokens.includes('backend') || tokens.includes('architecture')) {
+        return { label: 'OpenSDD backend workflow', description: 'OpenSDD state, command services, and backend validation flows' };
+    }
+    return { label: 'feature scope', description: feature.touches.join(', ') || 'the declared feature scope' };
+}
+function filesForFeatureScope(feature, paths) {
+    const tokens = [
+        ...feature.touches,
+        ...feature.recommended_skills,
+        feature.title,
+        feature.summary || '',
+    ].join(' ').toLowerCase();
+    const profile = workspaceExecutionProfileForFeature(feature);
+    if (profile.id === 'python_agentic_backend') {
+        return [
+            ...profile.implementationFiles,
+            '.sdd/active/<FEAT-ID>/3-tasks.yaml',
+            '.sdd/active/<FEAT-ID>/5-quality.yaml',
+        ];
+    }
+    const files = new Set();
+    if (tokens.includes('schema') || tokens.includes('yaml') || tokens.includes('workspace')) {
+        files.add('src/core/sdd/workspace-schemas.ts');
+        files.add('src/core/sdd/legacy-operations.ts');
+        files.add('src/core/sdd/write-manifest.ts');
+    }
+    if (tokens.includes('quality') || tokens.includes('finalize') || tokens.includes('task')) {
+        files.add('src/core/sdd/legacy-operations.ts');
+        files.add('src/core/sdd/services/finalize.service.ts');
+    }
+    if (tokens.includes('skill')) {
+        files.add('src/core/sdd/default-skills.ts');
+        files.add(path.relative(paths.projectRoot, paths.skillsDir).replace(/\\/g, '/'));
+    }
+    if (tokens.includes('frontend')) {
+        files.add('src/core/sdd/services/frontend-impact.service.ts');
+        files.add('src/core/sdd/services/frontend-gap.service.ts');
+    }
+    if (files.size === 0) {
+        files.add('src/core/sdd/legacy-operations.ts');
+    }
+    files.add('.sdd/active/<FEAT-ID>/3-tasks.yaml');
+    files.add('.sdd/active/<FEAT-ID>/5-quality.yaml');
+    return Array.from(files);
+}
+function testCommandForFeature(feature) {
+    const profile = workspaceExecutionProfileForFeature(feature);
+    if (profile.id === 'python_agentic_backend') {
+        return profile.unitCommand;
+    }
+    const tokens = [
+        ...feature.touches,
+        ...feature.recommended_skills,
+        feature.title,
+        feature.summary || '',
+    ].join(' ').toLowerCase();
+    if (tokens.includes('quality') || tokens.includes('task') || tokens.includes('finalize')) {
+        return 'pnpm test -- test/core/sdd/task-quality-schemas.test.ts';
+    }
+    if (tokens.includes('schema') || tokens.includes('yaml') || tokens.includes('workspace')) {
+        return 'pnpm test -- test/core/sdd/workspace-schemas.test.ts';
+    }
+    if (tokens.includes('frontend')) {
+        return 'pnpm test -- test/core/sdd-operations.test.ts';
+    }
+    if (tokens.includes('skill')) {
+        return 'pnpm test -- test/core/sdd-skills.test.ts';
+    }
+    return 'pnpm test -- test/core/sdd-operations.test.ts';
+}
+export function buildActiveChangelogDoc(feature) {
+    return workspaceYamlDoc('4-changelog.yaml', {
+        schema_version: 1,
+        feature_id: feature.id,
+        entries: [
+            {
+                timestamp: nowIso(),
+                action: 'workspace_created',
+                details: 'Workspace created automatically for feature execution.',
+            },
+        ],
+    });
+}
+export async function ensureFeaturePlannedWorkspace(paths, config, feature, recommendedBundles) {
+    const plannedPath = featurePlannedDir(paths, feature.id);
+    const names = activeDocNamesForLayout(config);
+    const docs = [
+        path.join(plannedPath, names.spec),
+        path.join(plannedPath, names.plan),
+        path.join(plannedPath, names.quality),
+        path.join(plannedPath, names.tasks),
+        path.join(plannedPath, names.changelog),
+    ];
+    ensureFeatureQualityContract(feature);
+    const tx = new SddWriteTransaction();
+    let hasWrites = false;
+    if (!(await pathExists(docs[0]))) {
+        tx.writeFile(docs[0], buildActiveSpecDoc(feature));
+        hasWrites = true;
+    }
+    if (!(await pathExists(docs[1]))) {
+        tx.writeFile(docs[1], buildActivePlanDoc(feature, recommendedBundles));
+        hasWrites = true;
+    }
+    if (!(await pathExists(docs[2]))) {
+        tx.writeFile(docs[2], buildActiveQualityDoc(feature));
+        hasWrites = true;
+    }
+    if (!(await pathExists(docs[3]))) {
+        tx.writeFile(docs[3], buildActiveTasksDoc(feature, paths));
+        hasWrites = true;
+    }
+    if (!(await pathExists(docs[4]))) {
+        tx.writeFile(docs[4], buildActiveChangelogDoc(feature));
+        hasWrites = true;
+    }
+    if (hasWrites) {
+        await tx.commit(paths.projectRoot, paths.memoryRoot, 'ensureFeaturePlannedWorkspace');
+    }
+    const handoffSeedRefs = [feature.id, feature.origin_ref].filter((v) => Boolean(v));
+    return {
+        plannedPath,
+        generatedDocs: docs.map((doc) => path.relative(paths.projectRoot, doc)),
+        handoffSeedRefs,
+    };
+}
+export async function ensureFeatureActiveWorkspace(paths, config, feature, recommendedBundles) {
+    const activePath = featureActiveDir(paths, feature.id);
+    const names = activeDocNamesForLayout(config);
+    const docs = [
+        path.join(activePath, names.spec),
+        path.join(activePath, names.plan),
+        path.join(activePath, names.quality),
+        path.join(activePath, names.tasks),
+        path.join(activePath, names.changelog),
+    ];
+    ensureFeatureQualityContract(feature);
+    const tx = new SddWriteTransaction();
+    let hasWrites = false;
+    if (!(await pathExists(docs[0]))) {
+        tx.writeFile(docs[0], buildActiveSpecDoc(feature));
+        hasWrites = true;
+    }
+    if (!(await pathExists(docs[1]))) {
+        tx.writeFile(docs[1], buildActivePlanDoc(feature, recommendedBundles));
+        hasWrites = true;
+    }
+    if (!(await pathExists(docs[2]))) {
+        tx.writeFile(docs[2], buildActiveQualityDoc(feature));
+        hasWrites = true;
+    }
+    if (!(await pathExists(docs[3]))) {
+        tx.writeFile(docs[3], buildActiveTasksDoc(feature, paths));
+        hasWrites = true;
+    }
+    if (!(await pathExists(docs[4]))) {
+        tx.writeFile(docs[4], buildActiveChangelogDoc(feature));
+        hasWrites = true;
+    }
+    if (hasWrites) {
+        await tx.commit(paths.projectRoot, paths.memoryRoot, 'ensureFeatureActiveWorkspace');
+    }
+    const handoffSeedRefs = [feature.id, feature.origin_ref].filter((v) => Boolean(v));
+    return {
+        activePath,
+        generatedDocs: docs.map((doc) => path.relative(paths.projectRoot, doc)),
+        handoffSeedRefs,
+    };
+}
+export function resolveRadar(record) {
+    if (!record || (record.type !== 'RAD' && record.type !== 'EPIC')) {
+        throw new Error('Referencia EPIC/RAD invalida.');
+    }
+}
+export function resolveFeat(items, id) {
+    const feat = items.find((item) => item.id === id);
+    if (!feat) {
+        throw new Error(`Feature ${id} nao encontrada no backlog.`);
+    }
+    return feat;
+}
+export function buildBacklogItem(id, title, originType, originRef, scale, recommendedSkills, options) {
+    const flowMode = options?.flowMode || 'padrao';
+    const profileSeed = [
+        title,
+        ...(options?.touches || []),
+        ...recommendedSkills,
+        ...(options?.produces || []),
+        ...(options?.consumes || []),
+    ].join(' ').toLowerCase();
+    const profileHasPythonAgenticStack = includesAny(profileSeed, [
+        'api-clean-flask-langgraph',
+        'python',
+        'flask',
+        'langgraph',
+        'langchain',
+    ]);
+    const profileHasApiSurface = includesAny(profileSeed, ['/api', 'api/', 'endpoint']);
+    const profileHasAgentApiSurface = profileHasApiSurface && includesAny(profileSeed, ['agent', 'agente']);
+    const stackProfile = (profileHasPythonAgenticStack || profileHasAgentApiSurface)
+        ? 'python_agentic_backend'
+        : includesAny(profileSeed, ['typescript', 'nodejs', 'node.js', 'nestjs', 'typeorm', 'devtrack'])
+            ? 'typescript_node'
+            : 'default';
+    const gates = flowMode === 'direto'
+        ? {
+            proposta: { status: 'nao_exigida', approved_at: '', approved_by: '', note: '' },
+            planejamento: { status: 'nao_exigida', approved_at: '', approved_by: '', note: '' },
+            tarefas: { status: 'rascunho', approved_at: '', approved_by: '', note: '' },
+        }
+        : {
+            proposta: { status: 'rascunho', approved_at: '', approved_by: '', note: '' },
+            planejamento: { status: 'rascunho', approved_at: '', approved_by: '', note: '' },
+            tarefas: { status: 'rascunho', approved_at: '', approved_by: '', note: '' },
+        };
+    return {
+        id,
+        title,
+        status: 'READY',
+        origin_type: originType,
+        origin_ref: originRef,
+        scale,
+        summary: '',
+        blocked_by: [],
+        touches: options?.touches || [],
+        lock_domains: options?.lockDomains || [],
+        parallel_group: options?.parallelGroup || '',
+        execution_kind: options?.executionKind || 'feature',
+        planning_mode: options?.planningMode || 'local_plan',
+        flow_mode: flowMode,
+        current_stage: 'proposta',
+        gates,
+        acceptance_refs: options?.acceptanceRefs || [],
+        produces: options?.produces || [],
+        consumes: options?.consumes || [],
+        priority_score: 0,
+        dependency_count: 0,
+        agent_role: '',
+        recommended_skills: recommendedSkills,
+        change_name: '',
+        branch_name: '',
+        worktree_path: '',
+        start_commit_sha: '',
+        requires_adr: false,
+        quality_contract: buildDefaultQualityContract({
+            inheritedFrom: originRef || originType,
+            scope: 'touched_scope',
+            stackProfile,
+        }),
+        frontend_impact_status: 'unknown',
+        frontend_impact_reason: '',
+        frontend_impact_declared_at: '',
+        frontend_surface_tokens: [],
+        frontend_gap_refs: [],
+        warning_links: [],
+        spec_refs: [],
+        last_sync_at: nowIso(),
+        archived_at: '',
+        done_at: '',
+        unblocked_at: '',
+    };
+}
+export function includesAny(haystack, needles) {
+    return needles.some((needle) => {
+        if (needle.length <= 3) {
+            return new RegExp(`(^|[^a-z0-9])${needle.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}([^a-z0-9]|$)`, 'i').test(haystack);
+        }
+        return haystack.includes(needle);
+    });
+}
+export function classifyFeatureShape(title, contextTokens = []) {
+    const titleNormalized = title.toLowerCase();
+    const contextNormalized = contextTokens.join(' ').toLowerCase();
+    const normalized = [titleNormalized, contextNormalized].join(' ').toLowerCase();
+    if (includesAny(normalized, ['migracao', 'migration', 'seed', 'backfill'])) {
+        return {
+            executionKind: 'migration',
+            touches: ['database'],
+            lockDomains: ['schema-change'],
+            produces: ['dados-migrados'],
+            consumes: ['modelo-de-dominio'],
+            planningMode: 'local_plan',
+        };
+    }
+    const routeTarget = parseRouteToken(title);
+    const isApiRoute = !!routeTarget && routeTarget.startsWith('/api');
+    const contextHasPythonAgenticStack = includesAny(contextNormalized, ['python', 'flask', 'langgraph', 'langchain']);
+    const titleHasExplicitApiSurface = includesAny(titleNormalized, [
+        '/api',
+        'api/',
+        'endpoint',
+        'flask',
+        'python',
+        'langgraph',
+        'langchain',
+    ]);
+    const titleHasBackendWork = contextHasPythonAgenticStack && titleNormalized.includes('backend');
+    const titleHasAgentApiWork = contextHasPythonAgenticStack &&
+        includesAny(titleNormalized, ['agent', 'agente']) &&
+        includesAny(titleNormalized, ['api', '/api', 'api/', 'endpoint', 'route', 'rota', 'backend']);
+    const isApiBackend = isApiRoute || titleHasExplicitApiSurface || titleHasBackendWork || titleHasAgentApiWork;
+    if (isApiBackend) {
+        const touches = ['backend', 'api'];
+        const lockDomains = ['api-contract'];
+        const produces = ['api-contract'];
+        if (routeTarget)
+            produces.push(`route:${routeTarget}`);
+        if (includesAny(normalized, ['python']))
+            touches.push('python');
+        if (includesAny(normalized, ['flask']))
+            touches.push('flask');
+        if (includesAny(normalized, ['langgraph', 'langchain'])) {
+            touches.push('langgraph');
+            lockDomains.push('agent-runtime');
+            produces.push('agent-workflow');
+        }
+        if (includesAny(normalized, ['agent', 'agente']))
+            touches.push('agent');
+        if (includesAny(normalized, ['pdf']))
+            produces.push('pdf-report');
+        if (includesAny(normalized, ['i18n', 'internationalization', 'localization', 'copy']))
+            touches.push('i18n');
+        return {
+            executionKind: 'feature',
+            touches: Array.from(new Set(touches)),
+            lockDomains: Array.from(new Set(lockDomains)),
+            produces: Array.from(new Set(produces)),
+            consumes: [],
+            planningMode: 'local_plan',
+        };
+    }
+    if (includesAny(normalized, ['frontend', 'tela', 'ui', 'pagina', 'rota'])) {
+        return {
+            executionKind: 'frontend_coverage',
+            touches: ['frontend'],
+            lockDomains: ['frontend-route'],
+            produces: ['interface-usuario'],
+            consumes: ['api-ou-contrato'],
+            planningMode: 'local_plan',
+        };
+    }
+    if (includesAny(normalized, ['infra', 'deploy', 'helm', 'terraform', 'pipeline'])) {
+        return {
+            executionKind: 'infra',
+            touches: ['infra'],
+            lockDomains: ['infra-shared'],
+            produces: ['infra-configurada'],
+            consumes: [],
+            planningMode: 'local_plan',
+        };
+    }
+    if (includesAny(normalized, ['docs', 'documentacao', 'adr', 'manual'])) {
+        return {
+            executionKind: 'documentation',
+            touches: ['docs'],
+            lockDomains: [],
+            produces: ['documentacao-atualizada'],
+            consumes: ['implementacao-concluida'],
+            planningMode: 'direct_tasks',
+        };
+    }
+    const authLock = includesAny(normalized, ['auth', 'autoriz', 'permiss'])
+        ? ['auth-rules']
+        : [];
+    const backendTouches = ['backend'];
+    if (includesAny(normalized, ['devtrack', 'foundation api', 'foundation-api', 'foundation'])) {
+        backendTouches.push('devtrack');
+    }
+    if (includesAny(normalized, ['nestjs', 'nest.js', 'nest js'])) {
+        backendTouches.push('nestjs');
+    }
+    if (includesAny(normalized, ['typeorm'])) {
+        backendTouches.push('typeorm');
+    }
+    return {
+        executionKind: 'feature',
+        touches: Array.from(new Set(backendTouches)),
+        lockDomains: authLock,
+        produces: ['capacidade-de-negocio'],
+        consumes: [],
+        planningMode: 'local_plan',
+    };
+}
+export function normalizeTitle(value) {
+    return normalizeSemanticText(value).replace(/\s+/g, '-');
+}
+export function intersects(a, b) {
+    const setB = new Set(b);
+    return a.some((v) => setB.has(v));
+}
+export function unresolvedDependencies(item, all) {
+    const byId = new Map(all.map((entry) => [entry.id, entry]));
+    return item.blocked_by.filter((depId) => {
+        const dep = byId.get(depId);
+        return !dep || dep.status !== 'DONE';
+    });
+}
+export function lockConflictWithActive(item, all) {
+    if (item.lock_domains.length === 0)
+        return [];
+    const conflicts = [];
+    for (const other of all) {
+        if (other.id === item.id)
+            continue;
+        if (other.status !== 'IN_PROGRESS')
+            continue;
+        if (intersects(item.lock_domains, other.lock_domains)) {
+            conflicts.push(other.id);
+        }
+    }
+    return conflicts;
+}
+export function featureReadiness(item, all) {
+    if (unresolvedDependencies(item, all).length > 0 || item.status === 'BLOCKED')
+        return 'BLOCKED';
+    if (lockConflictWithActive(item, all).length > 0)
+        return 'LOCK_CONFLICT';
+    return 'READY';
+}
+export function updateDependencyMetadata(items) {
+    for (const item of items) {
+        item.dependency_count = item.blocked_by.length;
+    }
+}
+export function parseRouteToken(value) {
+    const token = value.trim();
+    if (!token)
+        return null;
+    if (token.startsWith('route:')) {
+        const raw = token.slice('route:'.length).trim();
+        if (!raw)
+            return null;
+        return raw.startsWith('/') ? raw : `/${raw}`;
+    }
+    if (token.startsWith('/'))
+        return token;
+    const inlineRoute = token.match(/\/[a-z0-9_\-/:]*/i);
+    if (inlineRoute && inlineRoute[0])
+        return inlineRoute[0];
+    return null;
+}
+export function inferRouteTargetsFromFeature(feature) {
+    const routes = [
+        ...feature.produces.map(parseRouteToken),
+        ...feature.consumes.map(parseRouteToken),
+        ...(feature.frontend_surface_tokens || []).map(parseRouteToken),
+    ].filter((value) => Boolean(value));
+    return Array.from(new Set(routes));
+}
+export function inferSurfaceTargetsFromFeature(feature) {
+    return Array.from(new Set((feature.frontend_surface_tokens || []).map((token) => token.trim()).filter(Boolean)));
+}
+export async function gitHeadCommit(projectRoot) {
+    try {
+        const { stdout } = await execFileAsync('git', ['rev-parse', 'HEAD'], { cwd: projectRoot });
+        return stdout.trim();
+    }
+    catch {
+        return '';
+    }
+}
+export async function gitChangedFiles(projectRoot, baseRef) {
+    if (!baseRef) {
+        return { files: [], warning: 'base_ref_ausente' };
+    }
+    try {
+        const { stdout } = await execFileAsync('git', ['diff', '--name-only', `${baseRef}..HEAD`], {
+            cwd: projectRoot,
+        });
+        const files = stdout
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter(Boolean);
+        return { files, warning: '' };
+    }
+    catch {
+        return { files: [], warning: 'git_diff_indisponivel' };
+    }
+}
+export function isFrontendPath(filePath) {
+    const normalized = filePath.replace(/\\/g, '/').toLowerCase();
+    const frontendDirs = [
+        '/frontend/',
+        '/web/',
+        '/ui/',
+        '/app/',
+        '/pages/',
+        '/components/',
+        '/routes/',
+        '/views/',
+        '/templates/',
+        '/public/',
+    ];
+    if (frontendDirs.some((segment) => normalized.includes(segment)))
+        return true;
+    if (normalized.includes('/src/') &&
+        (normalized.includes('/src/app/') ||
+            normalized.includes('/src/pages/') ||
+            normalized.includes('/src/components/'))) {
+        return true;
+    }
+    return /\.(tsx|jsx|vue|svelte|css|scss|sass|less|html)$/.test(normalized);
+}
+export function detectFrontendImpactEvidence(feature, changedFiles) {
+    const metadataRoutes = inferRouteTargetsFromFeature(feature);
+    const metadataSurfaces = inferSurfaceTargetsFromFeature(feature);
+    const diffFiles = changedFiles.filter(isFrontendPath);
+    const metadataEvidence = metadataRoutes.length > 0 ||
+        metadataSurfaces.length > 0 ||
+        feature.execution_kind === 'frontend_coverage' ||
+        feature.touches.includes('frontend');
+    const sources = [];
+    if (metadataEvidence)
+        sources.push('metadata');
+    if (diffFiles.length > 0)
+        sources.push('diff');
+    return {
+        metadata_routes: metadataRoutes,
+        metadata_surfaces: metadataSurfaces,
+        diff_files: diffFiles,
+        evidence_sources: sources,
+        has_frontend_evidence: sources.length > 0,
+    };
+}
+export function ensureRouteInFrontendMap(snapshot, routePath, gapId) {
+    if (!snapshot.frontendMap)
+        return;
+    const routeId = `route-${slugify(routePath) || 'root'}`;
+    const existing = snapshot.frontendMap.routes.find((route) => route.id === routeId);
+    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 || []), gapId]));
+        return;
+    }
+    snapshot.frontendMap.routes.push({
+        id: routeId,
+        path: routePath,
+        parent_id: '',
+        label: '',
+        nav_surface: '',
+        ui_status: 'GAP',
+        source_gap_ids: [gapId],
+        implemented_files: [],
+        notes: '',
+    });
+}
+export async function maybeCreateAutomaticFrontendGap(paths, snapshot, feature, options) {
+    if (!snapshot.frontendGaps || !snapshot.frontendMap)
+        return '';
+    if (feature.frontend_gap_refs.length > 0)
+        return '';
+    const backendImpact = feature.touches.includes('backend') ||
+        feature.execution_kind === 'feature' ||
+        feature.execution_kind === 'migration';
+    if (!backendImpact && !options?.force)
+        return '';
+    const gapId = await allocateEntityId(paths, 'FGAP');
+    syncCounterFromId(snapshot.discoveryIndex, gapId);
+    const now = nowIso();
+    const routeTargets = Array.from(new Set([...(options?.routeTargets || []), ...inferRouteTargetsFromFeature(feature)]));
+    snapshot.frontendGaps.items.push({
+        id: gapId,
+        title: `Cobertura frontend pendente para ${feature.id}: ${feature.title}`,
+        status: 'OPEN',
+        origin_kind: 'automatic',
+        detection_sources: options?.detectionSources || ['metadata'],
+        origin_feature: feature.id,
+        backend_refs: [feature.id],
+        frontend_scope: '',
+        route_targets: routeTargets,
+        menu_targets: [],
+        suggested_files: [],
+        implemented_files: [],
+        resolved_by_feature: '',
+        related_route_ids: routeTargets.map((route) => `route-${slugify(route) || 'root'}`),
+        notes: 'Gerado automaticamente no finalize para evitar perda de rastreabilidade.',
+        created_at: now,
+        updated_at: now,
+    });
+    feature.frontend_gap_refs = Array.from(new Set([...feature.frontend_gap_refs, gapId]));
+    feature.summary = [feature.summary || '', `FGAP automático criado: ${gapId}`]
+        .filter(Boolean)
+        .join('\n');
+    for (const routePath of routeTargets) {
+        ensureRouteInFrontendMap(snapshot, routePath, gapId);
+    }
+    return gapId;
+}
+export function resolveRoutedSkills(snapshot, touches) {
+    const knownSkills = new Set((snapshot.skillCatalog?.skills || []).map((skill) => skill.id));
+    let injectedSkills = [];
+    if (touches.length > 0 && snapshot.skillRouting && snapshot.skillRouting.routes) {
+        for (const touch of touches) {
+            const route = snapshot.skillRouting.routes.find((r) => r.domain === touch);
+            if (route && route.skills) {
+                injectedSkills.push(...route.skills);
+            }
+        }
+    }
+    if (injectedSkills.length === 0 && snapshot.skillRouting && snapshot.skillRouting.default_skills) {
+        injectedSkills = [...snapshot.skillRouting.default_skills];
+    }
+    // fallback extremo
+    if (injectedSkills.length === 0) {
+        injectedSkills = ['architecture', 'concise-planning', 'context-window-management'];
+    }
+    const validSkills = Array.from(new Set(injectedSkills)).filter((skillId) => knownSkills.has(skillId));
+    if (validSkills.length > 0) {
+        return validSkills.slice(0, 5);
+    }
+    const canonicalFallback = ['architecture', 'concise-planning', 'context-window-management'].filter((skillId) => knownSkills.has(skillId));
+    return canonicalFallback.slice(0, 5);
+}
+export function inferOriginType(input) {
+    if (/^(?:RAD|EPIC)-\d{3,}$/.test(input))
+        return 'epic';
+    if (/^FGAP-\d{3,}$/.test(input))
+        return 'frontend_gap';
+    if (/^TD-\d{3,}$/.test(input))
+        return 'tech_debt';
+    return 'direct';
+}
+export async function buildFinalizeQueue(paths, backlogItems, queueItems) {
+    const queueByFeature = new Map(queueItems.map((item) => [item.feature_id, item]));
+    const archiveRoot = resolveOpenSpecSubpath(paths.projectRoot, 'changes', 'archive');
+    for (const item of backlogItems) {
+        if (!item.change_name)
+            continue;
+        if (item.status === 'DONE')
+            continue;
+        const archivedPath = path.join(archiveRoot, item.change_name);
+        const archived = await fs
+            .access(archivedPath)
+            .then(() => true)
+            .catch(() => false);
+        if (!archived)
+            continue;
+        if (!queueByFeature.has(item.id)) {
+            queueByFeature.set(item.id, {
+                feature_id: item.id,
+                status: 'PENDING',
+                summary: `Consolidar memoria da ${item.id} (${item.change_name})`,
+                created_at: nowIso(),
+                completed_at: '',
+            });
+        }
+        if (item.status === 'ARCHIVED') {
+            item.archived_at = item.archived_at || nowIso();
+        }
+    }
+    return Array.from(queueByFeature.values()).sort((a, b) => a.feature_id.localeCompare(b.feature_id));
+}
+export async function evaluateFeatureQuality(paths, config, feature) {
+    const contract = feature.quality_contract;
+    if (!contract || contract.enabled === false) {
+        return {
+            ok: false,
+            blocking: true,
+            reasons: ['quality_contract missing or disabled'],
+            artifact: '',
+        };
+    }
+    const names = activeDocNamesForLayout(config);
+    const activePath = path.join(paths.activeDir, feature.id);
+    const artifactName = [names.quality, ...activeDocCandidateNames(config)].find((name) => (name === '5-quality.yaml' || name === 'quality.md') && existsSync(path.join(activePath, name))) || names.quality;
+    const artifactPath = path.join(activePath, artifactName);
+    const content = await fs.readFile(artifactPath, 'utf-8').catch(() => '');
+    const reasons = [];
+    if (!content.trim()) {
+        reasons.push(`quality artifact missing: ${relProjectPath(paths, artifactPath)}`);
+    }
+    if (contract.unit_target_percent < 95 && contract.exceptions.length === 0) {
+        reasons.push('unit target below 95% without formal exception');
+    }
+    if (contract.integration_target_percent < 95 && contract.exceptions.length === 0) {
+        reasons.push('integration/e2e target below 95% without formal exception');
+    }
+    if (contract.required_axes.length === 0) {
+        reasons.push('required quality axes missing');
+    }
+    if (contract.required_evidence.length === 0 && contract.exceptions.length === 0) {
+        reasons.push('required evidence missing without formal exception');
+    }
+    return {
+        ok: reasons.length === 0,
+        blocking: contract.enforcement === 'blocking' && contract.exceptions.length === 0,
+        reasons,
+        artifact: relProjectPath(paths, artifactPath),
+    };
+}
+export function buildAdrMarkdown(feature, unlocked, timestamp) {
+    const refs = [feature.id, feature.origin_ref].filter(Boolean).join(', ') || '-';
+    return `# ADR ${feature.id}
+
+## Context
+- Feature: ${feature.id} - ${feature.title}
+- Origin: ${feature.origin_type}${feature.origin_ref ? ` (${feature.origin_ref})` : ''}
+- Finalized at: ${timestamp}
+
+## Decision
+Consolidate feature ${feature.id} and make the result official in SDD memory.
+
+## Changes
+- Associated change: ${feature.change_name || '-'}
+- Execution type: ${feature.execution_kind}
+- Planning mode: ${feature.planning_mode}
+- Lock domains: ${feature.lock_domains.length > 0 ? feature.lock_domains.join(', ') : '-'}
+
+## Consequences
+- Residual risk documented in feature summary: ${feature.summary || '-'}
+
+## Released Dependents
+${unlocked.length > 0 ? unlocked.map((id) => `- ${id}`).join('\n') : '- None'}
+
+## References
+- ${refs}
+`;
+}
+export function applyLoggedTransition(transitionLog, entityType, entity, toStatus, options) {
+    TransitionEngine.assertValid(entityType, entity.status, toStatus, {
+        forceTransition: options.forceTransition,
+        lensViolations: options.lensViolations,
+    });
+    const fromStatus = entity.status;
+    entity.status = toStatus;
+    transitionLog.push({
+        timestamp: options.timestamp || new Date().toISOString(),
+        entity_type: entityType,
+        entity_id: entity.id,
+        from: fromStatus,
+        to: toStatus,
+        actor: options.actor || 'system',
+        reason: options.reason || '',
+        source_command: options.sourceCommand || '',
+        force_transition: options.forceTransition || false,
+        lens_violations: options.lensViolations || [],
+    });
+    if (options.afterTransition) {
+        options.afterTransition(entity);
+    }
+}
+export function gateSatisfied(status) {
+    return status === 'aprovada' || status === 'nao_exigida';
+}
+export function detectContextType(ref) {
+    if (/^FEAT-\d{3,}$/.test(ref))
+        return 'FEAT';
+    if (/^EPIC-\d{3,}$/.test(ref))
+        return 'EPIC';
+    if (/^RAD-\d{3,}$/.test(ref))
+        return 'RAD';
+    if (/^FGAP-\d{3,}$/.test(ref))
+        return 'FGAP';
+    if (/^TD-\d{3,}$/.test(ref))
+        return 'TD';
+    return null;
+}
+export async function pathExists(targetPath) {
+    try {
+        await fs.access(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function listAdrRefs(paths, refs) {
+    const adrDir = path.join(paths.coreDir, 'adrs');
+    const entries = await fs.readdir(adrDir).catch(() => []);
+    const normalized = refs.filter(Boolean);
+    return entries
+        .filter((name) => name.endsWith('.md'))
+        .filter((name) => normalized.some((ref) => name.includes(ref)))
+        .map((name) => relProjectPath(paths, path.join(adrDir, name)))
+        .sort();
+}
+export function computeReadyFeatures(items, options) {
+    return computeReadyFeatureWaves(items, { rank: options?.rank || 'impact', maxAgents: options?.maxAgents });
+}
+const SESSION_TEMP_SENSITIVE_SEGMENTS = ['.env', 'secrets', 'secret', 'credentials', 'token', '.aws', '.ssh', 'id_rsa', 'pem'];
+export function buildSessionStateFingerprint(items) {
+    const normalized = items
+        .map((item) => ({
+        id: item.id,
+        status: item.status,
+        blocked_by: [...item.blocked_by].sort(),
+        lock_domains: [...item.lock_domains].sort(),
+        parallel_group: item.parallel_group || '',
+        dependency_count: item.dependency_count,
+        change_name: item.change_name || '',
+        start_commit_sha: item.start_commit_sha || '',
+    }))
+        .sort((a, b) => a.id.localeCompare(b.id));
+    const payload = JSON.stringify(normalized);
+    return createHash('sha1').update(payload).digest('hex');
+}
+export function buildSessionManifest(featureId, projectRoot, items) {
+    const activeFeatureIds = items.filter((item) => item.status === 'IN_PROGRESS').map((item) => item.id).sort();
+    return {
+        version: 1,
+        feature_id: featureId,
+        project_root: projectRoot,
+        created_at: nowIso(),
+        state_fingerprint: buildSessionStateFingerprint(items),
+        active_feature_ids: activeFeatureIds,
+        lock_domain_snapshot: Array.from(new Set(items.flatMap((item) => item.lock_domains))).sort(),
+    };
+}
+export function isSessionPackStale(manifest, items) {
+    const reasons = [];
+    const currentFingerprint = buildSessionStateFingerprint(items);
+    if (manifest.state_fingerprint !== currentFingerprint) {
+        reasons.push('state_fingerprint mismatch');
+    }
+    const active = items
+        .filter((item) => item.status === 'IN_PROGRESS')
+        .map((item) => item.id)
+        .sort();
+    if (manifest.active_feature_ids.join(',') !== active.join(',')) {
+        reasons.push('active_feature_ids mismatch');
+    }
+    return { stale: reasons.length > 0, reasons };
+}
+export function isSafeSessionTempPath(projectRoot, candidatePath) {
+    const resolvedRoot = path.resolve(projectRoot);
+    const resolvedCandidate = path.resolve(candidatePath);
+    const relative = path.relative(resolvedRoot, resolvedCandidate);
+    const inside = relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+    if (!inside)
+        return false;
+    const lowerCandidate = resolvedCandidate.toLowerCase();
+    const hasSensitiveSegment = SESSION_TEMP_SENSITIVE_SEGMENTS.some((segment) => lowerCandidate.includes(`/${segment.toLowerCase()}/`) || lowerCandidate.endsWith(`/${segment.toLowerCase()}`));
+    return !hasSensitiveSegment;
+}
+export async function cleanupSessionPath(sessionRoot, candidatePath) {
+    if (!isSafeSessionTempPath(sessionRoot, candidatePath)) {
+        return {
+            removed: false,
+            already_absent: false,
+            reason: 'caminho fora da raiz do projeto ou padrao sensível detectado',
+        };
+    }
+    const exists = await fs
+        .access(candidatePath)
+        .then(() => true)
+        .catch(() => false);
+    if (!exists) {
+        return { removed: false, already_absent: true, reason: 'ja inexistente' };
+    }
+    await fs.rm(candidatePath, { recursive: true, force: true });
+    return { removed: true, already_absent: false, reason: 'removido' };
+}
+export function computeReadyFeatureWaves(items, options) {
+    const rank = options?.rank || 'impact';
+    const requestedAgents = typeof options?.maxAgents === 'number' && Number.isFinite(options.maxAgents)
+        ? Math.floor(options.maxAgents)
+        : undefined;
+    const maxAgents = typeof requestedAgents === 'number' && requestedAgents > 0 ? requestedAgents : Number.MAX_SAFE_INTEGER;
+    const byId = new Map(items.map((item) => [item.id, item]));
+    const dependentsMap = buildDependentsMap(items);
+    const blocked = [];
+    const conflicts = [];
+    const deferred = [];
+    const candidateById = new Map();
+    const blockedByReasons = new Map();
+    const readyLikeStates = new Set(['READY', 'SYNC_REQUIRED', 'VERIFY_FAILED']);
+    for (const item of items) {
+        if (item.status === 'DONE' || item.status === 'ARCHIVED')
+            continue;
+        const unresolvedDeps = item.blocked_by.filter((depId) => {
+            const dep = byId.get(depId);
+            return !dep || dep.status !== 'DONE';
+        });
+        if (item.status === 'BLOCKED' || unresolvedDeps.length > 0) {
+            blocked.push(item);
+            const reasons = [`blocked_by=${unresolvedDeps.join(',') || 'pending'}`];
+            blockedByReasons.set(item.id, reasons);
+            continue;
+        }
+        if (!readyLikeStates.has(item.status)) {
+            continue;
+        }
+        const activeConflicts = lockConflictWithActive(item, items);
+        if (activeConflicts.length > 0) {
+            const reasons = [`active_lock_conflict=${activeConflicts.join(',')}`];
+            blockedByReasons.set(item.id, reasons);
+            conflicts.push(item);
+            continue;
+        }
+        const scored = scoreReadyItem(item, items, dependentsMap, rank);
+        candidateById.set(item.id, {
+            item,
+            score: scored.score,
+            score_reasons: scored.reasons,
+            deferredReasons: [...scored.reasons],
+            readinessBlockers: [],
+        });
+    }
+    const candidates = Array.from(candidateById.values()).sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        return extractFeatureNumber(a.item.id) - extractFeatureNumber(b.item.id);
+    });
+    const waves = [];
+    const remaining = [...candidates];
+    while (remaining.length > 0) {
+        const wave = [];
+        const waveLocks = new Map();
+        const selectedFeatureIds = new Set();
+        let picked = false;
+        for (const candidate of remaining) {
+            const reasoned = candidate;
+            if (wave.length >= maxAgents) {
+                reasoned.readinessBlockers.push(`max_agents=${maxAgents} atingiu limite da onda`);
+                deferred.push({ id: reasoned.item.id, reasons: [...reasoned.readinessBlockers] });
+                continue;
+            }
+            const lockConflicts = candidate.item.lock_domains.filter((lockDomain) => waveLocks.has(lockDomain));
+            if (lockConflicts.length > 0) {
+                const blockerIds = new Set();
+                for (const lockDomain of lockConflicts) {
+                    const owners = waveLocks.get(lockDomain) || [];
+                    for (const owner of owners)
+                        blockerIds.add(owner);
+                }
+                reasoned.readinessBlockers.push(`lock_conflict_wave=(${Array.from(blockerIds).join(',') || 'sem-owner'})`);
+                deferred.push({ id: reasoned.item.id, reasons: [...reasoned.readinessBlockers] });
+                continue;
+            }
+            wave.push(reasoned);
+            picked = true;
+            selectedFeatureIds.add(reasoned.item.id);
+            for (const lockDomain of reasoned.item.lock_domains) {
+                const owners = waveLocks.get(lockDomain) || [];
+                owners.push(reasoned.item.id);
+                waveLocks.set(lockDomain, owners);
+            }
+        }
+        if (!picked) {
+            const fallback = remaining.shift();
+            if (!fallback)
+                break;
+            waves.push([fallback.item.id]);
+            continue;
+        }
+        const selectedIds = new Set(wave.map((entry) => entry.item.id));
+        waves.push(wave.map((entry) => entry.item.id));
+        for (let index = remaining.length - 1; index >= 0; index -= 1) {
+            if (selectedIds.has(remaining[index].item.id)) {
+                remaining.splice(index, 1);
+            }
+        }
+    }
+    const readyIds = new Set(waves[0] || []);
+    const ready = candidates
+        .filter((entry) => readyIds.has(entry.item.id))
+        .map((entry) => entry.item);
+    if (ready.length > 0) {
+        ready.sort((a, b) => extractFeatureNumber(a.id) - extractFeatureNumber(b.id));
+    }
+    const deferredMap = new Map();
+    for (const entry of candidateById.values()) {
+        if (!readyIds.has(entry.item.id)) {
+            const reasons = [
+                ...(entry.readinessBlockers.length > 0 ? entry.readinessBlockers : ['deferred_by_wave']),
+            ];
+            deferredMap.set(entry.item.id, reasons);
+        }
+    }
+    for (const [id, reasons] of deferredMap) {
+        if (!blockedByReasons.has(id)) {
+            deferred.push({ id, reasons });
+        }
+    }
+    const conflictReasonsSet = new Set(deferred.map((item) => item.id));
+    for (const entry of blockedByReasons.entries()) {
+        const [id] = entry;
+        if (conflictReasonsSet.has(id) && !blocked.find((item) => item.id === id)) {
+            const item = byId.get(id);
+            if (item) {
+                conflicts.push(item);
+            }
+        }
+    }
+    return {
+        ready,
+        blocked,
+        conflicts: conflicts.filter((value, index, all) => index === all.findIndex((entry) => entry.id === value.id)),
+        waves,
+        deferred: Array.from(new Map(deferred.map((entry) => [entry.id, entry])).values()).filter((entry) => !readyIds.has(entry.id)),
+    };
+}
+export function extractFeatureNumber(featureId) {
+    const value = Number(featureId.split('-')[1]);
+    return Number.isFinite(value) ? value : Number.MAX_SAFE_INTEGER;
+}
+export function buildDependentsMap(items) {
+    const dependents = new Map();
+    for (const item of items) {
+        for (const dep of item.blocked_by) {
+            const list = dependents.get(dep) || [];
+            list.push(item.id);
+            dependents.set(dep, list);
+        }
+    }
+    return dependents;
+}
+export function countIndirectDependents(featureId, dependentsMap) {
+    const directSet = new Set(dependentsMap.get(featureId) || []);
+    const visited = new Set([featureId]);
+    const queue = [...directSet];
+    for (const id of queue)
+        visited.add(id);
+    while (queue.length > 0) {
+        const current = queue.shift();
+        const next = dependentsMap.get(current) || [];
+        for (const candidate of next) {
+            if (visited.has(candidate))
+                continue;
+            visited.add(candidate);
+            queue.push(candidate);
+        }
+    }
+    return {
+        direct: directSet.size,
+        indirect: Math.max(0, visited.size - 1 - directSet.size),
+    };
+}
+export function lockCriticality(lockDomains) {
+    if (lockDomains.length === 0)
+        return 0;
+    const weights = {
+        'auth-rules': 3,
+        payment: 3,
+        'schema-change': 3,
+    };
+    let total = 0;
+    for (const lock of lockDomains) {
+        total += weights[lock] ?? 1;
+    }
+    return total;
+}
+export function lockConflictRisk(item, items) {
+    if (item.lock_domains.length === 0)
+        return 0;
+    let risk = 0;
+    for (const other of items) {
+        if (other.id === item.id)
+            continue;
+        if (other.status !== 'IN_PROGRESS')
+            continue;
+        if (intersects(item.lock_domains, other.lock_domains)) {
+            risk++;
+        }
+    }
+    return risk;
+}
+export function scoreReadyItem(item, items, dependentsMap, rank) {
+    const { direct, indirect } = countIndirectDependents(item.id, dependentsMap);
+    const criticality = lockCriticality(item.lock_domains);
+    const conflictRisk = lockConflictRisk(item, items);
+    if (rank === 'fifo') {
+        const score = 1_000_000 - extractFeatureNumber(item.id);
+        return {
+            score,
+            reasons: ['ordem FIFO por numero da feature'],
+        };
+    }
+    if (rank === 'criticality') {
+        const score = criticality * 5 + direct * 2 + indirect - conflictRisk;
+        return {
+            score,
+            reasons: [
+                `criticidade_lock=${criticality}`,
+                `dependentes_diretos=${direct}`,
+                `dependentes_indiretos=${indirect}`,
+                `risco_conflito=${conflictRisk}`,
+            ],
+        };
+    }
+    const score = direct * 5 + indirect * 3 + criticality * 2 - conflictRisk;
+    return {
+        score,
+        reasons: [
+            `dependentes_diretos=${direct}`,
+            `dependentes_indiretos=${indirect}`,
+            `criticidade_lock=${criticality}`,
+            `risco_conflito=${conflictRisk}`,
+        ],
+    };
+}
+export function buildCuratedSkillContent(entry) {
+    const builtInSkill = BUILT_IN_SDD_SKILLS[entry.id];
+    if (typeof builtInSkill === 'string') {
+        return builtInSkill;
+    }
+    if (builtInSkill && typeof builtInSkill === 'object' && !('kind' in builtInSkill)) {
+        const markdown = builtInSkill['SKILL.md'];
+        if (typeof markdown === 'string' && markdown.trim().length > 0) {
+            return markdown;
+        }
+    }
+    const domainLine = entry.domains.length > 0 ? entry.domains.join(', ') : 'geral';
+    const phaseLine = entry.phases.length > 0 ? entry.phases.join(', ') : 'all';
+    return `---
+name: ${entry.id}
+description: ${entry.description || entry.title}
+---
+
+# ${entry.title}
+
+## Contexto
+- Dominios: ${domainLine}
+- Fases: ${phaseLine}
+
+## Instrucoes
+${entry.description || 'Aplicar esta skill como apoio especializado durante o planejamento e execucao.'}
+`;
+}
+export async function resolveSkillFileRef(paths, skillId) {
+    const candidates = [
+        path.join(paths.skillsCuratedDir, skillId, 'SKILL.md'),
+        path.join(paths.skillsCuratedDir, `sdd-curated-${skillId}`, 'SKILL.md'),
+        path.join(paths.skillsDir, 'curated', skillId, 'SKILL.md'),
+        path.join(paths.skillsDir, 'curated', `sdd-curated-${skillId}`, 'SKILL.md'),
+    ];
+    for (const candidate of candidates) {
+        if (await pathExists(candidate)) {
+            return relProjectPath(paths, candidate);
+        }
+    }
+    return relProjectPath(paths, path.join(paths.skillsCuratedDir, skillId, 'SKILL.md'));
+}
+export function buildSkillInvocationPrompt(input) {
+    const headerObjective = input.objective?.trim()
+        ? `Objetivo: ${input.objective.trim()}`
+        : 'Objetivo: executar a tarefa usando as skills selecionadas.';
+    const refLine = input.ref ? `Contexto de referencia: ${input.ref}` : '';
+    const skillsLines = input.skills
+        .map((skill, index) => `${index + 1}. ${skill.id} (${skill.path})${skill.reason ? ` - ${skill.reason}` : ''}`)
+        .join('\n');
+    return `Use as skills abaixo nesta ordem e execute a tarefa com rastreabilidade:
+
+${headerObjective}
+${refLine}
+
+Skills obrigatorias:
+${skillsLines}
+
+Regras:
+1. Cite as skills que esta aplicando no inicio da resposta.
+2. Siga a ordem definida acima.
+3. Se faltar contexto, consulte primeiro o estado canônico em .sdd/state/*.yaml.
+4. Finalize com proximos comandos OpenSDD recomendados.`;
+}
+//# sourceMappingURL=legacy-operations.js.map