@devtrack-solution/codesdd 1.2.2 → 1.2.4-rc3

package/dist/core/sdd/services/agent-run.service.d.ts

@@ -0,0 +1,97 @@
+import { type DeepAgentsRuntimeAdapterEnvelope } from '../deepagents/runtime-factory.js';
+import { type DeepAgentRunEvidence, type DeepAgentRunPlan } from '../deepagents/evidence-mapper.js';
+import { type DeepAgentsOperationalPreflight } from '../deepagents/policy.js';
+import type { DeepAgentsRuntimeImporter } from '../deepagents/runtime-loader.js';
+import { type CapabilityInventoryItem, type CapabilityKind } from '../domain/capability-diff.js';
+import type { ChangeSafetyContract, PlannedFileChange } from '../domain/change-safety-guardrails.js';
+import type { SddStores } from '../store/sdd-stores.js';
+import { type CapabilityDiffServiceResult } from './capability-diff.service.js';
+import { type ChangeSafetyPreflightResult } from './change-safety-preflight.service.js';
+import { type SemanticIntentClassifierServiceResult } from './semantic-intent-classifier.service.js';
+declare const DEEPAGENTS_RUN_MODES: readonly ["read-only", "plan", "validate", "apply-sandbox", "apply-approved"];
+export type DeepAgentsRunMode = (typeof DEEPAGENTS_RUN_MODES)[number];
+export type DeepAgentsRunStatus = 'allowed' | 'blocked';
+export interface DeepAgentsRunRequest {
+    provider: string;
+    mode?: string;
+    objective?: string;
+    plugin_execution_path?: string;
+    plugin_flow?: string[];
+    operations?: string[];
+    write_scope?: string[];
+    planned_writes?: string[];
+    change_safety?: ChangeSafetyContract;
+    planned_file_changes?: PlannedFileChange[];
+    capability_inventory_before?: CapabilityInventoryItem[];
+    capability_inventory_after?: CapabilityInventoryItem[];
+    capability_inventory_required?: boolean;
+    capability_required_kinds?: CapabilityKind[];
+    requested_env?: string[];
+    network_domains?: string[];
+    approval_grants?: string[];
+}
+export interface DeepAgentsRunResult {
+    schema_version: 1;
+    feature_id: string;
+    provider: 'deepagents';
+    requested_provider: string;
+    mode_requested: string;
+    mode: DeepAgentsRunMode;
+    status: DeepAgentsRunStatus;
+    fail_closed: true;
+    reasons: string[];
+    evidence: {
+        run_id: string;
+        generated_at: string;
+        policy: 'deepagents-run-governance/v1';
+        direct_state_write_allowed: false;
+        plugin_execution: {
+            broker_only: true;
+            requested_path: string;
+            required_flow: string[];
+            completed_flow: string[];
+            missing_flow: string[];
+        };
+        runtime_skipped?: boolean;
+        guardrail_telemetry: {
+            contract: 'preflight-telemetry/v1';
+            decision: DeepAgentsRunStatus;
+            runtime_skipped: boolean;
+            status_by_gate: {
+                plugin_flow: 'allowed' | 'blocked';
+                change_safety?: 'allowed' | 'blocked';
+                capability_diff?: 'not_run' | 'none' | 'low' | 'medium' | 'high' | 'critical';
+                semantic_intent?: 'not_run' | 'allowed' | 'blocked';
+            };
+            risk_level?: 'none' | 'low' | 'medium' | 'high' | 'critical';
+            semantic_classification?: 'incremental' | 'refactor' | 'replacement' | 'ambiguous';
+            override_status?: 'not_required' | 'valid' | 'invalid';
+        };
+        change_safety?: ChangeSafetyPreflightResult;
+        capability_diff?: CapabilityDiffServiceResult;
+        semantic_intent?: SemanticIntentClassifierServiceResult;
+        runtime?: {
+            preflight: DeepAgentsOperationalPreflight;
+            adapter: DeepAgentsRuntimeAdapterEnvelope;
+            plan: DeepAgentRunPlan;
+            run: DeepAgentRunEvidence;
+            agent_result?: unknown;
+            fake_result?: unknown;
+            error?: string;
+        };
+    };
+}
+export interface DeepAgentsRunServiceOptions {
+    projectRoot?: string;
+    env?: NodeJS.ProcessEnv;
+    stores?: SddStores;
+    importer?: DeepAgentsRuntimeImporter;
+    skipRuntime?: boolean;
+}
+export declare class DeepAgentsRunService {
+    execute(featureId: string, request: DeepAgentsRunRequest, options?: DeepAgentsRunServiceOptions): Promise<DeepAgentsRunResult>;
+    private executeRuntimePath;
+    private invokeReadyRuntime;
+}
+export {};
+//# sourceMappingURL=agent-run.service.d.ts.map

