@devtrack-solution/codesdd 1.2.2 → 1.2.4-rc3

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

@@ -31,6 +31,16 @@ function upsertMarkedBlock(source, startMarker, endMarker, blockContent) {
     const next = `${prefix}${replacement}\n`;
     return { content: next, changed: true, hasMarkers: false };
 }
+function validateManagedBlock(source, startMarker, endMarker, expectedBlock, label, missingBlocks) {
+    if (!source.includes(startMarker) || !source.includes(endMarker)) {
+        missingBlocks.push(label);
+        return;
+    }
+    const expected = upsertMarkedBlock(source, startMarker, endMarker, expectedBlock);
+    if (expected.changed) {
+        missingBlocks.push(`${label}:DRIFT`);
+    }
+}
 function buildReadmeBlock(memoryDir, config) {
     return `## Onboarding SDD
 
@@ -39,6 +49,14 @@ 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.
+- In initialized CodeSDD repositories, any user request that implies implementation, file edits, validation, execution, or finalize must be treated as requiring CodeSDD planning unless the user explicitly marks it as read-only or outside CodeSDD.
+- For change requests, agents must bind the work to an active or ready FEAT through \`${CLI_NAME} sdd next\` and \`${CLI_NAME} sdd context <FEAT-ID>\` before implementation; agent-native plans may only decompose execution after that CodeSDD context exists.
+- 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 +75,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 +96,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 +109,22 @@ 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.
+- In initialized CodeSDD repositories, implementation, edit, validation, execution, and finalize requests implicitly require CodeSDD planning unless the user explicitly marks the request as read-only or outside CodeSDD.
+- A change request must use the active or ready FEAT returned by \`${CLI_NAME} sdd next\` and must load \`${CLI_NAME} sdd context <FEAT-ID>\` before coding; model-native plans may only refine execution after that context exists.
+- 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 +139,20 @@ 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.
+- In initialized CodeSDD repositories, implementation, edit, validation, execution, and finalize requests implicitly require CodeSDD planning unless the user explicitly marks the request as read-only or outside CodeSDD.
+- Agents must bind each change request to the active or ready FEAT returned by \`${CLI_NAME} sdd next\` and load \`${CLI_NAME} sdd context <FEAT-ID>\` before coding.
+- 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');
@@ -197,11 +241,9 @@ export async function validateSddGuideDocs(projectRoot, paths, config) {
     const agentCompatRaw = (await fileExists(agentCompatPath))
         ? await fs.readFile(agentCompatPath, 'utf-8')
         : '';
-    if (!readmeRaw.includes(README_SDD_BLOCK_START) || !readmeRaw.includes(README_SDD_BLOCK_END)) {
-        missingBlocks.push('README.md::SDD:ONBOARDING');
-    }
+    validateManagedBlock(readmeRaw, README_SDD_BLOCK_START, README_SDD_BLOCK_END, buildReadmeBlock(memoryDirName, config), 'README.md::SDD:ONBOARDING', missingBlocks);
     if (internalReadmeRaw !==
-        buildSddInternalReadme(path.relative(projectRoot, paths.memoryRoot) || '.sdd', {
+        buildSddInternalReadme(memoryDirName, {
             discovery: config?.folders.discovery,
             planning: config?.folders.planning,
             skills: config?.folders.skills,
@@ -212,17 +254,9 @@ export async function validateSddGuideDocs(projectRoot, paths, config) {
         })) {
         missingBlocks.push(`${memoryDirName}/README.md::SDD:INTERNAL`);
     }
-    if (!agentRaw.includes(AGENT_SDD_BLOCK_START) || !agentRaw.includes(AGENT_SDD_BLOCK_END)) {
-        missingBlocks.push(`${memoryDirName}/AGENT.md::SDD:GUIA`);
-    }
-    if (!agentsRaw.includes(ROOT_AGENTS_SDD_BLOCK_START) ||
-        !agentsRaw.includes(ROOT_AGENTS_SDD_BLOCK_END)) {
-        missingBlocks.push('AGENTS.md::SDD:ROOT-AGENTS');
-    }
-    if (!agentCompatRaw.includes(ROOT_AGENTS_SDD_BLOCK_START) ||
-        !agentCompatRaw.includes(ROOT_AGENTS_SDD_BLOCK_END)) {
-        missingBlocks.push('AGENT.md::SDD:ROOT-AGENTS');
-    }
+    validateManagedBlock(agentRaw, AGENT_SDD_BLOCK_START, AGENT_SDD_BLOCK_END, buildAgentGuideBlock(memoryDirName, config), `${memoryDirName}/AGENT.md::SDD:GUIA`, missingBlocks);
+    validateManagedBlock(agentsRaw, ROOT_AGENTS_SDD_BLOCK_START, ROOT_AGENTS_SDD_BLOCK_END, buildRootAgentsBlock(memoryDirName), 'AGENTS.md::SDD:ROOT-AGENTS', missingBlocks);
+    validateManagedBlock(agentCompatRaw, ROOT_AGENTS_SDD_BLOCK_START, ROOT_AGENTS_SDD_BLOCK_END, buildRootAgentsBlock(memoryDirName), 'AGENT.md::SDD:ROOT-AGENTS', missingBlocks);
     return {
         documentationSync: missingBlocks.length === 0,
         missingBlocks,

package/dist/core/sdd/domain/capability-diff.d.ts

@@ -0,0 +1,63 @@
+import type { ChangeSafetyEvaluation, PlannedFileChange } from './change-safety-guardrails.js';
+export declare const CAPABILITY_KINDS: readonly ["route", "page", "cli_command", "public_contract", "schema", "event", "core_flow", "governance_state"];
+export declare const CAPABILITY_CHANGE_TYPES: readonly ["added", "removed", "modified", "unchanged"];
+export declare const CAPABILITY_RISK_LEVELS: readonly ["none", "low", "medium", "high", "critical"];
+export type CapabilityKind = (typeof CAPABILITY_KINDS)[number];
+export type CapabilityChangeType = (typeof CAPABILITY_CHANGE_TYPES)[number];
+export type CapabilityRiskLevel = (typeof CAPABILITY_RISK_LEVELS)[number];
+export interface CapabilityInventoryItem {
+    kind: CapabilityKind;
+    id: string;
+    path?: string;
+    fingerprint?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface CapabilityInventory {
+    schema_version: 1;
+    contract: 'capability-inventory/v1';
+    items: CapabilityInventoryItem[];
+}
+export interface CapabilityDiffEntry {
+    kind: CapabilityKind;
+    id: string;
+    change: CapabilityChangeType;
+    before?: CapabilityInventoryItem;
+    after?: CapabilityInventoryItem;
+}
+export interface CapabilityDiffCounts {
+    added: number;
+    removed: number;
+    modified: number;
+    unchanged: number;
+}
+export interface CapabilityDiffReport {
+    schema_version: 1;
+    contract: 'capability-diff-report/v1';
+    entries: CapabilityDiffEntry[];
+    counts: CapabilityDiffCounts;
+}
+export interface CapabilityRiskSignal {
+    code: string;
+    level: Exclude<CapabilityRiskLevel, 'none'>;
+    message: string;
+    capability_ref?: string;
+    path?: string;
+}
+export interface CapabilityRiskReport {
+    schema_version: 1;
+    contract: 'deterministic-capability-risk/v1';
+    level: CapabilityRiskLevel;
+    score: number;
+    signals: CapabilityRiskSignal[];
+}
+export interface CapabilityRiskInput {
+    diff: CapabilityDiffReport;
+    change_safety?: ChangeSafetyEvaluation;
+    planned_changes?: PlannedFileChange[];
+    required_kinds?: CapabilityKind[];
+}
+export declare function buildCapabilityInventory(items: CapabilityInventoryItem[]): CapabilityInventory;
+export declare function diffCapabilityInventories(before: CapabilityInventory, after: CapabilityInventory): CapabilityDiffReport;
+export declare function scoreCapabilityDiffRisk(input: CapabilityRiskInput): CapabilityRiskReport;
+export declare function capabilityKey(item: Pick<CapabilityInventoryItem, 'kind' | 'id'>): string;
+//# sourceMappingURL=capability-diff.d.ts.map