@devtrack-solution/codesdd 1.2.2

package/dist/core/sdd/diagnose.js

@@ -0,0 +1,1312 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { loadProjectSddConfig, loadStateSnapshot, resolveSddPaths, } from './state.js';
+import { StructuralDiagnosticReportSchema, StructuralFindingSchema, } from './structural-health.js';
+import { evaluateWorkspaceTraceability } from './domain/traceability.js';
+import { detectArchiveArchivedLifecycleCollisions } from './domain/post-active-validation.js';
+import { parseWorkspaceYamlDocument, workspaceSchemaForFile, } from './workspace-schemas.js';
+const WORKSPACE_FILE_ALLOWLIST = [
+    '1-spec.yaml',
+    '2-plan.yaml',
+    '3-tasks.yaml',
+    '4-changelog.yaml',
+    '5-quality.yaml',
+];
+const WORKSPACE_FILE_ALLOWLIST_SET = new Set(WORKSPACE_FILE_ALLOWLIST);
+const WORKSPACE_SCHEMA_FILE_SET = new Set(WORKSPACE_FILE_ALLOWLIST);
+const FEATURE_WORKSPACE_PATTERN = /^FEAT-\d{4}$/;
+export class SddDiagnosticOptionsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SddDiagnosticOptionsError';
+    }
+}
+function projectRelative(projectRoot, targetPath) {
+    const relative = path.relative(projectRoot, targetPath);
+    return relative.length > 0 ? relative : '.';
+}
+function isInsidePath(rootPath, candidatePath) {
+    const relative = path.relative(rootPath, candidatePath);
+    return relative === '' || (!!relative && !relative.startsWith('..') && !path.isAbsolute(relative));
+}
+async function pathExists(targetPath) {
+    try {
+        await fs.access(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function safeRealpath(targetPath) {
+    try {
+        return await fs.realpath(targetPath);
+    }
+    catch {
+        return path.resolve(targetPath);
+    }
+}
+function addFinding(findings, input) {
+    findings.push(StructuralFindingSchema.parse({
+        evidence: {},
+        ...input,
+        sanitizer: {
+            actions: [],
+            ...input.sanitizer,
+        },
+    }));
+}
+function duplicateIdFindings(findings, items, scope, filePath) {
+    const seen = new Set();
+    const duplicates = new Set();
+    for (const item of items) {
+        if (seen.has(item.id))
+            duplicates.add(item.id);
+        seen.add(item.id);
+    }
+    for (const id of duplicates) {
+        addFinding(findings, {
+            finding_id: `SH-DUPLICATE-ID-${id}`,
+            rule_id: 'SH-RULE-DUPLICATE-ID',
+            category: 'integrity',
+            severity: 'blocker',
+            summary: `Duplicate SDD identifier detected: ${id}.`,
+            location: filePath,
+            evidence: { id, scope },
+            sanitizer: {
+                disposition: 'manual',
+                reason: 'Duplicate IDs may represent conflicting planning history and cannot be safely merged.',
+                actions: ['inspect duplicate records', 'preserve one canonical record', 'record migration rationale'],
+            },
+        });
+    }
+}
+function zodIssuePath(pathSegments) {
+    return pathSegments.length > 0 ? pathSegments.join('.') : '<root>';
+}
+function normalizeFindingToken(input) {
+    return input.toUpperCase().replace(/[^A-Z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+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))
+        .map((entry) => ({
+        featureId: entry.name,
+        lifecycleRoot,
+        dirPath: path.join(rootDir, entry.name),
+    }));
+}
+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) {
+    const workspaces = [
+        ...(await listFeatureWorkspaceDirs(paths.plannedDir, 'planned')),
+        ...(await listFeatureWorkspaceDirs(paths.activeDir, 'active')),
+    ];
+    for (const workspace of workspaces) {
+        const entries = await fs.readdir(workspace.dirPath, { withFileTypes: true }).catch(() => []);
+        const legacyMarkdown = await hasLegacyMarkdown(workspace.dirPath);
+        for (const entry of entries) {
+            if (!entry.isFile() || !WORKSPACE_SCHEMA_FILE_SET.has(entry.name))
+                continue;
+            const schema = workspaceSchemaForFile(entry.name);
+            if (!schema)
+                continue;
+            const filePath = path.join(workspace.dirPath, entry.name);
+            const relativePath = projectRelative(paths.projectRoot, filePath);
+            let parsed;
+            try {
+                parsed = parseYaml(await fs.readFile(filePath, 'utf-8'));
+            }
+            catch (error) {
+                addFinding(findings, {
+                    finding_id: `SH-WORKSPACE-SCHEMA-INVALID-${workspace.featureId}-${normalizeFindingToken(entry.name)}`,
+                    rule_id: 'SH-RULE-WORKSPACE-SCHEMA-INVALID',
+                    category: 'integrity',
+                    severity: 'error',
+                    summary: `${workspace.featureId} ${entry.name} is not valid YAML.`,
+                    location: relativePath,
+                    evidence: {
+                        id: workspace.featureId,
+                        lifecycle_root: workspace.lifecycleRoot,
+                        file: entry.name,
+                        parse_error: error.message,
+                        has_legacy_markdown: legacyMarkdown,
+                    },
+                    sanitizer: {
+                        disposition: 'manual',
+                        reason: legacyMarkdown
+                            ? '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}`]
+                            : [`edit ${relativePath} to match ${entry.name} schema`],
+                    },
+                });
+                continue;
+            }
+            const result = schema.safeParse(parsed);
+            if (result.success)
+                continue;
+            addFinding(findings, {
+                finding_id: `SH-WORKSPACE-SCHEMA-INVALID-${workspace.featureId}-${normalizeFindingToken(entry.name)}`,
+                rule_id: 'SH-RULE-WORKSPACE-SCHEMA-INVALID',
+                category: 'integrity',
+                severity: 'error',
+                summary: `${workspace.featureId} ${entry.name} does not match the workspace schema.`,
+                location: relativePath,
+                evidence: {
+                    id: workspace.featureId,
+                    lifecycle_root: workspace.lifecycleRoot,
+                    file: entry.name,
+                    invalid_fields: result.error.issues.map((issue) => ({
+                        path: zodIssuePath(issue.path),
+                        message: issue.message,
+                    })),
+                    has_legacy_markdown: legacyMarkdown,
+                },
+                sanitizer: {
+                    disposition: 'manual',
+                    reason: legacyMarkdown
+                        ? '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`],
+                },
+            });
+        }
+    }
+}
+async function collectWorkspaceAllowlistFindings(findings, paths) {
+    const workspaces = [
+        ...(await listFeatureWorkspaceDirs(paths.plannedDir, 'planned')),
+        ...(await listFeatureWorkspaceDirs(paths.activeDir, 'active')),
+        ...(await listFeatureWorkspaceDirs(paths.archivedDir, 'archived')),
+    ];
+    for (const workspace of workspaces) {
+        const entries = await fs.readdir(workspace.dirPath, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries) {
+            if (!entry.isFile() || WORKSPACE_FILE_ALLOWLIST_SET.has(entry.name))
+                continue;
+            const filePath = path.join(workspace.dirPath, entry.name);
+            const relativePath = projectRelative(paths.projectRoot, filePath);
+            addFinding(findings, {
+                finding_id: `SH-WORKSPACE-FILE-NOTALLOWLISTED-${workspace.featureId}-${normalizeFindingToken(entry.name)}`,
+                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}.`,
+                location: relativePath,
+                evidence: {
+                    id: workspace.featureId,
+                    lifecycle_root: workspace.lifecycleRoot,
+                    file: entry.name,
+                    allowed_files: WORKSPACE_FILE_ALLOWLIST,
+                    legacy_markdown: entry.name.endsWith('.md'),
+                },
+                sanitizer: {
+                    disposition: 'manual',
+                    reason: entry.name.endsWith('.md')
+                        ? 'Legacy markdown workspace files should be migrated or moved out of the lifecycle workspace.'
+                        : 'Non-allowlisted files may contain user data and require confirmation before relocation.',
+                    actions: [
+                        entry.name.endsWith('.md')
+                            ? `opensdd sdd migrate-workspace --feat ${workspace.featureId}`
+                            : 'move the file to .sdd/backup after review',
+                        'remove the file only after confirming it is obsolete',
+                    ],
+                },
+            });
+        }
+    }
+}
+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' },
+        { root: 'active', dir: paths.activeDir, expectedStatus: 'IN_PROGRESS' },
+        { root: 'archived', dir: paths.archivedDir, expectedStatus: 'DONE' },
+    ];
+    for (const check of checks) {
+        const workspaces = await listFeatureWorkspaceDirs(check.dir, check.root);
+        for (const workspace of workspaces) {
+            const item = byId.get(workspace.featureId);
+            if (!item || item.status === check.expectedStatus)
+                continue;
+            addFinding(findings, {
+                finding_id: `SH-LIFECYCLE-VIOLATION-${workspace.featureId}-${check.root.toUpperCase()}`,
+                rule_id: 'SH-RULE-LIFECYCLE-VIOLATION',
+                category: 'lifecycle',
+                severity: 'error',
+                summary: `${workspace.featureId} is in ${check.root}/ but backlog status is ${item.status}; expected ${check.expectedStatus}.`,
+                location: projectRelative(paths.projectRoot, workspace.dirPath),
+                evidence: {
+                    id: workspace.featureId,
+                    lifecycle_root: check.root,
+                    actual_status: item.status,
+                    expected_status: check.expectedStatus,
+                    backlog_path: projectRelative(paths.projectRoot, paths.stateFiles.backlog),
+                },
+                sanitizer: {
+                    disposition: 'manual',
+                    reason: 'Backlog status should be corrected to match the real lifecycle directory after review.',
+                    actions: [`set ${workspace.featureId}.status to ${check.expectedStatus} in backlog.yaml`],
+                },
+            });
+        }
+    }
+}
+function qualityEvidenceReferencesCoverage(evidenceLog, targets) {
+    if (evidenceLog.length === 0)
+        return false;
+    const evidenceText = evidenceLog
+        .map((entry) => `${entry.kind} ${entry.result} ${entry.artifact ?? ''}`)
+        .join('\n')
+        .toLowerCase();
+    return (evidenceText.includes('coverage') ||
+        evidenceText.includes(`${targets.unit}`) ||
+        evidenceText.includes(`${targets.integration}`));
+}
+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) {
+        const item = byId.get(workspace.featureId);
+        if (!item || item.status !== 'IN_PROGRESS')
+            continue;
+        if (item.current_stage !== 'execucao' && item.current_stage !== 'consolidacao')
+            continue;
+        const qualityPath = path.join(workspace.dirPath, '5-quality.yaml');
+        const relativePath = projectRelative(paths.projectRoot, qualityPath);
+        if (!(await pathExists(qualityPath))) {
+            addFinding(findings, {
+                finding_id: `SH-QUALITY-EVIDENCE-INCOMPLETE-${workspace.featureId}`,
+                rule_id: 'SH-RULE-QUALITY-EVIDENCE-INCOMPLETE',
+                category: 'integrity',
+                severity: 'warning',
+                summary: `${workspace.featureId} is in ${item.current_stage} without 5-quality.yaml evidence.`,
+                location: relativePath,
+                evidence: {
+                    id: workspace.featureId,
+                    current_stage: item.current_stage,
+                    missing_quality_file: true,
+                },
+                sanitizer: {
+                    disposition: 'manual',
+                    reason: 'Quality evidence is feature-specific and must be supplied by the implementation round.',
+                    actions: [`create ${relativePath} and fill evidence_log[]`],
+                },
+            });
+            continue;
+        }
+        const qualityContent = await fs.readFile(qualityPath, 'utf-8').catch(() => '');
+        let qualityDocument;
+        try {
+            qualityDocument = parseWorkspaceYamlDocument('5-quality.yaml', qualityContent);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            addFinding(findings, {
+                finding_id: `SH-QUALITY-EVIDENCE-INCOMPLETE-${workspace.featureId}`,
+                rule_id: 'SH-RULE-QUALITY-EVIDENCE-INCOMPLETE',
+                category: 'integrity',
+                severity: 'warning',
+                summary: `${workspace.featureId} quality evidence cannot be validated because 5-quality.yaml is invalid.`,
+                location: relativePath,
+                evidence: {
+                    id: workspace.featureId,
+                    current_stage: item.current_stage,
+                    parser_gate_error: message,
+                },
+                sanitizer: {
+                    disposition: 'manual',
+                    reason: 'Fix the quality YAML so coverage evidence can be validated before finalize.',
+                    actions: [`edit ${relativePath} and rerun opensdd sdd diagnose`],
+                },
+            });
+            continue;
+        }
+        const coverageReferenced = qualityEvidenceReferencesCoverage(qualityDocument.evidence_log, qualityDocument.coverage_targets);
+        if (qualityDocument.evidence_log.length > 0 && coverageReferenced)
+            continue;
+        addFinding(findings, {
+            finding_id: `SH-QUALITY-EVIDENCE-INCOMPLETE-${workspace.featureId}`,
+            rule_id: 'SH-RULE-QUALITY-EVIDENCE-INCOMPLETE',
+            category: 'integrity',
+            severity: 'warning',
+            summary: `${workspace.featureId} quality evidence is incomplete for execution/finalization.`,
+            location: relativePath,
+            evidence: {
+                id: workspace.featureId,
+                current_stage: item.current_stage,
+                evidence_count: qualityDocument.evidence_log.length,
+                coverage_targets: qualityDocument.coverage_targets,
+                coverage_referenced: coverageReferenced,
+            },
+            sanitizer: {
+                disposition: 'manual',
+                reason: 'Coverage evidence must be recorded before finalize or covered by a formal exception.',
+                actions: [`fill evidence_log[] in ${relativePath} with coverage validation results`],
+            },
+        });
+    }
+}
+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) {
+        const item = byId.get(workspace.featureId);
+        if (!item || item.status !== 'IN_PROGRESS')
+            continue;
+        if (item.current_stage !== 'execucao' && item.current_stage !== 'consolidacao')
+            continue;
+        const specPath = path.join(workspace.dirPath, '1-spec.yaml');
+        const changelogPath = path.join(workspace.dirPath, '4-changelog.yaml');
+        const qualityPath = path.join(workspace.dirPath, '5-quality.yaml');
+        const relativePath = projectRelative(paths.projectRoot, qualityPath);
+        const [specContent, changelogContent, qualityContent] = await Promise.all([
+            fs.readFile(specPath, 'utf-8').catch(() => ''),
+            fs.readFile(changelogPath, 'utf-8').catch(() => ''),
+            fs.readFile(qualityPath, 'utf-8').catch(() => ''),
+        ]);
+        if (!specContent.trim() || !changelogContent.trim() || !qualityContent.trim()) {
+            addFinding(findings, {
+                finding_id: `SH-TRACEABILITY-INCOMPLETE-${workspace.featureId}`,
+                rule_id: 'SH-RULE-TRACEABILITY-INCOMPLETE',
+                category: 'integrity',
+                severity: 'warning',
+                summary: `${workspace.featureId} is missing traceability inputs required for finalize.`,
+                location: relativePath,
+                evidence: {
+                    id: workspace.featureId,
+                    spec_present: Boolean(specContent.trim()),
+                    changelog_present: Boolean(changelogContent.trim()),
+                    quality_present: Boolean(qualityContent.trim()),
+                },
+                sanitizer: {
+                    disposition: 'manual',
+                    reason: 'Requirement-to-code-to-test traceability must be curated per feature before finalize.',
+                    actions: [`complete traceability in ${relativePath}`],
+                },
+            });
+            continue;
+        }
+        let spec;
+        let changelog;
+        let quality;
+        try {
+            spec = parseWorkspaceYamlDocument('1-spec.yaml', specContent);
+            changelog = parseWorkspaceYamlDocument('4-changelog.yaml', changelogContent);
+            quality = parseWorkspaceYamlDocument('5-quality.yaml', qualityContent);
+        }
+        catch (error) {
+            addFinding(findings, {
+                finding_id: `SH-TRACEABILITY-INCOMPLETE-${workspace.featureId}`,
+                rule_id: 'SH-RULE-TRACEABILITY-INCOMPLETE',
+                category: 'integrity',
+                severity: 'warning',
+                summary: `${workspace.featureId} traceability cannot be validated because workspace YAML is invalid.`,
+                location: relativePath,
+                evidence: {
+                    id: workspace.featureId,
+                    parser_gate_error: error instanceof Error ? error.message : String(error),
+                },
+                sanitizer: {
+                    disposition: 'manual',
+                    reason: 'Fix the workspace YAML before validating traceability closure.',
+                    actions: [`edit ${relativePath} and rerun opensdd sdd diagnose`],
+                },
+            });
+            continue;
+        }
+        const traceability = evaluateWorkspaceTraceability(paths.projectRoot, spec, changelog, quality);
+        if (traceability.ok)
+            continue;
+        addFinding(findings, {
+            finding_id: `SH-TRACEABILITY-INCOMPLETE-${workspace.featureId}`,
+            rule_id: 'SH-RULE-TRACEABILITY-INCOMPLETE',
+            category: 'integrity',
+            severity: 'warning',
+            summary: `${workspace.featureId} traceability closure is incomplete for execution/finalization.`,
+            location: relativePath,
+            evidence: {
+                id: workspace.featureId,
+                reasons: traceability.reasons,
+                mapped_requirements: quality.traceability.requirements.length,
+            },
+            sanitizer: {
+                disposition: 'manual',
+                reason: 'Finalize requires requirement-to-code-to-test links, semantic coverage status, and changelog linkage.',
+                actions: [`update traceability.requirements[] in ${relativePath}`],
+            },
+        });
+    }
+}
+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) {
+    const privacyItems = snapshot.backlog.items.filter((item) => item.status !== 'DONE' && item.status !== 'ARCHIVED' && isPrivacyComplianceBacklogItem(item));
+    if (privacyItems.length === 0)
+        return;
+    if (snapshot.sourceIndex.jurisdiction_profiles.length === 0) {
+        addFinding(findings, {
+            finding_id: 'SH-PRIVACY-JURISDICTION-PROFILES-MISSING',
+            rule_id: 'SH-RULE-PRIVACY-COMPLIANCE-BASELINE',
+            category: 'integrity',
+            severity: 'warning',
+            summary: 'Privacy compliance baseline missing jurisdiction profiles for active EPIC-0020/EPIC-0021 features.',
+            location: projectRelative(paths.projectRoot, paths.stateFiles.sourceIndex),
+            evidence: { required: 'source-index.jurisdiction_profiles[]', found: 0 },
+            sanitizer: {
+                disposition: 'manual',
+                reason: 'Jurisdiction profiles require domain modeling and traceable source references.',
+                actions: ['populate source-index.jurisdiction_profiles with canonical IDs and source refs'],
+            },
+        });
+    }
+    if (snapshot.sourceIndex.control_catalog.length === 0) {
+        addFinding(findings, {
+            finding_id: 'SH-PRIVACY-CONTROL-CATALOG-MISSING',
+            rule_id: 'SH-RULE-PRIVACY-COMPLIANCE-BASELINE',
+            category: 'integrity',
+            severity: 'warning',
+            summary: 'Privacy compliance baseline missing control catalog for active EPIC-0020/EPIC-0021 features.',
+            location: projectRelative(paths.projectRoot, paths.stateFiles.sourceIndex),
+            evidence: { required: 'source-index.control_catalog[]', found: 0 },
+            sanitizer: {
+                disposition: 'manual',
+                reason: 'Control catalog entries must be mapped to jurisdictions and evidence strategies.',
+                actions: ['populate source-index.control_catalog with category, severity, and source refs'],
+            },
+        });
+    }
+    if (snapshot.sourceIndex.version_events.length === 0) {
+        addFinding(findings, {
+            finding_id: 'SH-PRIVACY-SOURCE-VERSION-EVENTS-MISSING',
+            rule_id: 'SH-RULE-PRIVACY-COMPLIANCE-BASELINE',
+            category: 'integrity',
+            severity: 'warning',
+            summary: 'Privacy compliance baseline missing source version events for active EPIC-0020/EPIC-0021 features.',
+            location: projectRelative(paths.projectRoot, paths.stateFiles.sourceIndex),
+            evidence: { required: 'source-index.version_events[]', found: 0 },
+            sanitizer: {
+                disposition: 'manual',
+                reason: 'Versioned regulatory catalog requires auditable source revision events.',
+                actions: ['populate source-index.version_events via source ingest/update lifecycle'],
+            },
+        });
+    }
+    const activeRefs = new Set();
+    for (const item of privacyItems) {
+        activeRefs.add(item.id);
+        if (item.origin_ref)
+            activeRefs.add(item.origin_ref);
+    }
+    for (const source of snapshot.sourceIndex.sources) {
+        const relevant = source.used_by.some((ref) => activeRefs.has(ref));
+        if (!relevant)
+            continue;
+        const hasAuthority = source.authority !== 'unknown';
+        const hasClassification = source.source_classification !== 'other';
+        const hasVerificationDate = Boolean((source.last_verified_at || '').trim());
+        const hasVersion = typeof source.source_version === 'number' && source.source_version > 0;
+        const hasFingerprint = Boolean((source.source_fingerprint || '').trim());
+        if (hasAuthority && hasClassification && hasVerificationDate && hasVersion && hasFingerprint)
+            continue;
+        addFinding(findings, {
+            finding_id: `SH-PRIVACY-SOURCE-METADATA-${normalizeFindingToken(source.id)}`,
+            rule_id: 'SH-RULE-PRIVACY-SOURCE-METADATA',
+            category: 'integrity',
+            severity: 'warning',
+            summary: `Source ${source.id} linked to privacy features is missing provenance/version metadata.`,
+            location: projectRelative(paths.projectRoot, paths.stateFiles.sourceIndex),
+            evidence: {
+                source_id: source.id,
+                authority: source.authority,
+                source_classification: source.source_classification,
+                last_verified_at: source.last_verified_at || '',
+                source_version: source.source_version ?? null,
+                source_fingerprint: source.source_fingerprint || '',
+            },
+            sanitizer: {
+                disposition: 'manual',
+                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',
+                ],
+            },
+        });
+    }
+    for (const item of privacyItems.filter((entry) => entry.status === 'IN_PROGRESS')) {
+        const specPath = path.join(paths.activeDir, item.id, '1-spec.yaml');
+        const planPath = path.join(paths.activeDir, item.id, '2-plan.yaml');
+        const qualityPath = path.join(paths.activeDir, item.id, '5-quality.yaml');
+        if (!(await pathExists(specPath)) || !(await pathExists(planPath)) || !(await pathExists(qualityPath))) {
+            addFinding(findings, {
+                finding_id: `SH-PRIVACY-WORKSPACE-FILES-${item.id}`,
+                rule_id: 'SH-RULE-PRIVACY-WORKSPACE-CHECKLIST',
+                category: 'integrity',
+                severity: 'warning',
+                summary: `${item.id} is missing mandatory privacy workspace files (1-spec.yaml, 2-plan.yaml, 5-quality.yaml).`,
+                location: projectRelative(paths.projectRoot, path.join(paths.activeDir, item.id)),
+                evidence: { feature_id: item.id },
+                sanitizer: {
+                    disposition: 'manual',
+                    reason: 'Privacy lifecycle gates require complete workspace artifacts.',
+                    actions: [`restore missing YAML files under .sdd/active/${item.id}`],
+                },
+            });
+            continue;
+        }
+        try {
+            const spec = parseWorkspaceYamlDocument('1-spec.yaml', await fs.readFile(specPath, 'utf-8'));
+            const plan = parseWorkspaceYamlDocument('2-plan.yaml', await fs.readFile(planPath, 'utf-8'));
+            const quality = parseWorkspaceYamlDocument('5-quality.yaml', await fs.readFile(qualityPath, 'utf-8'));
+            const missingBlocks = [];
+            if ((spec.compliance_context?.source_refs || []).length === 0) {
+                missingBlocks.push('spec.compliance_context.source_refs');
+            }
+            if ((spec.compliance_context?.jurisdictions || []).length === 0) {
+                missingBlocks.push('spec.compliance_context.jurisdictions');
+            }
+            if ((plan.privacy_controls?.source_registry_refs || []).length === 0) {
+                missingBlocks.push('plan.privacy_controls.source_registry_refs');
+            }
+            if ((plan.privacy_controls?.jurisdiction_profiles || []).length === 0) {
+                missingBlocks.push('plan.privacy_controls.jurisdiction_profiles');
+            }
+            if ((plan.privacy_controls?.control_ids || []).length === 0) {
+                missingBlocks.push('plan.privacy_controls.control_ids');
+            }
+            if ((plan.skill_conformance?.selected_skills || []).length === 0) {
+                missingBlocks.push('plan.skill_conformance.selected_skills');
+            }
+            if (!((plan.skill_conformance?.architecture_tree_ascii || '').trim()) && item.execution_kind !== 'documentation') {
+                missingBlocks.push('plan.skill_conformance.architecture_tree_ascii');
+            }
+            if ((plan.skill_conformance?.detected_conflicts || []).length > 0 &&
+                !((plan.skill_conformance?.resolution_adr_ref || '').trim())) {
+                missingBlocks.push('plan.skill_conformance.resolution_adr_ref');
+            }
+            if (!quality.security_integrity) {
+                missingBlocks.push('quality.security_integrity');
+            }
+            if (missingBlocks.length > 0) {
+                addFinding(findings, {
+                    finding_id: `SH-PRIVACY-WORKSPACE-CHECKLIST-${item.id}`,
+                    rule_id: 'SH-RULE-PRIVACY-WORKSPACE-CHECKLIST',
+                    category: 'integrity',
+                    severity: 'warning',
+                    summary: `${item.id} has incomplete privacy lifecycle checklist fields.`,
+                    location: projectRelative(paths.projectRoot, path.join(paths.activeDir, item.id)),
+                    evidence: { feature_id: item.id, missing_blocks: missingBlocks },
+                    sanitizer: {
+                        disposition: 'manual',
+                        reason: 'Checklist completion requires feature-specific privacy data and evidence.',
+                        actions: ['fill missing privacy blocks in 1-spec/2-plan/5-quality'],
+                    },
+                });
+            }
+        }
+        catch (error) {
+            addFinding(findings, {
+                finding_id: `SH-PRIVACY-WORKSPACE-PARSE-${item.id}`,
+                rule_id: 'SH-RULE-PRIVACY-WORKSPACE-CHECKLIST',
+                category: 'integrity',
+                severity: 'warning',
+                summary: `${item.id} privacy checklist could not be evaluated due to invalid workspace YAML.`,
+                location: projectRelative(paths.projectRoot, path.join(paths.activeDir, item.id)),
+                evidence: { feature_id: item.id, error: error.message },
+                sanitizer: {
+                    disposition: 'manual',
+                    reason: 'Workspace YAML must be valid before privacy checklist gates can be applied.',
+                    actions: ['fix workspace YAML schema errors and rerun diagnose'],
+                },
+            });
+        }
+    }
+}
+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));
+    if (snapshot.frontendGaps) {
+        duplicateIdFindings(findings, snapshot.frontendGaps.items, 'frontend-gaps.items', projectRelative(paths.projectRoot, paths.stateFiles.frontendGaps));
+    }
+}
+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',
+        category: 'references',
+        severity: 'error',
+        summary: `${owner} references missing ${relation}: ${ref}.`,
+        location,
+        evidence: { owner, relation, ref },
+        sanitizer: {
+            disposition: 'manual',
+            reason: 'Broken references require semantic review before removal or replacement.',
+            actions: ['verify referenced entity', 'update relation or create missing entity'],
+        },
+    });
+}
+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));
+    const frontendGapIds = new Set(snapshot.frontendGaps?.items.map((item) => item.id) ?? []);
+    const ecosystemIds = new Set([...discoveryIds, ...backlogIds, ...techDebtIds, ...frontendGapIds]);
+    for (const item of snapshot.backlog.items) {
+        const location = projectRelative(paths.projectRoot, paths.stateFiles.backlog);
+        if ((item.origin_type === 'epic' || item.origin_type === 'radar') && item.origin_ref && !discoveryIds.has(item.origin_ref)) {
+            addBrokenReference(findings, item.origin_ref, item.id, 'origin_ref', location);
+        }
+        if (item.origin_type === 'frontend_gap' && item.origin_ref && !frontendGapIds.has(item.origin_ref)) {
+            addBrokenReference(findings, item.origin_ref, item.id, 'origin_ref', location);
+        }
+        if (item.origin_type === 'tech_debt' && item.origin_ref && !techDebtIds.has(item.origin_ref)) {
+            addBrokenReference(findings, item.origin_ref, item.id, 'origin_ref', location);
+        }
+        for (const dep of item.blocked_by) {
+            if (!backlogIds.has(dep)) {
+                addBrokenReference(findings, dep, item.id, 'blocked_by', location);
+            }
+        }
+        for (const acceptanceRef of item.acceptance_refs) {
+            if (!ecosystemIds.has(acceptanceRef)) {
+                addBrokenReference(findings, acceptanceRef, item.id, 'acceptance_refs', location);
+            }
+        }
+    }
+    for (const record of snapshot.discoveryIndex.records) {
+        const location = projectRelative(paths.projectRoot, paths.stateFiles.discoveryIndex);
+        for (const relatedId of record.related_ids) {
+            if (!ecosystemIds.has(relatedId)) {
+                addBrokenReference(findings, relatedId, record.id, 'related_ids', location);
+            }
+        }
+    }
+    for (const gap of snapshot.frontendGaps?.items ?? []) {
+        if (gap.resolved_by_feature && !backlogIds.has(gap.resolved_by_feature)) {
+            addBrokenReference(findings, gap.resolved_by_feature, gap.id, 'resolved_by_feature', projectRelative(paths.projectRoot, paths.stateFiles.frontendGaps));
+        }
+    }
+}
+async function collectDirectoryFindings(findings, config, paths) {
+    const requiredDirectories = [
+        { semantic: 'memory', dir: paths.memoryRoot, severity: 'blocker' },
+        { semantic: 'state', dir: paths.stateDir, severity: 'blocker' },
+        { semantic: 'discovery', dir: paths.discoveryDir, severity: 'error' },
+        { semantic: 'planning', dir: paths.pendenciasDir, severity: 'error' },
+        { semantic: 'planned', dir: paths.plannedDir, severity: 'error' },
+        { semantic: 'active', dir: paths.activeDir, severity: 'error' },
+        { semantic: 'archived', dir: paths.archivedDir, severity: 'error' },
+        { semantic: 'core', dir: paths.coreDir, severity: 'error' },
+    ];
+    for (const item of requiredDirectories) {
+        if (!(await pathExists(item.dir))) {
+            addFinding(findings, {
+                finding_id: `SH-MISSING-DIR-${item.semantic.toUpperCase()}`,
+                rule_id: 'SH-RULE-MISSING-DIRECTORY',
+                category: 'lifecycle',
+                severity: item.severity,
+                summary: `Required SDD directory is missing: ${item.semantic}.`,
+                location: projectRelative(paths.projectRoot, item.dir),
+                evidence: { semantic: item.semantic, expected_path: projectRelative(paths.projectRoot, item.dir) },
+                sanitizer: {
+                    disposition: 'safe',
+                    reason: 'Missing canonical directories can be recreated without deleting user data.',
+                    actions: [`mkdir ${projectRelative(paths.projectRoot, item.dir)}`],
+                },
+            });
+        }
+    }
+    if (config.layout !== 'en-US') {
+        addFinding(findings, {
+            finding_id: `SH-LANGUAGE-DEPENDENT-LAYOUT-${config.layout.toUpperCase().replace(/[^A-Z0-9]/g, '-')}`,
+            rule_id: 'SH-RULE-LANGUAGE-INVARIANT-LAYOUT',
+            category: 'naming',
+            severity: 'error',
+            summary: `SDD layout is language-dependent: ${config.layout}.`,
+            location: projectRelative(paths.projectRoot, paths.memoryRoot),
+            evidence: { layout: config.layout, language: config.language, folders: config.folders },
+            sanitizer: {
+                disposition: 'manual',
+                reason: 'Migrating localized structural folders requires preserving existing state and generated views.',
+                actions: ['plan migration to en-US structural tokens', 'preserve content before relocating folders'],
+            },
+        });
+    }
+    const translatedCandidates = ['pendencias', 'planejamento', 'execucao', 'arquivados', 'descoberta'];
+    for (const name of translatedCandidates) {
+        const candidate = path.join(paths.memoryRoot, name);
+        if (candidate === paths.pendenciasDir || candidate === paths.activeDir || candidate === paths.archivedDir || candidate === paths.discoveryDir) {
+            continue;
+        }
+        if (await pathExists(candidate)) {
+            addFinding(findings, {
+                finding_id: `SH-TRANSLATED-DIR-${name.toUpperCase().replace(/[^A-Z0-9]/g, '-')}`,
+                rule_id: 'SH-RULE-TRANSLATED-STRUCTURAL-DIRECTORY',
+                category: 'naming',
+                severity: 'error',
+                summary: `Translated or legacy structural directory found outside the active layout: ${name}.`,
+                location: projectRelative(paths.projectRoot, candidate),
+                evidence: { directory: name, active_layout: config.layout },
+                sanitizer: {
+                    disposition: 'manual',
+                    reason: 'Directory may contain historical planning data and must be reviewed before relocation.',
+                    actions: ['inspect directory contents', 'move valid artifacts to canonical folders', 'record migration'],
+                },
+            });
+        }
+    }
+}
+async function collectStateFileFindings(findings, config, paths) {
+    const requiredStateFiles = [
+        paths.stateFiles.discoveryIndex,
+        paths.stateFiles.backlog,
+        paths.stateFiles.techDebt,
+        paths.stateFiles.finalizeQueue,
+        paths.stateFiles.skillCatalog,
+        paths.stateFiles.unblockEvents,
+        paths.stateFiles.transitionLog,
+        paths.stateFiles.architecture,
+        paths.stateFiles.serviceCatalog,
+        paths.stateFiles.techStack,
+        paths.stateFiles.integrationContracts,
+        paths.stateFiles.repoMap,
+        paths.stateFiles.sourceIndex,
+        paths.stateFiles.skillRouting,
+    ];
+    if (config.frontend.enabled) {
+        requiredStateFiles.push(paths.stateFiles.frontendGaps);
+        requiredStateFiles.push(paths.stateFiles.frontendMap);
+        requiredStateFiles.push(paths.stateFiles.frontendDecisions);
+    }
+    for (const filePath of requiredStateFiles) {
+        if (!(await pathExists(filePath))) {
+            addFinding(findings, {
+                finding_id: `SH-MISSING-STATE-${path.basename(filePath).toUpperCase().replace(/[^A-Z0-9]/g, '-')}`,
+                rule_id: 'SH-RULE-MISSING-STATE-FILE',
+                category: 'metadata',
+                severity: 'error',
+                summary: `Required SDD state file is missing: ${path.basename(filePath)}.`,
+                location: projectRelative(paths.projectRoot, filePath),
+                evidence: { state_file: projectRelative(paths.projectRoot, filePath) },
+                sanitizer: {
+                    disposition: 'manual',
+                    reason: 'State files need schema-aware defaults and may require project-specific reconstruction.',
+                    actions: ['inspect backup or generated views', 'restore schema-valid state file'],
+                },
+            });
+        }
+    }
+}
+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(() => []);
+    const archivedEntries = await fs.readdir(paths.archivedDir).catch(() => []);
+    const plannedSet = new Set(plannedEntries);
+    const activeSet = new Set(activeEntries);
+    const archivedSet = new Set(archivedEntries);
+    const archiveCollisions = await detectArchiveArchivedLifecycleCollisions(paths);
+    for (const collision of archiveCollisions) {
+        addFinding(findings, {
+            finding_id: `SH-LIFECYCLE-ARCHIVE-CANONICALIZATION-${collision.feature_id}`,
+            rule_id: 'SH-RULE-LIFECYCLE-ARCHIVE-CANONICALIZATION',
+            category: 'lifecycle',
+            severity: 'error',
+            summary: collision.message,
+            location: collision.legacy_archive_path,
+            evidence: {
+                id: collision.feature_id,
+                legacy_archive_path: collision.legacy_archive_path,
+                canonical_archived_path: collision.canonical_archived_path,
+                expected_root: 'archived',
+            },
+            sanitizer: {
+                disposition: 'manual',
+                reason: 'Archive versus archived lifecycle duplicates require operator review before completed workspaces are consolidated.',
+                actions: ['compare archive and archived workspaces', 'move or merge evidence into .sdd/archived', 'remove the non-canonical archive copy after review'],
+            },
+        });
+    }
+    for (const item of byId.values()) {
+        const plannedPath = path.join(paths.plannedDir, item.id);
+        const activePath = path.join(paths.activeDir, item.id);
+        const archivedPath = path.join(paths.archivedDir, item.id);
+        const isPlanned = item.status === 'READY' || item.status === 'BLOCKED' || item.status === 'SYNC_REQUIRED';
+        if (isPlanned && !plannedSet.has(item.id)) {
+            addFinding(findings, {
+                finding_id: `SH-LIFECYCLE-MISSING-PLANNED-${item.id}`,
+                rule_id: 'SH-RULE-LIFECYCLE-PLACEMENT',
+                category: 'lifecycle',
+                severity: 'error',
+                summary: `${item.id} is ${item.status} but has no planned workspace.`,
+                location: projectRelative(paths.projectRoot, plannedPath),
+                evidence: { id: item.id, status: item.status, expected_root: 'planned' },
+                sanitizer: {
+                    disposition: 'manual',
+                    reason: 'Planned workspace reconstruction can be safely regenerated.',
+                    actions: ['run sdd start to regenerate or manually recreate the folder'],
+                },
+            });
+        }
+        if (!isPlanned && plannedSet.has(item.id)) {
+            addFinding(findings, {
+                finding_id: `SH-LIFECYCLE-UNEXPECTED-PLANNED-${item.id}`,
+                rule_id: 'SH-RULE-LIFECYCLE-PLACEMENT',
+                category: 'lifecycle',
+                severity: 'error',
+                summary: `${item.id} is ${item.status} but still has a planned workspace.`,
+                location: projectRelative(paths.projectRoot, plannedPath),
+                evidence: { id: item.id, status: item.status, actual_root: 'planned' },
+                sanitizer: {
+                    disposition: 'manual',
+                    reason: 'Moving planned workspaces requires confirmation before archival or removal.',
+                    actions: ['inspect workspace contents', 'archive or remove only after confirmation'],
+                },
+            });
+        }
+        if (item.status === 'IN_PROGRESS' && plannedSet.has(item.id)) {
+            addFinding(findings, {
+                finding_id: `SH-LIFECYCLE-ACTIVE-PLANNED-COLLISION-${item.id}`,
+                rule_id: 'SH-RULE-LIFECYCLE-PLACEMENT',
+                category: 'lifecycle',
+                severity: 'error',
+                summary: `${item.id} is IN_PROGRESS and also has a planned workspace.`,
+                location: projectRelative(paths.projectRoot, plannedPath),
+                evidence: { id: item.id, status: item.status, actual_root: 'planned' },
+                sanitizer: {
+                    disposition: 'manual',
+                    reason: 'Planned workspace may conflict with active workspace.',
+                    actions: ['compare active and planned workspaces', 'remove redundant planned workspace'],
+                },
+            });
+        }
+        if (item.status === 'IN_PROGRESS' && !activeSet.has(item.id)) {
+            addFinding(findings, {
+                finding_id: `SH-LIFECYCLE-MISSING-ACTIVE-${item.id}`,
+                rule_id: 'SH-RULE-LIFECYCLE-PLACEMENT',
+                category: 'lifecycle',
+                severity: 'error',
+                summary: `${item.id} is IN_PROGRESS but has no active workspace.`,
+                location: projectRelative(paths.projectRoot, activePath),
+                evidence: { id: item.id, status: item.status, expected_root: 'active' },
+                sanitizer: {
+                    disposition: 'manual',
+                    reason: 'Active workspace reconstruction must preserve feature-specific spec, plan, tasks, and changelog.',
+                    actions: ['run or repair sdd start for the feature', 'restore active workspace files'],
+                },
+            });
+        }
+        if (item.status !== 'IN_PROGRESS' && activeSet.has(item.id)) {
+            addFinding(findings, {
+                finding_id: `SH-LIFECYCLE-UNEXPECTED-ACTIVE-${item.id}`,
+                rule_id: 'SH-RULE-LIFECYCLE-PLACEMENT',
+                category: 'lifecycle',
+                severity: item.status === 'DONE' || item.status === 'ARCHIVED' ? 'warning' : 'error',
+                summary: `${item.id} is ${item.status} but still has an active workspace.`,
+                location: projectRelative(paths.projectRoot, activePath),
+                evidence: { id: item.id, status: item.status, actual_root: 'active' },
+                sanitizer: {
+                    disposition: 'manual',
+                    reason: 'Moving active workspaces can hide unfinished work if done blindly.',
+                    actions: ['inspect workspace contents', 'archive or remove only after confirmation'],
+                },
+            });
+        }
+        if (item.status === 'IN_PROGRESS' && archivedSet.has(item.id)) {
+            addFinding(findings, {
+                finding_id: `SH-LIFECYCLE-ACTIVE-ARCHIVED-COLLISION-${item.id}`,
+                rule_id: 'SH-RULE-LIFECYCLE-PLACEMENT',
+                category: 'lifecycle',
+                severity: 'error',
+                summary: `${item.id} is IN_PROGRESS and also has an archived workspace.`,
+                location: projectRelative(paths.projectRoot, archivedPath),
+                evidence: { id: item.id, status: item.status, actual_root: 'archived' },
+                sanitizer: {
+                    disposition: 'manual',
+                    reason: 'Archived workspace may contain completed historical evidence.',
+                    actions: ['compare active and archived workspaces', 'preserve historical evidence before relocating'],
+                },
+            });
+        }
+    }
+    for (const entry of activeEntries) {
+        if (!/^FEAT-\d{3,}$/.test(entry))
+            continue;
+        if (!byId.has(entry)) {
+            addFinding(findings, {
+                finding_id: `SH-ORPHAN-ACTIVE-${entry}`,
+                rule_id: 'SH-RULE-ORPHAN-WORKSPACE',
+                category: 'integrity',
+                severity: 'error',
+                summary: `Active workspace has no matching backlog item: ${entry}.`,
+                location: projectRelative(paths.projectRoot, path.join(paths.activeDir, entry)),
+                evidence: { workspace: entry, root: 'active' },
+                sanitizer: {
+                    disposition: 'manual',
+                    reason: 'Orphan workspaces may contain user-authored execution evidence.',
+                    actions: ['inspect workspace', 'restore backlog entry or archive after review'],
+                },
+            });
+        }
+    }
+    for (const entry of plannedEntries) {
+        if (!/^FEAT-\d{3,}$/.test(entry))
+            continue;
+        if (!byId.has(entry)) {
+            addFinding(findings, {
+                finding_id: `SH-ORPHAN-PLANNED-${entry}`,
+                rule_id: 'SH-RULE-ORPHAN-WORKSPACE',
+                category: 'integrity',
+                severity: 'error',
+                summary: `Planned workspace has no matching backlog item: ${entry}.`,
+                location: projectRelative(paths.projectRoot, path.join(paths.plannedDir, entry)),
+                evidence: { workspace: entry, root: 'planned' },
+                sanitizer: {
+                    disposition: 'manual',
+                    reason: 'Orphan planned workspaces may contain spec details.',
+                    actions: ['inspect workspace', 'restore backlog entry or remove after review'],
+                },
+            });
+        }
+    }
+}
+async function newestMtime(filePaths) {
+    let newest = 0;
+    for (const filePath of filePaths) {
+        const stat = await fs.stat(filePath).catch(() => null);
+        if (stat)
+            newest = Math.max(newest, stat.mtimeMs);
+    }
+    return newest;
+}
+async function collectGeneratedViewFindings(findings, config, paths) {
+    const generatedViews = [
+        path.join(paths.pendenciasDir, 'backlog-features.md'),
+        path.join(paths.pendenciasDir, 'backlog-graph.md'),
+        path.join(paths.pendenciasDir, 'discovery.md'),
+        path.join(paths.pendenciasDir, 'progress.md'),
+        path.join(paths.pendenciasDir, 'compliance-health.md'),
+        path.join(paths.coreDir, 'index.md'),
+        path.join(paths.coreDir, 'arquitetura.md'),
+        path.join(paths.coreDir, 'servicos.md'),
+        path.join(paths.coreDir, 'spec-tecnologica.md'),
+        path.join(paths.coreDir, 'repo-map.md'),
+    ];
+    if (config.frontend.enabled) {
+        generatedViews.push(path.join(paths.pendenciasDir, 'frontend-auditoria.md'));
+        generatedViews.push(path.join(paths.coreDir, 'frontend-map.md'));
+        generatedViews.push(path.join(paths.coreDir, 'frontend-sitemap.md'));
+        generatedViews.push(path.join(paths.coreDir, 'frontend-decisions.md'));
+    }
+    const stateFiles = Object.values(paths.stateFiles);
+    const latestStateMtime = await newestMtime(stateFiles);
+    for (const viewPath of generatedViews) {
+        const exists = await pathExists(viewPath);
+        if (!exists) {
+            addFinding(findings, {
+                finding_id: `SH-MISSING-VIEW-${path.basename(viewPath).toUpperCase().replace(/[^A-Z0-9]/g, '-')}`,
+                rule_id: 'SH-RULE-GENERATED-VIEW',
+                category: 'render',
+                severity: 'warning',
+                summary: `Generated SDD view is missing: ${path.basename(viewPath)}.`,
+                location: projectRelative(paths.projectRoot, viewPath),
+                evidence: { view: projectRelative(paths.projectRoot, viewPath) },
+                sanitizer: {
+                    disposition: 'safe',
+                    reason: 'Generated views can be recreated from canonical state.',
+                    actions: ['run opensdd sdd check --render'],
+                },
+            });
+            continue;
+        }
+        const stat = await fs.stat(viewPath);
+        if (latestStateMtime > stat.mtimeMs + 1000) {
+            addFinding(findings, {
+                finding_id: `SH-STALE-VIEW-${path.basename(viewPath).toUpperCase().replace(/[^A-Z0-9]/g, '-')}`,
+                rule_id: 'SH-RULE-GENERATED-VIEW',
+                category: 'render',
+                severity: 'warning',
+                summary: `Generated SDD view may be stale: ${path.basename(viewPath)}.`,
+                location: projectRelative(paths.projectRoot, viewPath),
+                evidence: {
+                    view_mtime: new Date(stat.mtimeMs).toISOString(),
+                    latest_state_mtime: new Date(latestStateMtime).toISOString(),
+                },
+                sanitizer: {
+                    disposition: 'safe',
+                    reason: 'Stale generated views can be refreshed from canonical state.',
+                    actions: ['run opensdd sdd check --render'],
+                },
+            });
+        }
+    }
+}
+async function collectBoundaryFindings(findings, paths) {
+    if (!(await pathExists(paths.memoryRoot)))
+        return;
+    const memoryRootReal = await safeRealpath(paths.memoryRoot);
+    const stack = [paths.memoryRoot];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        const entries = await fs.readdir(current, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries) {
+            const candidate = path.join(current, entry.name);
+            if (entry.isSymbolicLink()) {
+                const realTarget = await safeRealpath(candidate);
+                if (!isInsidePath(memoryRootReal, realTarget)) {
+                    addFinding(findings, {
+                        finding_id: `SH-BOUNDARY-SYMLINK-${projectRelative(paths.projectRoot, candidate).toUpperCase().replace(/[^A-Z0-9]/g, '-')}`,
+                        rule_id: 'SH-RULE-ROOT-BOUNDARY',
+                        category: 'boundary',
+                        severity: 'blocker',
+                        summary: 'SDD-owned symlink resolves outside the SDD root.',
+                        location: projectRelative(paths.projectRoot, candidate),
+                        evidence: {
+                            symlink: projectRelative(paths.projectRoot, candidate),
+                            real_target: realTarget,
+                            sdd_root: projectRelative(paths.projectRoot, paths.memoryRoot),
+                        },
+                        sanitizer: {
+                            disposition: 'blocked',
+                            reason: 'External symlink targets can escape the SDD root and require manual containment review.',
+                            actions: ['remove or replace symlink with in-root artifact after review'],
+                        },
+                    });
+                }
+                continue;
+            }
+            if (entry.isDirectory()) {
+                stack.push(candidate);
+            }
+        }
+    }
+}
+function collectNavigationShapeFindings(findings, snapshot, paths) {
+    const backlogByOrigin = new Map();
+    for (const item of snapshot.backlog.items) {
+        if (!item.origin_ref)
+            continue;
+        const existing = backlogByOrigin.get(item.origin_ref) ?? [];
+        existing.push(item);
+        backlogByOrigin.set(item.origin_ref, existing);
+    }
+    for (const record of snapshot.discoveryIndex.records) {
+        if (record.type !== 'EPIC' && record.type !== 'RAD')
+            continue;
+        if (record.status === 'SPLIT') {
+            const children = backlogByOrigin.get(record.id) ?? [];
+            if (children.length === 0) {
+                addFinding(findings, {
+                    finding_id: `SH-NAV-SPLIT-WITHOUT-FEATS-${record.id}`,
+                    rule_id: 'SH-RULE-NAVIGATION-INTEGRITY',
+                    category: 'references',
+                    severity: 'error',
+                    summary: `${record.id} is SPLIT but has no child FEATs in backlog.`,
+                    location: projectRelative(paths.projectRoot, paths.stateFiles.discoveryIndex),
+                    evidence: { id: record.id, status: record.status },
+                    sanitizer: {
+                        disposition: 'manual',
+                        reason: 'Missing child FEATs require recovery from EPIC intent or backlog history.',
+                        actions: ['inspect EPIC artifact', 'rerun or repair breakdown'],
+                    },
+                });
+            }
+        }
+    }
+}
+function summarizeFindings(findings) {
+    const bySeverity = {};
+    const byCategory = {};
+    for (const finding of findings) {
+        bySeverity[finding.severity] = (bySeverity[finding.severity] ?? 0) + 1;
+        byCategory[finding.category] = (byCategory[finding.category] ?? 0) + 1;
+    }
+    return {
+        total: findings.length,
+        by_severity: bySeverity,
+        by_category: byCategory,
+    };
+}
+export function getDiagnosticExitCode(report) {
+    const blockers = report.summary.by_severity.blocker ?? 0;
+    const errors = report.summary.by_severity.error ?? 0;
+    const warnings = report.summary.by_severity.warning ?? 0;
+    if (blockers > 0)
+        return 2;
+    if (errors > 0)
+        return 1;
+    if (report.strict && warnings > 0)
+        return 1;
+    return 0;
+}
+export function getDiagnosticHealth(report) {
+    if ((report.summary.by_severity.blocker ?? 0) > 0)
+        return 'BLOCKED';
+    if ((report.summary.by_severity.error ?? 0) > 0)
+        return 'ERROR';
+    if ((report.summary.by_severity.warning ?? 0) > 0)
+        return 'WARNING';
+    return 'HEALTHY';
+}
+export async function diagnoseSddRoot(projectRoot, options = {}) {
+    const absoluteProjectRoot = path.resolve(projectRoot);
+    const findings = [];
+    let config;
+    let paths;
+    try {
+        config = await loadProjectSddConfig(absoluteProjectRoot);
+        paths = resolveSddPaths(absoluteProjectRoot, config);
+    }
+    catch (error) {
+        const rootPath = path.join(absoluteProjectRoot, '.sdd');
+        addFinding(findings, {
+            finding_id: 'SH-INVALID-SDD-CONFIG',
+            rule_id: 'SH-RULE-INVALID-METADATA',
+            category: 'metadata',
+            severity: 'blocker',
+            summary: 'SDD runtime configuration is invalid.',
+            location: '.sdd/config.yaml',
+            evidence: { error: error.message },
+            sanitizer: {
+                disposition: 'manual',
+                reason: 'Invalid configuration must be corrected before canonical paths can be resolved.',
+                actions: ['fix .sdd/config.yaml', 'rerun diagnosis'],
+            },
+        });
+        return StructuralDiagnosticReportSchema.parse({
+            report_version: 1,
+            generated_at: new Date().toISOString(),
+            root_path: rootPath,
+            strict: options.strict ?? false,
+            findings,
+            summary: summarizeFindings(findings),
+        });
+    }
+    await collectDirectoryFindings(findings, config, paths);
+    await collectStateFileFindings(findings, config, paths);
+    await collectBoundaryFindings(findings, paths);
+    await collectWorkspaceSchemaFindings(findings, paths);
+    await collectWorkspaceAllowlistFindings(findings, paths);
+    let snapshot = null;
+    try {
+        snapshot = await loadStateSnapshot(paths, config);
+    }
+    catch (error) {
+        addFinding(findings, {
+            finding_id: 'SH-INVALID-STATE-METADATA',
+            rule_id: 'SH-RULE-INVALID-METADATA',
+            category: 'metadata',
+            severity: 'blocker',
+            summary: 'One or more SDD state files do not match the canonical schema.',
+            location: projectRelative(paths.projectRoot, paths.stateDir),
+            evidence: { error: error.message },
+            sanitizer: {
+                disposition: 'manual',
+                reason: 'Schema-invalid state may lose information if rewritten automatically.',
+                actions: ['inspect invalid YAML/schema fields', 'restore schema-valid state'],
+            },
+        });
+    }
+    if (snapshot) {
+        collectDuplicateIdFindings(findings, snapshot, paths);
+        collectReferenceFindings(findings, snapshot, paths);
+        collectNavigationShapeFindings(findings, snapshot, paths);
+        await collectLifecyclePlacementFindings(findings, paths, snapshot.backlog.items);
+        await collectLifecycleViolationFindings(findings, paths, snapshot.backlog.items);
+        await collectQualityEvidenceFindings(findings, paths, snapshot.backlog.items);
+        await collectTraceabilityFindings(findings, paths, snapshot.backlog.items);
+        await collectPrivacyComplianceFindings(findings, paths, snapshot);
+        await collectGeneratedViewFindings(findings, config, paths);
+    }
+    return StructuralDiagnosticReportSchema.parse({
+        report_version: 1,
+        generated_at: new Date().toISOString(),
+        root_path: paths.memoryRoot,
+        strict: options.strict ?? false,
+        findings,
+        summary: summarizeFindings(findings),
+    });
+}
+export async function writeDiagnosticReport(projectRoot, outputPath, report) {
+    const config = await loadProjectSddConfig(projectRoot);
+    const paths = resolveSddPaths(path.resolve(projectRoot), config);
+    const resolvedOutputPath = path.resolve(projectRoot, outputPath);
+    const resolvedMemoryRoot = path.resolve(paths.memoryRoot);
+    if (!isInsidePath(resolvedMemoryRoot, resolvedOutputPath)) {
+        throw new SddDiagnosticOptionsError(`Diagnostic output must stay inside the active SDD root: ${projectRelative(path.resolve(projectRoot), resolvedOutputPath)}`);
+    }
+    await fs.mkdir(path.dirname(resolvedOutputPath), { recursive: true });
+    await fs.writeFile(resolvedOutputPath, `${JSON.stringify(report, null, 2)}\n`, 'utf-8');
+    return resolvedOutputPath;
+}
+export function formatDiagnosticText(report) {
+    const severity = report.summary.by_severity;
+    const lines = [
+        `SDD diagnosis: ${report.root_path}`,
+        `Health: ${getDiagnosticHealth(report)}`,
+        `Findings: ${severity.blocker ?? 0} blockers, ${severity.error ?? 0} errors, ${severity.warning ?? 0} warnings, ${severity.info ?? 0} info`,
+    ];
+    if (report.findings.length > 0) {
+        lines.push('');
+    }
+    for (const finding of report.findings) {
+        lines.push(`${finding.severity.toUpperCase()} ${finding.category}/${finding.rule_id}`);
+        lines.push(`  id: ${finding.finding_id}`);
+        lines.push(`  message: ${finding.summary}`);
+        if (finding.location) {
+            lines.push(`  path: ${finding.location}`);
+        }
+        if (finding.rule_id === 'SH-RULE-WORKSPACE-SCHEMA-INVALID') {
+            const invalidFields = Array.isArray(finding.evidence.invalid_fields)
+                ? finding.evidence.invalid_fields
+                : [];
+            if (invalidFields.length > 0) {
+                lines.push(`  invalid fields: ${invalidFields.map((field) => `${field.path ?? '<root>'} (${field.message ?? 'invalid'})`).join('; ')}`);
+            }
+            if (typeof finding.evidence.parse_error === 'string') {
+                lines.push(`  parse error: ${finding.evidence.parse_error}`);
+            }
+        }
+        if (finding.rule_id === 'SH-RULE-WORKSPACE-FILE-NOT-ALLOWLISTED') {
+            lines.push(`  allowed: ${WORKSPACE_FILE_ALLOWLIST.join(', ')}`);
+        }
+        if (finding.rule_id === 'SH-RULE-LIFECYCLE-VIOLATION') {
+            lines.push(`  expected status: ${String(finding.evidence.expected_status)}; actual status: ${String(finding.evidence.actual_status)}`);
+        }
+        if (finding.rule_id === 'SH-RULE-QUALITY-EVIDENCE-INCOMPLETE') {
+            lines.push(`  evidence entries: ${String(finding.evidence.evidence_count ?? 0)}; coverage referenced: ${String(finding.evidence.coverage_referenced ?? false)}`);
+        }
+        lines.push(`  fix: ${finding.sanitizer.disposition} - ${finding.sanitizer.reason}`);
+    }
+    return lines.join('\n');
+}
+export class SddDiagnoseCommand {
+    async execute(projectRoot, options = {}) {
+        const report = await diagnoseSddRoot(projectRoot, { strict: options.strict });
+        const outputPath = options.output
+            ? await writeDiagnosticReport(projectRoot, options.output, report)
+            : undefined;
+        return {
+            report,
+            exitCode: getDiagnosticExitCode(report),
+            health: getDiagnosticHealth(report),
+            outputPath,
+        };
+    }
+}
+//# sourceMappingURL=diagnose.js.map