scene-capability-engine 3.6.29 → 3.6.32

package/lib/commands/studio.js

@@ -1,4 +1,4 @@
-const path = require('path');
+const path = require('path');
 const crypto = require('crypto');
 const { spawnSync } = require('child_process');
 const fs = require('fs-extra');
@@ -20,6 +20,13 @@ const {
   runStudioSpecGovernance,
   runStudioSceneBackfill
 } = require('../studio/spec-intake-governor');
+const { attachTaskFeedbackModel } = require('../magicball/task-feedback-model');
+const { deriveTaskIntentShape, buildTaskSummaryLines, buildTaskAcceptanceCriteria } = require('../studio/task-intent');
+const {
+  buildStudioTaskKey,
+  resolveTaskReference: resolveSharedTaskReference,
+  buildCommandPayload: buildSharedCommandPayload
+} = require('../studio/task-envelope');
 
 const STUDIO_JOB_API_VERSION = 'sce.studio.job/v0.1';
 const STAGE_ORDER = ['plan', 'generate', 'apply', 'verify', 'release'];
@@ -1230,490 +1237,6 @@ function extractErrorsFromStageMetadata(stageState = {}, stageMetadata = {}) {
   return [...directErrors, ...gateStepErrors];
 }
 
-function collectTaskFileChanges(job = {}, stageName = '', stageMetadata = {}) {
-  const fileChanges = [];
-  if (Array.isArray(stageMetadata && stageMetadata.file_changes)) {
-    fileChanges.push(...stageMetadata.file_changes);
-  }
-
-  const createdSpec = job?.source?.intake?.created_spec;
-  const createdSpecId = createdSpec && createdSpec.created
-    ? normalizeString(createdSpec.spec_id)
-    : '';
-  if (stageName === 'plan' && createdSpecId) {
-    fileChanges.push(
-      { path: `.sce/specs/${createdSpecId}/requirements.md`, line: 1 },
-      { path: `.sce/specs/${createdSpecId}/design.md`, line: 1 },
-      { path: `.sce/specs/${createdSpecId}/tasks.md`, line: 1 },
-      { path: `.sce/specs/${createdSpecId}/custom/problem-domain-chain.json`, line: 1 },
-      { path: `.sce/specs/${createdSpecId}/custom/problem-contract.json`, line: 1 }
-    );
-  }
-
-  const artifacts = job && job.artifacts ? job.artifacts : {};
-  if (stageName === 'plan') {
-    if (normalizeString(artifacts.spec_portfolio_report)) {
-      fileChanges.push({ path: artifacts.spec_portfolio_report, line: 1 });
-    }
-    if (normalizeString(artifacts.spec_scene_index)) {
-      fileChanges.push({ path: artifacts.spec_scene_index, line: 1 });
-    }
-  }
-  if (stageName === 'generate' && normalizeString(artifacts.generate_report)) {
-    fileChanges.push({ path: artifacts.generate_report, line: 1 });
-  }
-  if (stageName === 'verify' && normalizeString(artifacts.verify_report)) {
-    fileChanges.push({ path: artifacts.verify_report, line: 1 });
-  }
-  if (stageName === 'release' && normalizeString(artifacts.release_report)) {
-    fileChanges.push({ path: artifacts.release_report, line: 1 });
-  }
-  return normalizeTaskFileChanges(fileChanges);
-}
-
-function collectTaskEvidence(job = {}, stageName = '', stageMetadata = {}) {
-  const evidence = [];
-  const stageReport = normalizeString(stageMetadata && stageMetadata.report);
-  if (stageReport) {
-    evidence.push({ type: 'stage-report', ref: stageReport, detail: stageName });
-  }
-
-  const artifacts = job && job.artifacts ? job.artifacts : {};
-  if (stageName && artifacts.problem_eval_reports && artifacts.problem_eval_reports[stageName]) {
-    evidence.push({
-      type: 'problem-evaluation-report',
-      ref: artifacts.problem_eval_reports[stageName],
-      detail: stageName
-    });
-  }
-
-  if (normalizeString(job?.source?.domain_chain?.chain_path)) {
-    evidence.push({
-      type: 'domain-chain',
-      ref: job.source.domain_chain.chain_path,
-      detail: stageName
-    });
-  }
-  if (normalizeString(job?.source?.problem_contract_path)) {
-    evidence.push({
-      type: 'problem-contract',
-      ref: job.source.problem_contract_path,
-      detail: stageName
-    });
-  }
-  if (Array.isArray(stageMetadata && stageMetadata.auto_errorbook_records)) {
-    for (const item of stageMetadata.auto_errorbook_records) {
-      const entryId = normalizeString(item && item.entry_id);
-      if (!entryId) {
-        continue;
-      }
-      evidence.push({
-        type: 'errorbook-entry',
-        ref: entryId,
-        detail: normalizeString(item && item.step_id) || null
-      });
-    }
-  }
-
-  if (normalizeString(job && job.job_id)) {
-    evidence.push({
-      type: 'event-log',
-      ref: '.sce/state/sce-state.sqlite',
-      detail: `studio_event_stream:job_id=${job.job_id}`
-    });
-  }
-
-  return normalizeTaskEvidence(evidence);
-}
-
-function buildTaskSummaryLines(job = {}, stageName = '', taskStatus = '', nextAction = '', taskRef = '') {
-  const sceneId = normalizeString(job?.scene?.id) || 'scene.n/a';
-  const specId = normalizeString(job?.scene?.spec_id) || normalizeString(job?.source?.spec_id) || 'spec.n/a';
-  const progress = buildProgress(job);
-  return [
-    `Stage: ${stageName || 'plan'} | Status: ${taskStatus || 'unknown'}${taskRef ? ` | Ref: ${taskRef}` : ''}`,
-    `Scene: ${sceneId} | Spec: ${specId} | Progress: ${progress.completed}/${progress.total}`,
-    `Next: ${nextAction || 'n/a'}`
-  ];
-}
-
-function truncateTaskText(value = '', maxLength = 96) {
-  const normalized = normalizeString(value).replace(/\s+/g, ' ');
-  if (!normalized) {
-    return '';
-  }
-  if (normalized.length <= maxLength) {
-    return normalized;
-  }
-  return `${normalized.slice(0, Math.max(0, maxLength - 3)).trim()}...`;
-}
-
-function dedupeTaskList(items = [], limit = 3) {
-  const seen = new Set();
-  const result = [];
-  for (const item of items) {
-    const normalized = truncateTaskText(item, 120);
-    if (!normalized) {
-      continue;
-    }
-    const key = normalized.toLowerCase();
-    if (seen.has(key)) {
-      continue;
-    }
-    seen.add(key);
-    result.push(normalized);
-    if (result.length >= limit) {
-      break;
-    }
-  }
-  return result;
-}
-
-function splitTaskRawRequest(rawRequest = '') {
-  const normalized = normalizeString(rawRequest).replace(/\s+/g, ' ');
-  if (!normalized) {
-    return [];
-  }
-  const chunks = normalized
-    .split(/(?:\r?\n|[;；。!?！？]|(?:\s+\band\b\s+)|(?:\s+\bthen\b\s+)|(?:\s+\balso\b\s+)|(?:\s*并且\s*)|(?:\s*同时\s*)|(?:\s*以及\s*)|(?:\s*然后\s*))/gi)
-    .map((item) => normalizeString(item).replace(/^(?:and|then|also)\s+/i, ''))
-    .filter(Boolean);
-  return dedupeTaskList(chunks, 3);
-}
-
-function deriveTaskIntentShape(rawRequest = '', stageName = '') {
-  const normalizedRaw = normalizeString(rawRequest).replace(/\s+/g, ' ');
-  const clauses = splitTaskRawRequest(normalizedRaw);
-  const hasRaw = normalizedRaw.length > 0;
-  const inferredSubGoals = clauses.length > 1 ? clauses.slice(0, 3) : [];
-  const needsSplit = inferredSubGoals.length > 1;
-  const titleSource = clauses.length > 0
-    ? clauses[0]
-    : (hasRaw ? normalizedRaw : `Studio ${stageName || 'task'} execution`);
-
-  let confidence = hasRaw ? 0.9 : 0.6;
-  if (needsSplit) {
-    confidence = 0.72;
-  }
-  if (normalizeString(stageName) && normalizeString(stageName) !== 'plan') {
-    confidence = Math.min(0.95, confidence + 0.03);
-  }
-
-  return {
-    title_norm: truncateTaskText(titleSource, 96) || `Studio ${stageName || 'task'} execution`,
-    raw_request: hasRaw ? normalizedRaw : null,
-    sub_goals: inferredSubGoals,
-    needs_split: needsSplit,
-    confidence: Number(confidence.toFixed(2))
-  };
-}
-
-function buildTaskAcceptanceCriteria(stageName = '', job = {}, nextAction = '') {
-  const normalizedStage = normalizeString(stageName) || 'task';
-  const artifacts = job && job.artifacts ? job.artifacts : {};
-  const criteriaByStage = {
-    plan: [
-      'Scene/spec binding is resolved and persisted in studio job metadata.',
-      'Plan stage problem evaluation passes with no blockers.',
-      `Next action is executable (${nextAction || 'sce studio generate --job <job-id>'}).`
-    ],
-    generate: [
-      'Patch bundle id is produced for downstream apply stage.',
-      'Generate stage report is written to artifacts.',
-      `Next action is executable (${nextAction || 'sce studio apply --patch-bundle <id> --job <job-id>'}).`
-    ],
-    apply: [
-      'Authorization requirements are satisfied for apply stage.',
-      'Apply stage completes without policy blockers.',
-      `Next action is executable (${nextAction || 'sce studio verify --job <job-id>'}).`
-    ],
-    verify: [
-      'Verification gates finish with no required-step failures.',
-      `Verify report is available (${normalizeString(artifacts.verify_report) || 'artifact pending'}).`,
-      `Next action is executable (${nextAction || 'sce studio release --job <job-id>'}).`
-    ],
-    release: [
-      'Release gates pass under configured release profile.',
-      `Release reference is emitted (${normalizeString(artifacts.release_ref) || 'artifact pending'}).`,
-      `Next action is executable (${nextAction || 'complete'}).`
-    ],
-    rollback: [
-      'Rollback stage transitions job status to rolled_back.',
-      'Rollback evidence is appended to studio event stream.',
-      `Recovery next action is executable (${nextAction || 'sce studio plan --scene <scene-id> --from-chat <session>'}).`
-    ],
-    events: [
-      'Events stream payload is available for task-level audit.',
-      'Task envelope preserves normalized IDs and handoff fields.',
-      `Next action is explicit (${nextAction || 'n/a'}).`
-    ],
-    resume: [
-      'Current job status and stage progress are restored deterministically.',
-      'Task envelope remains schema-compatible for downstream UI.',
-      `Next action is explicit (${nextAction || 'n/a'}).`
-    ]
-  };
-  return criteriaByStage[normalizedStage] || [
-    'Task envelope contains normalized identifiers and task contract fields.',
-    'Task output preserves evidence, command logs, and error bundles.',
-    `Next action is explicit (${nextAction || 'n/a'}).`
-  ];
-}
-
-function buildTaskFeedbackModel(payload = {}) {
-  const task = payload && payload.task && typeof payload.task === 'object' ? payload.task : {};
-  const handoff = task && typeof task.handoff === 'object' ? task.handoff : {};
-  const errors = Array.isArray(task.errors) ? task.errors : [];
-  const commands = Array.isArray(task.commands) ? task.commands : [];
-  const fileChanges = Array.isArray(task.file_changes) ? task.file_changes : [];
-  const evidence = Array.isArray(task.evidence) ? task.evidence : [];
-  const acceptance = Array.isArray(task.acceptance_criteria) ? task.acceptance_criteria : [];
-  const firstError = errors[0] || {};
-  const stage = normalizeString(handoff.stage) || 'task';
-  const status = normalizeString(task.status) || 'unknown';
-  const problemComponent = normalizeString(handoff.component) || normalizeString(payload.sceneId) || null;
-  const expected = normalizeString(acceptance[0]) || ('Complete ' + stage + ' stage successfully');
-  const actual = normalizeString(firstError.message) || ('Current status: ' + status);
-
-  let chainCheckpoint = 'task-envelope';
-  if (errors.length > 0 && commands.length > 0) {
-    chainCheckpoint = 'command-execution';
-  } else if (errors.length > 0) {
-    chainCheckpoint = 'stage-gate';
-  } else if (fileChanges.length > 0) {
-    chainCheckpoint = 'patch-applied';
-  } else if (evidence.length > 0) {
-    chainCheckpoint = 'evidence-collected';
-  }
-
-  let confidence = 'low';
-  if (errors.length > 0) {
-    confidence = 'medium';
-  } else if (status === 'completed') {
-    confidence = 'high';
-  }
-
-  let recommendedAction = '继续当前阶段';
-  if (errors.length > 0) {
-    recommendedAction = '处理阻断后重试';
-  } else if (status === 'completed' && normalizeString(task.next_action) && normalizeString(task.next_action) !== 'complete') {
-    recommendedAction = '执行下一阶段';
-  } else if (status === 'completed') {
-    recommendedAction = '任务完成';
-  }
-
-  return {
-    version: '1.0',
-    problem: {
-      component: problemComponent,
-      action: normalizeString(handoff.action) || stage,
-      expected,
-      actual
-    },
-    execution: {
-      stage,
-      status,
-      summary: Array.isArray(task.summary) ? task.summary.slice(0, 3) : [],
-      blocking_summary: normalizeString(handoff.blocking_summary) || normalizeString(firstError.message) || null
-    },
-    diagnosis: {
-      hypothesis: normalizeString(firstError.error_bundle) || normalizeString(firstError.message) || normalizeString(handoff.reason) || null,
-      chain_checkpoint: chainCheckpoint,
-      root_cause_confidence: confidence
-    },
-    evidence: {
-      file_count: fileChanges.length,
-      file_paths: fileChanges.slice(0, 5).map((item) => normalizeString(item && item.path)).filter(Boolean),
-      command_count: commands.length,
-      error_count: errors.length,
-      verification_result: status === 'completed' ? 'passed-or-advanced' : (errors.length > 0 ? 'blocked' : 'in-progress'),
-      regression_scope: Array.isArray(handoff.regression_scope) ? handoff.regression_scope : []
-    },
-    next_step: {
-      recommended_action: recommendedAction,
-      next_action: normalizeString(task.next_action) || null,
-      next_command: normalizeString(task.next_action) || null
-    }
-  };
-}
-
-function buildMagicballStatusLanguage(input = {}) {
-  const attention = normalizeString(input.attention_level) || 'medium';
-  const status = normalizeString(input.status) || 'unknown';
-  const blockingSummary = normalizeString(input.blocking_summary) || null;
-  const recommendedAction = normalizeString(input.recommended_action) || null;
-  return {
-    attention_level: attention,
-    status_tone: attention === 'critical' ? 'danger' : (attention === 'high' ? 'warning' : (attention === 'low' ? 'success' : 'info')),
-    status_label: status || 'unknown',
-    blocking_summary: blockingSummary,
-    recommended_action: recommendedAction
-  };
-}
-
-function attachTaskFeedbackModel(payload = {}) {
-  if (!payload || typeof payload !== 'object' || !payload.task || typeof payload.task !== 'object') {
-    return payload;
-  }
-  return {
-    ...payload,
-    task: {
-      ...payload.task,
-      feedback_model: (() => { const model = buildTaskFeedbackModel(payload); return { ...model, mb_status: buildMagicballStatusLanguage({ status: model.execution.status, attention_level: model.diagnosis.root_cause_confidence === 'high' ? 'high' : (model.execution.status === 'completed' ? 'low' : 'medium'), blocking_summary: model.execution.blocking_summary, recommended_action: model.next_step.recommended_action }) }; })()
-    }
-  };
-}
-function buildTaskEnvelope(mode, job, options = {}) {
-  const stageName = resolveTaskStage(mode, job, options.stageName);
-  const stageState = stageName && job && job.stages && job.stages[stageName]
-    ? job.stages[stageName]
-    : {};
-  const stageMetadata = stageState && typeof stageState.metadata === 'object' && stageState.metadata
-    ? stageState.metadata
-    : {};
-  const nextAction = resolveNextAction(job);
-
-  const events = Array.isArray(options.events)
-    ? options.events
-    : (options.event ? [options.event] : []);
-  const latestEvent = events.length > 0 ? events[events.length - 1] : null;
-
-  const taskStatus = normalizeString(stageState && stageState.status)
-    || (stageName === 'rollback' && normalizeString(job && job.status) === 'rolled_back'
-      ? 'completed'
-      : normalizeString(job && job.status) || 'unknown');
-  const taskId = normalizeString(options.taskId)
-    || (normalizeString(job && job.job_id)
-      ? `${job.job_id}:${stageName || 'task'}`
-      : null);
-  const rawRequest = normalizeString(job?.source?.goal);
-  const goal = rawRequest
-    || `Studio ${stageName || 'task'} execution`;
-  const taskIntent = deriveTaskIntentShape(rawRequest, stageName);
-  const sessionId = normalizeString(job?.session?.scene_session_id) || null;
-  const sceneId = normalizeString(job?.scene?.id) || null;
-  const specId = normalizeString(job?.scene?.spec_id) || normalizeString(job?.source?.spec_id) || null;
-  const taskRef = normalizeString(options.taskRef) || null;
-
-  const commands = normalizeTaskCommands([
-    ...(Array.isArray(stageMetadata.commands) ? stageMetadata.commands : []),
-    ...extractCommandsFromStageMetadata(stageMetadata)
-  ]);
-  const errors = normalizeTaskErrors(
-    extractErrorsFromStageMetadata(stageState, stageMetadata)
-  );
-  const fileChanges = collectTaskFileChanges(job, stageName, stageMetadata);
-  const evidence = collectTaskEvidence(job, stageName, stageMetadata);
-
-  const handoff = stageMetadata.handoff && typeof stageMetadata.handoff === 'object'
-    ? stageMetadata.handoff
-    : {
-      stage: stageName,
-      status: taskStatus,
-      completed_at: normalizeString(stageState && stageState.completed_at) || null,
-      report: normalizeString(stageMetadata.report) || null,
-      release_ref: normalizeString(stageMetadata.release_ref) || normalizeString(job?.artifacts?.release_ref) || null
-    };
-
-  const normalizedHandoff = {
-    ...handoff,
-    task_ref: taskRef
-  };
-
-  return {
-    sessionId,
-    sceneId,
-    specId,
-    taskId,
-    taskRef,
-    eventId: normalizeString(latestEvent && latestEvent.event_id) || null,
-    task: {
-      ref: taskRef,
-      task_ref: taskRef,
-      title_norm: taskIntent.title_norm,
-      raw_request: taskIntent.raw_request,
-      goal,
-      sub_goals: taskIntent.sub_goals,
-      acceptance_criteria: buildTaskAcceptanceCriteria(stageName, job, nextAction),
-      needs_split: taskIntent.needs_split,
-      confidence: taskIntent.confidence,
-      status: taskStatus,
-      summary: buildTaskSummaryLines(job, stageName, taskStatus, nextAction, taskRef),
-      handoff: normalizedHandoff,
-      next_action: nextAction,
-      file_changes: fileChanges,
-      commands,
-      errors,
-      evidence
-    },
-    event: events
-  };
-}
-
-function toRelativePosix(projectPath, absolutePath) {
-  return path.relative(projectPath, absolutePath).replace(/\\/g, '/');
-}
-
-async function readSpecDomainChain(projectPath, specId, fileSystem = fs) {
-  const specRoot = path.join(projectPath, '.sce', 'specs', specId);
-  const chainPath = path.join(specRoot, DOMAIN_CHAIN_RELATIVE_PATH);
-  if (!await fileSystem.pathExists(chainPath)) {
-    return null;
-  }
-  try {
-    const payload = await fileSystem.readJson(chainPath);
-    const stat = await fileSystem.stat(chainPath);
-    return {
-      spec_id: specId,
-      chain_path: toRelativePosix(projectPath, chainPath),
-      payload,
-      updated_at: stat && stat.mtime ? stat.mtime.toISOString() : null,
-      mtime_ms: Number(stat && stat.mtimeMs) || 0
-    };
-  } catch (_error) {
-    return null;
-  }
-}
-
-async function readSpecProblemContract(projectPath, specId, fileSystem = fs) {
-  const specRoot = path.join(projectPath, '.sce', 'specs', specId);
-  const contractPath = path.join(specRoot, DEFAULT_PROBLEM_CONTRACT_RELATIVE_PATH);
-  if (!await fileSystem.pathExists(contractPath)) {
-    return null;
-  }
-  try {
-    const payload = await fileSystem.readJson(contractPath);
-    const stat = await fileSystem.stat(contractPath);
-    return {
-      spec_id: specId,
-      contract_path: toRelativePosix(projectPath, contractPath),
-      payload,
-      updated_at: stat && stat.mtime ? stat.mtime.toISOString() : null,
-      mtime_ms: Number(stat && stat.mtimeMs) || 0
-    };
-  } catch (_error) {
-    return null;
-  }
-}
-
-async function readGovernanceSignals(projectPath, fileSystem = fs) {
-  const reportPath = path.join(projectPath, DEFAULT_INTERACTIVE_GOVERNANCE_REPORT);
-  if (!await fileSystem.pathExists(reportPath)) {
-    return {
-      available: false,
-      report_path: null,
-      high_breach_count: 0,
-      medium_breach_count: 0
-    };
-  }
-  const payload = await fileSystem.readJson(reportPath).catch(() => null);
-  const summary = extractGovernanceBreachSignals(payload || {});
-  return {
-    ...summary,
-    report_path: toRelativePosix(projectPath, reportPath)
-  };
-}
-
 async function readVerifyReportSignals(projectPath, verifyReportPath = '', fileSystem = fs) {
   const normalized = normalizeString(verifyReportPath);
   if (!normalized) {
@@ -1807,6 +1330,70 @@ function normalizeProblemContract(contract = {}, context = {}) {
   };
 }
 
+function toRelativePosix(projectPath, absolutePath) {
+  return path.relative(projectPath, absolutePath).replace(/\\/g, '/');
+}
+
+async function readSpecDomainChain(projectPath, specId, fileSystem = fs) {
+  const specRoot = path.join(projectPath, '.sce', 'specs', specId);
+  const chainPath = path.join(specRoot, DOMAIN_CHAIN_RELATIVE_PATH);
+  if (!await fileSystem.pathExists(chainPath)) {
+    return null;
+  }
+  try {
+    const payload = await fileSystem.readJson(chainPath);
+    const stat = await fileSystem.stat(chainPath);
+    return {
+      spec_id: specId,
+      chain_path: toRelativePosix(projectPath, chainPath),
+      payload,
+      updated_at: stat && stat.mtime ? stat.mtime.toISOString() : null,
+      mtime_ms: Number(stat && stat.mtimeMs) || 0
+    };
+  } catch (_error) {
+    return null;
+  }
+}
+
+async function readSpecProblemContract(projectPath, specId, fileSystem = fs) {
+  const specRoot = path.join(projectPath, '.sce', 'specs', specId);
+  const contractPath = path.join(specRoot, DEFAULT_PROBLEM_CONTRACT_RELATIVE_PATH);
+  if (!await fileSystem.pathExists(contractPath)) {
+    return null;
+  }
+  try {
+    const payload = await fileSystem.readJson(contractPath);
+    const stat = await fileSystem.stat(contractPath);
+    return {
+      spec_id: specId,
+      contract_path: toRelativePosix(projectPath, contractPath),
+      payload,
+      updated_at: stat && stat.mtime ? stat.mtime.toISOString() : null,
+      mtime_ms: Number(stat && stat.mtimeMs) || 0
+    };
+  } catch (_error) {
+    return null;
+  }
+}
+
+async function readGovernanceSignals(projectPath, fileSystem = fs) {
+  const reportPath = path.join(projectPath, DEFAULT_INTERACTIVE_GOVERNANCE_REPORT);
+  if (!await fileSystem.pathExists(reportPath)) {
+    return {
+      available: false,
+      report_path: null,
+      high_breach_count: 0,
+      medium_breach_count: 0
+    };
+  }
+  const payload = await fileSystem.readJson(reportPath).catch(() => null);
+  const summary = extractGovernanceBreachSignals(payload || {});
+  return {
+    ...summary,
+    report_path: toRelativePosix(projectPath, reportPath)
+  };
+}
+
 function extractGovernanceBreachSignals(report = {}) {
   if (!report || typeof report !== 'object') {
     return {
@@ -2049,109 +1636,38 @@ async function resolveDomainChainBinding(options = {}, dependencies = {}) {
   };
 }
 
-function printStudioPayload(payload, options = {}) {
-  if (options.json) {
-    console.log(JSON.stringify(payload, null, 2));
-    return;
-  }
-
-  console.log(chalk.blue(`Studio job: ${payload.job_id}`));
-  console.log(`  Status: ${payload.status}`);
-  console.log(`  Progress: ${payload.progress.completed}/${payload.progress.total} (${payload.progress.percent}%)`);
-  console.log(`  Next: ${payload.next_action}`);
-}
-
-function ensureStageCompleted(job, stageName, metadata = {}) {
-  if (!job.stages || !job.stages[stageName]) {
-    job.stages = job.stages || createStageState();
-    job.stages[stageName] = { status: 'pending', completed_at: null, metadata: {} };
-  }
-
-  job.stages[stageName] = {
-    status: 'completed',
-    completed_at: nowIso(),
-    metadata
-  };
-}
-
-function isStageCompleted(job, stageName) {
-  return Boolean(job && job.stages && job.stages[stageName] && job.stages[stageName].status === 'completed');
-}
-
-function ensureStagePrerequisite(job, stageName, prerequisiteStage) {
-  if (!isStageCompleted(job, prerequisiteStage)) {
-    throw new Error(`Cannot run studio ${stageName}: stage "${prerequisiteStage}" is not completed`);
-  }
-}
-
-function ensureNotRolledBack(job, stageName) {
-  if (job.status === 'rolled_back') {
-    throw new Error(`Cannot run studio ${stageName}: job ${job.job_id} is rolled back`);
-  }
-}
-
-function buildStudioTaskKey(stageName = '') {
-  const normalizedStage = normalizeString(stageName) || 'task';
-  return `studio:${normalizedStage}`;
-}
-
-async function resolveTaskReference(mode, job, options = {}) {
-  const explicitTaskRef = normalizeString(options.taskRef);
-  if (explicitTaskRef) {
-    return explicitTaskRef;
-  }
-
-  const sceneId = normalizeString(job?.scene?.id);
-  const specId = normalizeString(job?.scene?.spec_id) || normalizeString(job?.source?.spec_id);
-  if (!sceneId || !specId) {
-    return null;
-  }
-
-  const stageName = resolveTaskStage(mode, job, options.stageName);
-  const taskKey = normalizeString(options.taskKey) || buildStudioTaskKey(stageName);
-  const projectPath = normalizeString(options.projectPath) || process.cwd();
-  const fileSystem = options.fileSystem || fs;
-  const taskRefRegistry = options.taskRefRegistry || new TaskRefRegistry(projectPath, { fileSystem });
-
-  try {
-    const taskRef = await taskRefRegistry.resolveOrCreateRef({
-      sceneId,
-      specId,
-      taskKey,
-      source: 'studio-stage',
-      metadata: {
-        mode: normalizeString(mode) || null,
-        stage: stageName || null,
-        job_id: normalizeString(job?.job_id) || null
-      }
-    });
-    return taskRef.task_ref;
-  } catch (_error) {
-    return null;
-  }
+function resolveTaskReference(mode, job, options = {}, dependencies = {}) {
+  return resolveSharedTaskReference(mode, job, options, {
+    normalizeString,
+    resolveTaskStage,
+    TaskRefRegistry,
+    fileSystem: dependencies.fileSystem || options.fileSystem || fs
+  });
 }
 
 async function buildCommandPayload(mode, job, options = {}) {
-  const taskRef = await resolveTaskReference(mode, job, options);
-  const base = {
-    mode,
-    success: true,
-    job_id: job.job_id,
-    status: job.status,
-    progress: buildProgress(job),
-    next_action: resolveNextAction(job),
-    artifacts: { ...job.artifacts }
-  };
-  return attachTaskFeedbackModel({
-    ...base,
-    ...buildTaskEnvelope(mode, job, {
-      ...options,
-      taskRef
-    })
+  return buildSharedCommandPayload(mode, job, options, {
+    normalizeString,
+    resolveTaskStage,
+    resolveNextAction,
+    normalizeTaskCommands,
+    normalizeTaskErrors,
+    normalizeTaskEvidence,
+    normalizeTaskFileChanges,
+    extractCommandsFromStageMetadata,
+    extractErrorsFromStageMetadata,
+    deriveTaskIntentShape,
+    buildTaskSummaryLines,
+    buildTaskAcceptanceCriteria,
+    buildProgress,
+    TaskRefRegistry,
+    fileSystem: options.fileSystem || fs,
+    attachTaskFeedbackModel
   });
 }
 
 function buildJobDomainChainMetadata(job = {}) {
+
   const domainChain = job && job.source && job.source.domain_chain
     ? job.source.domain_chain
     : null;
@@ -2312,6 +1828,19 @@ async function markStudioStageBlockedByProblemEval(paths, job, stageName, evalua
   throw new Error(`studio ${stageName} blocked by problem evaluation: ${reason}`);
 }
 
+function printStudioPayload(payload, options = {}) {
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  console.log(chalk.blue(`Studio job: ${payload.job_id}`));
+  console.log(`  Status: ${payload.status}`);
+  console.log(`  Progress: ${payload.progress.completed}/${payload.progress.total} (${payload.progress.percent}%)`);
+  console.log(`  Next: ${payload.next_action}`);
+}
+
+
 async function runStudioPlanCommand(options = {}, dependencies = {}) {
   const projectPath = dependencies.projectPath || process.cwd();
   const fileSystem = dependencies.fileSystem || fs;
@@ -2656,6 +2185,36 @@ async function runStudioPlanCommand(options = {}, dependencies = {}) {
   return payload;
 }
 
+function ensureStageCompleted(job, stageName, metadata = {}) {
+  if (!job.stages || !job.stages[stageName]) {
+    job.stages = job.stages || createStageState();
+    job.stages[stageName] = { status: 'pending', completed_at: null, metadata: {} };
+  }
+
+  job.stages[stageName] = {
+    status: 'completed',
+    completed_at: nowIso(),
+    metadata
+  };
+}
+
+function isStageCompleted(job, stageName) {
+  return Boolean(job && job.stages && job.stages[stageName] && job.stages[stageName].status === 'completed');
+}
+
+function ensureStagePrerequisite(job, stageName, prerequisiteStage) {
+  if (!isStageCompleted(job, prerequisiteStage)) {
+    throw new Error(`Cannot run studio ${stageName}: stage "${prerequisiteStage}" is not completed`);
+  }
+}
+
+function ensureNotRolledBack(job, stageName) {
+  if (job.status === 'rolled_back') {
+    throw new Error(`Cannot run studio ${stageName}: job ${job.job_id} is rolled back`);
+  }
+}
+
+
 async function runStudioGenerateCommand(options = {}, dependencies = {}) {
   const projectPath = dependencies.projectPath || process.cwd();
   const fileSystem = dependencies.fileSystem || fs;
@@ -3741,9 +3300,15 @@ module.exports = {
   runStudioReleaseCommand,
   runStudioRollbackCommand,
   runStudioEventsCommand,
-  buildMagicballStatusLanguage,
   runStudioPortfolioCommand,
   runStudioBackfillSpecScenesCommand,
   runStudioResumeCommand,
   registerStudioCommands
 };
+
+
+
+
+
+
+