create-yss-spec 3.2.0 → 3.3.1

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/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

@@ -0,0 +1,141 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+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 ORCHESTRATION_CONTRACT_REF = ".agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml";
+const SKILL_REGISTRY_REF = "docs/agents/yss-skill-registry.yaml";
+
+function read(relativePath) {
+  return readFileSync(path.join(ROOT, relativePath), "utf8");
+}
+
+function sha256(source) {
+  return createHash("sha256").update(source).digest("hex");
+}
+
+function loadYaml(relativePath, label) {
+  const document = parseDocument(read(relativePath), { maxAliasCount: 0, uniqueKeys: true });
+  if (document.errors.length) throw new TypeError(`无法解析${label}: ${document.errors[0].message}`);
+  const value = document.toJS({ maxAliasCount: 0 });
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError(`${label}必须是对象`);
+  return value;
+}
+
+function canonicalize(value) {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonicalize(value[key])]));
+  }
+  return value;
+}
+
+function selectById(records, id, label) {
+  if (!id) return null;
+  const selected = records.find((record) => record.id === id);
+  if (!selected) throw new TypeError(`未知${label}: ${id}`);
+  return selected;
+}
+
+function collectPathReferences(value, references = new Set()) {
+  if (Array.isArray(value)) {
+    for (const item of value) collectPathReferences(item, references);
+  } else if (value && typeof value === "object") {
+    for (const item of Object.values(value)) collectPathReferences(item, references);
+  } else if (typeof value === "string" && /(?:^|\/)[^\s]+\.(?:md|ya?ml|json|mjs)(?:#.*)?$/.test(value)) {
+    references.add(value);
+  }
+  return references;
+}
+
+function selectedSkills(route, skillRegistry) {
+  if (!route) return [];
+  const ids = new Set([
+    route.primary_skill,
+    route.native?.skill,
+    ...(route.supporting_skills ?? []),
+    ...(route.skills ?? []),
+  ].filter(Boolean));
+  return skillRegistry.skills.filter((skill) => ids.has(skill.id));
+}
+
+export function queryLifecycleContext({ mode, stageId, workUnitId, include = [] } = {}) {
+  if (!mode && !stageId && !workUnitId && include.length === 0) {
+    throw new TypeError("至少提供 --mode、--stage、--work-unit 或 --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, "工作单元");
+
+  if (mode && !(mode in orchestration.modes)) throw new TypeError(`未知模式: ${mode}`);
+  const normalizedIncludes = [...new Set(include.flatMap((value) => value.split(",")).map((value) => value.trim()).filter(Boolean))].sort();
+  for (const key of normalizedIncludes) {
+    if (!(key in orchestration)) throw new TypeError(`未知编排合同子树: ${key}`);
+  }
+
+  const route = workUnitId ? orchestration.work_unit_routes?.[workUnitId] ?? null : null;
+  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 ? {
+    next: orchestration.transition_graph?.routes?.[workUnitId] ?? [],
+    forbidden_shortcuts: (orchestration.transition_graph?.forbidden_shortcuts ?? [])
+      .filter((edge) => edge.from === workUnitId || edge.to === workUnitId),
+  } : null;
+
+  const result = {
+    schema_version: 1,
+    query: {
+      include: normalizedIncludes,
+      mode: mode ?? null,
+      stage: stageId ?? null,
+      work_unit: workUnitId ?? null,
+    },
+    sources: {
+      lifecycle_registry: {
+        ref: LIFECYCLE_REGISTRY_REF,
+        semantic_sha256: semanticDigest(lifecycle),
+        status: lifecycle.status,
+      },
+      orchestration_contract: {
+        ref: ORCHESTRATION_CONTRACT_REF,
+        sha256: sha256(read(ORCHESTRATION_CONTRACT_REF)),
+      },
+      skill_registry: {
+        ref: SKILL_REGISTRY_REF,
+        sha256: sha256(read(SKILL_REGISTRY_REF)),
+        status: skillRegistry.status,
+      },
+    },
+    lifecycle: {
+      artifacts,
+      evidence: lifecycle.evidence.filter((item) => evidenceIds.has(item.id)),
+      gates,
+      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,
+    },
+    skills: selectedSkills(route, skillRegistry),
+  };
+  result.references = [...collectPathReferences(result), LIFECYCLE_REGISTRY_REF, ORCHESTRATION_CONTRACT_REF, SKILL_REGISTRY_REF]
+    .filter((value, index, all) => all.indexOf(value) === index)
+    .sort();
+  return canonicalize(result);
+}

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

@@ -2,9 +2,11 @@ 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";
+const REPOSITORY_PREPARATION_WORK_UNIT = "work-unit.implementation-repository-preparation";
 
 function deepFreeze(value) {
   if (!value || typeof value !== "object" || Object.isFrozen(value)) return value;
@@ -14,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"],
@@ -22,13 +24,14 @@ 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", TICKET_DECOMPOSITION_WORK_UNIT],
-  "work-unit.prototype-design": ["work-unit.technical-analysis", TICKET_DECOMPOSITION_WORK_UNIT],
-  "work-unit.technical-analysis": [TICKET_DECOMPOSITION_WORK_UNIT],
+  "work-unit.spec-synthesis": ["work-unit.prototype-design", "work-unit.technical-analysis", REPOSITORY_PREPARATION_WORK_UNIT],
+  "work-unit.prototype-design": ["work-unit.technical-analysis", REPOSITORY_PREPARATION_WORK_UNIT],
+  "work-unit.technical-analysis": [REPOSITORY_PREPARATION_WORK_UNIT],
+  [REPOSITORY_PREPARATION_WORK_UNIT]: [TICKET_DECOMPOSITION_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"],
@@ -56,6 +59,15 @@ const BLOCKING_SIGNALS = Object.freeze({
   contractNotCurrent: "slice-contract-not-current",
   missingEvidence: "ticket-formalization-evidence-missing",
   stale: "ticket-formalization-stale",
+  repositoryDecisionRequired: "implementation-repository-decision-required",
+  repositoryLocationRequired: "implementation-repository-location-required",
+  repositoryOnboardingIncomplete: "implementation-repository-onboarding-incomplete",
+  scaffoldChoiceRequired: "scaffold-choice-required",
+  scaffoldContractUnapproved: "scaffold-contract-unapproved",
+  scaffoldGenerationIncomplete: "scaffold-generation-incomplete",
+  scaffoldVerificationFailed: "scaffold-verification-failed",
+  frontendTemplateUnavailable: "frontend-template-unavailable",
+  implementationRepositoriesStale: "implementation-repositories-stale",
 });
 
 const allowedResult = (evidenceRefs = []) => ({
@@ -113,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]); }
@@ -130,9 +143,105 @@ 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;
+  }
   return decisionState ? validateDecisionBoundary(currentWorkUnit, decisionState, options) : allowedResult();
 }
 
+/**
+ * Validate the aggregate stage-5 repository-preparation result. Every affected
+ * delivery role must resolve to an onboarded existing repository or a freshly
+ * generated and verified scaffold. Unaffected roles need an explicit reason.
+ */
+export function validateImplementationRepositoriesReady(state, { exists = existsSync } = {}) {
+  const preparation = state?.implementation_repository_preparation;
+  const impacts = state?.delivery_impacts;
+  const signals = [];
+  const missing = [];
+  const evidenceRefs = Array.isArray(preparation?.evidence_refs) ? preparation.evidence_refs : [];
+
+  if (!preparation || preparation.result !== "completed" || !Array.isArray(preparation.projects)) {
+    return blockedResult([BLOCKING_SIGNALS.repositoryDecisionRequired], ["completed implementation_repository_preparation with projects"]);
+  }
+  if (preparation.current_version !== true || state?.implementation_repositories_stale === true) {
+    signals.push(BLOCKING_SIGNALS.implementationRepositoriesStale);
+    missing.push("implementation repository preparation is current");
+  }
+  if (evidenceRefs.length === 0 || evidenceRefs.some((ref) => !isReadable(ref, exists))) {
+    signals.push(BLOCKING_SIGNALS.repositoryOnboardingIncomplete);
+    missing.push("readable implementation_repository_preparation.evidence_refs");
+  }
+
+  for (const role of ["backend", "frontend"]) {
+    const affected = impacts?.[role] === true;
+    const projects = preparation.projects.filter((project) => project?.delivery_role === role);
+    if (affected && projects.length === 0) {
+      signals.push(BLOCKING_SIGNALS.repositoryDecisionRequired);
+      missing.push(`${role} repository decision`);
+    }
+    if (!affected && projects.length === 0) {
+      signals.push(BLOCKING_SIGNALS.repositoryDecisionRequired);
+      missing.push(`${role} not-applicable decision with reason`);
+    }
+    for (const project of projects) {
+      if (!hasText(project.project_id) || !hasText(project.status)) {
+        signals.push(BLOCKING_SIGNALS.repositoryDecisionRequired);
+        missing.push(`${role} project_id and status`);
+        continue;
+      }
+      if (project.status === "not-applicable") {
+        if (affected || !hasText(project.reason)) {
+          signals.push(BLOCKING_SIGNALS.repositoryDecisionRequired);
+          missing.push(`${project.project_id} not-applicable reason for an unaffected role`);
+        }
+        continue;
+      }
+      if (!hasText(project.repository_ref) || !hasText(project.project_root) || !hasText(project.repository_scope)) {
+        signals.push(BLOCKING_SIGNALS.repositoryLocationRequired);
+        missing.push(`${project.project_id} repository_ref, project_root and repository_scope`);
+      }
+      if (project.status === "existing-and-onboarded") {
+        if (project.onboarding_result?.status !== "completed" || !isReadable(project.onboarding_result?.ref, exists)) {
+          signals.push(BLOCKING_SIGNALS.repositoryOnboardingIncomplete);
+          missing.push(`${project.project_id} readable completed onboarding result`);
+        }
+      } else if (project.status === "initialized-and-verified") {
+        if (role === "backend" && !hasText(project.architecture_family)) {
+          signals.push(BLOCKING_SIGNALS.scaffoldChoiceRequired);
+          missing.push(`${project.project_id} confirmed backend architecture_family`);
+        }
+        const contract = project.scaffold_contract;
+        if (![3, 4].includes(contract?.schema_version) || contract?.status !== "approved" || contract?.persisted !== true || contract?.current_version !== true || (role === "frontend" && contract?.schema_version !== 4)) {
+          signals.push(BLOCKING_SIGNALS.scaffoldContractUnapproved);
+          missing.push(`${project.project_id} approved persisted current scaffold contract`);
+        }
+        if (!isReadable(project.scaffold_manifest_ref, exists)) {
+          signals.push(BLOCKING_SIGNALS.scaffoldGenerationIncomplete);
+          missing.push(`${project.project_id} readable scaffold manifest`);
+        }
+        if (project.scaffold_verification?.status !== "passed" || !isReadable(project.scaffold_verification?.ref, exists)) {
+          signals.push(BLOCKING_SIGNALS.scaffoldVerificationFailed);
+          missing.push(`${project.project_id} readable passed scaffold verification`);
+        }
+        if (role === "frontend" && project.template_available !== true) {
+          signals.push(BLOCKING_SIGNALS.frontendTemplateUnavailable);
+          missing.push(`${project.project_id} verified frontend template source`);
+        }
+      } else {
+        signals.push(BLOCKING_SIGNALS.repositoryDecisionRequired);
+        missing.push(`${project.project_id} supported repository preparation status`);
+      }
+    }
+  }
+  return signals.length === 0 ? allowedResult(evidenceRefs) : blockedResult(signals, missing, evidenceRefs);
+}
+
 function validateDecisionBoundary(workUnit, state, options) {
   try { assertWorkUnitUserDecision(workUnit, state, options); return allowedResult(); }
   catch (error) { return blockedResult([error.code || "user-decision-invalid"], [error.message]); }
@@ -145,6 +254,8 @@ function validateDecisionBoundary(workUnit, state, options) {
 export function validateTicketFormalization(state, { exists = existsSync, read = (ref) => readFileSync(ref, "utf8"), ...decisionOptions } = {}) {
   try { enforceFrontendDelivery(state, { root: decisionOptions.root, phase: "implementation" }); }
   catch (error) { return blockedResult(["frontend-delivery-blocked"], [error.message]); }
+  const repositoryResult = validateImplementationRepositoriesReady(state, { exists });
+  if (repositoryResult.result === "blocked") return repositoryResult;
   const decomposition = state?.ticket_decomposition_result;
   const ticket = state?.vertical_slice_ticket;
   const contract = state?.slice_contract;
@@ -276,6 +387,7 @@ export function validateImplementationEntry(state, options = {}) {
 export const lifecycleTransitionContract = Object.freeze({
   implementation_work_unit: IMPLEMENTATION_WORK_UNIT,
   ticket_decomposition_work_unit: TICKET_DECOMPOSITION_WORK_UNIT,
+  repository_preparation_work_unit: REPOSITORY_PREPARATION_WORK_UNIT,
   next_routes: NEXT_ROUTES,
   blocking_signals: BLOCKING_SIGNALS,
 });

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);
+}