@devtrack-solution/codesdd 1.2.3 → 1.2.4-rc3

package/dist/core/sdd/services/context.service.js

@@ -1,11 +1,48 @@
 import path from "node:path";
 import { existsSync, promises as fs } from "node:fs";
+import { createHash } from "node:crypto";
 import { parse } from "yaml";
+import { createProjectFingerprint, ensureGlobalCacheLayout } from "../../global-config.js";
 import { CLI_NAME } from "../../branding.js";
-import { loadStateSnapshot } from "../state.js";
+import { loadStateSnapshot, nowIso } from "../state.js";
 import { bundlesForSkills, getRuntime, relProjectPath, coreDocRef, planningDocRef, featureActiveDir, activeDocNamesForLayout, unresolvedDependencies, lockConflictWithActive, featureReadiness, gateSatisfied, detectContextType, pathExists, listAdrRefs } from "../legacy-operations.js";
 import { normalizeSddEntityRef } from "../entity-reference.js";
 import { workspacePlanSchema, workspaceSpecSchema } from "../workspace-schemas.js";
+export const CONTEXT_PACK_BUDGET_MODES = ['compact', 'standard', 'full'];
+const UNLIMITED = Number.POSITIVE_INFINITY;
+const CONTEXT_PACK_CACHE_SCHEMA_VERSION = 2;
+const CONTEXT_PACK_BUDGET_PROFILES = {
+    compact: {
+        maxReadOrder: 8,
+        maxCoreDocs: 6,
+        maxRelevantContracts: 40,
+        maxRelevantServices: 5,
+        maxServiceContracts: 12,
+        maxPredecessorOutputs: 5,
+        maxRelatedFeatures: 50,
+        maxRelatedDebates: 20,
+    },
+    standard: {
+        maxReadOrder: UNLIMITED,
+        maxCoreDocs: UNLIMITED,
+        maxRelevantContracts: UNLIMITED,
+        maxRelevantServices: UNLIMITED,
+        maxServiceContracts: UNLIMITED,
+        maxPredecessorOutputs: UNLIMITED,
+        maxRelatedFeatures: UNLIMITED,
+        maxRelatedDebates: UNLIMITED,
+    },
+    full: {
+        maxReadOrder: UNLIMITED,
+        maxCoreDocs: UNLIMITED,
+        maxRelevantContracts: UNLIMITED,
+        maxRelevantServices: UNLIMITED,
+        maxServiceContracts: UNLIMITED,
+        maxPredecessorOutputs: UNLIMITED,
+        maxRelatedFeatures: UNLIMITED,
+        maxRelatedDebates: UNLIMITED,
+    },
+};
 async function readYamlWorkspaceDoc(filePath, schema) {
     const content = await fs.readFile(filePath, 'utf-8').catch(() => '');
     if (!content.trim())
@@ -60,7 +97,8 @@ export class ContextService {
     constructor(stores) {
         this.stores = stores;
     }
-    async execute(projectRoot, ref) {
+    async execute(projectRoot, ref, options = {}) {
+        const budgetMode = options.budgetMode ?? 'standard';
         const { config, paths } = await getRuntime(projectRoot);
         const snapshot = await loadStateSnapshot(paths, config);
         const normalizedRef = normalizeSddEntityRef(ref);
@@ -68,6 +106,16 @@ export class ContextService {
         if (!type) {
             throw new Error(`Referencia ${ref} invalida. Use FEAT/EPIC/RAD/FGAP/TD.`);
         }
+        const cacheRef = await buildContextPackCacheRef(paths, normalizedRef, type, budgetMode);
+        const cached = await readContextPackCache(cacheRef);
+        if (cached) {
+            return attachContextPackCacheMetadata(cached, cacheRef, true);
+        }
+        const finishContextPack = async (context) => {
+            const budgeted = applyContextPackBudget(context, budgetMode);
+            await writeContextPackCache(cacheRef, budgeted);
+            return attachContextPackCacheMetadata(budgeted, cacheRef, false);
+        };
         const coreDocs = [
             coreDocRef(paths, 'index.md'),
             coreDocRef(paths, 'arquitetura.md'),
@@ -147,7 +195,7 @@ export class ContextService {
                 ? relProjectPath(paths, path.join(paths.projectRoot, workspace.workspace_path, docNames.quality))
                 : '';
             const requiredSkillEvidence = item.recommended_skills.filter(Boolean);
-            return {
+            return finishContextPack({
                 sdd_pack_version: 1,
                 target_id: normalizedRef,
                 target_type: type,
@@ -212,14 +260,14 @@ export class ContextService {
                 lock_conflicts_with: lockConflicts,
                 readiness: featureReadiness(item, snapshot.backlog.items),
                 core_docs: coreDocs,
-            };
+            });
         }
         if (type === 'RAD' || type === 'EPIC') {
             const radar = snapshot.discoveryIndex.records.find((record) => record.id === normalizedRef && (record.type === 'RAD' || record.type === 'EPIC'));
             if (!radar)
                 throw new Error(`Epic/Radar ${normalizedRef} nao encontrado.`);
             const relatedFeatures = snapshot.backlog.items.filter((item) => (item.origin_type === 'radar' || item.origin_type === 'epic') && item.origin_ref === normalizedRef);
-            return {
+            return finishContextPack({
                 sdd_pack_version: 1,
                 target_id: normalizedRef,
                 target_type: type,
@@ -236,13 +284,13 @@ export class ContextService {
                     planningDocRef(paths, 'backlog-graph.md'),
                 ],
                 core_docs: coreDocs,
-            };
+            });
         }
         if (type === 'FGAP') {
             const gap = snapshot.frontendGaps?.items.find((item) => item.id === normalizedRef);
             if (!gap)
                 throw new Error(`Gap de frontend ${normalizedRef} nao encontrado.`);
-            return {
+            return finishContextPack({
                 sdd_pack_version: 1,
                 target_id: normalizedRef,
                 target_type: type,
@@ -257,12 +305,12 @@ export class ContextService {
                     planningDocRef(paths, 'frontend-gaps.md'),
                 ],
                 core_docs: coreDocs,
-            };
+            });
         }
         const debt = snapshot.techDebt.items.find((item) => item.id === normalizedRef);
         if (!debt)
             throw new Error(`Divida tecnica ${normalizedRef} nao encontrada.`);
-        return {
+        return finishContextPack({
             sdd_pack_version: 1,
             target_id: normalizedRef,
             target_type: type,
@@ -274,7 +322,273 @@ export class ContextService {
                 planningDocRef(paths, 'tech-debt.md'),
             ],
             core_docs: coreDocs,
+        });
+    }
+}
+async function buildContextPackCacheRef(paths, ref, type, mode) {
+    const projectFingerprint = createProjectFingerprint(paths.projectRoot);
+    const sourceFingerprint = await buildContextSourceFingerprint(paths, ref);
+    const key = createHash('sha256')
+        .update(JSON.stringify([CONTEXT_PACK_CACHE_SCHEMA_VERSION, projectFingerprint, ref, type, mode, sourceFingerprint]))
+        .digest('hex')
+        .slice(0, 32);
+    const cacheRoot = path.join(ensureGlobalCacheLayout().projects, projectFingerprint, 'context-summary');
+    const cacheFilePath = path.join(cacheRoot, `${key}.json`);
+    return {
+        schema_version: CONTEXT_PACK_CACHE_SCHEMA_VERSION,
+        enabled: true,
+        key,
+        project_fingerprint: projectFingerprint,
+        source_fingerprint: sourceFingerprint,
+        cache_path: displayCachePath(cacheFilePath),
+        cache_file_path: cacheFilePath,
+    };
+}
+async function buildContextSourceFingerprint(paths, ref) {
+    const hash = createHash('sha256');
+    const stateFiles = Object.values(paths.stateFiles);
+    for (const filePath of stateFiles.sort()) {
+        await hashFileIfPresent(hash, filePath);
+    }
+    const workspaceFiles = await listContextWorkspaceFiles(paths, ref);
+    for (const filePath of workspaceFiles.sort()) {
+        await hashFileIfPresent(hash, filePath);
+    }
+    return hash.digest('hex').slice(0, 32);
+}
+async function listContextWorkspaceFiles(paths, ref) {
+    const workspaceRoots = [paths.activeDir, paths.plannedDir, paths.archivedDir].map((root) => path.join(root, ref));
+    const files = [];
+    for (const workspaceRoot of workspaceRoots) {
+        const names = await fs.readdir(workspaceRoot).catch(() => []);
+        for (const name of names) {
+            if (name.endsWith('.yaml') || name.endsWith('.yml') || name.endsWith('.md')) {
+                files.push(path.join(workspaceRoot, name));
+            }
+        }
+    }
+    return files;
+}
+async function hashFileIfPresent(hash, filePath) {
+    const content = await fs.readFile(filePath).catch(() => null);
+    if (!content)
+        return;
+    hash.update(filePath);
+    hash.update('\0');
+    hash.update(content);
+    hash.update('\0');
+}
+async function readContextPackCache(cacheRef) {
+    const content = await fs.readFile(cacheRef.cache_file_path, 'utf-8').catch(() => '');
+    if (!content.trim())
+        return null;
+    try {
+        const entry = JSON.parse(content);
+        if (entry.schema_version !== CONTEXT_PACK_CACHE_SCHEMA_VERSION ||
+            entry.key !== cacheRef.key ||
+            entry.project_fingerprint !== cacheRef.project_fingerprint ||
+            entry.source_fingerprint !== cacheRef.source_fingerprint ||
+            !isRecord(entry.context)) {
+            return null;
+        }
+        return entry.context;
+    }
+    catch {
+        return null;
+    }
+}
+async function writeContextPackCache(cacheRef, context) {
+    const entry = {
+        schema_version: CONTEXT_PACK_CACHE_SCHEMA_VERSION,
+        key: cacheRef.key,
+        project_fingerprint: cacheRef.project_fingerprint,
+        source_fingerprint: cacheRef.source_fingerprint,
+        created_at: nowIso(),
+        context,
+    };
+    await fs.mkdir(path.dirname(cacheRef.cache_file_path), { recursive: true });
+    await fs.writeFile(cacheRef.cache_file_path, JSON.stringify(entry), 'utf-8').catch(() => undefined);
+}
+function attachContextPackCacheMetadata(context, cacheRef, hit) {
+    const { cache_file_path: _cacheFilePath, ...publicCacheRef } = cacheRef;
+    const result = {
+        ...context,
+        context_cache: {
+            ...publicCacheRef,
+            hit,
+            refreshed_at: nowIso(),
+        },
+    };
+    result.context_budget = {
+        ...result.context_budget,
+        estimated_chars_after_budget: estimatePayloadChars(result),
+    };
+    return result;
+}
+function displayCachePath(filePath) {
+    const homeDir = process.env.HOME ? path.resolve(process.env.HOME) : '';
+    const resolved = path.resolve(filePath);
+    if (!homeDir || !resolved.startsWith(`${homeDir}${path.sep}`)) {
+        return resolved;
+    }
+    return path.join('~', path.relative(homeDir, resolved));
+}
+function applyContextPackBudget(context, mode) {
+    const profile = CONTEXT_PACK_BUDGET_PROFILES[mode];
+    const estimatedBefore = estimatePayloadChars(context);
+    const dedupedFields = [];
+    const truncatedFields = [];
+    const budgeted = { ...context };
+    const targetRef = typeof context.target_id === 'string' ? context.target_id : '<REF>';
+    const omittedFields = [];
+    budgeted.read_order = dedupeArrayField(budgeted.read_order, 'read_order', dedupedFields);
+    budgeted.core_docs = dedupeArrayField(budgeted.core_docs, 'core_docs', dedupedFields);
+    budgeted.relevant_contracts = dedupeArrayField(budgeted.relevant_contracts, 'relevant_contracts', dedupedFields);
+    budgeted.predecessor_outputs = dedupeArrayField(budgeted.predecessor_outputs, 'predecessor_outputs', dedupedFields);
+    budgeted.related_features = dedupeArrayField(budgeted.related_features, 'related_features', dedupedFields);
+    budgeted.related_debates = dedupeArrayField(budgeted.related_debates, 'related_debates', dedupedFields);
+    budgeted.relevant_services = dedupeRelevantServices(budgeted.relevant_services, dedupedFields);
+    budgeted.read_order = trimArrayField(budgeted.read_order, profile.maxReadOrder, 'read_order', truncatedFields, omittedFields);
+    budgeted.core_docs = trimArrayField(budgeted.core_docs, profile.maxCoreDocs, 'core_docs', truncatedFields, omittedFields);
+    budgeted.relevant_contracts = trimArrayField(budgeted.relevant_contracts, profile.maxRelevantContracts, 'relevant_contracts', truncatedFields, omittedFields);
+    budgeted.relevant_services = trimRelevantServices(trimArrayField(budgeted.relevant_services, profile.maxRelevantServices, 'relevant_services', truncatedFields, omittedFields), profile.maxServiceContracts, truncatedFields, omittedFields);
+    budgeted.predecessor_outputs = trimArrayField(budgeted.predecessor_outputs, profile.maxPredecessorOutputs, 'predecessor_outputs', truncatedFields, omittedFields);
+    budgeted.related_features = trimArrayField(budgeted.related_features, profile.maxRelatedFeatures, 'related_features', truncatedFields, omittedFields);
+    budgeted.related_debates = trimArrayField(budgeted.related_debates, profile.maxRelatedDebates, 'related_debates', truncatedFields, omittedFields);
+    const result = {
+        ...budgeted,
+        context_budget: {
+            mode,
+            estimated_chars_before_budget: estimatedBefore,
+            estimated_chars_after_budget: 0,
+            deduped_fields: dedupedFields,
+            truncated_fields: Array.from(new Set(truncatedFields)),
+        },
+    };
+    if (omittedFields.length > 0) {
+        result.progressive_disclosure = {
+            mode,
+            reveal_command: `${CLI_NAME} sdd context ${targetRef} --full --json`,
+            omitted_fields: mergeDisclosureHints(omittedFields),
         };
     }
+    result.context_budget.estimated_chars_after_budget = estimatePayloadChars(result);
+    return result;
+}
+function dedupeArrayField(value, fieldName, dedupedFields) {
+    if (!Array.isArray(value) || value.length <= 1) {
+        return value;
+    }
+    const seen = new Set();
+    const deduped = [];
+    for (const entry of value) {
+        const key = stableContextKey(entry);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        deduped.push(entry);
+    }
+    if (deduped.length < value.length) {
+        dedupedFields.push({
+            field: fieldName,
+            before: value.length,
+            after: deduped.length,
+            removed: value.length - deduped.length,
+        });
+    }
+    return deduped;
+}
+function dedupeRelevantServices(value, dedupedFields) {
+    const services = dedupeArrayField(value, 'relevant_services', dedupedFields);
+    if (!Array.isArray(services)) {
+        return services;
+    }
+    return services.map((service, index) => {
+        if (!isRecord(service) || !Array.isArray(service.contracts)) {
+            return service;
+        }
+        const field = `relevant_services[${index}].contracts`;
+        return {
+            ...service,
+            contracts: dedupeArrayField(service.contracts, field, dedupedFields),
+        };
+    });
+}
+function trimArrayField(value, maxItems, fieldName, truncatedFields, omittedFields) {
+    if (!Array.isArray(value) || !Number.isFinite(maxItems) || value.length <= maxItems) {
+        return value;
+    }
+    truncatedFields.push(fieldName);
+    omittedFields.push({
+        field: fieldName,
+        omitted_count: value.length - maxItems,
+        reason: 'budget',
+    });
+    return value.slice(0, maxItems);
+}
+function trimRelevantServices(value, maxServiceContracts, truncatedFields, omittedFields) {
+    if (!Array.isArray(value) || !Number.isFinite(maxServiceContracts)) {
+        return value;
+    }
+    let truncated = false;
+    const services = value.map((service) => {
+        if (!isRecord(service) || !Array.isArray(service.contracts)) {
+            return service;
+        }
+        if (service.contracts.length <= maxServiceContracts) {
+            return service;
+        }
+        truncated = true;
+        omittedFields.push({
+            field: 'relevant_services.contracts',
+            omitted_count: service.contracts.length - maxServiceContracts,
+            reason: 'budget',
+        });
+        return {
+            ...service,
+            contracts: service.contracts.slice(0, maxServiceContracts),
+        };
+    });
+    if (truncated) {
+        truncatedFields.push('relevant_services.contracts');
+    }
+    return services;
+}
+function mergeDisclosureHints(hints) {
+    const byField = new Map();
+    for (const hint of hints) {
+        const existing = byField.get(hint.field);
+        if (!existing) {
+            byField.set(hint.field, { ...hint });
+            continue;
+        }
+        existing.omitted_count += hint.omitted_count;
+    }
+    return Array.from(byField.values());
+}
+function stableContextKey(value) {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'boolean' || value === null) {
+        return JSON.stringify(value);
+    }
+    return JSON.stringify(sortContextValue(value));
+}
+function sortContextValue(value) {
+    if (Array.isArray(value)) {
+        return value.map(sortContextValue);
+    }
+    if (!isRecord(value)) {
+        return value;
+    }
+    return Object.fromEntries(Object.keys(value)
+        .sort()
+        .map((key) => [key, sortContextValue(value[key])]));
+}
+function estimatePayloadChars(value) {
+    return JSON.stringify(value).length;
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
 //# sourceMappingURL=context.service.js.map

package/dist/core/sdd/services/finalize.service.d.ts

@@ -17,6 +17,7 @@ export declare class FinalizeService {
         finalized: string[];
         unblocked: string[];
         pending: number;
+        post_finalize_replan: PostFinalizeReplan;
         updated_core_docs: string[];
         updated_readme: boolean;
         updated_agent_guide: boolean;
@@ -73,6 +74,22 @@ export type Q95Ledger = {
     axes: Record<Q95AxisKey, Q95AxisResult>;
     next_best_action: string;
 };
+export type PostFinalizeReplan = {
+    rank: 'impact';
+    generated_at: string;
+    finalized: string[];
+    unlocked: string[];
+    ready: Array<{
+        id: string;
+        title: string;
+        recommended_skills: string[];
+        score: number;
+        reasons: string[];
+    }>;
+    waves: string[][];
+    blocked_count: number;
+    conflicts_count: number;
+};
 export declare function computeQ95Ledger(paths: SddPaths, config: SddRuntimeConfig, feature: BacklogItem, document: WorkspaceQualityDocument): Promise<Q95Ledger>;
 export declare function weightedAxis(input: {
     raw_score: number;
@@ -90,6 +107,10 @@ export declare function computeIntegrityAxis(document: WorkspaceQualityDocument)
     raw_score: number;
     rationale: string;
 };
+export declare function computeRuntimeQualityAxis(document: WorkspaceQualityDocument): {
+    raw_score: number;
+    rationale: string;
+};
 export declare function computeNamingAxis(feature: BacklogItem, document: WorkspaceQualityDocument): {
     raw_score: number;
     rationale: string;
@@ -98,6 +119,10 @@ export declare function computeTokenAxis(document: WorkspaceQualityDocument): {
     raw_score: number;
     rationale: string;
 };
+export declare function computeStructuredTokenAxis(document: WorkspaceQualityDocument): {
+    raw_score: number;
+    rationale: string;
+};
 export declare function extractCoveragePerformance(document: WorkspaceQualityDocument, kind: 'unit' | 'integration'): number;
 export declare function integritySignalScore(value: 'not_applicable' | 'pending' | 'passed' | 'failed'): number;
 export declare function inferQ95NextAction(axes: Record<Q95AxisKey, Q95AxisResult>): string;