@devtrack-solution/codesdd 1.2.2 → 1.2.3

package/dist/core/sdd/deepagents/policy.js

@@ -0,0 +1,358 @@
+import { createHash } from 'node:crypto';
+import { inferNetworkDomainsForModel, requiredCredentialEnvForModel, resolveDeepAgentsModelProvider, } from './model-provider.js';
+const DEFAULT_ENV_ALLOWLIST = [
+    'CI',
+    'CODESDD_AGENT_PROVIDER',
+    'CODESDD_DEEPAGENTS_RUNTIME',
+    'CODESDD_DEEPAGENTS_DEFAULT_MODE',
+];
+const SECRET_ENV_TOKENS = ['KEY', 'SECRET', 'TOKEN', 'PASSWORD', 'CREDENTIAL', 'PRIVATE', 'AUTH'];
+const HIGH_RISK_OPERATIONS = new Set([
+    'write',
+    'execute',
+    'network',
+    'plugin-apply',
+    'finalize',
+    'dependency-change',
+    'process-spawn',
+]);
+export function createDeepAgentsPolicySnapshot(env = process.env) {
+    const envAllowlist = normalizeEnvNames([
+        ...DEFAULT_ENV_ALLOWLIST,
+        ...parseCsv(env.CODESDD_AGENT_ENV_ALLOWLIST),
+    ]);
+    const allowedDomains = normalizeDomains(parseCsv(env.CODESDD_AGENT_ALLOWED_DOMAINS));
+    const snapshot = {
+        provider: (env.CODESDD_AGENT_PROVIDER || 'deepagents').trim() || 'deepagents',
+        enabled: parseBooleanFlag(env.CODESDD_DEEPAGENTS_ENABLED, false),
+        runtime: parseRuntimeMode(env.CODESDD_DEEPAGENTS_RUNTIME),
+        defaultMode: parseDefaultMode(env.CODESDD_DEEPAGENTS_DEFAULT_MODE),
+        requireHitl: parseBooleanFlag(env.CODESDD_DEEPAGENTS_REQUIRE_HITL, true),
+        networkPolicy: parseNetworkPolicy(env.CODESDD_AGENT_NETWORK_POLICY),
+        envAllowlist,
+        allowedDomains,
+        writeScope: parseCsv(env.CODESDD_AGENT_WRITE_SCOPE),
+        model: safeTrim(env.CODESDD_DEEPAGENTS_MODEL),
+        plannerModel: safeTrim(env.CODESDD_DEEPAGENTS_PLANNER_MODEL),
+        reviewerModel: safeTrim(env.CODESDD_DEEPAGENTS_REVIEWER_MODEL),
+        coderModel: safeTrim(env.CODESDD_DEEPAGENTS_CODER_MODEL),
+        maxIterations: parsePositiveInteger(env.CODESDD_DEEPAGENTS_MAX_ITERATIONS),
+        maxSubagents: parsePositiveInteger(env.CODESDD_DEEPAGENTS_MAX_SUBAGENTS),
+        maxParallel: parsePositiveInteger(env.CODESDD_DEEPAGENTS_MAX_PARALLEL),
+        sandboxRoot: safeTrim(env.CODESDD_DEEPAGENTS_SANDBOX_ROOT),
+        worktreeRoot: safeTrim(env.CODESDD_AGENT_WORKTREE_ROOT),
+    };
+    return {
+        ...snapshot,
+        configFingerprint: buildDeepAgentsConfigFingerprint(snapshot),
+    };
+}
+export function evaluateDeepAgentsRuntimeReadiness(snapshot, env = process.env) {
+    if (!snapshot.enabled || snapshot.runtime === 'disabled') {
+        return {
+            status: 'disabled',
+            runtime: snapshot.runtime,
+            model: snapshot.model,
+            credentialPresent: false,
+            reasons: ['DeepAgents runtime is disabled by policy.'],
+        };
+    }
+    if (snapshot.provider.trim().toLowerCase() !== 'deepagents') {
+        return {
+            status: 'blocked',
+            runtime: snapshot.runtime,
+            model: snapshot.model,
+            credentialPresent: false,
+            reasons: ['CODESDD_AGENT_PROVIDER must be deepagents when DeepAgents runtime is enabled.'],
+        };
+    }
+    if (snapshot.runtime === 'fake') {
+        return {
+            status: 'ready',
+            runtime: snapshot.runtime,
+            model: snapshot.model,
+            credentialPresent: false,
+            reasons: [],
+        };
+    }
+    const reasons = [];
+    if (!snapshot.model) {
+        reasons.push('CODESDD_DEEPAGENTS_MODEL is required when runtime is deepagents-js.');
+    }
+    const providerResolution = resolveDeepAgentsModelProvider(snapshot.model, env);
+    reasons.push(...providerResolution.reasons);
+    const credentialEnv = providerResolution.credential.credentialEnv;
+    const credentialPresent = providerResolution.credential.credentialPresent;
+    return {
+        status: reasons.length > 0 ? 'blocked' : 'ready',
+        runtime: snapshot.runtime,
+        model: snapshot.model,
+        provider: providerResolution.profile?.provider ?? providerResolution.modelRef?.provider,
+        credentialEnv,
+        credentialPresent,
+        endpointEnv: providerResolution.endpoint.endpointEnv,
+        endpointPresent: providerResolution.endpoint.endpointPresent,
+        reasons,
+    };
+}
+export function buildDeepAgentsOperationalPreflight(snapshot, env = process.env) {
+    const readiness = evaluateDeepAgentsRuntimeReadiness(snapshot, env);
+    const checks = [];
+    const reasons = [...readiness.reasons];
+    const requiredEnv = new Set();
+    const missingEnv = new Set();
+    const inferredDomains = inferNetworkDomainsForModel(snapshot.model, env);
+    const providerOk = snapshot.provider.trim().toLowerCase() === 'deepagents';
+    checks.push({
+        id: 'provider',
+        status: readiness.status === 'disabled' ? 'skip' : providerOk ? 'pass' : 'fail',
+        message: providerOk
+            ? 'Provider deepagents configurado.'
+            : 'CODESDD_AGENT_PROVIDER deve ser deepagents quando runtime estiver habilitado.',
+    });
+    checks.push({
+        id: 'runtime',
+        status: readiness.status === 'disabled'
+            ? 'skip'
+            : snapshot.runtime === 'fake' || snapshot.runtime === 'deepagents-js'
+                ? 'pass'
+                : 'fail',
+        message: readiness.status === 'disabled'
+            ? 'Runtime DeepAgents desabilitado.'
+            : `Runtime configurado: ${snapshot.runtime}.`,
+    });
+    if (readiness.status !== 'disabled' && snapshot.runtime === 'deepagents-js') {
+        checks.push({
+            id: 'model',
+            status: snapshot.model ? 'pass' : 'fail',
+            message: snapshot.model
+                ? `Modelo selecionado: ${snapshot.model}.`
+                : 'CODESDD_DEEPAGENTS_MODEL e obrigatorio para runtime deepagents-js.',
+        });
+    }
+    else {
+        checks.push({
+            id: 'model',
+            status: 'skip',
+            message: 'Modelo nao obrigatorio para runtime desabilitado/fake.',
+        });
+    }
+    if (readiness.credentialEnv) {
+        requiredEnv.add(readiness.credentialEnv);
+        if (!readiness.credentialPresent) {
+            missingEnv.add(readiness.credentialEnv);
+        }
+    }
+    checks.push({
+        id: 'credential',
+        status: readiness.status === 'disabled'
+            ? 'skip'
+            : readiness.credentialEnv
+                ? readiness.credentialPresent
+                    ? 'pass'
+                    : 'fail'
+                : 'skip',
+        message: readiness.credentialEnv
+            ? readiness.credentialPresent
+                ? `${readiness.credentialEnv} presente.`
+                : `${readiness.credentialEnv} ausente.`
+            : 'Credencial nao requerida para o perfil atual.',
+    });
+    if (readiness.endpointEnv) {
+        requiredEnv.add(readiness.endpointEnv);
+        if (!readiness.endpointPresent) {
+            missingEnv.add(readiness.endpointEnv);
+        }
+    }
+    checks.push({
+        id: 'endpoint',
+        status: readiness.status === 'disabled'
+            ? 'skip'
+            : readiness.endpointEnv
+                ? readiness.endpointPresent
+                    ? 'pass'
+                    : 'fail'
+                : 'skip',
+        message: readiness.endpointEnv
+            ? readiness.endpointPresent
+                ? `${readiness.endpointEnv} presente.`
+                : `${readiness.endpointEnv} ausente.`
+            : 'Endpoint nao obrigatorio para o perfil atual.',
+    });
+    const networkDecision = evaluateNetworkAccess(inferredDomains, snapshot.networkPolicy, snapshot.allowedDomains);
+    if (networkDecision.blocked.length > 0) {
+        reasons.push(`Network policy ${snapshot.networkPolicy} bloqueia dominios inferidos: ${networkDecision.blocked.join(', ')}.`);
+    }
+    checks.push({
+        id: 'network',
+        status: readiness.status === 'disabled'
+            ? 'skip'
+            : networkDecision.blocked.length === 0
+                ? 'pass'
+                : 'fail',
+        message: networkDecision.blocked.length === 0
+            ? 'Politica de rede cobre os dominios inferidos do provider.'
+            : `Dominios bloqueados: ${networkDecision.blocked.join(', ')}.`,
+    });
+    const status = readiness.status === 'disabled'
+        ? 'disabled'
+        : reasons.length > 0
+            ? 'blocked'
+            : 'ready';
+    return {
+        status,
+        provider: snapshot.provider,
+        runtime: snapshot.runtime,
+        model: snapshot.model,
+        reasons,
+        checks,
+        required_env: Array.from(requiredEnv).sort(),
+        missing_env: Array.from(missingEnv).sort(),
+        allowed_domains: [...snapshot.allowedDomains],
+        inferred_domains: inferredDomains,
+    };
+}
+export function evaluateEnvPassThrough(requestedEnv, allowlist) {
+    const allowedSet = new Set(normalizeEnvNames(allowlist));
+    const normalizedRequested = normalizeEnvNames(requestedEnv);
+    const allowed = [];
+    const blocked = [];
+    for (const envName of normalizedRequested) {
+        if (isSecretEnvName(envName)) {
+            blocked.push({ env: envName, reason: 'SECRET_ENV_BLOCKED' });
+            continue;
+        }
+        if (!allowedSet.has(envName)) {
+            blocked.push({ env: envName, reason: 'ENV_NOT_ALLOWLISTED' });
+            continue;
+        }
+        allowed.push(envName);
+    }
+    return { allowed, blocked };
+}
+export function evaluateNetworkAccess(requestedDomains, policy, allowlist) {
+    const requested = normalizeDomains(requestedDomains);
+    const approved = normalizeDomains(allowlist);
+    if (requested.length === 0) {
+        return { allowed: [], blocked: [], policy };
+    }
+    if (policy === 'disabled') {
+        return { allowed: [], blocked: requested, policy };
+    }
+    if (policy === 'enabled') {
+        return { allowed: requested, blocked: [], policy };
+    }
+    const allowed = [];
+    const blocked = [];
+    for (const domain of requested) {
+        const approvedDomain = approved.some((candidate) => domain === candidate || domain.endsWith(`.${candidate}`));
+        if (approvedDomain) {
+            allowed.push(domain);
+            continue;
+        }
+        blocked.push(domain);
+    }
+    return { allowed, blocked, policy };
+}
+export function requiresHumanApproval(mode, operation, requireHitl) {
+    if (!requireHitl) {
+        return false;
+    }
+    if (mode === 'apply-sandbox' || mode === 'apply-approved') {
+        return true;
+    }
+    return HIGH_RISK_OPERATIONS.has(operation);
+}
+export function buildDeepAgentsConfigFingerprint(config) {
+    const normalized = normalizeForFingerprint(config);
+    const payload = JSON.stringify(normalized);
+    return createHash('sha256').update(payload).digest('hex');
+}
+function parseDefaultMode(mode) {
+    const candidate = (mode || '').trim().toLowerCase();
+    switch (candidate) {
+        case 'read-only':
+        case 'plan':
+        case 'validate':
+        case 'apply-sandbox':
+        case 'apply-approved':
+            return candidate;
+        default:
+            return 'plan';
+    }
+}
+function parseRuntimeMode(value) {
+    const normalized = (value || '').trim().toLowerCase();
+    if (normalized === 'fake' || normalized === 'deepagents-js') {
+        return normalized;
+    }
+    return 'disabled';
+}
+function parseNetworkPolicy(value) {
+    const normalized = (value || '').trim().toLowerCase();
+    if (normalized === 'restricted' || normalized === 'enabled') {
+        return normalized;
+    }
+    return 'disabled';
+}
+function parseBooleanFlag(value, fallback) {
+    if (typeof value !== 'string') {
+        return fallback;
+    }
+    const normalized = value.trim().toLowerCase();
+    if (normalized === '1' || normalized === 'true' || normalized === 'yes') {
+        return true;
+    }
+    if (normalized === '0' || normalized === 'false' || normalized === 'no') {
+        return false;
+    }
+    return fallback;
+}
+function parseCsv(value) {
+    return (value || '')
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+}
+function normalizeEnvNames(values) {
+    return Array.from(new Set(values.map((value) => value.trim().toUpperCase()).filter(Boolean))).sort();
+}
+function normalizeDomains(values) {
+    return Array.from(new Set(values
+        .map((value) => value.trim().toLowerCase())
+        .filter(Boolean)
+        .map((value) => value.replace(/^https?:\/\//u, '').replace(/\/.*$/u, '')))).sort();
+}
+function isSecretEnvName(value) {
+    return SECRET_ENV_TOKENS.some((token) => value.includes(token));
+}
+function safeTrim(value) {
+    const trimmed = (value || '').trim();
+    return trimmed || undefined;
+}
+function parsePositiveInteger(value) {
+    const trimmed = safeTrim(value);
+    if (!trimmed) {
+        return undefined;
+    }
+    const parsed = Number.parseInt(trimmed, 10);
+    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : undefined;
+}
+function normalizeForFingerprint(value) {
+    if (Array.isArray(value)) {
+        return value.map((entry) => normalizeForFingerprint(entry));
+    }
+    if (!value || typeof value !== 'object') {
+        return value;
+    }
+    const entries = Object.entries(value)
+        .filter(([, entryValue]) => typeof entryValue !== 'undefined')
+        .sort(([left], [right]) => left.localeCompare(right));
+    const normalized = {};
+    for (const [key, entryValue] of entries) {
+        normalized[key] = normalizeForFingerprint(entryValue);
+    }
+    return normalized;
+}
+export { inferNetworkDomainsForModel, requiredCredentialEnvForModel, resolveDeepAgentsModelProvider };
+//# sourceMappingURL=policy.js.map

package/dist/core/sdd/deepagents/quality-witness.d.ts

@@ -0,0 +1,3 @@
+import type { WorkspaceQualityDocument } from '../workspace-schemas.js';
+export declare function evaluateQualityWitnessMatrix(document: WorkspaceQualityDocument): string[];
+//# sourceMappingURL=quality-witness.d.ts.map

package/dist/core/sdd/deepagents/quality-witness.js

@@ -0,0 +1,77 @@
+const PLACEHOLDER_TOKENS = ['tbd', 'todo', 'pending', 'to define', 'na', 'n/a'];
+const FUTURE_TENSE_COMPLETION_PATTERNS = [
+    /\bwill\s+(?:verify|validate|run|execute|confirm|check|ensure)\b/iu,
+    /\bwill\s+be\s+(?:verified|validated|run|executed|confirmed|checked|ensured)\b/iu,
+];
+function isPlaceholderValue(value) {
+    const normalized = value.trim().toLowerCase();
+    return PLACEHOLDER_TOKENS.some((token) => normalized === token || normalized.includes(`${token} `));
+}
+function hasPlaceholderValues(values) {
+    return values.some((value) => isPlaceholderValue(value));
+}
+function hasFutureTenseCompletionClaim(value) {
+    return FUTURE_TENSE_COMPLETION_PATTERNS.some((pattern) => pattern.test(value));
+}
+function collectFutureTenseCompletionClaims(document) {
+    const claims = [];
+    for (const entry of document.evidence_log) {
+        if (hasFutureTenseCompletionClaim(entry.result)) {
+            claims.push(`evidence_log entry "${entry.kind}" uses future-tense completion evidence`);
+        }
+    }
+    for (const entry of document.acceptance_matrix) {
+        if (hasFutureTenseCompletionClaim(entry.evidence)) {
+            claims.push(`acceptance_matrix criterion "${entry.criterion}" uses future-tense completion evidence`);
+        }
+    }
+    for (const row of document.requirement_validation_evidence_risk_matrix ?? []) {
+        if (hasPlaceholderValues(row.evidence_refs)) {
+            continue;
+        }
+        for (const evidenceRef of row.evidence_refs) {
+            if (hasFutureTenseCompletionClaim(evidenceRef)) {
+                claims.push(`${row.requirement_ref} evidence_refs use future-tense completion evidence`);
+            }
+        }
+    }
+    return claims;
+}
+export function evaluateQualityWitnessMatrix(document) {
+    const matrix = document.requirement_validation_evidence_risk_matrix ?? [];
+    const reasons = [];
+    reasons.push(...collectFutureTenseCompletionClaims(document));
+    if (matrix.length === 0) {
+        reasons.push('requirement_validation_evidence_risk_matrix is required and cannot be empty before finalize');
+        return reasons;
+    }
+    const traceabilityRequirements = new Set((document.traceability?.requirements ?? [])
+        .map((entry) => (entry.requirement_ref || '').trim())
+        .filter(Boolean));
+    const matrixRequirements = new Set();
+    for (const row of matrix) {
+        const requirementRef = row.requirement_ref.trim();
+        if (!requirementRef) {
+            reasons.push('matrix row has empty requirement_ref');
+            continue;
+        }
+        matrixRequirements.add(requirementRef);
+        if (row.validation_refs.length === 0 || hasPlaceholderValues(row.validation_refs)) {
+            reasons.push(`${requirementRef} must declare concrete validation_refs`);
+        }
+        if (row.evidence_refs.length === 0 || hasPlaceholderValues(row.evidence_refs)) {
+            reasons.push(`${requirementRef} must declare concrete evidence_refs`);
+        }
+        const residualRisk = (row.residual_risk || '').trim();
+        if (residualRisk.length < 10 || isPlaceholderValue(residualRisk)) {
+            reasons.push(`${requirementRef} must declare a concrete residual_risk`);
+        }
+    }
+    for (const requirementRef of traceabilityRequirements) {
+        if (!matrixRequirements.has(requirementRef)) {
+            reasons.push(`traceability requirement ${requirementRef} is missing from requirement_validation_evidence_risk_matrix`);
+        }
+    }
+    return Array.from(new Set(reasons));
+}
+//# sourceMappingURL=quality-witness.js.map

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

@@ -0,0 +1,75 @@
+import { z } from 'zod';
+export declare const reversaDomainSchema: z.ZodEnum<{
+    specs: "specs";
+    architecture: "architecture";
+    rules: "rules";
+    data: "data";
+    migration: "migration";
+    "legacy-analysis": "legacy-analysis";
+    screens: "screens";
+    microservices: "microservices";
+    "equivalence-validation": "equivalence-validation";
+}>;
+export declare const deepAgentsReversaRequestSchema: z.ZodObject<{
+    feature_ref: z.ZodString;
+    domains: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        specs: "specs";
+        architecture: "architecture";
+        rules: "rules";
+        data: "data";
+        migration: "migration";
+        "legacy-analysis": "legacy-analysis";
+        screens: "screens";
+        microservices: "microservices";
+        "equivalence-validation": "equivalence-validation";
+    }>>>;
+    legacy_sources: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const deepAgentsReversaPlanSchema: z.ZodObject<{
+    schema_version: z.ZodLiteral<1>;
+    feature_ref: z.ZodString;
+    runtime_provider: z.ZodLiteral<"deepagents">;
+    status: z.ZodEnum<{
+        ready: "ready";
+        blocked: "blocked";
+    }>;
+    fail_closed: z.ZodLiteral<true>;
+    reasons: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    canonical_authority: z.ZodObject<{
+        governance_system: z.ZodLiteral<"CodeSDD">;
+        canonical_state_path: z.ZodLiteral<".sdd/state/**">;
+        direct_state_mutation_allowed: z.ZodLiteral<false>;
+    }, z.core.$strip>;
+    legacy_input_policy: z.ZodObject<{
+        trust_model: z.ZodLiteral<"untrusted">;
+        source_attestation_required: z.ZodLiteral<true>;
+        accepted_sources: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        rejected_sources: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            reason: z.ZodString;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>;
+    routes: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        domain: z.ZodEnum<{
+            specs: "specs";
+            architecture: "architecture";
+            rules: "rules";
+            data: "data";
+            migration: "migration";
+            "legacy-analysis": "legacy-analysis";
+            screens: "screens";
+            microservices: "microservices";
+            "equivalence-validation": "equivalence-validation";
+        }>;
+        subagent_id: z.ZodString;
+        skill_ref: z.ZodString;
+        legacy_input_refs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        evidence_refs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        quality_refs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type ReversaDomain = z.infer<typeof reversaDomainSchema>;
+export type DeepAgentsReversaPlanRequest = z.infer<typeof deepAgentsReversaRequestSchema>;
+export type DeepAgentsReversaPlan = z.infer<typeof deepAgentsReversaPlanSchema>;
+export declare function planDeepAgentsReversaSubagents(request: DeepAgentsReversaPlanRequest): DeepAgentsReversaPlan;
+//# sourceMappingURL=reversa-subagents.d.ts.map