@devtrack-solution/codesdd 1.2.2

package/dist/core/sdd/docs-sync.d.ts

@@ -0,0 +1,21 @@
+import type { SddPaths, SddRuntimeConfig } from './state.js';
+export declare const README_SDD_BLOCK_START = "<!-- SDD:ONBOARDING:START -->";
+export declare const README_SDD_BLOCK_END = "<!-- SDD:ONBOARDING:END -->";
+export declare const AGENT_SDD_BLOCK_START = "<!-- SDD:GUIA:START -->";
+export declare const AGENT_SDD_BLOCK_END = "<!-- SDD:GUIA:END -->";
+export declare const ROOT_AGENTS_SDD_BLOCK_START = "<!-- SDD:ROOT-AGENTS:START -->";
+export declare const ROOT_AGENTS_SDD_BLOCK_END = "<!-- SDD:ROOT-AGENTS:END -->";
+export declare function syncSddGuideDocs(projectRoot: string, paths: SddPaths, config?: SddRuntimeConfig): Promise<{
+    updatedInternalReadme: boolean;
+    updatedReadme: boolean;
+    updatedAgentGuide: boolean;
+    updatedRootAgents: boolean;
+    readmeHadMarkers: boolean;
+    agentHadMarkers: boolean;
+    rootAgentsHadMarkers: boolean;
+}>;
+export declare function validateSddGuideDocs(projectRoot: string, paths: SddPaths, config?: SddRuntimeConfig): Promise<{
+    documentationSync: boolean;
+    missingBlocks: string[];
+}>;
+//# sourceMappingURL=docs-sync.d.ts.map

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

