@devtrack-solution/codesdd 1.2.2 → 1.2.3

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

@@ -1,4 +1,10 @@
+import { type SddPaths, type SddRuntimeConfig, type SddStateSnapshot } from './state.js';
 import { type StructuralDiagnosticReport } from './structural-health.js';
+import type { BacklogItem } from './types.js';
+export type Finding = StructuralDiagnosticReport['findings'][number];
+export type FindingSeverity = Finding['severity'];
+export type FindingCategory = Finding['category'];
+export type SanitizerDisposition = Finding['sanitizer']['disposition'];
 export interface SddDiagnoseOptions {
     strict?: boolean;
 }
@@ -14,6 +20,59 @@ export interface SddDiagnoseResult {
 export declare class SddDiagnosticOptionsError extends Error {
     constructor(message: string);
 }
+export declare function projectRelative(projectRoot: string, targetPath: string): string;
+export declare function isInsidePath(rootPath: string, candidatePath: string): boolean;
+export declare function pathExists(targetPath: string): Promise<boolean>;
+export declare function safeRealpath(targetPath: string): Promise<string>;
+export declare function addFinding(findings: Finding[], input: {
+    finding_id: string;
+    rule_id: string;
+    category: FindingCategory;
+    severity: FindingSeverity;
+    summary: string;
+    evidence?: Record<string, unknown>;
+    location?: string;
+    sanitizer: {
+        disposition: SanitizerDisposition;
+        reason: string;
+        actions?: string[];
+    };
+}): void;
+export declare function duplicateIdFindings<T extends {
+    id: string;
+}>(findings: Finding[], items: T[], scope: string, filePath: string): void;
+export declare function zodIssuePath(pathSegments: PropertyKey[]): string;
+export declare function normalizeFindingToken(input: string): string;
+export declare function listFeatureWorkspaceDirs(rootDir: string, lifecycleRoot: 'planned' | 'active' | 'archived'): Promise<Array<{
+    featureId: string;
+    lifecycleRoot: 'planned' | 'active' | 'archived';
+    dirPath: string;
+}>>;
+export declare function hasLegacyMarkdown(workspaceDir: string): Promise<boolean>;
+export declare function collectWorkspaceSchemaFindings(findings: Finding[], paths: SddPaths): Promise<void>;
+export declare function collectWorkspaceAllowlistFindings(findings: Finding[], paths: SddPaths): Promise<void>;
+export declare function collectLifecycleViolationFindings(findings: Finding[], paths: SddPaths, backlogItems: BacklogItem[]): Promise<void>;
+export declare function qualityEvidenceReferencesCoverage(evidenceLog: Array<{
+    kind: string;
+    result: string;
+    artifact?: string;
+}>, targets: {
+    unit: number;
+    integration: number;
+}): boolean;
+export declare function collectQualityEvidenceFindings(findings: Finding[], paths: SddPaths, backlogItems: BacklogItem[]): Promise<void>;
+export declare function collectTraceabilityFindings(findings: Finding[], paths: SddPaths, backlogItems: BacklogItem[]): Promise<void>;
+export declare function isPrivacyComplianceBacklogItem(item: BacklogItem): boolean;
+export declare function collectPrivacyComplianceFindings(findings: Finding[], paths: SddPaths, snapshot: SddStateSnapshot): Promise<void>;
+export declare function collectDuplicateIdFindings(findings: Finding[], snapshot: SddStateSnapshot, paths: SddPaths): void;
+export declare function addBrokenReference(findings: Finding[], ref: string, owner: string, relation: string, location: string): void;
+export declare function collectReferenceFindings(findings: Finding[], snapshot: SddStateSnapshot, paths: SddPaths): void;
+export declare function collectDirectoryFindings(findings: Finding[], config: SddRuntimeConfig, paths: SddPaths): Promise<void>;
+export declare function collectStateFileFindings(findings: Finding[], config: SddRuntimeConfig, paths: SddPaths): Promise<void>;
+export declare function collectLifecyclePlacementFindings(findings: Finding[], paths: SddPaths, backlogItems: BacklogItem[]): Promise<void>;
+export declare function newestMtime(filePaths: string[]): Promise<number>;
+export declare function collectGeneratedViewFindings(findings: Finding[], config: SddRuntimeConfig, paths: SddPaths): Promise<void>;
+export declare function collectBoundaryFindings(findings: Finding[], paths: SddPaths): Promise<void>;
 export declare function getDiagnosticExitCode(report: StructuralDiagnosticReport): number;
 export declare function getDiagnosticHealth(report: StructuralDiagnosticReport): SddDiagnoseResult['health'];
 export declare function diagnoseSddRoot(projectRoot: string, options?: SddDiagnoseOptions): Promise<StructuralDiagnosticReport>;

package/dist/core/sdd/diagnose.js

@@ -22,15 +22,15 @@ export class SddDiagnosticOptionsError extends Error {
         this.name = 'SddDiagnosticOptionsError';
     }
 }
