create-yss-spec 3.5.0 → 3.5.3

package/template/scripts/lib/lifecycle-status.mjs

@@ -0,0 +1,137 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { parseDocument } from '../vendor/yaml.mjs';
+import { safeTrackingPath, trackingDrift } from './stage-tracking.mjs';
+
+const sha = bytes => `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+function parse(bytes) {
+  const document = parseDocument(String(bytes), { uniqueKeys: true, maxAliasCount: 0 });
+  if (document.errors.length) throw new TypeError(document.errors[0].message);
+  return document.toJS({ maxAliasCount: 0 });
+}
+function source(root, ref) {
+  const bytes = readFileSync(safeTrackingPath(root, ref));
+  return { value: parse(bytes), digest: sha(bytes) };
+}
+
+/** Read-only projection; checkpoint, registry and orchestration remain authoritative. */
+export function lifecycleStatus({ root, checkpointRef, taskPackageRef }) {
+  if (!root || !checkpointRef) throw new TypeError('root and checkpoint are required');
+  root = path.resolve(root);
+  const identity = source(root, 'yss-project.yaml').value;
+  if (identity.schema_version !== 1 || identity.repository_mode !== 'project-instance') throw new TypeError('生命周期状态仅适用于 project-instance');
+  const registryRef = '.template-spec/process/lifecycle-registry.yaml';
+  const contractRef = '.agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml';
+  const checkpoint = source(root, checkpointRef), registry = source(root, registryRef), contract = source(root, contractRef);
+  const value = checkpoint.value;
+  if (value.schema_version !== 1 || value.repository_mode !== 'project-instance') throw new TypeError('checkpoint 身份或版本无效');
+  const items = value.stage_tracking?.items ?? [];
+  if (!Array.isArray(items)) throw new TypeError('阶段追踪 items 必须为数组');
+  const activeItems = items.filter(item => item.work_unit === value.next_work_unit && item.progress !== 'cancelled');
+  const owner = value.pause?.owner_or_authority ?? activeItems.find(item => item.progress !== 'completed')?.owner ?? '未登记';
+  const diagnostics = [], verification_scope = [];
+  const check = (id, status, refs, reason) => verification_scope.push({ id, status, refs, reason });
+  const issue = (code, message, source_ref, recovery, severity = 'error') => diagnostics.push({ code, message, source_ref, owner, recovery, severity });
+  if (!Object.hasOwn(value, 'blockers')) {
+    issue('registered-blockers-missing', 'checkpoint 缺少 blockers；不能据此判定无已登记阻塞', checkpointRef, '核对原始状态并补齐真实阻塞记录后重验');
+  } else if (!Array.isArray(value.blockers)) {
+    issue('registered-blockers-invalid', 'checkpoint.blockers 必须为数组；当前登记不可核验', checkpointRef, '修复阻塞记录类型，保留原有阻塞内容后重验');
+  } else {
+    for (const item of value.blockers) {
+      issue('registered-blocker', typeof item === 'string' ? item : JSON.stringify(item), checkpointRef, '按原阻塞证据处理并复验');
+    }
+  }
+  check('registered-blockers', diagnostics.length ? 'failed' : 'passed', [checkpointRef], '仅读取已登记阻塞，不代表完整就绪');
+  const stage = registry.value.stages?.find(item => item.id === value.stage);
+  const workUnit = registry.value.work_units?.find(item => item.id === value.next_work_unit);
+  if (!stage) issue('unknown-stage', `未知阶段: ${value.stage}`, registryRef, '按注册表核对当前阶段');
+  if (value.next_work_unit && !workUnit) issue('unknown-work-unit', `未知下一工作单元: ${value.next_work_unit}`, registryRef, '按注册表核对下一工作单元');
+  if (workUnit && workUnit.id !== 'work-unit.entry-triage' && !contract.value.work_unit_routes?.[workUnit.id]) issue('missing-route', `缺少执行路由: ${workUnit.id}`, contractRef, '修复当前合同路由后重验');
+  check('stage-and-route', diagnostics.some(x => ['unknown-stage', 'unknown-work-unit', 'missing-route'].includes(x.code)) ? 'failed' : 'passed', [registryRef, contractRef], '仅检查身份与路由存在，不计算完整 frontier');
+  if (value.context_reconciliation?.status === 'blocked') issue('context-blocked', 'Context reconciliation blocked', checkpointRef, '修复词汇对账并执行适用校验');
+  check('context-reconciliation', value.context_reconciliation?.status === 'blocked' ? 'failed' : 'not-checked', [value.context_reconciliation?.ref].filter(Boolean), '读取登记状态；当前对账内容和摘要仍须由原验证器核验');
+  for (const [id, gate] of Object.entries(value.gates ?? {})) {
+    if (['blocked', 'stale'].includes(gate?.status)) issue('gate-blocked', `${id}: ${gate.status}`, checkpointRef, '核对受影响依据和当前批准');
+  }
+  check('registered-gates', diagnostics.some(x => x.code === 'gate-blocked') ? 'failed' : 'passed', [checkpointRef], '仅检查登记的 blocked/stale 标志');
+  const evidenceRefs = [value.context_reconciliation?.ref, ...Object.values(value.artifacts ?? {}).filter(item => item?.status === 'approved').map(item => item.ref)].filter(Boolean);
+  for (const ref of evidenceRefs) {
+    try { readFileSync(safeTrackingPath(root, ref)); }
+    catch { issue('evidence-unreadable', `证据不可读: ${ref}`, ref, '恢复正确来源或重新取得证据，不伪造历史批准'); }
+  }
+  check('evidence-readable', diagnostics.some(x => x.code === 'evidence-unreadable') ? 'failed' : 'passed', evidenceRefs, '仅检查已引用证据可读，不证明证据完整或当前有效');
+  check('artifact-digests', 'not-checked', evidenceRefs, '未核验批准资产原字节摘要；恢复时运行资产所有者的适用预检');
+  check('approval-validity', 'not-checked', [checkpointRef], '未核验真实决定、延续、外部审批及完整执行授权');
+  if (value.stage_tracking?.items) {
+    try {
+      const drift = trackingDrift(root, value.stage_tracking);
+      for (const id of drift) issue('tracking-drift', `阶段工作项来源漂移: ${id}`, checkpointRef, '按依赖重验受影响项，保留未受影响记录');
+      check('stage-tracking', drift.length ? 'failed' : 'passed', [checkpointRef], '只核对已登记工作项来源及完成证据摘要；结构与流转仍须原预检');
+    } catch (error) {
+      issue('tracking-unverifiable', `阶段追踪不可核验: ${error.message}`, checkpointRef, '修复追踪输入后重新检查');
+      check('stage-tracking', 'failed', [checkpointRef], error.message);
+    }
+  } else {
+    check('stage-tracking', 'not-checked', [checkpointRef], '未登记追踪；按实例既有兼容或显式迁移入口处理，不自动补建');
+  }
+  if (value.status === 'blocked' && !diagnostics.some(x => x.severity === 'error')) issue('reason-missing', 'checkpoint 已标 blocked，原因未登记', checkpointRef, '补齐真实阻塞原因');
+  let taskSource, task, contractSource;
+  const recovery = {sequence: ['read-status', 'inspect-actual-result', 'verify-current-inputs', 'continue-or-reroute'], task_package_ref: taskPackageRef ?? null, contract_view: null, result_refs: [], prechecks: [], verification_items: [], checks: 'read-only; execution and approval not evaluated'};
+  if(taskPackageRef) {
+    try {
+      taskSource=source(root,taskPackageRef);task=taskSource.value;
+      if(task.work_unit_id!==value.next_work_unit && task.convergence?.parent_work_unit!==value.next_work_unit)throw Error('任务包与 checkpoint 工作单元不一致');
+      if(!['not-started','active','paused','resolved','failed'].includes(task.workflow_status))throw Error('任务运行状态未知');
+      recovery.prechecks.push({status:'not-checked',cwd:root,command:['node','scripts/verify-digital-human-task-package',taskPackageRef]});
+      if(task.contract?.kind==='slice-implementation') {
+        contractSource=source(root,task.contract.slice_contract_ref);
+        const c=contractSource.value.slice_contract||contractSource.value;
+        if(c.contract_id!==task.contract.contract_id||c.contract_version!==task.contract.contract_version)throw Error('任务与当前合同版本不一致');
+        recovery.contract_view={cwd:root,command:['node','scripts/contract','view',task.contract.slice_contract_ref,'--kind','slice','--profile','task','--unit',task.work_unit_id]};
+        const approval=task.contract.gate_refs?.[0];
+        recovery.prechecks.push({status:'not-checked',cwd:root,command:['node','scripts/slice-contract','verify',task.contract.slice_contract_ref,'--unit',task.work_unit_id,...(approval?['--approval-ref',approval]:[])],approval_scope:approval?'current-approval-required':'not-checked: approval reference missing'});
+        if(c.schema_version===3){
+          const unit=c.work_units?.find(x=>x.id===task.work_unit_id);
+          if(!unit)throw Error('当前合同不存在该工作单元');
+          recovery.verification_items=Object.entries(c.verification||{}).filter(([id,check])=>unit.verification_refs?.includes(id)||check.required_for_all===true).map(([id,check])=>({id,...check,status:'not-checked'}));
+        }
+      }
+      recovery.result_refs=[...new Set([...(task.result?.evidence_refs||[]),...(task.verification_results||[]).map(x=>x.evidence_ref)].filter(Boolean))];
+      for(const ref of recovery.result_refs)readFileSync(safeTrackingPath(root,ref));
+      check('task-recovery','passed',[taskPackageRef,...recovery.result_refs],'仅读取任务身份、状态和结果引用；继续前仍须正式验收');
+    } catch(error) {issue('task-recovery-invalid',error.message,taskPackageRef,'核对任务身份与实际结果，再执行适用预检');}
+  }
+  const blockers = [...new Set(diagnostics.filter(x => x.severity === 'error').map(x => x.message))];
+  const next_step = {
+    action_type: 'verify', work_unit: value.next_work_unit ?? null, cwd: root,
+    command: null, input_refs: [checkpointRef,...(taskPackageRef?[taskPackageRef]:[])],
+    prerequisites: ['核验当前来源、Context、适用门禁与决定或延续', '核对当前范围、任务结果和允许写路径；输入变化时重验'],
+  };
+  let next_action;
+  if (blockers.length) {
+    next_step.action_type = 'repair';
+    next_action = `处理当前阻塞：${blockers[0]}`;
+  } else if (value.status === 'paused-human-gate') {
+    next_step.action_type = 'wait';
+    next_action = '核对当前会签责任方、资产与决定范围；满足已登记恢复条件后复验';
+  } else if (activeItems.some(item => item.progress === 'running') || task?.workflow_status === 'active') {
+    next_step.action_type = 'inspect';
+    next_action = '核对运行中任务身份与实际结果；状态未知时不得重复派发';
+  } else if ((activeItems.length && activeItems.every(item => item.progress === 'completed')) || task?.workflow_status === 'resolved') {
+    next_step.action_type = 'inspect';
+    next_action = '核验已有完成证据并重算下一工作单元，不直接重做';
+  } else {
+    next_action = value.next_work_unit ? `先核验当前输入及适用门禁，再由主控恢复 ${value.next_work_unit}` : '复核当前阶段验收与下一动作';
+    // Commands are argv arrays. They are recommendations, never executed by this view.
+    const script = value.next_work_unit === 'work-unit.spec-synthesis' ? 'scripts/verify-plan-spec-entry' : 'scripts/verify-lifecycle-checkpoint';
+    try { readFileSync(safeTrackingPath(root, script)); next_step.command = ['node', script, checkpointRef]; }
+    catch { issue('precheck-unavailable', `预检入口不可读: ${script}`, script, '补齐当前实例工具后执行预检', 'warning'); }
+  }
+  return {
+    schema_version: 1, read_only: true, stage: value.stage, checkpoint_status: value.status,
+    work_unit: value.next_work_unit ?? null, owner, blockers, next_action,
+    execution_authorization: 'not-evaluated', verification_scope, diagnostics, next_step, recovery,
+    source_digests: { checkpoint: { ref: checkpointRef, digest: checkpoint.digest }, registry: { ref: registryRef, digest: registry.digest }, orchestration: { ref: contractRef, digest: contract.digest }, ...(taskSource?{task:{ref:taskPackageRef,digest:taskSource.digest}}:{}), ...(contractSource?{slice_contract:{ref:task.contract.slice_contract_ref,digest:contractSource.digest}}:{}) },
+  };
+}

package/template/scripts/lib/lifecycle-transition.mjs

@@ -12,11 +12,15 @@ import path from "node:path";
 import { validateApiContractDecision } from "./api-contract-decision.mjs";
 import { loadApprovalRecord, validateApprovalRecord } from "./approval-record.mjs";
 import { validateBackendReview } from "./backend-review.mjs";
+import { validateJsonSchema } from "./json-schema.mjs";
 import { ROOT } from "./lifecycle-registry.mjs";
+import { readRepositoryMode } from './repository-mode.mjs';
+import { validateResearchCompletion } from './maintenance-research.mjs';
 
 const IMPLEMENTATION_WORK_UNIT = "work-unit.slice-implementation";
 const TICKET_DECOMPOSITION_WORK_UNIT = "work-unit.ticket-decomposition";
 const REPOSITORY_PREPARATION_WORK_UNIT = "work-unit.implementation-repository-preparation";
+const SERVICE_INITIALIZATION_WORK_UNIT = "work-unit.service-project-initialization";
 
 function deepFreeze(value) {
   if (!value || typeof value !== "object" || Object.isFrozen(value)) return value;
@@ -26,22 +30,24 @@ function deepFreeze(value) {
 }
 
 const NEXT_ROUTES = deepFreeze({
+  "work-unit.maintenance-research": ["work-unit.ssot-update"],
   "work-unit.entry-triage": ["work-unit.plan-opportunity", "work-unit.plan-requirements"],
-  "work-unit.ssot-update": ["work-unit.skill-projection-sync", "work-unit.intensity-aware-verification"],
-  "work-unit.skill-projection-sync": ["work-unit.template-snapshot-build", "work-unit.intensity-aware-verification"],
-  "work-unit.template-snapshot-build": ["work-unit.attach-sync-integration", "work-unit.intensity-aware-verification"],
-  "work-unit.attach-sync-integration": ["work-unit.intensity-aware-verification"],
-  "work-unit.intensity-aware-verification": ["work-unit.intensity-aware-review"],
-  "work-unit.intensity-aware-review": ["work-unit.release-and-rollback"],
+  "work-unit.ssot-update": ["work-unit.skill-projection-sync", "work-unit.intensity-aware-verification-v2"],
+  "work-unit.skill-projection-sync": ["work-unit.template-snapshot-build", "work-unit.intensity-aware-verification-v2"],
+  "work-unit.template-snapshot-build": ["work-unit.attach-sync-integration", "work-unit.intensity-aware-verification-v2"],
+  "work-unit.attach-sync-integration": ["work-unit.intensity-aware-verification-v2"],
+  "work-unit.intensity-aware-verification-v2": ["work-unit.intensity-aware-review-v2"],
+  "work-unit.intensity-aware-review-v2": ["work-unit.release-and-rollback"],
   "work-unit.release-and-rollback": [],
   "work-unit.plan-opportunity": ["work-unit.plan-requirements", "work-unit.domain-strategy-design", "work-unit.stage-decision", "work-unit.spec-synthesis"],
   "work-unit.plan-requirements": ["work-unit.domain-strategy-design", "work-unit.stage-decision", "work-unit.spec-synthesis"],
   "work-unit.domain-strategy-design": ["work-unit.stage-decision", "work-unit.spec-synthesis"],
   "work-unit.stage-decision": ["work-unit.spec-synthesis"],
-  "work-unit.spec-synthesis": ["work-unit.prototype-design", "work-unit.technical-analysis"],
-  "work-unit.prototype-design": ["work-unit.technical-analysis"],
+  "work-unit.spec-synthesis": ["work-unit.prototype-design-v2", "work-unit.technical-analysis"],
+  "work-unit.prototype-design-v2": ["work-unit.technical-analysis"],
   "work-unit.technical-analysis": [REPOSITORY_PREPARATION_WORK_UNIT],
-  [REPOSITORY_PREPARATION_WORK_UNIT]: [TICKET_DECOMPOSITION_WORK_UNIT],
+  [REPOSITORY_PREPARATION_WORK_UNIT]: [SERVICE_INITIALIZATION_WORK_UNIT, TICKET_DECOMPOSITION_WORK_UNIT],
+  [SERVICE_INITIALIZATION_WORK_UNIT]: [REPOSITORY_PREPARATION_WORK_UNIT],
   [TICKET_DECOMPOSITION_WORK_UNIT]: [IMPLEMENTATION_WORK_UNIT],
   [IMPLEMENTATION_WORK_UNIT]: ["work-unit.frontend-implementation-verification", "work-unit.code-review"],
   "work-unit.frontend-implementation-verification": ["work-unit.code-review"],
@@ -83,6 +89,8 @@ const BLOCKING_SIGNALS = Object.freeze({
   backendDesignPrerequisitesMissing: "backend-design-prerequisites-missing",
   legacyScaffoldReconciliationRequired: "legacy-scaffold-reconciliation-required",
   prematureImplementationDetected: "premature-implementation-detected",
+  serviceInitializationInvalid: "service-project-initialization-invalid",
+  serviceInitializationIncomplete: "service-project-initialization-incomplete",
 });
 
 const allowedResult = (evidenceRefs = []) => ({
@@ -121,6 +129,52 @@ function readDecompositionResult(ref, read) {
   }
 }
 
+/** The service branch reuses the approved v4 scaffold contract and its real verification. */
+export function validateServiceProjectInitialization(state, { root = ROOT, exists = existsSync, read = (ref) => readFileSync(ref, "utf8"), completed = false } = {}) {
+  const request = state?.service_project_initialization;
+  const resolved = ref => path.isAbsolute(ref) ? ref : path.resolve(root, ref);
+  const present = ref => hasText(ref) && exists(resolved(ref));
+  const contents = ref => read(resolved(ref));
+  const document = ref => readDecompositionResult(resolved(ref), contents);
+  const blocked = (detail, incomplete = false) => blockedResult(
+    [incomplete ? BLOCKING_SIGNALS.serviceInitializationIncomplete : BLOCKING_SIGNALS.serviceInitializationInvalid], [detail]);
+  if (!request || !hasText(request.project_id) || !hasText(request.contract_ref) || !hasText(request.contract_digest) || !hasText(request.project_root)) return blocked("project_id, contract_ref, contract_digest and project_root required");
+  const contractFile = resolved(request.contract_ref);
+  if (!present(contractFile)) return blocked("approved v4 scaffold contract must be readable");
+  let contractBytes;
+  try { contractBytes = contents(contractFile); } catch { return blocked("approved v4 scaffold contract must be readable"); }
+  const contract = document(contractFile);
+  if (!contract || request.contract_digest !== `sha256:${createHash("sha256").update(contractBytes).digest("hex")}`) return blocked("current scaffold contract digest mismatch");
+  try { validateJsonSchema(contract, path.join(ROOT, ".template-spec/process/schemas/project-scaffold-contract.schema.json")); }
+  catch (error) { return blocked(`scaffold contract schema: ${error.message}`); }
+  if (contract.schema_version !== 4 || contract.status !== "approved" || contract.current_version !== true || !hasText(contract.persisted_ref) || contract.architecture_profile !== "mvc-data-analysis-v1" || contract.scaffold_kind !== "backend-mvc-data-analysis" || contract.generator_skill !== "yss-layered-mvc-scaffold-generator" || contract.init_git !== true || contract.project_name !== request.project_id || path.resolve(contract.target_output_dir, contract.project_name) !== path.resolve(request.project_root)) return blocked("current approved mvc-data-analysis-v1 initialization contract required");
+  const contractRoot = path.dirname(contractFile);
+  const contractExists = ref => exists(path.isAbsolute(ref) ? ref : path.resolve(contractRoot, ref));
+  if (!backendDesignPrerequisitesReady(contract.design_prerequisites, contractExists, contractRoot, request.project_id)) return blocked("current technical, data, API and engineering approval bindings required");
+  const handoff = path.resolve(path.dirname(contractFile), contract.context_handoff_ref ?? "");
+  if (!handoff.startsWith(`${path.dirname(contractFile)}${path.sep}`) || !present(handoff)) return blocked("CONTEXT handoff must be inside the contract directory");
+  let handoffBytes;
+  try { handoffBytes = contents(handoff); } catch { return blocked("CONTEXT handoff must be readable"); }
+  const handoffDigest = `sha256:${createHash("sha256").update(handoffBytes).digest("hex")}`;
+  if (contract.context_handoff_digest !== handoffDigest || request.context_handoff_digest !== handoffDigest) return blocked("CONTEXT handoff digest mismatch");
+  if (!completed) {
+    if (present(request.project_root)) return blocked("service project already exists; initialization is not repeatable");
+    return allowedResult([request.contract_ref, contract.context_handoff_ref]);
+  }
+  for (const field of ["manifest_ref", "verification_ref", "result_ref"]) if (!present(request[field])) return blocked(`${field} must be readable`, true);
+  const manifest = document(request.manifest_ref);
+  const verification = document(request.verification_ref);
+  const result = document(request.result_ref);
+  if (result?.result_schema !== "workflow-execution-result-v1" || result.work_unit !== SERVICE_INITIALIZATION_WORK_UNIT || result.result !== "completed" || ![request.manifest_ref, request.verification_ref].every(ref => result.evidence_refs?.includes(ref))) return blocked("completed Workflow Execution Result with manifest and verification evidence required", true);
+  if (manifest?.schema_version !== 4 || manifest.kind !== "service-project-initialization" || manifest.architecture_profile !== "mvc-data-analysis-v1" || manifest.project_name !== request.project_id || manifest.contract_digest !== request.contract_digest || manifest.completion_level !== "empty-scaffold-verified") return blocked("current v4 service Manifest required", true);
+  const phases = ["validate", "test", "package"];
+  if (verification?.status !== "passed" || verification.completion_level !== "empty-scaffold-verified" || path.resolve(verification.project_root ?? "") !== path.resolve(request.project_root) || !Array.isArray(verification.commands) || phases.some(phase => !verification.commands.some(item => item.phase === phase && item.exit_code === 0 && item.command?.startsWith(`./mvnw ${phase}`) && present(item.stdout_ref) && present(item.stderr_ref)))) return blocked("real Maven Wrapper validate/test/package evidence required", true);
+  const childContext = path.join(request.project_root, "CONTEXT.md");
+  const initialization = document(path.join(request.project_root, ".template-spec/process/service-initialization.json"));
+  if (!present(childContext) || !present(path.join(request.project_root, ".git")) || !present(path.join(path.dirname(request.project_root), "skillUtils/skills-lock.json")) || contents(childContext) !== handoffBytes || initialization?.contract_id !== contract.contract_id || initialization.context_handoff_digest !== handoffDigest) return blocked("child project identity, CONTEXT and skillUtils must match the contract", true);
+  return allowedResult([request.result_ref, request.manifest_ref, request.verification_ref]);
+}
+
 function artifactBindingReady(binding, exists) {
   return hasText(binding?.ref) && /^v[1-9][0-9]*$/.test(binding?.version ?? "") && /^sha256:[a-f0-9]{64}$/.test(binding?.digest ?? "") && isReadable(binding.ref, exists);
 }
@@ -252,6 +306,21 @@ function validateTicketReference(ref, trackerKind) {
  * by `validateWorkflowExecutionResult` before this function is called.
  */
 export function validateNextRoute(currentWorkUnit, nextRoute, decisionState, options = {}) {
+  let entryRoutes;
+  if (currentWorkUnit === 'work-unit.entry-triage' || currentWorkUnit === 'work-unit.maintenance-research' || nextRoute === 'work-unit.maintenance-research') {
+    try {
+      const mode = readRepositoryMode(options.root || ROOT);
+      if (currentWorkUnit === 'work-unit.entry-triage') entryRoutes = mode === 'template-source'
+        ? ['work-unit.maintenance-research', 'work-unit.ssot-update'] : NEXT_ROUTES[currentWorkUnit];
+      if ((currentWorkUnit === 'work-unit.maintenance-research' || nextRoute === 'work-unit.maintenance-research') && mode !== 'template-source') throw Error('template-research-requires-template-source');
+      if (currentWorkUnit === 'work-unit.maintenance-research') {
+        assertScopeTransition(currentWorkUnit, nextRoute, decisionState, options);
+        if (nextRoute !== null && nextRoute !== 'work-unit.ssot-update') return blockedResult([BLOCKING_SIGNALS.invalidRoute]);
+        validateResearchCompletion(decisionState, {root: options.root || ROOT, continuing: nextRoute !== null});
+        return allowedResult(decisionState.evidence_refs);
+      }
+    } catch (error) { return blockedResult(['maintenance-research-boundary'], [error.message]); }
+  }
   try { assertTrackingTransition(currentWorkUnit, nextRoute, decisionState, { root: options.root || ROOT }); }
   catch (error) { return blockedResult(['stage-tracking-blocked'], [error.message]); }
   try { assertScopeTransition(currentWorkUnit, nextRoute, decisionState, options); }
@@ -269,9 +338,9 @@ export function validateNextRoute(currentWorkUnit, nextRoute, decisionState, opt
     try { enforceFrontendDelivery(decisionState, { root: options.root, phase: nextRoute === IMPLEMENTATION_WORK_UNIT ? "implementation" : "inputs" }); }
     catch (error) { return blockedResult(["frontend-delivery-blocked"], [error.message]); }
   }
-  const routes = NEXT_ROUTES[currentWorkUnit] && scopedNextRoutes(currentWorkUnit, NEXT_ROUTES[currentWorkUnit], options);
+  const routes = NEXT_ROUTES[currentWorkUnit] && scopedNextRoutes(currentWorkUnit, entryRoutes || NEXT_ROUTES[currentWorkUnit], options);
   if (!routes) return blockedResult([BLOCKING_SIGNALS.invalidRoute], ["known_current_work_unit"]);
-  if (nextRoute === REPOSITORY_PREPARATION_WORK_UNIT && currentWorkUnit !== "work-unit.technical-analysis") {
+  if (nextRoute === REPOSITORY_PREPARATION_WORK_UNIT && !["work-unit.technical-analysis", SERVICE_INITIALIZATION_WORK_UNIT].includes(currentWorkUnit)) {
     return blockedResult([BLOCKING_SIGNALS.technicalAnalysisRequired], ["work-unit.technical-analysis predecessor"]);
   }
   if (nextRoute === null && routes.length === 0) {
@@ -285,6 +354,12 @@ export function validateNextRoute(currentWorkUnit, nextRoute, decisionState, opt
     }
     return blockedResult(signals, ["allowed_next_route"]);
   }
+  if (nextRoute === SERVICE_INITIALIZATION_WORK_UNIT) {
+    return validateServiceProjectInitialization(decisionState, { ...options, completed: false });
+  }
+  if (currentWorkUnit === SERVICE_INITIALIZATION_WORK_UNIT && nextRoute === REPOSITORY_PREPARATION_WORK_UNIT) {
+    return validateServiceProjectInitialization(decisionState, { ...options, completed: true });
+  }
   if (nextRoute === REPOSITORY_PREPARATION_WORK_UNIT) {
     const analysis = validateTechnicalAnalysisCompletion(decisionState, options);
     if (analysis.result === "blocked") return analysis;
@@ -294,6 +369,10 @@ export function validateNextRoute(currentWorkUnit, nextRoute, decisionState, opt
     if (entry.result === 'blocked' || nextRoute === 'work-unit.spec-synthesis') return entry;
   }
   if (nextRoute === TICKET_DECOMPOSITION_WORK_UNIT) {
+    if (decisionState?.service_project_initialization) {
+      const service = validateServiceProjectInitialization(decisionState, { ...options, completed: true });
+      if (service.result === "blocked") return service;
+    }
     const readiness = validateImplementationRepositoriesReady(decisionState, options);
     if (readiness.result === "blocked") return readiness;
   }

package/template/scripts/lib/maintenance-research.mjs

@@ -0,0 +1,63 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {spawnSync} from 'node:child_process';
+import {safe, hash, parse, ensure} from './strategic-handoff-io.mjs';
+import {assertUserDecisionRequirement} from './user-decision.mjs';
+
+export const RESEARCH_VALIDATOR = '.agents/skills/yss-research/scripts/validate-research-package.mjs';
+const binding = (root, ref) => ({ref, digest: hash(fs.readFileSync(safe(root, ref)))});
+function readBound(root, bound) {
+  ensure(bound && binding(root, bound.ref).digest === bound.digest, 'research-evidence-stale');
+  return fs.readFileSync(safe(root, bound.ref));
+}
+function execute(root, brief, evidence) {
+  return spawnSync(process.execPath, [safe(root, RESEARCH_VALIDATOR), safe(root, brief), safe(root, evidence)], {
+    cwd: root, encoding: 'utf8', timeout: 30000, maxBuffer: 2 * 1024 * 1024,
+    env: {...process.env, NODE_OPTIONS: '', NODE_PATH: ''},
+  });
+}
+
+/** Capture actual validator output; never overwrite a historical run. */
+export function recordResearchVerification(root, brief, evidence, output) {
+  const inputs = {brief: binding(root, brief), evidence: binding(root, evidence), validator: binding(root, RESEARCH_VALIDATOR)};
+  const dir = safe(root, output, {missing: true});
+  ensure(!fs.existsSync(dir), '研究验证输出目录必须不存在');
+  const started_at = new Date().toISOString(), result = execute(root, brief, evidence);
+  fs.mkdirSync(dir, {recursive: true});
+  fs.writeFileSync(path.join(dir, 'stdout.log'), result.stdout || '');
+  fs.writeFileSync(path.join(dir, 'stderr.log'), result.stderr || result.error?.message || '');
+  const record = {schema_version: 1, kind: 'maintenance-research-verification', inputs,
+    command: ['node', RESEARCH_VALIDATOR, brief, evidence], started_at, completed_at: new Date().toISOString(),
+    exit_code: result.status, stdout: binding(root, `${output}/stdout.log`), stderr: binding(root, `${output}/stderr.log`)};
+  for (const value of Object.values(inputs)) readBound(root, value);
+  fs.writeFileSync(path.join(dir, 'verification.json'), JSON.stringify(record, null, 2) + '\n');
+  return {binding: binding(root, `${output}/verification.json`), exit_code: result.status};
+}
+
+export function validateResearchCompletion(state, {root, continuing = false}) {
+  ensure(state?.context_reconciliation?.status === 'not-applicable' && state.context_reconciliation.reason?.trim(), 'research-context-reason-missing');
+  fs.readFileSync(safe(root, state.context_reconciliation.ref));
+  for (const key of ['blocking_signals', 'drift', 'violation', 'new_impacts', 'stale_candidates']) {
+    ensure(Array.isArray(state[key]) && state[key].length === 0, `research-${key}-unresolved`);
+  }
+  const record = parse(readBound(root, state.research_verification));
+  ensure(record.schema_version === 1 && record.kind === 'maintenance-research-verification', 'research-verification-invalid');
+  for (const key of ['brief', 'evidence', 'validator']) readBound(root, record.inputs?.[key]);
+  ensure(record.inputs.validator.ref === RESEARCH_VALIDATOR, 'research-validator-mismatch');
+  ensure(record.exit_code === 0 && Number.isFinite(Date.parse(record.started_at)) && Date.parse(record.completed_at) >= Date.parse(record.started_at), 'research-verification-not-passed');
+  ensure(JSON.stringify(record.command) === JSON.stringify(['node', RESEARCH_VALIDATOR, record.inputs.brief.ref, record.inputs.evidence.ref]), 'research-command-mismatch');
+  readBound(root, record.stdout); readBound(root, record.stderr);
+  for (const ref of [state.context_reconciliation.ref, state.research_verification.ref, record.inputs.brief.ref, record.inputs.evidence.ref]) {
+    ensure(state.evidence_refs?.includes(ref), `research-evidence-unreferenced: ${ref}`);
+  }
+  const current = execute(root, record.inputs.brief.ref, record.inputs.evidence.ref);
+  ensure(!current.error && current.status === 0, 'research-current-validation-failed');
+  readBound(root, state.research_verification);
+  for(const value of Object.values(record.inputs))readBound(root,value);
+  if (continuing) {
+    const authorization = parse(readBound(root, state.maintenance_authorization));
+    ensure(authorization.boundary === 'template-maintenance-scope' && authorization.scope?.includes('work-unit.ssot-update'), 'maintenance-authorization-required');
+    assertUserDecisionRequirement(authorization, {root});
+  }
+  return record;
+}

package/template/scripts/lib/openapi-draft-validation.mjs

@@ -83,7 +83,7 @@ function verifyOperations(document, resolveReference) {
   }
 }
 
-export function validateOpenApiDraftValidationRecord(recordFile, { root = TEMPLATE_ROOT, allowTemplate = false, schemaPath = path.join(TEMPLATE_ROOT, "docs/process/schemas/openapi-draft-validation-record.schema.json") } = {}) {
+export function validateOpenApiDraftValidationRecord(recordFile, { root = TEMPLATE_ROOT, allowTemplate = false, schemaPath = path.join(TEMPLATE_ROOT, ".template-spec/process/schemas/openapi-draft-validation-record.schema.json") } = {}) {
   const projectRoot = path.resolve(root);
   const recordDocument = parseDocument(readFileSync(recordFile, "utf8"), { uniqueKeys: true, maxAliasCount: 0 });
   ensure(!recordDocument.errors.length, `validation record YAML 无效: ${recordDocument.errors[0]?.message}`);

package/template/scripts/lib/plan-spec-entry-view.mjs

@@ -0,0 +1,48 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { parseDocument } from '../vendor/yaml.mjs';
+import { safeTrackingPath } from './stage-tracking.mjs';
+
+const digest = bytes => `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+const read = (root, ref) => readFileSync(safeTrackingPath(root, ref));
+const parse = bytes => {
+  const document = parseDocument(String(bytes), { uniqueKeys: true, maxAliasCount: 0 });
+  if (document.errors.length) throw new TypeError(document.errors[0].message);
+  return document.toJS({ maxAliasCount: 0 });
+};
+
+/** Draft data only: no checks, impacts, approvals or user decisions are inferred. */
+export function preparePlanSpecEntry({ root, featureId, planRef, contextRef }) {
+  if (![root, featureId, planRef, contextRef].every(value => typeof value === 'string' && value.trim())) throw new TypeError('root, feature, plan and context-reconciliation are required');
+  const identity = parse(read(root, 'yss-project.yaml'));
+  if (identity.schema_version !== 1 || identity.repository_mode !== 'project-instance') throw new TypeError('Plan 入口仅适用于 project-instance');
+  const registryRef = '.template-spec/process/lifecycle-registry.yaml';
+  const registry = parse(read(root, registryRef));
+  const policy = registry.stages?.find(stage => stage.id === 'stage.plan')?.spec_entry;
+  if (!policy?.required_checks?.length) throw new TypeError('Plan 入口检查合同缺失');
+  const refs = [...new Set([planRef, 'CONTEXT.md', registryRef, contextRef])];
+  const basis = refs.map(ref => ({ ref, digest: digest(read(root, ref)) }));
+  const review_candidate = {
+    schema_version: 1, kind: 'plan-entry-review', gate_id: 'gate.plan-approved', feature_id: featureId,
+    plan_ref: planRef, context_reconciliation_ref: contextRef, basis,
+    checks: Object.fromEntries(policy.required_checks.map(id => [id, { status: 'pending', evidence_refs: [] }])),
+    open_items: [],
+    impacts: Object.fromEntries(Object.values(policy.check_impacts ?? {}).map(impact => [impact, null])),
+    internal_checks: Object.fromEntries(Object.keys(policy.check_impacts ?? {}).map(id => [id, { status: 'pending', evidence_refs: [] }])),
+  };
+  return { schema_version: 1, status: 'draft', review_candidate, missing_requirements: ['补齐检查证据与影响判断', '展示当前审阅包并提供真实用户决定，或按用户决定协议核验绑定当前范围的 plan_continuation_ref；未知或实质变化须重新决定'], approval_created: false };
+}
+
+export function diffPlanSpecEntry({ root, reviewRef }) {
+  if (!root || !reviewRef) throw new TypeError('root and review are required');
+  const review = parse(read(root, reviewRef));
+  if (review.kind !== 'plan-entry-review' || review.schema_version !== 1 || !Array.isArray(review.basis)) throw new TypeError('不是 Plan 入口审阅包');
+  const changed_refs = [], missing_refs = [];
+  for (const item of review.basis) {
+    if (!item?.ref || !item?.digest) throw new TypeError('basis 缺少 ref 或 digest');
+    try { if (digest(read(root, item.ref)) !== item.digest) changed_refs.push(item.ref); }
+    catch { missing_refs.push(item.ref); }
+  }
+  return { schema_version: 1, review_ref: reviewRef, status: changed_refs.length || missing_refs.length ? 'stale' : 'current', changed_refs, missing_refs, approval_created: false };
+}

