create-yss-spec 3.4.10 → 3.5.2

package/template/scripts/lib/frontend-delivery.mjs

@@ -7,7 +7,7 @@ import { openBundle } from './strategic-handoff.mjs';
 import { verifyConsumption } from './strategic-handoff-consumption.mjs';
 import { read, safe, ensure, hash, schema, project, ROOT } from './strategic-handoff-io.mjs';
 
-const ACCEPTANCE_SCHEMAS=new Map([[1,'docs/process/schemas/frontend-delivery-acceptance-v1.schema.json'],[2,'docs/process/schemas/frontend-delivery-acceptance.schema.json'],[3,'docs/process/schemas/frontend-delivery-acceptance-v3.schema.json']]);
+const ACCEPTANCE_SCHEMAS=new Map([[1,'.template-spec/process/schemas/frontend-delivery-acceptance-v1.schema.json'],[2,'.template-spec/process/schemas/frontend-delivery-acceptance.schema.json'],[3,'.template-spec/process/schemas/frontend-delivery-acceptance-v3.schema.json']]);
 
 function acceptanceSchema(version) {
   ensure(ACCEPTANCE_SCHEMAS.has(version),`Frontend Delivery Acceptance 未知 schema_version: ${String(version)}；支持版本: 1, 2, 3；既有 UI 接收请使用 3`);
@@ -18,7 +18,7 @@ export async function verifyFrontendStrategicPreflight({root=process.cwd(),prefl
   project(root);
   const file=safe(root,preflightRef),preflight=read(file);
   ensure([1,2].includes(preflight.schema_version),'Frontend Strategic Preflight 未知 schema_version');
-  schema(preflight,preflight.schema_version===2?'docs/process/schemas/frontend-strategic-preflight-v2.schema.json':'docs/process/schemas/frontend-strategic-preflight.schema.json');
+  schema(preflight,preflight.schema_version===2?'.template-spec/process/schemas/frontend-strategic-preflight-v2.schema.json':'.template-spec/process/schemas/frontend-strategic-preflight.schema.json');
   const preflightDigest=hash(readFileSync(file));
   if(expectedDigest)ensure(expectedDigest===preflightDigest,'前端战略预检摘要已变化，需重编译合同');
   ensure(preflight.status==='verified','前端战略预检尚未 verified');

package/template/scripts/lib/governance-layout.mjs

@@ -0,0 +1,74 @@
+import { existsSync, lstatSync, readdirSync } from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+const requiredShared = [
+  ".template-spec/agents/yss-skill-registry.yaml",
+  ".template-spec/agents/digital-human-roles.yaml",
+  ".template-spec/agents/issue-tracker.md",
+  ".template-spec/process/lifecycle-registry.yaml",
+  ".template-spec/process/lifecycle-artifact-map.md",
+];
+const oldStaticDirs = [
+  "docs/agents", "docs/process", "docs/templates", "docs/user-guide",
+  "docs/plan/templates", "docs/api/templates", "docs/architecture/templates",
+  "docs/design/templates", "docs/design/tokens", "docs/design/schemas",
+  "docs/design/diagrams", "docs/discovery/templates",
+];
+const oldStaticFiles = new Set([
+  "docs/adr/README.md", "docs/architecture/README.md",
+  "docs/plan/README.md", "docs/plan/entry-review.md",
+  "docs/discovery/README.md", "docs/discovery/IDEATION.md",
+  "docs/design/README.md", "docs/design/design.md",
+  "docs/design/design-system-sync.yaml", "docs/design/preview.html",
+  "docs/design/preview-dark.html", "docs/design/preview.css",
+  "docs/design/preview.js", "docs/engineering/backend-platforms.json",
+  "docs/engineering/backend-platforms.md",
+]);
+
+function staticPath(ref) {
+  return oldStaticFiles.has(ref) || oldStaticDirs.some((directory) => ref.startsWith(`${directory}/`));
+}
+
+function filesBelow(root, relativePath) {
+  const full = path.join(root, relativePath);
+  if (!existsSync(full)) return [];
+  const entry = lstatSync(full);
+  if (!entry.isDirectory()) return [relativePath];
+  return readdirSync(full).filter((name) => name !== ".DS_Store")
+    .flatMap((name) => filesBelow(root, `${relativePath}/${name}`));
+}
+
+export function verifyGovernanceLayout(root, mode) {
+  if (!["template-source", "project-instance"].includes(mode)) {
+    throw new TypeError(`不支持的仓库身份: ${mode}`);
+  }
+  for (const ref of requiredShared) {
+    if (!existsSync(path.join(root, ref))) throw new TypeError(`缺少共享治理资产: ${ref}`);
+  }
+  let oldFiles;
+  if (mode === "template-source") {
+    const result = spawnSync("git", ["ls-files", "-z", "--", "docs"], { cwd: root, encoding: "utf8" });
+    if (result.status !== 0) throw new TypeError(result.stderr || "无法读取模板源受控文件清单");
+    oldFiles = result.stdout.split("\0").filter(Boolean).filter(staticPath);
+    for (const ref of [
+      ".template-source/process/maintenance-intensity.yaml",
+      ".template-source/process/template-verification-profiles.yaml",
+      ".template-source/agents/skills-maintenance.md",
+    ]) {
+      if (!existsSync(path.join(root, ref))) throw new TypeError(`缺少模板维护资产: ${ref}`);
+    }
+  } else {
+    oldFiles = [...new Set([
+      ...oldStaticDirs.flatMap((ref) => filesBelow(root, ref)),
+      ...[...oldStaticFiles].filter((ref) => existsSync(path.join(root, ref))),
+    ])];
+    if (existsSync(path.join(root, ".template-source"))) {
+      throw new TypeError("项目实例不得包含 .template-source");
+    }
+  }
+  if (oldFiles.length) {
+    throw new TypeError(`旧治理文件仍位于 docs/，需显式迁移: ${oldFiles.sort().join(", ")}`);
+  }
+  return { mode, shared: requiredShared.length, legacy: 0 };
+}

package/template/scripts/lib/harness-execution-scope.mjs

@@ -6,9 +6,9 @@ import { ROOT, read, safe, ensure } from './strategic-handoff-io.mjs';
 export function loadDeliveryProfile(root=ROOT) {
   const metadata=['backend','frontend'].filter(side=>existsSync(path.join(root,`.yss-harness-${side}.json`)));
   ensure(metadata.length<=1,'专职 Harness metadata 身份冲突');
-  const profilePath=path.join(root,'docs/process/harness-profile.yaml');
+  const profilePath=path.join(root,'.template-spec/process/harness-profile.yaml');
   ensure(!metadata.length||existsSync(profilePath),'专职 Harness 缺少 profile，不得绕过执行门禁');
-  const profile=existsSync(profilePath)?read(safe(root,'docs/process/harness-profile.yaml')):null;
+  const profile=existsSync(profilePath)?read(safe(root,'.template-spec/process/harness-profile.yaml')):null;
   if(metadata.length) {
     const expected=`harness.${metadata[0]}-delivery`;
     const record=read(safe(root,`.yss-harness-${metadata[0]}.json`));

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

@@ -6,9 +6,9 @@ import { parseDocument } from "../vendor/yaml.mjs";
 import { ROOT, loadRegistry, semanticDigest, validateRegistry } from "./lifecycle-registry.mjs";
 import { loadSkillRegistry } from "./skill-registry.mjs";
 
-const LIFECYCLE_REGISTRY_REF = "docs/process/lifecycle-registry.yaml";
+const LIFECYCLE_REGISTRY_REF = ".template-spec/process/lifecycle-registry.yaml";
 const ORCHESTRATION_CONTRACT_REF = ".agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml";
-const SKILL_REGISTRY_REF = "docs/agents/yss-skill-registry.yaml";
+const SKILL_REGISTRY_REF = ".template-spec/agents/yss-skill-registry.yaml";
 
 function read(relativePath) {
   return readFileSync(path.join(ROOT, relativePath), "utf8");
@@ -88,6 +88,12 @@ export function queryLifecycleContext({ mode, stageId, workUnitId, include = []
   }
 
   const route = workUnitId ? orchestration.work_unit_routes?.[workUnitId] ?? null : null;
+  if (workUnit?.scope === "project-instance" && workUnit.id !== "work-unit.entry-triage" && !route) {
+    throw new TypeError(`项目工作单元缺少执行路由: ${workUnit.id}`);
+  }
+  if (workUnit?.scope === "project-instance" && workUnit.id !== "work-unit.entry-triage" && !Object.hasOwn(orchestration.transition_graph?.routes ?? {}, workUnit.id)) {
+    throw new TypeError(`项目工作单元缺少流转路由: ${workUnit.id}`);
+  }
   const gates = lifecycle.gates.filter((gate) => gate.stage === stageId || (loadPlan && gate.stage === 'stage.plan'));
   const checks = lifecycle.checks.filter(check => check.stage === stageId || gates.some(gate => gate.requires_checks?.includes(check.id)));
   const artifacts = lifecycle.artifacts.filter((artifact) => artifact.stage === stageId || (loadPlan && artifact.stage === 'stage.plan'));
@@ -125,7 +131,9 @@ export function queryLifecycleContext({ mode, stageId, workUnitId, include = []
     },
     lifecycle: {
       artifacts,
-      evidence: lifecycle.evidence.filter((item) => evidenceIds.has(item.id)),
+      evidence: lifecycle.evidence.filter((item) => evidenceIds.has(item.id)).map(({ public_description, ...item }) => ({
+        ...item, description: public_description ?? item.description
+      })),
       gates,
       checks,
       stage,

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

@@ -6,8 +6,8 @@ import { fileURLToPath } from "node:url";
 import { parseDocument } from "../vendor/yaml.mjs";
 
 export const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
-export const DEFAULT_REGISTRY = path.join(ROOT, "docs/process/lifecycle-registry.yaml");
-export const DEFAULT_BASELINE = path.join(ROOT, "docs/process/lifecycle-registry-baseline.json");
+export const DEFAULT_REGISTRY = path.join(ROOT, ".template-spec/process/lifecycle-registry.yaml");
+export const DEFAULT_BASELINE = path.join(ROOT, ".template-spec/process/lifecycle-registry-baseline.json");
 const ID_PATTERN = /^(stage|gate|check|artifact|work-unit|evidence)\.[a-z0-9][a-z0-9-]*$/;
 const COLLECTIONS = ["stages", "gates", "checks", "artifacts", "work_units", "evidence"];
 
@@ -63,6 +63,12 @@ export function semanticDigest(registry) {
   return createHash("sha256").update(JSON.stringify(semanticProjection(registry))).digest("hex");
 }
 
+export function semanticHashesById(registry) {
+  return Object.fromEntries(semanticProjection(registry).map(({ record }) => [
+    record.id, createHash("sha256").update(JSON.stringify(record)).digest("hex")
+  ]));
+}
+
 function validateBaseline(registry, ids, baselinePath) {
   let baseline;
   try {
@@ -72,7 +78,7 @@ function validateBaseline(registry, ids, baselinePath) {
     if (error instanceof SyntaxError) fail(`无法解析生命周期已发布基线: ${error.message}`);
     throw error;
   }
-  if (baseline.schema_version !== 1 || baseline.registry_id !== registry.registry_id) {
+  if (![1, 2].includes(baseline.schema_version) || baseline.registry_id !== registry.registry_id) {
     fail("生命周期已发布基线版本或 registry_id 不匹配");
   }
   const publishedIds = baseline.published_ids;
@@ -91,7 +97,26 @@ function validateBaseline(registry, ids, baselinePath) {
   if (JSON.stringify(activeIds) !== JSON.stringify(expected)) {
     fail("生命周期活跃 ID 与已发布基线不一致；新增、移除或弃用必须先更新发布基线");
   }
-  if (baseline.semantic_sha256 !== semanticDigest(registry)) fail("生命周期稳定 ID 的语义快照已变化；不得复用已发布 ID");
+  if (baseline.schema_version === 1) {
+    if (baseline.semantic_sha256 !== semanticDigest(registry)) fail("生命周期稳定 ID 的语义快照已变化；不得复用已发布 ID");
+    return;
+  }
+  const archivedPath = path.resolve(ROOT, baseline.historical_baseline ?? "");
+  if (baseline.historical_baseline !== ".template-spec/process/lifecycle-registry-baseline-v1.json") fail("生命周期历史基线路径无效");
+  const archivedBytes = readFileSync(archivedPath);
+  if (createHash("sha256").update(archivedBytes).digest("hex") !== baseline.historical_sha256) fail("生命周期历史基线摘要不匹配");
+  const archived = JSON.parse(archivedBytes.toString("utf8"));
+  if (archived.schema_version !== 1 || archived.registry_id !== registry.registry_id || !archived.published_ids.every((id) => publishedIds.includes(id))) fail("生命周期历史基线与当前发布 ID 不兼容");
+  const migrations = baseline.migrations;
+  if (!migrations || typeof migrations !== "object" || Array.isArray(migrations)) fail("生命周期迁移映射无效");
+  for (const [oldId, newId] of Object.entries(migrations)) {
+    if (!archived.published_ids.includes(oldId) || !deprecated.includes(oldId) || !activeIds.includes(newId) || oldId.split(".")[0] !== newId.split(".")[0]) fail(`生命周期迁移映射无效: ${oldId} -> ${newId}`);
+  }
+  const hashes = semanticHashesById(registry);
+  if (!baseline.semantic_sha256_by_id || JSON.stringify(Object.keys(baseline.semantic_sha256_by_id).sort()) !== JSON.stringify(activeIds)) fail("生命周期逐 ID 语义基线与活跃 ID 不一致");
+  for (const [id, digest] of Object.entries(hashes)) {
+    if (baseline.semantic_sha256_by_id[id] !== digest) fail(`生命周期稳定 ID 的语义快照已变化: ${id}`);
+  }
 }
 
 export function validateRegistry(registry, { baseline = DEFAULT_BASELINE } = {}) {
@@ -108,7 +133,7 @@ export function validateRegistry(registry, { baseline = DEFAULT_BASELINE } = {})
   }
   if (policy.published_ids_immutable !== true) fail("published_ids_immutable 必须为 true");
   if (policy.pattern !== "^(stage|gate|check|artifact|work-unit|evidence)\\.[a-z0-9][a-z0-9-]*$") fail("id_policy.pattern 不符合固定命名空间");
-  if (policy.baseline !== "docs/process/lifecycle-registry-baseline.json") fail("id_policy.baseline 必须指向发布基线");
+  if (policy.baseline !== ".template-spec/process/lifecycle-registry-baseline.json") fail("id_policy.baseline 必须指向发布基线");
   if (!Array.isArray(policy.deprecated_ids)) fail("deprecated_ids 必须是数组");
   const ids = new Map();
   for (const collection of COLLECTIONS) {
@@ -159,6 +184,20 @@ export function validateRegistry(registry, { baseline = DEFAULT_BASELINE } = {})
   for (const artifact of registry.artifacts) {
     requireReference(ids, artifact.stage, `${artifact.id}.stage`);
     if (ids.get(artifact.stage) !== "stages") fail(`${artifact.id}.stage 必须引用 stage.*`);
+    for (const reference of artifact.trigger.match(/\b(?:stage|gate|check|artifact|work-unit|evidence)\.[a-z0-9][a-z0-9-]*\b/g) ?? []) {
+      requireReference(ids, reference, `${artifact.id}.trigger`);
+    }
+  }
+  // Human-readable rules are execution instructions too. A retired control ID
+  // must never survive in an active trigger or completion sentence.
+  for (const collection of COLLECTIONS) for (const record of registry[collection]) {
+    for (const [field, value] of Object.entries(record)) {
+      if (field === "id" || typeof value !== "string") continue;
+      for (const reference of value.match(/\b(?:gate|check)\.[a-z0-9][a-z0-9-]*\b/g) ?? []) {
+        requireReference(ids, reference, `${record.id}.${field}`);
+        if (ids.get(reference) !== `${reference.split(".")[0]}s`) fail(`${record.id}.${field} 引用类型不匹配: ${reference}`);
+      }
+    }
   }
   if (baseline) validateBaseline(registry, ids, baseline);
   return registry;
@@ -168,7 +207,7 @@ export function renderLifecycleStructure(registry) {
   const display = (record, field) => record[`public_${field}`] ?? record[field];
   const lines = [
     "<!-- lifecycle-registry:structure:start -->",
-    `> 此结构区由 \`docs/process/lifecycle-registry.yaml\` 生成。当前为 \`${registry.status}\` 模式：正式门禁、内部检查和派生文档共同消费此事实源。`, "",
+    `> 此结构区由 \`.template-spec/process/lifecycle-registry.yaml\` 生成。当前为 \`${registry.status}\` 模式：正式门禁、内部检查和派生文档共同消费此事实源。`, "",
     "## 1. 主阶段", "", "| 稳定 ID | 阶段 | 目标 | 退出标准 |", "|---|---|---|---|"
   ];
   for (const stage of registry.stages) lines.push(`| \`${stage.id}\` | ${display(stage, "name")} | ${display(stage, "goal")} | ${display(stage, "exit_criteria")} |`);
@@ -186,7 +225,7 @@ export function renderLifecycleStructure(registry) {
 
 export function renderWorkUnits(registry) {
   const display = (record, field) => record[`public_${field}`] ?? record[field];
-  const lines = ["<!-- lifecycle-registry:work-units:start -->", "> 此表由 `docs/process/lifecycle-registry.yaml` 生成；工作单元按 `scope` 区分模板维护与项目实例流程。", "", "| 稳定 ID | 范围 | 工作单元 | 输入 | 输出 | 完成条件 |", "|---|---|---|---|---|---|"];
+  const lines = ["<!-- lifecycle-registry:work-units:start -->", "> 此表由 `.template-spec/process/lifecycle-registry.yaml` 生成；工作单元按 `scope` 区分模板维护与项目实例流程。", "", "| 稳定 ID | 范围 | 工作单元 | 输入 | 输出 | 完成条件 |", "|---|---|---|---|---|---|"];
   for (const unit of registry.work_units) lines.push(`| \`${unit.id}\` | ${unit.scope} | ${display(unit, "name")} | ${display(unit, "input")} | ${display(unit, "output")} | ${display(unit, "completion")} |`);
   lines.push("<!-- lifecycle-registry:work-units:end -->");
   return `${lines.join("\n")}\n`;

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

@@ -0,0 +1,111 @@
+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 }) {
+  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, '补齐真实阻塞原因');
+  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],
+    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')) {
+    next_step.action_type = 'inspect';
+    next_action = '核对运行中任务身份与实际结果；状态未知时不得重复派发';
+  } else if (activeItems.length && activeItems.every(item => item.progress === 'completed')) {
+    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,
+    source_digests: { checkpoint: { ref: checkpointRef, digest: checkpoint.digest }, registry: { ref: registryRef, digest: registry.digest }, orchestration: { ref: contractRef, digest: contract.digest } },
+  };
+}

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

@@ -12,11 +12,13 @@ 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";
 
 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;
@@ -27,21 +29,22 @@ function deepFreeze(value) {
 
 const NEXT_ROUTES = deepFreeze({
   "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 +86,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 +126,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);
 }
@@ -271,7 +322,7 @@ export function validateNextRoute(currentWorkUnit, nextRoute, decisionState, opt
   }
   const routes = NEXT_ROUTES[currentWorkUnit] && scopedNextRoutes(currentWorkUnit, 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 +336,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 +351,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/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}`);