@devtrack-solution/codesdd 1.2.2 → 1.2.3

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

@@ -2,6 +2,7 @@ export interface StructuralLens {
     artifact_type: string;
     name: string;
     required_sections: string[];
+    frontmatter_optional_sections?: string[];
     forbidden_phrases?: string[];
     section_rules?: Record<string, {
         min_lines?: number;

package/dist/core/sdd/lenses.js

@@ -1,8 +1,11 @@
+import { parseGovernanceFile } from './governance-parser.js';
+import { adrFrontmatterSchema, debateFrontmatterSchema, epicFrontmatterSchema, insightFrontmatterSchema, } from './governance-schemas.js';
 export const LENSES = {
     insight: {
         artifact_type: 'INS',
         name: 'Insight Lens',
         required_sections: ['## Title', '## Description'],
+        frontmatter_optional_sections: ['## Title'],
         section_rules: {
             '## Description': { min_length: 100 },
         },
@@ -23,12 +26,14 @@ export const LENSES = {
             '## 8) Quality Contract (Required)',
             '## 9) Output',
         ],
+        frontmatter_optional_sections: ['- Choice (A/B/C):'],
         forbidden_phrases: ['(fill in', 'Describe the result'],
     },
     epic: {
         artifact_type: 'EPIC',
         name: 'Epic Lens',
         required_sections: ['## Origin', '## Approved Summary', '## Status'],
+        frontmatter_optional_sections: ['## Origin', '## Status'],
         forbidden_phrases: ['(fill in approved summary)'],
     },
     adr: {
@@ -61,8 +66,31 @@ function extractFromLines(lines, startIndex) {
     return contentLines.join('\n').trim();
 }
 export function validateDocumentAgainstLens(content, lens) {
-    const missing = lens.required_sections.filter((section) => !content.includes(section));
+    const hasFrontmatter = /^---\r?\n[\s\S]*?\r?\n---\r?\n/.test(content);
+    const effectiveSections = hasFrontmatter && lens.frontmatter_optional_sections
+        ? lens.required_sections.filter((section) => !lens.frontmatter_optional_sections?.includes(section))
+        : lens.required_sections;
+    const missing = effectiveSections.filter((section) => !content.includes(section));
     const violations = [...missing];
+    if (hasFrontmatter) {
+        try {
+            if (lens.artifact_type === 'INS') {
+                parseGovernanceFile('lens-inline-content', content, insightFrontmatterSchema);
+            }
+            else if (lens.artifact_type === 'DEB') {
+                parseGovernanceFile('lens-inline-content', content, debateFrontmatterSchema);
+            }
+            else if (lens.artifact_type === 'EPIC') {
+                parseGovernanceFile('lens-inline-content', content, epicFrontmatterSchema);
+            }
+            else if (lens.artifact_type === 'ADR') {
+                parseGovernanceFile('lens-inline-content', content, adrFrontmatterSchema);
+            }
+        }
+        catch (error) {
+            violations.push(error instanceof Error ? error.message : String(error));
+        }
+    }
     if (lens.forbidden_phrases) {
         for (const phrase of lens.forbidden_phrases) {
             if (content.includes(phrase)) {

package/dist/core/sdd/migrate-workspace.js

@@ -2,6 +2,7 @@ import path from 'node:path';
 import { existsSync, promises as fs } from 'node:fs';
 import { stringify as stringifyYaml } from 'yaml';
 import { loadProjectSddConfig, resolveSddPaths } from './state.js';
+import { normalizeFeatRef } from './entity-reference.js';
 import { workspaceChangelogSchema, workspacePlanSchema, workspaceQualitySchema, workspaceSpecSchema, workspaceTasksSchema, } from './workspace-schemas.js';
 const MIGRATION_MARKER = '# MIGRATION: field required but source had no content';
 const CANONICAL_DOCS = [
@@ -18,9 +19,10 @@ const CANONICAL_DOCS = [
 export async function findMarkdownWorkspaceFiles(projectRoot, feat) {
     const config = await loadProjectSddConfig(projectRoot);
     const paths = resolveSddPaths(projectRoot, config);
+    const featFilter = feat ? normalizeFeatRef(feat) ?? feat.trim() : undefined;
     const files = [];
     for (const root of [paths.plannedDir, paths.activeDir, paths.archivedDir]) {
-        for (const workspace of await listFeatureWorkspaces(root, feat)) {
+        for (const workspace of await listFeatureWorkspaces(root, featFilter)) {
             const entries = await fs.readdir(workspace.path, { withFileTypes: true }).catch(() => []);
             for (const entry of entries) {
                 if (!entry.isFile() || path.extname(entry.name) !== '.md')
@@ -38,13 +40,14 @@ export class MigrateWorkspaceCommand {
         const config = await loadProjectSddConfig(projectRoot);
         const paths = resolveSddPaths(projectRoot, config);
         const dryRun = Boolean(options?.dryRun);
+        const featFilter = options?.feat ? normalizeFeatRef(options.feat) ?? options.feat.trim() : undefined;
         const features = [];
         for (const [rootName, rootPath] of [
             ['planned', paths.plannedDir],
             ['active', paths.activeDir],
             ['archived', paths.archivedDir],
         ]) {
-            for (const workspace of await listFeatureWorkspaces(rootPath, options?.feat)) {
+            for (const workspace of await listFeatureWorkspaces(rootPath, featFilter)) {
                 const fileResults = [];
                 const entries = await fs.readdir(workspace.path, { withFileTypes: true }).catch(() => []);
                 for (const entry of entries) {
@@ -272,6 +275,7 @@ function migrateQuality(featureId, parsed) {
         })),
         skill_evidence: {
             required_skill_ids: [],
+            policy_requirements: [],
             evidence: [],
             verification_rule: 'No skill evidence required for migrated legacy workspaces.',
         },
@@ -282,6 +286,15 @@ function migrateQuality(featureId, parsed) {
                 evidence: evidence.join('; ') || `${MIGRATION_MARKER}: quality evidence`,
             },
         ],
+        requirement_validation_evidence_risk_matrix: [
+            {
+                requirement_ref: `${featureId}-MIG-R1`,
+                validation_refs: ['Migrated validation'],
+                evidence_refs: evidence.length > 0 ? evidence : [`${MIGRATION_MARKER}: quality evidence`],
+                residual_risk: 'Residual risk migrated from legacy workspace and requires follow-up review.',
+                risk_status: 'open',
+            },
+        ],
         exceptions: [],
         remediation_policy: { on_coverage_miss: 'block', max_rounds: 3 },
         traceability: {
@@ -291,6 +304,47 @@ function migrateQuality(featureId, parsed) {
             },
             requirements: [],
         },
+        q95_ledger: {
+            threshold: 95,
+            score: 0,
+            status: 'pending',
+            computed_at: '',
+            weights: {
+                coverage: 30,
+                traceability: 20,
+                integrity: 20,
+                naming: 10,
+                token: 20,
+            },
+            axes: {
+                coverage: {
+                    raw_score: 0,
+                    weighted_score: 0,
+                    rationale: 'Computed during finalize.',
+                },
+                traceability: {
+                    raw_score: 0,
+                    weighted_score: 0,
+                    rationale: 'Computed during finalize.',
+                },
+                integrity: {
+                    raw_score: 0,
+                    weighted_score: 0,
+                    rationale: 'Computed during finalize.',
+                },
+                naming: {
+                    raw_score: 0,
+                    weighted_score: 0,
+                    rationale: 'Computed during finalize.',
+                },
+                token: {
+                    raw_score: 0,
+                    weighted_score: 0,
+                    rationale: 'Computed during finalize.',
+                },
+            },
+            next_best_action: 'Record missing evidence to raise the lowest weighted axis.',
+        },
     };
     return withValidation('5-quality.yaml', doc, missing, workspaceQualitySchema);
 }

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

@@ -1,4 +1,4 @@
-export declare const CURRENT_SDD_STATE_VERSION = 2;
+export { CURRENT_SDD_STATE_VERSION } from './contract.js';
 export interface SddMigrationAssessment {
     currentVersion: number;
     targetVersion: number;

package/dist/core/sdd/migrate.js

@@ -2,10 +2,11 @@ import path from 'node:path';
 import { promises as fs } from 'node:fs';
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
 import { CLI_NAME, } from '../branding.js';
+import { CURRENT_SDD_STATE_VERSION, buildSddContractConfig, sddContractMismatchReasons, } from './contract.js';
 import { findMarkdownWorkspaceFiles, MigrateWorkspaceCommand } from './migrate-workspace.js';
 import { loadProjectSddConfig, loadStateSnapshot, resolveSddPaths, saveBacklogState, saveDiscoveryIndexState, saveFinalizeQueueState, saveFrontendDecisionsState, saveFrontendGapsState, saveFrontendMapState, saveIntegrationContractsState, saveRepoMapState, saveServiceCatalogState, saveSourceIndexState, saveTechDebtState, saveTechStackState, saveUnblockEventsState, } from './state.js';
 import { runLifecycleHooks } from './domain/lifecycle-hooks.js';
-export const CURRENT_SDD_STATE_VERSION = 2;
+export { CURRENT_SDD_STATE_VERSION } from './contract.js';
 const ID_PREFIXES = new Set(['INS', 'DEB', 'RAD', 'EPIC', 'FEAT', 'FGAP', 'TD', 'SRC']);
 const REFERENCE_LIKE_VALUE = /\b(?:INS|DEB|RAD|EPIC|FEAT|FGAP|TD|SRC)-\d+\b/;
 const MIGRATABLE_FILE_EXTENSIONS = new Set(['.md', '.yaml', '.yml', '.txt']);
@@ -83,6 +84,21 @@ async function readStateConfigVersion(configPath) {
         return 1;
     }
 }
+async function readStateConfig(configPath) {
+    try {
+        const parsed = parseYaml(await fs.readFile(configPath, 'utf-8'));
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+const LEGACY_GENERATED_BY_PREFIXES = [`${'open'}sdd`, `${'open'}spec`];
+function isLegacyGeneratedBy(value) {
+    if (typeof value !== 'string')
+        return false;
+    return LEGACY_GENERATED_BY_PREFIXES.some((prefix) => new RegExp(`^${prefix}\\s`, 'i').test(value));
+}
 async function writeStateConfigVersion(configPath) {
     let payload = {};
     try {
@@ -95,8 +111,12 @@ async function writeStateConfigVersion(configPath) {
         payload = {};
     }
     payload.version = 1;
-    payload.generatedBy = payload.generatedBy || `${CLI_NAME} sdd init`;
+    payload.generatedBy =
+        typeof payload.generatedBy === 'string' && !isLegacyGeneratedBy(payload.generatedBy)
+            ? payload.generatedBy
+            : `${CLI_NAME} sdd migrate`;
     payload.state_version = CURRENT_SDD_STATE_VERSION;
+    payload.sdd_contract = buildSddContractConfig();
     payload.last_migrated_at = new Date().toISOString();
     await fs.writeFile(configPath, stringifyYaml(payload), 'utf-8');
 }
@@ -199,6 +219,7 @@ export async function assessSddMigration(projectRoot) {
     const paths = resolveSddPaths(projectRoot, config);
     const snapshot = await loadStateSnapshot(paths, config);
     const currentVersion = await readStateConfigVersion(paths.configFile);
+    const rawConfig = await readStateConfig(paths.configFile);
     const conversions = new Map();
     collectReferenceConversions(snapshot.discoveryIndex, conversions);
     collectReferenceConversions(snapshot.backlog, conversions);
@@ -223,6 +244,16 @@ export async function assessSddMigration(projectRoot) {
     if (currentVersion < CURRENT_SDD_STATE_VERSION) {
         reasons.push(`state_version=${currentVersion} esta abaixo da versao requerida ${CURRENT_SDD_STATE_VERSION}`);
     }
+    if (currentVersion > CURRENT_SDD_STATE_VERSION) {
+        reasons.push(`state_version=${currentVersion} esta acima da versao suportada ${CURRENT_SDD_STATE_VERSION}`);
+    }
+    const contractReasons = sddContractMismatchReasons(rawConfig.sdd_contract);
+    if (contractReasons.length > 0) {
+        reasons.push(`sdd_contract desalinhado: ${contractReasons.join(', ')}`);
+    }
+    if (isLegacyGeneratedBy(rawConfig.generatedBy)) {
+        reasons.push('generatedBy ainda usa identidade legacy pre-CodeSDD');
+    }
     if (legacyRecords.length > 0) {
         reasons.push(`registros legacy detectados: ${legacyRecords.join(', ')}`);
     }
@@ -260,6 +291,9 @@ export class SddMigrateCommand {
             messages.push(`Estado SDD ja esta na versao ${assessment.targetVersion}. Nenhuma migracao necessaria.`);
             return { converted: 0, messages, assessment };
         }
+        if (assessment.currentVersion > assessment.targetVersion) {
+            throw new Error(`Estado SDD state_version=${assessment.currentVersion} esta acima da versao suportada ${assessment.targetVersion}. Atualize o CodeSDD antes de executar migracao ou comandos SDD.`);
+        }
         if (options?.radToEpic === false) {
             throw new Error('Migracao SDD mandatória nao pode ser desabilitada.');
         }

package/dist/core/sdd/package-structure-gate.d.ts

@@ -0,0 +1,83 @@
+import { z } from 'zod';
+export declare const DerivationProfileSchema: z.ZodEnum<{
+    prototype: "prototype";
+    "foundation-compatible": "foundation-compatible";
+    "enterprise-strict": "enterprise-strict";
+}>;
+export declare const PreviewGateStatusSchema: z.ZodEnum<{
+    pending: "pending";
+    approved: "approved";
+    corrected: "corrected";
+    rejected: "rejected";
+}>;
+export declare const PackageStructureNodeKindSchema: z.ZodEnum<{
+    file: "file";
+    dir: "dir";
+}>;
+export declare const PackageStructureNodeSchema: z.ZodSchema<PackageStructureNode>;
+export declare const PackageStructurePreviewSchema: z.ZodObject<{
+    schema_version: z.ZodLiteral<1>;
+    generated_at: z.ZodString;
+    project_name: z.ZodString;
+    profile: z.ZodEnum<{
+        prototype: "prototype";
+        "foundation-compatible": "foundation-compatible";
+        "enterprise-strict": "enterprise-strict";
+    }>;
+    contexts: z.ZodArray<z.ZodString>;
+    subsystems: z.ZodArray<z.ZodString>;
+    transports: z.ZodArray<z.ZodString>;
+    tree: z.ZodType<PackageStructureNode, unknown, z.core.$ZodTypeInternals<PackageStructureNode, unknown>>;
+}, z.core.$strip>;
+export declare const HumanValidationGateSchema: z.ZodObject<{
+    gate_id: z.ZodString;
+    rule_ref: z.ZodLiteral<"DTAPI-P0-PREVIEW-001">;
+    status: z.ZodEnum<{
+        pending: "pending";
+        approved: "approved";
+        corrected: "corrected";
+        rejected: "rejected";
+    }>;
+    preview_ref: z.ZodString;
+    approved_at: z.ZodOptional<z.ZodString>;
+    approved_by: z.ZodOptional<z.ZodString>;
+    correction_notes: z.ZodOptional<z.ZodString>;
+    exception_refs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export interface HumanValidationGateData {
+    selected_profile: z.infer<typeof DerivationProfileSchema>;
+    package_preview: z.infer<typeof PackageStructurePreviewSchema>;
+    human_validation_gate: z.infer<typeof HumanValidationGateSchema>;
+    exception_list: Array<{
+        adr_ref: string;
+        reason: string;
+        severity: string;
+    }>;
+    policy_pool_seed: string[];
+}
+export interface DebGateInput {
+    project_name: string;
+    profile?: z.infer<typeof DerivationProfileSchema>;
+    contexts?: string[];
+    subsystems?: string[];
+    transports?: string[];
+    generated_at?: string;
+}
+export declare function generatePackageStructurePreview(input: DebGateInput): z.infer<typeof PackageStructurePreviewSchema>;
+export declare function formatPreviewAsTree(node: z.infer<typeof PackageStructureNodeSchema>, prefix?: string): string;
+export declare function buildHumanValidationGate(preview: z.infer<typeof PackageStructurePreviewSchema>): z.infer<typeof HumanValidationGateSchema>;
+export declare function generateDevtrackApiDebGate(input: DebGateInput): HumanValidationGateData;
+export declare function isGatePending(gate: z.infer<typeof HumanValidationGateSchema>): boolean;
+export declare function isGateApproved(gate: z.infer<typeof HumanValidationGateSchema>): boolean;
+export type DerivationProfile = z.infer<typeof DerivationProfileSchema>;
+export type PreviewGateStatus = z.infer<typeof PreviewGateStatusSchema>;
+export type PackageStructureNodeKind = z.infer<typeof PackageStructureNodeKindSchema>;
+export type PackageStructureNode = {
+    name: string;
+    kind: PackageStructureNodeKind;
+    description?: string;
+    children?: PackageStructureNode[];
+};
+export type PackageStructurePreview = z.infer<typeof PackageStructurePreviewSchema>;
+export type HumanValidationGate = z.infer<typeof HumanValidationGateSchema>;
+//# sourceMappingURL=package-structure-gate.d.ts.map