@@ -0,0 +1,231 @@
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import { buildSddInternalReadme } from './default-bootstrap-files.js';
+import { CLI_NAME } from '../branding.js';
+export const README_SDD_BLOCK_START = '<!-- SDD:ONBOARDING:START -->';
+export const README_SDD_BLOCK_END = '<!-- SDD:ONBOARDING:END -->';
+export const AGENT_SDD_BLOCK_START = '<!-- SDD:GUIA:START -->';
+export const AGENT_SDD_BLOCK_END = '<!-- SDD:GUIA:END -->';
+export const ROOT_AGENTS_SDD_BLOCK_START = '<!-- SDD:ROOT-AGENTS:START -->';
+export const ROOT_AGENTS_SDD_BLOCK_END = '<!-- SDD:ROOT-AGENTS:END -->';
+async function fileExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function upsertMarkedBlock(source, startMarker, endMarker, blockContent) {
+    const replacement = `${startMarker}\n${blockContent.trim()}\n${endMarker}`;
+    const startIndex = source.indexOf(startMarker);
+    const endIndex = source.indexOf(endMarker);
+    if (startIndex >= 0 && endIndex > startIndex) {
+        const before = source.slice(0, startIndex);
+        const after = source.slice(endIndex + endMarker.length);
+        const next = `${before}${replacement}${after}`;
+        return { content: next, changed: next !== source, hasMarkers: true };
+    }
+    const prefix = source.length > 0 && !source.endsWith('\n') ? `${source}\n\n` : `${source}\n`;
+    const next = `${prefix}${replacement}\n`;
+    return { content: next, changed: true, hasMarkers: false };
+}
+function buildReadmeBlock(memoryDir, config) {
+    return `## Onboarding SDD
+
+Operational authority:
+- Canonical operational state, planning, dependencies, blockers, and handoff live only in \`${memoryDir}/state/*.yaml\`.
+- 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.
+
+Read order for any new agent:
+1. \`README.md\` (this block)
+2. \`${memoryDir}/AGENT.md\`
+3. \`${memoryDir}/core/index.md\`
+4. \`${memoryDir}/core/arquitetura.md\`
+5. \`${memoryDir}/core/servicos.md\`
+6. \`${memoryDir}/core/spec-tecnologica.md\`
+7. \`${memoryDir}/core/repo-map.md\`
+8. \`${memoryDir}/core/fontes.md\`
+9. \`${memoryDir}/core/frontend-sitemap.md\` (when frontend is enabled)
+10. \`${memoryDir}/core/frontend-decisions.md\` (when frontend is enabled)
+
+Essential commands:
+- \`${CLI_NAME} sdd onboard system\`
+- \`${CLI_NAME} sdd next\`
+- \`${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>\``;
+}
+function buildAgentGuideBlock(memoryDir, config) {
+    const planningDir = config?.folders.planning || 'planning';
+    const activeDir = config?.folders.active || 'active';
+    const depositoDir = config?.folders.deposito || 'sources';
+    const promptsDir = 'prompts';
+    return `# SDD Operational Guide
+
+Official workflow:
+1. Run \`${CLI_NAME} sdd onboard system\`.
+2. Use \`${CLI_NAME} sdd next\` to choose ready work.
+3. Use \`${CLI_NAME} sdd start <FEAT-ID>\` only when the selected item is not already active.
+4. Use \`${CLI_NAME} sdd context <FEAT-ID>\` before coding.
+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>\`.
+
+- Canonical state: \`${memoryDir}/state/*.yaml\`
+- Views: \`${memoryDir}/core/*.md\` and \`${memoryDir}/${planningDir}/*.md\`
+- Active workspace per feature: \`${memoryDir}/${activeDir}/<FEAT-ID>/\`
+- Quality contract per active feature: \`${memoryDir}/${activeDir}/<FEAT-ID>/5-quality.yaml\`
+- Raw sources: \`${memoryDir}/${depositoDir}/\` (PRDs, RFCs, wireframes, references)
+- Recommended prompts: \`${memoryDir}/${promptsDir}/\`
+
+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.`;
+}
+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.
+
+Required execution order:
+1. Run \`${CLI_NAME} sdd onboard system\` before broad work.
+2. Run \`${CLI_NAME} sdd next\` and use the active or ready feature returned by SDD.
+3. Use \`${CLI_NAME} sdd context <FEAT-ID>\` before coding.
+4. Before archive/finalize, update \`${memoryDir}/active/<FEAT-ID>/5-quality.yaml\` with validation evidence or a formal exception.
+5. Before archive/finalize, declare frontend impact with \`${CLI_NAME} sdd frontend-impact <FEAT-ID> ...\`.
+6. Before archive/finalize, update the documentation affected by the feature:
+   - \`README.md\`
+   - \`${memoryDir}/AGENT.md\`
+   - \`${memoryDir}/core/*.md\`
+   - \`AGENTS.md\`
+   - \`AGENT.md\`
+7. Run \`${CLI_NAME} sdd finalize --ref <FEAT-ID>\` to consolidate memory.
+
+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.`;
+}
+export async function syncSddGuideDocs(projectRoot, paths, config) {
+    const readmePath = path.join(projectRoot, 'README.md');
+    const internalReadmePath = path.join(paths.memoryRoot, 'README.md');
+    const agentPath = path.join(paths.memoryRoot, 'AGENT.md');
+    const legacyAgentPath = path.join(paths.memoryRoot, 'agente.md');
+    const agentsPath = path.join(projectRoot, 'AGENTS.md');
+    const agentCompatPath = path.join(projectRoot, 'AGENT.md');
+    const memoryDirName = path.relative(projectRoot, paths.memoryRoot) || '.sdd';
+    const readmeExists = await fileExists(readmePath);
+    const agentExists = await fileExists(agentPath);
+    const legacyAgentExists = await fileExists(legacyAgentPath);
+    const agentsExists = await fileExists(agentsPath);
+    const agentCompatExists = await fileExists(agentCompatPath);
+    const readmeRaw = readmeExists ? await fs.readFile(readmePath, 'utf-8') : '# Projeto\n';
+    const agentRaw = agentExists
+        ? await fs.readFile(agentPath, 'utf-8')
+        : legacyAgentExists
+            ? await fs.readFile(legacyAgentPath, 'utf-8')
+            : '';
+    const agentsRaw = agentsExists ? await fs.readFile(agentsPath, 'utf-8') : '# AGENTS\n';
+    const agentCompatRaw = agentCompatExists
+        ? await fs.readFile(agentCompatPath, 'utf-8')
+        : '# AGENT\n';
+    const readmeUpdate = upsertMarkedBlock(readmeRaw, README_SDD_BLOCK_START, README_SDD_BLOCK_END, buildReadmeBlock(memoryDirName, config));
+    const agentUpdate = upsertMarkedBlock(agentRaw, AGENT_SDD_BLOCK_START, AGENT_SDD_BLOCK_END, buildAgentGuideBlock(memoryDirName, config));
+    const agentsUpdate = upsertMarkedBlock(agentsRaw, ROOT_AGENTS_SDD_BLOCK_START, ROOT_AGENTS_SDD_BLOCK_END, buildRootAgentsBlock(memoryDirName));
+    const agentCompatUpdate = upsertMarkedBlock(agentCompatRaw, ROOT_AGENTS_SDD_BLOCK_START, ROOT_AGENTS_SDD_BLOCK_END, buildRootAgentsBlock(memoryDirName));
+    const internalReadmeContent = buildSddInternalReadme(memoryDirName, {
+        discovery: config?.folders.discovery,
+        planning: config?.folders.planning,
+        skills: config?.folders.skills,
+        templates: config?.folders.templates,
+        active: config?.folders.active,
+        deposito: config?.folders.deposito,
+        prompts: 'prompts',
+    });
+    const currentInternalReadme = (await fileExists(internalReadmePath))
+        ? await fs.readFile(internalReadmePath, 'utf-8')
+        : '';
+    const internalReadmeChanged = currentInternalReadme !== internalReadmeContent;
+    if (internalReadmeChanged) {
+        await fs.writeFile(internalReadmePath, internalReadmeContent, 'utf-8');
+    }
+    if (readmeUpdate.changed) {
+        await fs.writeFile(readmePath, readmeUpdate.content, 'utf-8');
+    }
+    if (agentUpdate.changed) {
+        await fs.writeFile(agentPath, agentUpdate.content, 'utf-8');
+    }
+    if (agentsUpdate.changed) {
+        await fs.writeFile(agentsPath, agentsUpdate.content, 'utf-8');
+    }
+    if (agentCompatUpdate.changed) {
+        await fs.writeFile(agentCompatPath, agentCompatUpdate.content, 'utf-8');
+    }
+    return {
+        updatedInternalReadme: internalReadmeChanged,
+        updatedReadme: readmeUpdate.changed,
+        updatedAgentGuide: agentUpdate.changed,
+        updatedRootAgents: agentsUpdate.changed || agentCompatUpdate.changed,
+        readmeHadMarkers: readmeUpdate.hasMarkers,
+        agentHadMarkers: agentUpdate.hasMarkers,
+        rootAgentsHadMarkers: agentsUpdate.hasMarkers && agentCompatUpdate.hasMarkers,
+    };
+}
+export async function validateSddGuideDocs(projectRoot, paths, config) {
+    const readmePath = path.join(projectRoot, 'README.md');
+    const internalReadmePath = path.join(paths.memoryRoot, 'README.md');
+    const memoryDirName = path.relative(projectRoot, paths.memoryRoot) || '.sdd';
+    const agentPath = path.join(paths.memoryRoot, 'AGENT.md');
+    const legacyAgentPath = path.join(paths.memoryRoot, 'agente.md');
+    const agentsPath = path.join(projectRoot, 'AGENTS.md');
+    const agentCompatPath = path.join(projectRoot, 'AGENT.md');
+    const missingBlocks = [];
+    const readmeRaw = (await fileExists(readmePath)) ? await fs.readFile(readmePath, 'utf-8') : '';
+    const internalReadmeRaw = (await fileExists(internalReadmePath))
+        ? await fs.readFile(internalReadmePath, 'utf-8')
+        : '';
+    const agentRaw = (await fileExists(agentPath))
+        ? await fs.readFile(agentPath, 'utf-8')
+        : (await fileExists(legacyAgentPath))
+            ? await fs.readFile(legacyAgentPath, 'utf-8')
+            : '';
+    const agentsRaw = (await fileExists(agentsPath)) ? await fs.readFile(agentsPath, 'utf-8') : '';
+    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');
+    }
+    if (internalReadmeRaw !==
+        buildSddInternalReadme(path.relative(projectRoot, paths.memoryRoot) || '.sdd', {
+            discovery: config?.folders.discovery,
+            planning: config?.folders.planning,
+            skills: config?.folders.skills,
+            templates: config?.folders.templates,
+            active: config?.folders.active,
+            deposito: config?.folders.deposito,
+            prompts: 'prompts',
+        })) {
+        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');
+    }
+    return {
+        documentationSync: missingBlocks.length === 0,
+        missingBlocks,
+    };
+}
+//# sourceMappingURL=docs-sync.js.map

