@devtrack-solution/codesdd 1.2.2

package/dist/core/sdd/state.js

@@ -0,0 +1,1000 @@
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { resolveOpenSpecLiveSubpath } from './services/legacy-capability.service.js';
+import { ArchitectureStateSchema, BacklogStateSchema, DiscoveryIndexStateSchema, FinalizeQueueStateSchema, IntegrationContractsStateSchema, FrontendDecisionsStateSchema, UnblockEventsStateSchema, TransitionLogStateSchema, AuditHistoryStateSchema, FrontendGapsStateSchema, FrontendMapStateSchema, RepoMapStateSchema, SourceIndexStateSchema, SkillCatalogStateSchema, SkillRoutingStateSchema, ServiceCatalogStateSchema, TechStackStateSchema, TechDebtStateSchema, NamingContractStateSchema, } from './types.js';
+import { CLI_NAME } from '../branding.js';
+import { DEFAULT_CURATED_SKILL_CATALOG, BUILT_IN_SDD_SKILLS, buildCuratedBundlesMarkdown, } from './default-skills.js';
+import { buildSddInternalReadme, PROMPT_00_COMECE_POR_AQUI_MD, PROMPT_01_INGESTAO_DEPOSITO_MD, PROMPT_02_NORMALIZAR_PLANEJAMENTO_MD, PROMPT_03_EXECUCAO_FEATURE_MD, PROMPT_04_CONSOLIDACAO_FINALIZE_MD, PROMPTS_README_MD, TEMPLATE_1_SPEC_MD, TEMPLATE_2_PLAN_MD, TEMPLATE_QUALITY_MD, TEMPLATE_3_TASKS_MD, TEMPLATE_4_CHANGELOG_MD, } from './default-bootstrap-files.js';
+import { SddWriteTransaction } from './transaction.js';
+const LEGACY_LAYOUT_FOLDERS = {
+    discovery: 'discovery',
+    planning: 'pendencias',
+    skills: 'skills',
+    templates: 'templates',
+    deposito: 'deposito',
+    planned: 'planned',
+    active: 'active',
+    archived: 'archived',
+};
+const EN_US_LAYOUT_FOLDERS = {
+    discovery: 'discovery',
+    planning: 'planning',
+    skills: 'skills',
+    templates: 'templates',
+    deposito: 'sources',
+    planned: 'planned',
+    active: 'active',
+    archived: 'archived',
+};
+const PT_BR_LAYOUT_FOLDERS = {
+    discovery: 'descoberta',
+    planning: 'planejamento',
+    skills: 'habilidades',
+    templates: 'modelos',
+    deposito: 'deposito',
+    planned: 'planejados',
+    active: 'execucao',
+    archived: 'arquivados',
+};
+function skillSubfoldersForLayout(layout) {
+    if (layout === 'pt-BR') {
+        return { curated: 'skills', bundles: 'pacotes' };
+    }
+    return { curated: 'curated', bundles: 'bundles' };
+}
+function defaultFoldersForLayout(layout) {
+    if (layout === 'pt-BR') {
+        return { ...PT_BR_LAYOUT_FOLDERS };
+    }
+    if (layout === 'en-US') {
+        return { ...EN_US_LAYOUT_FOLDERS };
+    }
+    return { ...LEGACY_LAYOUT_FOLDERS };
+}
+const DEFAULT_SDD_CONFIG = {
+    enabled: true,
+    memoryDir: '.sdd',
+    language: 'pt-BR',
+    layout: 'legacy',
+    folders: defaultFoldersForLayout('legacy'),
+    frontend: { enabled: false },
+    views: { autoRender: true },
+};
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../');
+const CANONICAL_FOLDER_OPTIONS = {
+    'en-US': {
+        discovery: ['discovery'],
+        planning: ['planning'],
+        skills: ['skills'],
+        templates: ['templates'],
+        deposito: ['sources'],
+        planned: ['planned'],
+        active: ['active'],
+        archived: ['archived'],
+    },
+    legacy: {
+        discovery: ['discovery'],
+        planning: ['pendencias'],
+        skills: ['skills'],
+        templates: ['templates'],
+        deposito: ['deposito'],
+        planned: ['planned'],
+        active: ['active'],
+        archived: ['archived'],
+    },
+    'pt-BR': {
+        discovery: ['descoberta'],
+        planning: ['planejamento'],
+        skills: ['habilidades'],
+        templates: ['modelos'],
+        deposito: ['deposito'],
+        planned: ['planejados'],
+        active: ['execucao'],
+        archived: ['arquivados'],
+    },
+};
+function isRecord(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+function mergeRuntimeConfig(raw) {
+    if (!isRecord(raw)) {
+        return {
+            ...DEFAULT_SDD_CONFIG,
+            folders: { ...DEFAULT_SDD_CONFIG.folders },
+            frontend: { enabled: false },
+            views: { autoRender: true },
+        };
+    }
+    const frontend = isRecord(raw.frontend) ? raw.frontend : {};
+    const views = isRecord(raw.views) ? raw.views : {};
+    const language = raw.language === 'en-US' ? 'en-US' : 'pt-BR';
+    const layout = raw.layout === 'pt-BR' ? 'pt-BR' : raw.layout === 'en-US' ? 'en-US' : 'legacy';
+    const folderDefaults = defaultFoldersForLayout(layout);
+    const rawFolders = isRecord(raw.folders) ? raw.folders : {};
+    // compatibilidade retroativa para nome legado "pendencias"
+    const legacyPlanning = typeof rawFolders.pendencias === 'string' && rawFolders.pendencias.trim().length > 0
+        ? rawFolders.pendencias.trim()
+        : '';
+    const planningFolder = typeof rawFolders.planning === 'string' && rawFolders.planning.trim().length > 0
+        ? rawFolders.planning.trim()
+        : legacyPlanning || folderDefaults.planning;
+    return {
+        enabled: typeof raw.enabled === 'boolean' ? raw.enabled : DEFAULT_SDD_CONFIG.enabled,
+        memoryDir: typeof raw.memoryDir === 'string' && raw.memoryDir.trim().length > 0
+            ? raw.memoryDir.trim()
+            : DEFAULT_SDD_CONFIG.memoryDir,
+        language,
+        layout,
+        folders: {
+            discovery: typeof rawFolders.discovery === 'string' && rawFolders.discovery.trim().length > 0
+                ? rawFolders.discovery.trim()
+                : folderDefaults.discovery,
+            planning: planningFolder,
+            skills: typeof rawFolders.skills === 'string' && rawFolders.skills.trim().length > 0
+                ? rawFolders.skills.trim()
+                : folderDefaults.skills,
+            templates: typeof rawFolders.templates === 'string' && rawFolders.templates.trim().length > 0
+                ? rawFolders.templates.trim()
+                : folderDefaults.templates,
+            deposito: typeof rawFolders.deposito === 'string' && rawFolders.deposito.trim().length > 0
+                ? rawFolders.deposito.trim()
+                : folderDefaults.deposito,
+            planned: typeof rawFolders.planned === 'string' && rawFolders.planned.trim().length > 0
+                ? rawFolders.planned.trim()
+                : folderDefaults.planned,
+            active: typeof rawFolders.active === 'string' && rawFolders.active.trim().length > 0
+                ? rawFolders.active.trim()
+                : folderDefaults.active,
+            archived: typeof rawFolders.archived === 'string' && rawFolders.archived.trim().length > 0
+                ? rawFolders.archived.trim()
+                : folderDefaults.archived,
+        },
+        frontend: {
+            enabled: typeof frontend.enabled === 'boolean'
+                ? frontend.enabled
+                : DEFAULT_SDD_CONFIG.frontend.enabled,
+        },
+        views: {
+            autoRender: typeof views.autoRender === 'boolean'
+                ? views.autoRender
+                : DEFAULT_SDD_CONFIG.views.autoRender,
+        },
+    };
+}
+function validateRuntimeConfig(config) {
+    const allowed = CANONICAL_FOLDER_OPTIONS[config.layout];
+    const invalidEntries = Object.entries(config.folders).flatMap(([key, value]) => {
+        const folderKey = key;
+        const accepted = allowed[folderKey];
+        if (!accepted)
+            throw new Error("Missing allowed for key: " + folderKey + " value: " + value + " allowed: " + JSON.stringify(allowed));
+        if (accepted.includes(value)) {
+            return [];
+        }
+        return [`${folderKey}="${value}" (permitidos: ${accepted.join(', ')})`];
+    });
+    if (invalidEntries.length > 0) {
+        throw new Error(`Configuracao SDD invalida em .sdd/config.yaml: folders fora do canonico para layout ${config.layout}: ${invalidEntries.join('; ')}`);
+    }
+}
+function defaultRuntimeConfig() {
+    return {
+        ...DEFAULT_SDD_CONFIG,
+        folders: { ...DEFAULT_SDD_CONFIG.folders },
+        frontend: { enabled: DEFAULT_SDD_CONFIG.frontend.enabled },
+        views: { autoRender: DEFAULT_SDD_CONFIG.views.autoRender },
+    };
+}
+async function fileExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function ensureDir(dirPath) {
+    await fs.mkdir(dirPath, { recursive: true });
+}
+async function firstExistingFile(paths) {
+    for (const filePath of paths) {
+        if (await fileExists(filePath)) {
+            return filePath;
+        }
+    }
+    return null;
+}
+async function readYamlObject(filePath) {
+    const parsed = parseYaml(await fs.readFile(filePath, 'utf-8'));
+    return isRecord(parsed) ? parsed : {};
+}
+function buildSddConfigDocument(existing, config) {
+    const next = { ...existing };
+    delete next.sdd;
+    next.version = typeof next.version === 'number' ? next.version : 1;
+    next.state_version = typeof next.state_version === 'number' ? next.state_version : 2;
+    next.generatedBy =
+        typeof next.generatedBy === 'string' && !next.generatedBy.startsWith('openspec ')
+            ? next.generatedBy
+            : `${CLI_NAME} sdd init`;
+    next.meta_evolution = isRecord(next.meta_evolution)
+        ? next.meta_evolution
+        : {
+            enabled: true,
+            audit_interval_days: 180,
+            placeholder_markers: ['(fill in', '(placeholder', 'TODO:', 'TBD:'],
+            health_alert_threshold: 75,
+        };
+    next.language = config.language;
+    next.enabled = config.enabled;
+    next.memoryDir = config.memoryDir;
+    next.layout = config.layout;
+    next.folders = { ...config.folders };
+    next.frontend = { enabled: config.frontend.enabled };
+    next.views = { autoRender: config.views.autoRender };
+    return next;
+}
+async function removeSddRuntimeConfigFromOpenSpecConfig(projectRoot) {
+    const legacyConfigPath = await firstExistingFile([
+        resolveOpenSpecLiveSubpath(projectRoot, 'config.yaml'),
+        resolveOpenSpecLiveSubpath(projectRoot, 'config.yml'),
+    ]);
+    if (!legacyConfigPath) {
+        return;
+    }
+    const legacyRoot = await readYamlObject(legacyConfigPath);
+    if (!Object.prototype.hasOwnProperty.call(legacyRoot, 'sdd')) {
+        return;
+    }
+    delete legacyRoot.sdd;
+    await fs.writeFile(legacyConfigPath, stringifyYaml(legacyRoot), 'utf-8');
+}
+export async function loadProjectSddConfig(projectRoot) {
+    const configPath = await firstExistingFile([
+        path.join(projectRoot, DEFAULT_SDD_CONFIG.memoryDir, 'config.yaml'),
+        path.join(projectRoot, DEFAULT_SDD_CONFIG.memoryDir, 'config.yml'),
+    ]);
+    if (configPath) {
+        const config = mergeRuntimeConfig(await readYamlObject(configPath));
+        validateRuntimeConfig(config);
+        return config;
+    }
+    const legacyConfigPath = await firstExistingFile([
+        resolveOpenSpecLiveSubpath(projectRoot, 'config.yaml'),
+        resolveOpenSpecLiveSubpath(projectRoot, 'config.yml'),
+    ]);
+    if (legacyConfigPath) {
+        const legacyRoot = await readYamlObject(legacyConfigPath);
+        const config = mergeRuntimeConfig(legacyRoot.sdd);
+        validateRuntimeConfig(config);
+        return config;
+    }
+    const config = defaultRuntimeConfig();
+    validateRuntimeConfig(config);
+    return config;
+}
+export async function upsertProjectSddConfig(projectRoot, overrides) {
+    const sddDir = path.join(projectRoot, DEFAULT_SDD_CONFIG.memoryDir);
+    await ensureDir(sddDir);
+    const configPath = (await firstExistingFile([
+        path.join(sddDir, 'config.yaml'),
+        path.join(sddDir, 'config.yml'),
+    ])) ?? path.join(sddDir, 'config.yaml');
+    let rootConfig = {};
+    if (await fileExists(configPath)) {
+        rootConfig = await readYamlObject(configPath);
+    }
+    else {
+        const legacyConfigPath = await firstExistingFile([
+            resolveOpenSpecLiveSubpath(projectRoot, 'config.yaml'),
+            resolveOpenSpecLiveSubpath(projectRoot, 'config.yml'),
+        ]);
+        if (legacyConfigPath) {
+            const legacyRoot = await readYamlObject(legacyConfigPath);
+            rootConfig = isRecord(legacyRoot.sdd) ? legacyRoot.sdd : {};
+        }
+    }
+    const mergedSdd = mergeRuntimeConfig(rootConfig);
+    if (overrides?.frontendEnabled !== undefined) {
+        mergedSdd.frontend.enabled = overrides.frontendEnabled;
+    }
+    if (overrides?.language) {
+        mergedSdd.language = overrides.language;
+    }
+    if (overrides?.layout) {
+        mergedSdd.layout = overrides.layout;
+        mergedSdd.folders = defaultFoldersForLayout(overrides.layout);
+    }
+    validateRuntimeConfig(mergedSdd);
+    await fs.writeFile(configPath, stringifyYaml(buildSddConfigDocument(rootConfig, mergedSdd)), 'utf-8');
+    await removeSddRuntimeConfigFromOpenSpecConfig(projectRoot);
+    return mergedSdd;
+}
+export function resolveSddPaths(projectRoot, config) {
+    const memoryRoot = path.resolve(projectRoot, config.memoryDir);
+    const stateDir = path.join(memoryRoot, 'state');
+    const discoveryDir = path.join(memoryRoot, config.folders.discovery);
+    const pendenciasDir = path.join(memoryRoot, config.folders.planning);
+    const skillsDir = path.join(memoryRoot, config.folders.skills);
+    const skillSubfolders = skillSubfoldersForLayout(config.layout);
+    const skillsCuratedDir = path.join(skillsDir, skillSubfolders.curated);
+    const skillsBundlesDir = path.join(skillsDir, skillSubfolders.bundles);
+    const templatesDir = path.join(memoryRoot, config.folders.templates);
+    const promptsDir = path.join(memoryRoot, 'prompts');
+    const depositoDir = path.join(memoryRoot, config.folders.deposito);
+    const plannedDir = path.join(memoryRoot, config.folders.planned);
+    const activeDir = path.join(memoryRoot, config.folders.active);
+    const archivedDir = path.join(memoryRoot, config.folders.archived);
+    const discoveryInsightsDir = path.join(discoveryDir, '1-insights');
+    const discoveryDebatesDir = path.join(discoveryDir, '2-debates');
+    const discoveryEpicDir = path.join(discoveryDir, '3-epic');
+    // Mantemos a chave legada por compatibilidade interna, mas novos projetos
+    // devem materializar apenas a pasta canonica `3-epic`.
+    const discoveryRadarDir = discoveryEpicDir;
+    const discoveryDiscardedDir = path.join(discoveryDir, '4-discarded');
+    return {
+        projectRoot,
+        memoryRoot,
+        configFile: path.join(memoryRoot, 'config.yaml'),
+        coreDir: path.join(memoryRoot, 'core'),
+        discoveryDir,
+        pendenciasDir,
+        stateDir,
+        skillsDir,
+        skillsCuratedDir,
+        skillsBundlesDir,
+        skillsCuratedFolderName: skillSubfolders.curated,
+        skillsBundlesFolderName: skillSubfolders.bundles,
+        templatesDir,
+        promptsDir,
+        depositoDir,
+        plannedDir,
+        activeDir,
+        archivedDir,
+        discoveryInsightsDir,
+        discoveryDebatesDir,
+        discoveryRadarDir,
+        discoveryEpicDir,
+        discoveryDiscardedDir,
+        stateFiles: {
+            discoveryIndex: path.join(stateDir, 'discovery-index.yaml'),
+            backlog: path.join(stateDir, 'backlog.yaml'),
+            techDebt: path.join(stateDir, 'tech-debt.yaml'),
+            finalizeQueue: path.join(stateDir, 'finalize-queue.yaml'),
+            skillCatalog: path.join(stateDir, 'skill-catalog.yaml'),
+            unblockEvents: path.join(stateDir, 'unblock-events.yaml'),
+            transitionLog: path.join(stateDir, 'transition-log.yaml'),
+            auditHistory: path.join(stateDir, 'audit-history.yaml'),
+            frontendGaps: path.join(stateDir, 'frontend-gaps.yaml'),
+            frontendMap: path.join(stateDir, 'frontend-map.yaml'),
+            architecture: path.join(stateDir, 'architecture.yaml'),
+            serviceCatalog: path.join(stateDir, 'service-catalog.yaml'),
+            techStack: path.join(stateDir, 'tech-stack.yaml'),
+            integrationContracts: path.join(stateDir, 'integration-contracts.yaml'),
+            frontendDecisions: path.join(stateDir, 'frontend-decisions.yaml'),
+            repoMap: path.join(stateDir, 'repo-map.yaml'),
+            sourceIndex: path.join(stateDir, 'source-index.yaml'),
+            skillRouting: path.join(stateDir, 'skill-routing.yaml'),
+            namingContract: path.join(stateDir, 'naming-contract.yaml'),
+        },
+    };
+}
+export async function ensureBaseStructure(paths) {
+    await Promise.all([
+        ensureDir(paths.memoryRoot),
+        ensureDir(paths.coreDir),
+        ensureDir(paths.discoveryDir),
+        ensureDir(paths.pendenciasDir),
+        ensureDir(paths.stateDir),
+        ensureDir(paths.plannedDir),
+        ensureDir(paths.activeDir),
+        ensureDir(paths.archivedDir),
+        ensureDir(paths.skillsDir),
+        ensureDir(paths.skillsCuratedDir),
+        ensureDir(paths.skillsBundlesDir),
+        ensureDir(paths.templatesDir),
+        ensureDir(paths.promptsDir),
+        ensureDir(paths.discoveryInsightsDir),
+        ensureDir(paths.discoveryDebatesDir),
+        ensureDir(paths.discoveryRadarDir),
+        ensureDir(paths.discoveryEpicDir),
+        ensureDir(paths.discoveryDiscardedDir),
+        ensureDir(path.join(paths.coreDir, 'dados')),
+        ensureDir(path.join(paths.coreDir, 'integracoes')),
+        ensureDir(path.join(paths.coreDir, 'adrs')),
+        ensureDir(paths.depositoDir),
+        ensureDir(path.join(paths.depositoDir, 'prds')),
+        ensureDir(path.join(paths.depositoDir, 'rfcs')),
+        ensureDir(path.join(paths.depositoDir, 'briefings')),
+        ensureDir(path.join(paths.depositoDir, 'historias')),
+        ensureDir(path.join(paths.depositoDir, 'wireframes')),
+        ensureDir(path.join(paths.depositoDir, 'html-mocks')),
+        ensureDir(path.join(paths.depositoDir, 'referencias-visuais')),
+        ensureDir(path.join(paths.depositoDir, 'entrevistas')),
+        ensureDir(path.join(paths.depositoDir, 'anexos')),
+        ensureDir(path.join(paths.depositoDir, 'legado')),
+    ]);
+}
+async function writeYamlIfMissing(filePath, content) {
+    if (await fileExists(filePath)) {
+        return;
+    }
+    await fs.writeFile(filePath, stringifyYaml(content), 'utf-8');
+}
+async function writeFileIfMissing(filePath, content) {
+    if (await fileExists(filePath)) {
+        return;
+    }
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, content, 'utf-8');
+}
+function isBuiltInSkillSourceTree(definition) {
+    return (typeof definition === 'object' &&
+        definition !== null &&
+        'kind' in definition &&
+        definition.kind === 'source-tree');
+}
+function adaptSkillContentForLayout(content, paths, config) {
+    if (config.layout === 'en-US') {
+        return content;
+    }
+    const sourceRoot = `${path.basename(paths.memoryRoot)}/${config.folders.deposito}`;
+    return content
+        .replaceAll('.sdd/sources', sourceRoot)
+        .replaceAll('/stories/', '/historias/')
+        .replaceAll('/visual-references/', '/referencias-visuais/')
+        .replaceAll('/interviews/', '/entrevistas/')
+        .replaceAll('/attachments/', '/anexos/')
+        .replaceAll('/legacy/', '/legado/');
+}
+async function listTreeFiles(rootDir) {
+    async function walk(currentDir, relativePrefix) {
+        const entries = await fs.readdir(currentDir, { withFileTypes: true });
+        const files = [];
+        for (const entry of entries) {
+            if (entry.name.startsWith('.')) {
+                continue;
+            }
+            const relativePath = relativePrefix ? `${relativePrefix}/${entry.name}` : entry.name;
+            const absolutePath = path.join(currentDir, entry.name);
+            if (entry.isDirectory()) {
+                files.push(...(await walk(absolutePath, relativePath)));
+                continue;
+            }
+            if (entry.isFile()) {
+                files.push(relativePath.replace(/\\/g, '/'));
+            }
+        }
+        return files;
+    }
+    const files = await walk(rootDir, '');
+    files.sort((a, b) => a.localeCompare(b));
+    return files;
+}
+async function resolveBuiltInSourceRoot(paths, sourceRoot) {
+    const normalized = sourceRoot.trim();
+    if (!normalized) {
+        return null;
+    }
+    const candidates = path.isAbsolute(normalized)
+        ? [path.resolve(normalized)]
+        : [path.resolve(paths.projectRoot, normalized), path.resolve(PACKAGE_ROOT, normalized)];
+    for (const candidate of candidates) {
+        try {
+            const stats = await fs.stat(candidate);
+            if (stats.isDirectory()) {
+                return candidate;
+            }
+        }
+        catch {
+            // candidate not available; try next
+        }
+    }
+    return null;
+}
+async function materializeBuiltInSkill(paths, config, skillId, definition) {
+    if (typeof definition === 'string') {
+        const materializedContent = adaptSkillContentForLayout(definition, paths, config);
+        await writeFileIfMissing(path.join(paths.skillsCuratedDir, skillId, 'SKILL.md'), materializedContent);
+        return;
+    }
+    if (isBuiltInSkillSourceTree(definition)) {
+        const sourceRoot = await resolveBuiltInSourceRoot(paths, definition.sourceRoot);
+        if (!sourceRoot) {
+            return;
+        }
+        const files = await listTreeFiles(sourceRoot);
+        for (const relativePath of files) {
+            const sourceFile = path.join(sourceRoot, relativePath);
+            const targetFile = path.join(paths.skillsCuratedDir, skillId, relativePath);
+            const content = await fs.readFile(sourceFile, 'utf-8');
+            await writeFileIfMissing(targetFile, adaptSkillContentForLayout(content, paths, config));
+        }
+        return;
+    }
+    for (const [relativePath, content] of Object.entries(definition)) {
+        if (relativePath.trim().length === 0) {
+            continue;
+        }
+        const targetFile = path.join(paths.skillsCuratedDir, skillId, relativePath);
+        await writeFileIfMissing(targetFile, adaptSkillContentForLayout(content, paths, config));
+    }
+}
+async function ensureCuratedSkillCatalog(filePath) {
+    if (!(await fileExists(filePath))) {
+        await fs.writeFile(filePath, stringifyYaml(DEFAULT_CURATED_SKILL_CATALOG), 'utf-8');
+        return;
+    }
+    const parsed = SkillCatalogStateSchema.safeParse(await readYaml(filePath));
+    if (!parsed.success) {
+        return;
+    }
+    const existing = parsed.data;
+    if (existing.skills.length === 0 && existing.bundles.length === 0) {
+        await fs.writeFile(filePath, stringifyYaml(DEFAULT_CURATED_SKILL_CATALOG), 'utf-8');
+        return;
+    }
+    const skillById = new Map(existing.skills.map((entry) => [entry.id, entry]));
+    let changed = false;
+    for (const defaultSkill of DEFAULT_CURATED_SKILL_CATALOG.skills) {
+        if (!skillById.has(defaultSkill.id)) {
+            skillById.set(defaultSkill.id, defaultSkill);
+            changed = true;
+        }
+    }
+    const bundleById = new Map(existing.bundles.map((entry) => [entry.id, entry]));
+    for (const defaultBundle of DEFAULT_CURATED_SKILL_CATALOG.bundles) {
+        const existingBundle = bundleById.get(defaultBundle.id);
+        if (!existingBundle) {
+            bundleById.set(defaultBundle.id, defaultBundle);
+            changed = true;
+            continue;
+        }
+        const mergedSkillIds = Array.from(new Set([...existingBundle.skill_ids, ...defaultBundle.skill_ids]));
+        if (mergedSkillIds.length !== existingBundle.skill_ids.length) {
+            bundleById.set(defaultBundle.id, {
+                ...existingBundle,
+                skill_ids: mergedSkillIds,
+            });
+            changed = true;
+        }
+    }
+    if (changed) {
+        await fs.writeFile(filePath, stringifyYaml({
+            version: 1,
+            skills: Array.from(skillById.values()).sort((a, b) => a.id.localeCompare(b.id)),
+            bundles: Array.from(bundleById.values()).sort((a, b) => a.id.localeCompare(b.id)),
+        }), 'utf-8');
+    }
+}
+export async function ensureBaseFiles(paths, config) {
+    await writeYamlIfMissing(paths.configFile, {
+        version: 1,
+        state_version: 2,
+        generatedBy: `${CLI_NAME} sdd init`,
+        meta_evolution: {
+            enabled: true,
+            audit_interval_days: 180,
+            placeholder_markers: ['(fill in', '(placeholder', 'TODO:', 'TBD:'],
+            health_alert_threshold: 75,
+        },
+        language: config.language,
+        layout: config.layout,
+        folders: config.folders,
+        frontend: { enabled: config.frontend.enabled },
+        views: { autoRender: config.views.autoRender },
+    });
+    await writeYamlIfMissing(paths.stateFiles.discoveryIndex, {
+        version: 1,
+        counters: { INS: 0, DEB: 0, RAD: 0, EPIC: 0, FEAT: 0, FGAP: 0, TD: 0 },
+        records: [],
+    });
+    await writeYamlIfMissing(paths.stateFiles.backlog, { version: 1, items: [] });
+    await writeYamlIfMissing(paths.stateFiles.techDebt, { version: 1, items: [] });
+    await writeYamlIfMissing(paths.stateFiles.finalizeQueue, { version: 1, items: [] });
+    await ensureCuratedSkillCatalog(paths.stateFiles.skillCatalog);
+    await writeYamlIfMissing(paths.stateFiles.unblockEvents, { version: 1, events: [] });
+    await writeYamlIfMissing(paths.stateFiles.transitionLog, { version: 1, events: [] });
+    await writeYamlIfMissing(paths.stateFiles.auditHistory, { version: 1, runs: [] });
+    await writeYamlIfMissing(paths.stateFiles.architecture, { version: 1, nodes: [] });
+    await writeYamlIfMissing(paths.stateFiles.serviceCatalog, { version: 1, services: [] });
+    await writeYamlIfMissing(paths.stateFiles.techStack, { version: 1, items: [] });
+    await writeYamlIfMissing(paths.stateFiles.integrationContracts, { version: 1, contracts: [] });
+    await writeYamlIfMissing(paths.stateFiles.repoMap, { version: 1, items: [] });
+    await writeYamlIfMissing(paths.stateFiles.sourceIndex, {
+        version: 1,
+        sources: [],
+        version_events: [],
+        jurisdiction_profiles: [],
+        control_catalog: [],
+    });
+    await writeYamlIfMissing(paths.stateFiles.skillRouting, {
+        version: 1,
+        default_skills: ['architecture', 'concise-planning', 'context-window-management'],
+        routes: [
+            { domain: 'backend', skills: ['architecture', 'api-design-principles'], bundles: [] },
+            { domain: 'api', skills: ['api-design-principles', 'api-clean-flask-langgraph'], bundles: ['python-agentic-backend'] },
+            { domain: 'python', skills: ['api-clean-flask-langgraph', 'architecture'], bundles: ['python-agentic-backend'] },
+            { domain: 'flask', skills: ['api-clean-flask-langgraph'], bundles: ['python-agentic-backend'] },
+            { domain: 'nestjs', skills: ['devtrack-api', 'architecture'], bundles: ['architecture-backend'] },
+            { domain: 'typeorm', skills: ['devtrack-api', 'database-design'], bundles: ['architecture-backend'] },
+            { domain: 'devtrack', skills: ['devtrack-api'], bundles: ['architecture-backend'] },
+            { domain: 'frontend', skills: ['frontend-design', 'react-patterns'], bundles: [] },
+            { domain: 'infra', skills: ['terraform-specialist', 'docker-expert'], bundles: [] }
+        ]
+    });
+    if (config.frontend.enabled) {
+        await writeYamlIfMissing(paths.stateFiles.frontendGaps, { version: 1, items: [] });
+        await writeYamlIfMissing(paths.stateFiles.frontendMap, { version: 1, routes: [] });
+        await writeYamlIfMissing(paths.stateFiles.frontendDecisions, { version: 1, items: [] });
+    }
+    await writeFileIfMissing(path.join(paths.coreDir, 'arquitetura.md'), '# Architecture\n\nHigh-level project architecture document.\n');
+    await writeFileIfMissing(path.join(paths.memoryRoot, 'README.md'), buildSddInternalReadme(path.basename(paths.memoryRoot), {
+        discovery: config.folders.discovery,
+        planning: config.folders.planning,
+        skills: config.folders.skills,
+        templates: config.folders.templates,
+        active: config.folders.active,
+        deposito: config.folders.deposito,
+        prompts: 'prompts',
+    }));
+    await writeFileIfMissing(path.join(paths.skillsBundlesDir, config.layout === 'en-US' ? 'curation-en-us.md' : 'curadoria-pt-br.md'), buildCuratedBundlesMarkdown());
+    for (const [skillId, definition] of Object.entries(BUILT_IN_SDD_SKILLS)) {
+        await materializeBuiltInSkill(paths, config, skillId, definition);
+    }
+    await writeFileIfMissing(path.join(paths.depositoDir, 'README.md'), `# Raw Sources\n\nThis folder stores PRDs, RFCs, wireframes, HTML mockups, visual references, interviews, and other consolidated inputs.\n\nRule: nothing here is canonical state. The official inventory lives in \`.sdd/state/source-index.yaml\`.\n`);
+    await writeFileIfMissing(path.join(paths.promptsDir, 'README.md'), PROMPTS_README_MD);
+    const promptNames = config.layout === 'en-US'
+        ? [
+            ['00-start-here.md', PROMPT_00_COMECE_POR_AQUI_MD],
+            ['01-source-intake.md', PROMPT_01_INGESTAO_DEPOSITO_MD],
+            ['02-normalize-planning.md', PROMPT_02_NORMALIZAR_PLANEJAMENTO_MD],
+            ['03-feature-execution.md', PROMPT_03_EXECUCAO_FEATURE_MD],
+            ['04-finalize-consolidation.md', PROMPT_04_CONSOLIDACAO_FINALIZE_MD],
+        ]
+        : [
+            ['00-comece-por-aqui.md', PROMPT_00_COMECE_POR_AQUI_MD],
+            ['01-ingestao-deposito.md', PROMPT_01_INGESTAO_DEPOSITO_MD],
+            ['02-normalizar-planejamento.md', PROMPT_02_NORMALIZAR_PLANEJAMENTO_MD],
+            ['03-execucao-feature.md', PROMPT_03_EXECUCAO_FEATURE_MD],
+            ['04-consolidacao-finalize.md', PROMPT_04_CONSOLIDACAO_FINALIZE_MD],
+        ];
+    for (const [name, content] of promptNames) {
+        await writeFileIfMissing(path.join(paths.promptsDir, name), content);
+    }
+    await writeFileIfMissing(path.join(paths.templatesDir, 'template-1-spec.yaml'), TEMPLATE_1_SPEC_MD);
+    await writeFileIfMissing(path.join(paths.templatesDir, 'template-2-plan.yaml'), TEMPLATE_2_PLAN_MD);
+    await writeFileIfMissing(path.join(paths.templatesDir, 'template-5-quality.yaml'), TEMPLATE_QUALITY_MD);
+    await writeFileIfMissing(path.join(paths.templatesDir, 'template-3-tasks.yaml'), TEMPLATE_3_TASKS_MD);
+    await writeFileIfMissing(path.join(paths.templatesDir, 'template-4-changelog.yaml'), TEMPLATE_4_CHANGELOG_MD);
+    if (config.layout === 'pt-BR') {
+        await writeFileIfMissing(path.join(paths.templatesDir, 'modelo-1-especificacao.yaml'), TEMPLATE_1_SPEC_MD);
+        await writeFileIfMissing(path.join(paths.templatesDir, 'modelo-2-planejamento.yaml'), TEMPLATE_2_PLAN_MD);
+        await writeFileIfMissing(path.join(paths.templatesDir, 'modelo-5-quality.yaml'), TEMPLATE_QUALITY_MD);
+        await writeFileIfMissing(path.join(paths.templatesDir, 'modelo-3-tarefas.yaml'), TEMPLATE_3_TASKS_MD);
+        await writeFileIfMissing(path.join(paths.templatesDir, 'modelo-4-historico.yaml'), TEMPLATE_4_CHANGELOG_MD);
+    }
+}
+async function readYaml(filePath) {
+    const content = await fs.readFile(filePath, 'utf-8');
+    return parseYaml(content);
+}
+async function writeYaml(filePath, value) {
+    const tx = new SddWriteTransaction();
+    tx.writeFile(filePath, stringifyYaml(value));
+    await tx.commit();
+}
+export async function loadStateSnapshot(paths, config) {
+    const discoveryIndex = DiscoveryIndexStateSchema.parse(await readYaml(paths.stateFiles.discoveryIndex));
+    const backlog = BacklogStateSchema.parse(await readYaml(paths.stateFiles.backlog));
+    const techDebt = TechDebtStateSchema.parse(await readYaml(paths.stateFiles.techDebt));
+    const finalizeQueue = FinalizeQueueStateSchema.parse(await readYaml(paths.stateFiles.finalizeQueue));
+    const skillCatalog = SkillCatalogStateSchema.parse(await readYaml(paths.stateFiles.skillCatalog));
+    const unblockEvents = UnblockEventsStateSchema.parse(await readYaml(paths.stateFiles.unblockEvents));
+    const transitionLog = TransitionLogStateSchema.parse(await readYaml(paths.stateFiles.transitionLog));
+    const auditHistory = AuditHistoryStateSchema.parse(await readYaml(paths.stateFiles.auditHistory).catch(() => ({ version: 1, runs: [] })));
+    const architecture = ArchitectureStateSchema.parse(await readYaml(paths.stateFiles.architecture));
+    const serviceCatalog = ServiceCatalogStateSchema.parse(await readYaml(paths.stateFiles.serviceCatalog));
+    const techStack = TechStackStateSchema.parse(await readYaml(paths.stateFiles.techStack));
+    const integrationContracts = IntegrationContractsStateSchema.parse(await readYaml(paths.stateFiles.integrationContracts));
+    const repoMap = RepoMapStateSchema.parse(await readYaml(paths.stateFiles.repoMap));
+    const sourceIndex = SourceIndexStateSchema.parse(await readYaml(paths.stateFiles.sourceIndex));
+    let skillRouting;
+    try {
+        skillRouting = SkillRoutingStateSchema.parse(await readYaml(paths.stateFiles.skillRouting));
+    }
+    catch (e) {
+        skillRouting = {
+            version: 1,
+            default_skills: ['architecture', 'concise-planning', 'context-window-management'],
+            routes: [
+                { domain: 'backend', skills: ['architecture', 'api-design-principles'], bundles: [] },
+                { domain: 'api', skills: ['api-design-principles', 'api-clean-flask-langgraph'], bundles: ['python-agentic-backend'] },
+                { domain: 'python', skills: ['api-clean-flask-langgraph', 'architecture'], bundles: ['python-agentic-backend'] },
+                { domain: 'flask', skills: ['api-clean-flask-langgraph'], bundles: ['python-agentic-backend'] },
+                { domain: 'nestjs', skills: ['devtrack-api', 'architecture'], bundles: ['architecture-backend'] },
+                { domain: 'typeorm', skills: ['devtrack-api', 'database-design'], bundles: ['architecture-backend'] },
+                { domain: 'devtrack', skills: ['devtrack-api'], bundles: ['architecture-backend'] }
+            ]
+        };
+    }
+    let frontendGaps;
+    let frontendMap;
+    let frontendDecisions;
+    if (config.frontend.enabled) {
+        frontendGaps = FrontendGapsStateSchema.parse(await readYaml(paths.stateFiles.frontendGaps));
+        frontendMap = FrontendMapStateSchema.parse(await readYaml(paths.stateFiles.frontendMap));
+        frontendDecisions = FrontendDecisionsStateSchema.parse(await readYaml(paths.stateFiles.frontendDecisions));
+    }
+    return {
+        discoveryIndex,
+        backlog,
+        techDebt,
+        finalizeQueue,
+        skillCatalog,
+        unblockEvents,
+        transitionLog,
+        auditHistory,
+        frontendGaps,
+        frontendMap,
+        architecture,
+        serviceCatalog,
+        techStack,
+        integrationContracts,
+        frontendDecisions,
+        repoMap,
+        sourceIndex,
+        skillRouting,
+    };
+}
+export async function loadSkillCatalogState(paths) {
+    return SkillCatalogStateSchema.parse(await readYaml(paths.stateFiles.skillCatalog));
+}
+function formatCounterId(prefix, value) {
+    return `${prefix}-${String(value).padStart(4, '0')}`;
+}
+export function nowIso() {
+    return new Date().toISOString();
+}
+export async function saveDiscoveryIndexState(paths, state) {
+    await writeYaml(paths.stateFiles.discoveryIndex, state);
+}
+export async function saveBacklogState(paths, state) {
+    await writeYaml(paths.stateFiles.backlog, state);
+}
+export async function saveTechDebtState(paths, state) {
+    await writeYaml(paths.stateFiles.techDebt, state);
+}
+export async function saveFinalizeQueueState(paths, state) {
+    await writeYaml(paths.stateFiles.finalizeQueue, state);
+}
+export async function saveSkillCatalogState(paths, state) {
+    await writeYaml(paths.stateFiles.skillCatalog, state);
+}
+export async function saveUnblockEventsState(paths, state) {
+    await writeYaml(paths.stateFiles.unblockEvents, state);
+}
+export async function saveTransitionLogState(paths, state) {
+    await writeYaml(paths.stateFiles.transitionLog, state);
+}
+export async function saveFrontendGapsState(paths, state) {
+    await writeYaml(paths.stateFiles.frontendGaps, state);
+}
+export async function saveFrontendMapState(paths, state) {
+    await writeYaml(paths.stateFiles.frontendMap, state);
+}
+export async function saveArchitectureState(paths, state) {
+    await writeYaml(paths.stateFiles.architecture, state);
+}
+export async function saveServiceCatalogState(paths, state) {
+    await writeYaml(paths.stateFiles.serviceCatalog, state);
+}
+export async function saveTechStackState(paths, state) {
+    await writeYaml(paths.stateFiles.techStack, state);
+}
+export async function saveIntegrationContractsState(paths, state) {
+    await writeYaml(paths.stateFiles.integrationContracts, state);
+}
+export async function saveFrontendDecisionsState(paths, state) {
+    await writeYaml(paths.stateFiles.frontendDecisions, state);
+}
+export async function saveRepoMapState(paths, state) {
+    await writeYaml(paths.stateFiles.repoMap, state);
+}
+export async function saveSourceIndexState(paths, state) {
+    await writeYaml(paths.stateFiles.sourceIndex, state);
+}
+export function defaultNamingContractState() {
+    const sharedAllowlist = [
+        '.sdd/archived/**',
+        '.sdd/sources/legado/**',
+        '.sdd/discovery/**',
+        'test/core/sdd/fixtures/**',
+    ];
+    return {
+        version: 1,
+        product_name: 'CodeSDD',
+        cli_bin: 'codesdd',
+        package_name: '@devtrack-solution/codesdd',
+        current_identity: {
+            product_name: 'CodeSDD',
+            cli_bin: 'codesdd',
+            package_name: '@devtrack-solution/codesdd',
+        },
+        target_identity: {
+            product_name: 'CodeSDD',
+            cli_bin: 'codesdd',
+            package_name: '@devtrack-solution/codesdd',
+        },
+        forbidden_terms: [
+            { term: 'openspec', scope: 'all', severity: 'warning', allowlist_paths: [...sharedAllowlist] },
+            { term: 'OpenSpec', scope: 'all', severity: 'warning', allowlist_paths: [...sharedAllowlist] },
+            { term: 'openSpec', scope: 'all', severity: 'warning', allowlist_paths: [...sharedAllowlist] },
+        ],
+        allowlist: [
+            { path_pattern: '.sdd/archived/**', reason: 'Archived SDD artifacts retain legacy terminology', owner: 'sdd-core' },
+            { path_pattern: '.sdd/sources/legacy/spec-corpus/**', reason: 'Legacy OpenSpec import sources', owner: 'sdd-core' },
+            { path_pattern: 'node_modules/**', reason: 'Third-party dependencies', owner: 'sdd-core' },
+            { path_pattern: 'dist/**', reason: 'Build output', owner: 'sdd-core' },
+            { path_pattern: 'coverage/**', reason: 'Test coverage artifacts', owner: 'sdd-core' },
+            { path_pattern: '.git/**', reason: 'Git internals', owner: 'sdd-core' },
+        ],
+        rename_rules: [
+            {
+                from: 'OpenSDD',
+                to: 'CodeSDD',
+                scope: 'all',
+                phase: 'identity-introduction',
+                owner: 'sdd-core',
+                status: 'planned',
+                path_globs: ['README.md', 'docs/**', 'src/**', 'test/**', '.sdd/state/**'],
+            },
+            {
+                from: 'opensdd',
+                to: 'codesdd',
+                scope: 'all',
+                phase: 'identity-introduction',
+                owner: 'sdd-core',
+                status: 'planned',
+                path_globs: ['package.json', 'bin/**', 'src/**', 'test/**', 'docs/**'],
+            },
+            {
+                from: '@devtrack-solution/codesdd',
+                to: '@devtrack-solution/codesdd',
+                scope: 'all',
+                phase: 'package-identity',
+                owner: 'sdd-core',
+                status: 'planned',
+                path_globs: ['package.json', 'README.md', 'docs/**', 'test/**'],
+            },
+        ],
+        zero_residue_gate: {
+            enabled: true,
+            enforcement: 'warning',
+            terms: ['openspec', 'OpenSpec', 'openSpec', 'opensdd', 'OpenSDD', 'openSDD'],
+            allowlist_paths: [...sharedAllowlist],
+            removal_phase: 'compatibility-shutdown',
+        },
+        updated_at: nowIso(),
+    };
+}
+export async function loadNamingContractState(paths) {
+    if (!(await fileExists(paths.stateFiles.namingContract))) {
+        return defaultNamingContractState();
+    }
+    try {
+        return NamingContractStateSchema.parse(await readYaml(paths.stateFiles.namingContract));
+    }
+    catch {
+        return defaultNamingContractState();
+    }
+}
+export async function saveNamingContractState(paths, state) {
+    await writeYaml(paths.stateFiles.namingContract, state);
+}
+export async function saveStateTransaction(paths, updates) {
+    const tx = new SddWriteTransaction();
+    if (updates.discoveryIndex) {
+        tx.writeFile(paths.stateFiles.discoveryIndex, stringifyYaml(updates.discoveryIndex));
+    }
+    if (updates.backlog) {
+        tx.writeFile(paths.stateFiles.backlog, stringifyYaml(updates.backlog));
+    }
+    if (updates.techDebt) {
+        tx.writeFile(paths.stateFiles.techDebt, stringifyYaml(updates.techDebt));
+    }
+    if (updates.finalizeQueue) {
+        tx.writeFile(paths.stateFiles.finalizeQueue, stringifyYaml(updates.finalizeQueue));
+    }
+    if (updates.skillCatalog) {
+        tx.writeFile(paths.stateFiles.skillCatalog, stringifyYaml(updates.skillCatalog));
+    }
+    if (updates.unblockEvents) {
+        tx.writeFile(paths.stateFiles.unblockEvents, stringifyYaml(updates.unblockEvents));
+    }
+    if (updates.transitionLog) {
+        tx.writeFile(paths.stateFiles.transitionLog, stringifyYaml(updates.transitionLog));
+    }
+    if (updates.auditHistory) {
+        tx.writeFile(paths.stateFiles.auditHistory, stringifyYaml(updates.auditHistory));
+    }
+    if (updates.frontendGaps) {
+        tx.writeFile(paths.stateFiles.frontendGaps, stringifyYaml(updates.frontendGaps));
+    }
+    if (updates.frontendMap) {
+        tx.writeFile(paths.stateFiles.frontendMap, stringifyYaml(updates.frontendMap));
+    }
+    if (updates.architecture) {
+        tx.writeFile(paths.stateFiles.architecture, stringifyYaml(updates.architecture));
+    }
+    if (updates.serviceCatalog) {
+        tx.writeFile(paths.stateFiles.serviceCatalog, stringifyYaml(updates.serviceCatalog));
+    }
+    if (updates.techStack) {
+        tx.writeFile(paths.stateFiles.techStack, stringifyYaml(updates.techStack));
+    }
+    if (updates.integrationContracts) {
+        tx.writeFile(paths.stateFiles.integrationContracts, stringifyYaml(updates.integrationContracts));
+    }
+    if (updates.frontendDecisions) {
+        tx.writeFile(paths.stateFiles.frontendDecisions, stringifyYaml(updates.frontendDecisions));
+    }
+    if (updates.repoMap) {
+        tx.writeFile(paths.stateFiles.repoMap, stringifyYaml(updates.repoMap));
+    }
+    if (updates.sourceIndex) {
+        tx.writeFile(paths.stateFiles.sourceIndex, stringifyYaml(updates.sourceIndex));
+    }
+    await tx.commit();
+}
+/**
+ * Allocates a new entity ID with atomic reservation and collision detection.
+ * Verifies that the generated ID does not already exist in the discovery index
+ * records before persisting. Retries with the next counter value if collision
+ * is detected (defensive against manual edits or stale counters).
+ *
+ * @param paths - SDD directory paths
+ * @param type - Counter type (INS, DEB, RAD, EPIC, FEAT, FGAP, TD)
+ * @returns The reserved ID string
+ */
+export async function allocateEntityId(paths, type) {
+    const discoveryIndex = DiscoveryIndexStateSchema.parse(await readYaml(paths.stateFiles.discoveryIndex));
+    // Build a set of all existing IDs for fast collision check
+    const existingIds = new Set();
+    for (const record of discoveryIndex.records) {
+        existingIds.add(record.id);
+    }
+    // Also check backlog items for FEAT collision
+    if (type === 'FEAT') {
+        try {
+            const backlog = BacklogStateSchema.parse(await readYaml(paths.stateFiles.backlog));
+            for (const item of backlog.items) {
+                existingIds.add(item.id);
+            }
+        }
+        catch {
+            // If backlog can't be read, proceed with discovery-only check
+        }
+    }
+    let candidate = (discoveryIndex.counters[type] ?? 0) + 1;
+    let candidateId = formatCounterId(type, candidate);
+    // Retry loop: advance counter until no collision
+    const maxRetries = 100;
+    let retries = 0;
+    while (existingIds.has(candidateId) && retries < maxRetries) {
+        candidate++;
+        candidateId = formatCounterId(type, candidate);
+        retries++;
+    }
+    if (retries >= maxRetries) {
+        throw new Error(`Falha ao alocar ID para ${type}: ${maxRetries} colisoes consecutivas detectadas. Verifique o estado do discovery-index.`);
+    }
+    // Persist the updated counter
+    discoveryIndex.counters[type] = candidate;
+    await saveDiscoveryIndexState(paths, discoveryIndex);
+    return candidateId;
+}
+//# sourceMappingURL=state.js.map