create-yss-spec 3.0.1 → 3.1.0

package/template/scripts/verify-business-language-scenarios

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { loadRegistry, renderLifecycleStructure, renderWorkUnits, semanticDigest, validateRegistry } from "./lib/lifecycle-registry.mjs";
+
+const ROOT = path.resolve(import.meta.dirname, "..");
+const PUBLIC_FILES = [
+  "CONTEXT.md",
+  "docs/templates/spec-template.md",
+  "docs/design/templates/product-overview-design-template.md",
+  "docs/process/harness-executive-blueprint.md",
+  ".agents/skills/yss-stage-decision/SKILL.md",
+];
+const JARGON = ["DDD", "子域", "限界上下文", "Context Map", "统一语言", "不变量", "Strategic Design", "Tactical Design"];
+
+function read(relativePath) {
+  return readFileSync(path.join(ROOT, relativePath), "utf8");
+}
+
+for (const relativePath of PUBLIC_FILES) {
+  const source = read(relativePath);
+  for (const term of JARGON) {
+    assert.equal(source.includes(term), false, `${relativePath} 不应向业务角色展示术语: ${term}`);
+  }
+}
+
+const lifecycle = read(".agents/skills/yss-product-lifecycle/SKILL.md");
+for (const phrase of [
+  "机会与目标 → 业务故事 → 责任与交接 → 规则、例子与疑问 → 可验收需求 → 页面验证 → 业务任务 → 交接研发",
+  "业务方案总览",
+  "不成为新的事实源",
+]) assert.match(lifecycle, new RegExp(phrase));
+
+const registry = read("docs/process/lifecycle-registry.yaml");
+for (const stableId of ["work-unit.domain-strategy-design", "artifact.domain-strategy", "gate.domain-strategy-approved"]) {
+  assert.match(registry, new RegExp(`id: ${stableId.replaceAll(".", "\\.")}`));
+}
+for (const displayName of ["业务边界与协作梳理", "业务边界与规则设计", "业务边界与规则确认", "方案决策包"]) {
+  assert.match(registry, new RegExp(displayName));
+}
+
+const registryContract = loadRegistry();
+const withoutPublicPresentation = structuredClone(registryContract);
+for (const collection of ["stages", "gates", "artifacts", "work_units", "evidence"]) {
+  for (const record of withoutPublicPresentation[collection]) {
+    for (const key of Object.keys(record).filter((key) => key.startsWith("public_"))) delete record[key];
+  }
+}
+assert.equal(semanticDigest(registryContract), semanticDigest(withoutPublicPresentation), "public_* 展示字段不得改变稳定 ID 语义摘要");
+const rendered = `${renderLifecycleStructure(registryContract)}${renderWorkUnits(registryContract)}`;
+for (const displayName of ["业务边界与协作梳理", "业务边界与规则设计", "业务边界与规则确认", "方案决策包"]) {
+  assert.match(rendered, new RegExp(displayName));
+}
+const invalidPresentation = structuredClone(registryContract);
+invalidPresentation.artifacts[0].public_name = "";
+assert.throws(() => validateRegistry(invalidPresentation, { baseline: null }), /public_name 必须是非空字符串/);
+
+process.stdout.write("本体业务角色通俗语言场景验证通过\n");

package/template/scripts/verify-context-contract

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { parseContextContract, resolveContextTermRefs } from "./lib/context-contract.mjs";
+
+try {
+  const { values } = parseArgs({ options: { root: { type: "string", default: process.cwd() }, "allowed-context": { type: "string", multiple: true }, "term-ref": { type: "string", multiple: true }, json: { type: "boolean", default: false } }, strict: true });
+  const contract = parseContextContract({ root: values.root, allowedContextIds: values["allowed-context"] });
+  const resolved = resolveContextTermRefs(contract, values["term-ref"] || []);
+  const contextSnapshot = { context_ref: contract.context_ref, context_schema_version: contract.context_schema_version, document_digest: contract.document_digest, referenced_terms_digest: resolved.referenced_terms_digest, term_refs: resolved.terms.map((term) => term.term_ref) };
+  const result = { result: "completed", ...contextSnapshot, context_snapshot: contextSnapshot, process_term_count: contract.process_terms, business_term_count: contract.business_terms.length };
+  process.stdout.write(`${JSON.stringify(result, null, values.json ? 2 : 0)}\n`);
+} catch (error) {
+  process.stderr.write(`${JSON.stringify({ result: "blocked", reason_code: error.code || "context-contract-invalid", errors: error.problems || [error.message] }, null, 2)}\n`);
+  process.exitCode = 1;
+}

