sdd-agent-platform 0.4.0 → 0.4.2

package/node_modules/@sdd-agent-platform/core/src/risk/contracts.ts

@@ -30,7 +30,7 @@ export interface RequiredEvidence {
   id: string;
   acceptanceRef: string;
   kind: 'command' | 'artifact' | 'review' | 'runtime-projection' | 'manual';
-  requiredBefore: 'sync-back' | 'ship' | 'handoff';
+  requiredBefore: 'ship' | 'handoff';
   refs: RuntimeRef[];
   reasons: string[];
 }
@@ -38,7 +38,7 @@ export interface RequiredEvidence {
 export interface RequiredReview {
   id: string;
   kind: 'source-boundary' | 'runtime-state' | 'security' | 'evidence' | 'release';
-  requiredBefore: 'handoff' | 'sync-back' | 'ship';
+  requiredBefore: 'handoff' | 'ship';
   reasons: string[];
 }
 

package/node_modules/@sdd-agent-platform/core/src/risk/kernel.ts

@@ -130,10 +130,10 @@ function requiredStagesForProfile(profile: LifecycleRiskProfile): LifecycleRiskD
     return ['do', 'test'];
   }
   if (profile === 'compact') {
-    return ['tasks', 'verifies', 'do', 'test', 'goal-verify', 'sync-back'];
+    return ['tasks', 'verifies', 'do', 'test', 'goal-verify'];
   }
   if (profile === 'full') {
-    return ['spec', 'plan', 'tasks', 'verifies', 'do', 'test', 'goal-verify', 'sync-back'];
+    return ['spec', 'plan', 'tasks', 'verifies', 'do', 'test', 'goal-verify', 'ship'];
   }
   if (profile === 'research') {
     return ['spec', 'plan', 'verifies'];
@@ -157,7 +157,7 @@ function requiredEvidenceFor(profile: LifecycleRiskProfile, signals: CodingRiskS
     id: 'phase8-risk:command-evidence',
     acceptanceRef: 'phase8-risk-decision',
     kind: 'command',
-    requiredBefore: 'sync-back',
+    requiredBefore: 'ship',
     refs,
     reasons: uniqueStrings(reasons)
   }];
