create-yss-spec 3.3.0 → 3.3.3

package/template/scripts/lib/command-runner.mjs

@@ -0,0 +1,107 @@
+import { spawn, spawnSync } from "node:child_process";
+import { appendFileSync, rmSync, writeFileSync } from "node:fs";
+import { StringDecoder } from "node:string_decoder";
+import { fileURLToPath } from "node:url";
+
+function killTree(child, signal) {
+  if (!child.pid) return;
+  try {
+    if (process.platform === "win32") spawnSync("taskkill", ["/PID", String(child.pid), "/T", "/F"], { stdio: "ignore" });
+    else process.kill(-child.pid, signal);
+  } catch (error) { if (error.code !== "ESRCH") throw error; }
+}
+
+/** Bounded lifetime for external tools; stdout is never mixed with progress. */
+export function runCommand(command, args, { cwd, env = process.env, timeoutMs = 0, signal, stdoutFile, stderrFile, secrets = [], progress = false } = {}) {
+  if (!Number.isFinite(timeoutMs) || timeoutMs < 0) throw new TypeError("timeoutMs 必须是非负毫秒数");
+  if (signal?.aborted) return Promise.resolve({ status: 1, stdout: "", stderr: "command cancelled", termination: "cancelled", duration_ms: 0 });
+  return new Promise(resolve => {
+    const started = performance.now();
+    const argumentSecrets = args.flatMap(value => { try { const url = new URL(value); return url.password ? [url.password, decodeURIComponent(url.password)] : []; } catch { return []; } });
+    const secretNames = new Map(Object.entries(env).filter(([key]) => /(?:PASSWORD|TOKEN|SECRET)$/.test(key) || key === "MAVEN_REPO_USERNAME").map(([key,value]) => [value,key]));
+    const replacement = secret => secretNames.has(secret) ? `[REDACTED:${secretNames.get(secret)}]` : "[REDACTED]";
+    const sensitive = [...secrets, ...argumentSecrets, ...secretNames.keys()].filter(value => typeof value === "string" && value.length > 0).sort((a, b) => b.length - a.length);
+    const redact = text => sensitive.reduce((value, secret) => value.replaceAll(secret, replacement(secret)), text);
+    if (progress) process.stderr.write(`[开始] ${redact(command + " " + args.join(" "))}\n`);
+    for (const file of [stdoutFile, stderrFile]) if (file) writeFileSync(file, "");
+    const child = spawn(command, args, { cwd, env, detached: process.platform !== "win32", stdio: ["ignore", "pipe", "pipe"] });
+    let termination = null, escalation, timer, errorMessage;
+    const makeStream = file => {
+      const decoder = new StringDecoder("utf8");
+      let pending = "", captured = "";
+      const emit = text => { captured += text; if (file) appendFileSync(file, text); };
+      function consume(final = false) {
+        let output = "", cursor = 0;
+        while (cursor < pending.length) {
+          const match = sensitive.find(secret => pending.startsWith(secret, cursor));
+          if (match) { output += replacement(match); cursor += match.length; continue; }
+          if (!final && sensitive.some(secret => secret.startsWith(pending.slice(cursor)))) break;
+          output += pending[cursor++];
+        }
+        pending = pending.slice(cursor);
+        emit(output);
+      }
+      return { write(bytes) { pending += decoder.write(bytes); consume(); }, end() { pending += decoder.end(); consume(true); return captured; } };
+    };
+    const stdout = makeStream(stdoutFile), stderr = makeStream(stderrFile);
+    function cancel(reason) {
+      if (termination) return;
+      termination = reason;
+      killTree(child, "SIGTERM");
+      escalation = setTimeout(() => killTree(child, "SIGKILL"), 1000);
+    }
+    const abort = () => cancel("cancelled");
+    const onInterrupt = () => cancel("cancelled");
+    signal?.addEventListener("abort", abort, { once: true });
+    process.on("SIGINT", onInterrupt); process.on("SIGTERM", onInterrupt);
+    if (timeoutMs) timer = setTimeout(() => cancel("timeout"), timeoutMs);
+    child.stdout.on("data", bytes => stdout.write(bytes));
+    child.stderr.on("data", bytes => stderr.write(bytes));
+    child.on("error", error => { errorMessage = redact(error.message); });
+    child.on("close", (code, exitSignal) => {
+      clearTimeout(timer); clearTimeout(escalation);
+      // A group leader can exit before its descendants close redirected streams.
+      if (termination) killTree(child, "SIGKILL");
+      signal?.removeEventListener("abort", abort);
+      process.off("SIGINT", onInterrupt); process.off("SIGTERM", onInterrupt);
+      const duration_ms = performance.now() - started;
+      const status = termination === "timeout" ? 124 : termination ? 1 : code ?? 1;
+      if (progress) process.stderr.write(`[${status === 0 ? "完成" : "失败"}] ${command} (${Math.round(duration_ms)}ms, exit=${status}${termination ? `, ${termination}` : ""})\n`);
+      resolve({ status, stdout: stdout.end(), stderr: stderr.end() + (errorMessage || ""), signal: exitSignal, termination, duration_ms });
+    });
+  });
+}
+
+// Synchronous API compatibility for existing generators/cache consumers. The worker
+// owns the process group and streams logs; it never updates project metadata.
+export function runCommandSync(command, args, options = {}) {
+  const result = spawnSync(process.execPath, [fileURLToPath(import.meta.url), "--worker"], {
+    input: JSON.stringify({ command, args, options }), encoding: "utf8", maxBuffer: 64 * 1024 * 1024,
+    stdio: ["pipe", "pipe", "inherit"], env: options.env ?? process.env,
+  });
+  if (result.error || result.status !== 0) throw new TypeError(result.error?.message || "command worker failed");
+  return JSON.parse(result.stdout);
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url) && process.argv[2] === "--worker") {
+  const parent = process.ppid;
+  let input = "";
+  for await (const bytes of process.stdin) input += bytes;
+  const { command, args, options } = JSON.parse(input);
+  const controller = new AbortController();
+  const watchParent = setInterval(() => {
+    if (process.ppid !== parent) controller.abort();
+    else {
+      try { process.kill(parent, 0); } catch (error) { if (error.code === "ESRCH") controller.abort(); }
+    }
+  }, 100);
+  try {
+    const result = await runCommand(command, args, { ...options, signal: controller.signal });
+    if (result.status !== 0) {
+      // Only caller-created temporary resources are supplied here. The worker
+      // also owns this cleanup when a terminated synchronous caller cannot run finally.
+      for (const directory of options.cleanupPathsOnFailure || []) rmSync(directory, { recursive: true, force: true });
+    }
+    if (process.ppid === parent) process.stdout.write(JSON.stringify(result));
+  } finally { clearInterval(watchParent); }
+}