-function projectRelative(projectRoot, targetPath) {
+export function projectRelative(projectRoot, targetPath) {
     const relative = path.relative(projectRoot, targetPath);
     return relative.length > 0 ? relative : '.';
 }
-function isInsidePath(rootPath, candidatePath) {
+export function isInsidePath(rootPath, candidatePath) {
     const relative = path.relative(rootPath, candidatePath);
     return relative === '' || (!!relative && !relative.startsWith('..') && !path.isAbsolute(relative));
 }
-async function pathExists(targetPath) {
+export async function pathExists(targetPath) {
     try {
         await fs.access(targetPath);
         return true;
@@ -39,7 +39,7 @@ async function pathExists(targetPath) {
         return false;
     }
 }
-async function safeRealpath(targetPath) {
+export async function safeRealpath(targetPath) {
     try {
         return await fs.realpath(targetPath);
     }
@@ -47,7 +47,7 @@ async function safeRealpath(targetPath) {
         return path.resolve(targetPath);
     }
 }
-function addFinding(findings, input) {
+export function addFinding(findings, input) {
     findings.push(StructuralFindingSchema.parse({
         evidence: {},
         ...input,
@@ -57,7 +57,7 @@ function addFinding(findings, input) {
         },
     }));
 }
-function duplicateIdFindings(findings, items, scope, filePath) {
+export function duplicateIdFindings(findings, items, scope, filePath) {
     const seen = new Set();
     const duplicates = new Set();
     for (const item of items) {
@@ -82,13 +82,13 @@ function duplicateIdFindings(findings, items, scope, filePath) {
         });
     }
 }
-function zodIssuePath(pathSegments) {
+export function zodIssuePath(pathSegments) {
     return pathSegments.length > 0 ? pathSegments.join('.') : '<root>';
 }
-function normalizeFindingToken(input) {
+export function normalizeFindingToken(input) {
     return input.toUpperCase().replace(/[^A-Z0-9]+/g, '-').replace(/^-+|-+$/g, '');
 }
-async function listFeatureWorkspaceDirs(rootDir, lifecycleRoot) {
+export async function listFeatureWorkspaceDirs(rootDir, lifecycleRoot) {
     const entries = await fs.readdir(rootDir, { withFileTypes: true }).catch(() => []);
     return entries
         .filter((entry) => entry.isDirectory() && FEATURE_WORKSPACE_PATTERN.test(entry.name))
@@ -98,11 +98,11 @@ async function listFeatureWorkspaceDirs(rootDir, lifecycleRoot) {
         dirPath: path.join(rootDir, entry.name),
     }));
 }
-async function hasLegacyMarkdown(workspaceDir) {
+export async function hasLegacyMarkdown(workspaceDir) {
     const entries = await fs.readdir(workspaceDir, { withFileTypes: true }).catch(() => []);
     return entries.some((entry) => entry.isFile() && entry.name.endsWith('.md'));
 }
-async function collectWorkspaceSchemaFindings(findings, paths) {
+export async function collectWorkspaceSchemaFindings(findings, paths) {
     const workspaces = [
         ...(await listFeatureWorkspaceDirs(paths.plannedDir, 'planned')),
         ...(await listFeatureWorkspaceDirs(paths.activeDir, 'active')),
@@ -143,7 +143,7 @@ async function collectWorkspaceSchemaFindings(findings, paths) {
                             ? 'Legacy markdown exists and should be migrated into schema-valid workspace YAML.'
                             : 'Workspace YAML cannot be repaired automatically without losing feature-specific intent.',
                         actions: legacyMarkdown
-                            ? [`opensdd sdd migrate-workspace --feat ${workspace.featureId}`]
+                            ? [`codesdd sdd migrate-workspace --feat ${workspace.featureId}`]
                             : [`edit ${relativePath} to match ${entry.name} schema`],
                     },
                 });
@@ -175,14 +175,14 @@ async function collectWorkspaceSchemaFindings(findings, paths) {
                         ? 'Legacy markdown exists and should be migrated into schema-valid workspace YAML.'
                         : 'Workspace YAML requires schema-aware manual editing.',
                     actions: legacyMarkdown
-                        ? [`opensdd sdd migrate-workspace --feat ${workspace.featureId}`]
-                        : [`edit ${relativePath} and rerun opensdd sdd diagnose`],
+                        ? [`codesdd sdd migrate-workspace --feat ${workspace.featureId}`]
+                        : [`edit ${relativePath} and rerun codesdd sdd diagnose`],
                 },
             });
         }
     }
 }
-async function collectWorkspaceAllowlistFindings(findings, paths) {
+export async function collectWorkspaceAllowlistFindings(findings, paths) {
     const workspaces = [
         ...(await listFeatureWorkspaceDirs(paths.plannedDir, 'planned')),
         ...(await listFeatureWorkspaceDirs(paths.activeDir, 'active')),
@@ -200,7 +200,7 @@ async function collectWorkspaceAllowlistFindings(findings, paths) {
                 rule_id: 'SH-RULE-WORKSPACE-FILE-NOT-ALLOWLISTED',
                 category: 'integrity',
                 severity: 'warning',
-                summary: `${workspace.featureId} contains a workspace file outside the OpenSDD allowlist: ${entry.name}.`,
+                summary: `${workspace.featureId} contains a workspace file outside the CodeSDD allowlist: ${entry.name}.`,
                 location: relativePath,
                 evidence: {
                     id: workspace.featureId,
@@ -216,7 +216,7 @@ async function collectWorkspaceAllowlistFindings(findings, paths) {
                         : 'Non-allowlisted files may contain user data and require confirmation before relocation.',
                     actions: [
                         entry.name.endsWith('.md')
-                            ? `opensdd sdd migrate-workspace --feat ${workspace.featureId}`
+                            ? `codesdd sdd migrate-workspace --feat ${workspace.featureId}`
                             : 'move the file to .sdd/backup after review',
                         'remove the file only after confirming it is obsolete',
                     ],
@@ -225,7 +225,7 @@ async function collectWorkspaceAllowlistFindings(findings, paths) {
         }
     }
 }
-async function collectLifecycleViolationFindings(findings, paths, backlogItems) {
+export async function collectLifecycleViolationFindings(findings, paths, backlogItems) {
     const byId = new Map(backlogItems.map((item) => [item.id, item]));
     const checks = [
         { root: 'planned', dir: paths.plannedDir, expectedStatus: 'READY' },
@@ -261,7 +261,7 @@ async function collectLifecycleViolationFindings(findings, paths, backlogItems)
         }
     }
 }
-function qualityEvidenceReferencesCoverage(evidenceLog, targets) {
+export function qualityEvidenceReferencesCoverage(evidenceLog, targets) {
     if (evidenceLog.length === 0)
         return false;
     const evidenceText = evidenceLog
@@ -272,7 +272,7 @@ function qualityEvidenceReferencesCoverage(evidenceLog, targets) {
         evidenceText.includes(`${targets.unit}`) ||
         evidenceText.includes(`${targets.integration}`));
 }
-async function collectQualityEvidenceFindings(findings, paths, backlogItems) {
+export async function collectQualityEvidenceFindings(findings, paths, backlogItems) {
     const byId = new Map(backlogItems.map((item) => [item.id, item]));
     const activeWorkspaces = await listFeatureWorkspaceDirs(paths.activeDir, 'active');
     for (const workspace of activeWorkspaces) {
@@ -326,7 +326,7 @@ async function collectQualityEvidenceFindings(findings, paths, backlogItems) {
                 sanitizer: {
                     disposition: 'manual',
                     reason: 'Fix the quality YAML so coverage evidence can be validated before finalize.',
-                    actions: [`edit ${relativePath} and rerun opensdd sdd diagnose`],
+                    actions: [`edit ${relativePath} and rerun codesdd sdd diagnose`],
                 },
             });
             continue;
@@ -356,7 +356,7 @@ async function collectQualityEvidenceFindings(findings, paths, backlogItems) {
         });
     }
 }
-async function collectTraceabilityFindings(findings, paths, backlogItems) {
+export async function collectTraceabilityFindings(findings, paths, backlogItems) {
     const byId = new Map(backlogItems.map((item) => [item.id, item]));
     const activeWorkspaces = await listFeatureWorkspaceDirs(paths.activeDir, 'active');
     for (const workspace of activeWorkspaces) {
@@ -419,7 +419,7 @@ async function collectTraceabilityFindings(findings, paths, backlogItems) {
                 sanitizer: {
                     disposition: 'manual',
                     reason: 'Fix the workspace YAML before validating traceability closure.',
-                    actions: [`edit ${relativePath} and rerun opensdd sdd diagnose`],
+                    actions: [`edit ${relativePath} and rerun codesdd sdd diagnose`],
                 },
             });
             continue;
@@ -447,13 +447,13 @@ async function collectTraceabilityFindings(findings, paths, backlogItems) {
         });
     }
 }
-function isPrivacyComplianceBacklogItem(item) {
+export function isPrivacyComplianceBacklogItem(item) {
     if (item.origin_ref === 'EPIC-0020' || item.origin_ref === 'EPIC-0021')
         return true;
     const refs = new Set(item.acceptance_refs || []);
     return refs.has('EPIC-0020') || refs.has('EPIC-0021') || refs.has('DEB-0021') || refs.has('INS-0021');
 }
-async function collectPrivacyComplianceFindings(findings, paths, snapshot) {
+export async function collectPrivacyComplianceFindings(findings, paths, snapshot) {
     const privacyItems = snapshot.backlog.items.filter((item) => item.status !== 'DONE' && item.status !== 'ARCHIVED' && isPrivacyComplianceBacklogItem(item));
     if (privacyItems.length === 0)
         return;
@@ -542,7 +542,7 @@ async function collectPrivacyComplianceFindings(findings, paths, snapshot) {
                 reason: 'Regulatory traceability requires explicit provenance and verification metadata.',
                 actions: [
                     `set authority/source_classification/last_verified_at/source_version/source_fingerprint for ${source.id}`,
-                    'rerun opensdd sdd check --render and opensdd sdd diagnose',
+                    'rerun codesdd sdd check --render and codesdd sdd diagnose',
                 ],
             },
         });
@@ -636,7 +636,7 @@ async function collectPrivacyComplianceFindings(findings, paths, snapshot) {
         }
     }
 }
-function collectDuplicateIdFindings(findings, snapshot, paths) {
+export function collectDuplicateIdFindings(findings, snapshot, paths) {
     duplicateIdFindings(findings, snapshot.discoveryIndex.records, 'discovery-index.records', projectRelative(paths.projectRoot, paths.stateFiles.discoveryIndex));
     duplicateIdFindings(findings, snapshot.backlog.items, 'backlog.items', projectRelative(paths.projectRoot, paths.stateFiles.backlog));
     duplicateIdFindings(findings, snapshot.techDebt.items, 'tech-debt.items', projectRelative(paths.projectRoot, paths.stateFiles.techDebt));
@@ -644,7 +644,7 @@ function collectDuplicateIdFindings(findings, snapshot, paths) {
         duplicateIdFindings(findings, snapshot.frontendGaps.items, 'frontend-gaps.items', projectRelative(paths.projectRoot, paths.stateFiles.frontendGaps));
     }
 }
-function addBrokenReference(findings, ref, owner, relation, location) {
+export function addBrokenReference(findings, ref, owner, relation, location) {
     addFinding(findings, {
         finding_id: `SH-BROKEN-REF-${owner}-${relation}-${ref}`.replace(/[^A-Z0-9-]/g, '-'),
         rule_id: 'SH-RULE-BROKEN-REFERENCE',
@@ -660,7 +660,7 @@ function addBrokenReference(findings, ref, owner, relation, location) {
         },
     });
 }
-function collectReferenceFindings(findings, snapshot, paths) {
+export function collectReferenceFindings(findings, snapshot, paths) {
     const discoveryIds = new Set(snapshot.discoveryIndex.records.map((record) => record.id));
     const backlogIds = new Set(snapshot.backlog.items.map((item) => item.id));
     const techDebtIds = new Set(snapshot.techDebt.items.map((item) => item.id));
@@ -702,7 +702,7 @@ function collectReferenceFindings(findings, snapshot, paths) {
         }
     }
 }
-async function collectDirectoryFindings(findings, config, paths) {
+export async function collectDirectoryFindings(findings, config, paths) {
     const requiredDirectories = [
         { semantic: 'memory', dir: paths.memoryRoot, severity: 'blocker' },
         { semantic: 'state', dir: paths.stateDir, severity: 'blocker' },
@@ -771,7 +771,7 @@ async function collectDirectoryFindings(findings, config, paths) {
         }
     }
 }
-async function collectStateFileFindings(findings, config, paths) {
+export async function collectStateFileFindings(findings, config, paths) {
     const requiredStateFiles = [
         paths.stateFiles.discoveryIndex,
         paths.stateFiles.backlog,
@@ -812,7 +812,7 @@ async function collectStateFileFindings(findings, config, paths) {
         }
     }
 }
-async function collectLifecyclePlacementFindings(findings, paths, backlogItems) {
+export async function collectLifecyclePlacementFindings(findings, paths, backlogItems) {
     const byId = new Map(backlogItems.map((item) => [item.id, item]));
     const plannedEntries = await fs.readdir(paths.plannedDir).catch(() => []);
     const activeEntries = await fs.readdir(paths.activeDir).catch(() => []);
@@ -985,7 +985,7 @@ async function collectLifecyclePlacementFindings(findings, paths, backlogItems)
         }
     }
 }
-async function newestMtime(filePaths) {
+export async function newestMtime(filePaths) {
     let newest = 0;
     for (const filePath of filePaths) {
         const stat = await fs.stat(filePath).catch(() => null);
@@ -994,7 +994,7 @@ async function newestMtime(filePaths) {
     }
     return newest;
 }
-async function collectGeneratedViewFindings(findings, config, paths) {
+export async function collectGeneratedViewFindings(findings, config, paths) {
     const generatedViews = [
         path.join(paths.pendenciasDir, 'backlog-features.md'),
         path.join(paths.pendenciasDir, 'backlog-graph.md'),
@@ -1029,7 +1029,7 @@ async function collectGeneratedViewFindings(findings, config, paths) {
                 sanitizer: {
                     disposition: 'safe',
                     reason: 'Generated views can be recreated from canonical state.',
-                    actions: ['run opensdd sdd check --render'],
+                    actions: ['run codesdd sdd check --render'],
                 },
             });
             continue;
@@ -1050,13 +1050,13 @@ async function collectGeneratedViewFindings(findings, config, paths) {
                 sanitizer: {
                     disposition: 'safe',
                     reason: 'Stale generated views can be refreshed from canonical state.',
-                    actions: ['run opensdd sdd check --render'],
+                    actions: ['run codesdd sdd check --render'],
                 },
             });
         }
     }
 }
-async function collectBoundaryFindings(findings, paths) {
+export async function collectBoundaryFindings(findings, paths) {
     if (!(await pathExists(paths.memoryRoot)))
         return;
     const memoryRootReal = await safeRealpath(paths.memoryRoot);

package/dist/core/sdd/docs-sync.js

@@ -39,6 +39,12 @@ Operational authority:
 - Human-readable operational views are derived from \`${memoryDir}/core/*.md\` and \`${memoryDir}/${config?.folders.planning || 'planning'}/*.md\`.
 - Do not use external context, memory, workflow, or backlog tools as a project source of truth.
 
+Initial operational directives:
+- CodeSDD is the official planner for any build request; other planners or agent-native plans are secondary execution aids only.
+- For API/backend work, use \`devtrack-api\` by default unless the user or SDD context explicitly selects another skill/profile; Python/Flask API work stays routed to \`api-clean-flask-langgraph\`.
+- During init, onboard, insight, and debate flows, CodeSDD-managed agent instruction blocks must be inspected and reconfigured when they drift from this contract.
+- Commit requests must follow Conventional Commits, selective staging, and grouping by modified directory plus change protocol (\`src\`, \`${memoryDir}\`, docs, config, infra, dependencies, or generated files).
+
 Read order for any new agent:
 1. \`README.md\` (this block)
 2. \`${memoryDir}/AGENT.md\`
@@ -57,7 +63,11 @@ Essential commands:
 - \`${CLI_NAME} sdd context <FEAT-ID>\`
 - update \`${memoryDir}/${config?.folders.active || 'active'}/<FEAT-ID>/5-quality.yaml\`
 - \`${CLI_NAME} sdd frontend-impact <FEAT-ID> --status required|none --reason "..."\`
-- \`${CLI_NAME} sdd finalize --ref <FEAT-ID>\``;
+- \`${CLI_NAME} sdd finalize --ref <FEAT-ID>\`
+- \`${CLI_NAME} sdd diagnose\`
+- \`${CLI_NAME} sdd check --render\`
+- confirm \`DONE\`, \`current_stage: consolidacao\`, \`done_at\`, \`archived_at\`, \`${memoryDir}/${config?.folders.archived || 'archived'}/<FEAT-ID>/\`, and no \`${memoryDir}/${config?.folders.active || 'active'}/<FEAT-ID>/\`
+- triage remote security warnings such as Dependabot as a fix, exception, or follow-up SDD item`;
 }
 function buildAgentGuideBlock(memoryDir, config) {
     const planningDir = config?.folders.planning || 'planning';
@@ -74,6 +84,9 @@ Official workflow:
 5. Update \`${memoryDir}/${activeDir}/<FEAT-ID>/5-quality.yaml\` with validation evidence or a formal exception.
 6. Declare frontend impact with \`${CLI_NAME} sdd frontend-impact <FEAT-ID> ...\`.
 7. After archiving the technical change, run \`${CLI_NAME} sdd finalize --ref <FEAT-ID>\`.
+8. After finalize, run \`${CLI_NAME} sdd diagnose\` and \`${CLI_NAME} sdd check --render\`.
+9. Confirm the FEAT is \`DONE\`, \`current_stage: consolidacao\`, has \`done_at\` and \`archived_at\`, is present under \`${memoryDir}/${config?.folders.archived || 'archived'}/<FEAT-ID>/\`, and has no \`${memoryDir}/${activeDir}/<FEAT-ID>/\` residue.
+10. Triage remote security warnings such as Dependabot as an in-scope fix, formal exception, or follow-up SDD item before reporting completion.
 
 - Canonical state: \`${memoryDir}/state/*.yaml\`
 - Views: \`${memoryDir}/core/*.md\` and \`${memoryDir}/${planningDir}/*.md\`
@@ -84,14 +97,20 @@ Official workflow:
 
 Operational exclusivity:
 - Do not consult or persist planning, backlog, workflow status, handoff, or project memory in external context stores.
-- If legacy notes conflict with OpenSDD, migrate useful decisions into \`${memoryDir}/state/*.yaml\`, \`${memoryDir}/active/<FEAT-ID>/\`, or the relevant OpenSDD guide, then ignore the legacy note.
-- Current repository files remain the implementation fact source; OpenSDD remains the operational state source.`;
+- If legacy notes conflict with CodeSDD, migrate useful decisions into \`${memoryDir}/state/*.yaml\`, \`${memoryDir}/active/<FEAT-ID>/\`, or the relevant CodeSDD guide, then ignore the legacy note.
+- Current repository files remain the implementation fact source; CodeSDD remains the operational state source.
+
+Initial directives:
+- CodeSDD is the official planner for requested work; model-native plans and other planning tools are subordinate to CodeSDD artifacts.
+- API/backend work uses \`devtrack-api\` by default unless an explicit skill/profile says otherwise; Python/Flask API work uses \`api-clean-flask-langgraph\`.
+- CodeSDD-managed blocks in \`AGENTS.md\`, \`AGENT.md\`, \`CLAUDE.md\`, \`GEMINI.md\`, \`.codex\`, \`.opencode\`, \`.ai\`, \`.cloud\`, or equivalent agent files must be inspected and normalized during init/onboard/insight/debate when CodeSDD owns project governance.
+- Commits must use Conventional Commits, selective staging, and grouping by modified directory plus protocol: source, \`${memoryDir}\`, docs, config, infra, dependencies, generated files, renames, or deletions.`;
 }
 function buildRootAgentsBlock(memoryDir) {
     return `## SDD Operational Contract
 
 Agents working in this repository must treat documentation sync as part of feature completion.
-OpenSDD is the only canonical operational state system for this repository.
+CodeSDD is the only canonical operational state system for this repository.
 
 Required execution order:
 1. Run \`${CLI_NAME} sdd onboard system\` before broad work.
@@ -106,9 +125,18 @@ Required execution order:
    - \`AGENTS.md\`
    - \`AGENT.md\`
 7. Run \`${CLI_NAME} sdd finalize --ref <FEAT-ID>\` to consolidate memory.
+8. After finalize, run \`${CLI_NAME} sdd diagnose\` and \`${CLI_NAME} sdd check --render\`.
+9. Confirm the completed FEAT is \`DONE\` in \`${memoryDir}/state/backlog.yaml\`, has \`current_stage: consolidacao\`, has \`done_at\` and \`archived_at\`, lives under \`${memoryDir}/archived/<FEAT-ID>/\`, and no longer has \`${memoryDir}/active/<FEAT-ID>/\` residue.
+10. If push or validation reports a remote security warning such as Dependabot, record the triage result in CodeSDD as an in-scope fix, formal exception, or follow-up SDD item before reporting completion.
 
 Canonical state lives in \`${memoryDir}/state/*.yaml\`. Markdown files are operational views or guides derived from that state.
-Do not use external context, memory, workflow, backlog, scratchpad, or handoff tools as a project source of truth. If legacy material is useful, repatriate it into OpenSDD and remove or deprecate the legacy artifact.`;
+Do not use external context, memory, workflow, backlog, scratchpad, or handoff tools as a project source of truth. If legacy material is useful, repatriate it into CodeSDD and remove or deprecate the legacy artifact.
+
+Initial directives:
+- CodeSDD is the official planner. Other planning systems may assist execution only after CodeSDD context exists.
+- API/backend work defaults to \`devtrack-api\` unless an explicit skill/profile overrides it; Python/Flask API work remains a documented exception routed to \`api-clean-flask-langgraph\`.
+- CodeSDD lifecycle entrypoints must inspect and normalize CodeSDD-managed agent instruction blocks in root and tool-specific agent files.
+- Commit work must use Conventional Commits, selective staging, and directory/protocol grouping. Source changes, \`${memoryDir}\` governance, docs, config, infra, dependencies, generated files, renames, and deletions should be staged and committed separately unless indivisible.`;
 }
 export async function syncSddGuideDocs(projectRoot, paths, config) {
     const readmePath = path.join(projectRoot, 'README.md');

package/dist/core/sdd/domain/post-active-validation.d.ts

@@ -9,6 +9,13 @@ export interface PostActiveValidationResult {
     ok: boolean;
     reasons: string[];
 }
+export interface ArchivedActiveReference {
+    feature_id: string;
+    path: string;
+    message: string;
+}
+export declare function normalizeArchivedFeatureActiveReferences(paths: SddPaths, featureId: string): Promise<string[]>;
+export declare function detectArchivedFeatureActiveReferences(paths: SddPaths, featureId: string): Promise<ArchivedActiveReference[]>;
 export declare function detectArchiveArchivedLifecycleCollisions(paths: SddPaths, featureId?: string): Promise<ArchiveArchivedLifecycleCollision[]>;
 export declare function validatePreFinalizeArchiveCanonicalization(paths: SddPaths, featureId: string): Promise<PostActiveValidationResult>;
 export declare function validatePostActiveFeaturePlacement(paths: SddPaths, featureId: string): Promise<PostActiveValidationResult>;

package/dist/core/sdd/domain/post-active-validation.js

@@ -17,6 +17,65 @@ function relativePath(paths, targetPath) {
 function legacyArchiveRoot(paths) {
     return path.join(paths.memoryRoot, LEGACY_ARCHIVE_DIR);
 }
+async function listFiles(root) {
+    const entries = await fs.readdir(root, { withFileTypes: true }).catch(() => []);
+    const files = [];
+    for (const entry of entries) {
+        const fullPath = path.join(root, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...(await listFiles(fullPath)));
+        }
+        else if (entry.isFile()) {
+            files.push(fullPath);
+        }
+    }
+    return files;
+}
+function archivedActiveReferenceNeedle(featureId) {
+    return `.sdd/active/${featureId}`;
+}
+function archivedFeatureReference(featureId) {
+    return `.sdd/archived/${featureId}`;
+}
+export async function normalizeArchivedFeatureActiveReferences(paths, featureId) {
+    const archivedFeaturePath = path.join(paths.archivedDir, featureId);
+    if (!(await exists(archivedFeaturePath))) {
+        return [];
+    }
+    const needle = archivedActiveReferenceNeedle(featureId);
+    const replacement = archivedFeatureReference(featureId);
+    const updated = [];
+    for (const filePath of await listFiles(archivedFeaturePath)) {
+        const content = await fs.readFile(filePath, 'utf-8').catch(() => '');
+        if (!content.includes(needle)) {
+            continue;
+        }
+        await fs.writeFile(filePath, content.split(needle).join(replacement), 'utf-8');
+        updated.push(relativePath(paths, filePath));
+    }
+    return updated;
+}
+export async function detectArchivedFeatureActiveReferences(paths, featureId) {
+    const archivedFeaturePath = path.join(paths.archivedDir, featureId);
+    if (!(await exists(archivedFeaturePath))) {
+        return [];
+    }
+    const needle = archivedActiveReferenceNeedle(featureId);
+    const references = [];
+    for (const filePath of await listFiles(archivedFeaturePath)) {
+        const content = await fs.readFile(filePath, 'utf-8').catch(() => '');
+        if (!content.includes(needle)) {
+            continue;
+        }
+        const relative = relativePath(paths, filePath);
+        references.push({
+            feature_id: featureId,
+            path: relative,
+            message: `${featureId} archived workspace file ${relative} references removed active workspace ${needle}.`,
+        });
+    }
+    return references;
+}
 export async function detectArchiveArchivedLifecycleCollisions(paths, featureId) {
     const legacyRoot = legacyArchiveRoot(paths);
     if (path.resolve(legacyRoot) === path.resolve(paths.archivedDir)) {
@@ -63,6 +122,8 @@ export async function validatePostActiveFeaturePlacement(paths, featureId) {
     }
     const collisions = await detectArchiveArchivedLifecycleCollisions(paths, featureId);
     reasons.push(...collisions.map((collision) => collision.message));
+    const activeReferences = await detectArchivedFeatureActiveReferences(paths, featureId);
+    reasons.push(...activeReferences.map((reference) => reference.message));
     return {
         ok: reasons.length === 0,
         reasons,

package/dist/core/sdd/domain/transition-engine.js

@@ -5,6 +5,7 @@ export class TransitionEngine {
             NEW: ['DEBATED', 'DISCARDED'],
         },
         DEB: {
+            DEBATED: ['APPROVED', 'DISCARDED'],
             OPEN: ['APPROVED', 'DISCARDED'],
         },
         EPIC: {

package/dist/core/sdd/entity-reference.d.ts

@@ -0,0 +1,5 @@
+export type SddEntityType = 'FEAT' | 'RAD' | 'EPIC' | 'FGAP' | 'TD';
+export declare function normalizeFeatRef(input: string): string | null;
+export declare function normalizeSddEntityRef(input: string): string;
+export declare function detectSddEntityType(input: string): SddEntityType | null;
+//# sourceMappingURL=entity-reference.d.ts.map

package/dist/core/sdd/entity-reference.js

@@ -0,0 +1,22 @@
+const FEAT_ALIAS_PATTERN = /^(?:FEAT|FEATS|FEATES)-(\d{3,})$/i;
+const CANONICAL_PATTERNS = [
+    ['FEAT', /^FEAT-\d{3,}$/],
+    ['EPIC', /^EPIC-\d{3,}$/],
+    ['RAD', /^RAD-\d{3,}$/],
+    ['FGAP', /^FGAP-\d{3,}$/],
+    ['TD', /^TD-\d{3,}$/],
+];
+export function normalizeFeatRef(input) {
+    const match = input.trim().match(FEAT_ALIAS_PATTERN);
+    if (!match)
+        return null;
+    return `FEAT-${match[1]}`;
+}
+export function normalizeSddEntityRef(input) {
+    return normalizeFeatRef(input) ?? input.trim();
+}
+export function detectSddEntityType(input) {
+    const normalized = normalizeSddEntityRef(input);
+    return CANONICAL_PATTERNS.find(([, pattern]) => pattern.test(normalized))?.[0] ?? null;
+}
+//# sourceMappingURL=entity-reference.js.map

package/dist/core/sdd/governance-backfill.d.ts

@@ -0,0 +1,31 @@
+type BackfillScope = 'discovery' | 'adr';
+export interface GovernanceBackfillException {
+    scope: BackfillScope;
+    file: string;
+    id: string;
+    reason: string;
+    severity: 'warning' | 'skipped';
+}
+export interface GovernanceBackfillBucket {
+    inspected: number;
+    updated: number;
+    skipped: number;
+    exceptions: GovernanceBackfillException[];
+}
+export interface GovernanceBackfillReport {
+    generated_at: string;
+    write: boolean;
+    discovery: GovernanceBackfillBucket;
+    adr: GovernanceBackfillBucket;
+}
+export interface GovernanceBackfillOptions {
+    projectRoot: string;
+    discovery?: boolean;
+    adr?: boolean;
+    write?: boolean;
+    reportPath?: string;
+    nowIso?: string;
+}
+export declare function backfillGovernanceFrontmatter(options: GovernanceBackfillOptions): Promise<GovernanceBackfillReport>;
+export {};
+//# sourceMappingURL=governance-backfill.d.ts.map