package/template/scripts/verify-context-contract-scenarios

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+const ROOT = path.resolve(import.meta.dirname, "..");
+const validator = path.join(ROOT, "scripts/verify-context-contract");
+
+function contextSource(rows = [], scopeHeader = "适用业务责任区") {
+  return `---
+context_schema_version: 1
+---
+# 领域上下文
+
+本文档只记录稳定业务语言。
+
+## 流程术语
+
+| 术语 | 含义 | 英文标识 | 避免 / 备注 |
+|---|---|---|---|
+| Spec | 产品研发规格。 | — |  |
+
+## 业务术语
+
+| 术语 | 含义 | 英文标识 | ${scopeHeader} | 避免 / 备注 |
+|---|---|---|---|---|
+${rows.join("\n")}
+`;
+}
+
+function run(root, ...args) {
+  return spawnSync(process.execPath, [validator, "--root", root, ...args], {
+    cwd: ROOT,
+    encoding: "utf8",
+  });
+}
+
+function expectBlocked(result, pattern, label) {
+  assert.notEqual(result.status, 0, `${label} 应被阻断`);
+  assert.match(`${result.stdout}\n${result.stderr}`, pattern, label);
+}
+
+const sandbox = mkdtempSync(path.join(tmpdir(), "yss-context-contract-"));
+try {
+  const valid = path.join(sandbox, "valid");
+  mkdirSync(valid);
+  writeFileSync(path.join(valid, "CONTEXT.md"), contextSource([
+    "| 供应商 | 提供商品或服务的业务主体。 | Supplier | Global | 避免：`厂商` |",
+    "| 准入决定 | 合规审查形成的准入结论。 | AdmissionDecision | ComplianceReview | 避免：`审批结果` |",
+  ]));
+  const validResult = run(valid, "--allowed-context", "ComplianceReview", "--term-ref", "Global/Supplier", "--term-ref", "ComplianceReview/AdmissionDecision", "--json");
+  assert.equal(validResult.status, 0, validResult.stderr);
+  const validOutput = JSON.parse(validResult.stdout);
+  assert.equal(validOutput.result, "completed");
+  assert.match(validOutput.document_digest, /^sha256:[0-9a-f]{64}$/);
+  assert.match(validOutput.referenced_terms_digest, /^sha256:[0-9a-f]{64}$/);
+
+  const legacyHeader = path.join(sandbox, "legacy-header");
+  mkdirSync(legacyHeader);
+  writeFileSync(path.join(legacyHeader, "CONTEXT.md"), contextSource([
+    "| 供应商 | 提供商品或服务的业务主体。 | Supplier | Global |  |",
+  ], "适用限界上下文"));
+  assert.equal(run(legacyHeader, "--term-ref", "Global/Supplier").status, 0, "旧表头应继续兼容读取");
+
+  const lowercase = path.join(sandbox, "lowercase");
+  mkdirSync(lowercase);
+  writeFileSync(path.join(lowercase, "context.md"), contextSource());
+  expectBlocked(run(lowercase), /根目录.*CONTEXT\.md|大小写/, "小写文件名");
+
+  const nested = path.join(sandbox, "nested");
+  mkdirSync(path.join(nested, "contexts/Foo"), { recursive: true });
+  writeFileSync(path.join(nested, "CONTEXT.md"), contextSource());
+  writeFileSync(path.join(nested, "contexts/Foo/CONTEXT.md"), contextSource());
+  expectBlocked(run(nested), /嵌套.*CONTEXT\.md|只允许项目根目录/, "嵌套 CONTEXT.md");
+
+  const mapped = path.join(sandbox, "mapped");
+  mkdirSync(mapped);
+  writeFileSync(path.join(mapped, "CONTEXT.md"), contextSource());
+  writeFileSync(path.join(mapped, "CONTEXT-MAP.md"), "# Context Map\n");
+  expectBlocked(run(mapped), /CONTEXT-MAP\.md.*禁止/, "CONTEXT-MAP.md");
+
+  const duplicate = path.join(sandbox, "duplicate");
+  mkdirSync(duplicate);
+  writeFileSync(path.join(duplicate, "CONTEXT.md"), contextSource([
+    "| 准入决定 | 第一种定义。 | AdmissionDecision | ComplianceReview |  |",
+    "| 准入结论 | 第二种定义。 | AdmissionDecision | ComplianceReview |  |",
+  ]));
+  expectBlocked(run(duplicate, "--allowed-context", "ComplianceReview"), /术语身份重复/, "重复术语身份");
+
+  const unknownContext = path.join(sandbox, "unknown-context");
+  mkdirSync(unknownContext);
+  writeFileSync(path.join(unknownContext, "CONTEXT.md"), contextSource([
+    "| 准入决定 | 合规审查形成的准入结论。 | AdmissionDecision | UnknownContext |  |",
+  ]));
+  expectBlocked(run(unknownContext, "--allowed-context", "ComplianceReview"), /未在业务边界与规则设计中登记/, "未知作用域");
+
+  expectBlocked(run(valid, "--allowed-context", "ComplianceReview", "--term-ref", "CONTEXT.md#Supplier"), /术语引用格式非法/, "Markdown 伪锚点");
+  expectBlocked(run(valid, "--allowed-context", "ComplianceReview", "--term-ref", "ComplianceReview/Missing"), /无法解析/, "缺失术语引用");
+
+  process.stdout.write("CONTEXT Contract 场景验证通过\n");
+} finally {
+  rmSync(sandbox, { recursive: true, force: true });
+}

