@devtrack-solution/codesdd 1.2.4-rc3 → 1.2.4

package/dist/core/sdd/check.js

@@ -11,6 +11,7 @@ import { syncSddGuideDocs, validateSddGuideDocs } from './docs-sync.js';
 import { evaluateWorkspaceTraceability } from './domain/traceability.js';
 import { detectArchiveArchivedLifecycleCollisions } from './domain/post-active-validation.js';
 import { parseWorkspaceYamlDocument, workspaceTasksSchema, } from './workspace-schemas.js';
+import { scanArchiveQualityCoherence } from './services/archive-quality-coherence.service.js';
 export function checkUniqueIds(items, scope, errors) {
     const seen = new Set();
     for (const item of items) {
@@ -21,6 +22,7 @@ export function checkUniqueIds(items, scope, errors) {
     }
 }
 const FORBIDDEN_TITLE_PATTERNS = ['debate:', 'insight:', '(preencher', '(placeholder'];
+const CLOSED_BACKLOG_STATUSES = new Set(['DONE', 'ARCHIVED']);
 export function hasForbiddenTitleToken(title) {
     const lowered = title.toLowerCase();
     for (const token of FORBIDDEN_TITLE_PATTERNS) {
@@ -29,6 +31,258 @@ export function hasForbiddenTitleToken(title) {
     }
     return null;
 }
+export function summarizeFrontendGapHealth(gaps) {
+    let open = 0;
+    let planned = 0;
+    let inProgress = 0;
+    let resolved = 0;
+    let superseded = 0;
+    for (const gap of gaps) {
+        if (gap.status === 'OPEN')
+            open++;
+        if (gap.status === 'PLANNED')
+            planned++;
+        if (gap.status === 'IN_PROGRESS')
+            inProgress++;
+        if (gap.status === 'DONE')
+            resolved++;
+        if (gap.status === 'SUPERSEDED')
+            superseded++;
+    }
+    return {
+        total: gaps.length,
+        open,
+        planned,
+        in_progress: inProgress,
+        resolved,
+        superseded,
+        unresolved: gaps.length - resolved - superseded,
+    };
+}
+export function summarizeLockDomainHealth(items) {
+    const lockOwners = new Map();
+    for (const item of items) {
+        for (const lock of item.lock_domains) {
+            const owners = lockOwners.get(lock) || [];
+            owners.push(item);
+            lockOwners.set(lock, owners);
+        }
+    }
+    const shared = [];
+    for (const [lock, owners] of lockOwners.entries()) {
+        if (owners.length <= 1)
+            continue;
+        const activeOwners = owners.filter((owner) => !CLOSED_BACKLOG_STATUSES.has(owner.status));
+        const historicalOwners = owners.filter((owner) => CLOSED_BACKLOG_STATUSES.has(owner.status));
+        const severity = activeOwners.length > 1 ? 'active' : activeOwners.length === 1 ? 'mixed' : 'historical';
+        shared.push({
+            lock,
+            severity,
+            owners: owners.map((owner) => owner.id),
+            active_owners: activeOwners.map((owner) => owner.id),
+            historical_owners: historicalOwners.map((owner) => owner.id),
+        });
+    }
+    shared.sort((left, right) => left.lock.localeCompare(right.lock));
+    return {
+        shared_total: shared.length,
+        active_conflicts: shared.filter((item) => item.severity === 'active').length,
+        mixed_history: shared.filter((item) => item.severity === 'mixed').length,
+        historical: shared.filter((item) => item.severity === 'historical').length,
+        shared,
+    };
+}
+function normalizeCatalogPath(input) {
+    return input.trim().replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/, '');
+}
+export function hasRepoMapReference(repoPath, repoMapPaths) {
+    const normalizedRepoPath = normalizeCatalogPath(repoPath);
+    if (!normalizedRepoPath)
+        return false;
+    return repoMapPaths.some((repoMapPath) => {
+        const normalizedRepoMapPath = normalizeCatalogPath(repoMapPath);
+        if (!normalizedRepoMapPath)
+            return false;
+        return (normalizedRepoMapPath === normalizedRepoPath ||
+            normalizedRepoMapPath.startsWith(`${normalizedRepoPath}/`) ||
+            normalizedRepoPath.startsWith(`${normalizedRepoMapPath}/`));
+    });
+}
+export function hasIntegrationContract(contractRef, knownContracts) {
+    const normalizedContractRef = contractRef.trim();
+    if (!normalizedContractRef)
+        return false;
+    if (knownContracts.has(normalizedContractRef))
+        return true;
+    for (const knownContract of knownContracts) {
+        if (knownContract.startsWith(`${normalizedContractRef}::`)) {
+            return true;
+        }
+    }
+    return false;
+}
+export function auditServiceCatalogMaturity(services, backlogItems, repoMapItems, integrationContracts) {
+    const backlogIds = new Set(backlogItems.map((item) => item.id));
+    const repoMapPaths = repoMapItems.map((item) => item.path);
+    const contracts = new Set(integrationContracts.map((item) => item.trim()).filter(Boolean));
+    const byLevel = { 1: 0, 2: 0, 3: 0, 4: 0, 5: 0 };
+    const below5 = [];
+    for (const service of services) {
+        const unmet = [];
+        const hasIdentity = Boolean(service.id.trim()) && Boolean(service.name.trim()) && Boolean((service.responsibility || '').trim());
+        if (!hasIdentity)
+            unmet.push('identity');
+        const hasOwners = service.owner_refs.length > 0 && service.owner_refs.every((ownerRef) => backlogIds.has(ownerRef));
+        if (!hasOwners)
+            unmet.push('owner_refs');
+        const hasRepoPaths = service.repo_paths.length > 0 && service.repo_paths.every((repoPath) => hasRepoMapReference(repoPath, repoMapPaths));
+        if (!hasRepoPaths)
+            unmet.push('repo_paths');
+        const hasContracts = service.contracts.length > 0 &&
+            service.contracts.every((contractRef) => hasIntegrationContract(contractRef, contracts));
+        if (!hasContracts)
+            unmet.push('contracts');
+        const hasExternalDependencies = Array.isArray(service.external_dependencies);
+        if (!hasExternalDependencies)
+            unmet.push('external_dependencies');
+        const level = !hasIdentity ? 1 : !hasOwners ? 2 : !hasRepoPaths ? 3 : !hasContracts || !hasExternalDependencies ? 4 : 5;
+        byLevel[level] += 1;
+        if (level < 5) {
+            below5.push({
+                id: service.id,
+                level,
+                unmet,
+            });
+        }
+    }
+    return {
+        serviceCount: services.length,
+        byLevel,
+        below5,
+    };
+}
+export async function validateAdrConsistency(adrsDir, backlogItems, errors, warnings, isStrict) {
+    const backlogStatus = new Map();
+    for (const item of backlogItems) {
+        backlogStatus.set(item.id, item.status);
+    }
+    let filenames;
+    try {
+        filenames = await fs.readdir(adrsDir);
+    }
+    catch {
+        return;
+    }
+    const adrs = filenames.filter((f) => f.startsWith('ADR-') && f.endsWith('.md'));
+    for (const filename of adrs) {
+        let content;
+        try {
+            content = await fs.readFile(path.join(adrsDir, filename), 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        const frontmatterMatch = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
+        if (!frontmatterMatch)
+            continue;
+        let frontmatter;
+        try {
+            frontmatter = parseYaml(frontmatterMatch[1]) ?? {};
+        }
+        catch {
+            continue;
+        }
+        const adrStatus = typeof frontmatter.status === 'string' ? frontmatter.status : '';
+        const featureId = typeof frontmatter.feature_id === 'string' ? frontmatter.feature_id : '';
+        const adrId = typeof frontmatter.id === 'string' ? frontmatter.id : filename;
+        if (!featureId || !adrStatus)
+            continue;
+        const featureStatus = backlogStatus.get(featureId);
+        if (!featureStatus)
+            continue;
+        const featureDone = featureStatus === 'DONE' || featureStatus === 'ARCHIVED';
+        const adrUnresolved = adrStatus === 'IN_PROGRESS' || adrStatus === 'DRAFT';
+        if (featureDone && adrUnresolved) {
+            const message = `ADR consistency gate failed: ${adrId} status is ${adrStatus} but feature ${featureId} is ${featureStatus} in backlog`;
+            if (isStrict) {
+                errors.push(message);
+            }
+            else {
+                warnings.push(message);
+            }
+        }
+    }
+}
+export function validateInsightMinimums(insightTitle, insightBody, errors) {
+    if ((insightTitle || '').trim().length < 50) {
+        errors.push(`INSIGHT quality gate: title must be >=50 characters (current: ${(insightTitle || '').trim().length}). Expand the title to describe the problem and expected impact.`);
+    }
+    const bodyLower = (insightBody || '').toLowerCase();
+    const missingKeywords = [];
+    if (!/\bproblem|\bproblema|\bissue\b/.test(bodyLower))
+        missingKeywords.push('problem description');
+    if (!/\bscope|\bescopo|\bboundary\b/.test(bodyLower))
+        missingKeywords.push('scope definition');
+    if (!/\bimpact|\bimpacto|\boutcome\b/.test(bodyLower))
+        missingKeywords.push('expected impact');
+    if (missingKeywords.length > 0) {
+        errors.push(`INSIGHT quality gate: body must describe problem, scope, and impact. Missing: ${missingKeywords.join(', ')}.`);
+    }
+}
+export function validateEpicMinimums(epicBody, epicTitle, errors) {
+    const bodyClean = (epicBody || '').replace(/^---[\s\S]*?---\r?\n?/, '').trim();
+    if (bodyClean.length < 500) {
+        errors.push(`EPIC quality gate: expanded plan must be >=500 characters (current: ${bodyClean.length}). Add feature breakdown, dependency map, risk matrix, and DoD.`);
+    }
+    const featMatches = bodyClean.match(/FEAT-\d{4}/g) || [];
+    const uniqueFeats = new Set(featMatches).size;
+    if (uniqueFeats < 3) {
+        errors.push(`EPIC quality gate: must reference >=3 estimated features (current: ${uniqueFeats}). Expand the breakdown plan with concrete feature estimates.`);
+    }
+    const hasDependencyMap = /\bupstream\b|\bdownstream\b|\bdependencies\b|\bdependency map\b/i.test(bodyClean);
+    if (!hasDependencyMap) {
+        errors.push(`EPIC quality gate: must include a dependency map with upstream and downstream references.`);
+    }
+}
+export function validateTransitionLogConsistency(transitionLogEvents, backlogItems, errors, warnings, isStrict) {
+    if (transitionLogEvents.length === 0)
+        return;
+    const oldestEventTs = Math.min(...transitionLogEvents.map((e) => e.timestamp ? Date.parse(String(e.timestamp)) : Infinity));
+    const backlogStatus = new Map(backlogItems.map((item) => [item.id, item.status]));
+    const finalizeEvents = new Set();
+    for (const event of transitionLogEvents) {
+        const action = event.action || event.to || '';
+        if (action === 'finalized' || action === 'archived' || action === 'DONE' || action === 'ARCHIVED') {
+            finalizeEvents.add(event.entity_id);
+        }
+    }
+    for (const item of backlogItems) {
+        const isDone = item.status === 'DONE' || item.status === 'ARCHIVED';
+        if (!isDone)
+            continue;
+        if (finalizeEvents.has(item.id))
+            continue;
+        const itemDoneAt = item.done_at || item.archived_at || '';
+        if (itemDoneAt && oldestEventTs !== Infinity && Date.parse(itemDoneAt) < oldestEventTs) {
+            continue;
+        }
+        const message = `Transition-log consistency: ${item.id} is ${item.status} in backlog but has no finalized event in transition-log`;
+        warnings.push(message);
+    }
+    for (const eventId of finalizeEvents) {
+        const status = backlogStatus.get(eventId);
+        if (!status) {
+            warnings.push(`Transition-log consistency: transition-log has finalized event for ${eventId} but no matching backlog item`);
+        }
+        else if (status !== 'DONE' && status !== 'ARCHIVED') {
+            const message = `Transition-log consistency: ${eventId} has finalized event in transition-log but backlog status is ${status}`;
+            if (isStrict)
+                errors.push(message);
+            else
+                warnings.push(message);
+        }
+    }
+}
 export function validateDiscoveryRecords(records, errors) {
     for (const record of records) {
         if (record.type === 'INS' && !ID_PATTERNS.insight.test(record.id)) {
@@ -53,7 +307,6 @@ export function validateDiscoveryRecords(records, errors) {
 }
 export function validateBacklog(items, errors, warnings) {
     const ids = new Set(items.map((item) => item.id));
-    const lockOwners = new Map();
     for (const item of items) {
         const forbidden = hasForbiddenTitleToken(item.title);
         if (forbidden) {
@@ -67,15 +320,10 @@ export function validateBacklog(items, errors, warnings) {
                 warnings.push(`Item de backlog ${item.id} bloqueado por referencia inexistente: ${dep}`);
             }
         }
-        for (const lock of item.lock_domains) {
-            const owners = lockOwners.get(lock) || [];
-            owners.push(item.id);
-            lockOwners.set(lock, owners);
-        }
     }
-    for (const [lock, owners] of lockOwners.entries()) {
-        if (owners.length > 1) {
-            warnings.push(`Lock domain "${lock}" compartilhado por: ${owners.join(', ')}`);
+    for (const sharedLock of summarizeLockDomainHealth(items).shared) {
+        if (sharedLock.severity === 'active') {
+            warnings.push(`Lock domain "${sharedLock.lock}" compartilhado por FEATs ativas: ${sharedLock.active_owners.join(', ')}`);
         }
     }
 }
@@ -739,6 +987,15 @@ export class SddCheckCommand {
         validatePrivacySourceRegistry(snapshot, warnings);
         await validatePrivacyWorkspaceChecklist(paths.activeDir, snapshot.backlog.items, warnings);
         await validateTraceabilityWorkspaceChecklist(paths.projectRoot, paths.activeDir, snapshot.backlog.items, warnings);
+        await validateAdrConsistency(path.join(paths.coreDir, 'adrs'), snapshot.backlog.items, errors, warnings, isStrict);
+        validateTransitionLogConsistency(snapshot.transitionLog?.events || [], snapshot.backlog.items, errors, warnings, isStrict);
+        const archiveQualityCoherence = await scanArchiveQualityCoherence(paths.archivedDir);
+        for (const issue of archiveQualityCoherence.issues) {
+            errors.push(issue.message);
+        }
+        if (archiveQualityCoherence.grandfathered > 0) {
+            warnings.push(`Archive quality coherence grandfathered ${archiveQualityCoherence.grandfathered} archived FEAT workspaces (<= FEAT-0451).`);
+        }
         const featuresMissingFrontendDeclaration = config.frontend.enabled
             ? snapshot.backlog.items
                 .filter((item) => item.status !== 'ARCHIVED' && item.status !== 'DONE')
@@ -780,6 +1037,22 @@ export class SddCheckCommand {
         if (snapshot.repoMap.items.length === 0) {
             missingArchitectureFields.push('repo-map.items vazio');
         }
+        const serviceCatalogMaturityAudit = auditServiceCatalogMaturity(snapshot.serviceCatalog.services, snapshot.backlog.items, snapshot.repoMap.items, snapshot.integrationContracts.contracts);
+        if (serviceCatalogMaturityAudit.below5.length > 0) {
+            const sample = serviceCatalogMaturityAudit.below5
+                .slice(0, 10)
+                .map((entry) => `${entry.id}(L${entry.level}: ${entry.unmet.join(', ')})`)
+                .join('; ');
+            const remainder = serviceCatalogMaturityAudit.below5.length - Math.min(10, serviceCatalogMaturityAudit.below5.length);
+            const suffix = remainder > 0 ? `; +${remainder} service(s)` : '';
+            const message = `Service catalog maturity gate failed: ${serviceCatalogMaturityAudit.below5.length}/${serviceCatalogMaturityAudit.serviceCount} services are below level 5. ${sample}${suffix}`;
+            if (isStrict) {
+                errors.push(message);
+            }
+            else {
+                warnings.push(message);
+            }
+        }
         const hasFrontendDecisionDemand = config.frontend.enabled &&
             ((snapshot.frontendGaps?.items.length ?? 0) > 0 ||
                 snapshot.backlog.items.some((item) => featureHasMetadataFrontendEvidence(item)));
@@ -832,6 +1105,8 @@ export class SddCheckCommand {
         const finalizeQueuePending = snapshot.finalizeQueue.items.filter((item) => item.status === 'PENDING').length;
         const finalizeQueueDone = snapshot.finalizeQueue.history.length +
             snapshot.finalizeQueue.items.filter((item) => item.status === 'DONE').length;
+        const frontendGapsSummary = summarizeFrontendGapHealth(snapshot.frontendGaps?.items ?? []);
+        const lockDomainHealth = summarizeLockDomainHealth(snapshot.backlog.items);
         return {
             valid: errors.length === 0,
             errors,
@@ -845,12 +1120,14 @@ export class SddCheckCommand {
                 finalizeQueueDone,
                 frontendEnabled: config.frontend.enabled,
                 frontendGaps: snapshot.frontendGaps?.items.length ?? 0,
+                frontendGapsSummary,
                 frontendRoutes: snapshot.frontendMap?.routes.length ?? 0,
                 progress_global: progress.progressGlobal,
                 progress_by_radar: progress.progressByRadar,
                 ready_for_parallel: graph.readyForParallel,
                 blocked: graph.blocked,
                 lock_conflicts: graph.lockConflicts,
+                lock_domain_health: lockDomainHealth,
                 documentation_sync: docsValidation.documentationSync,
                 core_views_stale: coreViewsStale,
                 missing_architecture_fields: missingArchitectureFields,

package/dist/core/sdd/deepagent-contracts.d.ts

@@ -148,8 +148,8 @@ export declare const deepagentRunRequestSchema: z.ZodObject<{
         kind: z.ZodEnum<{
             event: "event";
             schema: "schema";
-            route: "route";
             page: "page";
+            route: "route";
             cli_command: "cli_command";
             public_contract: "public_contract";
             core_flow: "core_flow";
@@ -164,8 +164,8 @@ export declare const deepagentRunRequestSchema: z.ZodObject<{
         kind: z.ZodEnum<{
             event: "event";
             schema: "schema";
-            route: "route";
             page: "page";
+            route: "route";
             cli_command: "cli_command";
             public_contract: "public_contract";
             core_flow: "core_flow";
@@ -180,8 +180,8 @@ export declare const deepagentRunRequestSchema: z.ZodObject<{
     capability_required_kinds: z.ZodDefault<z.ZodArray<z.ZodEnum<{
         event: "event";
         schema: "schema";
-        route: "route";
         page: "page";
+        route: "route";
         cli_command: "cli_command";
         public_contract: "public_contract";
         core_flow: "core_flow";
@@ -336,8 +336,8 @@ export declare const deepagentRunEvidenceSchema: z.ZodObject<{
         completed: "completed";
         blocked: "blocked";
         failed: "failed";
-        running: "running";
         allowed: "allowed";
+        running: "running";
     }>;
     model_metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     config_fingerprint: z.ZodString;

package/dist/core/sdd/deepagents/reversa-subagents.d.ts

@@ -5,8 +5,8 @@ export declare const reversaDomainSchema: z.ZodEnum<{
     rules: "rules";
     data: "data";
     migration: "migration";
-    "legacy-analysis": "legacy-analysis";
     screens: "screens";
+    "legacy-analysis": "legacy-analysis";
     microservices: "microservices";
     "equivalence-validation": "equivalence-validation";
 }>;
@@ -18,8 +18,8 @@ export declare const deepAgentsReversaRequestSchema: z.ZodObject<{
         rules: "rules";
         data: "data";
         migration: "migration";
-        "legacy-analysis": "legacy-analysis";
         screens: "screens";
+        "legacy-analysis": "legacy-analysis";
         microservices: "microservices";
         "equivalence-validation": "equivalence-validation";
     }>>>;
@@ -56,8 +56,8 @@ export declare const deepAgentsReversaPlanSchema: z.ZodObject<{
             rules: "rules";
             data: "data";
             migration: "migration";
-            "legacy-analysis": "legacy-analysis";
             screens: "screens";
+            "legacy-analysis": "legacy-analysis";
             microservices: "microservices";
             "equivalence-validation": "equivalence-validation";
         }>;

package/dist/core/sdd/default-bootstrap-files.d.ts

@@ -10,7 +10,7 @@ export interface SddReadmeFolders {
 }
 export declare function buildSddInternalReadme(memoryDir?: string, folders?: SddReadmeFolders): string;
 export declare const PROMPTS_README_MD = "# Recommended SDD Prompts\n\nUse these prompts to speed up agent workflows without losing the SDD standard.\n\n## Recommended Order For Raw Material\n1. `00-start-here.md`\n2. `01-source-intake.md`\n3. `02-normalize-planning.md`\n4. `03-feature-execution.md`\n5. `04-finalize-consolidation.md`\n\nRule: prompts guide the agent, but the canonical state remains in `.sdd/state/*.yaml`.\nDo not persist project memory, workflow state, backlog, or handoff in external context stores.\n";
-export declare const PROMPT_00_COMECE_POR_AQUI_MD = "# Start Here (First Use)\n\nIf you have never used CodeSDD, follow this order.\n\n## 1) Install And Initialize The Project\n\nIn the terminal, from your project directory:\n\n```bash\ncodesdd install --tools none --lang en-US --layout en-US\ncodesdd sdd init --frontend --lang en-US --layout en-US\ncodesdd sdd init-context --frontend --lang en-US --layout en-US\ncodesdd sdd check --render\ncodesdd sdd rebuild --from-disk --dry-run\ncodesdd sdd dedup --apply --dry-run\ncodesdd sdd onboard system\ncodesdd reload --tools none --lang en-US --layout en-US\n```\n\n## 2) Understand The Main Folders\n\n- `.sdd/sources/`: raw material such as PRDs, wireframes, stories, and references.\n- `.sdd/state/`: canonical YAML source of truth.\n- `.sdd/core/`: generated human-readable system overview.\n- `.sdd/planning/`: backlog, progress, and finalize queue.\n- `.sdd/active/`: active FEAT workspaces.\n- `.sdd/archived/`: finalized workspaces.\n\nCodeSDD is the only operational memory for the project. Do not use external context, memory, workflow, backlog, scratchpad, or handoff stores as active project state.\nIn initialized CodeSDD repositories, requests that imply implementation, edits, validation, execution, or finalize implicitly require CodeSDD planning unless explicitly marked read-only or outside CodeSDD.\n\n## 3) I Have PRDs, Wireframes, Or Stories. What Now?\n\n1. Place the files under `.sdd/sources/` in the appropriate subfolders.\n2. Run:\n\n```bash\ncodesdd sdd ingest-deposito --source-dir .sdd/sources --title \"Initial system planning\"\n```\n\n3. Review:\n\n```bash\ncodesdd sdd check --render\ncodesdd sdd next\n```\n\nExpected result:\n- sources indexed in `.sdd/state/source-index.yaml`\n- EPIC created or reused\n- FEATs generated in the backlog\n- first ready FEAT started automatically when possible\n\n## 4) Execute A Feature\n\n```bash\ncodesdd sdd start FEAT-0001 --flow-mode standard\ncodesdd sdd context FEAT-0001\ncodesdd sdd frontend-impact FEAT-0001 --status required --reason \"New route and UI components\"\n```\n\nImplement and update the FEAT package:\n- `1-spec.yaml`\n- `2-plan.yaml`\n- `5-quality.yaml`\n- `3-tasks.yaml`\n- `4-changelog.yaml`\n\n## 5) Finalize Without Losing Context\n\n```bash\ncodesdd sdd finalize --ref FEAT-0001\ncodesdd sdd check --render\ncodesdd sdd onboard system\n```\n\nGolden rule:\n- A FEAT is only truly complete after documentation consolidation.\n\n## 6) Short Usage Story\n\nThe team placed a PRD and a wireframe in `.sdd/sources/`.\nThey ran `codesdd sdd ingest-deposito --source-dir .sdd/sources` and got an EPIC plus ready FEATs.\nThey started the priority FEAT with `codesdd sdd start FEAT-0001`.\nBefore coding, they ran `codesdd sdd context FEAT-0001`.\nAfter implementation, they ran `codesdd sdd finalize --ref FEAT-0001`.\nResult: backlog updated, docs synchronized, and the next FEAT released without guesswork.\n\n## 7) Essential Commands\n\n- `codesdd sdd onboard system`: understand the current state.\n- `codesdd sdd ingest-deposito --source-dir .sdd/sources`: turn raw material into an executable trail.\n- `codesdd sdd rebuild --from-disk --dry-run`: preview state reconciliation from disk artifacts.\n- `codesdd sdd audit --json`: persist an audit snapshot in `.sdd/state/audit-history.yaml`.\n- `codesdd sdd metrics --since 7d`: inspect lead time, aging, and throughput.\n- `codesdd sdd dedup --apply --dry-run`: preview historical warning_links reconciliation.\n- `codesdd sdd lint feature FEAT-0001`: inspect feature scope before execution.\n- `codesdd sdd next`: see what can start now.\n- `codesdd sdd start FEAT-0001`: open feature execution.\n- `codesdd sdd context FEAT-0001`: generate focused context.\n- `codesdd sdd frontend-impact FEAT-0001 --status required|none --reason \"...\"`: declare frontend impact.\n- `codesdd sdd finalize --ref FEAT-0001`: consolidate memory and close.\n";
+export declare const PROMPT_00_COMECE_POR_AQUI_MD = "# Start Here (First Use)\n\nIf you have never used CodeSDD, follow this order.\n\n## 1) Install And Initialize The Project\n\nIn the terminal, from your project directory:\n\n```bash\ncodesdd sdd init-context --frontend --lang en-US --layout en-US\ncodesdd sdd check --render\ncodesdd sdd rebuild --from-disk --dry-run\ncodesdd sdd dedup --apply --dry-run\ncodesdd sdd onboard system\ncodesdd reload --tools none --lang en-US --layout en-US\n```\n\n## 2) Understand The Main Folders\n\n- `.sdd/sources/`: raw material such as PRDs, wireframes, stories, and references.\n- `.sdd/state/`: canonical YAML source of truth.\n- `.sdd/core/`: generated human-readable system overview.\n- `.sdd/planning/`: backlog, progress, and finalize queue.\n- `.sdd/active/`: active FEAT workspaces.\n- `.sdd/archived/`: finalized workspaces.\n\nCodeSDD is the only operational memory for the project. Do not use external context, memory, workflow, backlog, scratchpad, or handoff stores as active project state.\nIn initialized CodeSDD repositories, requests that imply implementation, edits, validation, execution, or finalize implicitly require CodeSDD planning unless explicitly marked read-only or outside CodeSDD.\n\n## 3) I Have PRDs, Wireframes, Or Stories. What Now?\n\n1. Place the files under `.sdd/sources/` in the appropriate subfolders.\n2. Run:\n\n```bash\ncodesdd sdd ingest-deposito --source-dir .sdd/sources --title \"Initial system planning\"\n```\n\n3. Review:\n\n```bash\ncodesdd sdd check --render\ncodesdd sdd next\n```\n\nExpected result:\n- sources indexed in `.sdd/state/source-index.yaml`\n- EPIC created or reused\n- FEATs generated in the backlog\n- first ready FEAT started automatically when possible\n\n## 4) Execute A Feature\n\n```bash\ncodesdd sdd start FEAT-0001 --flow-mode standard\ncodesdd sdd context FEAT-0001\ncodesdd sdd frontend-impact FEAT-0001 --status required --reason \"New route and UI components\"\n```\n\nImplement and update the FEAT package:\n- `1-spec.yaml`\n- `2-plan.yaml`\n- `5-quality.yaml`\n- `3-tasks.yaml`\n- `4-changelog.yaml`\n\n## 5) Finalize Without Losing Context\n\n```bash\ncodesdd sdd finalize --ref FEAT-0001\ncodesdd sdd check --render\ncodesdd sdd onboard system\n```\n\nGolden rule:\n- A FEAT is only truly complete after documentation consolidation.\n\n## 6) Short Usage Story\n\nThe team placed a PRD and a wireframe in `.sdd/sources/`.\nThey ran `codesdd sdd ingest-deposito --source-dir .sdd/sources` and got an EPIC plus ready FEATs.\nThey started the priority FEAT with `codesdd sdd start FEAT-0001`.\nBefore coding, they ran `codesdd sdd context FEAT-0001`.\nAfter implementation, they ran `codesdd sdd finalize --ref FEAT-0001`.\nResult: backlog updated, docs synchronized, and the next FEAT released without guesswork.\n\n## 7) Essential Commands\n\n- `codesdd sdd onboard system`: understand the current state.\n- `codesdd sdd ingest-deposito --source-dir .sdd/sources`: turn raw material into an executable trail.\n- `codesdd sdd rebuild --from-disk --dry-run`: preview state reconciliation from disk artifacts.\n- `codesdd sdd audit --json`: persist an audit snapshot in `.sdd/state/audit-history.yaml`.\n- `codesdd sdd metrics --since 7d`: inspect lead time, aging, and throughput.\n- `codesdd sdd dedup --apply --dry-run`: preview historical warning_links reconciliation.\n- `codesdd sdd lint feature FEAT-0001`: inspect feature scope before execution.\n- `codesdd sdd next`: see what can start now.\n- `codesdd sdd start FEAT-0001`: open feature execution.\n- `codesdd sdd context FEAT-0001`: generate focused context.\n- `codesdd sdd frontend-impact FEAT-0001 --status required|none --reason \"...\"`: declare frontend impact.\n- `codesdd sdd finalize --ref FEAT-0001`: consolidate memory and close.\n";
 export declare const PROMPT_01_INGESTAO_DEPOSITO_MD = "# Prompt: Source Intake\n\nUse the skills:\n- source-intake-sdd\n- business-extractor-sdd\n- frontend-extractor-sdd\n- planning-normalizer-sdd\n\nObjective:\n1. Scan `.sdd/sources/`.\n2. Update `.sdd/state/source-index.yaml`.\n3. Consolidate canonical context (`architecture`, `service-catalog`, `tech-stack`, `integration-contracts`, and frontend when enabled).\n4. Generate an executable trail (EPIC plus FEATs) with source traceability.\n\nRequired output:\n- summary of sources read;\n- IDs created or updated (EPIC/FEAT/FGAP/INS when ambiguity exists);\n- recommended next CLI commands.\n";
 export declare const PROMPT_02_NORMALIZAR_PLANEJAMENTO_MD = "# Prompt: Normalize Planning\n\nObjective:\nTurn consolidated material into an executable plan with clear dependencies.\n\nInstructions:\n1. Start from `.sdd/state/source-index.yaml` and `.sdd/core/*.md`.\n2. Propose EPICs and FEATs with clear English names.\n3. Define dependencies (`blocked_by`) and conflicts (`lock_domains`).\n4. List what can run in parallel.\n5. End with a documentation consolidation checklist per feature.\n";
 export declare const PROMPT_03_EXECUCAO_FEATURE_MD = "# Prompt: Feature Execution\n\nObjective:\nExecute a FEAT without losing traceability.\n\nInstructions:\n1. Treat implementation, edit, validation, execution, and finalize requests as requiring CodeSDD planning unless the user explicitly marks the request as read-only or outside CodeSDD.\n2. Run `codesdd sdd next` and bind the work to the active or ready FEAT returned by CodeSDD.\n3. Run `codesdd sdd context FEAT-0001`.\n4. Update `.sdd/active/FEAT-0001/` (spec, plan, tasks, changelog).\n5. Implement.\n6. Update `.sdd/active/FEAT-0001/5-quality.yaml` with evidence or a formal exception; quality contracts are blocking by default.\n7. Update affected canonical docs.\n8. Declare frontend impact with `codesdd sdd frontend-impact FEAT-0001 ...`.\n9. Ensure architectural-impact FEATs have an ADR before finalize.\n10. Finish with `codesdd sdd finalize --ref FEAT-0001`.\n";

package/dist/core/sdd/default-bootstrap-files.js

@@ -81,8 +81,6 @@ If you have never used CodeSDD, follow this order.
 In the terminal, from your project directory:
 
 \`\`\`bash
-codesdd install --tools none --lang en-US --layout en-US
-codesdd sdd init --frontend --lang en-US --layout en-US
 codesdd sdd init-context --frontend --lang en-US --layout en-US
 codesdd sdd check --render
 codesdd sdd rebuild --from-disk --dry-run

package/dist/core/sdd/default-skills.js

@@ -73,8 +73,8 @@ const SKILL_METADATA_OVERRIDES = {
         description: 'Canonical Python/Flask agentic backend skill with Clean Architecture boundaries, tenant/security authority-source rules, CodeSDD decision support (runtime-safe), production-readiness guidance, and maintainable quality gates.',
     },
     'devtrack-api': {
-        title: 'DevTrack API',
-        description: 'Model-agnostic backend engineering and governance skill for DevTrack APIs using NestJS, TypeORM, DDD/Clean Architecture boundaries, evidence-based validation, and safe operational delivery.',
+        title: 'CodeSDD API Profiles',
+        description: 'Compatibility backend engineering and governance skill for CodeSDD API profiles using NestJS, TypeORM, DDD/Clean Architecture boundaries, Swagger/OpenAPI, .env.example, package scripts, route guards, auth/authz planning, application use cases, evidence-based validation, and safe operational delivery.',
     },
     'devtrack-angular': {
         title: 'DevTrack Angular Admin',
@@ -554,8 +554,9 @@ export function buildCuratedBundlesCurationData(layout = 'en-US') {
             bundle_id: 'architecture-backend',
             canonical_path: '.sdd/skills/curated/devtrack-api/',
             notes: [
-                'Canonical directory for the DevTrack API skill; includes agents/ and references/.',
-                'Operational default: API/backend work uses devtrack-api unless an explicit skill/profile overrides it; Python/Flask API work uses api-clean-flask-langgraph.',
+                'Canonical directory for the CodeSDD API profile compatibility skill; includes agents/ and references/.',
+                'Operational default: API/backend work selects one of minimal-rest, rest-auth-rbac, rest-crud-typeorm, evented-api, ai-agent-api, or full-foundation-compatible; devtrack-api remains compatibility-only and Python/Flask API work uses api-clean-flask-langgraph.',
+                'Tool-level API baseline: Swagger/OpenAPI, .env.example, package scripts with cleanup/cleanup:install and port-safe start/start:dev bootstrap, application use cases, route guards, and auth/authz planning are inferred minimums unless an explicit profile exception is recorded.',
             ],
         },
         {
@@ -620,7 +621,8 @@ export function buildCuratedBundlesMarkdown() {
     lines.push('- Canonical file: `.sdd/skills/curated/api-clean-flask-langgraph/SKILL.md`.');
     lines.push('- `devtrack-api` belongs to bundle `architecture-backend`.');
     lines.push('- Canonical directory: `.sdd/skills/curated/devtrack-api/` (includes `agents/` and `references/`).');
-    lines.push('- Operational default: API/backend work uses `devtrack-api` unless an explicit skill/profile overrides it; Python/Flask API work uses `api-clean-flask-langgraph`.');
+    lines.push('- Operational default: API/backend work selects one of `minimal-rest`, `rest-auth-rbac`, `rest-crud-typeorm`, `evented-api`, `ai-agent-api`, or `full-foundation-compatible`; `devtrack-api` remains compatibility-only and Python/Flask API work uses `api-clean-flask-langgraph`.');
+    lines.push('- Tool-level API baseline: Swagger/OpenAPI, `.env.example`, package scripts with `cleanup`/`cleanup:install` and port-safe `start`/`start:dev` bootstrap, application use cases, route guards, and auth/authz planning are inferred minimums unless an explicit profile exception is recorded.');
     lines.push('- `devtrack-angular` belongs to bundle `frontend-product` as the Angular Admin/backoffice skill.');
     lines.push('- Canonical directory: `.sdd/skills/curated/devtrack-angular/` (includes `agents/` and `references/`).');
     lines.push('- Operational default: Angular Admin/backoffice work that names admin pages, dashboards, CRUD, data grids, admin Formly, admin NGXS/state, official Angular framework patterns, permissions, reports, workflow, admin realtime, or admin chat should use `devtrack-angular` unless an explicit skill/profile overrides it.');

package/dist/core/sdd/devtrack-api-appliance.d.ts

@@ -1,6 +1,10 @@
 import { type PluginArtifactManifest, type PluginRuntimeInvocationPlan } from './plugin-broker.js';
 import { type PluginManifest } from './plugin-manifest.js';
 import type { PluginArtifactKind, PluginArtifactMapEntry, PluginArtifactRole } from './plugin-sdk-contract.js';
+import { CODESDD_API_PROFILE_FAMILY_ID, type CodeSddApiProfileId, type ResolvedCodeSddApiProfile } from './api-profile-catalog.js';
+import { CODESDD_API_FOUNDATION_SHARED_BASELINE, CODESDD_API_SHARED_BASELINE_QUALITY_GATES, CODESDD_API_SHARED_BASELINE_REQUIREMENTS, type CodeSddApiSharedBaselineRequirement } from './api-foundation-baseline.js';
+import { CODESDD_FULL_FOUNDATION_COMPATIBLE_PROFILE_ID, CODESDD_FULL_FOUNDATION_PARITY_DIMENSIONS, CODESDD_FULL_FOUNDATION_PARITY_MATRIX, CODESDD_FULL_FOUNDATION_PARITY_QUALITY_GATES, type CodeSddFullFoundationParityDimension } from './api-foundation-parity.js';
+import { type CodeSddApiProfileDryRunProjection } from './api-profile-dry-run-projection.js';
 export declare const DEVTRACK_API_APPLIANCE_PLUGIN_ID = "codesdd-plugin-devtrack-api";
 export declare const DEVTRACK_API_APPLIANCE_CAPABILITIES: readonly ["scaffold.project", "generate.domain", "generate.crud", "validate.structure", "evidence.emit"];
 declare const DEVTRACK_API_SCAFFOLD_CAPABILITY = "scaffold.project";
@@ -23,6 +27,7 @@ export interface DevTrackApiScaffoldDryRunInput {
     feature_ref: string;
     project_name: string;
     package_name?: string;
+    api_profile?: string;
     created_at?: string;
     operation_id?: string;
     requested_write_scope?: string[];
@@ -51,12 +56,41 @@ export interface DevTrackApiScaffoldEvidenceManifest {
         status: 'pending';
     }>;
     quality_gates: string[];
+    api_profile: {
+        family_id: typeof CODESDD_API_PROFILE_FAMILY_ID;
+        selected_profile: CodeSddApiProfileId;
+        requested_profile?: string;
+        legacy_alias: boolean;
+        migration_notice?: string;
+        inherited_baseline: typeof CODESDD_API_SHARED_BASELINE_REQUIREMENTS;
+    };
+    profile_projection: CodeSddApiProfileDryRunProjection;
+    foundation_baseline: {
+        id: typeof CODESDD_API_FOUNDATION_SHARED_BASELINE.id;
+        version: typeof CODESDD_API_FOUNDATION_SHARED_BASELINE.version;
+        source: typeof CODESDD_API_FOUNDATION_SHARED_BASELINE.foundation_reference;
+        requirement_ids: typeof CODESDD_API_SHARED_BASELINE_REQUIREMENTS;
+        quality_gates: typeof CODESDD_API_SHARED_BASELINE_QUALITY_GATES;
+        requirements: CodeSddApiSharedBaselineRequirement[];
+    };
+    full_foundation_compatibility?: {
+        id: typeof CODESDD_FULL_FOUNDATION_PARITY_MATRIX.id;
+        version: typeof CODESDD_FULL_FOUNDATION_PARITY_MATRIX.version;
+        profile_id: typeof CODESDD_FULL_FOUNDATION_COMPATIBLE_PROFILE_ID;
+        source: typeof CODESDD_FULL_FOUNDATION_PARITY_MATRIX.foundation_reference;
+        dimension_ids: typeof CODESDD_FULL_FOUNDATION_PARITY_DIMENSIONS;
+        quality_gates: typeof CODESDD_FULL_FOUNDATION_PARITY_QUALITY_GATES;
+        dimensions: Array<CodeSddFullFoundationParityDimension & {
+            status: 'pending';
+        }>;
+    };
 }
 export type DevTrackApiScaffoldDryRunPlan = {
     schema_version: 1;
     status: 'planned';
     created_at: string;
     operation_id: string;
+    api_profile: ResolvedCodeSddApiProfile;
     project_name: string;
     package_name: string;
     runtime_plan: PluginRuntimeInvocationPlan;