create-yss-spec 3.3.0 → 3.3.1

package/template/scripts/lib/json-schema.mjs

@@ -2,21 +2,50 @@ import { existsSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import path from "node:path";
 
-export function validateJsonSchema(value, schemaPath, { cwd = process.cwd(), label = "JSON Schema" } = {}) {
-  const effectiveSchema = path.resolve(schemaPath);
-  if (!existsSync(effectiveSchema)) throw new TypeError(`缺少 ${label}: ${effectiveSchema}`);
-  const validator = String.raw`
+const validator = String.raw`
 import json
 import sys
+import traceback
 from jsonschema import Draft202012Validator, FormatChecker
-schema = json.load(open(sys.argv[1], encoding="utf-8"))
-value = json.load(sys.stdin)
-errors = sorted(Draft202012Validator(schema, format_checker=FormatChecker()).iter_errors(value), key=lambda error: list(error.absolute_path))
-for error in errors:
-    location = ".".join(str(part) for part in error.absolute_path) or "<root>"
-    print(f"{location}: {error.message}", file=sys.stderr)
-sys.exit(1 if errors else 0)
+validators = {}
+results = []
+for item in json.load(sys.stdin):
+    try:
+        key = (item['schemaPath'], item['formatChecker'])
+        if key not in validators:
+            with open(item['schemaPath'], encoding='utf-8') as source:
+                schema = json.load(source)
+            validators[key] = Draft202012Validator(schema, format_checker=FormatChecker() if key[1] else None)
+        errors = list(validators[key].iter_errors(item['value']))
+        if item['errorStyle'] == 'verbose':
+            message = '\n'.join(str(error) for error in errors)
+        else:
+            errors.sort(key=lambda error: list(error.absolute_path))
+            message = '\n'.join(f"{'.'.join(str(part) for part in error.absolute_path) or '<root>'}: {error.message}" for error in errors)
+        results.append({'valid': not errors, 'error': message})
+    except Exception:
+        results.append({'valid': False, 'error': traceback.format_exc().strip()})
+json.dump(results, sys.stdout)
 `;
-  const result = spawnSync("python3", ["-c", validator, effectiveSchema], { cwd, encoding: "utf8", input: JSON.stringify(value) });
-  if (result.status !== 0) throw new TypeError(`${result.stdout}${result.stderr}`.trim());
+
+/** One immutable validation phase, never a cache of successful work units. */
+export function validateJsonSchemas(items, { cwd = process.cwd() } = {}) {
+  if (!Array.isArray(items)) throw new TypeError("schema batch 必须是数组");
+  if (!items.length) return [];
+  const jobs = items.map(({ value, schemaPath, formatChecker = true, errorStyle = "compact", label = "JSON Schema" }) => {
+    const effectiveSchema = path.resolve(schemaPath);
+    if (!existsSync(effectiveSchema)) throw new TypeError(`缺少 ${label}: ${effectiveSchema}`);
+    if (!["compact", "verbose"].includes(errorStyle)) throw new TypeError(`未知 schema errorStyle: ${errorStyle}`);
+    return { value, schemaPath: effectiveSchema, formatChecker, errorStyle };
+  });
+  const result = spawnSync("python3", ["-c", validator], { cwd, encoding: "utf8", input: JSON.stringify(jobs), maxBuffer: 16 * 1024 * 1024 });
+  if (result.error || result.status !== 0) throw new TypeError(result.error?.message || `${result.stdout}${result.stderr}`.trim());
+  const results = JSON.parse(result.stdout);
+  if (results.length !== jobs.length) throw new TypeError("schema batch 返回数量不匹配");
+  return results;
+}
+
+export function validateJsonSchema(value, schemaPath, options = {}) {
+  const [result] = validateJsonSchemas([{ value, schemaPath, ...options }], options);
+  if (!result.valid) throw new TypeError(result.error);
 }

package/template/scripts/lib/lifecycle-context-query.mjs

@@ -70,6 +70,10 @@ export function queryLifecycleContext({ mode, stageId, workUnitId, include = []
   const lifecycle = validateRegistry(loadRegistry());
   const orchestration = loadYaml(ORCHESTRATION_CONTRACT_REF, "生命周期编排合同");
   const skillRegistry = loadSkillRegistry();
+  const planUnit = ['work-unit.plan-opportunity', 'work-unit.plan-requirements', 'work-unit.domain-strategy-design', 'work-unit.stage-decision', 'work-unit.spec-synthesis'].includes(workUnitId);
+  const loadPlan = ['stage.plan', 'stage.spec-architecture'].includes(stageId) || planUnit;
+  stageId ??= planUnit ? 'stage.plan' : undefined;
+  if (loadPlan) include = [...include, 'planning', 'grill_exit'];
   const stage = selectById(lifecycle.stages, stageId, "阶段");
   const workUnit = selectById(lifecycle.work_units, workUnitId, "工作单元");
 
@@ -80,8 +84,8 @@ export function queryLifecycleContext({ mode, stageId, workUnitId, include = []
   }
 
   const route = workUnitId ? orchestration.work_unit_routes?.[workUnitId] ?? null : null;
-  const gates = stageId ? lifecycle.gates.filter((gate) => gate.stage === stageId) : [];
-  const artifacts = stageId ? lifecycle.artifacts.filter((artifact) => artifact.stage === stageId) : [];
+  const gates = lifecycle.gates.filter((gate) => gate.stage === stageId || (loadPlan && gate.stage === 'stage.plan'));
+  const artifacts = lifecycle.artifacts.filter((artifact) => artifact.stage === stageId || (loadPlan && artifact.stage === 'stage.plan'));
   const evidenceIds = new Set(gates.flatMap((gate) => gate.evidence ?? []));
   const selected = Object.fromEntries(normalizedIncludes.map((key) => [key, orchestration[key]]));
   const transition = workUnitId ? {
@@ -124,6 +128,7 @@ export function queryLifecycleContext({ mode, stageId, workUnitId, include = []
     execution: {
       mode: mode ? orchestration.modes[mode] : null,
       selected,
+      ...(loadPlan ? { plan_checks: lifecycle.stages.find(stage => stage.id === 'stage.plan').spec_entry.required_checks.map(id => ({ id, status: 'pending', evidence_refs: [] })) } : {}),
       transition,
       work_unit_route: route,
     },
@@ -134,4 +139,3 @@ export function queryLifecycleContext({ mode, stageId, workUnitId, include = []
     .sort();
   return canonicalize(result);
 }
-

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

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { parseDocument } from "../vendor/yaml.mjs";
 import { assertWorkUnitUserDecision, assertImplementationDecision } from "./user-decision.mjs";
 import { enforceFrontendDelivery } from "./frontend-delivery-boundary.mjs";
+import { validatePlanSpecEntry } from "./plan-spec-entry.mjs";
 
 const IMPLEMENTATION_WORK_UNIT = "work-unit.slice-implementation";
 const TICKET_DECOMPOSITION_WORK_UNIT = "work-unit.ticket-decomposition";
@@ -15,7 +16,7 @@ function deepFreeze(value) {
 }
 
 const NEXT_ROUTES = deepFreeze({
-  "work-unit.entry-triage": ["work-unit.discovery-opportunity", "work-unit.discovery-requirements"],
+  "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"],
@@ -23,8 +24,8 @@ const NEXT_ROUTES = deepFreeze({
   "work-unit.intensity-aware-verification": ["work-unit.intensity-aware-review"],
   "work-unit.intensity-aware-review": ["work-unit.release-and-rollback"],
   "work-unit.release-and-rollback": [],
-  "work-unit.discovery-opportunity": ["work-unit.discovery-requirements", "work-unit.domain-strategy-design", "work-unit.stage-decision", "work-unit.spec-synthesis"],
-  "work-unit.discovery-requirements": ["work-unit.domain-strategy-design", "work-unit.stage-decision", "work-unit.spec-synthesis"],
+  "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", REPOSITORY_PREPARATION_WORK_UNIT],
@@ -124,6 +125,7 @@ function validateTicketReference(ref, trackerKind) {
  * by `validateWorkflowExecutionResult` before this function is called.
  */
 export function validateNextRoute(currentWorkUnit, nextRoute, decisionState, options = {}) {
+
   if (["work-unit.technical-analysis", TICKET_DECOMPOSITION_WORK_UNIT, IMPLEMENTATION_WORK_UNIT, "work-unit.frontend-implementation-verification"].includes(nextRoute)) {
     try { enforceFrontendDelivery(decisionState, { root: options.root, phase: nextRoute === IMPLEMENTATION_WORK_UNIT ? "implementation" : "inputs" }); }
     catch (error) { return blockedResult(["frontend-delivery-blocked"], [error.message]); }
@@ -141,6 +143,10 @@ export function validateNextRoute(currentWorkUnit, nextRoute, decisionState, opt
     }
     return blockedResult(signals, ["allowed_next_route"]);
   }
+  if (nextRoute === 'work-unit.spec-synthesis' || currentWorkUnit === 'work-unit.spec-synthesis') {
+    const entry = validatePlanSpecEntry(decisionState, options);
+    if (entry.result === 'blocked' || nextRoute === 'work-unit.spec-synthesis') return entry;
+  }
   if (nextRoute === TICKET_DECOMPOSITION_WORK_UNIT) {
     const readiness = validateImplementationRepositoriesReady(decisionState, options);
     if (readiness.result === "blocked") return readiness;

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

@@ -0,0 +1,87 @@
+import path from 'node:path';
+import { verifyContextReconciliation } from './context-reconciliation.mjs';
+import { decisionIO, decisionDigest, assertUserDecisionRequirement } from './user-decision.mjs';
+import { validateApprovalRecord } from './approval-record.mjs';
+
+const fail = message => { throw new TypeError(`plan-spec-entry-blocked: ${message}`); };
+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 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();
+  if (JSON.stringify(gateIds) !== JSON.stringify(Object.keys(policy.gate_impacts).sort())) fail('Plan 门禁触发策略覆盖不完整');
+  return policy;
+}
+
+// 自动加载只产生 pending；持久化审阅包、证据新鲜度和真实回复共同决定放行。
+export function assertPlanSpecEntry(state, options = {}) {
+  if (!text(state?.plan_review_ref) || !text(state?.feature_id)) fail('缺少 plan_review_ref / feature_id');
+  const io = decisionIO(options);
+  const policy = planEntryPolicy(options);
+  const review = io.document(state.plan_review_ref);
+  if (review.schema_version !== 1 || review.kind !== 'plan-entry-review' || review.feature_id !== state.feature_id) fail('审阅包身份或范围不匹配');
+  if (!Array.isArray(review.basis) || !review.basis.length) fail('缺少带摘要依据');
+  const basis = new Map();
+  for (const asset of review.basis) {
+    if (!text(asset.ref) || basis.has(asset.ref) || decisionDigest(io.bytes(asset.ref)) !== asset.digest) fail(`依据缺失、重复或已变更: ${asset.ref}`);
+    basis.set(asset.ref, asset);
+  }
+  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]) {
+    if (!basis.has(ref)) fail(`必需依据未绑定: ${ref}`);
+  }
+  if (Object.keys(review.checks || {}).length !== policy.required_checks.length) fail('检查项缺失或存在未知项');
+  for (const id of policy.required_checks) {
+    const check = review.checks[id];
+    if (check?.status !== 'passed') fail(`检查未通过: ${id}`);
+    evidence(check.evidence_refs);
+  }
+  if (!Array.isArray(review.open_items)) fail('必须显式列出未决项');
+  for (const item of review.open_items) {
+    if (!text(item.id) || typeof item.critical !== 'boolean' || typeof item.runnable_blocker !== 'boolean') fail('未决项分类不完整');
+    if (item.status === 'resolved') { evidence(item.evidence_refs); continue; }
+    if (item.status !== 'deferred' || item.critical || item.runnable_blocker) fail(`关键问题或可执行阻塞未解决: ${item.id}`);
+    for (const field of ['noncritical_reason', 'owner', 'resolution_point', 'downstream_recipient']) if (!text(item[field])) fail(`延期项缺少 ${field}`);
+    evidence(item.evidence_refs);
+  }
+  for (const [gateId, impact] of Object.entries(policy.gate_impacts)) {
+    if (typeof review.impacts?.[impact] !== 'boolean') fail(`未评估影响面: ${impact}`);
+    const gate = review.gates?.[gateId];
+    evidence(gate?.evidence_refs);
+    if (review.impacts[impact]) {
+      if (gate.status !== 'approved' || !basis.has(gate.approval_ref) || !basis.has(gate.subject_ref)) fail(`命中门禁未批准或未绑定依据: ${gateId}`);
+      const record = io.document(gate.approval_ref);
+      if (record.gate_id !== gateId || record.subject_ref !== gate.subject_ref || !gate.approval_scope?.includes(state.feature_id) || JSON.stringify([...(gate.approval_scope || [])].sort()) !== JSON.stringify([...(record.approval_scope || [])].sort())) fail(`会签资产或范围不匹配: ${gateId}`);
+      validateApprovalRecord(record, { ...options, requireApproved: true });
+      assertUserDecisionRequirement({ boundary: gateId, subject_ref: gate.subject_ref, scope: gate.approval_scope, user_decision_ref: record.user_decision_ref }, options);
+    } else if (gate.status !== 'not-applicable' || !text(gate.reason)) fail(`未命中门禁须有原因和依据: ${gateId}`);
+  }
+  // 门禁依赖不能通过将上游标成 N/A 来跳过。
+  const registry = io.document('docs/process/lifecycle-registry.yaml');
+  for (const gate of registry.gates.filter(gate => gate.stage === 'stage.plan')) {
+    if (review.gates[gate.id]?.status === 'approved') {
+      for (const dependency of gate.requires_gates || []) if (review.gates[dependency]?.status !== 'approved') fail(`门禁依赖未批准: ${dependency}`);
+    }
+  }
+  const reconciliation = io.document(review.context_reconciliation_ref);
+  if (reconciliation.status !== 'reconciled' || reconciliation.repository_mode !== 'project-instance') fail('Context 未调和');
+  try { verifyContextReconciliation(path.resolve(io.root, review.context_reconciliation_ref), { root: io.root }); }
+  catch (error) { fail(`Context reconciliation 验证失败: ${error.message}\n`); }
+  assertUserDecisionRequirement({ boundary: 'plan-conclusion', subject_ref: state.plan_review_ref, scope: [state.feature_id], user_decision_ref: state.plan_user_decision_ref }, options);
+  return { result: 'allowed', blocking_signals: [], missing_requirements: [], evidence_refs: [state.plan_review_ref, ...basis.keys()], next_work_unit: null };
+}
+
+export function validatePlanSpecEntry(state, options = {}) {
+  try { return assertPlanSpecEntry(state, options); }
+  catch (error) { return { result: 'blocked', blocking_signals: ['plan-spec-entry-blocked'], missing_requirements: [error.message], evidence_refs: [], next_work_unit: null }; }
+}
+
+export function assertPlanCheckpoint(checkpoint, options = {}) {
+  if (checkpoint.repository_mode !== 'project-instance') return;
+  const entering = checkpoint.next_work_unit === 'work-unit.spec-synthesis' || checkpoint.stage === 'stage.spec-architecture' || checkpoint.stage_trace?.completed_work_unit === 'work-unit.spec-synthesis';
+  if (entering) assertPlanSpecEntry(checkpoint, options);
+}

package/template/scripts/lib/scenario-checks.mjs

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, mkdtempSync, rmSync } from "node:fs";
 import path from "node:path";
+import { buildPlanFixture } from "../fixtures/user-decision/plan-fixture.mjs";
 import os from "node:os";
 import { buildDecisionFixture, buildImplementationFixture } from "../fixtures/user-decision/build-fixture.mjs";
 import { fileURLToPath } from "node:url";
@@ -58,8 +59,8 @@ function validateInvocationBoundary(data) {
   ensure(native?.default_entry === "yss-product-lifecycle" && native?.formal_artifact_owner === "yss-product-lifecycle", "生命周期原生入口未持有默认正式资产所有权");
   ensure(native?.user_confirmation_policy_ref === "docs/agents/digital-human-roles.yaml#user_decision_policy", "生命周期人工门禁集合已漂移");
   const routes = data.work_unit_routes;
-  ensure(routes?.["work-unit.discovery-requirements"]?.skills?.includes("grilling") && routes?.["work-unit.discovery-requirements"]?.skills?.includes("domain-modeling"), "需求分析工作单元缺少 grilling/domain-modeling");
-  ensure(routes?.["work-unit.discovery-opportunity"]?.route_by?.market_or_competitor_fact === "competitive-intelligence" && routes["work-unit.discovery-opportunity"].route_by.technical_or_standard_fact === "yss-research:technical-evidence" && routes["work-unit.discovery-opportunity"].route_by.strategy_fact === "yss-research:strategy-evidence", "机会调研事实路由不准确");
+  ensure(routes?.["work-unit.plan-requirements"]?.skills?.includes("grilling") && routes?.["work-unit.plan-requirements"]?.skills?.includes("domain-modeling"), "需求分析工作单元缺少 grilling/domain-modeling");
+  ensure(routes?.["work-unit.plan-opportunity"]?.route_by?.market_or_competitor_fact === "competitive-intelligence" && routes["work-unit.plan-opportunity"].route_by.technical_or_standard_fact === "yss-research:technical-evidence" && routes["work-unit.plan-opportunity"].route_by.strategy_fact === "yss-research:strategy-evidence", "机会调研事实路由不准确");
   const strategyResearch = routes?.["work-unit.domain-strategy-design"]?.research_contract;
   ensure(strategyResearch?.profile === "strategy-evidence" && strategyResearch.mode_before_gate === "evidence-audited" && strategyResearch.artifact_owner === "yss-research" && strategyResearch.downstream_owner === "yss-stage-decision", "领域战略研究合同缺少 profile、门禁前审计或资产所有权边界");
   const stageDecisionResearch = routes?.["work-unit.stage-decision"]?.research_contract;
@@ -94,7 +95,7 @@ function validateInvocationBoundary(data) {
   }
 }
 
-function validateWorkflowExecutionResult(payload, contract, workUnitRoutes) {
+function validateWorkflowExecutionResult(payload, contract, workUnitRoutes, options = {}) {
   for (const field of contract.required) ensure(Object.hasOwn(payload, field), `Workflow Execution Result 缺少 ${field}`);
   ensure(contract.result_values.includes(payload.result), "Workflow Execution Result result 无效");
   if (Object.hasOwn(payload, "unavailable_skill")) {
@@ -107,7 +108,7 @@ function validateWorkflowExecutionResult(payload, contract, workUnitRoutes) {
   const workUnit = workUnitRoutes?.[payload.work_unit];
   ensure(workUnit, `未知 Workflow Execution Result work_unit: ${payload.work_unit}`);
   if (payload.result === "completed") {
-    const routeResult = validateNextRoute(payload.work_unit, payload.next_route, payload);
+    const routeResult = validateNextRoute(payload.work_unit, payload.next_route, payload, options);
     ensure(routeResult.result === "allowed", `Workflow Execution Result next_route 非法: ${routeResult.blocking_signals.join(", ")}`);
     ensure(payload.context_reconciliation?.status === "reconciled", "project-instance 完成态必须具有 reconciled context_reconciliation");
     ensure(hasText(payload.context_reconciliation?.ref) && payload.evidence_refs.includes(payload.context_reconciliation.ref) && exists(payload.context_reconciliation.ref), "context_reconciliation.ref 必须可读并包含在 evidence_refs 中");
@@ -268,7 +269,9 @@ export function runScenario(name) {
     process.on("exit", () => rmSync(decisionTemp, { recursive: true, force: true }));
     const specDecision = buildDecisionFixture(path.join(decisionTemp, "spec"));
     const implementationDecision = buildImplementationFixture(path.join(decisionTemp, "implementation"), "docs/.scratch/demo/issues/01-valid-slice.md");
+    const planFixture = buildPlanFixture(path.join(decisionTemp, 'plan'));
     const validResult = {
+      ...planFixture.state,
       user_decisions: [specDecision.requirement],
       result_schema: "workflow-execution-result-v1",
       work_unit: "work-unit.spec-synthesis",
@@ -282,7 +285,7 @@ export function runScenario(name) {
       next_route: "work-unit.implementation-repository-preparation",
       blocking_signals: []
     };
-    validateWorkflowExecutionResult(validResult, data.workflow_execution_result, data.work_unit_routes);
+    validateWorkflowExecutionResult(validResult, data.workflow_execution_result, data.work_unit_routes, { root: planFixture.root });
     const validTicketResult = {
       ...validResult,
       work_unit: "work-unit.ticket-decomposition",
@@ -290,7 +293,7 @@ export function runScenario(name) {
       ticket_decomposition_result_ref: "docs/.scratch/demo/evidence/ticket-decomposition-result.yaml",
       vertical_slice_ticket_ref: "docs/.scratch/demo/issues/01-valid-slice.md",
     };
-    validateWorkflowExecutionResult(validTicketResult, data.workflow_execution_result, data.work_unit_routes);
+    validateWorkflowExecutionResult(validTicketResult, data.workflow_execution_result, data.work_unit_routes, { root: planFixture.root });
     const validImplementationResult = {
       ...validResult,
       ...implementationDecision.state,
@@ -317,7 +320,7 @@ export function runScenario(name) {
         ],
       },
     };
-    validateWorkflowExecutionResult(validImplementationResult, data.workflow_execution_result, data.work_unit_routes);
+    validateWorkflowExecutionResult(validImplementationResult, data.workflow_execution_result, data.work_unit_routes, { root: planFixture.root });
     for (const mutate of [
       (item) => { item.vertical_slice_ticket_role = "ready-for-human"; },
       (item) => { item.vertical_slice_ticket_kind = "parent-ticket"; },
@@ -329,22 +332,22 @@ export function runScenario(name) {
     ]) {
       const invalid = structuredClone(validImplementationResult); mutate(invalid);
       let rejected = false;
-      try { validateWorkflowExecutionResult(invalid, data.workflow_execution_result, data.work_unit_routes); } catch { rejected = true; }
+      try { validateWorkflowExecutionResult(invalid, data.workflow_execution_result, data.work_unit_routes, { root: planFixture.root }); } catch { rejected = true; }
       ensure(rejected, "实现 Workflow Execution Result 的 Ticket 语义变异未被拒绝");
     }
     const unavailableResult = structuredClone(validResult);
     unavailableResult.result = "blocked";
     unavailableResult.unavailable_skill = { skill: "yss-ui", provider: "codex", fallback: "manual-review", resolution: "needs-human" };
     unavailableResult.blocking_signals = ["missing_evidence"];
-    validateWorkflowExecutionResult(unavailableResult, data.workflow_execution_result, data.work_unit_routes);
+    validateWorkflowExecutionResult(unavailableResult, data.workflow_execution_result, data.work_unit_routes, { root: planFixture.root });
     const malformedUnavailable = structuredClone(unavailableResult);
     delete malformedUnavailable.unavailable_skill.fallback;
     let unavailableRejected = false;
-    try { validateWorkflowExecutionResult(malformedUnavailable, data.workflow_execution_result, data.work_unit_routes); } catch { unavailableRejected = true; }
+    try { validateWorkflowExecutionResult(malformedUnavailable, data.workflow_execution_result, data.work_unit_routes, { root: planFixture.root }); } catch { unavailableRejected = true; }
     ensure(unavailableRejected, "技能不可用结果缺少 fallback 时未被拒绝");
     const compatibleResult = structuredClone(validResult);
     compatibleResult.workflow_reference = { source: "mattpocock/skills", skill: "to-spec", invocation_mode: "reference" };
-    validateWorkflowExecutionResult(compatibleResult, data.workflow_execution_result, data.work_unit_routes);
+    validateWorkflowExecutionResult(compatibleResult, data.workflow_execution_result, data.work_unit_routes, { root: planFixture.root });
     for (const mutate of [
       (item) => { delete item.workflow_reference; },
       (item) => { delete item.context_reconciliation; },
@@ -360,7 +363,7 @@ export function runScenario(name) {
     ]) {
       const invalid = structuredClone(validResult); mutate(invalid);
       let rejected = false;
-      try { validateWorkflowExecutionResult(invalid, data.workflow_execution_result, data.work_unit_routes); } catch { rejected = true; }
+      try { validateWorkflowExecutionResult(invalid, data.workflow_execution_result, data.work_unit_routes, { root: planFixture.root }); } catch { rejected = true; }
       ensure(rejected, "Workflow Execution Result 完成态变异未被拒绝");
     }
     let metadataRejected = false;

package/template/scripts/lib/skill-supply-chain.mjs

@@ -117,7 +117,16 @@ function loadStrategicDesignSkillManifest() {
   return validateStrategicDesignSkillManifest(JSON.parse(readFileSync(STRATEGIC_DESIGN_MANIFEST_PATH, "utf8")));
 }
 function git(args) { return spawnSync("git", args, { cwd: ROOT, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }); }
-function tracked(relativePath) { return git(["ls-files", "-z", "--", relativePath]).stdout.length > 0; }
+function trackedPaths() {
+  const result = git(["ls-files", "-z"]);
+  if (result.status !== 0) throw new TypeError("无法读取 Git 受跟踪路径");
+  const paths = new Set();
+  for (const file of result.stdout.split("\0").filter(Boolean)) {
+    let ref = file;
+    while (ref !== ".") { paths.add(ref); ref = path.posix.dirname(ref); }
+  }
+  return paths;
+}
 function parseLock() { return existsSync(LOCK_PATH) ? JSON.parse(readFileSync(LOCK_PATH, "utf8")) : null; }
 function sharedFromLock(lock) {
   const shared = lock?.version === 3 && lock.skills?.shared;
@@ -137,6 +146,13 @@ export function unlockedCanonicalEntries(names, allowedNames, hasSkillMd = () =>
   return names.filter((name) => !allowed.has(name) && !OBSOLETE.has(name) && hasSkillMd(name)).sort();
 }
 export function syncSkills({ check = false } = {}) {
+  let trackedSet;
+  const tracked = ref => (trackedSet ??= trackedPaths()).has(ref);
+  const sourceHashes = new Map();
+  const sourceHash = source => {
+    if (!sourceHashes.has(source)) sourceHashes.set(source, treeHash(source));
+    return sourceHashes.get(source);
+  };
   const lock = parseLock();
   const shared = sharedFromLock(lock);
   const absent = shared.filter((name) => !lstatSafe(path.join(SOURCE_ROOT, name))?.isDirectory());
@@ -162,7 +178,7 @@ export function syncSkills({ check = false } = {}) {
         if (info?.isSymbolicLink()) {
           if (!existsSync(target) || realpathSync(target) !== realpathSync(source)) drift.push(`projection target mismatch: ${relative(target)}`);
         } else if (!info?.isDirectory()) drift.push(`missing projection: ${relative(target)}`);
-        else if (treeHash(source) !== treeHash(target)) drift.push(`projection drift: ${relative(target)}`);
+        else if (sourceHash(source) !== treeHash(target)) drift.push(`projection drift: ${relative(target)}`);
       } else if (info?.isSymbolicLink() && existsSync(target) && realpathSync(target) === realpathSync(source)) {
         continue;
       } else {

package/template/scripts/lib/strategic-handoff-io.mjs

@@ -3,6 +3,7 @@ import { existsSync, lstatSync, readdirSync, readFileSync, mkdirSync, writeFileS
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
+import { validateJsonSchemas } from './json-schema.mjs';
 import { parseDocument } from '../vendor/yaml.mjs';
 export const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
 export const ensure = (condition, message) => { if (!condition) throw new TypeError(message); };
@@ -50,11 +51,11 @@ export function project(root) {
   ensure(value.schema_version === 1 && value.repository_mode === 'project-instance', '只允许 project-instance 导出或导入业务包');
   return realpathSync(root);
 }
-export function schema(value, ref) {
-  const program = 'import json,sys; from jsonschema import Draft202012Validator; s=json.load(open(sys.argv[1])); v=json.load(sys.stdin); errors=list(Draft202012Validator(s).iter_errors(v)); print("\\n".join(str(e) for e in errors)); sys.exit(bool(errors))';
-  const out = spawnSync('python3', ['-c', program, safe(ROOT, ref)], { input: JSON.stringify(value), encoding: 'utf8', maxBuffer: 4 * 1024 * 1024 });
-  ensure(out.status === 0, `schema 校验失败: ${out.error?.message || out.stdout || out.stderr}`);
+export function schemaBatch(items) {
+  const results = validateJsonSchemas(items.map(([value, ref]) => ({ value, schemaPath: safe(ROOT, ref), formatChecker: false, errorStyle: 'verbose' })));
+  for (const result of results) ensure(result.valid, `schema 校验失败: ${result.error}\n`);
 }
+export function schema(value, ref) { schemaBatch([[value, ref]]); }
 export function archive(command, source, destination) {
   const out = spawnSync('python3', [path.join(ROOT, 'scripts/lib/strategic-handoff-zip.py'), command, source, destination], { encoding: 'utf8' });
   ensure(out.status === 0, `ZIP 操作失败: ${out.error?.message || out.stderr}`);

package/template/scripts/lib/strategic-handoff.mjs

@@ -1,7 +1,7 @@
 import { existsSync, lstatSync, readFileSync, mkdirSync, mkdtempSync, renameSync, rmSync, cpSync } from 'node:fs';
 import path from 'node:path';
 import { tmpdir } from 'node:os';
-import { ensure, canonical, digest, hash, json, parse, read, safe, relative, files, write, project, schema, archive, ROOT, sourceApprovalPolicy } from './strategic-handoff-io.mjs';
+import { ensure, canonical, digest, hash, json, parse, read, safe, relative, files, write, project, schema, schemaBatch, archive, ROOT, sourceApprovalPolicy } from './strategic-handoff-io.mjs';
 import { parseContextSource, parseContextContract, resolveContextTermRefs } from './context-contract.mjs';
 import { countersignRuleForGate } from './digital-human-roles.mjs';
 import { validateApprovalRecord } from './approval-record.mjs';
@@ -91,8 +91,7 @@ export async function inspectSource(root, handoffRef) {
   snapshot(handoff.source_context_snapshot,source); checkDelta(handoff,source);
   const strategy=read(safe(root,handoff.source.domain_strategy_ref.persisted_ref));
   const stage=read(safe(root,handoff.source.stage_decision_package_ref.persisted_ref));
-  schema(strategy,'docs/process/schemas/strategic-handoff-domain-strategy.schema.json');
-  schema(stage,'docs/process/schemas/strategic-handoff-stage-decision-package.schema.json');
+  schemaBatch([[strategy,'docs/process/schemas/strategic-handoff-domain-strategy.schema.json'],[stage,'docs/process/schemas/strategic-handoff-stage-decision-package.schema.json']]);
   snapshot(strategy.context_snapshot,source); snapshot(stage.context_snapshot,source);
   ensure(strategy.status==='approved' && stage.status==='approved', '战略合同/方案决策包尚未批准');
   ensure(strategy.domain_strategy_id===handoff.source.domain_strategy_ref.id && strategy.domain_version===handoff.source.domain_strategy_ref.version, '战略身份/版本不一致');
@@ -141,21 +140,22 @@ function collect(root, handoffRef, handoff, config) {
     if(Array.isArray(value)) { if(key==='evidence_refs') value.forEach(enqueue); else value.forEach(v=>refs(v,key)); }
     else if(value && typeof value==='object') for(const [k,v]of Object.entries(value)) { if(['approval_ref','persisted_ref','user_decision_ref'].includes(k)&&typeof v==='string')enqueue(v); else if(k==='ref'&&typeof v==='string'&&!/^[a-z]+:\/\//i.test(v))enqueue(v); else refs(v,k); }
   }
+  let totalBytes = 0;
   while(queue.length) {
     const ref=symbolic[queue[0]]||queue[0]; queue.shift(); if(/^https?:\/\//i.test(ref))continue; relative(ref);
     if(collected.has(ref))continue;
     const full=safe(root,ref),stat=lstatSync(full);
     if(stat.isDirectory()) { queue.push(...files(root,ref)); continue; }
     ensure(stat.isFile() && stat.size<=MAX_BYTES,`源文件类型/大小无效: ${ref}`);
-    const bytes=readFileSync(full); collected.set(ref,bytes);
-    ensure(collected.size<=20000 && [...collected.values()].reduce((n,b)=>n+b.length,0)<=MAX_BYTES,'交接包大小超限');
+    const bytes=readFileSync(full); collected.set(ref,bytes); totalBytes += bytes.length;
+    ensure(collected.size<=20000 && totalBytes<=MAX_BYTES,'交接包大小超限');
     if(/\.(yaml|yml|json)$/.test(ref))refs(parse(bytes));
     queue.push(...documentLinks(ref,bytes));
   }
   return collected;
 }
-function materialize(bundleRoot, manifest, destination) {
-  for(const file of manifest.files.filter(x=>x.original_ref))write(destination,file.original_ref,readFileSync(safe(bundleRoot,file.path)));
+function materialize(captured, manifest, destination) {
+  for(const file of manifest.files.filter(x=>x.original_ref))write(destination,file.original_ref,captured.get(file.path));
 }
 export async function openBundle(input, action) {
   const temp=mkdtempSync(path.join(tmpdir(),'yss-handoff-'));
@@ -170,10 +170,11 @@ export async function openBundle(input, action) {
     ensure(new Set(paths.map(x=>x.toLowerCase())).size===paths.length,'包文件路径重复');
     ensure(own([...paths,'manifest.json'].sort(),files(root).sort()),'包文件缺失或存在未登记文件');
     ensure(manifest.files.length<=20000 && manifest.files.reduce((n,f)=>n+f.size_bytes,0)<=MAX_BYTES,'包大小超限');
-    for(const file of manifest.files){const bytes=readFileSync(safe(root,file.path));ensure(bytes.length===file.size_bytes && hash(bytes)===file.sha256,`文件摘要不一致: ${file.path}`);if(file.original_ref)relative(file.original_ref);}
+    const captured = new Map();
+    for(const file of manifest.files){const bytes=readFileSync(safe(root,file.path));ensure(bytes.length===file.size_bytes && hash(bytes)===file.sha256,`文件摘要不一致: ${file.path}`);if(file.original_ref)relative(file.original_ref);captured.set(file.path,bytes);}
     const originals=manifest.files.filter(x=>x.original_ref).map(x=>x.original_ref);
     ensure(new Set(originals.map(x=>x.toLowerCase())).size===originals.length,'源路径重复');
-    const source=path.join(temp,'source');mkdirSync(source);materialize(root,manifest,source);
+    const source=path.join(temp,'source');mkdirSync(source);materialize(captured,manifest,source);
     const inspected=await inspectSource(source,manifest.handoff_ref);
     ensure(manifest.bundle_id===inspected.handoff.handoff_id && manifest.version===inspected.handoff.handoff_version,'包身份与源交接不一致');
     ensure(own(read(safe(root,'indexes/rules.json')),inspected.indexes.rules) && own(read(safe(root,'indexes/scenarios.json')),inspected.indexes.scenarios),'规则/场景索引与源资产不一致');

package/template/scripts/lib/task-package.mjs

@@ -6,6 +6,7 @@ import { loadRegistry, ROOT } from "./lifecycle-registry.mjs";
 import { loadMaintenanceCheckpoint, validateMaintenanceCheckpoint } from "./maintenance-intensity.mjs";
 import { assertImplementationDecision } from "./user-decision.mjs";
 import { validateNextRoute } from "./lifecycle-transition.mjs";
+import { assertPlanSpecEntry } from "./plan-spec-entry.mjs";
 import { enforceHarnessTaskScope } from "./harness-execution-scope.mjs";
 import { enforceFrontendDelivery } from "./frontend-delivery-boundary.mjs";
 import { LEGACY_TASK_PACKAGE_SCHEMA, TASK_PACKAGE_SCHEMA, validateTaskPackageSchema } from "./task-package-schema.mjs";
@@ -59,6 +60,7 @@ function validateSkillSource(value, registry) {
 }
 
 function validateCommon(value, registry, lifecycle) {
+  if (value.work_unit_id === 'work-unit.spec-synthesis') assertPlanSpecEntry(value);
   const workUnit = lifecycle.work_units.find((item) => item.id === value.work_unit_id);
   if (!workUnit && value.contract.kind !== "slice-implementation") fail(`未知 work_unit_id: ${value.work_unit_id}`);
   const roleDefaults = taskPackageDefaults(value.role_id, registry);

package/template/scripts/lib/template-commit-cache.mjs

@@ -1,3 +1,4 @@
+import { runCommandSync } from "./command-runner.mjs";
 import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
@@ -7,13 +8,14 @@ import { ROOT } from "./template-verification.mjs";
 
 function fail(message) { throw new TypeError(message); }
 function ensure(condition, message) { if (!condition) fail(message); }
-function git(args, cwd) {
-  const result = spawnSync("git", args, { cwd, encoding: "utf8" });
-  if (result.status !== 0) fail(result.stderr.trim() || `git ${args.join(" ")} 执行失败`);
+function git(args, cwd, timeoutMs = 0, cleanupPathsOnFailure = []) {
+  const result = args.includes("fetch") ? runCommandSync("git", args, { cwd, timeoutMs, progress: true, cleanupPathsOnFailure }) : spawnSync("git", args, { cwd, encoding: "utf8" });
+  if (result.status !== 0) fail(result.termination || result.error?.message || result.stderr.trim() || `git ${args.join(" ")} 执行失败`);
   return result.stdout.trim();
 }
 
-export function acquireTemplateCommit({ repository, commit, cacheRoot = path.join(ROOT, ".template-source/cache/remote-templates"), allowLocal = false }) {
+export function acquireTemplateCommit({ repository, commit, cacheRoot = path.join(ROOT, ".template-source/cache/remote-templates"), allowLocal = false, timeoutMs = 0 }) {
+  ensure(Number.isFinite(timeoutMs) && timeoutMs >= 0, "timeoutMs 必须是非负毫秒数");
   ensure(typeof repository === "string" && repository.trim(), "repository 不能为空");
   ensure(/^[a-f0-9]{40}$/.test(commit), "模板 ref 必须是 40 位 commit");
   if (!allowLocal) ensure(/^(?:https?:\/\/|ssh:\/\/|git@)/.test(repository), "正式模板缓存只接受远程 repository URL");
@@ -35,7 +37,7 @@ export function acquireTemplateCommit({ repository, commit, cacheRoot = path.joi
   try {
     const temporaryRepository = path.join(temporary, "repository.git");
     git(["init", "--bare", "-q", temporaryRepository], ROOT);
-    git(["--git-dir", temporaryRepository, "fetch", "--depth=1", "--no-tags", repository, commit], ROOT);
+    git(["--git-dir", temporaryRepository, "fetch", "--depth=1", "--no-tags", repository, commit], ROOT, timeoutMs, [temporary]);
     const actual = git(["--git-dir", temporaryRepository, "rev-parse", "FETCH_HEAD^{commit}"], ROOT);
     ensure(actual === commit, `远程返回 commit 与请求不一致: ${actual}`);
     writeFileSync(path.join(temporary, "metadata.json"), `${JSON.stringify({ schema_version: 1, key, repository, commit })}\n`);

package/template/scripts/run-template-verification

@@ -23,12 +23,18 @@ function collectChangedFiles(base) {
 function runCommand(command) {
   return new Promise((resolve) => {
     const started = Date.now();
+    process.stderr.write(`[开始] ${command}\n`);
     const child = spawn(command, { cwd: ROOT, shell: true, env: process.env, stdio: ["ignore", "pipe", "pipe"] });
     let stdout = "";
     let stderr = "";
     child.stdout.on("data", (chunk) => { stdout += chunk; });
     child.stderr.on("data", (chunk) => { stderr += chunk; });
-    child.on("close", (code) => resolve({ command, code: code ?? 1, duration_ms: Date.now() - started, stdout, stderr }));
+    child.on("error", error => { stderr += `${error.message}\n`; });
+    child.on("close", (code) => {
+      const duration_ms = Date.now() - started;
+      process.stderr.write(`[${code === 0 ? "完成" : "失败"}] ${command} (${duration_ms}ms, exit=${code ?? 1})\n`);
+      resolve({ command, code: code ?? 1, duration_ms, stdout, stderr });
+    });
   });
 }
 
@@ -106,8 +112,8 @@ try {
   const concurrency = Number(values.concurrency || plan.max_concurrency);
   if (!Number.isInteger(concurrency) || concurrency < 1 || concurrency > 4) throw new TypeError("concurrency 必须为 1..4");
 
-  process.stdout.write(`模板核验 profile: ${plan.requested_profile} -> ${plan.effective_profile}\n`);
-  if (plan.escalation_reason) process.stdout.write(`自动升级原因: ${plan.escalation_reason}\n`);
+  process.stderr.write(`模板核验 profile: ${plan.requested_profile} -> ${plan.effective_profile}\n`);
+  if (plan.escalation_reason) process.stderr.write(`自动升级原因: ${plan.escalation_reason}\n`);
   const groups = await runGroups(plan, modeResult.stdout.trim(), concurrency);
   printResults(groups);
   const failed = groups.flatMap((group) => group.results).find((result) => result.code !== 0);

package/template/scripts/sync-strategic-handoff-tools

@@ -7,10 +7,19 @@ const root=path.resolve(import.meta.dirname,'..');
 const check=process.argv.includes('--check');
 const targets=['submodules/yss-harness-design-agent','submodules/yss-harness-dev-agent','submodules/yss-harness-backend-agent','submodules/yss-harness-frontend-agent'];
 const shared=['scripts/strategic-handoff','scripts/verify-strategic-handoff-consumption','scripts/verify-strategic-handoff-package-scenarios','scripts/verify-strategic-context-import','scripts/verify-strategic-context-import-scenarios','scripts/lib/context-contract.mjs','docs/process/strategic-handoff-package.md','docs/process/schemas/strategic-design-handoff.schema.json',...readdirSync(path.join(root,'scripts/lib')).filter(x=>x.startsWith('strategic-handoff-')||x==='strategic-handoff.mjs').map(x=>`scripts/lib/${x}`),...readdirSync(path.join(root,'docs/process/schemas')).filter(x=>x.startsWith('strategic-handoff-')).map(x=>`docs/process/schemas/${x}`),...readdirSync(path.join(root,'scripts/fixtures/strategic-handoff')).map(x=>`scripts/fixtures/strategic-handoff/${x}`)];
+shared.push('scripts/lib/command-runner.mjs','scripts/lib/json-schema.mjs','scripts/lib/context-reconciliation.mjs','scripts/verify-context-reconciliation');
 shared.push('scripts/instantiate-harness','scripts/backend-delivery','scripts/verify-frontend-delivery','scripts/lib/backend-delivery.mjs','scripts/lib/frontend-delivery.mjs','scripts/lib/frontend-delivery-boundary.mjs','docs/process/frontend-backend-delivery.md','docs/process/schemas/backend-delivery.schema.json','docs/process/schemas/backend-delivery-verification.schema.json','docs/process/schemas/frontend-delivery-acceptance.schema.json');
 let differences=[];
 // 专职执行范围由各模板持有；后端只消费 wire 校验器，不恢复原型构建技能。
 function sync(source,dest){let bytes=readFileSync(source);if(dest.includes('/yss-harness-backend-agent/')){let content=bytes.toString();if(dest.endsWith('/scripts/lib/strategic-handoff.mjs'))content=content.replace('../../.agents/skills/yss-prototype-stage/scripts/visual-baseline-contract.mjs','./visual-baseline-contract.mjs');if(dest.endsWith('/scripts/fixtures/strategic-handoff/fixture.mjs'))content=content.replace('../../../.agents/skills/yss-prototype-stage/scripts/visual-baseline-contract.mjs','../../lib/visual-baseline-contract.mjs');bytes=Buffer.from(content);}if(!existsSync(dest)||!bytes.equals(readFileSync(dest))){differences.push(path.relative(root,dest));if(!check){mkdirSync(path.dirname(dest),{recursive:true});writeFileSync(dest,bytes);}}if(!check&&path.basename(path.dirname(dest))==='scripts'&&!path.extname(dest))chmodSync(dest,0o755);}
+// CLI core owns the portable external-command runner; all runtime copies are generated here.
+sync(path.join(root,'.template-source/cli-core/command-runner.mjs'),path.join(root,'scripts/lib/command-runner.mjs'));
+for(const name of ['create-yss-spec','create-yss-strategic-design','create-yss-harness-dev']) {
+ const target=`submodules/${name}`;
+ if(!existsSync(path.join(root,target,'.git')))continue;
+ if(!check){const state=inspectWorkingTreeScope(root,{project_root:target,repository_scope:'git-submodule',checkout_state:'attached-branch'});if(!state.writable)throw new Error(`${target}: ${state.violation}`);}
+ sync(path.join(root,'.template-source/cli-core/command-runner.mjs'),path.join(root,target,'src/command-runner.mjs'));
+}
 for(const kind of ['domain-strategy','stage-decision-package'])sync(path.join(root,`.agents/skills/yss-stage-decision/references/${kind}.schema.json`),path.join(root,`docs/process/schemas/strategic-handoff-${kind}.schema.json`));
 for(const target of targets){
  if(!existsSync(path.join(root,target,'.git')))continue;