create-yss-spec 3.0.0 → 3.1.0

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-repository-scope-scenarios

@@ -217,8 +217,8 @@ const markerFiles = [
   ["docs/templates/cross-repo-slice-template.md", "superproject-gitlink-update"],
   ["docs/templates/implementation-routing-template.md", "git-submodule-harness-apps"],
   [".agents/skills/implementation-repo-onboarding/SKILL.md", "git-submodule"],
-  [".agents/skills/yss-router/references/slice-implementation-contract.md", "git-submodule-harness-apps"],
-  [".agents/skills/yss-router/references/router-contract.yaml", "git-submodule-harness-apps"],
+  [".agents/skills/yss-implementation-contract-compiler/references/slice-implementation-contract.md", "git-submodule-harness-apps"],
+  [".agents/skills/yss-implementation-contract-compiler/references/compiler-contract.yaml", "git-submodule-harness-apps"],
   [".agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml", "repository_scope=git-submodule"],
   [".agents/skills/yss-ddd-scaffold-generator/scripts/generate_scaffold.mjs", "gitSubmoduleScaffoldViolation"],
   [".agents/skills/yss-ddd-scaffold-generator/scripts/generate_scaffold.mjs", "refuseGitlinkAsRegularDirectory"]

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

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { PROJECTION_ROOTS, ROOT } from "./lib/skill-supply-chain.mjs";
+
+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 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"
+});
+if (![0, 1].includes(search.status)) {
+  process.stderr.write(search.stderr || "无法扫描退役 skill id\n");
+  process.exit(1);
+}
+const violations = search.stdout.split(/\r?\n/).filter(Boolean).filter((line) => {
+  const match = line.match(/^\.\/(.*?):\d+:/);
+  return !match || !allowed(match[1], line);
+});
+for (const name of retired) {
+  const roots = [".agents/skills", ...PROJECTION_ROOTS];
+  for (const root of roots) if (existsSync(path.join(ROOT, root, name))) violations.push(`${root}/${name}: retired physical directory remains`);
+}
+if (violations.length) {
+  process.stderr.write(`退役 skill id 仍存在于活跃资产:\n${violations.join("\n")}\n`);
+  process.exitCode = 1;
+} else process.stdout.write("retired skill ids are absent from active assets\n");

package/template/scripts/verify-scaffold-architecture-decision-scenarios

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import { attachScaffoldDecisionFixture } from "./fixtures/user-decision/build-fixture.mjs";
+import path from "node:path";
+import { parseDocument } from "./vendor/yaml.mjs";
+
+const root = mkdtempSync(path.join(os.tmpdir(), "scaffold-decision-scenarios-"));
+process.on("exit", () => rmSync(root, { recursive: true, force: true }));
+const verifier = path.resolve("scripts/verify-scaffold-architecture-decisions");
+const digest = `sha256:${"1".repeat(64)}`;
+const confirmation = `\n    user_confirmation:\n      confirmed_by: user\n      channel: codex\n      confirmation_ref: turn://1\n      confirmed_at: 2026-09-05T01:00:00+08:00\n      normalized_text: 确认 MVC`;
+function run(name, body) {
+  const file = path.join(root, `${name}.yaml`);
+  const value = parseDocument(body).toJS();
+  value.decisions = value.decisions.map((decision) => attachScaffoldDecisionFixture(path.join(root, name, decision.project_id), decision));
+  writeFileSync(file, JSON.stringify(value));
+  return spawnSync(verifier, [file], { encoding: "utf8" });
+}
+const base = `schema_version: 1\nkind: scaffold-architecture-decisions\ntemplate: false\nstatus: current\ndecisions:\n`;
+const mvc = `${base}  - decision_id: scaffold-decision.main\n    project_id: main\n    parent_project_id: null\n    status: lifecycle-approved\n    recommended_architecture: layered-mvc\n    recommendation_reasons: [CRUD 与报表为主]\n    confirmed_architecture: layered-mvc\n    override_reason: null\n    inheritance_mode: root-default\n    inherited_from: null\n    platform_profile: spring-boot-2.7-jdk8\n    architecture_profile: layered-mvc-service\n    verification_database: h2\n    production_database: not-bound\n    requested_capabilities: [feign-client]\n    resolved_modules: [server, service, repository, client, feign-client]\n    resolution_version: 1${confirmation}\n    decision_inputs_digest: ${digest}\n`;
+assert.equal(run("mvc", mvc).status, 0);
+assert.notEqual(run("missing-confirmation", mvc.replace("confirmation_ref: turn://1", "confirmation_ref: null")).status, 0);
+assert.notEqual(run("invalid-closure", mvc.replace("[server, service, repository, client, feign-client]", "[server, service, repository]")).status, 0);
+const child = `${mvc}  - decision_id: scaffold-decision.child\n    project_id: child\n    parent_project_id: main\n    status: lifecycle-approved\n    recommended_architecture: domain-driven\n    recommendation_reasons: [存在复杂状态机]\n    confirmed_architecture: layered-mvc\n    override_reason: 继承本体的统一架构\n    inheritance_mode: inherit\n    inherited_from: main\n    platform_profile: spring-boot-2.7-jdk8\n    architecture_profile: layered-mvc-service\n    verification_database: h2\n    production_database: not-bound\n    requested_capabilities: []\n    resolved_modules: [server, service, repository]\n    resolution_version: 1${confirmation}\n    decision_inputs_digest: ${digest}\n`;
+assert.equal(run("child", child).status, 0);
+assert.notEqual(run("inherit-mismatch", child.replace("confirmed_architecture: layered-mvc\n    override_reason: 继承本体的统一架构\n    inheritance_mode: inherit", "confirmed_architecture: domain-driven\n    override_reason: null\n    inheritance_mode: inherit")).status, 0);
+process.stdout.write("脚手架架构选择场景验证通过\n");