package/dist/core/sdd/services/agent-run.service.js

@@ -0,0 +1,261 @@
+import { createDeepAgentsRuntimeAdapter, } from '../deepagents/runtime-factory.js';
+import { createCodeSddDeepAgentsRuntimeTools } from '../deepagents/codesdd-tools.js';
+import { mapDeepAgentsRunEvidence, mapDeepAgentsRunPlan, } from '../deepagents/evidence-mapper.js';
+import { buildDeepAgentsOperationalPreflight, createDeepAgentsPolicySnapshot, } from '../deepagents/policy.js';
+import { CAPABILITY_KINDS, } from '../domain/capability-diff.js';
+import { CapabilityDiffService, } from './capability-diff.service.js';
+import { ChangeSafetyPreflightService, } from './change-safety-preflight.service.js';
+import { SemanticIntentClassifierService, } from './semantic-intent-classifier.service.js';
+const FEATURE_REF_PATTERN = /^FEAT-\d{4}$/;
+const DEEPAGENTS_RUN_MODES = [
+    'read-only',
+    'plan',
+    'validate',
+    'apply-sandbox',
+    'apply-approved',
+];
+const DEEPAGENTS_MUTATION_MODES = new Set(['apply-sandbox', 'apply-approved']);
+const REQUIRED_PLUGIN_BROKER_FLOW_BASE = [
+    'plugin-inspect',
+    'plugin-plan',
+    'plugin-dry-run',
+    'policy-evaluation',
+    'artifact-manifest',
+    'evidence-manifest',
+    'validation-manifest',
+    'rollback-manifest',
+];
+const DEEPAGENTS_PROVIDER = 'deepagents';
+export class DeepAgentsRunService {
+    async execute(featureId, request, options = {}) {
+        const generatedAt = new Date().toISOString();
+        const requestedProvider = request.provider.trim().toLowerCase();
+        const modeRequested = request.mode?.trim().toLowerCase() || 'plan';
+        const pluginExecutionPath = (request.plugin_execution_path || 'broker').trim().toLowerCase();
+        const completedPluginFlow = normalizeFlow(request.plugin_flow ?? []);
+        const operations = resolveOperations(request.operations, modeRequested);
+        const reasons = [];
+        const runId = `deepagents-${featureId}-${Date.now()}`;
+        if (!FEATURE_REF_PATTERN.test(featureId)) {
+            reasons.push('Feature ref must match FEAT-####.');
+        }
+        if (requestedProvider !== DEEPAGENTS_PROVIDER) {
+            reasons.push('Provider is not authorized. FEAT-0243 only allows --provider deepagents.');
+        }
+        const supportedModes = DEEPAGENTS_RUN_MODES;
+        const mode = supportedModes.includes(modeRequested)
+            ? modeRequested
+            : 'read-only';
+        if (!supportedModes.includes(modeRequested)) {
+            reasons.push(`Mode '${modeRequested}' is invalid. Allowed modes: ${DEEPAGENTS_RUN_MODES.join(', ')}.`);
+        }
+        const requiredPluginFlow = resolveRequiredPluginFlow(mode);
+        const missingPluginFlow = requiredPluginFlow.filter((step) => !completedPluginFlow.includes(step));
+        if (DEEPAGENTS_MUTATION_MODES.has(mode)) {
+            if (pluginExecutionPath !== 'broker') {
+                reasons.push('Direct plugin execution is forbidden. DeepAgents must use plugin broker envelopes only.');
+            }
+            if (missingPluginFlow.length > 0) {
+                reasons.push(`Mutation mode '${mode}' requires broker evidence flow: ${requiredPluginFlow.join(', ')}. Missing: ${missingPluginFlow.join(', ')}.`);
+            }
+        }
+        const plannedFileChanges = resolvePlannedFileChanges(request);
+        const changeSafety = DEEPAGENTS_MUTATION_MODES.has(mode)
+            ? new ChangeSafetyPreflightService().execute({
+                feature_id: featureId,
+                change_safety: request.change_safety,
+                planned_changes: plannedFileChanges,
+            })
+            : undefined;
+        if (changeSafety?.status === 'blocked') {
+            reasons.push(...changeSafety.violations.map((violation) => violation.message));
+        }
+        const capabilityDiff = resolveCapabilityDiff(request, changeSafety, plannedFileChanges);
+        if (DEEPAGENTS_MUTATION_MODES.has(mode) && capabilityDiff?.risk.level === 'critical') {
+            reasons.push(`Capability diff deterministic risk is critical: ${capabilityDiff.risk.signals.map((signal) => signal.message).join(' ')}`);
+        }
+        const semanticIntent = capabilityDiff
+            ? new SemanticIntentClassifierService().execute({
+                objective: request.objective,
+                declared_operation: changeSafety?.operation,
+                capability_diff: capabilityDiff.diff,
+                deterministic_risk: capabilityDiff.risk,
+            })
+            : undefined;
+        if (semanticIntent?.status === 'blocked') {
+            reasons.push(...semanticIntent.reasons);
+        }
+        const runtime = reasons.length === 0 && options.skipRuntime !== true
+            ? await this.executeRuntimePath(featureId, mode, runId, request, operations, options)
+            : undefined;
+        if (runtime?.adapter.status === 'blocked' && runtime.adapter.runtime !== 'disabled') {
+            reasons.push(...runtime.adapter.reasons);
+        }
+        if (runtime?.run.status === 'failed' && runtime.error) {
+            reasons.push(`DeepAgents runtime invocation failed: ${runtime.error}`);
+        }
+        const status = reasons.length === 0 ? 'allowed' : 'blocked';
+        return {
+            schema_version: 1,
+            feature_id: featureId,
+            provider: DEEPAGENTS_PROVIDER,
+            requested_provider: requestedProvider,
+            mode_requested: modeRequested,
+            mode,
+            status,
+            fail_closed: true,
+            reasons,
+            evidence: {
+                run_id: runId,
+                generated_at: generatedAt,
+                policy: 'deepagents-run-governance/v1',
+                direct_state_write_allowed: false,
+                plugin_execution: {
+                    broker_only: true,
+                    requested_path: pluginExecutionPath,
+                    required_flow: requiredPluginFlow,
+                    completed_flow: completedPluginFlow,
+                    missing_flow: missingPluginFlow,
+                },
+                runtime_skipped: options.skipRuntime === true,
+                guardrail_telemetry: {
+                    contract: 'preflight-telemetry/v1',
+                    decision: status,
+                    runtime_skipped: options.skipRuntime === true,
+                    status_by_gate: {
+                        plugin_flow: missingPluginFlow.length === 0 && pluginExecutionPath === 'broker' ? 'allowed' : 'blocked',
+                        change_safety: changeSafety?.status,
+                        capability_diff: capabilityDiff?.risk.level ?? 'not_run',
+                        semantic_intent: semanticIntent?.status ?? 'not_run',
+                    },
+                    risk_level: capabilityDiff?.risk.level,
+                    semantic_classification: semanticIntent?.classification,
+                    override_status: changeSafety?.governed_override.status,
+                },
+                change_safety: changeSafety,
+                capability_diff: capabilityDiff,
+                semantic_intent: semanticIntent,
+                runtime,
+            },
+        };
+    }
+    async executeRuntimePath(featureId, mode, runId, request, operations, options) {
+        const snapshot = createDeepAgentsPolicySnapshot(options.env);
+        const preflight = buildDeepAgentsOperationalPreflight(snapshot, options.env);
+        const tools = options.projectRoot && options.stores
+            ? createCodeSddDeepAgentsRuntimeTools(options.stores, options.projectRoot, {
+                profile: mode === 'apply-sandbox' || mode === 'apply-approved' ? 'all' : 'read-diagnostic',
+            })
+            : [];
+        const adapter = await createDeepAgentsRuntimeAdapter({
+            featureRef: featureId,
+            objective: `Run CodeSDD governed agent mode ${mode} for ${featureId}.`,
+            mode,
+            runId,
+            projectRoot: options.projectRoot,
+            tools,
+            operations,
+            writeScope: normalizeList(request.write_scope ?? []),
+            plannedWrites: normalizeList(request.planned_writes ?? []),
+            requestedEnv: normalizeList(request.requested_env ?? []),
+            networkDomains: normalizeList(request.network_domains ?? []),
+            approvalGrants: normalizeFlow(request.approval_grants ?? []),
+        }, { env: options.env, importer: options.importer, snapshot });
+        const envelope = adapter.describe();
+        const plan = mapDeepAgentsRunPlan({ adapter: envelope });
+        const invocation = envelope.status === 'ready'
+            ? await this.invokeReadyRuntime(adapter, mode, featureId)
+            : { result: undefined, error: undefined };
+        const run = mapDeepAgentsRunEvidence({
+            adapter: envelope,
+            status: invocation.error
+                ? 'failed'
+                : envelope.status === 'ready'
+                    ? 'completed'
+                    : 'blocked',
+            planRef: `${runId}:plan`,
+        });
+        return {
+            preflight,
+            adapter: envelope,
+            plan,
+            run,
+            agent_result: invocation.result,
+            fake_result: envelope.runtime === 'fake' ? invocation.result : undefined,
+            error: invocation.error,
+        };
+    }
+    async invokeReadyRuntime(adapter, mode, featureId) {
+        try {
+            const agent = await adapter.createAgent();
+            const result = await agent.invoke({
+                messages: [
+                    {
+                        role: 'user',
+                        content: `Run ${mode} for ${featureId} under CodeSDD governance.`,
+                    },
+                ],
+            });
+            return { result };
+        }
+        catch (error) {
+            return { error: error instanceof Error ? error.message : String(error) };
+        }
+    }
+}
+function resolveRequiredPluginFlow(mode) {
+    if (mode === 'apply-sandbox') {
+        return [...REQUIRED_PLUGIN_BROKER_FLOW_BASE, 'apply-sandbox'];
+    }
+    if (mode === 'apply-approved') {
+        return [...REQUIRED_PLUGIN_BROKER_FLOW_BASE, 'apply-approved'];
+    }
+    return [];
+}
+function normalizeFlow(flow) {
+    return [...new Set(flow.map((step) => step.trim().toLowerCase()).filter((step) => step.length > 0))].sort();
+}
+function normalizeList(values) {
+    return [...new Set(values.map((value) => value.trim()).filter((value) => value.length > 0))].sort();
+}
+function resolvePlannedFileChanges(request) {
+    if (request.planned_file_changes) {
+        return request.planned_file_changes;
+    }
+    return normalizeList(request.planned_writes ?? []).map((plannedWrite) => ({
+        path: plannedWrite,
+        operation: 'modify',
+    }));
+}
+function resolveCapabilityDiff(request, changeSafety, plannedChanges) {
+    const hasInventory = Boolean(request.capability_inventory_before || request.capability_inventory_after);
+    if (!hasInventory && !request.capability_inventory_required) {
+        return undefined;
+    }
+    return new CapabilityDiffService().execute({
+        before: request.capability_inventory_before ?? [],
+        after: request.capability_inventory_after ?? [],
+        change_safety: changeSafety,
+        planned_changes: plannedChanges,
+        required_kinds: request.capability_inventory_required
+            ? request.capability_required_kinds ?? [...CAPABILITY_KINDS]
+            : request.capability_required_kinds,
+    });
+}
+function resolveOperations(operations, modeRequested) {
+    const normalized = normalizeFlow(operations ?? []);
+    const candidates = normalized.length > 0
+        ? normalized
+        : modeRequested === 'apply-sandbox' || modeRequested === 'apply-approved'
+            ? ['plugin-apply', 'write']
+            : ['read'];
+    return candidates.filter((operation) => operation === 'read' ||
+        operation === 'write' ||
+        operation === 'execute' ||
+        operation === 'network' ||
+        operation === 'plugin-apply' ||
+        operation === 'finalize' ||
+        operation === 'dependency-change' ||
+        operation === 'process-spawn');
+}
+//# sourceMappingURL=agent-run.service.js.map

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