package/dist/core/sdd/domain/helpers.d.ts

@@ -0,0 +1,6 @@
+export declare function slugify(value: string): string;
+export declare function stripFunctionalTitlePrefixes(value: string): string;
+export declare function computeCanonicalTitle(value: string): string;
+export declare function buildFeatureTitle(featureId: string, title: string): string;
+export declare function markdownInsightTemplate(id: string, title: string, content: string): string;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/core/sdd/domain/helpers.js

@@ -0,0 +1,37 @@
+export function slugify(value) {
+    return value
+        .toLowerCase()
+        .normalize('NFD')
+        .replace(/[\u0300-\u036f]/g, '')
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .replace(/-{2,}/g, '-');
+}
+export function stripFunctionalTitlePrefixes(value) {
+    return value
+        .replace(/^\s*debate:\s*/i, '')
+        .replace(/^\s*insight:\s*/i, '')
+        .trim();
+}
+export function computeCanonicalTitle(value) {
+    const normalized = stripFunctionalTitlePrefixes(value)
+        .replace(/\s+/g, ' ')
+        .trim();
+    const fallback = normalized || 'Untitled canonical item';
+    return fallback.slice(0, 60).trim();
+}
+export function buildFeatureTitle(featureId, title) {
+    return `${featureId}: ${title}`;
+}
+export function markdownInsightTemplate(id, title, content) {
+    const now = new Date().toISOString();
+    return `# Insight: ${title}
+  
+> ID: ${id}
+> Status: NEW
+> Date: ${now}
+
+${content}
+`;
+}
+//# sourceMappingURL=helpers.js.map