package/template/scripts/verify-context-reconciliation

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { parseArgs } from "node:util";
+import { fileURLToPath } from "node:url";
+import { parseDocument } from "./vendor/yaml.mjs";
+import { resolveContextTermRefs, verifyContextSnapshot } from "./lib/context-contract.mjs";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const schemaPath = path.join(repoRoot, "docs/process/schemas/context-reconciliation.schema.json");
+const pythonValidator = String.raw`
+import json, sys
+from jsonschema import Draft202012Validator
+schema = json.load(open(sys.argv[1], encoding="utf-8"))
+value = json.load(sys.stdin)
+errors = sorted(Draft202012Validator(schema).iter_errors(value), key=lambda error: list(error.absolute_path))
+for error in errors:
+    where = ".".join(str(part) for part in error.absolute_path) or "<root>"
+    print(f"{where}: {error.message}", file=sys.stderr)
+sys.exit(1 if errors else 0)
+`;
+
+function parseFile(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 });
+}
+
+try {
+  const { values, positionals } = parseArgs({ options: { root: { type: "string", default: process.cwd() } }, allowPositionals: true, strict: true });
+  if (positionals.length !== 1) throw new TypeError("用法: scripts/verify-context-reconciliation [--root <repo>] <record.yaml|json>");
+  const root = path.resolve(values.root);
+  const file = path.resolve(positionals[0]);
+  const value = parseFile(file);
+  const schemaResult = spawnSync("python3", ["-c", pythonValidator, schemaPath], { encoding: "utf8", input: JSON.stringify(value) });
+  if (schemaResult.status !== 0) throw new TypeError(`${schemaResult.stdout}${schemaResult.stderr}`.trim());
+  const manifest = parseFile(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}`);
+  }
+  process.stdout.write("Context reconciliation 验证通过\n");
+} catch (error) {
+  process.stderr.write(`Context reconciliation 验证失败: ${error.message}\n`);
+  process.exitCode = 1;
+}

package/template/scripts/verify-context-reconciliation-scenarios

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+const repoRoot = path.resolve(import.meta.dirname, "..");
+const root = mkdtempSync(path.join(tmpdir(), "yss-context-reconciliation-"));
+mkdirSync(path.join(root, "docs", "evidence"), { recursive: true });
+writeFileSync(path.join(root, "yss-project.yaml"), "schema_version: 1\nrepository_mode: project-instance\n");
+writeFileSync(path.join(root, "CONTEXT.md"), `---
+context_schema_version: 1
+---
+
+# CONTEXT
+
+## 流程术语
+
+| 术语 | 含义 | 英文标识 | 避免 / 备注 |
+|---|---|---|---|
+| 阶段 | 生命周期阶段 | — | |
+
+## 业务术语
+
+| 术语 | 含义 | 英文标识 | 适用限界上下文 | 避免 / 备注 |
+|---|---|---|---|---|
+| 供应商 | 提供产品或服务的主体 | Supplier | Global | |
+| 准入结论 | 合规审查的准入结果 | AdmissionDecision | ComplianceReview | |
+`);
+
+function run(command, args) {
+  return spawnSync(command, args, { cwd: repoRoot, encoding: "utf8" });
+}
+
+const snapshotResult = run("scripts/verify-context-contract", ["--root", root, "--allowed-context", "ComplianceReview", "--term-ref", "Global/Supplier", "--term-ref", "ComplianceReview/AdmissionDecision", "--json"]);
+if (snapshotResult.status !== 0) throw new Error(snapshotResult.stderr || snapshotResult.stdout);
+const snapshot = JSON.parse(snapshotResult.stdout).context_snapshot;
+
+function record(overrides = {}) {
+  return {
+    schema_version: 1,
+    repository_mode: "project-instance",
+    stage: "stage.discovery",
+    work_unit: "work-unit.domain-strategy-design",
+    status: "reconciled",
+    context_snapshot: snapshot,
+    changes: { added: ["Global/Supplier", "ComplianceReview/AdmissionDecision"], updated: [], deprecated: [] },
+    unresolved_terms: [],
+    evidence_refs: ["CONTEXT.md"],
+    ...overrides,
+  };
+}
+
+function verify(name, value, expectedStatus) {
+  const file = path.join(root, "docs", "evidence", `${name}.json`);
+  writeFileSync(file, JSON.stringify(value, null, 2));
+  const result = run("scripts/verify-context-reconciliation", ["--root", root, file]);
+  if (result.status !== expectedStatus) throw new Error(`${name}: expected ${expectedStatus}, got ${result.status}\n${result.stdout}${result.stderr}`);
+}
+
+verify("valid", record(), 0);
+verify("stale", record({ context_snapshot: { ...snapshot, document_digest: "sha256:stale" } }), 1);
+verify("blocked", record({ status: "blocked", unresolved_terms: [{ term: "准入状态", reason: "英文标识未确认", owner: "product-owner", next_action: "确认命名" }] }), 1);
+verify("missing-term", record({ changes: { added: ["ComplianceReview/Unknown"], updated: [], deprecated: [] } }), 1);
+verify("not-applicable-project", record({ status: "not-applicable", reason: "无术语变化" }), 1);
+writeFileSync(path.join(root, "yss-project.yaml"), "schema_version: 1\nrepository_mode: template-source\n");
+verify("template-source", record({ repository_mode: "template-source", status: "not-applicable", reason: "模板源仅校验 CONTEXT.md 结构", changes: { added: [], updated: [], deprecated: [] } }), 0);
+
+process.stdout.write("Context reconciliation scenarios passed\n");

package/template/scripts/verify-digital-human-roles-scenarios

@@ -39,7 +39,7 @@ function mustFail(doc, pattern, label) {
 validateDefaultDigitalHumanRoles();
 
 const tester = loadDigitalHumanRoles().roles.find((role) => role.id === "role.test-engineer");
-for (const skill of ["code-review", "alibaba-java-code-style", "yss-ui", "yss-page-module-development", "yss-domain", "yss-application", "yss-web-controller", "yss-dto", "mapstruct", "lombok"]) {
+for (const skill of ["code-review", "alibaba-java-code-style", "yss-ui", "yss-ui-business-page-generation", "yss-domain", "yss-application", "yss-web-controller", "yss-dto", "mapstruct", "lombok"]) {
   if (!tester.core_skills.includes(skill)) throw new TypeError(`role.test-engineer 缺少只读专项检查 skill: ${skill}`);
 }
 if (tester.forbidden_skills.includes("yss-ui") || tester.forbidden_skills.includes("alibaba-java-code-style")) {

package/template/scripts/verify-frontend-implementation-evidence

@@ -5,9 +5,10 @@ import path from "node:path";
 import { parseArgs } from "node:util";
 import { fileURLToPath } from "node:url";
 import { parseDocument } from "./vendor/yaml.mjs";
+import { validateVisualBaseline } from "../.agents/skills/yss-prototype-stage/scripts/visual-baseline-contract.mjs";
 
-const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
-const schemaPath = path.join(root, "docs/process/schemas/frontend-implementation-evidence.schema.json");
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const schemaPath = path.join(repoRoot, "docs/process/schemas/frontend-implementation-evidence.schema.json");
 const validator = String.raw`
 import json
 import sys
@@ -22,27 +23,49 @@ sys.exit(1 if errors else 0)
 `;
 
 try {
-  const { values, positionals } = parseArgs({ options: { "allow-template": { type: "boolean" } }, allowPositionals: true, strict: true });
-  if (positionals.length !== 1) throw new TypeError("用法: scripts/verify-frontend-implementation-evidence [--allow-template] <file.yaml>");
+  const { values, positionals } = parseArgs({ options: { "allow-template": { type: "boolean" }, root: { type: "string", default: repoRoot } }, allowPositionals: true, strict: true });
+  if (positionals.length !== 1) throw new TypeError("用法: scripts/verify-frontend-implementation-evidence [--allow-template] [--root <repo>] <file.yaml>");
+  const root = path.resolve(values.root);
   const document = parseDocument(readFileSync(path.resolve(positionals[0]), "utf8"), { maxAliasCount: 0, uniqueKeys: true });
   if (document.errors.length) throw new TypeError(document.errors[0].message);
   const value = document.toJS({ maxAliasCount: 0 });
-  const result = spawnSync("python3", ["-c", validator, schemaPath], { cwd: root, encoding: "utf8", input: JSON.stringify(value) });
+  if (value.schema_version === 1 && !values["allow-template"]) throw new TypeError("migration-required: frontend implementation evidence v1 是只读历史资产；在途 UI 工作必须升级 v2 并绑定 Visual Baseline case_id");
+  const result = spawnSync("python3", ["-c", validator, schemaPath], { cwd: repoRoot, encoding: "utf8", input: JSON.stringify(value) });
   if (result.status !== 0) throw new TypeError(`${result.stdout}${result.stderr}`.trim());
   if (!values["allow-template"] && value.template !== false) throw new TypeError("正式证据必须设置 template: false");
   if (!values["allow-template"] && value.status !== "approved") throw new TypeError("正式证据必须达到 status: approved");
   const serialized = JSON.stringify(value);
   if (!values["allow-template"] && /REPLACE_ME|<[^>]+>|docs\/\.scratch\/example/.test(serialized)) throw new TypeError("正式证据不得保留模板占位值");
   if (!values["allow-template"]) {
-    for (const field of ["prototype_ref", "spec_ref"]) {
-      const reference = value[field];
+    for (const field of ["prototype_ref", "spec_ref", "visual_baseline.manifest_ref"]) {
+      const reference = field === "visual_baseline.manifest_ref" ? value.visual_baseline.manifest_ref : value[field];
       if (!/^https?:\/\//.test(reference) && !existsSync(path.resolve(root, reference))) throw new TypeError(`${field} 不可读取: ${reference}`);
     }
+    const baselineDocument = parseDocument(readFileSync(path.resolve(root, value.visual_baseline.manifest_ref), "utf8"), { maxAliasCount: 0, uniqueKeys: true });
+    if (baselineDocument.errors.length) throw new TypeError(baselineDocument.errors[0].message);
+    const baseline = baselineDocument.toJS({ maxAliasCount: 0 });
+    const baselineValidation = await validateVisualBaseline(baseline, { bundleRoot: path.dirname(path.resolve(root, value.visual_baseline.manifest_ref)) });
+    if (baselineValidation.errors.length) throw new TypeError(`Visual Baseline Bundle 无效:\n${baselineValidation.errors.join("\n")}`);
+    if (baseline.baseline_id !== value.visual_baseline.baseline_id || baseline.version !== value.visual_baseline.version || baseline.bundle?.digest !== value.visual_baseline.digest || baseline.status !== "approved") throw new TypeError("Visual Baseline 身份、版本、digest 或状态不一致");
+    const manifestCaseIds = new Set((baseline.cases ?? []).map((item) => item.case_id));
+    const selectedCaseIds = value.visual_baseline.case_ids;
+    if (selectedCaseIds.some((id) => !manifestCaseIds.has(id))) throw new TypeError("前端证据引用了 Visual Baseline 中不存在的 case_id");
+    for (const item of value.route_and_page_inventory) if (item.case_ids.some((id) => !selectedCaseIds.includes(id))) throw new TypeError("route_and_page_inventory.case_ids 必须属于选定 Visual Baseline cases");
+    if (value.kind === "plan" && value.baseline_case_ids.some((id) => !selectedCaseIds.includes(id))) throw new TypeError("baseline_case_ids 必须属于选定 Visual Baseline cases");
   }
   if (!values["allow-template"] && value.kind === "verification") {
     if (value.console_warning_check !== "pass") throw new TypeError("前端验证必须通过 console warning 检查");
-    if (value.uncovered_differences.length > 0 && !value.difference_owner) throw new TypeError("存在未覆盖差异时必须填写 difference_owner");
+    if (value.uncovered_differences.length > 0) throw new TypeError("存在未解释视觉差异，不能通过前端实现还原验证");
     if (value.independent_review?.status !== "approved") throw new TypeError("前端验证必须通过独立 UI fidelity review");
+    const expected = [...value.visual_baseline.case_ids].sort();
+    const actual = value.case_results.map((item) => item.case_id).sort();
+    if (new Set(actual).size !== actual.length || JSON.stringify(actual) !== JSON.stringify(expected)) throw new TypeError("case_results 必须与选定 Visual Baseline case_ids 一一对应");
+    for (const item of value.case_results) {
+      if (item.result !== "pass" || item.uncovered_difference !== false) throw new TypeError(`${item.case_id} 存在未通过或未解释差异`);
+      for (const field of ["baseline_image_ref", "implementation_image_ref", "diff_ref"]) if (!existsSync(path.resolve(root, item[field]))) throw new TypeError(`${item.case_id}.${field} 不可读取`);
+      if (item.mask_ref !== "not-applicable" && !existsSync(path.resolve(root, item.mask_ref))) throw new TypeError(`${item.case_id}.mask_ref 不可读取`);
+    }
+    if (value.actual_verification.some((item) => item.exit_code !== 0)) throw new TypeError("pnpm fresh verification 存在非零退出码");
   }
   process.stdout.write(`前端实现还原 ${value.kind} 验证通过\n`);
 } catch (error) {

package/template/scripts/verify-frontend-implementation-evidence-scenarios

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { sealVisualBaseline } from "../.agents/skills/yss-prototype-stage/scripts/visual-baseline-contract.mjs";
+
+const repoRoot = path.resolve(import.meta.dirname, "..");
+const root = mkdtempSync(path.join(os.tmpdir(), "yss-frontend-evidence-"));
+const write = (relative, value = relative) => {
+  const file = path.join(root, relative); mkdirSync(path.dirname(file), { recursive: true }); writeFileSync(file, Buffer.isBuffer(value) || typeof value === "string" ? value : JSON.stringify(value, null, 2)); return relative;
+};
+write("docs/spec.md"); write("docs/prototype.html");
+for (const file of ["verification/desktop.png", "verification/narrow.png", "verification/desktop-diff.png", "verification/narrow-diff.png", "verification/pnpm.txt", "verification/review.md"]) write(file);
+const digest = `sha256:${"a".repeat(64)}`;
+function pngHeader(width, height) { const value = Buffer.alloc(24); Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]).copy(value, 0); value.writeUInt32BE(13, 8); value.write("IHDR", 12, "ascii"); value.writeUInt32BE(width, 16); value.writeUInt32BE(height, 20); return value; }
+write("baseline/images/primary-desktop.png", pngHeader(1440, 900)); write("baseline/images/primary-narrow.png", pngHeader(390, 844));
+write("baseline/sources/prototype.html", "<main>demo</main>\n"); write("baseline/sources/interaction.md", "# Interaction\n"); write("baseline/sources/states.md", "# States\n");
+write("baseline/capture/capture.mjs", "// capture\n"); write("baseline/capture/result.json", "{\"result\":\"passed\"}\n");
+const baselineFile = write("baseline/visual-baseline.yaml", {
+  schema_version: 1, baseline_id: "visual-baseline.demo", feature: "demo", version: "v1", status: "approved",
+  bundle: { format: "portable-directory", root_ref: "baseline", digest, size_bytes: 0, max_image_bytes: 5242880, max_bundle_bytes: 104857600 },
+  source: { prototype_ref: "sources/prototype.html", prototype_digest: digest, interaction_spec_ref: "sources/interaction.md", interaction_spec_digest: digest, state_matrix_ref: "sources/states.md", state_matrix_digest: digest },
+  capture_environment: { browser: "chromium", browser_version: "140.0.0", operating_system: "linux", fonts_digest: digest, device_scale_factor: 1, color_space: "srgb", locale: "zh-CN", timezone: "Asia/Shanghai", animations_disabled: true, cursor_hidden: true, capture_script_ref: "capture/capture.mjs", capture_script_digest: digest, capture_result_ref: "capture/result.json", capture_result_digest: digest },
+  cases: [
+    { case_id: "primary-desktop", route: "/demo", page: "DemoPage", state: "normal", viewport: { name: "desktop", width: 1440, height: 900, scroll_mode: "viewport", scroll_position: 0 }, theme: "compact-light", locale: "zh-CN", data_scenario: "primary", image_ref: "images/primary-desktop.png", image_digest: digest, image_size_bytes: 1, mask_ref: "not-applicable", mask_digest: "not-applicable", mask_size_bytes: 0, semantic_refs: ["sources/prototype.html", "sources/interaction.md"], allowed_differences: [], result: "passed" },
+    { case_id: "primary-narrow", route: "/demo", page: "DemoPage", state: "normal", viewport: { name: "narrow", width: 390, height: 844, scroll_mode: "viewport", scroll_position: 0 }, theme: "compact-light", locale: "zh-CN", data_scenario: "primary", image_ref: "images/primary-narrow.png", image_digest: digest, image_size_bytes: 1, mask_ref: "not-applicable", mask_digest: "not-applicable", mask_size_bytes: 0, semantic_refs: ["sources/states.md"], allowed_differences: [], result: "passed" }
+  ]
+});
+const sealedBaseline = await sealVisualBaseline(path.join(root, baselineFile), path.join(root, "baseline"));
+const visual_baseline = { baseline_id: "visual-baseline.demo", version: "v1", digest: sealedBaseline.bundle.digest, manifest_ref: "baseline/visual-baseline.yaml", status: "approved", case_ids: ["primary-desktop", "primary-narrow"] };
+const base = {
+  schema_version: 2, template: false, status: "approved", prototype_ref: "docs/prototype.html", spec_ref: "docs/spec.md", visual_baseline,
+  route_and_page_inventory: [{ route: "/demo", page: "DemoPage", case_ids: ["primary-desktop", "primary-narrow"] }], pnpm_commands: ["pnpm test"]
+};
+const plan = { ...base, kind: "plan", baseline_case_ids: ["primary-desktop", "primary-narrow"], desktop_viewport: "1440x900", narrow_viewport: "390x844", state_cases: ["normal"] };
+const verification = {
+  ...base, kind: "verification",
+  case_results: [
+    { case_id: "primary-desktop", baseline_image_ref: "baseline/images/primary-desktop.png", implementation_image_ref: "verification/desktop.png", diff_ref: "verification/desktop-diff.png", mask_ref: "not-applicable", result: "pass", uncovered_difference: false, explanation: "无未解释差异" },
+    { case_id: "primary-narrow", baseline_image_ref: "baseline/images/primary-narrow.png", implementation_image_ref: "verification/narrow.png", diff_ref: "verification/narrow-diff.png", mask_ref: "not-applicable", result: "pass", uncovered_difference: false, explanation: "无未解释差异" }
+  ],
+  interaction_results: ["normal passed"], console_warning_check: "pass", actual_verification: [{ command: "pnpm test", exit_code: 0, executed_at: "2026-09-05T00:00:00Z", evidence_ref: "verification/pnpm.txt" }],
+  uncovered_differences: [], difference_owner: null, independent_review: { reviewer: "reviewer-1", candidate_digest: digest, status: "approved", findings_ref: "verification/review.md" }
+};
+const run = (name, value, expected, pattern) => {
+  const file = write(`${name}.json`, value);
+  const result = spawnSync("scripts/verify-frontend-implementation-evidence", ["--root", root, path.join(root, file)], { cwd: repoRoot, encoding: "utf8" });
+  if (result.status !== expected || (pattern && !pattern.test(`${result.stdout}${result.stderr}`))) throw new Error(`${name} unexpected\n${result.stdout}${result.stderr}`);
+};
+run("valid-plan", plan, 0);
+run("valid-verification", verification, 0);
+run("missing-case", { ...verification, case_results: verification.case_results.slice(0, 1) }, 1, /一一对应/);
+run("unexplained", { ...verification, uncovered_differences: ["间距偏差"], difference_owner: "frontend" }, 1, /未解释视觉差异/);
+run("nonzero", { ...verification, actual_verification: [{ ...verification.actual_verification[0], exit_code: 1 }] }, 1, /非零退出码/);
+process.stdout.write("Frontend implementation evidence v2 scenarios passed\n");

package/template/scripts/verify-grill-with-docs-context-scenarios

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+
+const root = path.resolve(import.meta.dirname, "..");
+const skill = readFileSync(path.join(root, ".agents/skills/grill-with-docs/SKILL.md"), "utf8");
+for (const marker of ["scripts/verify-context-contract --root . --json", "domain-modeling/CONTEXT-FORMAT.md", "<ContextId>/<EnglishIdentifier>", "context_reconciliation", "referenced_terms_digest", "template-source", "not-applicable", "yss-product-lifecycle"]) {
+  if (!skill.includes(marker)) throw new Error(`grill-with-docs 缺少统一 Context Contract 标记: ${marker}`);
+}
+for (const script of ["scripts/verify-context-contract-scenarios", "scripts/verify-context-reconciliation-scenarios"]) {
+  const result = spawnSync(path.join(root, script), { cwd: root, encoding: "utf8" });
+  if (result.status !== 0) throw new Error(`${script} failed\n${result.stdout}${result.stderr}`);
+}
+process.stdout.write("grill-with-docs Context Contract scenarios passed\n");

package/template/scripts/verify-lifecycle-checkpoint

@@ -5,7 +5,7 @@ import path from "node:path";
 import { parseArgs } from "node:util";
 import { fileURLToPath } from "node:url";
 import { parseDocument } from "./vendor/yaml.mjs";
-import { assertCheckpointApprovals } from "./lib/approval-record.mjs";
+import { assertCheckpointApprovals, assertCheckpointUserDecisions } from "./lib/approval-record.mjs";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const schemaPath = path.join(root, "docs/process/schemas/lifecycle-checkpoint.schema.json");
@@ -32,6 +32,14 @@ try {
   const result = spawnSync("python3", ["-c", validator, schemaPath], { cwd: root, encoding: "utf8", input: JSON.stringify(value) });
   if (result.status !== 0) throw new TypeError(`${result.stdout}${result.stderr}`.trim());
   assertCheckpointApprovals(value, sourcePath);
+  assertCheckpointUserDecisions(value);
+  if (value.repository_mode === "project-instance" && ["paused-human-gate", "completed"].includes(value.status)) {
+    if (value.context_reconciliation?.status !== "reconciled" || !value.context_reconciliation?.ref) throw new TypeError("project-instance 在会签或完成前必须具有 reconciled context_reconciliation");
+    const reconciliation = path.resolve(root, value.context_reconciliation.ref);
+    const checked = spawnSync(path.join(root, "scripts/verify-context-reconciliation"), ["--root", root, reconciliation], { cwd: root, encoding: "utf8" });
+    if (checked.status !== 0) throw new TypeError(checked.stderr.trim() || "context_reconciliation 无效");
+  }
+  if (value.repository_mode === "template-source" && value.context_reconciliation?.status !== "not-applicable") throw new TypeError("template-source context_reconciliation 必须为 not-applicable");
   process.stdout.write("生命周期 checkpoint 验证通过\n");
 } catch (error) {
   process.stderr.write(`生命周期 checkpoint 验证失败: ${error.message}\n`);

package/template/scripts/verify-lifecycle-transition-scenarios

@@ -1,17 +1,25 @@
 #!/usr/bin/env node
 import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, readFileSync, existsSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { buildImplementationFixture } from "./fixtures/user-decision/build-fixture.mjs";
+const temp = mkdtempSync(path.join(os.tmpdir(), "lifecycle-decision-test-"));
+process.on("exit", () => rmSync(temp, { recursive: true, force: true }));
+const approval = buildImplementationFixture(temp, "docs/.scratch/demo/issues/01-valid-slice.md");
 import { validateImplementationEntry, validateNextRoute, validateTicketFormalization } from "./lib/lifecycle-transition.mjs";
 
 const exists = (ref) => [
   "docs/process/lifecycle-registry.yaml",
   "docs/.scratch/demo/issues/01-valid-slice.md",
   "docs/.scratch/demo/evidence/ticket-decomposition-result.yaml",
-].includes(ref);
+].includes(ref) || existsSync(ref);
 const decompositionResult = `result_schema: workflow-execution-result-v1\nwork_unit: work-unit.ticket-decomposition\nresult: completed\nevidence_refs:\n  - docs/.scratch/demo/evidence/ticket-decomposition-result.yaml\n`;
-const read = (ref) => ref === "docs/.scratch/demo/evidence/ticket-decomposition-result.yaml" ? decompositionResult : "";
+const read = (ref) => ref === "docs/.scratch/demo/evidence/ticket-decomposition-result.yaml" ? decompositionResult : readFileSync(ref, "utf8");
 const options = { exists, read };
 
 const validTicketState = {
+  ...approval.state,
   predecessor_work_unit: "work-unit.ticket-decomposition",
   tracker_kind: "local-markdown",
   ticket_decomposition_result_ref: "docs/.scratch/demo/evidence/ticket-decomposition-result.yaml",
@@ -92,14 +100,16 @@ const arbitraryReadable = validateTicketFormalization({
 }, options);
 assert.equal(arbitraryReadable.result, "blocked");
 assert.ok(arbitraryReadable.blocking_signals.includes("ticket-decomposition-incomplete"));
+const remoteApproval = buildImplementationFixture(path.join(temp, "remote"), "https://github.com/example/project/issues/1");
 assert.equal(validateTicketFormalization({
   ...validTicketState,
+  ...remoteApproval.state,
   tracker_kind: "github",
   ticket_decomposition_result_ref: "https://github.com/example/project/issues/1",
   ticket_decomposition_result: { result: "completed", evidence_refs: ["https://github.com/example/project/issues/1"] },
   vertical_slice_ticket_ref: "https://github.com/example/project/issues/1",
   vertical_slice_ticket: { ref: "https://github.com/example/project/issues/1", kind: "vertical-slice-ticket", role: "ready-for-agent" },
   slice_contract: { ...validTicketState.slice_contract, ticket_ref: "https://github.com/example/project/issues/1" },
-}, { ...options, exists: (ref) => ref === "https://github.com/example/project/issues/1", read: (ref) => ref === "https://github.com/example/project/issues/1" ? decompositionResult.replace("docs/.scratch/demo/evidence/ticket-decomposition-result.yaml", "https://github.com/example/project/issues/1") : "" }).result, "allowed");
+}, { ...options, exists: (ref) => ref === "https://github.com/example/project/issues/1", read: (ref) => ref === "https://github.com/example/project/issues/1" ? decompositionResult.replace("docs/.scratch/demo/evidence/ticket-decomposition-result.yaml", "https://github.com/example/project/issues/1") : readFileSync(ref, "utf8") }).result, "allowed");
 
 process.stdout.write("生命周期转换压力场景验证通过\n");

package/template/scripts/verify-retired-skill-ids

@@ -4,18 +4,44 @@ import { existsSync } from "node:fs";
 import path from "node:path";
 import { PROJECTION_ROOTS, ROOT } from "./lib/skill-supply-chain.mjs";
 
-const retired = ["yss-router", "yss-source-index"];
-const allowed = (relative) => relative === "docs/agents/skill-migrations.md"
+const retired = [
+  "ask-matt",
+  "dispatching-parallel-agents",
+  "loop-me",
+  "migrate-to-shoehorn",
+  "prototype-page-acceptance",
+  "scaffold-exercises",
+  "setup-pre-commit",
+  "setup-ts-deep-modules",
+  "teach",
+  "writing-beats",
+  "writing-fragments",
+  "writing-shape",
+  "yss-microapp-commit",
+  "yss-page-module-development",
+  "yss-router",
+  "yss-source-index",
+];
+const allowed = (relative, line) => relative === "docs/agents/skill-migrations.md"
   || relative.includes("/docs/agents/skill-migrations.md")
   || relative.endsWith(".template-source/wiki/raw/skill-migrations.md")
   || relative.startsWith(".template-source/evidence/")
   || relative.includes("/.template-source/evidence/")
   || relative.includes("/tests/")
+  || relative.startsWith(".template-source/tooling/node/test/")
+  || relative.endsWith("/skills/.yss-skills-manifest.json")
+  || relative === "docs/agents/yss-ui-skills-integration.md"
+  || relative === "scripts/lib/skill-governance.mjs"
+  || (relative.endsWith("/skills/yss-product-lifecycle/references/orchestration-contract.yaml") && line.includes("retired_shared_skills:"))
   || relative.endsWith("scripts/verify-retired-skill-ids")
   || relative.endsWith("scripts/lib/skill-supply-chain.mjs")
   || relative.endsWith("scripts/lib/implementation-contract-compiler.mjs");
 
-const search = spawnSync("rg", ["-n", "--hidden", "--glob", "!.git/**", "--glob", "!.codegraph/**", "--glob", "!submodules/**", retired.join("|"), "."], {
+const escaped = retired.filter((id) => id !== "teach").map((id) => id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+const exactSkillIdPattern = `(?<![a-z0-9-])(?:${escaped.join("|")})(?![a-z0-9-])`;
+const teachSkillPattern = "(?:`teach`|/teach(?:/|\\b)|(?:^|[\\[,])\\s*[\"']?teach[\"']?\\s*(?=[,\\]])|\\b(?:id|name)\\s*:\\s*[\"']?teach[\"']?\\b)";
+const retiredSkillPattern = `(?:${exactSkillIdPattern}|${teachSkillPattern})`;
+const search = spawnSync("rg", ["-n", "--pcre2", "--hidden", "--glob", "!.git/**", "--glob", "!.codegraph/**", "--glob", "!submodules/**", retiredSkillPattern, "."], {
   cwd: ROOT,
   encoding: "utf8"
 });
@@ -25,7 +51,7 @@ if (![0, 1].includes(search.status)) {
 }
 const violations = search.stdout.split(/\r?\n/).filter(Boolean).filter((line) => {
   const match = line.match(/^\.\/(.*?):\d+:/);
-  return !match || !allowed(match[1]);
+  return !match || !allowed(match[1], line);
 });
 for (const name of retired) {
   const roots = [".agents/skills", ...PROJECTION_ROOTS];