@@ -54,7 +54,8 @@ export class BreakdownService {
                 const id = await allocateEntityId(paths, 'FEAT');
                 syncCounterFromId(snapshot.discoveryIndex, id);
                 const recommended = resolveRoutedSkills(snapshot, shape.touches);
-                const item = buildBacklogItem(id, title, 'radar', radar.id, options?.scale || 'STANDARD', recommended, {
+                const originType = radar.type === 'RAD' ? 'radar' : 'epic';
+                const item = buildBacklogItem(id, title, originType, radar.id, options?.scale || 'STANDARD', recommended, {
                     parallelGroup,
                     executionKind: shape.executionKind,
                     planningMode: shape.planningMode,

package/dist/core/sdd/services/capability-diff.service.d.ts

@@ -0,0 +1,18 @@
+import { type CapabilityDiffReport, type CapabilityInventory, type CapabilityInventoryItem, type CapabilityKind, type CapabilityRiskInput, type CapabilityRiskReport } from '../domain/capability-diff.js';
+export interface CapabilityDiffServiceRequest extends Omit<CapabilityRiskInput, 'diff'> {
+    before: CapabilityInventoryItem[] | CapabilityInventory;
+    after: CapabilityInventoryItem[] | CapabilityInventory;
+    required_kinds?: CapabilityKind[];
+}
+export interface CapabilityDiffServiceResult {
+    schema_version: 1;
+    contract: 'capability-diff-service-result/v1';
+    before: CapabilityInventory;
+    after: CapabilityInventory;
+    diff: CapabilityDiffReport;
+    risk: CapabilityRiskReport;
+}
+export declare class CapabilityDiffService {
+    execute(request: CapabilityDiffServiceRequest): CapabilityDiffServiceResult;
+}
+//# sourceMappingURL=capability-diff.service.d.ts.map

package/dist/core/sdd/services/capability-diff.service.js

@@ -0,0 +1,26 @@
+import { buildCapabilityInventory, diffCapabilityInventories, scoreCapabilityDiffRisk, } from '../domain/capability-diff.js';
+export class CapabilityDiffService {
+    execute(request) {
+        const before = normalizeInventoryRequest(request.before);
+        const after = normalizeInventoryRequest(request.after);
+        const diff = diffCapabilityInventories(before, after);
+        const risk = scoreCapabilityDiffRisk({
+            diff,
+            change_safety: request.change_safety,
+            planned_changes: request.planned_changes,
+            required_kinds: request.required_kinds,
+        });
+        return {
+            schema_version: 1,
+            contract: 'capability-diff-service-result/v1',
+            before,
+            after,
+            diff,
+            risk,
+        };
+    }
+}
+function normalizeInventoryRequest(input) {
+    return Array.isArray(input) ? buildCapabilityInventory(input) : input;
+}
+//# sourceMappingURL=capability-diff.service.js.map

package/dist/core/sdd/services/change-safety-preflight.service.d.ts

@@ -0,0 +1,17 @@
+import { type ChangeSafetyContract, type ChangeSafetyEvaluation, type PlannedFileChange } from '../domain/change-safety-guardrails.js';
+export interface ChangeSafetyPreflightRequest {
+    feature_id: string;
+    change_safety?: ChangeSafetyContract;
+    planned_changes?: PlannedFileChange[];
+}
+export interface ChangeSafetyPreflightResult extends ChangeSafetyEvaluation {
+    schema_version: 1;
+    contract: 'change-safety-preflight/v1';
+    feature_id: string;
+    fail_closed: true;
+    phase: 'mechanical';
+}
+export declare class ChangeSafetyPreflightService {
+    execute(request: ChangeSafetyPreflightRequest): ChangeSafetyPreflightResult;
+}
+//# sourceMappingURL=change-safety-preflight.service.d.ts.map

package/dist/core/sdd/services/change-safety-preflight.service.js

@@ -0,0 +1,17 @@
+import { evaluateChangeSafety, } from '../domain/change-safety-guardrails.js';
+export class ChangeSafetyPreflightService {
+    execute(request) {
+        const evaluation = evaluateChangeSafety(request.change_safety ?? {}, request.planned_changes ?? [], {
+            feature_id: request.feature_id,
+        });
+        return {
+            schema_version: 1,
+            contract: 'change-safety-preflight/v1',
+            feature_id: request.feature_id,
+            fail_closed: true,
+            phase: 'mechanical',
+            ...evaluation,
+        };
+    }
+}
+//# sourceMappingURL=change-safety-preflight.service.js.map