package/dist/core/sdd/domain/lifecycle-guardrails.d.ts

@@ -0,0 +1,22 @@
+import type { BacklogItem } from '../types.js';
+export interface LifecycleDependencyCheck {
+    ok: boolean;
+    unresolved: string[];
+}
+export interface LifecycleLockCheck {
+    ok: boolean;
+    conflicts: string[];
+}
+export interface FeatureStartGuardrails {
+    blocked_check: LifecycleDependencyCheck;
+    lock_check: LifecycleLockCheck;
+    forced: boolean;
+}
+export interface FeatureFinalizeGuardrails {
+    dependency_check: LifecycleDependencyCheck;
+    forced: boolean;
+    reasons: string[];
+}
+export declare function evaluateFeatureStartGuardrails(feature: BacklogItem, backlogItems: BacklogItem[], forced?: boolean): FeatureStartGuardrails;
+export declare function evaluateFeatureFinalizeGuardrails(feature: BacklogItem, backlogItems: BacklogItem[], forced?: boolean): FeatureFinalizeGuardrails;
+//# sourceMappingURL=lifecycle-guardrails.d.ts.map

package/dist/core/sdd/domain/lifecycle-guardrails.js

@@ -0,0 +1,31 @@
+import { lockConflictWithActive, unresolvedDependencies } from '../legacy-operations.js';
+export function evaluateFeatureStartGuardrails(feature, backlogItems, forced = false) {
+    const unresolved = unresolvedDependencies(feature, backlogItems);
+    const conflicts = lockConflictWithActive(feature, backlogItems);
+    return {
+        blocked_check: {
+            ok: unresolved.length === 0,
+            unresolved,
+        },
+        lock_check: {
+            ok: conflicts.length === 0,
+            conflicts,
+        },
+        forced,
+    };
+}
+export function evaluateFeatureFinalizeGuardrails(feature, backlogItems, forced = false) {
+    const unresolved = unresolvedDependencies(feature, backlogItems);
+    const reasons = unresolved.length > 0
+        ? [`blocked_by pendente no finalize (${unresolved.join(', ')}). Resolva dependencias ou use --force-transition.`]
+        : [];
+    return {
+        dependency_check: {
+            ok: unresolved.length === 0,
+            unresolved,
+        },
+        forced,
+        reasons,
+    };
+}
+//# sourceMappingURL=lifecycle-guardrails.js.map

