sdd-agent-platform 0.4.1 → 0.4.2

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

@@ -1,6 +1,6 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtemp, rm } from 'node:fs/promises';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 
@@ -17,6 +17,8 @@ import {
 import { writeVerifyContract } from '../verification/verify-contract.js';
 import { createRun, readRunState, writeRunState } from '../run-state/run-state.js';
 import { bindTestRunState } from '../test-support/run-state.js';
+import { evaluateLifecycleRiskDecisionForModel, recordLifecycleRiskDecisionProjection, readLifecycleRiskDecisionProjection } from '../risk.js';
+import { parseSddBranch } from '../sdd-docs/task-parser.js';
 import {
   inspectAgentSkillTeamRuntime,
   inspectCapabilitySource,
@@ -28,11 +30,13 @@ import {
   routeSddTask,
   validateAgentSkillTeamRuntime
 } from './route-sdd-task.js';
+import { importRuntimeSkillCapability } from './runtime-import.js';
 
 test('Phase 6 agent skill team runtime exposes reusable contracts and router decisions', async () => {
   const root = await mkdtemp(path.join(tmpdir(), 'sdd-phase60-runtime-'));
   try {
     await initProject(root);
+    await seedLifecycleRiskDecision(root, 'master');
 
     const runtime = await inspectAgentSkillTeamRuntime(root);
     const validation = await validateAgentSkillTeamRuntime(root);
@@ -101,6 +105,7 @@ test('Phase 6 adaptive team-mode routes choose cost-bounded agent teams automati
     await initProject(root);
     await writeBranchDocs(root, 'master', `# Tasks\n\n${adaptiveTeamTaskMarkdown('LOW', { allowedAgents: ['implementer'], affectedFiles: ['docs/low.md'] })}\n${adaptiveTeamTaskMarkdown('REVIEW', { allowedAgents: ['reviewer'], requiredArtifacts: ['artifacts/review-REVIEW.md'], affectedFiles: ['docs/review.md'] })}\n${adaptiveTeamTaskMarkdown('SOURCE', { allowedAgents: ['implementer'] })}\n${adaptiveTeamTaskMarkdown('HIGH', { allowedAgents: ['implementer'], risk: ['database'] })}\n${adaptiveTeamTaskMarkdown('SECURITY', { allowedAgents: ['security'], risk: ['security'] })}`);
     await writeVerifyContract(root, { branch: 'master', branchSource: 'cli_option', force: true });
+    await seedLifecycleRiskDecision(root, 'master');
 
     const low = await routeSddTask(root, { taskId: 'LOW', branch: 'master' });
     const review = await routeSddTask(root, { taskId: 'REVIEW', branch: 'master' });
@@ -130,7 +135,7 @@ test('Phase 6 adaptive team-mode routes choose cost-bounded agent teams automati
     assert.equal(review.teamMode.waveRecommendation.includes('implementation_review'), true);
     assert.equal(unapprovedHigh.category, 'blocked');
     assert.equal(unapprovedHigh.lifecycleGate, 'approval-before-test');
-    assert.match(unapprovedHigh.nextAction, /rerun sdd test task HIGH --approved/);
+    assert.match(unapprovedHigh.nextAction, /rerun sdd test task-HIGH --approved/);
     assert.equal(high.teamMode.mode, 'hyperplan');
     assert.equal(high.teamMode.enabled, true);
     assert.equal(high.teamMode.costClass, 'high');
@@ -154,7 +159,7 @@ test('Phase 6 adaptive team-mode routes choose cost-bounded agent teams automati
     assert.equal(unapprovedSecurity.category, 'blocked');
     assert.match(unapprovedSecurity.blockedReason ?? '', /human approval before validation/);
     assert.equal(unapprovedSecurity.lifecycleGate, 'approval-before-test');
-    assert.match(unapprovedSecurity.nextAction, /rerun sdd test task SECURITY --approved/);
+    assert.match(unapprovedSecurity.nextAction, /rerun sdd test task-SECURITY --approved/);
     assert.doesNotMatch(unapprovedSecurity.nextAction, /Fix task gaps/);
     assert.equal(forced.teamMode.activation, 'force');
     assert.equal(forced.teamMode.mode, 'review-lite');
@@ -178,6 +183,7 @@ test('routeSddTask uses derived route cache and opt-in profiling only', async ()
     await initProject(root);
     await writeBranchDocs(root, 'master', `# Tasks\n\n${adaptiveTeamTaskMarkdown('CACHE', { allowedAgents: ['reviewer'], requiredArtifacts: ['artifacts/review-CACHE.md'], affectedFiles: ['docs/cache.md'] })}`);
     await writeVerifyContract(root, { branch: 'master', branchSource: 'cli_option', force: true });
+    await seedLifecycleRiskDecision(root, 'master');
 
     const uncached = await routeSddTask(root, { taskId: 'CACHE', branch: 'master' });
     const first = await routeSddTask(root, { taskId: 'CACHE', branch: 'master', cache: true, profile: true });
@@ -204,6 +210,7 @@ test('routeSddTask uses derived route cache and opt-in profiling only', async ()
 
     await writeBranchDocs(root, 'master', `# Tasks\n\n${adaptiveTeamTaskMarkdown('CACHE', { allowedAgents: ['reviewer'], requiredArtifacts: ['artifacts/review-CACHE.md'], affectedFiles: ['docs/cache.md'] })}\n\nCache key invalidation fixture.`);
     await writeVerifyContract(root, { branch: 'master', branchSource: 'cli_option', force: true });
+    await seedLifecycleRiskDecision(root, 'master');
     const invalidated = await routeSddTask(root, { taskId: 'CACHE', branch: 'master', cache: true });
 
     assert.equal(invalidated.cache?.status, 'stored');
@@ -221,6 +228,7 @@ test('Phase 6.3 project agent runtime merges project config and routes by alias
     await appendProjectRuntimeConfig(root, phase63ProjectRuntimeConfig());
     await writeBranchDocs(root, 'master', phase63FrontendTaskMarkdown('FRONTEND-1'));
     await writeVerifyContract(root, { branch: 'master', branchSource: 'cli_option', force: true });
+    await seedLifecycleRiskDecision(root, 'master');
 
     const runtime = await inspectAgentSkillTeamRuntime(root);
     const validation = await validateAgentSkillTeamRuntime(root);
@@ -256,6 +264,126 @@ test('Phase 6.3 project agent runtime merges project config and routes by alias
   }
 });
 
+test('Phase 6.3 skill capability import writes project and user-global runtime declarations', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-phase63-import-runtime-'));
+  try {
+    await initProject(root);
+    const configPath = path.join(root, '.sdd', 'project.yml');
+    const before = await readFile(configPath, 'utf8');
+
+    const dryRun = await importRuntimeSkillCapability(root, {
+      capabilityId: 'project.skill.frontend_review_imported',
+      source: 'project',
+      sourceRef: '.claude/skills/frontend-review/SKILL.md',
+      name: 'Frontend review imported',
+      domains: ['frontend', 'review'],
+      stages: ['plan', 'do', 'test'],
+      dryRun: true
+    });
+    assert.equal(dryRun.status, 'dry_run');
+    assert.equal(dryRun.written, false);
+    assert.equal(await inspectSkillCapability(root, 'project.skill.frontend_review_imported'), null);
+    assert.equal(await readFile(configPath, 'utf8'), before);
+
+    const created = await importRuntimeSkillCapability(root, {
+      capabilityId: 'project.skill.frontend_review_imported',
+      source: 'project',
+      sourceRef: '.claude/skills/frontend-review/SKILL.md',
+      name: 'Frontend review imported',
+      domains: ['frontend', 'review'],
+      stages: ['plan', 'do', 'test']
+    });
+    const projectCapability = await inspectSkillCapability(root, 'project.skill.frontend_review_imported');
+    const projectSource = await inspectCapabilitySource(root, 'project_skill_frontend_review_imported_source');
+    const validation = await validateAgentSkillTeamRuntime(root);
+
+    assert.equal(created.status, 'created');
+    assert.equal(created.written, true);
+    assert.ok(projectCapability);
+    assert.equal(projectCapability.source, 'project');
+    assert.equal(projectCapability.sourceRef, 'project_skill_frontend_review_imported_source');
+    assert.ok(projectSource);
+    assert.equal(projectSource.kind, 'project_material');
+    assert.equal(projectSource.quarantineRequired, false);
+    assert.equal(validation.valid, true);
+
+    const afterCreate = await readFile(configPath, 'utf8');
+    const unchanged = await importRuntimeSkillCapability(root, {
+      capabilityId: 'project.skill.frontend_review_imported',
+      source: 'project',
+      sourceRef: '.claude/skills/frontend-review/SKILL.md',
+      name: 'Frontend review imported',
+      domains: ['frontend', 'review'],
+      stages: ['plan', 'do', 'test']
+    });
+    assert.equal(unchanged.status, 'unchanged');
+    assert.equal(unchanged.written, false);
+    assert.equal(await readFile(configPath, 'utf8'), afterCreate);
+
+    const blockedUpdate = await importRuntimeSkillCapability(root, {
+      capabilityId: 'project.skill.frontend_review_imported',
+      source: 'project',
+      sourceRef: '.claude/skills/frontend-review/SKILL.md',
+      name: 'Frontend review changed',
+      domains: ['frontend', 'review'],
+      stages: ['plan', 'do', 'test']
+    });
+    assert.equal(blockedUpdate.status, 'blocked');
+    assert.equal(blockedUpdate.written, false);
+
+    const forcedUpdate = await importRuntimeSkillCapability(root, {
+      capabilityId: 'project.skill.frontend_review_imported',
+      source: 'project',
+      sourceRef: '.claude/skills/frontend-review/SKILL.md',
+      name: 'Frontend review changed',
+      domains: ['frontend', 'review'],
+      stages: ['plan', 'do', 'test'],
+      force: true
+    });
+    assert.equal(forcedUpdate.status, 'updated');
+    assert.equal(forcedUpdate.written, true);
+    assert.equal((await inspectSkillCapability(root, 'project.skill.frontend_review_imported'))?.name, 'Frontend review changed');
+
+    const userGlobal = await importRuntimeSkillCapability(root, {
+      capabilityId: 'user.skill.ui_ux_pro_max',
+      source: 'user_global',
+      sourceRef: 'C:\\Users\\inshn\\.claude\\skills\\ui-ux-pro-max\\SKILL.md',
+      name: 'UI UX Pro Max',
+      domains: ['ui_ux', 'frontend'],
+      stages: ['spec', 'plan', 'test'],
+      allowedEvidenceTypes: ['candidate_evidence', 'design_context'],
+      attribution: 'user-global Claude Code skill'
+    });
+    const userCapability = await inspectSkillCapability(root, 'user.skill.ui_ux_pro_max');
+    const userSource = await inspectCapabilitySource(root, 'user_skill_ui_ux_pro_max_source');
+    const userPack = await inspectExternalAgentPackImport(root, 'user_skill_ui_ux_pro_max_source');
+
+    assert.equal(userGlobal.status, 'created');
+    assert.ok(userCapability);
+    assert.equal(userCapability.source, 'user_global');
+    assert.ok(userSource);
+    assert.equal(userSource.kind, 'user_global_material');
+    assert.equal(userSource.quarantineRequired, true);
+    assert.equal(userSource.quarantineStatus, 'required');
+    assert.equal(userSource.allowedEvidenceTypes.includes('design_context'), true);
+    assert.equal(userPack.status, 'quarantined');
+    assert.equal((await validateAgentSkillTeamRuntime(root)).valid, true);
+
+    const builtInBlocked = await importRuntimeSkillCapability(root, {
+      capabilityId: 'host.edit.hashline',
+      source: 'project',
+      sourceRef: '.claude/skills/hashline/SKILL.md',
+      domains: ['editing'],
+      stages: ['do'],
+      force: true
+    });
+    assert.equal(builtInBlocked.status, 'blocked');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+
 test('Phase 6.3 invalid agent runtime declarations fail closed', async () => {
   const root = await mkdtemp(path.join(tmpdir(), 'sdd-phase63-invalid-runtime-'));
   try {
@@ -298,6 +426,7 @@ ${capabilityRouteTaskMarkdown('SECURITY', 'Security permission boundary update',
 ${capabilityRouteTaskMarkdown('DB', 'Database migration data safety update', ['db/migrations/001.sql'], ['database', 'data-loss'], ['npm test'])}
 ${capabilityRouteTaskMarkdown('RELEASE', 'Release deploy rollback readiness', ['.github/workflows/release.yml'], ['release', 'ci-build'], ['npm test'])}
 ${capabilityRouteTaskMarkdown('TESTING', 'Testing quality coverage update', ['packages/core/src/parser.test.ts'], ['validation'], ['coverage acceptance test'])}`);
+    await seedLifecycleRiskDecision(root, 'master');
 
     const simple = await routeSddTask(root, { taskId: 'SIMPLE', branch: 'master' });
     const ui = await routeSddTask(root, { taskId: 'UI', branch: 'master' });
@@ -342,15 +471,17 @@ test('routeSddTask blocks downstream tasks until dependencies are completed', as
   try {
     await initProject(root);
     await writeBranchDocs(root, 'feature', `# Tasks\n\n${validTaskMarkdown('DEP1', [])}\n${validTaskMarkdown('DEP2', ['DEP1']).replace('packages/core/src/index.ts', 'docs/dep2.md')}`);
+    await seedLifecycleRiskDecision(root, 'feature');
 
     const blocked = await routeSddTask(root, { taskId: 'DEP2', branch: 'feature', approved: true });
 
     assert.equal(blocked.category, 'blocked');
     assert.equal(blocked.recommendedProfile, null);
     assert.match(blocked.blockedReason ?? '', /DEP2 depends on DEP1, but DEP1 has not passed required verification/);
-    assert.match(blocked.nextAction, /sdd test task DEP1/);
+    assert.match(blocked.nextAction, /sdd test task-DEP1/);
 
     await writeBranchDocs(root, 'feature', `# Tasks\n\n${validTaskMarkdown('DEP1', []).replace('status: pending', 'status: completed')}\n${validTaskMarkdown('DEP2', ['DEP1']).replace('packages/core/src/index.ts', 'docs/dep2.md')}`);
+    await seedLifecycleRiskDecision(root, 'feature');
     const ready = await routeSddTask(root, { taskId: 'DEP2', branch: 'feature' });
 
     assert.notEqual(ready.category, 'blocked');
@@ -371,6 +502,7 @@ ${validTaskMarkdown('DEP1', [])
   .replace('packages/core/src/index.ts', 'docs/dep1.md')
   .replace('validation:\n  - npm test', 'validation_batch: dep-batch\nvalidation_timing: batch_end\nrequires_verify_before_next: false\nvalidation:\n  - npm test')}
 ${validTaskMarkdown('DEP2', ['DEP1']).replace('packages/core/src/index.ts', 'docs/dep2.md')}`);
+    await seedLifecycleRiskDecision(root, 'feature');
     const run = await createRun(root, { runId: 'run-dep1-implemented' });
     await bindTestRunState(root, run.runId, 'feature', 'DEP1');
     const bound = await readRunState(root, run.runId);
@@ -402,6 +534,106 @@ ${validTaskMarkdown('DEP2', ['DEP1']).replace('packages/core/src/index.ts', 'doc
   }
 });
 
+test('routeSddTask blocks stage-local routing when lifecycle projection is missing', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-route-lifecycle-authority-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'master', `# Tasks\n\n${validTaskMarkdown('LOCAL', [])}`);
+    await writeVerifyContract(root, { branch: 'master', branchSource: 'cli_option', force: true });
+
+    const decision = await routeSddTask(root, { taskId: 'LOCAL', branch: 'master' });
+
+    assert.equal(decision.category, 'blocked');
+    assert.match(decision.blockedReason ?? '', /Stage-local entry requires an active lifecycle decision/);
+    assert.match(decision.nextAction, /Run \/sdd or \/sdd:spec/);
+    assert.equal(decision.recommendedProfile, null);
+
+    const projection = await readLifecycleRiskDecisionProjection(root, { branch: 'master' });
+    assert.equal(projection, null);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('routeSddTask semantically binds natural do text to the accepted task boundary', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-route-semantic-binding-'));
+  try {
+    await initProject(root);
+    const loginTask = validTaskMarkdown('LOGIN-1', [])
+      .replace('Valid task', '登录系统')
+      .replace('Stay in parser files only.', '只实现登录系统边界。')
+      .replace('Parser behavior is covered.', '登录系统任务完成。');
+    await writeBranchDocs(root, 'master', `# Tasks\n\n${loginTask}`);
+    await writeVerifyContract(root, { branch: 'master', branchSource: 'cli_option', force: true });
+    await seedLifecycleRiskDecision(root, 'master');
+
+    const byId = await routeSddTask(root, { taskId: 'LOGIN-1', branch: 'master' });
+    const byText = await routeSddTask(root, { taskId: '做登录系统', branch: 'master' });
+
+    assert.equal(byId.taskId, 'LOGIN-1');
+    assert.equal(byText.taskId, 'LOGIN-1');
+    assert.equal(byText.stageRouteBinding?.status, 'bound');
+    assert.equal(byText.stageRouteBinding?.targetId, 'LOGIN-1');
+    assert.equal(byText.blockedReason, null);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('routeSddTask blocks ambiguous natural do text before implementation routing', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-route-ambiguous-binding-'));
+  try {
+    await initProject(root);
+    const apiTask = validTaskMarkdown('LOGIN-API', [])
+      .replace('Valid task', '登录系统接口')
+      .replace('Stay in parser files only.', '只实现登录系统接口。')
+      .replace('Parser behavior is covered.', '登录系统接口完成。')
+      .replace('packages/core/src/index.ts', 'packages/core/src/login-api.ts');
+    const pageTask = validTaskMarkdown('LOGIN-UI', [])
+      .replace('Valid task', '登录系统页面')
+      .replace('Stay in parser files only.', '只实现登录系统页面。')
+      .replace('Parser behavior is covered.', '登录系统页面完成。')
+      .replace('packages/core/src/index.ts', 'packages/core/src/login-ui.ts');
+    await writeBranchDocs(root, 'master', `# Tasks\n\n${apiTask}\n${pageTask}`);
+    await writeVerifyContract(root, { branch: 'master', branchSource: 'cli_option', force: true });
+    await seedLifecycleRiskDecision(root, 'master');
+
+    const decision = await routeSddTask(root, { taskId: '登录系统', branch: 'master' });
+
+    assert.equal(decision.category, 'blocked');
+    assert.equal(decision.recommendedProfile, null);
+    assert.equal(decision.stageRouteBinding?.status, 'ambiguous');
+    assert.deepEqual(decision.stageRouteBinding?.matchedRefs.map((ref) => ref.ref).sort(), ['task:LOGIN-API', 'task:LOGIN-UI']);
+    assert.match(decision.nextAction, /Ambiguous task text/);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('routeSddTask routes boundary-expanding natural do text back to lifecycle authority', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-route-boundary-expanding-'));
+  try {
+    await initProject(root);
+    const paymentTask = validTaskMarkdown('PAY-1', [])
+      .replace('Valid task', '支付系统')
+      .replace('Stay in parser files only.', '只实现支付系统边界。')
+      .replace('Parser behavior is covered.', '支付系统任务完成。');
+    await writeBranchDocs(root, 'master', `# Tasks\n\n${paymentTask}`);
+    await writeVerifyContract(root, { branch: 'master', branchSource: 'cli_option', force: true });
+    await seedLifecycleRiskDecision(root, 'master');
+
+    const decision = await routeSddTask(root, { taskId: '做登录系统', branch: 'master' });
+
+    assert.equal(decision.category, 'blocked');
+    assert.equal(decision.recommendedProfile, null);
+    assert.equal(decision.stageRouteBinding?.status, 'boundary_expanding');
+    assert.equal(decision.stageRouteBinding?.targetId, null);
+    assert.match(decision.nextAction, /Run \/sdd or \/sdd:spec/);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
 function capabilityRouteTaskMarkdown(taskId: string, title: string, affectedFiles: string[], risk: string[], validation: string[]): string {
   const affectedFilesBlock = affectedFiles.length === 0 ? 'affected_files: []' : `affected_files:\n${affectedFiles.map((file) => `  - ${file}`).join('\n')}`;
   const riskBlock = risk.length === 0 ? 'risk: []' : `risk:\n${risk.map((item) => `  - ${item}`).join('\n')}`;
@@ -426,4 +658,9 @@ allowed_agents:
 
 - ${title}.
 `;
+}
+
+async function seedLifecycleRiskDecision(root: string, branch: string): Promise<void> {
+  const model = await parseSddBranch(root, branch);
+  await recordLifecycleRiskDecisionProjection(root, evaluateLifecycleRiskDecisionForModel(branch, model));
 }

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

@@ -12,9 +12,10 @@ import { buildTeamModePolicy, resolveTeamModeActivation } from './team-mode.js';
 import { matchRoutingRules } from './routing-rules.js';
 import { chooseRecommendedProfile, deriveAllowedProfiles, toAgentProfileId } from './profile-resolution.js';
 import { adapterMappingForProfile, buildAgentCapabilityRouteDecision, buildRejectedProfiles, buildToolPermissionSpec, modelPolicyForProfile, quarantineWarningsForSources, routeCategory, routeRegistrySources, selectRequiredSkillCapabilities } from './route-projection.js';
-import { lifecycleAutonomyCeilingFromDecision, ensureLifecycleRiskDecision } from '../orchestration/runtime.js';
+import { lifecycleAutonomyCeilingFromDecision, resolveStageLocalLifecycleRiskDecision } from '../orchestration/runtime.js';
 import { taskAutonomyCeiling } from './risk-policy.js';
 import { evaluateTaskWorkflowGate } from '../risk.js';
+import { bindStageRouteForModel, recordStageRouteBindingProjection, type StageRouteBinding } from './stage-route-binding.js';
 import { nextDependencyTaskId, resolveTaskDependencyReadiness } from '../workflow-state/dependencies.js';
 import { selectLatestEligibleRunsByTask, type LatestEligibleRunSelection } from '../workflow-state/latest-eligible-run.js';
 import { readAllRunStates } from '../run-state/run-state.js';
@@ -56,49 +57,59 @@ export async function routeSddTask(projectRoot: string, options: { taskId: strin
   const context = await resolveSddContext(projectRoot, { branch: options.branch, branchSource: options.branch ? 'cli_option' : undefined });
   const branch = context.partition;
   const model = await parseSddBranch(projectRoot, branch);
+  const binding = await bindStageRouteForModel(projectRoot, { branch, model, entry: 'sdd:do', userText: options.taskId });
+  await recordStageRouteBindingProjection(projectRoot, binding);
+  const routedTaskId = binding.status === 'bound' && binding.targetId ? binding.targetId : options.taskId;
   const states = await readAllRunStates(projectRoot);
   const runtimeByTask = latestRuntimeTaskStates(selectLatestEligibleRunsByTask({ states, model, partition: branch, currentGitBranch: context.currentGitBranch }), states);
   profileSpans.push(runtimeProfileSpan('document_parse', branchStart));
-  const cacheKey = routeCacheKey({ taskId: options.taskId, branch, agent: options.agent ?? null, teamModeActivation: resolveTeamModeActivation(options, 'auto'), approved: options.approved, documents: model.documents });
+  const cacheKey = routeCacheKey({ taskId: routedTaskId, branch, agent: options.agent ?? null, teamModeActivation: resolveTeamModeActivation(options, 'auto'), approved: options.approved, documents: model.documents });
   const cachedDecision = options.cache ? await readRouteCache<AgentRouterDecision>(projectRoot, cacheKey) : null;
   if (cachedDecision) {
     return {
       ...cachedDecision,
+      taskId: routedTaskId,
+      stageRouteBinding: binding,
       cache: { contract: ROUTE_CACHE_CONTRACT_VERSION, key: cacheKey, status: 'hit', source: 'content_addressed_derived_route', authoritative: false },
       profile: options.profile ? [...(cachedDecision.profile ?? []), runtimeProfileSpan('route_total', routeStart, routeStartedAt)] : undefined
     };
   }
   const computeStart = Date.now();
-  const inspected = inspectSddTask(model, options.taskId);
+  const inspected = inspectSddTask(model, routedTaskId);
   const task = inspected.task;
   const blockingGap = inspected.gaps.find((gap) => gap.severity === 'blocking');
   const matchedRules = task && !blockingGap ? matchRoutingRules(task, registry) : [];
   const profileSelection = task && !blockingGap ? deriveAllowedProfiles(task, registry, matchedRules) : { profiles: [], resolvedAliases: [] };
   const delegatedProfile = task && !blockingGap && options.agent ? toAgentProfileId(options.agent, registry) : null;
   const allowedProfiles = delegatedProfile && !profileSelection.profiles.includes(delegatedProfile) ? [...profileSelection.profiles, delegatedProfile] : profileSelection.profiles;
-  const riskDecision = task ? await ensureLifecycleRiskDecision(projectRoot, model, { branch, task }) : null;
-  const workflowGate = evaluateTaskWorkflowGate({ task, taskId: options.taskId, riskDecision, approved: options.approved });
-  const lifecycleBlockedReason = workflowGate.blocksRoute
-    ? workflowGate.primaryReason
-    : null;
-  const dependencyReadiness = task ? resolveTaskDependencyReadiness(model, options.taskId, { runtimeByTask }) : null;
+  const lifecycle = task && binding.status === 'bound' ? await resolveStageLocalLifecycleRiskDecision(projectRoot, model, { branch }) : null;
+  const riskDecision = lifecycle?.decision ?? null;
+  const gateRiskDecision = lifecycle && lifecycle.status !== 'fresh' ? lifecycle.decision : null;
+  const workflowGate = evaluateTaskWorkflowGate({ task, taskId: routedTaskId, riskDecision: gateRiskDecision, approved: options.approved });
+  const lifecycleBlockedReason = lifecycle && lifecycle.status !== 'fresh'
+    ? lifecycle.reasons[0] ?? workflowGate.primaryReason
+    : workflowGate.blocksRoute
+      ? workflowGate.primaryReason
+      : null;
+  const bindingBlockedReason = binding.status === 'bound' ? null : binding.reasons[0] ?? 'Stage route binding did not resolve to an executable target.';
+  const dependencyReadiness = task ? resolveTaskDependencyReadiness(model, routedTaskId, { runtimeByTask }) : null;
   const dependencyBlockedReason = dependencyReadiness?.blockingReasons[0] ?? null;
-  const dependencyTaskId = task ? nextDependencyTaskId(model, options.taskId, { runtimeByTask }) : null;
+  const dependencyTaskId = task ? nextDependencyTaskId(model, routedTaskId, { runtimeByTask }) : null;
   const taskRecommendedProfile = task && !blockingGap && !dependencyBlockedReason && !lifecycleBlockedReason ? chooseRecommendedProfile(task, allowedProfiles, registry, matchedRules) : null;
   const recommendedProfile = dependencyBlockedReason || lifecycleBlockedReason ? null : delegatedProfile ?? taskRecommendedProfile;
   const category = task ? routeCategory(task, blockingGap, allowedProfiles, matchedRules) : 'blocked';
-  const autonomyCeiling = riskDecision ? lifecycleAutonomyCeilingFromDecision(riskDecision) : task ? taskAutonomyCeiling(task) : 'research_before_implementation';
+  const autonomyCeiling = gateRiskDecision ? lifecycleAutonomyCeilingFromDecision(gateRiskDecision) : task ? taskAutonomyCeiling(task) : 'research_before_implementation';
   const requiredCapabilities = task && recommendedProfile ? selectRequiredSkillCapabilities(task, recommendedProfile, registry, matchedRules) : [];
   const sourceCapability = requiredCapabilities[0] ?? null;
   const sourceCapabilityContract = sourceCapability ? registry.skillCapabilities.find((capability) => capability.id === sourceCapability) ?? null : null;
-  const blockedReason = !task ? `Task ${options.taskId} was not found.` : blockingGap?.message ?? dependencyBlockedReason ?? lifecycleBlockedReason;
+  const blockedReason = bindingBlockedReason ?? (!task ? `Task ${routedTaskId} was not found.` : blockingGap?.message ?? dependencyBlockedReason ?? lifecycleBlockedReason);
   const routedCategory = blockedReason ? 'blocked' : category;
   const registrySources = routeRegistrySources(registry, recommendedProfile, requiredCapabilities);
   const adapterMapping = recommendedProfile ? adapterMappingForProfile(registry, recommendedProfile) : null;
   const capabilityDecision = buildAgentCapabilityRouteDecision(task ?? null, routedCategory, autonomyCeiling, registry, capabilityCatalog);
   const decision: AgentRouterDecision = {
     version: AGENT_ROUTER_CONTRACT_VERSION,
-    taskId: options.taskId,
+    taskId: routedTaskId,
     branch,
     category: routedCategory,
     recommendedProfile,
@@ -125,7 +136,8 @@ export async function routeSddTask(projectRoot: string, options: { taskId: strin
     primaryReason: workflowGate.primaryReason,
     requiredArtifacts: task?.requiredArtifacts ?? [],
     blockedReason,
-    nextAction: routeNextAction({ taskId: options.taskId, taskExists: Boolean(task), hasBlockingGap: Boolean(blockingGap), dependencyTaskId, blockedReason, workflowGateNextAction: workflowGate.nextAction, recommendedProfile, requiredCapabilities }),
+    nextAction: routeNextAction({ taskId: routedTaskId, taskExists: Boolean(task), bindingNextAction: stageBindingNextAction(binding), hasBlockingGap: Boolean(blockingGap), dependencyTaskId, blockedReason, workflowGateNextAction: workflowGate.nextAction, recommendedProfile, requiredCapabilities }),
+    stageRouteBinding: binding,
     capabilityDecision,
     registrySources,
     resolvedAliases: profileSelection.resolvedAliases,
@@ -164,6 +176,7 @@ function latestRuntimeTaskStates(selections: LatestEligibleRunSelection[], state
 function routeNextAction(input: {
   taskId: string;
   taskExists: boolean;
+  bindingNextAction: string | null;
   hasBlockingGap: boolean;
   dependencyTaskId: string | null;
   blockedReason: string | null;
@@ -171,6 +184,9 @@ function routeNextAction(input: {
   recommendedProfile: string | null;
   requiredCapabilities: string[];
 }): string {
+  if (input.bindingNextAction) {
+    return input.bindingNextAction;
+  }
   if (!input.taskExists) {
     return `Create or restore task ${input.taskId} before routing.`;
   }
@@ -179,7 +195,7 @@ function routeNextAction(input: {
   }
   if (input.dependencyTaskId) {
     return input.blockedReason?.includes('has not passed required verification')
-      ? `Run sdd test task ${input.dependencyTaskId} before routing ${input.taskId}.`
+      ? `Run sdd test task-${input.dependencyTaskId} before routing ${input.taskId}.`
       : `Run sdd do task ${input.dependencyTaskId} before routing ${input.taskId}.`;
   }
   if (input.workflowGateNextAction) {
@@ -189,4 +205,20 @@ function routeNextAction(input: {
     return `Use ${input.recommendedProfile} with ${input.requiredCapabilities.join(',') || 'no extra capability'} and preserve required artifacts before verify.`;
   }
   return `Declare a routable profile before routing ${input.taskId}.`;
+}
+
+function stageBindingNextAction(binding: StageRouteBinding): string | null {
+  if (binding.status === 'bound') {
+    return null;
+  }
+  if (binding.nextAction === 'route_to_lifecycle_decision') {
+    return 'Run /sdd or /sdd:spec to create or refresh the lifecycle decision, then return to /sdd:do.';
+  }
+  if (binding.nextAction === 'ask_clarification') {
+    return binding.reasons[0] ?? 'Clarify the target task id or task title before running /sdd:do.';
+  }
+  if (binding.nextAction === 'runtime_repair_required') {
+    return binding.reasons[0] ?? 'Repair stale upstream runtime state before running /sdd:do.';
+  }
+  return binding.reasons[0] ?? 'Stage route binding blocked this local entry.';
 }