package/template/scripts/lib/context-reconciliation.mjs

@@ -0,0 +1,34 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { parseDocument } from "../vendor/yaml.mjs";
+import { resolveContextTermRefs, verifyContextSnapshot } from "./context-contract.mjs";
+import { validateJsonSchema } from "./json-schema.mjs";
+const schemaPath = path.resolve(import.meta.dirname, "../../docs/process/schemas/context-reconciliation.schema.json");
+export function parseReconciliationFile(file) {
+  const document = parseDocument(readFileSync(file, "utf8"), { maxAliasCount: 0, uniqueKeys: true });
+  if (document.errors.length) throw new TypeError(document.errors[0].message);
+  return document.toJS({ maxAliasCount: 0 });
+}
+
+export function verifyContextReconciliation(file, { root = process.cwd() } = {}) {
+  root = path.resolve(root);
+  const value = parseReconciliationFile(path.resolve(file));
+  validateJsonSchema(value, schemaPath, { formatChecker: false });
+  const manifest = parseReconciliationFile(path.join(root, "yss-project.yaml"));
+  if (value.repository_mode !== manifest.repository_mode) throw new TypeError("repository_mode 必须与根目录 yss-project.yaml 一致");
+  const contract = verifyContextSnapshot(value.context_snapshot, { root });
+  const changedRefs = [...value.changes.added, ...value.changes.updated, ...value.changes.deprecated];
+  resolveContextTermRefs(contract, changedRefs);
+  if (new Set(changedRefs).size !== changedRefs.length) throw new TypeError("changes 中的术语引用不得跨分类重复");
+  if (value.repository_mode === "project-instance" && value.status !== "reconciled") throw new TypeError("project-instance 工作单元只有 status=reconciled 才允许批准或进入下一步");
+  if (value.status === "reconciled" && value.unresolved_terms.length) throw new TypeError("reconciled 不得包含 unresolved_terms");
+  if (value.status === "blocked" && value.unresolved_terms.length === 0) throw new TypeError("blocked 必须说明 unresolved_terms");
+  if (value.status === "not-applicable" && (value.repository_mode !== "template-source" || !value.reason)) throw new TypeError("not-applicable 只适用于 template-source 且必须说明 reason");
+  for (const ref of value.evidence_refs) {
+    if (/^https?:\/\//.test(ref)) continue;
+    const resolved = path.resolve(root, ref);
+    if (!resolved.startsWith(`${root}${path.sep}`) && resolved !== root) throw new TypeError(`evidence_ref 越出仓库: ${ref}`);
+    if (!existsSync(resolved)) throw new TypeError(`evidence_ref 不可读: ${ref}`);
+  }
+  return contract;
+}

package/template/scripts/lib/digital-human-roles.mjs

@@ -202,7 +202,7 @@ export function collectCountersignGateIds(policy) {
     const gates = policy?.[bucket];
     if (Array.isArray(gates)) ids.push(...gates);
   }
-  for (const rule of policy?.digital_human_review || []) {
+  for (const rule of [...(policy?.digital_human_review || []), ...(policy?.check_reviews || [])]) {
     if (rule?.gate) ids.push(rule.gate);
   }
   for (const rule of policy?.dual_digital_human || []) {
@@ -217,6 +217,8 @@ export function collectCountersignGateIds(policy) {
 }
 
 export function countersignRuleForGate(policy, gateId) {
+  const internal = (policy?.check_reviews || []).find(rule => rule.gate === gateId);
+  if (internal) return { bucket: "check_reviews", ...internal };
   const dual = (policy?.dual_digital_human || []).find((rule) => rule.gate === gateId);
   if (dual) return { bucket: "dual_digital_human", ...dual };
   const review = (policy?.digital_human_review || []).find((rule) => rule.gate === gateId);
@@ -332,7 +334,7 @@ export function validateDigitalHumanRoles(doc, { skillIds, stageIds, gateIds, ar
   }
   const claimed = new Set();
   for (const bucket of STRING_GATE_BUCKETS) {
-    if (bucket !== "product_digital_human_with_biological_veto" || policy[bucket]?.length !== 0) requireStringArray(policy[bucket], `gate_policy.${bucket}`);
+    if (policy[bucket]?.length !== 0) requireStringArray(policy[bucket], `gate_policy.${bucket}`);
     for (const gate of policy[bucket]) {
       if (!gateIds.has(gate)) fail(`gate_policy.${bucket} 引用了未知门禁: ${gate}`);
       if (claimed.has(gate)) fail(`门禁被多个会签桶重复占用: ${gate}`);
@@ -345,11 +347,17 @@ export function validateDigitalHumanRoles(doc, { skillIds, stageIds, gateIds, ar
   for (const [index, rule] of policy.digital_human_review.entries()) {
     if (typeof rule === "string") fail("digital_human_review 必须是含 gate 与 countersigners 的规则");
     validateSignRule(rule, { actors, gateIds, claimed, field: `digital_human_review[${index}]` });
-    if (rule.gate === "gate.release-ready") fail("gate.release-ready 不得放入 digital_human_review");
   }
-  if (!policy.biological_human.includes("gate.release-ready")) {
-    fail("gate.release-ready 必须属于 biological_human");
+  const checkIds = new Set(loadRegistry().checks.map(check => check.id));
+  const checkClaimed = new Set();
+  for (const id of policy.automatic_checks || []) {
+    if (!checkIds.has(id) || checkClaimed.has(id)) fail(`未知或重复自动检查: ${id}`);
+    checkClaimed.add(id);
   }
+  for (const [index, rule] of (policy.check_reviews || []).entries()) {
+    validateSignRule(rule, { actors, gateIds: checkIds, claimed: checkClaimed, field: `check_reviews[${index}]` });
+  }
+  if (checkClaimed.size !== checkIds.size) fail("内部检查职责覆盖不完整");
   if (!Array.isArray(policy.digital_human_review_work_units) || policy.digital_human_review_work_units.length === 0) {
     fail("缺少 digital_human_review_work_units");
   }
@@ -384,7 +392,7 @@ export function validateDigitalHumanRoles(doc, { skillIds, stageIds, gateIds, ar
   requireStringArray(decisions.gates, "user_decision_policy.gates");
   for (const gate of decisions.gates) if (!gateIds.has(gate)) fail(`用户决定引用未知门禁: ${gate}`);
   for (const unit of Object.keys(decisions.work_units || {})) if (!workUnitIds.has(unit)) fail(`用户决定引用未知工作单元: ${unit}`);
-  if (!policy.biological_human.includes("gate.user-confirmation")) fail("gate.user-confirmation 必须由真实用户裁决");
+  if (!policy.biological_human.includes("gate.product-design-approved")) fail("gate.product-design-approved 必须由真实用户裁决");
   for (const gate of [...(policy.unlisted_kept_biological || []), ...policy.biological_human]) {
     if (!decisions.gates.includes(gate)) fail(`${gate} 缺少真实回复要求`);
   }

package/template/scripts/lib/export-skills.mjs

@@ -7,7 +7,7 @@ import { fileURLToPath } from "node:url";
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
 const sourceRoot = path.join(root, ".agents/skills");
 const managed = ["skills", "skills.sh.json", ".yss-export-manifest.json"];
-const forbidden = ["AGENTS.md", "CONTEXT.md", "docs", "skills-lock.json", ".agents", ".claude", ".codex", ".pi", ".qoder", ".trae"];
+const forbidden = ["AGENTS.md", "CONTEXT.md", "docs", "skills-lock.json", ".agents", ".codex", ".cursor", ".pi"];
 const hash = (content) => createHash("sha256").update(content).digest("hex");
 const fail = (message) => { throw new TypeError("export-yss-skills: " + message); };
 
@@ -48,8 +48,8 @@ function sanitize(text, relative) {
   const prefix = prefixPath ? prefixPath + "/" : "";
   let value = text.replace(/(YSS_SKILLS_ROOT\s*=\s*["']?)\/path\/to\/\.agents\/skills/g, "$1__YSS_SKILLS_ROOT_PATH__");
   value = value.replace(/\/path\/to\/\.agents\/skills/g, "$YSS_SKILLS_ROOT");
-  value = value.replace(/(?:\$\{base_project\}\/)?(?:\/path\/to\/)?\.(?:agents|claude|codex|pi|qoder|trae)\/skills\//g, prefix);
-  value = value.replace(/\.(?:agents|claude|codex|pi|qoder|trae)\/skills\b/g, "the canonical public skill source");
+  value = value.replace(/(?:\$\{base_project\}\/)?(?:\/path\/to\/)?\.(?:agents|codex|cursor|pi)\/skills\//g, prefix);
+  value = value.replace(/\.(?:agents|codex|cursor|pi)\/skills\b/g, "the canonical public skill source");
   value = value.replace(/\/path\/to\/skill-creator/g, "skill-creator").replace(/(?<![\w.])\/path\//g, "./path/");
   value = value.replace(/\/(?:Users|home|private)\/[^\s"'()<>\]]+/g, "<local-path-removed>").replace(/\/tmp\//g, "./tmp/");
   value = value.replace(/yss-spec-project-template/g, "the consuming project").replace(/\$\{base_project\}/g, "the consuming project");
@@ -98,7 +98,7 @@ function validate(output, skillNames) {
     const text = bytes.toString("utf8");
     if (/-----BEGIN (?:[A-Z0-9 ]+ )?PRIVATE KEY-----|(?:ghp_|github_pat_|github_token_|xox[baprs]-)[A-Za-z0-9_-]+|AKIA[0-9A-Z]{16}/.test(text)) fail("suspicious credential-like content: " + absolute);
     if (/(?:^|[^.\w])\/(?:Users|home|private|tmp)\//.test(text)) fail("absolute local path in public export: " + absolute);
-    if (/\.(?:agents|claude|codex|pi|qoder|trae)\/skills/.test(text)) fail("Agent root path in public export: " + absolute);
+    if (/\.(?:agents|codex|cursor|pi)\/skills/.test(text)) fail("Agent root path in public export: " + absolute);
   }
   validateLinks(path.join(output, "skills"));
 }

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,11 @@ 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;
+  include = [...include, 'gate_consolidation'];
+  if (loadPlan) include = [...include, 'planning', 'grill_exit'];
   const stage = selectById(lifecycle.stages, stageId, "阶段");
   const workUnit = selectById(lifecycle.work_units, workUnitId, "工作单元");
 
@@ -80,9 +85,10 @@ 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 evidenceIds = new Set(gates.flatMap((gate) => gate.evidence ?? []));
+  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'));
+  const evidenceIds = new Set([...gates, ...checks].flatMap((gate) => gate.evidence ?? []));
   const selected = Object.fromEntries(normalizedIncludes.map((key) => [key, orchestration[key]]));
   const transition = workUnitId ? {
     next: orchestration.transition_graph?.routes?.[workUnitId] ?? [],
@@ -118,12 +124,14 @@ export function queryLifecycleContext({ mode, stageId, workUnitId, include = []
       artifacts,
       evidence: lifecycle.evidence.filter((item) => evidenceIds.has(item.id)),
       gates,
+      checks,
       stage,
       work_unit: workUnit,
     },
     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 +142,3 @@ export function queryLifecycleContext({ mode, stageId, workUnitId, include = []
     .sort();
   return canonicalize(result);
 }
-

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

@@ -0,0 +1,85 @@
+import { readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { parseDocument } from '../vendor/yaml.mjs';
+import { loadRegistry, ROOT } from './lifecycle-registry.mjs';
+import { loadDigitalHumanRoles, countersignRuleForGate } from './digital-human-roles.mjs';
+import { validateApprovalRecord, loadApprovalRecord } from './approval-record.mjs';
+
+const fail = message => { throw new TypeError(`lifecycle-control-blocked: ${message}`); };
+
+// Checks retain their own evidence and independent review; only the aggregate requests a user decision.
+export function assertGateChecks(gateId, state, { root = ROOT, registry = loadRegistry(), rolesDoc = loadDigitalHumanRoles() } = {}) {
+  const gate = registry.gates.find(item => item.id === gateId);
+  if (!gate) fail(`未知或已退役门禁: ${gateId}`);
+  const controls = new Map(registry.checks.map(item => [item.id, item]));
+  const seen = new Set();
+  const evidence = item => {
+    if (!Array.isArray(item.basis) || !item.basis.length) fail('缺少当前证据摘要');
+    const refs = new Set();
+    for (const asset of item.basis) {
+      if (!asset?.ref || refs.has(asset.ref)) fail('证据引用缺失或重复');
+      refs.add(asset.ref);
+      const bytes = readFileSync(path.resolve(root, asset.ref));
+      if (createHash('sha256').update(bytes).digest('hex') !== asset.digest) fail(`证据过期: ${asset.ref}`);
+    }
+    return refs;
+  };
+  function check(id) {
+    if (seen.has(id)) return;
+    seen.add(id);
+    const definition = controls.get(id), item = state.checks?.[id];
+    if (!definition || !item) fail(`缺少检查: ${id}`);
+    const refs = evidence(item);
+    if (item.status === 'not-applicable') {
+      if (item.applicable !== false || !item.reason?.trim()) fail(`${id} 未命中须有影响面、原因和证据`);
+      return;
+    }
+    if (item.applicable !== true || !['passed', 'approved'].includes(item.status)) fail(`${id} 未通过或未评估`);
+    for (const dependency of definition.requires_checks || []) {
+      check(dependency);
+      if (state.checks[dependency].status === 'not-applicable') fail(`${id} 前置检查不适用，必须重新评估依赖`);
+    }
+    for (const kind of definition.evidence || []) {
+      if (!item.evidence?.[kind]?.length || item.evidence[kind].some(ref => !refs.has(ref))) fail(`${id} 缺少绑定证据: ${kind}`);
+    }
+    const rule = countersignRuleForGate(rolesDoc.gate_policy, id);
+    if (rule) {
+      if (!refs.has(item.approval_ref) || !refs.has(item.subject_ref)) fail(`${id} 未绑定审查与资产`);
+      const record = loadApprovalRecord(path.resolve(root, item.approval_ref));
+      if (record.gate_id !== id || record.subject_ref !== item.subject_ref) fail(`${id} 审查对象不匹配`);
+      if (!item.approval_scope?.length || JSON.stringify([...item.approval_scope].sort()) !== JSON.stringify([...(record.approval_scope || [])].sort())) fail(`${id} 审查范围不匹配`);
+      const subjectDigest = createHash('sha256').update(readFileSync(path.resolve(root, item.subject_ref))).digest('hex');
+      if (record.subject_digest !== subjectDigest) fail(`${id} 审查资产摘要不匹配`);
+      validateApprovalRecord(record, { rolesDoc, root, requireApproved: true });
+      if (!record.drafter_principal_ref || record.drafter_principal_ref === record.principal_ref) fail(`${id} 缺少独立审查身份或起草者自签`);
+    }
+  }
+  for (const id of gate.requires_checks || []) check(id);
+  const item = state.gates?.[gateId];
+  if (!item || item.status !== 'approved') fail(`${gateId} 未批准`);
+  const refs = evidence(item);
+  for (const kind of gate.evidence) {
+    if (!item.evidence?.[kind]?.length || item.evidence[kind].some(ref => !refs.has(ref))) fail(`${gateId} 缺少绑定证据: ${kind}`);
+  }
+  const approvalRequired = countersignRuleForGate(rolesDoc.gate_policy, gateId);
+  if (approvalRequired) {
+    if (!refs.has(item.approval_ref) || !refs.has(item.subject_ref)) fail(`${gateId} 缺少已绑定批准记录和审阅包`);
+    const record = loadApprovalRecord(path.resolve(root, item.approval_ref));
+    if (!record.drafter_principal_ref || record.drafter_principal_ref === record.principal_ref) fail(`${gateId} 缺少独立审查身份或起草者自签`);
+    const bytes = readFileSync(path.resolve(root, item.subject_ref));
+    if (record.subject_ref !== item.subject_ref || record.subject_digest !== createHash('sha256').update(bytes).digest('hex')) fail(`${gateId} 批准依据过期`);
+    const document = parseDocument(bytes.toString(), { uniqueKeys: true, maxAliasCount: 0 });
+    if (document.errors.length) fail(`${gateId} 审阅包不可解析`);
+    const review = document.toJS({ maxAliasCount: 0 });
+    if (review?.gate_id !== gateId || !Array.isArray(review.basis)) fail(`${gateId} 审阅包身份或依据缺失`);
+    for (const asset of item.basis.filter(asset => ![item.approval_ref, item.subject_ref].includes(asset.ref))) {
+      if (!review.basis.some(bound => bound.ref === asset.ref && bound.digest === asset.digest)) fail(`${gateId} 批准范围未覆盖证据: ${asset.ref}`);
+    }
+  }
+  // Bind the aggregate approval to the exact check evidence it covers.
+  for (const id of seen) for (const asset of state.checks[id].basis) {
+    if (!item.basis.some(bound => bound.ref === asset.ref && bound.digest === asset.digest)) fail(`${gateId} 未覆盖检查依据: ${id}/${asset.ref}`);
+  }
+  return { gate: gateId, checks: [...seen], result: 'passed' };
+}

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

@@ -7,8 +7,8 @@ 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");
-const ID_PATTERN = /^(stage|gate|artifact|work-unit|evidence)\.[a-z0-9][a-z0-9-]*$/;
-const COLLECTIONS = ["stages", "gates", "artifacts", "work_units", "evidence"];
+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"];
 
 function fail(message) {
   throw new TypeError(message);
@@ -106,7 +106,7 @@ export function validateRegistry(registry, { baseline = DEFAULT_BASELINE } = {})
     if (!(key in policy)) fail(`id_policy 缺少字段: ${key}`);
   }
   if (policy.published_ids_immutable !== true) fail("published_ids_immutable 必须为 true");
-  if (policy.pattern !== "^(stage|gate|artifact|work-unit|evidence)\\.[a-z0-9][a-z0-9-]*$") fail("id_policy.pattern 不符合固定命名空间");
+  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 (!Array.isArray(policy.deprecated_ids)) fail("deprecated_ids 必须是数组");
   const ids = new Map();
@@ -126,7 +126,7 @@ export function validateRegistry(registry, { baseline = DEFAULT_BASELINE } = {})
       ids.set(id, collection);
     }
   }
-  for (const gate of registry.gates) {
+  for (const gate of [...registry.gates, ...registry.checks]) {
     requireReference(ids, gate.stage, `${gate.id}.stage`);
     if (ids.get(gate.stage) !== "stages") fail(`${gate.id}.stage 必须引用 stage.*`);
     if (!Array.isArray(gate.evidence) || gate.evidence.length === 0) fail(`${gate.id}.evidence 必须是非空数组`);
@@ -134,12 +134,27 @@ export function validateRegistry(registry, { baseline = DEFAULT_BASELINE } = {})
       requireReference(ids, reference, `${gate.id}.evidence`);
       if (ids.get(reference) !== "evidence") fail(`${gate.id}.evidence 必须引用 evidence.*`);
     }
+    for (const reference of gate.requires_checks ?? []) {
+      requireReference(ids, reference, `${gate.id}.requires_checks`);
+      if (ids.get(reference) !== "checks" || reference === gate.id) fail(`${gate.id}.requires_checks 必须引用其他 check.*`);
+    }
     for (const reference of gate.requires_gates ?? []) {
       requireReference(ids, reference, `${gate.id}.requires_gates`);
       if (ids.get(reference) !== "gates") fail(`${gate.id}.requires_gates 必须引用 gate.*`);
       if (reference === gate.id) fail(`${gate.id}.requires_gates 不得引用自身`);
     }
   }
+  const visiting = new Set(), visited = new Set();
+  const controls = new Map([...registry.gates, ...registry.checks].map(record => [record.id, record]));
+  function visit(id) {
+    if (visiting.has(id)) fail(`生命周期检查依赖循环: ${id}`);
+    if (visited.has(id)) return;
+    visiting.add(id);
+    const record = controls.get(id);
+    for (const next of [...(record.requires_checks || []), ...(record.requires_gates || [])]) visit(next);
+    visiting.delete(id); visited.add(id);
+  }
+  for (const id of controls.keys()) visit(id);
   for (const artifact of registry.artifacts) {
     requireReference(ids, artifact.stage, `${artifact.id}.stage`);
     if (ids.get(artifact.stage) !== "stages") fail(`${artifact.id}.stage 必须引用 stage.*`);
@@ -152,12 +167,14 @@ 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}\` 模式：它校验结构和派生文档，不改变运行时状态 schema 或人工批准语义。`, "",
+    `> 此结构区由 \`docs/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")} |`);
-  lines.push("", "## 2. 生命周期对象", "", "门禁是需要裁决的审查点；产物、工作单元和证据不是门禁的同义词。未命中条件的门禁记录 \`not-applicable\` 及原因，不生成空文档。", "", "### 2.1 条件门禁", "", "| 稳定 ID | 门禁 | 所属阶段 | 触发条件 | 前置门禁 | 必须留下的证据 |", "|---|---|---|---|---|---|");
-  for (const gate of registry.gates) lines.push(`| \`${gate.id}\` | ${display(gate, "name")} | \`${gate.stage}\` | ${display(gate, "trigger")} | ${(gate.requires_gates ?? []).map((id) => `\`${id}\``).join("、") || "无"} | ${gate.evidence.map((id) => `\`${id}\``).join("、")} |`);
+  lines.push("", "## 2. 生命周期对象", "", "门禁是需要裁决的审查点；产物、工作单元和证据不是门禁的同义词。未命中条件的门禁记录 \`not-applicable\` 及原因，不生成空文档。", "", "### 2.1 条件门禁", "", "| 稳定 ID | 门禁 | 所属阶段 | 触发条件 | 前置门禁 / 检查 | 必须留下的证据 |", "|---|---|---|---|---|---|");
+  for (const gate of registry.gates) lines.push(`| \`${gate.id}\` | ${display(gate, "name")} | \`${gate.stage}\` | ${display(gate, "trigger")} | ${[...(gate.requires_gates ?? []), ...(gate.requires_checks ?? [])].map((id) => `\`${id}\``).join("、") || "无"} | ${gate.evidence.map((id) => `\`${id}\``).join("、")} |`);
+  lines.push("", "### 内部检查与自动前置条件", "", "检查失败仍阻断。专业审查记录作为聚合门禁证据，不单独请求用户批准；自动检查通过不授权实现或发布。", "", "| 稳定 ID | 检查 | 阶段 | 触发条件 |", "|---|---|---|---|");
+  for (const check of registry.checks) lines.push(`| \`${check.id}\` | ${display(check, "name")} | \`${check.stage}\` | ${display(check, "trigger")} |`);
   lines.push("", "### 2.2 生命周期产物", "", "| 稳定 ID | 产物 | 所属阶段 | 触发条件 |", "|---|---|---|---|");
   for (const artifact of registry.artifacts) lines.push(`| \`${artifact.id}\` | ${display(artifact, "name")} | \`${artifact.stage}\` | ${display(artifact, "trigger")} |`);
   lines.push("", "### 2.3 执行证据", "", "| 稳定 ID | 证据 | 说明 |", "|---|---|---|");

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;