package/dist/core/sdd/domain/lifecycle-hooks.d.ts

@@ -0,0 +1,16 @@
+export type LifecycleHookEvent = 'before-approve' | 'after-approve' | 'before-start' | 'after-start' | 'before-finalize' | 'after-finalize' | 'before-migrate' | 'after-migrate';
+export interface LifecycleHookContext {
+    event: LifecycleHookEvent;
+    projectRoot: string;
+    featureId?: string;
+    entityId?: string;
+    stage?: string;
+    options?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+}
+export type LifecycleHook = (context: LifecycleHookContext) => void | Promise<void>;
+export declare function registerLifecycleHook(event: LifecycleHookEvent, hook: LifecycleHook): () => void;
+export declare function unregisterLifecycleHook(event: LifecycleHookEvent, hook: LifecycleHook): void;
+export declare function clearLifecycleHooks(): void;
+export declare function runLifecycleHooks(event: LifecycleHookEvent, context: Omit<LifecycleHookContext, 'event'>): Promise<void>;
+//# sourceMappingURL=lifecycle-hooks.d.ts.map

package/dist/core/sdd/domain/lifecycle-hooks.js

@@ -0,0 +1,27 @@
+const lifecycleHooks = new Map();
+export function registerLifecycleHook(event, hook) {
+    const hooks = lifecycleHooks.get(event) ?? [];
+    hooks.push(hook);
+    lifecycleHooks.set(event, hooks);
+    return () => unregisterLifecycleHook(event, hook);
+}
+export function unregisterLifecycleHook(event, hook) {
+    const hooks = lifecycleHooks.get(event);
+    if (!hooks) {
+        return;
+    }
+    lifecycleHooks.set(event, hooks.filter((entry) => entry !== hook));
+}
+export function clearLifecycleHooks() {
+    lifecycleHooks.clear();
+}
+export async function runLifecycleHooks(event, context) {
+    const hooks = lifecycleHooks.get(event) ?? [];
+    for (const hook of hooks) {
+        await hook({
+            event,
+            ...context,
+        });
+    }
+}
+//# sourceMappingURL=lifecycle-hooks.js.map

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

@@ -0,0 +1,15 @@
+import type { SddPaths } from '../state.js';
+export interface ArchiveArchivedLifecycleCollision {
+    feature_id: string;
+    legacy_archive_path: string;
+    canonical_archived_path: string;
+    message: string;
+}
+export interface PostActiveValidationResult {
+    ok: boolean;
+    reasons: string[];
+}
+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>;
+//# sourceMappingURL=post-active-validation.d.ts.map

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

