@devtrack-solution/codesdd 1.2.3 → 1.2.4

package/dist/core/sdd/sdk-agent-plugin-quality-gates.d.ts

@@ -0,0 +1,150 @@
+import { z } from 'zod';
+export declare const sdkAgentPluginCoverageScopeSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    metrics: z.ZodObject<{
+        statements: z.ZodOptional<z.ZodNumber>;
+        branches: z.ZodOptional<z.ZodNumber>;
+        functions: z.ZodOptional<z.ZodNumber>;
+        lines: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    target: z.ZodOptional<z.ZodObject<{
+        statements: z.ZodOptional<z.ZodNumber>;
+        branches: z.ZodOptional<z.ZodNumber>;
+        functions: z.ZodOptional<z.ZodNumber>;
+        lines: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const sdkAgentPluginQualityGateInputSchema: z.ZodObject<{
+    schema_version: z.ZodDefault<z.ZodLiteral<1>>;
+    generated_at: z.ZodString;
+    feature_ref: z.ZodOptional<z.ZodString>;
+    package_governance: z.ZodOptional<z.ZodUnknown>;
+    language_runtime: z.ZodOptional<z.ZodUnknown>;
+    artifact_map: z.ZodOptional<z.ZodUnknown>;
+    agent_runtime_plans: z.ZodDefault<z.ZodArray<z.ZodUnknown>>;
+    plugin_compliance_indexes: z.ZodDefault<z.ZodArray<z.ZodUnknown>>;
+    coverage_scopes: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        metrics: z.ZodObject<{
+            statements: z.ZodOptional<z.ZodNumber>;
+            branches: z.ZodOptional<z.ZodNumber>;
+            functions: z.ZodOptional<z.ZodNumber>;
+            lines: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>;
+        target: z.ZodOptional<z.ZodObject<{
+            statements: z.ZodOptional<z.ZodNumber>;
+            branches: z.ZodOptional<z.ZodNumber>;
+            functions: z.ZodOptional<z.ZodNumber>;
+            lines: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+    required_agent_providers: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        opencode: "opencode";
+        codex: "codex";
+        deepagents: "deepagents";
+    }>>>;
+    coverage_target: z.ZodDefault<z.ZodObject<{
+        statements: z.ZodOptional<z.ZodNumber>;
+        branches: z.ZodOptional<z.ZodNumber>;
+        functions: z.ZodOptional<z.ZodNumber>;
+        lines: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const sdkAgentPluginQualityGateIssueSchema: z.ZodObject<{
+    code: z.ZodString;
+    severity: z.ZodEnum<{
+        fail: "fail";
+        warn: "warn";
+    }>;
+    message: z.ZodString;
+    remediation: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const sdkAgentPluginQualityGateSchema: z.ZodObject<{
+    id: z.ZodString;
+    domain: z.ZodEnum<{
+        coverage: "coverage";
+        "agent-runtime": "agent-runtime";
+        "plugin-sdk": "plugin-sdk";
+        "plugin-compliance": "plugin-compliance";
+        "foundation-architecture": "foundation-architecture";
+    }>;
+    status: z.ZodEnum<{
+        pass: "pass";
+        fail: "fail";
+        warn: "warn";
+    }>;
+    severity: z.ZodEnum<{
+        info: "info";
+        fail: "fail";
+        warn: "warn";
+    }>;
+    evidence: z.ZodString;
+    issues: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        severity: z.ZodEnum<{
+            fail: "fail";
+            warn: "warn";
+        }>;
+        message: z.ZodString;
+        remediation: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export declare const sdkAgentPluginQualityGateReportSchema: z.ZodObject<{
+    schema_version: z.ZodLiteral<1>;
+    generated_at: z.ZodString;
+    feature_ref: z.ZodOptional<z.ZodString>;
+    decision: z.ZodEnum<{
+        warning: "warning";
+        failed: "failed";
+        passed: "passed";
+    }>;
+    summary: z.ZodObject<{
+        total: z.ZodNumber;
+        passed: z.ZodNumber;
+        warned: z.ZodNumber;
+        failed: z.ZodNumber;
+    }, z.core.$strip>;
+    gates: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        domain: z.ZodEnum<{
+            coverage: "coverage";
+            "agent-runtime": "agent-runtime";
+            "plugin-sdk": "plugin-sdk";
+            "plugin-compliance": "plugin-compliance";
+            "foundation-architecture": "foundation-architecture";
+        }>;
+        status: z.ZodEnum<{
+            pass: "pass";
+            fail: "fail";
+            warn: "warn";
+        }>;
+        severity: z.ZodEnum<{
+            info: "info";
+            fail: "fail";
+            warn: "warn";
+        }>;
+        evidence: z.ZodString;
+        issues: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            code: z.ZodString;
+            severity: z.ZodEnum<{
+                fail: "fail";
+                warn: "warn";
+            }>;
+            message: z.ZodString;
+            remediation: z.ZodString;
+            path: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SdkAgentPluginCoverageScope = z.infer<typeof sdkAgentPluginCoverageScopeSchema>;
+export type SdkAgentPluginQualityGateInput = z.input<typeof sdkAgentPluginQualityGateInputSchema>;
+export type SdkAgentPluginQualityGateIssue = z.infer<typeof sdkAgentPluginQualityGateIssueSchema>;
+export type SdkAgentPluginQualityGate = z.infer<typeof sdkAgentPluginQualityGateSchema>;
+export type SdkAgentPluginQualityGateReport = z.infer<typeof sdkAgentPluginQualityGateReportSchema>;
+export declare function buildSdkAgentPluginQualityGateReport(value: SdkAgentPluginQualityGateInput): SdkAgentPluginQualityGateReport;
+export declare function buildSdkAgentPluginQualityGateJsonSchemas(): Record<string, unknown>;
+//# sourceMappingURL=sdk-agent-plugin-quality-gates.d.ts.map

package/dist/core/sdd/sdk-agent-plugin-quality-gates.js

@@ -0,0 +1,258 @@
+import { toJSONSchema, z } from 'zod';
+import { agentRuntimeCommandPlanSchema, agentRuntimeProviderSchema, } from './agent-runtime-contract.js';
+import { validateFoundationArtifactMapArchitecture } from './foundation-artifact-map-validator.js';
+import { pluginComplianceIndexSchema } from './plugin-evidence.js';
+import { pluginArtifactMapSchema, pluginLanguageRuntimeSchema, pluginPackageGovernanceSchema, } from './plugin-sdk-contract.js';
+const JSON_SCHEMA_DRAFT = 'https://json-schema.org/draft/2020-12/schema';
+const FEATURE_REF_PATTERN = /^FEAT-\d{4}$/;
+const ISSUE_CODE_PATTERN = /^[A-Z][A-Z0-9_]*$/;
+const coverageMetricsSchema = z
+    .object({
+    statements: z.number().min(0).max(100).optional(),
+    branches: z.number().min(0).max(100).optional(),
+    functions: z.number().min(0).max(100).optional(),
+    lines: z.number().min(0).max(100).optional(),
+})
+    .refine((metrics) => Object.keys(metrics).length > 0, {
+    message: 'At least one coverage metric is required.',
+});
+export const sdkAgentPluginCoverageScopeSchema = z.object({
+    id: z.string().min(1),
+    label: z.string().min(1),
+    metrics: coverageMetricsSchema,
+    target: coverageMetricsSchema.optional(),
+});
+export const sdkAgentPluginQualityGateInputSchema = z.object({
+    schema_version: z.literal(1).default(1),
+    generated_at: z.string().datetime(),
+    feature_ref: z.string().regex(FEATURE_REF_PATTERN).optional(),
+    package_governance: z.unknown().optional(),
+    language_runtime: z.unknown().optional(),
+    artifact_map: z.unknown().optional(),
+    agent_runtime_plans: z.array(z.unknown()).default([]),
+    plugin_compliance_indexes: z.array(z.unknown()).default([]),
+    coverage_scopes: z.array(sdkAgentPluginCoverageScopeSchema).default([]),
+    required_agent_providers: z.array(agentRuntimeProviderSchema).default(['deepagents', 'codex', 'opencode']),
+    coverage_target: coverageMetricsSchema.default({
+        statements: 95,
+        branches: 85,
+        functions: 95,
+        lines: 95,
+    }),
+});
+export const sdkAgentPluginQualityGateIssueSchema = z.object({
+    code: z.string().regex(ISSUE_CODE_PATTERN),
+    severity: z.enum(['warn', 'fail']),
+    message: z.string().min(1),
+    remediation: z.string().min(1),
+    path: z.string().min(1).optional(),
+});
+export const sdkAgentPluginQualityGateSchema = z.object({
+    id: z.string().min(1),
+    domain: z.enum([
+        'plugin-sdk',
+        'agent-runtime',
+        'plugin-compliance',
+        'foundation-architecture',
+        'coverage',
+    ]),
+    status: z.enum(['pass', 'warn', 'fail']),
+    severity: z.enum(['info', 'warn', 'fail']),
+    evidence: z.string().min(1),
+    issues: z.array(sdkAgentPluginQualityGateIssueSchema).default([]),
+});
+export const sdkAgentPluginQualityGateReportSchema = z.object({
+    schema_version: z.literal(1),
+    generated_at: z.string().datetime(),
+    feature_ref: z.string().regex(FEATURE_REF_PATTERN).optional(),
+    decision: z.enum(['passed', 'warning', 'failed']),
+    summary: z.object({
+        total: z.number().int().nonnegative(),
+        passed: z.number().int().nonnegative(),
+        warned: z.number().int().nonnegative(),
+        failed: z.number().int().nonnegative(),
+    }),
+    gates: z.array(sdkAgentPluginQualityGateSchema).min(1),
+});
+const COVERAGE_METRICS = ['statements', 'branches', 'functions', 'lines'];
+export function buildSdkAgentPluginQualityGateReport(value) {
+    const input = sdkAgentPluginQualityGateInputSchema.parse(value);
+    const gates = [
+        packageGovernanceGate(input.package_governance),
+        languageRuntimeGate(input.language_runtime),
+        artifactMapGate(input.artifact_map),
+        agentRuntimeGate(input.agent_runtime_plans, input.required_agent_providers),
+        pluginComplianceGate(input.plugin_compliance_indexes),
+        coverageGate(input.coverage_scopes, input.coverage_target),
+    ];
+    const summary = {
+        total: gates.length,
+        passed: gates.filter((gate) => gate.status === 'pass').length,
+        warned: gates.filter((gate) => gate.status === 'warn').length,
+        failed: gates.filter((gate) => gate.status === 'fail').length,
+    };
+    return sdkAgentPluginQualityGateReportSchema.parse({
+        schema_version: 1,
+        generated_at: input.generated_at,
+        feature_ref: input.feature_ref,
+        decision: summary.failed > 0 ? 'failed' : summary.warned > 0 ? 'warning' : 'passed',
+        summary,
+        gates,
+    });
+}
+export function buildSdkAgentPluginQualityGateJsonSchemas() {
+    return {
+        'sdk-agent-plugin-quality-gate-input.yaml': normalizeJsonSchema(sdkAgentPluginQualityGateInputSchema, 'CodeSDD SDK Agent Plugin Quality Gate Input', 'Input contract for validating plugin SDK, agent runtime, plugin compliance, Foundation artifact map, and coverage evidence together.'),
+        'sdk-agent-plugin-quality-gate-report.yaml': normalizeJsonSchema(sdkAgentPluginQualityGateReportSchema, 'CodeSDD SDK Agent Plugin Quality Gate Report', 'Machine-readable quality gate report for SDK contracts, agent runtimes, plugin compliance indexes, Foundation artifact maps, and coverage scopes.'),
+    };
+}
+function packageGovernanceGate(value) {
+    if (value === undefined) {
+        return gate('plugin-sdk.package-governance', 'plugin-sdk', [
+            issue('SDK_PACKAGE_GOVERNANCE_MISSING', 'fail', 'Plugin package governance evidence is missing.', 'Attach package_governance from @devtrack-solution/codesdd-plugin-sdk before accepting the plugin package.'),
+        ], 'No package governance evidence was provided.');
+    }
+    const parsed = pluginPackageGovernanceSchema.safeParse(value);
+    if (!parsed.success) {
+        return gate('plugin-sdk.package-governance', 'plugin-sdk', [
+            issue('SDK_PACKAGE_GOVERNANCE_INVALID', 'fail', `Package governance failed validation: ${formatIssues(parsed.error.issues)}`, 'Use the @devtrack-solution/codesdd-plugin-* package prefix, SemVer, package kind, and required discovery keywords.'),
+        ], 'Package governance evidence failed SDK validation.');
+    }
+    return gate('plugin-sdk.package-governance', 'plugin-sdk', [], `Package governance passed for ${parsed.data.package_name}.`);
+}
+function languageRuntimeGate(value) {
+    if (value === undefined) {
+        return gate('plugin-sdk.language-runtime', 'plugin-sdk', [
+            issue('SDK_LANGUAGE_RUNTIME_MISSING', 'fail', 'Plugin language runtime evidence is missing.', 'Declare language_runtime with bridge and transport metadata before planning standalone plugin execution.'),
+        ], 'No language runtime evidence was provided.');
+    }
+    const parsed = pluginLanguageRuntimeSchema.safeParse(value);
+    if (!parsed.success) {
+        return gate('plugin-sdk.language-runtime', 'plugin-sdk', [
+            issue('SDK_LANGUAGE_RUNTIME_INVALID', 'fail', `Language runtime failed validation: ${formatIssues(parsed.error.issues)}`, 'Use a valid bridge for the plugin language and declare commands for process-backed runtimes.'),
+        ], 'Language runtime evidence failed SDK validation.');
+    }
+    return gate('plugin-sdk.language-runtime', 'plugin-sdk', [], `Language runtime passed for ${parsed.data.language} through ${parsed.data.bridge}.`);
+}
+function artifactMapGate(value) {
+    if (value === undefined) {
+        return gate('foundation.artifact-map', 'foundation-architecture', [
+            issue('SDK_ARTIFACT_MAP_MISSING', 'fail', 'Plugin artifact map evidence is missing.', 'Attach a typed artifact map before accepting generated or modified project files.'),
+        ], 'No artifact map evidence was provided.');
+    }
+    const sdkParsed = pluginArtifactMapSchema.safeParse(value);
+    if (!sdkParsed.success) {
+        return gate('foundation.artifact-map', 'foundation-architecture', [
+            issue('SDK_ARTIFACT_MAP_INVALID', 'fail', `Artifact map failed SDK validation: ${formatIssues(sdkParsed.error.issues)}`, 'Validate artifact maps with the CodeSDD plugin SDK before Foundation architecture checks run.'),
+        ], 'Artifact map failed SDK schema validation.');
+    }
+    const foundation = validateFoundationArtifactMapArchitecture(sdkParsed.data);
+    const issues = foundation.findings.map((finding) => issue(finding.code, 'warn', finding.message, finding.remediation, finding.path));
+    return gate('foundation.artifact-map', 'foundation-architecture', issues, `Artifact map contains ${sdkParsed.data.artifacts.length} artifacts; Foundation architecture status is ${foundation.status}.`);
+}
+function agentRuntimeGate(values, requiredProviders) {
+    const plansByProvider = new Map();
+    const issues = [];
+    values.forEach((value, index) => {
+        const parsed = agentRuntimeCommandPlanSchema.safeParse(value);
+        if (!parsed.success) {
+            issues.push(issue('AGENT_RUNTIME_PLAN_INVALID', 'fail', `Agent runtime plan at index ${index} failed validation: ${formatIssues(parsed.error.issues)}`, 'Build agent execution through the Agent Runtime v2 command-plan contract.', `agent_runtime_plans.${index}`));
+            return;
+        }
+        const plan = parsed.data;
+        plansByProvider.set(plan.provider, (plansByProvider.get(plan.provider) ?? 0) + 1);
+        if (plan.status === 'blocked') {
+            issues.push(issue('AGENT_RUNTIME_PLAN_BLOCKED', 'fail', `${plan.provider} plan is blocked: ${plan.reasons.join('; ') || 'no reason provided'}`, 'Resolve runtime policy findings or keep the agent outside executable apply flows.', `agent_runtime_plans.${index}`));
+        }
+    });
+    for (const provider of requiredProviders) {
+        if (!plansByProvider.has(provider)) {
+            issues.push(issue('AGENT_RUNTIME_PROVIDER_MISSING', 'fail', `Required agent runtime provider ${provider} has no command plan.`, 'Attach command plans for DeepAgents, Codex exec, and OpenCode run before closing agent-runtime coverage.', provider));
+        }
+    }
+    return gate('agent-runtime.v2-command-plans', 'agent-runtime', issues, `Validated ${values.length} agent runtime plans across ${plansByProvider.size} providers.`);
+}
+function pluginComplianceGate(values) {
+    const issues = [];
+    if (values.length === 0) {
+        issues.push(issue('PLUGIN_COMPLIANCE_INDEX_MISSING', 'fail', 'No plugin compliance index was attached.', 'Attach at least one compliance index generated from plugin evidence before accepting plugin quality gates.'));
+    }
+    values.forEach((value, index) => {
+        const parsed = pluginComplianceIndexSchema.safeParse(value);
+        if (!parsed.success) {
+            issues.push(issue('PLUGIN_COMPLIANCE_INDEX_INVALID', 'fail', `Plugin compliance index at index ${index} failed validation: ${formatIssues(parsed.error.issues)}`, 'Build compliance indexes through the plugin evidence contract.', `plugin_compliance_indexes.${index}`));
+            return;
+        }
+        if (parsed.data.decision === 'non-compliant') {
+            issues.push(issue('PLUGIN_COMPLIANCE_NON_COMPLIANT', 'fail', `${parsed.data.plugin_ref.id}@${parsed.data.plugin_ref.version} is non-compliant with score ${parsed.data.score}.`, 'Resolve failing compliance criteria before enabling plugin execution.', `plugin_compliance_indexes.${index}`));
+        }
+        else if (parsed.data.decision === 'warning') {
+            issues.push(issue('PLUGIN_COMPLIANCE_WARNING', 'warn', `${parsed.data.plugin_ref.id}@${parsed.data.plugin_ref.version} has warning compliance with score ${parsed.data.score}.`, 'Record the accepted residual risk or improve plugin evidence before apply modes.', `plugin_compliance_indexes.${index}`));
+        }
+    });
+    return gate('plugin-compliance.indexes', 'plugin-compliance', issues, `Validated ${values.length} plugin compliance indexes.`);
+}
+function coverageGate(scopes, defaultTarget) {
+    const issues = [];
+    if (scopes.length === 0) {
+        issues.push(issue('COVERAGE_SCOPE_MISSING', 'fail', 'No coverage scope evidence was attached.', 'Attach coverage metrics for touched SDK, agent runtime, and plugin modules.'));
+    }
+    for (const scope of scopes) {
+        const target = { ...defaultTarget, ...scope.target };
+        for (const metric of COVERAGE_METRICS) {
+            const targetValue = target[metric];
+            if (targetValue === undefined)
+                continue;
+            const actual = scope.metrics[metric];
+            if (actual === undefined) {
+                issues.push(issue('COVERAGE_METRIC_MISSING', 'fail', `Coverage scope ${scope.id} is missing ${metric} coverage.`, `Record ${metric} coverage or remove ${metric} from the scope target.`, scope.id));
+            }
+            else if (actual < targetValue) {
+                issues.push(issue('COVERAGE_TARGET_MISSED', 'fail', `Coverage scope ${scope.id} has ${metric} ${formatPercent(actual)}, below target ${formatPercent(targetValue)}.`, 'Add tests for the touched contract or record a formal CodeSDD exception with compensating controls.', scope.id));
+            }
+        }
+    }
+    return gate('coverage.touched-contracts', 'coverage', issues, `Validated ${scopes.length} coverage scopes against touched-contract targets.`);
+}
+function gate(id, domain, issues, evidence) {
+    const status = issues.some((item) => item.severity === 'fail')
+        ? 'fail'
+        : issues.length > 0
+            ? 'warn'
+            : 'pass';
+    return sdkAgentPluginQualityGateSchema.parse({
+        id,
+        domain,
+        status,
+        severity: status === 'pass' ? 'info' : status,
+        evidence,
+        issues,
+    });
+}
+function issue(code, severity, message, remediation, path) {
+    return sdkAgentPluginQualityGateIssueSchema.parse({
+        code,
+        severity,
+        message,
+        remediation,
+        path,
+    });
+}
+function normalizeJsonSchema(schema, title, description) {
+    return {
+        ...toJSONSchema(schema),
+        $schema: JSON_SCHEMA_DRAFT,
+        title,
+        description,
+    };
+}
+function formatIssues(issues) {
+    return issues.map((item) => {
+        const issuePath = item.path.length > 0 ? item.path.join('.') : '<root>';
+        return `${issuePath}: ${item.message}`;
+    }).join('; ');
+}
+function formatPercent(value) {
+    return `${value.toFixed(2)} percent`;
+}
+//# sourceMappingURL=sdk-agent-plugin-quality-gates.js.map

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

@@ -2,18 +2,30 @@ import { type DeepAgentsRuntimeAdapterEnvelope } from '../deepagents/runtime-fac
 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[];
@@ -40,6 +52,24 @@ export interface DeepAgentsRunResult {
             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;
@@ -51,13 +81,15 @@ export interface DeepAgentsRunResult {
         };
     };
 }
+export interface DeepAgentsRunServiceOptions {
+    projectRoot?: string;
+    env?: NodeJS.ProcessEnv;
+    stores?: SddStores;
+    importer?: DeepAgentsRuntimeImporter;
+    skipRuntime?: boolean;
+}
 export declare class DeepAgentsRunService {
-    execute(featureId: string, request: DeepAgentsRunRequest, options?: {
-        projectRoot?: string;
-        env?: NodeJS.ProcessEnv;
-        stores?: SddStores;
-        importer?: DeepAgentsRuntimeImporter;
-    }): Promise<DeepAgentsRunResult>;
+    execute(featureId: string, request: DeepAgentsRunRequest, options?: DeepAgentsRunServiceOptions): Promise<DeepAgentsRunResult>;
     private executeRuntimePath;
     private invokeReadyRuntime;
 }

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

@@ -2,6 +2,10 @@ import { createDeepAgentsRuntimeAdapter, } from '../deepagents/runtime-factory.j
 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',
@@ -55,7 +59,33 @@ export class DeepAgentsRunService {
                 reasons.push(`Mutation mode '${mode}' requires broker evidence flow: ${requiredPluginFlow.join(', ')}. Missing: ${missingPluginFlow.join(', ')}.`);
             }
         }
-        const runtime = reasons.length === 0
+        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') {
@@ -87,6 +117,24 @@ export class DeepAgentsRunService {
                     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,
             },
         };
@@ -170,6 +218,30 @@ function normalizeFlow(flow) {
 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

package/dist/core/sdd/services/archive-quality-coherence.service.d.ts

@@ -0,0 +1,17 @@
+export type ArchiveQualityCoherenceIssueCode = 'ACCEPTANCE_NOT_MET_WITH_Q95_PASS' | 'OPEN_RISK_WITH_Q95_PASS' | 'PLACEHOLDER_EVIDENCE_WITH_Q95_PASS' | 'GENERIC_EVIDENCE_WITH_Q95_PASS';
+export interface ArchiveQualityCoherenceIssue {
+    featureId: string;
+    qualityPath: string;
+    issueCode: ArchiveQualityCoherenceIssueCode;
+    message: string;
+}
+export interface ArchiveQualityCoherenceReport {
+    scanned: number;
+    analyzed: number;
+    grandfathered: number;
+    issues: ArchiveQualityCoherenceIssue[];
+}
+export declare function scanArchiveQualityCoherence(archivedDir: string, options?: {
+    grandfatherMaxFeat?: number;
+}): Promise<ArchiveQualityCoherenceReport>;
+//# sourceMappingURL=archive-quality-coherence.service.d.ts.map