package/template/scripts/lib/plan-spec-entry.mjs

@@ -7,7 +7,7 @@ const fail = message => { throw new TypeError(`plan-spec-entry-blocked: ${messag
 const text = value => typeof value === 'string' && value.trim().length > 0;
 
 export function planEntryPolicy(options = {}) {
-  const registry = decisionIO(options).document('docs/process/lifecycle-registry.yaml');
+  const registry = decisionIO(options).document('.template-spec/process/lifecycle-registry.yaml');
   const policy = registry.stages.find(stage => stage.id === 'stage.plan')?.spec_entry;
   if (!policy?.required_checks?.length || !policy?.gate_impacts) fail('缺少 Plan 入口策略');
   const gateIds = registry.gates.filter(gate => gate.stage === 'stage.plan').map(gate => gate.id).sort();
@@ -33,7 +33,7 @@ export function assertPlanSpecEntry(state, options = {}) {
   const evidence = refs => {
     if (!Array.isArray(refs) || !refs.length || refs.some(ref => !basis.has(ref))) fail('检查项缺少当前依据');
   };
-  for (const ref of [review.plan_ref, 'CONTEXT.md', 'docs/process/lifecycle-registry.yaml', review.context_reconciliation_ref]) {
+  for (const ref of [review.plan_ref, 'CONTEXT.md', '.template-spec/process/lifecycle-registry.yaml', review.context_reconciliation_ref]) {
     if (!basis.has(ref)) fail(`必需依据未绑定: ${ref}`);
   }
   if (Object.keys(review.checks || {}).length !== policy.required_checks.length) fail('检查项缺失或存在未知项');
@@ -62,7 +62,7 @@ export function assertPlanSpecEntry(state, options = {}) {
     } else if (gate.status !== 'not-applicable' || !text(gate.reason)) fail(`未命中门禁须有原因和依据: ${gateId}`);
   }
   // 门禁依赖不能通过将上游标成 N/A 来跳过。
-  const registry = io.document('docs/process/lifecycle-registry.yaml');
+  const registry = io.document('.template-spec/process/lifecycle-registry.yaml');
   for (const gate of registry.checks.filter(gate => gate.stage === 'stage.plan')) {
     if (review.internal_checks[gate.id]?.status === 'approved') {
       for (const dependency of gate.requires_checks || []) if (review.internal_checks[dependency]?.status !== 'approved') fail(`门禁依赖未批准: ${dependency}`);

package/template/scripts/lib/read-only-intake.mjs

@@ -0,0 +1,132 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { parse } from '../vendor/yaml.mjs';
+import { runCommand } from './command-runner.mjs';
+
+const ensure = (ok, message) => { if (!ok) throw new TypeError(`read-only-intake: ${message}`); };
+export const digest = value => `sha256:${createHash('sha256').update(value).digest('hex')}`;
+const inside = (root, file) => { const rel = path.relative(root, file); return rel !== '..' && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel); };
+export function intakeEvidencePath(ref, { root, runDir }) {
+  const runtime = ref.startsWith('run:');
+  const base = runtime ? runDir : root;
+  ensure(base && path.isAbsolute(base), '运行证据必须显式提供绝对 run-dir');
+  const relative = runtime ? ref.slice(4) : ref;
+  ensure(relative && !path.isAbsolute(relative) && !relative.split(/[\\/]/).includes('..'), '证据路径越界');
+  const resolvedBase = fs.realpathSync(base), file = path.resolve(base, relative);
+  ensure(inside(path.resolve(base), file) && inside(resolvedBase, fs.realpathSync(file)), '证据符号链接越界');
+  ensure(fs.statSync(file).isFile(), '证据必须为文件');
+  return file;
+}
+// Stream large preserved evidence archives instead of allocating the whole file.
+export function fileDigest(file) {
+  const hash = createHash('sha256'), buffer = Buffer.allocUnsafe(1024 * 1024);
+  const fd = fs.openSync(file, 'r');
+  try {
+    let size;
+    while ((size = fs.readSync(fd, buffer, 0, buffer.length, null)) !== 0) hash.update(buffer.subarray(0, size));
+    return `sha256:${hash.digest('hex')}`;
+  } finally { fs.closeSync(fd); }
+}
+/** Final observable repository files, including ignored and untracked files; never follow links. */
+export function intakeSnapshot(root) {
+  const result = spawnSync('git', ['ls-files', '-z', '--cached', '--others'], { cwd: root, encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 });
+  ensure(result.status === 0, result.stderr || '无法观察仓库');
+  const rows = {};
+  for (const ref of [...new Set(result.stdout.split('\0').filter(Boolean))].sort()) {
+    const file = path.join(root, ref);
+    try {
+      const stat = fs.lstatSync(file);
+      if (stat.isDirectory()) {
+        const nested = spawnSync('git', ['rev-parse', '--show-toplevel'], { cwd: file, encoding: 'utf8' });
+        ensure(nested.status === 0 && fs.realpathSync(nested.stdout.trim()) === fs.realpathSync(file), `子仓未初始化: ${ref}`);
+        const head = spawnSync('git', ['rev-parse', 'HEAD'], { cwd: file, encoding: 'utf8' });
+        ensure(nested.status === 0 && head.status === 0, `子仓不可观测: ${ref}`);
+        rows[ref] = { kind: 'gitlink', head: head.stdout.trim(), files: intakeSnapshot(file) };
+      } else rows[ref] = { kind: stat.isSymbolicLink() ? 'link' : 'file', mode: stat.mode, digest: stat.isSymbolicLink() ? digest(fs.readlinkSync(file)) : fileDigest(file) };
+    } catch (error) { if (error.code === 'ENOENT') rows[ref] = null; else throw error; }
+  }
+  const head=spawnSync('git',['rev-parse','--verify','HEAD'],{cwd:root,encoding:'utf8'});
+  const index=spawnSync('git',['ls-files','--stage','-z'],{cwd:root,encoding:'utf8',maxBuffer:16*1024*1024});
+  ensure(index.status===0,'无法观察 Git index');
+  return {git:{head:head.status===0?head.stdout.trim():null,index_digest:digest(index.stdout)},files:rows};
+}
+export function validateReadOnlyIntake(value, { root, runDir, roles, lifecycle }) {
+  const identity = parse(fs.readFileSync(path.join(root, 'yss-project.yaml'), 'utf8'));
+  ensure(identity.schema_version === 1 && ['template-source', 'project-instance'].includes(identity.repository_mode), '仓库身份无效');
+  ensure(value.contract.kind === 'read-only-intake' && value.schema_version === 2 && value.execution_state === 'Explorer' && value.allowed_write_paths.length === 0, '只读合同不授予写权限');
+  ensure(lifecycle.work_units.some(x => x.id === value.work_unit_id) && ['work-unit.entry-triage', 'work-unit.harness-entry'].includes(value.work_unit_id), '只允许已登记分诊入口');
+  ensure(roles.runtimes.some(x => x.id === value.runtime_id), '未知运行时');
+  ensure(value.contract.status === 'issued' || value.workflow_status === 'paused', '过期合同必须暂停');
+  for (const ref of [value.contract.contract_ref, ...value.inputs, ...value.expected_evidence_files]) intakeEvidencePath(ref, { root, runDir });
+  if (value.result) {
+    ensure(value.result.work_unit===value.work_unit_id && value.result.workflow_reference===value.contract.contract_ref,'结果必须绑定原分诊工作单元和合同来源');
+    ensure(!value.result.changed_files?.length && !value.result.changed_artifacts?.length, '只读结果包含变更');
+    ensure(value.result.next_route == null && !value.result.checkpoint_ref, '只读结果不得流转或修改 checkpoint');
+    for (const ref of value.result.evidence_refs || []) intakeEvidencePath(ref, { root, runDir });
+  }
+  const commands = new Set(value.verification_commands);
+  ensure((value.verification_status === 'not-executed') === (value.verification_results.length === 0), '执行状态与实际结果不一致');
+  for (const row of value.verification_results) {
+    ensure(commands.has(row.command) && row.evidence_ref.startsWith('run:'), '运行结果必须绑定声明的命令及真实运行日志');
+    const evidence = fs.readFileSync(intakeEvidencePath(row.evidence_ref, { root, runDir }));
+    ensure(row.evidence_digest === digest(evidence), '运行证据摘要不一致');
+    const record = JSON.parse(evidence);
+    for (const key of ['command','exit_code','duration_ms','executed_at']) ensure(record[key] === row[key], `运行记录 ${key} 不一致`);
+    for (const stream of ['stdout','stderr']) {
+      const ref = row[`${stream}_ref`];
+      ensure(ref?.startsWith('run:'), '运行日志无效');
+      ensure(record[`${stream}_digest`] === digest(fs.readFileSync(intakeEvidencePath(ref, { root, runDir }))), '运行日志摘要不一致');
+    }
+  }
+  if (value.workflow_status === 'resolved' || value.result?.result === 'completed') {
+    ensure(value.workflow_status === 'resolved' && value.result?.result === 'completed', '完成状态不一致');
+    ensure(value.result.evidence_refs?.length && value.result.context_reconciliation?.status === 'not-applicable' && value.result.context_reconciliation?.reason, '只读结论缺少来源或不流转说明');
+    for (const key of ['drift','violation','new_impacts','stale_candidates','blocking_signals','deferred_seams']) ensure(Array.isArray(value.result[key]) && !value.result[key].length, `完成结果 ${key} 必须为空`);
+    ensure(value.verification_results.every(x => x.exit_code === 0) && [...commands].every(c => value.verification_results.some(x => x.command === c)), '实际验证缺失或失败');
+    ensure(value.observation_ref?.startsWith('run:'), '完成结果缺少执行器仓库观测');
+    const observation = JSON.parse(fs.readFileSync(intakeEvidencePath(value.observation_ref, { root, runDir }), 'utf8'));
+    const dispatchedBytes=fs.readFileSync(intakeEvidencePath(observation.task_ref,{root,runDir}));
+    ensure(observation.task_digest===digest(dispatchedBytes),'原派发任务摘要不一致');
+    const dispatched=JSON.parse(dispatchedBytes);
+    for(const key of ['task_id','work_unit_id','actor_id','role_id','runtime_id','contract','inputs','allowed_write_paths','objective','forbidden_actions','expected_outputs','expected_evidence_files','skill_source','downstream_consumers','convergence'])ensure(JSON.stringify(dispatched[key])===JSON.stringify(value[key]),`结果替换原任务 ${key}`);
+    ensure(!dispatched.verification_commands.length || JSON.stringify(dispatched.verification_commands)===JSON.stringify(value.verification_commands),'结果替换验证要求');
+    ensure(observation.kind === 'read-only-intake-observation' && observation.task_id === value.task_id && observation.root === fs.realpathSync(root), '观测身份不匹配');
+    ensure(JSON.stringify(observation.before) === JSON.stringify(observation.after) && JSON.stringify(observation.after) === JSON.stringify(intakeSnapshot(root)), '仓库实际差异与只读声明冲突');
+  }
+  return value;
+}
+/** Runner-owned evidence is outside the repository; the child receives no new repository permissions. */
+export async function observeReadOnlyIntake(task, { root, runDir, command, args = [], timeoutMs = 0 }) {
+  const label = command ? JSON.stringify([command,...args]) : null;
+  ensure(!command || !task.verification_commands.length || task.verification_commands.length===1 && task.verification_commands[0]===label,'执行命令与声明不一致，不得替换要求的验证');
+  root = fs.realpathSync(root);
+  ensure(path.isAbsolute(runDir) && !inside(root, path.resolve(runDir)), '运行目录必须位于仓库外');
+  ensure(!inside(root, fs.realpathSync(path.dirname(runDir))), '运行目录父路径符号链接进入仓库');
+  fs.mkdirSync(runDir, { recursive: false });
+  runDir = fs.realpathSync(runDir);
+  fs.writeFileSync(path.join(runDir,'task.json'),JSON.stringify(task,null,2)+'\n',{flag:'wx'});
+  const before = intakeSnapshot(root), started = new Date().toISOString();
+  const result = command ? await runCommand(command, args, { cwd: root, timeoutMs, stdoutFile: path.join(runDir, 'stdout.log'), stderrFile: path.join(runDir, 'stderr.log') }) : null;
+  const after = intakeSnapshot(root);
+  const observation = { schema_version: 1, kind: 'read-only-intake-observation', task_id: task.task_id, task_ref:'run:task.json', task_digest:digest(fs.readFileSync(path.join(runDir,'task.json'))), root, started_at: started, before, after };
+  fs.writeFileSync(path.join(runDir, 'observation.json'), JSON.stringify(observation, null, 2)+'\n');
+  const changed = JSON.stringify(before) !== JSON.stringify(after);
+  const completed = !changed && (!result || result.status === 0);
+  const output = structuredClone(task);
+  output.observation_ref = 'run:observation.json';
+  output.verification_status = result ? 'executed' : 'not-executed';
+  output.verification_results = [];
+  if (result) {
+    const label = JSON.stringify([command, ...args]);
+    const record = { command: label, exit_code: result.status ?? 1, duration_ms: Math.round(result.duration_ms), executed_at: started, termination: result.termination ?? null, stdout_digest: digest(fs.readFileSync(path.join(runDir,'stdout.log'))), stderr_digest: digest(fs.readFileSync(path.join(runDir,'stderr.log'))) };
+    const bytes = JSON.stringify(record, null, 2)+'\n'; fs.writeFileSync(path.join(runDir, 'execution.json'), bytes);
+    output.verification_commands = [label];
+    output.verification_results = [{command:label,exit_code:record.exit_code,duration_ms:record.duration_ms,executed_at:started,evidence_ref:'run:execution.json',evidence_digest:digest(bytes),stdout_ref:'run:stdout.log',stderr_ref:'run:stderr.log'}];
+  }
+  output.workflow_status = completed ? 'resolved' : 'failed';
+  output.result = { result_schema: 'workflow-execution-result-v1', work_unit: task.work_unit_id, workflow_reference: task.contract.contract_ref, result: completed ? 'completed' : 'failed', skill: 'yss-research', changed_files: [], changed_artifacts: [], evidence_refs: [...task.inputs, 'run:observation.json'], context_reconciliation: {status:'not-applicable',ref:'CONTEXT.md',reason:'只读分诊，不批准资产或流转阶段'}, deferred_seams: [], drift: [], violation: changed ? ['repository-changed'] : [], new_impacts: [], stale_candidates: [], next_route: null, blocking_signals: completed ? [] : ['read-only-intake-failed'] };
+  fs.writeFileSync(path.join(runDir, 'task-result.json'), JSON.stringify(output, null, 2)+'\n');
+  return output;
+}