@devtrack-solution/codesdd 1.2.2 → 1.2.4-rc3

package/dist/core/sdd/state.d.ts

@@ -1,4 +1,5 @@
 import { type NamingContractState, type ArchitectureState, type BacklogState, type DiscoveryIndexState, type FinalizeQueueState, type FrontendDecisionsState, type FrontendGapsState, type FrontendMapState, type IntegrationContractsState, type RepoMapState, type SourceIndexState, type SkillCatalogState, type SkillRoutingState, type ServiceCatalogState, type TechStackState, type TechDebtState, type UnblockEventsState, type TransitionLogState, type AuditHistoryState } from './types.js';
+import { type BuiltInSkillDefinition, type BuiltInSkillSourceTree } from './default-skills.js';
 export type SddLanguage = 'pt-BR' | 'en-US';
 export type SddLayout = 'legacy' | 'pt-BR' | 'en-US';
 export interface SddRuntimeConfig {
@@ -23,6 +24,7 @@ export interface SddRuntimeConfig {
         autoRender: boolean;
     };
 }
+export declare function buildDefaultSkillRoutingState(): SkillRoutingState;
 export interface SddPaths {
     projectRoot: string;
     memoryRoot: string;
@@ -89,6 +91,21 @@ export interface SddStateSnapshot {
     sourceIndex: SourceIndexState;
     skillRouting: SkillRoutingState;
 }
+export declare function skillSubfoldersForLayout(layout: SddLayout): {
+    curated: string;
+    bundles: string;
+};
+export declare function defaultFoldersForLayout(layout: SddLayout): SddRuntimeConfig['folders'];
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function mergeRuntimeConfig(raw: unknown): SddRuntimeConfig;
+export declare function validateRuntimeConfig(config: SddRuntimeConfig): void;
+export declare function defaultRuntimeConfig(): SddRuntimeConfig;
+export declare function fileExists(filePath: string): Promise<boolean>;
+export declare function firstExistingFile(paths: string[]): Promise<string | null>;
+export declare function readYamlObject(filePath: string): Promise<Record<string, unknown>>;
+export declare function isLegacyGeneratedBy(value: unknown): boolean;
+export declare function buildSddConfigDocument(existing: Record<string, unknown>, config: SddRuntimeConfig): Record<string, unknown>;
+export declare function removeSddRuntimeConfigFromLegacySpecConfig(projectRoot: string): Promise<void>;
 export declare function loadProjectSddConfig(projectRoot: string): Promise<SddRuntimeConfig>;
 export declare function upsertProjectSddConfig(projectRoot: string, overrides?: {
     frontendEnabled?: boolean;
@@ -97,6 +114,12 @@ export declare function upsertProjectSddConfig(projectRoot: string, overrides?:
 }): Promise<SddRuntimeConfig>;
 export declare function resolveSddPaths(projectRoot: string, config: SddRuntimeConfig): SddPaths;
 export declare function ensureBaseStructure(paths: SddPaths): Promise<void>;
+export declare function isBuiltInSkillSourceTree(definition: BuiltInSkillDefinition): definition is BuiltInSkillSourceTree;
+export declare function adaptSkillContentForLayout(content: string, paths: SddPaths, config: SddRuntimeConfig): string;
+export declare function listTreeFiles(rootDir: string): Promise<string[]>;
+export declare function resolveBuiltInSourceRoot(paths: SddPaths, sourceRoot: string): Promise<string | null>;
+export declare function materializeBuiltInSkill(paths: SddPaths, config: SddRuntimeConfig, skillId: string, definition: BuiltInSkillDefinition): Promise<void>;
+export declare function ensureCuratedSkillCatalog(filePath: string): Promise<void>;
 export declare function ensureBaseFiles(paths: SddPaths, config: SddRuntimeConfig): Promise<void>;
 export declare function loadStateSnapshot(paths: SddPaths, config: SddRuntimeConfig): Promise<SddStateSnapshot>;
 export declare function loadSkillCatalogState(paths: SddPaths): Promise<SkillCatalogState>;

package/dist/core/sdd/state.js

@@ -2,12 +2,261 @@ 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 { resolveLegacySpecLiveSubpath } 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 { CURRENT_SDD_STATE_VERSION, buildSddContractConfig } from './contract.js';
+import { DEFAULT_CURATED_SKILL_CATALOG, BUILT_IN_SDD_SKILLS, buildCuratedBundlesMarkdown, buildCuratedBundlesCurationData, } 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';
+export function buildDefaultSkillRoutingState() {
+    return {
+        version: 1,
+        default_skills: ['architecture', 'concise-planning', 'context-window-management'],
+        routes: [
+            {
+                domain: 'backend',
+                skills: ['devtrack-api', 'architecture', 'api-design-principles'],
+                bundles: ['architecture-backend'],
+            },
+            {
+                domain: 'api',
+                skills: ['devtrack-api', 'api-design-principles'],
+                bundles: ['architecture-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: 'python',
+                skills: ['api-clean-flask-langgraph', 'architecture'],
+                bundles: ['python-agentic-backend'],
+            },
+            {
+                domain: 'flask',
+                skills: ['api-clean-flask-langgraph'],
+                bundles: ['python-agentic-backend'],
+            },
+            {
+                domain: 'frontend',
+                skills: ['frontend-design', 'react-patterns'],
+                bundles: ['frontend-product'],
+            },
+            {
+                domain: 'angular',
+                skills: ['frontend-design', 'frontend-security-coder'],
+                bundles: ['frontend-product', 'security-quality'],
+            },
+            {
+                domain: 'flutter',
+                skills: ['devtrack-flutter', 'mobile-design', 'frontend-design'],
+                bundles: ['frontend-product'],
+            },
+            {
+                domain: 'dart',
+                skills: ['devtrack-flutter', 'architecture'],
+                bundles: ['frontend-product', 'architecture-backend'],
+            },
+            {
+                domain: 'cross-platform',
+                skills: ['devtrack-flutter', 'mobile-design'],
+                bundles: ['frontend-product'],
+            },
+            {
+                domain: 'flutter-ui',
+                skills: ['devtrack-flutter', 'frontend-design'],
+                bundles: ['frontend-product'],
+            },
+            {
+                domain: 'flutter-layout',
+                skills: ['devtrack-flutter', 'frontend-design'],
+                bundles: ['frontend-product'],
+            },
+            {
+                domain: 'flutter-routing',
+                skills: ['devtrack-flutter', 'architecture'],
+                bundles: ['frontend-product', 'architecture-backend'],
+            },
+            {
+                domain: 'flutter-l10n',
+                skills: ['devtrack-flutter'],
+                bundles: ['frontend-product'],
+            },
+            {
+                domain: 'flutter-http',
+                skills: ['devtrack-flutter', 'frontend-security-coder'],
+                bundles: ['frontend-product', 'security-quality'],
+            },
+            {
+                domain: 'flutter-json',
+                skills: ['devtrack-flutter'],
+                bundles: ['frontend-product'],
+            },
+            {
+                domain: 'widget-preview',
+                skills: ['devtrack-flutter', 'frontend-design'],
+                bundles: ['frontend-product'],
+            },
+            {
+                domain: 'widget-test',
+                skills: ['devtrack-flutter'],
+                bundles: ['frontend-product'],
+            },
+            {
+                domain: 'integration-test',
+                skills: ['devtrack-flutter'],
+                bundles: ['frontend-product'],
+            },
+            {
+                domain: 'go-router',
+                skills: ['devtrack-flutter', 'architecture'],
+                bundles: ['frontend-product', 'architecture-backend'],
+            },
+            {
+                domain: 'arb',
+                skills: ['devtrack-flutter'],
+                bundles: ['frontend-product'],
+            },
+            {
+                domain: 'l10n',
+                skills: ['devtrack-flutter'],
+                bundles: ['frontend-product'],
+            },
+            {
+                domain: 'admin',
+                skills: ['devtrack-angular', 'frontend-design', 'frontend-security-coder'],
+                bundles: ['frontend-product', 'security-quality'],
+            },
+            {
+                domain: 'angular-admin',
+                skills: ['devtrack-angular', 'frontend-design', 'frontend-security-coder'],
+                bundles: ['frontend-product', 'security-quality'],
+            },
+            {
+                domain: 'backoffice',
+                skills: ['devtrack-angular', 'frontend-design', 'frontend-security-coder'],
+                bundles: ['frontend-product', 'security-quality'],
+            },
+            {
+                domain: 'dashboard',
+                skills: ['devtrack-angular', 'frontend-design'],
+                bundles: ['frontend-product'],
+            },
+            {
+                domain: 'crud',
+                skills: ['devtrack-angular', 'architecture'],
+                bundles: ['frontend-product', 'architecture-backend'],
+            },
+            {
+                domain: 'data-grid',
+                skills: ['devtrack-angular', 'frontend-design'],
+                bundles: ['frontend-product'],
+            },
+            {
+                domain: 'formly',
+                skills: ['frontend-design'],
+                bundles: ['frontend-product'],
+            },
+            {
+                domain: 'ngxs',
+                skills: ['architecture'],
+                bundles: ['frontend-product', 'architecture-backend'],
+            },
+            {
+                domain: 'admin-formly',
+                skills: ['devtrack-angular', 'frontend-design'],
+                bundles: ['frontend-product'],
+            },
+            {
+                domain: 'admin-state',
+                skills: ['devtrack-angular', 'architecture'],
+                bundles: ['frontend-product', 'architecture-backend'],
+            },
+            {
+                domain: 'ngxs-admin',
+                skills: ['devtrack-angular', 'architecture'],
+                bundles: ['frontend-product', 'architecture-backend'],
+            },
+            {
+                domain: 'uiux',
+                skills: ['frontend-design', 'ui-ux-pro-max'],
+                bundles: ['frontend-product'],
+            },
+            {
+                domain: 'permissions',
+                skills: ['devtrack-angular', 'frontend-security-coder'],
+                bundles: ['frontend-product', 'security-quality'],
+            },
+            {
+                domain: 'reports',
+                skills: ['devtrack-angular', 'frontend-design'],
+                bundles: ['frontend-product'],
+            },
+            {
+                domain: 'workflow',
+                skills: ['devtrack-angular', 'architecture'],
+                bundles: ['frontend-product', 'architecture-backend'],
+            },
+            {
+                domain: 'realtime',
+                skills: ['architecture'],
+                bundles: ['frontend-product'],
+            },
+            {
+                domain: 'rtc',
+                skills: ['architecture'],
+                bundles: ['frontend-product'],
+            },
+            {
+                domain: 'chat',
+                skills: ['frontend-design'],
+                bundles: ['frontend-product'],
+            },
+            {
+                domain: 'admin-realtime',
+                skills: ['devtrack-angular', 'architecture'],
+                bundles: ['frontend-product'],
+            },
+            {
+                domain: 'admin-chat',
+                skills: ['devtrack-angular', 'frontend-design'],
+                bundles: ['frontend-product'],
+            },
+            {
+                domain: 'mobile',
+                skills: ['mobile-design'],
+                bundles: ['frontend-product'],
+            },
+            {
+                domain: 'ionic',
+                skills: ['mobile-design'],
+                bundles: ['frontend-product'],
+            },
+            {
+                domain: 'nativescript',
+                skills: ['mobile-design'],
+                bundles: ['frontend-product'],
+            },
+            {
+                domain: 'infra',
+                skills: ['terraform-specialist', 'docker-expert'],
+                bundles: [],
+            },
+        ],
+    };
+}
 const LEGACY_LAYOUT_FOLDERS = {
     discovery: 'discovery',
     planning: 'pendencias',
@@ -38,13 +287,13 @@ const PT_BR_LAYOUT_FOLDERS = {
     active: 'execucao',
     archived: 'arquivados',
 };
-function skillSubfoldersForLayout(layout) {
+export function skillSubfoldersForLayout(layout) {
     if (layout === 'pt-BR') {
         return { curated: 'skills', bundles: 'pacotes' };
     }
     return { curated: 'curated', bundles: 'bundles' };
 }
-function defaultFoldersForLayout(layout) {
+export function defaultFoldersForLayout(layout) {
     if (layout === 'pt-BR') {
         return { ...PT_BR_LAYOUT_FOLDERS };
     }
@@ -95,10 +344,10 @@ const CANONICAL_FOLDER_OPTIONS = {
         archived: ['arquivados'],
     },
 };
-function isRecord(value) {
+export function isRecord(value) {
     return !!value && typeof value === 'object' && !Array.isArray(value);
 }
-function mergeRuntimeConfig(raw) {
+export function mergeRuntimeConfig(raw) {
     if (!isRecord(raw)) {
         return {
             ...DEFAULT_SDD_CONFIG,
@@ -163,7 +412,7 @@ function mergeRuntimeConfig(raw) {
         },
     };
 }
-function validateRuntimeConfig(config) {
+export function validateRuntimeConfig(config) {
     const allowed = CANONICAL_FOLDER_OPTIONS[config.layout];
     const invalidEntries = Object.entries(config.folders).flatMap(([key, value]) => {
         const folderKey = key;
@@ -179,7 +428,7 @@ function validateRuntimeConfig(config) {
         throw new Error(`Configuracao SDD invalida em .sdd/config.yaml: folders fora do canonico para layout ${config.layout}: ${invalidEntries.join('; ')}`);
     }
 }
-function defaultRuntimeConfig() {
+export function defaultRuntimeConfig() {
     return {
         ...DEFAULT_SDD_CONFIG,
         folders: { ...DEFAULT_SDD_CONFIG.folders },
@@ -187,7 +436,7 @@ function defaultRuntimeConfig() {
         views: { autoRender: DEFAULT_SDD_CONFIG.views.autoRender },
     };
 }
-async function fileExists(filePath) {
+export async function fileExists(filePath) {
     try {
         await fs.access(filePath);
         return true;
@@ -199,7 +448,7 @@ async function fileExists(filePath) {
 async function ensureDir(dirPath) {
     await fs.mkdir(dirPath, { recursive: true });
 }
-async function firstExistingFile(paths) {
+export async function firstExistingFile(paths) {
     for (const filePath of paths) {
         if (await fileExists(filePath)) {
             return filePath;
@@ -207,17 +456,27 @@ async function firstExistingFile(paths) {
     }
     return null;
 }
-async function readYamlObject(filePath) {
+export async function readYamlObject(filePath) {
     const parsed = parseYaml(await fs.readFile(filePath, 'utf-8'));
     return isRecord(parsed) ? parsed : {};
 }
-function buildSddConfigDocument(existing, config) {
+const LEGACY_GENERATED_BY_PREFIXES = [`${'open'}sdd`, `${'open'}spec`];
+export function isLegacyGeneratedBy(value) {
+    if (typeof value !== 'string')
+        return false;
+    return LEGACY_GENERATED_BY_PREFIXES.some((prefix) => new RegExp(`^${prefix}\\s`, 'i').test(value));
+}
+export 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;
+    const stateVersion = typeof next.state_version === 'number' ? next.state_version : CURRENT_SDD_STATE_VERSION;
+    next.state_version = stateVersion;
+    if (stateVersion >= CURRENT_SDD_STATE_VERSION) {
+        next.sdd_contract = buildSddContractConfig();
+    }
     next.generatedBy =
-        typeof next.generatedBy === 'string' && !next.generatedBy.startsWith('openspec ')
+        typeof next.generatedBy === 'string' && !isLegacyGeneratedBy(next.generatedBy)
             ? next.generatedBy
             : `${CLI_NAME} sdd init`;
     next.meta_evolution = isRecord(next.meta_evolution)
@@ -237,10 +496,10 @@ function buildSddConfigDocument(existing, config) {
     next.views = { autoRender: config.views.autoRender };
     return next;
 }
-async function removeSddRuntimeConfigFromOpenSpecConfig(projectRoot) {
+export async function removeSddRuntimeConfigFromLegacySpecConfig(projectRoot) {
     const legacyConfigPath = await firstExistingFile([
-        resolveOpenSpecLiveSubpath(projectRoot, 'config.yaml'),
-        resolveOpenSpecLiveSubpath(projectRoot, 'config.yml'),
+        resolveLegacySpecLiveSubpath(projectRoot, 'config.yaml'),
+        resolveLegacySpecLiveSubpath(projectRoot, 'config.yml'),
     ]);
     if (!legacyConfigPath) {
         return;
@@ -263,8 +522,8 @@ export async function loadProjectSddConfig(projectRoot) {
         return config;
     }
     const legacyConfigPath = await firstExistingFile([
-        resolveOpenSpecLiveSubpath(projectRoot, 'config.yaml'),
-        resolveOpenSpecLiveSubpath(projectRoot, 'config.yml'),
+        resolveLegacySpecLiveSubpath(projectRoot, 'config.yaml'),
+        resolveLegacySpecLiveSubpath(projectRoot, 'config.yml'),
     ]);
     if (legacyConfigPath) {
         const legacyRoot = await readYamlObject(legacyConfigPath);
@@ -289,8 +548,8 @@ export async function upsertProjectSddConfig(projectRoot, overrides) {
     }
     else {
         const legacyConfigPath = await firstExistingFile([
-            resolveOpenSpecLiveSubpath(projectRoot, 'config.yaml'),
-            resolveOpenSpecLiveSubpath(projectRoot, 'config.yml'),
+            resolveLegacySpecLiveSubpath(projectRoot, 'config.yaml'),
+            resolveLegacySpecLiveSubpath(projectRoot, 'config.yml'),
         ]);
         if (legacyConfigPath) {
             const legacyRoot = await readYamlObject(legacyConfigPath);
@@ -310,7 +569,7 @@ export async function upsertProjectSddConfig(projectRoot, overrides) {
     }
     validateRuntimeConfig(mergedSdd);
     await fs.writeFile(configPath, stringifyYaml(buildSddConfigDocument(rootConfig, mergedSdd)), 'utf-8');
-    await removeSddRuntimeConfigFromOpenSpecConfig(projectRoot);
+    await removeSddRuntimeConfigFromLegacySpecConfig(projectRoot);
     return mergedSdd;
 }
 export function resolveSddPaths(projectRoot, config) {
@@ -431,13 +690,13 @@ async function writeFileIfMissing(filePath, content) {
     await fs.mkdir(path.dirname(filePath), { recursive: true });
     await fs.writeFile(filePath, content, 'utf-8');
 }
-function isBuiltInSkillSourceTree(definition) {
+export function isBuiltInSkillSourceTree(definition) {
     return (typeof definition === 'object' &&
         definition !== null &&
         'kind' in definition &&
         definition.kind === 'source-tree');
 }
-function adaptSkillContentForLayout(content, paths, config) {
+export function adaptSkillContentForLayout(content, paths, config) {
     if (config.layout === 'en-US') {
         return content;
     }
@@ -450,7 +709,7 @@ function adaptSkillContentForLayout(content, paths, config) {
         .replaceAll('/attachments/', '/anexos/')
         .replaceAll('/legacy/', '/legado/');
 }
-async function listTreeFiles(rootDir) {
+export async function listTreeFiles(rootDir) {
     async function walk(currentDir, relativePrefix) {
         const entries = await fs.readdir(currentDir, { withFileTypes: true });
         const files = [];
@@ -474,7 +733,7 @@ async function listTreeFiles(rootDir) {
     files.sort((a, b) => a.localeCompare(b));
     return files;
 }
-async function resolveBuiltInSourceRoot(paths, sourceRoot) {
+export async function resolveBuiltInSourceRoot(paths, sourceRoot) {
     const normalized = sourceRoot.trim();
     if (!normalized) {
         return null;
@@ -495,7 +754,7 @@ async function resolveBuiltInSourceRoot(paths, sourceRoot) {
     }
     return null;
 }
-async function materializeBuiltInSkill(paths, config, skillId, definition) {
+export 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);
@@ -523,7 +782,7 @@ async function materializeBuiltInSkill(paths, config, skillId, definition) {
         await writeFileIfMissing(targetFile, adaptSkillContentForLayout(content, paths, config));
     }
 }
-async function ensureCuratedSkillCatalog(filePath) {
+export async function ensureCuratedSkillCatalog(filePath) {
     if (!(await fileExists(filePath))) {
         await fs.writeFile(filePath, stringifyYaml(DEFAULT_CURATED_SKILL_CATALOG), 'utf-8');
         return;
@@ -573,7 +832,8 @@ async function ensureCuratedSkillCatalog(filePath) {
 export async function ensureBaseFiles(paths, config) {
     await writeYamlIfMissing(paths.configFile, {
         version: 1,
-        state_version: 2,
+        state_version: CURRENT_SDD_STATE_VERSION,
+        sdd_contract: buildSddContractConfig(),
         generatedBy: `${CLI_NAME} sdd init`,
         meta_evolution: {
             enabled: true,
@@ -594,7 +854,7 @@ export async function ensureBaseFiles(paths, config) {
     });
     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 writeYamlIfMissing(paths.stateFiles.finalizeQueue, { version: 1, items: [], history: [] });
     await ensureCuratedSkillCatalog(paths.stateFiles.skillCatalog);
     await writeYamlIfMissing(paths.stateFiles.unblockEvents, { version: 1, events: [] });
     await writeYamlIfMissing(paths.stateFiles.transitionLog, { version: 1, events: [] });
@@ -611,21 +871,7 @@ export async function ensureBaseFiles(paths, config) {
         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: [] }
-        ]
-    });
+    await writeYamlIfMissing(paths.stateFiles.skillRouting, buildDefaultSkillRoutingState());
     if (config.frontend.enabled) {
         await writeYamlIfMissing(paths.stateFiles.frontendGaps, { version: 1, items: [] });
         await writeYamlIfMissing(paths.stateFiles.frontendMap, { version: 1, routes: [] });
@@ -642,6 +888,11 @@ export async function ensureBaseFiles(paths, config) {
         prompts: 'prompts',
     }));
     await writeFileIfMissing(path.join(paths.skillsBundlesDir, config.layout === 'en-US' ? 'curation-en-us.md' : 'curadoria-pt-br.md'), buildCuratedBundlesMarkdown());
+    // EPIC-0072 wave 1 (FEAT-0284) — emit a schema-validated YAML form alongside
+    // the Markdown view so consumers can read typed data without scraping headings.
+    // The .md remains the human-readable view; the .yaml is the structured contract.
+    const curationLayout = config.layout === 'pt-BR' ? 'pt-BR' : 'en-US';
+    await writeFileIfMissing(path.join(paths.skillsBundlesDir, config.layout === 'en-US' ? 'curation-en-us.yaml' : 'curadoria-pt-br.yaml'), stringifyYaml(buildCuratedBundlesCurationData(curationLayout)));
     for (const [skillId, definition] of Object.entries(BUILT_IN_SDD_SKILLS)) {
         await materializeBuiltInSkill(paths, config, skillId, definition);
     }
@@ -707,19 +958,7 @@ export async function loadStateSnapshot(paths, config) {
         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'] }
-            ]
-        };
+        skillRouting = buildDefaultSkillRoutingState();
     }
     let frontendGaps;
     let frontendMap;
@@ -814,6 +1053,14 @@ export function defaultNamingContractState() {
         '.sdd/discovery/**',
         'test/core/sdd/fixtures/**',
     ];
+    const legacyPrefix = 'open';
+    const legacySpec = `${legacyPrefix}spec`;
+    const legacySdd = `${legacyPrefix}sdd`;
+    const legacyTitlePrefix = `${legacyPrefix[0].toUpperCase()}${legacyPrefix.slice(1)}`;
+    const legacySpecTitle = `${legacyTitlePrefix}Spec`;
+    const legacySddTitle = `${legacyTitlePrefix}SDD`;
+    const legacySpecCamel = `${legacyPrefix}Spec`;
+    const legacySddCamel = `${legacyPrefix}SDD`;
     return {
         version: 1,
         product_name: 'CodeSDD',
@@ -830,13 +1077,13 @@ export function defaultNamingContractState() {
             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] },
+            { term: legacySpec, scope: 'all', severity: 'warning', allowlist_paths: [...sharedAllowlist] },
+            { term: legacySpecTitle, scope: 'all', severity: 'warning', allowlist_paths: [...sharedAllowlist] },
+            { term: legacySpecCamel, 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: '.sdd/sources/legacy/spec-corpus/**', reason: 'Imported legacy corpus 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' },
@@ -844,7 +1091,7 @@ export function defaultNamingContractState() {
         ],
         rename_rules: [
             {
-                from: 'OpenSDD',
+                from: legacySddTitle,
                 to: 'CodeSDD',
                 scope: 'all',
                 phase: 'identity-introduction',
@@ -853,7 +1100,7 @@ export function defaultNamingContractState() {
                 path_globs: ['README.md', 'docs/**', 'src/**', 'test/**', '.sdd/state/**'],
             },
             {
-                from: 'opensdd',
+                from: legacySdd,
                 to: 'codesdd',
                 scope: 'all',
                 phase: 'identity-introduction',
@@ -862,7 +1109,7 @@ export function defaultNamingContractState() {
                 path_globs: ['package.json', 'bin/**', 'src/**', 'test/**', 'docs/**'],
             },
             {
-                from: '@devtrack-solution/codesdd',
+                from: `@devtrack-solution/${legacySdd}-cli`,
                 to: '@devtrack-solution/codesdd',
                 scope: 'all',
                 phase: 'package-identity',
@@ -874,7 +1121,7 @@ export function defaultNamingContractState() {
         zero_residue_gate: {
             enabled: true,
             enforcement: 'warning',
-            terms: ['openspec', 'OpenSpec', 'openSpec', 'opensdd', 'OpenSDD', 'openSDD'],
+            terms: [legacySpec, legacySpecTitle, legacySpecCamel, legacySdd, legacySddTitle, legacySddCamel],
             allowlist_paths: [...sharedAllowlist],
             removal_phase: 'compatibility-shutdown',
         },

package/dist/core/sdd/store/sdd-stores.js

@@ -7,7 +7,7 @@ export function createSddStores(paths) {
         discoveryIndex: new YamlFileAdapter(stateFiles.discoveryIndex, DiscoveryIndexStateSchema, () => ({ version: 1, counters: { INS: 0, DEB: 0, RAD: 0, EPIC: 0, FEAT: 0, FGAP: 0, TD: 0 }, records: [] })),
         backlog: new YamlFileAdapter(stateFiles.backlog, BacklogStateSchema, () => ({ version: 1, items: [] })),
         techDebt: new YamlFileAdapter(stateFiles.techDebt, TechDebtStateSchema, () => ({ version: 1, items: [] })),
-        finalizeQueue: new YamlFileAdapter(stateFiles.finalizeQueue, FinalizeQueueStateSchema, () => ({ version: 1, items: [] })),
+        finalizeQueue: new YamlFileAdapter(stateFiles.finalizeQueue, FinalizeQueueStateSchema, () => ({ version: 1, items: [], history: [] })),
         skillCatalog: new YamlFileAdapter(stateFiles.skillCatalog, SkillCatalogStateSchema, () => ({ version: 1, skills: [], bundles: [] })),
         unblockEvents: new YamlFileAdapter(stateFiles.unblockEvents, UnblockEventsStateSchema, () => ({ version: 1, events: [] })),
         transitionLog: new YamlFileAdapter(stateFiles.transitionLog, TransitionLogStateSchema, () => ({ version: 1, events: [] })),
@@ -34,7 +34,7 @@ export function createInMemorySddStores() {
         discoveryIndex: new InMemoryAdapter(DiscoveryIndexStateSchema, () => ({ version: 1, counters: { INS: 0, DEB: 0, RAD: 0, EPIC: 0, FEAT: 0, FGAP: 0, TD: 0 }, records: [] })),
         backlog: new InMemoryAdapter(BacklogStateSchema, () => ({ version: 1, items: [] })),
         techDebt: new InMemoryAdapter(TechDebtStateSchema, () => ({ version: 1, items: [] })),
-        finalizeQueue: new InMemoryAdapter(FinalizeQueueStateSchema, () => ({ version: 1, items: [] })),
+        finalizeQueue: new InMemoryAdapter(FinalizeQueueStateSchema, () => ({ version: 1, items: [], history: [] })),
         skillCatalog: new InMemoryAdapter(SkillCatalogStateSchema, () => ({ version: 1, skills: [], bundles: [] })),
         unblockEvents: new InMemoryAdapter(UnblockEventsStateSchema, () => ({ version: 1, events: [] })),
         transitionLog: new InMemoryAdapter(TransitionLogStateSchema, () => ({ version: 1, events: [] })),