@devtrack-solution/codesdd 1.2.2 → 1.2.3

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

@@ -7,13 +7,17 @@ import { promisify } from 'node:util';
 import * as yaml from 'yaml';
 import { CLI_NAME } from '../branding.js';
 import { LENSES, validateDocumentAgainstLens } from './lenses.js';
+import { detectSddEntityType, normalizeFeatRef } from './entity-reference.js';
 import { TransitionEngine } from './domain/transition-engine.js';
-import { resolveOpenSpecSubpath } from './services/legacy-capability.service.js';
+import { resolveLegacySpecSubpath } 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 { buildWorkspacePolicyInjection } from './skill-policy-pool.js';
 import { stringifyWorkspaceYamlDocument } from './workspace-schemas.js';
+import { parseGovernanceFile } from './governance-parser.js';
+import { debateFrontmatterSchema } from './governance-schemas.js';
 export const execFileAsync = promisify(execFile);
 export const RADAR_TO_DISCOVERY_STATUS = {
     READY: 'READY',
@@ -55,7 +59,70 @@ export function findDiscoveryRecord(records, id) {
 }
 export function markdownDebateTemplate(insight, debateId) {
     const now = nowIso();
-    return `# Debate ${debateId}
+    const frontmatter = yaml
+        .stringify({
+        schema_version: 1,
+        artifact_type: 'DEB',
+        id: debateId,
+        title: `Debate ${debateId}: ${insight.title}`,
+        status: 'OPEN',
+        origin: {
+            type: 'insight',
+            ref: insight.id,
+        },
+        related_ids: [insight.id],
+        created_at: now,
+        updated_at: now,
+        decision: {
+            question: 'Decide ____ instead of ____ to solve ____.',
+            options: [
+                { id: 'A', label: 'Option A' },
+                { id: 'B', label: 'Option B' },
+                { id: 'C', label: 'Option C' },
+            ],
+            criteria: ['User impact', 'Implementation complexity', 'Technical risk', 'Operational cost', 'Delivery time'],
+            scoring: [
+                {
+                    criterion: 'User impact',
+                    weight: 3,
+                    scores: { A: 0, B: 0, C: 0 },
+                },
+                {
+                    criterion: 'Implementation complexity',
+                    weight: 2,
+                    scores: { A: 0, B: 0, C: 0 },
+                },
+                {
+                    criterion: 'Technical risk',
+                    weight: 3,
+                    scores: { A: 0, B: 0, C: 0 },
+                },
+                {
+                    criterion: 'Operational cost',
+                    weight: 2,
+                    scores: { A: 0, B: 0, C: 0 },
+                },
+                {
+                    criterion: 'Delivery time',
+                    weight: 2,
+                    scores: { A: 0, B: 0, C: 0 },
+                },
+            ],
+            mediator: {
+                choice: 'A',
+                rationale: '____',
+                accepted_risks: [],
+                reversal_conditions: [],
+            },
+            output: 'APPROVED',
+        },
+    })
+        .trim();
+    return `---
+${frontmatter}
+---
+
+# Debate ${debateId}
 
 ## 1) Decision Question (Required)
 Decide ____ instead of ____ to solve ____.
@@ -135,7 +202,25 @@ Decide ____ instead of ____ to solve ____.
 `;
 }
 export function markdownInsightTemplate(id, title, text) {
-    return `# Insight ${id}
+    const now = nowIso();
+    const frontmatter = yaml
+        .stringify({
+        schema_version: 1,
+        artifact_type: 'INS',
+        id,
+        title,
+        status: 'NEW',
+        origin: { type: 'user_prompt' },
+        related_ids: [],
+        created_at: now,
+        updated_at: now,
+    })
+        .trim();
+    return `---
+${frontmatter}
+---
+
+# Insight ${id}
 
 ## Title
 ${title}
@@ -145,14 +230,44 @@ ${text}
 `;
 }
 export function markdownRadarTemplate(debate, radarId, rationale) {
-    return `# Epic ${radarId}
+    const now = nowIso();
+    const summary = rationale || 'Approved summary pending explicit expansion from the source debate.';
+    const frontmatter = yaml
+        .stringify({
+        schema_version: 1,
+        artifact_type: 'EPIC',
+        id: radarId,
+        title: debate.title,
+        status: 'READY',
+        origin: { type: 'debate', ref: debate.id },
+        related_ids: [debate.id],
+        created_at: now,
+        updated_at: now,
+        approved_summary: summary,
+        quality_contract: {
+            scope: 'touched_scope',
+            unit_target_percent: 95,
+            integration_target_percent: 95,
+            evidence_mode: 'hybrid',
+        },
+        lock_domains: [],
+        produces: [],
+        consumes: [],
+        breakdown_policy: 'graph',
+    })
+        .trim();
+    return `---
+${frontmatter}
+---
+
+# Epic ${radarId}
 
 ## Origin
 - Debate: ${debate.id}
 - Base title: ${debate.title}
 
 ## Approved Summary
-${rationale || 'Approved summary pending explicit expansion from the source debate.'}
+${summary}
 
 ## Quality Contract
 - Default scope: touched_scope.
@@ -166,14 +281,44 @@ READY
 `;
 }
 export function markdownRadarFromDepositoTemplate(radarId, title, sourceCount, rationale) {
-    return `# Epic ${radarId}
+    const now = nowIso();
+    const summary = rationale || 'Initial planning generated from source inputs.';
+    const frontmatter = yaml
+        .stringify({
+        schema_version: 1,
+        artifact_type: 'EPIC',
+        id: radarId,
+        title,
+        status: 'READY',
+        origin: { type: 'source_intake' },
+        related_ids: [],
+        created_at: now,
+        updated_at: now,
+        approved_summary: summary,
+        quality_contract: {
+            scope: 'touched_scope',
+            unit_target_percent: 95,
+            integration_target_percent: 95,
+            evidence_mode: 'hybrid',
+        },
+        lock_domains: [],
+        produces: [],
+        consumes: [],
+        breakdown_policy: 'graph',
+    })
+        .trim();
+    return `---
+${frontmatter}
+---
+
+# Epic ${radarId}
 
 ## Origin
 - Origin: source intake
 - Indexed sources: ${sourceCount}
 
 ## Approved Summary
-${rationale || 'Initial planning generated from source inputs.'}
+${summary}
 
 ## Quality Contract
 - Default scope: touched_scope.
@@ -190,14 +335,37 @@ READY
 `;
 }
 export function markdownDiscardTemplate(debate, rationale) {
-    return `# Discarded ${debate.id}
+    const now = nowIso();
+    const reason = rationale || '(reason not provided)';
+    const frontmatter = yaml
+        .stringify({
+        schema_version: 1,
+        artifact_type: 'Discarded',
+        id: debate.id,
+        title: debate.title,
+        status: 'DISCARDED',
+        origin: { type: 'debate', ref: debate.id },
+        related_ids: [debate.id],
+        created_at: debate.created_at || now,
+        updated_at: now,
+        discarded_from: debate.id,
+        discard_reason: reason,
+        discarded_at: now,
+        discarded_by: CLI_NAME,
+    })
+        .trim();
+    return `---
+${frontmatter}
+---
+
+# Discarded ${debate.id}
 
 ## Origin
 - Debate: ${debate.id}
 - Title: ${debate.title}
 
 ## Discard Reason
-${rationale || '(reason not provided)'}
+${reason}
 `;
 }
 export const DEFAULT_META_EVOLUTION_CONFIG = {
@@ -369,6 +537,19 @@ export async function collectAuditArtifacts(paths) {
     return artifactFiles;
 }
 export function debateHasRealDeliberation(content) {
+    try {
+        const parsed = parseGovernanceFile('inline-content', content, debateFrontmatterSchema);
+        if (parsed.hasFrontmatter && parsed.frontmatter) {
+            const choice = parsed.frontmatter.decision.mediator.choice.trim().toLowerCase();
+            const rationale = parsed.frontmatter.decision.mediator.rationale.trim().toLowerCase();
+            const invalidTokens = ['(preencher', '(fill in', '____', '-', 'todo', 'tbd'];
+            const isInvalid = (value, token) => value === token || (token !== '-' && value.includes(token));
+            return !invalidTokens.some((token) => isInvalid(choice, token) || isInvalid(rationale, token));
+        }
+    }
+    catch {
+        return false;
+    }
     const lower = content.toLowerCase();
     const sectionIndexCandidates = [
         lower.indexOf('## 7) decisao do mediador'),
@@ -565,6 +746,37 @@ export async function findDebateFile(paths, debateId) {
     return path.join(debateDir, found.name);
 }
 export function validateDebateDocument(content) {
+    try {
+        const parsed = parseGovernanceFile('inline-content', content, debateFrontmatterSchema);
+        if (parsed.hasFrontmatter && parsed.frontmatter) {
+            const missing = [];
+            const question = parsed.frontmatter.decision.question.trim().toLowerCase();
+            if (!question || question.includes('____')) {
+                missing.push('Fill the decision question with real context');
+            }
+            const rationale = parsed.frontmatter.decision.mediator.rationale.trim().toLowerCase();
+            if (!rationale || rationale.includes('____') || rationale.includes('(fill in') || rationale.includes('(preencher')) {
+                missing.push('Inform the mediator decision rationale');
+            }
+            if (/\- Unit coverage:\s*$/m.test(parsed.body)) {
+                missing.push('Inform required unit coverage evidence in the quality contract');
+            }
+            if (/\- Integration\/e2e or equivalent:\s*$/m.test(parsed.body)) {
+                missing.push('Inform integration/e2e or equivalence evidence in the quality contract');
+            }
+            if (/\- Acceptance and risk matrix:\s*$/m.test(parsed.body)) {
+                missing.push('Inform acceptance and risk matrix evidence in the quality contract');
+            }
+            if (/\- Exceptions:\s*\n\s+- None, or formal exception/m.test(parsed.body)) {
+                missing.push('Confirm there is no quality exception or document the formal exception');
+            }
+            return missing;
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return [`Invalid debate frontmatter: ${message}`];
+    }
     const missing = validateDocumentAgainstLens(content, LENSES.debate);
     if (content.includes('Decidir ____ em vez de ____ para resolver ____.') ||
         content.includes('Decide ____ instead of ____ to solve ____.')) {
@@ -754,7 +966,7 @@ function workspaceExecutionProfileForFeature(feature) {
         return {
             id: 'frontend_typescript',
             label: 'frontend workflow',
-            description: 'frontend routes, UI coverage, and OpenSDD frontend guardrails',
+            description: 'frontend routes, UI coverage, and CodeSDD 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',
@@ -764,9 +976,9 @@ function workspaceExecutionProfileForFeature(feature) {
         };
     }
     return {
-        id: 'opensdd_typescript',
-        label: 'OpenSDD backend workflow',
-        description: 'OpenSDD state, command services, and backend validation flows',
+        id: 'codesdd_typescript',
+        label: 'CodeSDD backend workflow',
+        description: 'CodeSDD 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',
@@ -789,7 +1001,7 @@ export function buildActiveSpecDoc(feature) {
         },
         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),
+        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 CodeSDD 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,
@@ -808,6 +1020,7 @@ export function buildActiveSpecDoc(feature) {
 }
 export function buildActivePlanDoc(feature, recommendedBundles) {
     const profile = workspaceExecutionProfileForFeature(feature);
+    const policyInjection = buildWorkspacePolicyInjection(feature.recommended_skills);
     const affectedContracts = [
         ...feature.consumes.map((name) => ({ name, change_type: 'consumes' })),
         ...feature.produces.map((name) => ({ name, change_type: 'produces' })),
@@ -836,6 +1049,7 @@ export function buildActivePlanDoc(feature, recommendedBundles) {
             detected_conflicts: [],
             architecture_tree_ascii: profile.architectureTreeAscii,
         },
+        policy_injection: policyInjection,
     };
     if (isPrivacyComplianceFeature(feature)) {
         baseDocument.privacy_controls = {
@@ -855,6 +1069,8 @@ export function buildActiveQualityDoc(feature) {
     const profile = workspaceExecutionProfileForFeature(feature);
     const targetedTestCommand = testCommandForFeature(feature);
     const requiredSkillIds = Array.from(new Set(feature.recommended_skills.filter(Boolean)));
+    const requirementRefs = Array.from(new Set([`${feature.id}-R1`, ...(feature.acceptance_refs ?? []).map((ref) => ref.trim()).filter(Boolean)]));
+    const policyInjection = buildWorkspacePolicyInjection(requiredSkillIds);
     const baseDocument = {
         schema_version: 1,
         feature_id: feature.id,
@@ -877,6 +1093,14 @@ export function buildActiveQualityDoc(feature) {
         evidence_log: [],
         skill_evidence: {
             required_skill_ids: requiredSkillIds,
+            policy_requirements: policyInjection.required_policies.map((policy) => ({
+                skill_id: policy.skill_id,
+                policy_pool_ref: policy.policy_pool_ref,
+                source_contract_ref: policy.source_contract_ref,
+                enforcement: policy.enforcement,
+                required_rule_refs: policy.required_rule_refs,
+                required_evidence: policy.required_evidence,
+            })),
             evidence: [],
             verification_rule: requiredSkillIds.length > 0
                 ? `Record one evidence entry per required skill before finalize: ${requiredSkillIds.join(', ')}.`
@@ -887,6 +1111,14 @@ export function buildActiveQualityDoc(feature) {
             status: 'not_met',
             evidence: 'Evidence must be recorded before finalize.',
         })),
+        requirement_validation_evidence_risk_matrix: requirementRefs.map((requirementRef) => ({
+            requirement_ref: requirementRef,
+            validation_refs: ['Targeted tests', 'Build'],
+            evidence_refs: ['Tasks must be completed with validation evidence.'],
+            residual_risk: 'Residual risk must be documented with mitigation before finalize.',
+            risk_status: 'open',
+        })),
+        policy_injection: policyInjection,
         exceptions: contract.exceptions.map((exception) => ({
             scope: exception.scope,
             reason: exception.reason,
@@ -904,6 +1136,47 @@ export function buildActiveQualityDoc(feature) {
             },
             requirements: [],
         },
+        q95_ledger: {
+            threshold: 95,
+            score: 0,
+            status: 'pending',
+            computed_at: '',
+            weights: {
+                coverage: 30,
+                traceability: 20,
+                integrity: 20,
+                naming: 10,
+                token: 20,
+            },
+            axes: {
+                coverage: {
+                    raw_score: 0,
+                    weighted_score: 0,
+                    rationale: 'Computed during finalize.',
+                },
+                traceability: {
+                    raw_score: 0,
+                    weighted_score: 0,
+                    rationale: 'Computed during finalize.',
+                },
+                integrity: {
+                    raw_score: 0,
+                    weighted_score: 0,
+                    rationale: 'Computed during finalize.',
+                },
+                naming: {
+                    raw_score: 0,
+                    weighted_score: 0,
+                    rationale: 'Computed during finalize.',
+                },
+                token: {
+                    raw_score: 0,
+                    weighted_score: 0,
+                    rationale: 'Computed during finalize.',
+                },
+            },
+            next_best_action: 'Record missing evidence to raise the lowest weighted axis.',
+        },
     };
     if (isPrivacyComplianceFeature(feature)) {
         baseDocument.security_integrity = {
@@ -926,18 +1199,23 @@ export function buildActiveTasksDoc(feature, paths) {
         ? feature.recommended_skills.join(', ')
         : 'architecture and api-design-principles';
     const summary = feature.summary || `Deliver ${feature.title} for ${scope.description}.`;
+    const policyInjection = buildWorkspacePolicyInjection(feature.recommended_skills);
+    const policySummary = policyInjection.required_policies.length > 0
+        ? ` Policy requirements injected for ${policyInjection.required_policies.map((policy) => policy.skill_id).join(', ')}.`
+        : '';
     return workspaceYamlDoc('3-tasks.yaml', {
         schema_version: 1,
         feature_id: feature.id,
+        policy_injection: policyInjection,
         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}`,
+                description: `Run ${CLI_NAME} sdd context ${feature.id}, confirm ${scope.description}, review ${skills}, and turn the feature summary into concrete acceptance checks: ${summary}${policySummary}`,
                 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.`,
+                acceptance: `The implementation plan names the ${scope.description} files, injected policy requirements, expected validation commands, and any dependency or lock-domain risk before edits begin.`,
                 status: 'pending',
             },
             {
@@ -947,7 +1225,7 @@ export function buildActiveTasksDoc(feature, paths) {
                 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.`,
+                acceptance: `The ${scope.label} behavior is implemented, uses existing CodeSDD patterns, and keeps generated workspace/state artifacts valid.`,
                 status: 'pending',
             },
             {
@@ -985,16 +1263,32 @@ export function buildActiveTasksDoc(feature, paths) {
                 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'],
+                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}. After finalize, run ${CLI_NAME} sdd diagnose and ${CLI_NAME} sdd check --render, confirm ${feature.id} is DONE with current_stage consolidacao, confirm done_at and archived_at are set, confirm .sdd/archived/${feature.id}/ exists, confirm .sdd/active/${feature.id}/ no longer exists, and triage any remote security warnings such as Dependabot as an in-scope fix, formal exception, or follow-up SDD item before reporting completion.`,
+                files_touched: [
+                    '.sdd/active/<FEAT-ID>/5-quality.yaml',
+                    '.sdd/archived/<FEAT-ID>/',
+                    '.sdd/state/backlog.yaml',
+                    '.sdd/state/finalize-queue.yaml',
+                    '.sdd/state/transition-log.yaml',
+                ],
                 test_scripts: [
                     {
                         command: profile.buildCommand,
                         type: 'build',
                         expected: profile.buildExpected,
                     },
+                    {
+                        command: `${CLI_NAME} sdd diagnose`,
+                        type: 'sdd',
+                        expected: 'SDD structural health is healthy after finalize.',
+                    },
+                    {
+                        command: `${CLI_NAME} sdd check --render`,
+                        type: 'sdd',
+                        expected: 'Rendered SDD state is valid and completed FEAT status is coherent.',
+                    },
                 ],
-                acceptance: 'Frontend impact is declared, quality coverage targets are met or formally excepted, and SDD finalize succeeds without unresolved re-task rounds.',
+                acceptance: `${feature.id} is DONE in .sdd/state/backlog.yaml, current_stage is consolidacao, done_at and archived_at are set, the workspace lives under .sdd/archived/${feature.id}/, no .sdd/active/${feature.id}/ residue remains, SDD diagnose/check pass, and any remote security warning observed during push or validation is recorded with a fix, exception, or follow-up SDD reference.`,
                 status: 'pending',
             },
         ],
@@ -1008,9 +1302,25 @@ function taskScopeForFeature(feature) {
         feature.summary || '',
     ].join(' ').toLowerCase();
     const profile = workspaceExecutionProfileForFeature(feature);
-    if (profile.id !== 'opensdd_typescript') {
+    if (profile.id !== 'codesdd_typescript') {
         return { label: profile.label, description: profile.description };
     }
+    if (includesAny(tokens, [
+        'creditos',
+        'créditos',
+        'clean-room',
+        'clean room',
+        'licenca',
+        'licença',
+        'license',
+        'notices',
+        'notice',
+    ])) {
+        return {
+            label: 'governance docs workflow',
+            description: 'credits clean-room boundary, runtime license notices, and repository documentation governance',
+        };
+    }
     if (tokens.includes('skill')) {
         return { label: 'skill distribution workflow', description: 'built-in skills, skill catalog state, and distribution templates' };
     }
@@ -1018,7 +1328,7 @@ function taskScopeForFeature(feature) {
         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: 'CodeSDD backend workflow', description: 'CodeSDD state, command services, and backend validation flows' };
     }
     return { label: 'feature scope', description: feature.touches.join(', ') || 'the declared feature scope' };
 }
@@ -1038,6 +1348,22 @@ function filesForFeatureScope(feature, paths) {
         ];
     }
     const files = new Set();
+    if (includesAny(tokens, [
+        'creditos',
+        'créditos',
+        'clean-room',
+        'clean room',
+        'licenca',
+        'licença',
+        'license',
+        'notices',
+        'notice',
+    ])) {
+        files.add('docs/CREDITS.md');
+        files.add('docs/THIRD_PARTY_NOTICES.md');
+        files.add('README.md');
+        files.add('src/core/sdd/legacy-operations.ts');
+    }
     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');
@@ -1073,6 +1399,19 @@ function testCommandForFeature(feature) {
         feature.title,
         feature.summary || '',
     ].join(' ').toLowerCase();
+    if (includesAny(tokens, [
+        'creditos',
+        'créditos',
+        'clean-room',
+        'clean room',
+        'licenca',
+        'licença',
+        'license',
+        'notices',
+        'notice',
+    ])) {
+        return 'pnpm test -- test/core/sdd-operations.test.ts';
+    }
     if (tokens.includes('quality') || tokens.includes('task') || tokens.includes('finalize')) {
         return 'pnpm test -- test/core/sdd/task-quality-schemas.test.ts';
     }
@@ -1192,9 +1531,10 @@ export function resolveRadar(record) {
     }
 }
 export function resolveFeat(items, id) {
-    const feat = items.find((item) => item.id === id);
+    const normalizedId = normalizeFeatRef(id) ?? id.trim();
+    const feat = items.find((item) => item.id === normalizedId);
     if (!feat) {
-        throw new Error(`Feature ${id} nao encontrada no backlog.`);
+        throw new Error(`Feature ${normalizedId} nao encontrada no backlog.`);
     }
     return feat;
 }
@@ -1291,6 +1631,38 @@ export function classifyFeatureShape(title, contextTokens = []) {
     const titleNormalized = title.toLowerCase();
     const contextNormalized = contextTokens.join(' ').toLowerCase();
     const normalized = [titleNormalized, contextNormalized].join(' ').toLowerCase();
+    const isDocumentationGovernanceWork = includesAny(normalized, [
+        'docs',
+        'documentacao',
+        'documentation',
+        'adr',
+        'manual',
+        'review',
+        'revisao',
+        'migration plan',
+        'plano de migracao',
+        'naming',
+        'nomeacao',
+    ]) &&
+        !includesAny(normalized, [
+            'seed',
+            'backfill',
+            'database migration',
+            'db migration',
+            'schema migration',
+            'migracao de banco',
+            'migracao de dados',
+        ]);
+    if (isDocumentationGovernanceWork) {
+        return {
+            executionKind: 'documentation',
+            touches: ['docs'],
+            lockDomains: [],
+            produces: ['documentacao-atualizada'],
+            consumes: ['implementacao-concluida'],
+            planningMode: 'direct_tasks',
+        };
+    }
     if (includesAny(normalized, ['migracao', 'migration', 'seed', 'backfill'])) {
         return {
             executionKind: 'migration',
@@ -1368,7 +1740,7 @@ export function classifyFeatureShape(title, contextTokens = []) {
             planningMode: 'local_plan',
         };
     }
-    if (includesAny(normalized, ['docs', 'documentacao', 'adr', 'manual'])) {
+    if (includesAny(normalized, ['docs', 'documentacao', 'documentation', 'adr', 'manual'])) {
         return {
             executionKind: 'documentation',
             touches: ['docs'],
@@ -1608,8 +1980,12 @@ export async function maybeCreateAutomaticFrontendGap(paths, snapshot, feature,
 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 hasPythonApiOverride = touches.some((touch) => ['python', 'flask', 'langgraph', 'langchain'].includes(touch));
+    const routeTouches = hasPythonApiOverride
+        ? touches.filter((touch) => touch !== 'backend' && touch !== 'api')
+        : touches;
+    if (routeTouches.length > 0 && snapshot.skillRouting && snapshot.skillRouting.routes) {
+        for (const touch of routeTouches) {
             const route = snapshot.skillRouting.routes.find((r) => r.domain === touch);
             if (route && route.skills) {
                 injectedSkills.push(...route.skills);
@@ -1641,7 +2017,7 @@ export function inferOriginType(input) {
 }
 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');
+    const archiveRoot = resolveLegacySpecSubpath(paths.projectRoot, 'changes', 'archive');
     for (const item of backlogItems) {
         if (!item.change_name)
             continue;
@@ -1708,8 +2084,30 @@ export async function evaluateFeatureQuality(paths, config, feature) {
     };
 }
 export function buildAdrMarkdown(feature, unlocked, timestamp) {
-    const refs = [feature.id, feature.origin_ref].filter(Boolean).join(', ') || '-';
-    return `# ADR ${feature.id}
+    const refs = [feature.id, feature.origin_ref].filter(Boolean);
+    const refsText = refs.join(', ') || '-';
+    const frontmatter = yaml
+        .stringify({
+        schema_version: 1,
+        artifact_type: 'ADR',
+        id: `ADR-${feature.id}`,
+        feature_id: feature.id,
+        title: `ADR ${feature.id}: ${feature.title}`,
+        status: feature.status,
+        origin: { type: 'feature', ref: feature.id },
+        related_ids: refs,
+        created_at: timestamp,
+        updated_at: timestamp,
+        decision_status: 'ACCEPTED',
+        supersedes: [],
+        superseded_by: [],
+        references: refs,
+    })
+        .trim();
+    return `---
+${frontmatter}
+---
+# ADR ${feature.id}
 
 ## Context
 - Feature: ${feature.id} - ${feature.title}
@@ -1732,7 +2130,7 @@ Consolidate feature ${feature.id} and make the result official in SDD memory.
 ${unlocked.length > 0 ? unlocked.map((id) => `- ${id}`).join('\n') : '- None'}
 
 ## References
-- ${refs}
+- ${refsText}
 `;
 }
 export function applyLoggedTransition(transitionLog, entityType, entity, toStatus, options) {
@@ -1762,17 +2160,7 @@ 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;
+    return detectSddEntityType(ref);
 }
 export async function pathExists(targetPath) {
     try {
@@ -2170,6 +2558,6 @@ 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.`;
+4. Finalize com proximos comandos CodeSDD recomendados.`;
 }
 //# sourceMappingURL=legacy-operations.js.map