package/template/scripts/verify-scaffold-architecture-decisions

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { fileURLToPath } from "node:url";
+import { parseDocument } from "./vendor/yaml.mjs";
+import { validateJsonSchema } from "./lib/json-schema.mjs";
+import { loadSkillRegistry } from "./lib/skill-registry.mjs";
+import { assertScaffoldUserDecision } from "./lib/user-decision.mjs";
+import { validateArchitectureIdentity } from "./lib/backend-architecture.mjs";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const schemaPath = path.join(repoRoot, "docs/process/schemas/scaffold-architecture-decisions.schema.json");
+const MVC_ORDER = ["server", "service", "repository", "adapter", "client", "feign-client"];
+const DDD_MODULES = ["domain", "application", "infrastructure", "adapter", "bootstrap"];
+const CAPABILITIES = { "external-integration": ["adapter"], "published-client": ["client"], "feign-client": ["client", "feign-client"] };
+
+function mvcModules(capabilities) {
+  const result = new Set(["server", "service", "repository"]);
+  for (const capability of capabilities) for (const module of CAPABILITIES[capability] ?? []) result.add(module);
+  return MVC_ORDER.filter((module) => result.has(module));
+}
+
+try {
+  const { values, positionals } = parseArgs({ options: { "allow-template": { type: "boolean" } }, allowPositionals: true, strict: true });
+  if (positionals.length !== 1) throw new TypeError("用法: scripts/verify-scaffold-architecture-decisions [--allow-template] <file.yaml>");
+  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 });
+  validateJsonSchema(value, schemaPath, { cwd: repoRoot, label: "scaffold architecture decision schema" });
+  if (!values["allow-template"] && value.template !== false) throw new TypeError("正式决策记录必须设置 template: false");
+  const ids = new Set();
+  const projects = new Map();
+  for (const decision of value.decisions) {
+    if (ids.has(decision.decision_id) || projects.has(decision.project_id)) throw new TypeError("decision_id 与 project_id 必须唯一");
+    ids.add(decision.decision_id);
+    projects.set(decision.project_id, decision);
+    const confirmed = ["user-confirmed", "lifecycle-approved", "consumed"].includes(decision.status);
+    const confirmation = decision.user_confirmation;
+    if (confirmed && (!decision.confirmed_architecture || Object.values(confirmation).some((item) => item === null || item === ""))) throw new TypeError(`${decision.project_id} 已确认状态必须提供完整用户确认引用`);
+    if (!confirmed && decision.status !== "stale" && decision.confirmed_architecture !== null) throw new TypeError(`${decision.project_id} 未确认状态不得预填 confirmed_architecture`);
+    if (decision.confirmed_architecture && decision.confirmed_architecture !== decision.recommended_architecture && !decision.override_reason) throw new TypeError(`${decision.project_id} 覆盖 Agent 推荐时必须说明 override_reason`);
+    if (decision.inheritance_mode === "root-default" && (decision.parent_project_id !== null || decision.inherited_from !== null)) throw new TypeError(`${decision.project_id} 根默认不得声明父项目`);
+    if (["inherit", "override"].includes(decision.inheritance_mode) && (!decision.parent_project_id || decision.inherited_from !== decision.parent_project_id)) throw new TypeError(`${decision.project_id} 子项目继承引用不完整`);
+    if (confirmed && value.template === false) {
+      assertScaffoldUserDecision(decision);
+    }
+    const registry = loadSkillRegistry();
+    validateArchitectureIdentity({ ...decision, architecture_family: decision.confirmed_architecture ?? decision.recommended_architecture, generator_skill: registry.architecture_profiles?.[decision.architecture_profile]?.generator_skill, contract_digest: decision.decision_inputs_digest }, registry);
+  }
+  for (const decision of value.decisions) {
+    if (!decision.parent_project_id) continue;
+    const parent = projects.get(decision.parent_project_id);
+    if (!parent) throw new TypeError(`${decision.project_id} 引用了不存在的父项目`);
+    if (decision.inheritance_mode === "inherit" && decision.confirmed_architecture && parent.confirmed_architecture && decision.confirmed_architecture !== parent.confirmed_architecture) throw new TypeError(`${decision.project_id} 继承值与父项目不一致；需要改为 override`);
+  }
+  process.stdout.write("脚手架架构选择记录验证通过\n");
+} catch (error) {
+  process.stderr.write(`脚手架架构选择记录验证失败: ${error.message}\n`);
+  process.exitCode = 1;
+}