@@ -221,7 +221,7 @@ function decisionReasons(input: LifecycleRiskDecisionInput, profile: LifecycleRi
 }
 
 function allStages(): LifecycleRiskDecision['requiredStages'] {
-  return ['spec', 'plan', 'tasks', 'verifies', 'do', 'test', 'goal-verify', 'sync-back', 'ship'];
+  return ['spec', 'plan', 'tasks', 'verifies', 'do', 'test', 'goal-verify', 'ship'];
 }
 
 function uniqueStrings<T extends string>(values: T[]): T[] {

package/node_modules/@sdd-agent-platform/core/src/risk/legacy-adapters.ts

@@ -172,9 +172,6 @@ function legacyStageToSddStage(stage: string): SddStage | null {
   if (['goal-verify', 'verify', 'acceptance-verify', 'evidence-judgment'].includes(normalized)) {
     return 'goal-verify';
   }
-  if (['sync-back', 'sync-back-proposal'].includes(normalized)) {
-    return 'sync-back';
-  }
   if (normalized === 'ship') {
     return 'ship';
   }
@@ -186,10 +183,10 @@ function defaultStagesForProfile(profile: LifecycleRiskProfile): SddStage[] {
     return ['do', 'test'];
   }
   if (profile === 'compact') {
-    return ['tasks', 'verifies', 'do', 'test', 'goal-verify', 'sync-back'];
+    return ['tasks', 'verifies', 'do', 'test', 'goal-verify'];
   }
   if (profile === 'full') {
-    return ['spec', 'plan', 'tasks', 'verifies', 'do', 'test', 'goal-verify', 'sync-back'];
+    return ['spec', 'plan', 'tasks', 'verifies', 'do', 'test', 'goal-verify', 'ship'];
   }
   if (profile === 'research') {
     return ['spec', 'plan', 'verifies'];
@@ -205,7 +202,7 @@ function lifecycleRequiredEvidence(requiredStages: SddStage[], inputRefs: Runtim
     id: 'legacy-lifecycle:test-evidence',
     acceptanceRef: 'legacy-lifecycle-decision',
     kind: 'command',
-    requiredBefore: 'sync-back',
+    requiredBefore: 'ship',
     refs: inputRefs,
     reasons: hardGateHits.length > 0 ? [`Legacy lifecycle hard gates require command evidence: ${hardGateHits.join(', ')}.`] : ['Legacy lifecycle requires validation evidence.']
   }];
@@ -250,7 +247,7 @@ function lifecycleApprovalPolicy(profile: LifecycleRiskProfile, checkpointRequir
 }
 
 function allSddStages(): SddStage[] {
-  return ['spec', 'plan', 'tasks', 'verifies', 'do', 'test', 'goal-verify', 'sync-back', 'ship'];
+  return ['spec', 'plan', 'tasks', 'verifies', 'do', 'test', 'goal-verify', 'ship'];
 }
 
 function uniqueStages(values: SddStage[]): SddStage[] {

package/node_modules/@sdd-agent-platform/core/src/risk/workflow-gates.ts

@@ -4,7 +4,7 @@ import type { ApprovalPolicy, LifecycleRiskDecision, LifecycleRiskProfile } from
 
 export type LifecycleWorkflowGate =
   | 'direct'
-  | 'review-before-sync-back'
+  | 'review-before-ship'
   | 'review-before-test'
   | 'approval-before-test'
   | 'research-before-implementation'
@@ -32,7 +32,7 @@ export function evaluateTaskWorkflowGate(input: {
   const riskProfile = input.task ? buildTaskRiskProfile(input.task) : null;
   const lifecycleGate = selectLifecycleGate(riskProfile, input.riskDecision ?? null);
   const primaryReason = primaryReasonForGate(lifecycleGate, input.taskId, riskProfile, input.riskDecision ?? null);
-  const nextAction = nextActionForGate(lifecycleGate, input.taskId, Boolean(input.approved));
+  const nextAction = nextActionForGate(lifecycleGate, input.taskId, Boolean(input.approved), input.riskDecision ?? null);
   const blocksRoute = routeBlockedByGate(lifecycleGate, Boolean(input.approved));
   const blocksTest = testBlockedByGate(lifecycleGate, Boolean(input.approved), Boolean(input.reviewerCheckpointSatisfied));
 
@@ -55,7 +55,7 @@ export function verifyContractBlockedGate(taskId: string): LifecycleWorkflowGate
     approvalPolicy: 'blocked',
     requiredStages: [],
     primaryReason: `verify.md is missing, stale, or invalid, so validation commands cannot run for ${taskId}.`,
-    nextAction: `Run sdd instructions verify --json, fix or refresh verify.md for ${taskId}, then rerun sdd test task ${taskId}.`,
+    nextAction: `Run sdd instructions verify --json, fix or refresh verify.md for ${taskId}, then rerun sdd test task-${taskId}.`,
     blocksRoute: false,
     blocksTest: true
   };
@@ -71,7 +71,7 @@ export function testBlockedByGate(gate: LifecycleWorkflowGate, approved = false,
   return ['review-before-test', 'approval-before-test', 'research-before-implementation', 'clarify-before-routing', 'verify-contract-blocked'].includes(gate);
 }
 
-export function gateRequiresSyncBackReview(gate: LifecycleWorkflowGate): boolean {
+export function gateRequiresShipReview(gate: LifecycleWorkflowGate): boolean {
   return gate !== 'direct';
 }
 
@@ -106,7 +106,7 @@ function selectLifecycleGate(riskProfile: TaskRiskProfile | null, riskDecision:
       candidates.push('review-before-test');
     }
     if (tags.has('validation-only') || riskProfile.contextRisk || riskProfile.tokenRisk || riskProfile.performanceRisk) {
-      candidates.push('review-before-sync-back');
+      candidates.push('review-before-ship');
     }
   }
 
@@ -129,7 +129,7 @@ function gateRank(gate: LifecycleWorkflowGate): number {
       return 3;
     case 'review-before-test':
       return 4;
-    case 'review-before-sync-back':
+    case 'review-before-ship':
       return 5;
     case 'direct':
       return 6;
@@ -147,7 +147,7 @@ function primaryReasonForGate(gate: LifecycleWorkflowGate, taskId: string, riskP
   switch (gate) {
     case 'clarify-before-routing':
       return riskDecision?.profile === 'blocked' || riskDecision?.approvalPolicy === 'blocked'
-        ? `Task ${taskId} is missing clear intent, acceptance, validation, or routable task data.`
+        ? riskDecision.reasons[0] ?? `Task ${taskId} is blocked by lifecycle routing.`
         : `Task ${taskId} contains unknown risk and needs clarification before routing.`;
     case 'research-before-implementation':
       return `Task ${taskId} depends on external or low-confidence impact and needs research before implementation.`;
@@ -155,8 +155,8 @@ function primaryReasonForGate(gate: LifecycleWorkflowGate, taskId: string, riskP
       return `Task ${taskId} includes security, token/secret, database, data-loss, or similarly high-impact risk that needs human approval before validation.`;
     case 'review-before-test':
       return `Task ${taskId} touches source, runtime state, API/schema, state/concurrency, or CI/build boundaries that need review before validation.`;
-    case 'review-before-sync-back':
-      return `Task ${taskId} can be validated, but ${reviewBeforeSyncBackReason(riskProfile)} requires review before applying status.`;
+    case 'review-before-ship':
+      return `Task ${taskId} can be validated, but ${reviewBeforeShipReason(riskProfile)} requires review before ship readiness.`;
     case 'direct':
       return `No high-risk lifecycle gate applies to ${taskId}.`;
     case 'verify-contract-blocked':
@@ -164,7 +164,7 @@ function primaryReasonForGate(gate: LifecycleWorkflowGate, taskId: string, riskP
   }
 }
 
-function reviewBeforeSyncBackReason(riskProfile: TaskRiskProfile | null): string {
+function reviewBeforeShipReason(riskProfile: TaskRiskProfile | null): string {
   if (riskProfile?.validationOnly) {
     return 'validation/evidence-only work';
   }
@@ -177,24 +177,26 @@ function reviewBeforeSyncBackReason(riskProfile: TaskRiskProfile | null): string
   return 'the lifecycle gate';
 }
 
-function nextActionForGate(gate: LifecycleWorkflowGate, taskId: string, approved: boolean): string {
+function nextActionForGate(gate: LifecycleWorkflowGate, taskId: string, approved: boolean, riskDecision: LifecycleRiskDecision | null): string {
   switch (gate) {
     case 'clarify-before-routing':
-      return `Update ${taskId} with clear intent, boundary, acceptance, validation, and impact, then rerun sdd tasks route ${taskId}.`;
+      return riskDecision?.profile === 'blocked' || riskDecision?.approvalPolicy === 'blocked'
+        ? 'Run /sdd or /sdd:spec to create or refresh the lifecycle decision before using stage-local entries.'
+        : `Update ${taskId} with clear intent, boundary, acceptance, validation, and impact, then rerun sdd tasks route ${taskId}.`;
     case 'research-before-implementation':
       return `Record research evidence for ${taskId}, document impact and validation, then rerun sdd tasks route ${taskId}.`;
     case 'approval-before-test':
       return approved
         ? `Run or continue validation for ${taskId} with the recorded approval.`
-        : `Have a human review the risk, affected files, and validation commands; if accepted, rerun sdd test task ${taskId} --approved.`;
+        : `Have a human review the risk, affected files, and validation commands; if accepted, rerun sdd test task-${taskId} --approved.`;
     case 'review-before-test':
-      return `Have a reviewer inspect affected files and validation commands for ${taskId}, record the checkpoint, then rerun sdd test task ${taskId}.`;
-    case 'review-before-sync-back':
-      return `Run validation for ${taskId}, then inspect the sync-back proposal before applying status.`;
+      return `Have a reviewer inspect affected files and validation commands for ${taskId}, record the checkpoint, then rerun sdd test task-${taskId}.`;
+    case 'review-before-ship':
+      return `Run validation for ${taskId}, then review accepted evidence before ship readiness.`;
     case 'direct':
-      return `Run validation for ${taskId}; sync-back can be direct after PASS.`;
+      return `Run validation for ${taskId}; proceed to goal-verify and ship after PASS.`;
     case 'verify-contract-blocked':
-      return `Run sdd instructions verify --json, fix or refresh verify.md for ${taskId}, then rerun sdd test task ${taskId}.`;
+      return `Run sdd instructions verify --json, fix or refresh verify.md for ${taskId}, then rerun sdd test task-${taskId}.`;
   }
 }
 

package/node_modules/@sdd-agent-platform/core/src/router/agent-runtime-config.ts

@@ -9,8 +9,10 @@ import type {
   AgentRuntimeAdapterMapping,
   AgentRuntimeRoutingRule,
   CapabilityReuseDecision,
+  CapabilitySourceAllowedEvidenceType,
   CapabilitySourceCatalogEntry,
   CapabilitySourceKind,
+  CapabilitySourceQuarantineStatus,
   ProjectAgentRuntimeConfig,
   SkillCapabilityContract,
   SkillCapabilityEvidenceType,
@@ -80,18 +82,27 @@ function parseAgentRuntimeSkillCapabilities(lines: string[]): SkillCapabilityCon
 }
 
 function parseAgentRuntimeCapabilitySources(lines: string[]): CapabilitySourceCatalogEntry[] {
-  return parseYamlObjectList(lines).map((object) => ({
-    version: CAPABILITY_SOURCE_CATALOG_VERSION,
-    id: object.scalars.id ?? '',
-    name: object.scalars.name ?? object.scalars.id ?? '',
-    kind: capabilitySourceKindField(object.scalars.kind),
-    sourceRef: object.scalars.source_ref ?? '',
-    reuseDecision: reuseDecisionField(object.scalars.reuse_decision),
-    quarantineRequired: booleanValue(object.scalars.quarantine_required, true),
-    allowedUse: object.scalars.allowed_use ?? '',
-    attribution: object.scalars.attribution ?? '',
-    rationale: object.scalars.rationale ?? ''
-  }));
+  return parseYamlObjectList(lines).map((object) => {
+    const quarantineRequired = booleanValue(object.scalars.quarantine_required, true);
+    return {
+      version: CAPABILITY_SOURCE_CATALOG_VERSION,
+      id: object.scalars.id ?? '',
+      name: object.scalars.name ?? object.scalars.id ?? '',
+      kind: capabilitySourceKindField(object.scalars.kind),
+      sourceRef: object.scalars.source_ref ?? '',
+      reuseDecision: reuseDecisionField(object.scalars.reuse_decision),
+      quarantineRequired,
+      quarantineStatus: capabilitySourceQuarantineStatusField(object.scalars.quarantine_status, quarantineRequired ? 'required' : 'not_required'),
+      permissionModel: listField(object, 'permission_model', []),
+      provenanceRequirements: listField(object, 'provenance_requirements', []),
+      hostCompatibility: listField(object, 'host_compatibility', []),
+      allowedEvidenceTypes: listField(object, 'allowed_evidence_types', []).map(capabilitySourceAllowedEvidenceTypeField),
+      forbiddenAuthority: listField(object, 'forbidden_authority', []),
+      allowedUse: object.scalars.allowed_use ?? '',
+      attribution: object.scalars.attribution ?? '',
+      rationale: object.scalars.rationale ?? ''
+    };
+  });
 }
 
 function parseAgentRuntimeAliases(lines: string[]): Record<string, string> {
@@ -265,7 +276,15 @@ function skillCapabilityEvidenceTypeField(value: string | undefined): SkillCapab
 }
 
 function capabilitySourceKindField(value: string | undefined): CapabilitySourceKind {
-  return value === 'native_host' || value === 'mcp_tool' || value === 'open_source_material' || value === 'mechanism_reference' || value === 'future_adapter' || value === 'project_material' ? value : 'project_material';
+  return value === 'native_host' || value === 'mcp_tool' || value === 'cli_tool' || value === 'user_global_material' || value === 'open_source_material' || value === 'mechanism_reference' || value === 'future_adapter' || value === 'project_material' ? value : 'project_material';
+}
+
+function capabilitySourceQuarantineStatusField(value: string | undefined, fallback: CapabilitySourceQuarantineStatus): CapabilitySourceQuarantineStatus {
+  return value === 'not_required' || value === 'required' || value === 'quarantined' || value === 'denied' ? value : fallback;
+}
+
+function capabilitySourceAllowedEvidenceTypeField(value: string): CapabilitySourceAllowedEvidenceType {
+  return value === 'none' || value === 'candidate_evidence' || value === 'command_output' || value === 'browser_snapshot' || value === 'design_context' || value === 'execution_record' || value === 'external_reference' ? value : 'candidate_evidence';
 }
 
 function agentRouterCategoryField(value: string | undefined): AgentRouterCategory | null {

package/node_modules/@sdd-agent-platform/core/src/router/agent-runtime.ts

@@ -13,8 +13,10 @@ import {
 import type { LifecycleAutonomyCeiling } from '../lifecycle/decision-gate.js';
 import type { ArtifactResultIngestionStatus } from '../artifacts/ingestion.js';
 import type { SddResultStatus } from '../artifacts/sdd-result.js';
+import type { StageRouteBinding } from './stage-route-binding.js';
 import type { RouteCacheMetadata, RuntimeProfileSpan, TeamModeActivation } from './route-cache.js';
 import type { ApprovalPolicy, LifecycleRiskProfile, LifecycleWorkflowGate } from '../risk.js';
+import type { AgentCapabilityAuthority, AgentCapabilityDomain, AgentCapabilityMaterialPack, MaterialPackLoadPolicy } from '../registries/agent-capability-catalog.js';
 
 export type BuiltInAgentProfileId = 'planner' | 'architect' | 'implementer' | 'reviewer' | 'validator' | 'researcher' | 'orchestrator' | 'security' | 'domain_expert';
 export type AgentProfileId = BuiltInAgentProfileId | string;
@@ -22,7 +24,9 @@ export type CapabilityReuseDecision = 'reuse_direct' | 'adapt_via_host_adapter'
 export type SkillCapabilityKind = 'skill' | 'mcp' | 'cli_tool' | 'host_tool' | 'project_agent' | 'external_pattern';
 export type SkillCapabilitySource = 'project' | 'user_global' | 'claude_code' | 'mcp' | 'open_source' | 'host';
 export type SkillCapabilityEvidenceType = 'none' | 'command_output' | 'test_result' | 'browser_snapshot' | 'artifact' | 'external_source' | 'execution_record';
-export type CapabilitySourceKind = 'native_host' | 'mcp_tool' | 'open_source_material' | 'mechanism_reference' | 'future_adapter' | 'project_material';
+export type CapabilitySourceKind = 'native_host' | 'mcp_tool' | 'cli_tool' | 'user_global_material' | 'open_source_material' | 'mechanism_reference' | 'future_adapter' | 'project_material';
+export type CapabilitySourceQuarantineStatus = 'not_required' | 'required' | 'quarantined' | 'denied';
+export type CapabilitySourceAllowedEvidenceType = 'none' | 'candidate_evidence' | 'command_output' | 'browser_snapshot' | 'design_context' | 'execution_record' | 'external_reference';
 export type ExternalPackImportStatus = 'approved' | 'quarantined' | 'denied';
 export type ExternalPackCheckStatus = 'pass' | 'warn' | 'fail' | 'not_run';
 export type ToolPermissionPolicy = 'allow' | 'ask' | 'deny';
@@ -33,6 +37,8 @@ export type TeamModeCostClass = 'none' | 'low' | 'medium' | 'high';
 export type TeamModeCostRoute = 'not_applicable' | 'downgraded' | 'no_downgrade' | 'blocked';
 export type AgentExecutionRecordStatus = 'claimed' | 'completed' | 'failed' | 'blocked' | 'skipped';
 export type TeamSessionRecordStatus = 'created' | 'completed' | 'blocked' | 'disabled';
+export type WorkflowHostAdapterId = 'claude_code' | 'codex' | 'opencode';
+export type WorkflowHostAdapterSupport = 'active' | 'future' | 'unsupported';
 
 export interface AgentProfileContract {
   version: typeof AGENT_SKILL_TEAM_RUNTIME_CONTRACT_VERSION;
@@ -70,6 +76,12 @@ export interface CapabilitySourceCatalogEntry {
   sourceRef: string;
   reuseDecision: CapabilityReuseDecision;
   quarantineRequired: boolean;
+  quarantineStatus: CapabilitySourceQuarantineStatus;
+  permissionModel: string[];
+  provenanceRequirements: string[];
+  hostCompatibility: string[];
+  allowedEvidenceTypes: CapabilitySourceAllowedEvidenceType[];
+  forbiddenAuthority: string[];
   allowedUse: string;
   attribution: string;
   rationale: string;
@@ -157,6 +169,16 @@ export interface ToolPermissionSpec {
   hostPermissionProjection: string;
 }
 
+export interface HostWorkflowProjectionContract {
+  host: WorkflowHostAdapterId;
+  support: WorkflowHostAdapterSupport;
+  commandSurface: string[];
+  skillSurface: string[];
+  permissionSurface: string[];
+  evidenceReturn: string[];
+  unsupportedReason: string | null;
+}
+
 export interface HostAdapterContract {
   version: typeof HOST_ADAPTER_CONTRACT_VERSION;
   id: string;
@@ -164,6 +186,8 @@ export interface HostAdapterContract {
   responsibilities: string[];
   forbiddenAuthority: string[];
   projections: string[];
+  workflowProjectionPolicy: string;
+  workflowProjections: HostWorkflowProjectionContract[];
 }
 
 export interface DelegationWavePolicy {
@@ -263,6 +287,47 @@ export interface AgentRouterRejectedProfile {
   reason: string;
 }
 
+export interface AgentCapabilitySelectedDomain {
+  domain: AgentCapabilityDomain;
+  capabilityId: string;
+  authority: AgentCapabilityAuthority;
+  reason: string;
+}
+
+export interface AgentCapabilitySelectedMaterialPack {
+  id: string;
+  domains: AgentCapabilityDomain[];
+  loadPolicy: MaterialPackLoadPolicy;
+  contextBudget: AgentCapabilityMaterialPack['contextBudget'];
+  sourceKind: AgentCapabilityMaterialPack['sourceKind'];
+  expectedOutputs: string[];
+  reason: string;
+}
+
+export interface AgentCapabilityRejectedSource {
+  sourceId: string;
+  quarantineStatus: CapabilitySourceQuarantineStatus;
+  reuseDecision: CapabilityReuseDecision;
+  allowedEvidenceTypes: CapabilitySourceAllowedEvidenceType[];
+  reason: string;
+}
+
+export interface AgentCapabilityConsideredSource extends AgentCapabilityRejectedSource {
+  kind: CapabilitySourceKind;
+  consideredUse: string;
+}
+
+
+export interface AgentCapabilityRouteDecision {
+  authority: 'advisory_only';
+  selectedDomains: AgentCapabilitySelectedDomain[];
+  selectedPacks: AgentCapabilitySelectedMaterialPack[];
+  rejectedExternalSources: AgentCapabilityRejectedSource[];
+  consideredExternalSources: AgentCapabilityConsideredSource[];
+  evidenceRequirements: string[];
+  permissionCeiling: LifecycleAutonomyCeiling;
+}
+
 export interface AgentRouterDecision {
   version: typeof AGENT_ROUTER_CONTRACT_VERSION;
   taskId: string;
@@ -286,6 +351,8 @@ export interface AgentRouterDecision {
   requiredArtifacts: string[];
   blockedReason: string | null;
   nextAction: string;
+  stageRouteBinding?: StageRouteBinding;
+  capabilityDecision: AgentCapabilityRouteDecision;
   registrySources?: RuntimeRegistryEntrySource[];
   resolvedAliases?: AgentRuntimeAliasResolution[];
   routingRuleHits?: string[];

package/node_modules/@sdd-agent-platform/core/src/router/route-projection.ts

@@ -1,12 +1,15 @@
+import type { AgentCapabilityCatalog, AgentCapabilityCatalogEntry, AgentCapabilityDomain, AgentCapabilityMaterialPack, AgentCapabilityStage } from '../registries/agent-capability-catalog.js';
 import { TOOL_PERMISSION_SPEC_VERSION } from '../contracts.js';
 import type { LifecycleAutonomyCeiling } from '../lifecycle/decision-gate.js';
 import type { SddTask, SddTaskGap } from '../sdd-docs/task-parser.js';
 import type {
+  AgentCapabilityRouteDecision,
   AgentProfileId,
   AgentRouterCategory,
   AgentRouterRejectedProfile,
   AgentRuntimeAdapterMapping,
   AgentRuntimeRoutingRule,
+  CapabilitySourceCatalogEntry,
   ModelPolicyContract,
   RuntimeRegistryEntrySource,
   ToolPermissionSpec
@@ -79,6 +82,56 @@ export function selectRequiredSkillCapabilities(task: SddTask, profile: AgentPro
   return [...capabilities];
 }
 
+export function buildAgentCapabilityRouteDecision(task: SddTask | null, category: AgentRouterCategory, autonomyCeiling: LifecycleAutonomyCeiling, registry: AgentSkillRuntimeRegistry, catalog: AgentCapabilityCatalog): AgentCapabilityRouteDecision {
+  if (!task) {
+    return {
+      authority: 'advisory_only',
+      selectedDomains: [],
+      selectedPacks: [],
+      rejectedExternalSources: rejectedCapabilitySources(registry.capabilitySources),
+      consideredExternalSources: consideredCapabilitySources(registry.capabilitySources),
+      evidenceRequirements: ['task metadata must exist before capability routing can select evidence requirements'],
+      permissionCeiling: autonomyCeiling
+    };
+  }
+  const stage = routeCapabilityStage(task, category);
+  const text = taskSignalText(task);
+  const selectedCapabilities = catalog.capabilities.filter((capability) => capability.domainGroup === 'professional' && capabilityStageFits(capability, stage, task, text) && capabilityMatchesTask(capability, task, text));
+  const effectiveCapabilities = selectedCapabilities.length > 0 ? selectedCapabilities : fallbackCapabilitiesForTask(catalog.capabilities, task, stage);
+  const packById = new Map(catalog.materialPacks.map((pack) => [pack.id, pack]));
+  const selectedPackIds = new Set<string>();
+  for (const capability of effectiveCapabilities) {
+    for (const packId of capability.routing.materialPackIds) {
+      const pack = packById.get(packId);
+      if (pack && pack.loadPolicy !== 'never_inline' && packFitsRoute(pack, stage, text)) {
+        selectedPackIds.add(packId);
+      }
+    }
+  }
+  return {
+    authority: 'advisory_only',
+    selectedDomains: effectiveCapabilities.map((capability) => ({
+      domain: capability.domain,
+      capabilityId: capability.id,
+      authority: capability.authority,
+      reason: capabilityReason(capability, task)
+    })),
+    selectedPacks: [...selectedPackIds].map((packId) => packById.get(packId)).filter((pack): pack is AgentCapabilityMaterialPack => Boolean(pack)).map((pack) => ({
+      id: pack.id,
+      domains: [...pack.domains],
+      loadPolicy: pack.loadPolicy,
+      contextBudget: pack.contextBudget,
+      sourceKind: pack.sourceKind,
+      expectedOutputs: [...pack.expectedOutputs],
+      reason: packReason(pack, stage)
+    })),
+    rejectedExternalSources: rejectedCapabilitySources(registry.capabilitySources),
+    consideredExternalSources: consideredCapabilitySources(registry.capabilitySources),
+    evidenceRequirements: evidenceRequirementsForCapabilities(effectiveCapabilities),
+    permissionCeiling: autonomyCeiling
+  };
+}
+
 export function routeRegistrySources(registry: AgentSkillRuntimeRegistry, profile: AgentProfileId | null, capabilityIds: string[]): RuntimeRegistryEntrySource[] {
   const selected: RuntimeRegistryEntrySource[] = [];
   const seen = new Set<string>();
@@ -123,7 +176,7 @@ export function buildToolPermissionSpec(task: SddTask, profile: AgentProfileId,
     profile,
     risk: [...task.risk],
     toolGroups,
-    fileScope: task.affectedFiles.length > 0 ? [...task.affectedFiles] : ['declared task boundary', 'artifacts/<task>.md'],
+    fileScope: task.affectedFiles.length > 0 ? [...task.affectedFiles] : ['declared task boundary', '.sdd/runs/<branch>/<stage>/<task>.md'],
     policy: highRisk || autonomyCeiling === 'full_sdd_with_checkpoint' || autonomyCeiling === 'research_before_implementation' ? 'ask' : 'allow',
     approvalPolicy: highRisk ? 'human checkpoint required before write or external side effect' : 'host approval policy applies',
     runtimeValidationRequired: highRisk || profile === 'implementer' || profile === 'validator',
@@ -144,3 +197,161 @@ export function buildRejectedProfiles(allowedProfiles: AgentProfileId[], blocked
     .filter((profile) => !allowed.has(profile.id))
     .map((profile) => ({ profile: profile.id, reason: blockedReason ?? 'Profile is outside task metadata allowed_agents/agent_fit, routing rules, or router risk category.' }));
 }
+
+function routeCapabilityStage(task: SddTask, category: AgentRouterCategory): AgentCapabilityStage {
+  if (category === 'planning') {
+    return 'plan';
+  }
+  if (category === 'validation' || task.status === 'completed') {
+    return 'test';
+  }
+  return 'do';
+}
+
+function taskSignalText(task: SddTask): string {
+  return [
+    task.id,
+    task.title ?? '',
+    task.boundary ?? '',
+    task.implementationNotes ?? '',
+    ...task.risk,
+    ...task.affectedFiles,
+    ...task.validation,
+    ...task.acceptance,
+    ...task.allowedAgents,
+    ...task.agentFit
+  ].join('\n').toLowerCase();
+}
+
+function capabilityMatchesTask(capability: AgentCapabilityCatalogEntry, task: SddTask, text: string): boolean {
+  return capability.routing.riskTags.some((tag) => text.includes(tag.toLowerCase())) || capability.routing.projectStackTags.some((tag) => projectStackMatches(tag, task, text)) || capability.routing.materialPackIds.some((packId) => text.includes(packId.replace(/^baseline-/, '').replace(/-/g, ' '))) || domainFileSignal(capability.domain, task.affectedFiles);
+}
+
+function fallbackCapabilitiesForTask(capabilities: AgentCapabilityCatalogEntry[], task: SddTask, stage: AgentCapabilityStage): AgentCapabilityCatalogEntry[] {
+  const codeFile = task.affectedFiles.some((file) => /\.(ts|js|java|go|py|rs|cs|php|rb)$/i.test(file));
+  const fallbackDomain: AgentCapabilityDomain = codeFile ? 'backend-engineering' : 'solution-design';
+  const fallback = capabilities.find((capability) => capability.domain === fallbackDomain && capabilityStageFits(capability, stage, task, taskSignalText(task)));
+  return fallback ? [fallback] : [];
+}
+
+function packFitsRoute(pack: AgentCapabilityMaterialPack, stage: AgentCapabilityStage, text: string): boolean {
+  const keywordTriggered = pack.triggerKeywords.some((keyword) => text.includes(keyword.toLowerCase()));
+  if (pack.sourceKind === 'sdd_native_baseline') {
+    return pack.triggerStages.includes(stage) || keywordTriggered;
+  }
+  return pack.triggerStages.includes(stage) && keywordTriggered;
+}
+
+function domainFileSignal(domain: AgentCapabilityDomain, affectedFiles: string[]): boolean {
+  const files = affectedFiles.map((file) => file.toLowerCase());
+  if (domain === 'frontend-engineering') {
+    return files.some((file) => /\.(tsx|jsx|vue|svelte|css|scss|less)$/.test(file) || file.includes('/components/') || file.includes('/pages/'));
+  }
+  if (domain === 'db-data-engineering') {
+    return files.some((file) => /\.(sql|prisma)$/.test(file) || file.includes('migration') || file.includes('schema') || file.includes('database'));
+  }
+  if (domain === 'backend-engineering') {
+    return files.some((file) => /\.(ts|js|java|go|py|rs|cs|php|rb)$/.test(file)) && !domainFileSignal('frontend-engineering', affectedFiles);
+  }
+  return false;
+}
+
+function capabilityStageFits(capability: AgentCapabilityCatalogEntry, stage: AgentCapabilityStage, task: SddTask, text: string): boolean {
+  if (capability.stages.includes(stage)) {
+    return true;
+  }
+  if (capability.domain === 'testing-quality-engineering' && stage === 'do') {
+    return testingQualityTaskSignal(task);
+  }
+  return capability.domain === 'release-engineering' && /release|ship|deploy|rollback|ci|发布/.test(text);
+}
+
+function testingQualityTaskSignal(task: SddTask): boolean {
+  const taskText = [task.id, task.title ?? '', task.boundary ?? '', task.implementationNotes ?? '', ...task.risk, ...task.affectedFiles, ...task.acceptance].join('\n').toLowerCase();
+  return /quality|coverage|acceptance|验证|测试/.test(taskText) || task.affectedFiles.some((file) => /\.(test|spec)\.[tj]sx?$/i.test(file));
+}
+
+function capabilityReason(capability: AgentCapabilityCatalogEntry, task: SddTask): string {
+  const fileSignal = domainFileSignal(capability.domain, task.affectedFiles) ? 'affected file evidence' : 'task risk, validation, or text evidence';
+  return `${capability.domain} selected from ${fileSignal}; authority remains ${capability.authority}.`;
+}
+
+function packReason(pack: AgentCapabilityMaterialPack, stage: AgentCapabilityStage): string {
+  return `${pack.id} is route_when_triggered for ${stage} and stays ${pack.contextBudget} context.`;
+}
+
+function evidenceRequirementsForCapabilities(capabilities: AgentCapabilityCatalogEntry[]): string[] {
+  const requirements = new Set<string>();
+  for (const capability of capabilities) {
+    for (const output of capability.outputs) {
+      requirements.add(`${capability.domain}: ${output}`);
+    }
+  }
+  return [...requirements];
+}
+
+function consideredCapabilitySources(sources: CapabilitySourceCatalogEntry[]): AgentCapabilityRouteDecision['consideredExternalSources'] {
+  return sources
+    .filter((source) => source.kind !== 'native_host')
+    .map((source) => ({
+      sourceId: source.id,
+      kind: source.kind,
+      quarantineStatus: source.quarantineStatus,
+      reuseDecision: source.reuseDecision,
+      allowedEvidenceTypes: [...source.allowedEvidenceTypes],
+      consideredUse: source.allowedUse,
+      reason: rejectedSourceReason(source)
+    }));
+}
+
+
+function rejectedCapabilitySources(sources: CapabilitySourceCatalogEntry[]): AgentCapabilityRouteDecision['rejectedExternalSources'] {
+  return sources
+    .filter((source) => source.kind !== 'native_host' && (source.quarantineRequired || source.reuseDecision !== 'reuse_direct' || source.kind === 'future_adapter'))
+    .map((source) => ({
+      sourceId: source.id,
+      quarantineStatus: source.quarantineStatus,
+      reuseDecision: source.reuseDecision,
+      allowedEvidenceTypes: [...source.allowedEvidenceTypes],
+      reason: rejectedSourceReason(source)
+    }));
+}
+
+function projectStackMatches(tag: string, task: SddTask, text: string): boolean {
+  if (tag === 'generic') {
+    return false;
+  }
+  if (text.includes(tag.toLowerCase())) {
+    return true;
+  }
+  const files = task.affectedFiles.map((file) => file.toLowerCase());
+  if (tag === 'typescript') {
+    return files.some((file) => /\.(ts|tsx)$/.test(file));
+  }
+  if (tag === 'javascript') {
+    return files.some((file) => /\.(js|jsx)$/.test(file));
+  }
+  if (tag === 'java') {
+    return files.some((file) => file.endsWith('.java'));
+  }
+  if (tag === 'sql') {
+    return files.some((file) => /\.(sql|prisma)$/.test(file));
+  }
+  return files.some((file) => file.includes(tag.toLowerCase()));
+}
+
+function rejectedSourceReason(source: CapabilitySourceCatalogEntry): string {
+  if (source.quarantineStatus === 'denied') {
+    return 'Source is denied or unsupported and cannot participate in routing.';
+  }
+  if (source.kind === 'future_adapter') {
+    return 'Future adapter is recorded as metadata only until host behavior is validated.';
+  }
+  if (source.quarantineStatus === 'quarantined' || source.quarantineStatus === 'required') {
+    return 'Source requires quarantine/provenance review and is not invoked by capability routing.';
+  }
+  if (source.reuseDecision === 'avoid') {
+    return 'Reuse policy avoids this source.';
+  }
+  return 'External source is considered but not loaded during progressive disclosure.';
+}