@@ -0,0 +1,71 @@
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+const LEGACY_ARCHIVE_DIR = 'archive';
+const FEATURE_DIR_PATTERN = /^FEAT-\d{3,}$/;
+async function exists(targetPath) {
+    try {
+        await fs.access(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function relativePath(paths, targetPath) {
+    return path.relative(paths.projectRoot, targetPath) || '.';
+}
+function legacyArchiveRoot(paths) {
+    return path.join(paths.memoryRoot, LEGACY_ARCHIVE_DIR);
+}
+export async function detectArchiveArchivedLifecycleCollisions(paths, featureId) {
+    const legacyRoot = legacyArchiveRoot(paths);
+    if (path.resolve(legacyRoot) === path.resolve(paths.archivedDir)) {
+        return [];
+    }
+    if (!(await exists(legacyRoot))) {
+        return [];
+    }
+    const entries = await fs.readdir(legacyRoot, { withFileTypes: true }).catch(() => []);
+    const featureIds = featureId
+        ? (await exists(path.join(legacyRoot, featureId)) ? [featureId] : [])
+        : entries
+            .filter((entry) => entry.isDirectory() && FEATURE_DIR_PATTERN.test(entry.name))
+            .map((entry) => entry.name);
+    return featureIds.map((id) => {
+        const legacyPath = path.join(legacyRoot, id);
+        const canonicalPath = path.join(paths.archivedDir, id);
+        return {
+            feature_id: id,
+            legacy_archive_path: relativePath(paths, legacyPath),
+            canonical_archived_path: relativePath(paths, canonicalPath),
+            message: `${id} has a non-canonical lifecycle archive workspace at ` +
+                `${relativePath(paths, legacyPath)}; completed FEAT workspaces must live only under ` +
+                `${relativePath(paths, paths.archivedDir)}.`,
+        };
+    });
+}
+export async function validatePreFinalizeArchiveCanonicalization(paths, featureId) {
+    const collisions = await detectArchiveArchivedLifecycleCollisions(paths, featureId);
+    return {
+        ok: collisions.length === 0,
+        reasons: collisions.map((collision) => collision.message),
+    };
+}
+export async function validatePostActiveFeaturePlacement(paths, featureId) {
+    const activePath = path.join(paths.activeDir, featureId);
+    const archivedPath = path.join(paths.archivedDir, featureId);
+    const reasons = [];
+    if (await exists(activePath)) {
+        reasons.push(`${featureId} still exists in ${relativePath(paths, activePath)} after finalize.`);
+    }
+    if (!(await exists(archivedPath))) {
+        reasons.push(`${featureId} was not found in canonical ${relativePath(paths, archivedPath)} after finalize.`);
+    }
+    const collisions = await detectArchiveArchivedLifecycleCollisions(paths, featureId);
+    reasons.push(...collisions.map((collision) => collision.message));
+    return {
+        ok: reasons.length === 0,
+        reasons,
+    };
+}
+//# sourceMappingURL=post-active-validation.js.map

package/dist/core/sdd/domain/traceability.d.ts

@@ -0,0 +1,8 @@
+import type { WorkspaceChangelogDocument, WorkspaceQualityDocument, WorkspaceSpecDocument } from '../workspace-schemas.js';
+type TraceabilityResult = {
+    ok: boolean;
+    reasons: string[];
+};
+export declare function evaluateWorkspaceTraceability(projectRoot: string, spec: WorkspaceSpecDocument, changelog: WorkspaceChangelogDocument, quality: WorkspaceQualityDocument): TraceabilityResult;
+export {};
+//# sourceMappingURL=traceability.d.ts.map

package/dist/core/sdd/domain/traceability.js

@@ -0,0 +1,83 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+function normalizedCorpus(parts) {
+    return parts
+        .map((part) => (part || '').trim().toLowerCase())
+        .filter(Boolean)
+        .join('\n');
+}
+function refPresent(corpus, ref) {
+    return corpus.includes(ref.trim().toLowerCase());
+}
+function fileExists(projectRoot, filePath) {
+    if (!filePath.trim())
+        return false;
+    const target = path.isAbsolute(filePath) ? filePath : path.join(projectRoot, filePath);
+    const relative = path.relative(projectRoot, target);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+        return false;
+    }
+    return existsSync(target);
+}
+export function evaluateWorkspaceTraceability(projectRoot, spec, changelog, quality) {
+    const traceability = quality.traceability;
+    const reasons = [];
+    if (!traceability || traceability.requirements.length === 0) {
+        reasons.push('traceability.requirements must contain at least one requirement mapping before finalize');
+        return { ok: false, reasons };
+    }
+    const specAnchor = traceability.spec_anchor;
+    if (!specAnchor.spec_updated_at.trim()) {
+        reasons.push('traceability.spec_anchor.spec_updated_at must be recorded');
+    }
+    else if (specAnchor.spec_updated_at !== spec.updated_at) {
+        reasons.push(`traceability.spec_anchor.spec_updated_at (${specAnchor.spec_updated_at}) does not match 1-spec.yaml updated_at (${spec.updated_at})`);
+    }
+    if (specAnchor.changelog_refs.length === 0) {
+        reasons.push('traceability.spec_anchor.changelog_refs must reference the changelog entry that synced the current spec');
+    }
+    const changelogCorpus = normalizedCorpus(changelog.entries.flatMap((entry) => [entry.action, entry.details, ...(entry.refs || [])]));
+    const evidenceCorpus = normalizedCorpus([
+        ...quality.evidence_log.flatMap((entry) => [entry.kind, entry.result, entry.artifact]),
+        ...quality.acceptance_matrix.flatMap((entry) => [entry.criterion, entry.evidence]),
+    ]);
+    for (const ref of specAnchor.changelog_refs) {
+        if (!refPresent(changelogCorpus, ref)) {
+            reasons.push(`traceability spec anchor changelog ref "${ref}" was not found in 4-changelog.yaml`);
+        }
+    }
+    const requirementRefs = new Set();
+    for (const requirement of traceability.requirements) {
+        if (requirementRefs.has(requirement.requirement_ref)) {
+            reasons.push(`traceability requirement_ref "${requirement.requirement_ref}" is duplicated`);
+            continue;
+        }
+        requirementRefs.add(requirement.requirement_ref);
+        if (requirement.semantic_coverage !== 'covered' &&
+            requirement.semantic_coverage !== 'not_applicable') {
+            reasons.push(`traceability requirement "${requirement.requirement_ref}" must be semantically covered before finalize`);
+        }
+        for (const codeRef of requirement.code_refs) {
+            if (!fileExists(projectRoot, codeRef.path)) {
+                reasons.push(`traceability code ref "${codeRef.path}" for requirement "${requirement.requirement_ref}" does not exist`);
+            }
+        }
+        for (const testRef of requirement.test_refs) {
+            if (testRef.path && !fileExists(projectRoot, testRef.path)) {
+                reasons.push(`traceability test ref path "${testRef.path}" for requirement "${requirement.requirement_ref}" does not exist`);
+            }
+        }
+        for (const ref of requirement.changelog_refs) {
+            if (!refPresent(changelogCorpus, ref)) {
+                reasons.push(`traceability changelog ref "${ref}" for requirement "${requirement.requirement_ref}" was not found in 4-changelog.yaml`);
+            }
+        }
+        for (const ref of requirement.evidence_refs) {
+            if (!refPresent(evidenceCorpus, ref)) {
+                reasons.push(`traceability evidence ref "${ref}" for requirement "${requirement.requirement_ref}" was not found in 5-quality.yaml evidence`);
+            }
+        }
+    }
+    return { ok: reasons.length === 0, reasons };
+}
+//# sourceMappingURL=traceability.js.map

package/dist/core/sdd/domain/transition-engine.d.ts

@@ -0,0 +1,49 @@
+import type { BacklogItem, TransitionLogEvent, TransitionLogState } from '../types.js';
+import type { StateStore } from '../store/state-store.js';
+export type EntityStatus = string;
+export declare class TransitionEngine {
+    private readonly transitionLogStore;
+    private static allowedTransitions;
+    constructor(transitionLogStore: StateStore<TransitionLogState>);
+    /**
+     * Valida se a transição de estado desejada é logicamente permitida pelo grafo de transições,
+     * e bloqueia transições caso haja violações arquiteturais ou de lente documental.
+     */
+    static assertValid(entityType: string, fromStatus: EntityStatus, toStatus: EntityStatus, options?: {
+        forceTransition?: boolean;
+        lensViolations?: string[];
+    }): void;
+    /**
+     * LEGACY: Synchronous transition for operations.ts monolithic snapshot logic.
+     * Do not use in new Domain Services.
+     */
+    static legacyApplyTransition<T extends {
+        id: string;
+        status: EntityStatus;
+    }>(entityType: string, entity: T, toStatus: EntityStatus, transitionLog: TransitionLogEvent[], options?: {
+        actor?: string;
+        reason?: string;
+        timestamp?: string;
+        sourceCommand?: string;
+        forceTransition?: boolean;
+        lensViolations?: string[];
+        afterTransition?: (entity: T) => void;
+    }): TransitionLogEvent;
+    applyTransition<T extends {
+        id: string;
+        status: EntityStatus;
+    }>(entityType: string, entity: T, toStatus: EntityStatus, options?: {
+        actor?: string;
+        reason?: string;
+        timestamp?: string;
+        sourceCommand?: string;
+        forceTransition?: boolean;
+        lensViolations?: string[];
+        afterTransition?: (entity: T) => void;
+    }): Promise<TransitionLogEvent>;
+    /**
+     * Validações de negócio granulares antes de finalizações ou progressos de FEAT.
+     */
+    validateFeatureStartGuardrails(feature: BacklogItem): Record<string, any>;
+}
+//# sourceMappingURL=transition-engine.d.ts.map