create-yss-spec 3.4.9 → 3.5.0

package/template/scripts/lib/design-md.mjs

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { parseDocument } from "../vendor/yaml.mjs";
+
+const repositoryRoot = path.resolve(new URL("../..", import.meta.url).pathname);
+const designPath = path.join(repositoryRoot, "DESIGN.md");
+const projectionDir = path.join(repositoryRoot, "docs/design/tokens");
+const manifestPath = path.join(projectionDir, ".design-md-projection.json");
+const syncMetadataPath = path.join(repositoryRoot, "docs/design/design-system-sync.yaml");
+const expectedSections = ["Overview", "Colors", "Typography", "Layout", "Elevation & Depth", "Shapes", "Components", "Do's and Don'ts"];
+const requiredFrontmatter = ["version", "name", "description", "colors", "typography", "rounded", "spacing", "components"];
+const componentProperties = new Set(["backgroundColor", "textColor", "typography", "rounded", "padding", "size", "height", "width"]);
+
+function sha256(value) { return createHash("sha256").update(value).digest("hex"); }
+function fail(message) { throw new Error(message); }
+function escapeRegExp(value) { return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); }
+
+function resolveValue(value, frontmatter) {
+  const match = typeof value === "string" ? value.match(/^\{(colors|typography|rounded|spacing)\.([\w-]+)\}$/) : null;
+  return match ? frontmatter[match[1]]?.[match[2]] : value;
+}
+
+function projectedCssVariables(frontmatter) {
+  const components = frontmatter.components;
+  return {
+    "yss-color-primary-control": resolveValue(components["button-primary"].backgroundColor, frontmatter),
+    "yss-color-primary-control-hover": resolveValue(components["button-primary-hover"].backgroundColor, frontmatter),
+    "yss-color-on-primary": resolveValue(components["button-primary"].textColor, frontmatter),
+    "yss-control-height": resolveValue(components["button-primary"].height, frontmatter),
+    "yss-card-padding": resolveValue(components["card-default"].padding, frontmatter),
+    "yss-control-height-compact": resolveValue(components["button-compact"].height, frontmatter),
+    "yss-card-compact-padding": resolveValue(components["card-compact"].padding, frontmatter)
+  };
+}
+
+function writeCssProjection(frontmatter) {
+  const cssPath = path.join(projectionDir, "variables.css");
+  let source = readFileSync(cssPath, "utf8");
+  for (const [name, value] of Object.entries(projectedCssVariables(frontmatter))) {
+    const declaration = `  --${name}: ${value};`;
+    const pattern = new RegExp(`^\\s*--${escapeRegExp(name)}:.*;$`, "m");
+    source = pattern.test(source) ? source.replace(pattern, declaration) : source.replace(":root {\n", `:root {\n${declaration}\n`);
+  }
+  writeFileSync(cssPath, source);
+}
+
+function validateCssProjection(frontmatter) {
+  const source = readFileSync(path.join(projectionDir, "variables.css"), "utf8");
+  for (const [name, value] of Object.entries(projectedCssVariables(frontmatter))) {
+    if (!new RegExp(`^\\s*--${escapeRegExp(name)}: ${escapeRegExp(String(value))};$`, "m").test(source)) fail(`variables.css 的 --${name} 与 DESIGN.md 不一致`);
+  }
+}
+
+function readDesign(file = designPath) {
+  const source = readFileSync(file, "utf8");
+  if (!source.startsWith("---\n")) fail(`${path.relative(repositoryRoot, file)} 缺少 YAML frontmatter`);
+  const end = source.indexOf("\n---", 4);
+  if (end < 0) fail(`${path.relative(repositoryRoot, file)} frontmatter 未闭合`);
+  const document = parseDocument(source.slice(4, end), { uniqueKeys: true, maxAliasCount: 0 });
+  if (document.errors.length) fail(document.errors[0].message);
+  const frontmatter = document.toJS({ maxAliasCount: 0 });
+  for (const field of requiredFrontmatter) if (!frontmatter?.[field]) fail(`frontmatter 缺少 ${field}`);
+  const body = source.slice(end + 4);
+  const headings = [...body.matchAll(/^## ([^\n]+)$/gm)].map((match) => match[1].trim());
+  const actual = headings.slice(0, expectedSections.length);
+  if (JSON.stringify(actual) !== JSON.stringify(expectedSections)) fail(`canonical H2 章节顺序必须为: ${expectedSections.join(" → ")}`);
+  for (const section of expectedSections) {
+    if (headings.filter((heading) => heading === section).length !== 1) fail(`canonical H2 章节必须且只能出现一次: ${section}`);
+  }
+  const canonicalH1 = [...body.matchAll(/^# ([^\n]+)$/gm)].map((match) => match[1].trim()).filter((heading) => expectedSections.includes(heading));
+  if (canonicalH1.length > 0) fail(`canonical 正文章节必须使用 H2，不能使用 H1: ${canonicalH1.join(", ")}`);
+  for (const [name, component] of Object.entries(frontmatter.components)) {
+    if (!/^[a-z][a-z0-9-]*$/.test(name)) fail(`组件变体名称非法: ${name}`);
+    for (const key of Object.keys(component)) if (!componentProperties.has(key)) fail(`组件 ${name} 使用不支持的属性: ${key}`);
+  }
+  const references = [...source.matchAll(/\{(colors|typography|rounded|spacing)\.([\w-]+)\}/g)].map((match) => match[0]);
+  for (const reference of references) {
+    const [, group, token] = reference.match(/^\{([^}]+)\.([^}]+)\}$/);
+    if (frontmatter[group]?.[token] === undefined) fail(`悬空 token 引用: ${reference}`);
+  }
+  if (file === designPath && existsSync(syncMetadataPath)) {
+    const syncDocument = parseDocument(readFileSync(syncMetadataPath, "utf8"), { uniqueKeys: true, maxAliasCount: 0 });
+    if (syncDocument.errors.length) fail(syncDocument.errors[0].message);
+    const sync = syncDocument.toJS({ maxAliasCount: 0 })?.design_system_sync;
+    if (!sync?.baseline_sha256 || sync.baseline_sha256 !== sha256(source)) {
+      fail("design-system-sync.yaml 的 baseline_sha256 与 DESIGN.md 不一致，请更新跨仓同步摘要");
+    }
+    if (!Array.isArray(sync.synchronized_sections) || sync.synchronized_sections.length === 0) {
+      fail("design-system-sync.yaml 缺少 synchronized_sections");
+    }
+  }
+  return { source, frontmatter };
+}
+
+function runUpstream(args) {
+  const result = spawnSync("npx", ["--yes", "@google/design.md@0.4.0", ...args], { cwd: repositoryRoot, encoding: "utf8" });
+  if (result.error || result.status !== 0) fail(result.stderr?.trim() || result.stdout?.trim() || "design.md CLI 执行失败");
+  return result.stdout;
+}
+
+function projectionFiles() {
+  return ["theme.json", "tokens.default.json", "tokens.dark.json", "tokens.compact.json", "variables.css", "variables.dark.css"].map((file) => path.join(projectionDir, file));
+}
+
+function writeProjectionManifest() {
+  const { source } = readDesign();
+  const files = Object.fromEntries(projectionFiles().map((file) => [path.relative(repositoryRoot, file), sha256(readFileSync(file))]));
+  writeFileSync(manifestPath, `${JSON.stringify({ schema_version: 1, source: "DESIGN.md", source_sha256: sha256(source), files }, null, 2)}\n`);
+}
+
+function writeThemeProjection(frontmatter) {
+  const themeFile = path.join(projectionDir, "theme.json");
+  const theme = { token: {}, algorithm: "default" };
+  const token = theme.token || (theme.token = {});
+  const colors = frontmatter.colors;
+  const typography = frontmatter.typography;
+  const rounded = frontmatter.rounded;
+  const spacing = frontmatter.spacing;
+  Object.assign(token, {
+    colorPrimary: colors.primary,
+    colorSuccess: colors.success,
+    colorWarning: colors.warning,
+    colorError: colors.error,
+    colorInfo: colors.info ?? colors.primary,
+    colorTextBase: "#000000",
+    colorBgBase: colors.surface ?? "#ffffff",
+    colorBgLayout: colors["canvas-layout"] ?? "#f0f2f5",
+    colorText: colors.text,
+    colorTextSecondary: colors["text-secondary"],
+    colorBorder: colors.border ?? "#d9d9d9",
+    fontFamily: typography.body.fontFamily,
+    fontSize: Number.parseInt(typography.body.fontSize, 10),
+    borderRadius: Number.parseInt(rounded.md, 10),
+    sizeUnit: Number.parseInt(spacing.xxs, 10),
+    sizeStep: Number.parseInt(spacing.xxs, 10),
+    controlHeight: Number.parseInt(frontmatter.components["button-primary"].height, 10),
+    controlHeightSM: Number.parseInt(frontmatter.components["button-small"].height, 10),
+    controlHeightLG: Number.parseInt(frontmatter.components["button-large"].height, 10),
+    fontSizeSM: Number.parseInt(typography.caption.fontSize, 10),
+    borderRadiusSM: Number.parseInt(rounded.sm, 10),
+    borderRadiusLG: Number.parseInt(rounded.lg, 10),
+    padding: Number.parseInt(spacing.md, 10),
+    paddingSM: Number.parseInt(spacing.sm, 10),
+    paddingXS: Number.parseInt(spacing.xs, 10),
+    paddingLG: Number.parseInt(spacing.card, 10)
+  });
+  theme.components = { Card: { borderRadiusLG: token.borderRadiusLG, paddingLG: token.paddingLG } };
+  writeFileSync(themeFile, `${JSON.stringify(theme, null, 2)}\n`);
+}
+
+function writeAlgorithmProjections(toolchain) {
+  if (!toolchain) fail("export --write 需要 --antd-toolchain <独立作者工具目录>，固定 antd 6.6.4");
+  const require = createRequire(path.join(path.resolve(toolchain), "package.json"));
+  if (require("antd/package.json").version !== "6.6.4") fail("主题算法需要 antd 6.6.4");
+  const { theme } = require("antd");
+  const config = JSON.parse(readFileSync(path.join(projectionDir, "theme.json")));
+  const kebab = key => key.replace(/[A-Z]/g, letter => `-${letter.toLowerCase()}`);
+  const snapshots = {};
+  for (const [mode, algorithm] of Object.entries({ default: theme.defaultAlgorithm, dark: theme.darkAlgorithm, compact: theme.compactAlgorithm })) {
+    const token = { ...config.token };
+    // Let the dark algorithm derive neutral colors instead of pinning light aliases.
+    if (mode === "dark") for (const key of ["colorBgBase", "colorTextBase", "colorBgLayout", "colorText", "colorTextSecondary", "colorBorder"]) delete token[key];
+    snapshots[mode] = theme.getDesignToken({ token, algorithm });
+    writeFileSync(path.join(projectionDir, `tokens.${mode}.json`), JSON.stringify(snapshots[mode], null, 2) + "\n");
+  }
+  const rewrite = (css, token) => {
+    const values = Object.fromEntries(Object.entries(token).map(([key,value]) => [kebab(key),value]));
+    return css.replace(/(--brand-([\w-]+):\s*)([^;]+);/g, (all, prefix, key, old) => {
+      const value = values[key];
+      if (value === undefined || typeof value === "object") return all;
+      const unit = typeof value === "number" ? old.trim().match(/(?:px|ms|s)$/)?.[0] || "" : "";
+      return `${prefix}${value}${unit};`;
+    });
+  };
+  const cssPath = path.join(projectionDir, "variables.css");
+  const css = readFileSync(cssPath, "utf8");
+  const darkStart = css.indexOf('[data-theme="dark"]');
+  writeFileSync(cssPath, darkStart < 0 ? rewrite(css, snapshots.default) : rewrite(css.slice(0, darkStart), snapshots.default) + rewrite(css.slice(darkStart), snapshots.dark));
+  const darkPath = path.join(projectionDir, "variables.dark.css");
+  writeFileSync(darkPath, rewrite(readFileSync(darkPath, "utf8"), snapshots.dark));
+}
+
+function driftCheck() {
+  const { source, frontmatter } = readDesign();
+  validateCssProjection(frontmatter);
+  if (!existsSync(manifestPath)) fail(`缺少 ${path.relative(repositoryRoot, manifestPath)}，请先执行 export --write-manifest`);
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  if (manifest.source_sha256 !== sha256(source)) fail("DESIGN.md 已变化但投影未重新生成（source_sha256 漂移）");
+  for (const [relative, digest] of Object.entries(manifest.files || {})) {
+    const file = path.join(repositoryRoot, relative);
+    if (!existsSync(file) || sha256(readFileSync(file)) !== digest) fail(`派生文件漂移: ${relative}`);
+  }
+}
+
+function main() {
+  const [command, ...args] = process.argv.slice(2);
+  if (command === "lint") {
+    const file = args.find((arg) => !arg.startsWith("-")) || designPath;
+    readDesign(path.resolve(repositoryRoot, file));
+    process.stdout.write(`${runUpstream(["lint", file, "--format", "json"])}`);
+    return;
+  }
+  if (command === "diff") {
+    if (args.length < 2) fail("用法: design-md diff <before> <after>");
+    process.stdout.write(runUpstream(["diff", ...args.slice(0, 2), "--format", "json"]));
+    return;
+  }
+  if (command === "export") {
+    const format = args[0] || "dtcg";
+    const { frontmatter } = readDesign();
+    process.stdout.write(runUpstream(["export", "DESIGN.md", "--format", format]));
+    if (args.includes("--write")) {
+      const toolchain = args[args.indexOf("--antd-toolchain") + 1];
+      if (!args.includes("--antd-toolchain") || !toolchain) fail("缺少 --antd-toolchain");
+      writeThemeProjection(frontmatter);
+      writeAlgorithmProjections(toolchain);
+      writeCssProjection(frontmatter);
+    }
+    if (args.includes("--write-manifest")) writeProjectionManifest();
+    return;
+  }
+  if (command === "drift") { driftCheck(); process.stdout.write("DESIGN.md 投影无漂移\n"); return; }
+  fail("用法: design-md lint|diff|export|drift");
+}
+
+try { main(); } catch (error) { process.stderr.write(`${error.message}\n`); process.exitCode = 1; }

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

@@ -1,4 +1,4 @@
-import { readFileSync } from "node:fs";
+import { readFileSync } from './validation-phase.mjs';
 import path from "node:path";
 import { parseDocument } from "../vendor/yaml.mjs";
 import { loadRegistry, ROOT } from "./lifecycle-registry.mjs";

package/template/scripts/lib/existing-backend-architecture.mjs

@@ -1,6 +1,7 @@
 import {assertApprovedExecutionContext} from './approved-execution-context.mjs';
 import {createHash} from 'node:crypto';
-import {readFileSync,realpathSync,lstatSync,readdirSync} from 'node:fs';
+import { realpathSync } from 'node:fs';
+import { readFileSync, lstatSync, readdirSync } from './validation-phase.mjs';
 import path from 'node:path';
 import {execFileSync} from 'node:child_process';
 import {parseDocument} from '../vendor/yaml.mjs';
@@ -35,7 +36,7 @@ function inspectMaven(root,units){
  const script=`import json,sys,xml.etree.ElementTree as ET\nout=[]\nfor p in json.load(sys.stdin):\n r=ET.parse(p).getroot(); ns={'m':'http://maven.apache.org/POM/4.0.0'}; q=lambda s:r.find(s,ns)\n aid=q('m:artifactId'); aid=aid if aid is not None else q('artifactId')\n deps=[e.text.strip() for e in r.findall('m:dependencies/m:dependency/m:artifactId',ns)+r.findall('m:profiles/m:profile/m:dependencies/m:dependency/m:artifactId',ns)+r.findall('dependencies/dependency/artifactId') if e.text]\n modules=[e.text.strip() for e in r.findall('.//m:modules/m:module',ns)+r.findall('.//modules/module') if e.text]\n out.append({'artifact_id':aid.text.strip() if aid is not None else '', 'dependencies':deps, 'modules':modules})\nprint(json.dumps(out))`;
  try{return JSON.parse(execFileSync('python3',['-c',script],{input:JSON.stringify(units.map(u=>file(root,u.pom_ref))),encoding:'utf8',timeout:15000,maxBuffer:2*1024*1024}));}catch(error){requireThat(false,'ARCH_BUILD_INVALID',`无法读取实际 Maven 构建单元: ${error.message}`);}
 }
-export function verifyExistingArchitecture(identity,bindings,{root,registry,execution}={}){
+export function verifyExistingArchitecture(identity,bindings,{root,registry,execution,readOnly=false}={}){
  const profile=validateExistingArchitecture(identity,registry);
  requireThat(text(root),'ARCH_EVIDENCE_REF','需要治理 root');
  const baseline=bound(root,bindings?.engineering_baseline),registration=bound(root,bindings?.repository_registration),manifest=bound(root,bindings?.manifest);
@@ -132,7 +133,7 @@ export function verifyExistingArchitecture(identity,bindings,{root,registry,exec
  }
  if(changes.length){
   requireThat(execution,'ARCH_SOURCE_STALE',`固定源码改变: ${changes.join(', ')}`);
-  const permission=assertApprovedExecutionContext(execution,{root,architectureIdentity:identity,architectureEvidence:bindings});
+  const permission=assertApprovedExecutionContext(execution,{root,architectureIdentity:identity,architectureEvidence:bindings,readOnly});
   const allowed=permission.allowed_write_paths.map(x=>{if(path.isAbsolute(x)){const rel=path.relative(projectRoot,x).split(path.sep).join('/');return rel==='.'||rel===''?'.':relative(rel);}return x==='.'?'.':relative(x);});
   requireThat(changes.every(ref=>allowed.some(scope=>beneath(ref,scope))&&registration.allowed_write_paths.some(scope=>beneath(ref,scope))),'ARCH_SOURCE_OUT_OF_SCOPE','输出增量超出批准写范围');
  }

package/template/scripts/lib/existing-ui-baseline.mjs

@@ -1,8 +1,10 @@
-import { readFileSync, statSync } from 'node:fs';
+import { statSync } from 'node:fs';
+import { readFileSync, withValidationPhase, inValidationPhase } from './validation-phase.mjs';
 import { ensure, hash, digest, read, safe, files, schema, treeDigest } from './strategic-handoff-io.mjs';
 
 // This is an observation bundle, not a prototype or an approval generator.
-export function validateExistingUiBaseline(data, { bundleRoot } = {}) {
+export function validateExistingUiBaseline(data,options={}) {return inValidationPhase()?validate(data,options):withValidationPhase({root:options.bundleRoot,purpose:'existing-ui-baseline',readOnly:true},()=>validate(data,options));}
+function validate(data, { bundleRoot } = {}) {
   const errors=[];
   try {
     schema(data,'docs/process/schemas/existing-ui-baseline.schema.json');

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

@@ -1,6 +1,6 @@
 import { normalizeSliceContract, sourceSliceContract, parseSliceYaml } from './slice-contract.mjs';
 import { loadDeliveryProfile } from './harness-execution-scope.mjs';
-import { existsSync } from 'node:fs';
+import { existsSync } from './validation-phase.mjs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { ROOT, read, safe, ensure, digest } from './strategic-handoff-io.mjs';

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

@@ -1,5 +1,5 @@
 import { uiBaselineRef, uiBaselineCaseIds, uiBaselineKind, hasConsumerRoutes } from './ui-baseline.mjs';
-import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync } from './validation-phase.mjs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { openBackendDelivery } from './backend-delivery.mjs';

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

@@ -1,4 +1,5 @@
-import { existsSync } from 'node:fs';
+import { loadExecutionScope, assertScopeWorkUnit } from './lifecycle-execution-scope.mjs';
+import { existsSync } from './validation-phase.mjs';
 import path from 'node:path';
 import { ROOT, read, safe, ensure } from './strategic-handoff-io.mjs';
 
@@ -30,6 +31,12 @@ function activeProfile(root) {
 }
 
 export function enforceHarnessTaskScope(task,{root=ROOT}={}) {
+  const scope=loadExecutionScope(root);
+  if(scope) {
+    assertScopeWorkUnit(task.contract?.kind==='slice-implementation'?'work-unit.slice-implementation':task.work_unit_id,{root});
+    ensure(task.role_id!=='role.frontend-engineer','后端职责不允许派发前端实现');
+    ensure(task.allowed_write_paths.every(ref=>!/^apps\/frontend(?:\/|$)/.test(ref)),'禁止写入前端工程');
+  }
   const profile=activeProfile(root);
   if (!profile) return;
   ensure(task.contract?.kind!=='template-maintenance','专职产品项目不得派发模板维护任务');
@@ -41,6 +48,13 @@ export function enforceHarnessTaskScope(task,{root=ROOT}={}) {
 }
 
 export function enforceHarnessSkillScope(skills,registry,{root=ROOT}={}) {
+  if(loadExecutionScope(root)) {
+    assertScopeWorkUnit('work-unit.slice-implementation',{root});
+    for(const id of skills) {
+      const impacts=registry.skills.find(skill=>skill.id===id)?.impacts||[];
+      ensure(!impacts.includes('frontend')||impacts.includes('backend')||impacts.includes('lifecycle'),`后端职责禁止编译生产前端技能: ${id}`);
+    }
+  }
   const profile=activeProfile(root);
   if (!profile) return;
   const side=profile.profile_id==='harness.frontend-delivery'?'frontend':'backend';

package/template/scripts/lib/implementation-contract-compiler.mjs

@@ -5,7 +5,7 @@ import { createApprovedExecutionContext, createApprovedRecompilationContext, ass
 import { enforceTechnicalDesign } from './technical-design-boundary.mjs';
 import { enforceHarnessSkillScope } from "./harness-execution-scope.mjs";
 import { createHash } from "node:crypto";
-import { readFileSync } from "node:fs";
+import { readFileSync } from './validation-phase.mjs';
 import path from "node:path";
 import { parseDocument } from "../vendor/yaml.mjs";
 import { DEFAULT_REGISTRY, loadSkillRegistry, resolveSkillForNewUse } from "./skill-registry.mjs";
@@ -276,8 +276,8 @@ export function evaluateContractFreshness(contract, { registry, compilerContract
   const reasons = [];
   let trustedExecution;
   try {
-    trustedExecution=approved_slice?createApprovedExecutionContext(approved_slice,{root,contract:all,work_unit_id}):execution;
-    if(trustedExecution)assertApprovedExecutionContext(trustedExecution,{root,contract});
+    trustedExecution=approved_slice?createApprovedExecutionContext(approved_slice,{root,contract:all,work_unit_id,readOnly}):execution;
+    if(trustedExecution)assertApprovedExecutionContext(trustedExecution,{root,contract,readOnly});
   } catch(error) { reasons.push(error.code||'EXECUTION_APPROVAL_INVALID');trustedExecution=undefined; }
   try { enforceTechnicalDesign({ ...resolution, slice_id: contract.slice_id ?? resolution.slice_id }, { root,execution:trustedExecution,readOnly }); }
   catch { reasons.push("technical-design-stale-or-unavailable"); }
@@ -289,7 +289,7 @@ export function evaluateContractFreshness(contract, { registry, compilerContract
     try { validateArchitectureIdentity(resolution.architecture_identity, registry); }
     catch { reasons.push("architecture-identity-invalid"); }
     if (resolution.architecture_identity.schema_version === 2) {
-      try { verifyArchitectureEvidence(resolution.architecture_identity, resolution.architecture_evidence, { root, registry, execution:trustedExecution }); }
+      try { verifyArchitectureEvidence(resolution.architecture_identity, resolution.architecture_evidence, { root, registry, execution:trustedExecution, readOnly }); }
       catch (error) { reasons.push(error.code ?? "architecture-evidence-stale-or-unavailable"); }
     }
     if (resolution.architecture_identity_digest !== architectureDigest(resolution.architecture_identity)) reasons.push("architecture-identity-digest-changed");

package/template/scripts/lib/json-schema.mjs

@@ -1,7 +1,8 @@
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync, validationCache } from './validation-phase.mjs';
 import { spawnSync } from "node:child_process";
 import path from "node:path";
 
+const schemaCache=Symbol('schema-results');
 const validator = String.raw`
 import json
 import sys
@@ -21,8 +22,7 @@ for item in jobs:
     try:
         key = (item['schemaPath'], item['formatChecker'])
         if key not in validators:
-            with open(item['schemaPath'], encoding='utf-8') as source:
-                schema = json.load(source)
+            schema = json.loads(item['schemaText'])
             validators[key] = Draft202012Validator(schema, format_checker=FormatChecker() if key[1] else None)
         errors = list(validators[key].iter_errors(item['value']))
         if item['errorStyle'] == 'verbose':
@@ -45,10 +45,11 @@ export function validateJsonSchemas(items, { cwd = process.cwd(), timeoutMs = 30
     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 };
+    return { value, schemaPath: effectiveSchema, schemaText: readFileSync(effectiveSchema, 'utf8'), formatChecker, errorStyle };
   });
   // readall waits for EOF even after the complete JSON has arrived. A known UTF-8
   // byte frame lets the validator finish when a transport keeps its write end open.
+  const run = jobs => {
   const input = Buffer.from(JSON.stringify(jobs), "utf8");
   const result = spawnSync("python3", ["-c", validator, String(input.length)], { cwd, encoding: "utf8", input, timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024 });
   if (result.error?.code === "ETIMEDOUT") throw new TypeError(`JSON_SCHEMA_TIMEOUT: schema validation exceeded ${timeoutMs}ms`);
@@ -58,6 +59,20 @@ export function validateJsonSchemas(items, { cwd = process.cwd(), timeoutMs = 30
   if (!Array.isArray(results) || results.some(item => !item || typeof item.valid !== "boolean" || typeof item.error !== "string")) throw new TypeError("JSON_SCHEMA_PROTOCOL: validator returned invalid result records");
   if (results.length !== jobs.length) throw new TypeError("schema batch 返回数量不匹配");
   return results;
+  };
+  // Batch identical jobs once and reuse only deterministic checks within this operation.
+  // External references retain the uncached path: their dependency closure is not local here.
+  const keys=jobs.map(job=>JSON.stringify([job.schemaPath,job.schemaText,job.value,job.formatChecker,job.errorStyle,path.resolve(cwd),timeoutMs]));
+  const pending=new Map(),cached=new Map();
+  for(let i=0;i<jobs.length;i++){
+    if(/"\$(?:ref|dynamicRef)"\s*:\s*"(?!#)/.test(jobs[i].schemaText)){pending.set(`${i}:${keys[i]}`,{job:jobs[i],indices:[i],cache:false});continue;}
+    const existing=validationCache(schemaCache,keys[i]);
+    if(existing!==undefined)cached.set(i,existing);
+    else {const item=pending.get(keys[i])||{job:jobs[i],indices:[],key:keys[i],cache:true};item.indices.push(i);pending.set(keys[i],item);}
+  }
+  const entries=[...pending.values()],computed=entries.length?run(entries.map(x=>x.job)):[];
+  entries.forEach((entry,index)=>{const result=computed[index];if(entry.cache&&!result.error.includes('Traceback (most recent call last)'))validationCache(schemaCache,entry.key,result);for(const i of entry.indices)cached.set(i,result);});
+  return jobs.map((_,i)=>structuredClone(cached.get(i)));
 }
 
 export function validateJsonSchema(value, schemaPath, options = {}) {

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

@@ -1,3 +1,4 @@
+import { loadExecutionScope, assertScopeWorkUnit, scopedNextRoutes } from './lifecycle-execution-scope.mjs';
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import path from "node:path";
@@ -67,6 +68,8 @@ export function queryLifecycleContext({ mode, stageId, workUnitId, include = []
     throw new TypeError("至少提供 --mode、--stage、--work-unit 或 --include 之一");
   }
 
+  const scope = loadExecutionScope();
+  if (workUnitId) assertScopeWorkUnit(workUnitId, { readOnly: true });
   const lifecycle = validateRegistry(loadRegistry());
   const orchestration = loadYaml(ORCHESTRATION_CONTRACT_REF, "生命周期编排合同");
   const skillRegistry = loadSkillRegistry();
@@ -91,7 +94,7 @@ export function queryLifecycleContext({ mode, stageId, workUnitId, include = []
   const evidenceIds = new Set([...gates, ...checks].flatMap((gate) => gate.evidence ?? []));
   const selected = Object.fromEntries(normalizedIncludes.map((key) => [key, orchestration[key]]));
   const transition = workUnitId ? {
-    next: orchestration.transition_graph?.routes?.[workUnitId] ?? [],
+    next: scopedNextRoutes(workUnitId, orchestration.transition_graph?.routes?.[workUnitId] ?? []),
     forbidden_shortcuts: (orchestration.transition_graph?.forbidden_shortcuts ?? [])
       .filter((edge) => edge.from === workUnitId || edge.to === workUnitId),
   } : null;
@@ -129,6 +132,7 @@ export function queryLifecycleContext({ mode, stageId, workUnitId, include = []
       work_unit: workUnit,
     },
     execution: {
+      ...(scope ? { responsibility_scope: scope } : {}),
       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: [] })) } : {}),

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

@@ -1,4 +1,4 @@
-import { readFileSync } from 'node:fs';
+import { readFileSync } from './validation-phase.mjs';
 import { createHash } from 'node:crypto';
 import path from 'node:path';
 import { parseDocument } from '../vendor/yaml.mjs';

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

@@ -0,0 +1,92 @@
+import { existsSync, readFileSync } from './validation-phase.mjs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { safe } from './strategic-handoff-io.mjs';
+import { ROOT } from './lifecycle-registry.mjs';
+import { parseDocument } from '../vendor/yaml.mjs';
+
+export const SCOPE_REF = '.yss-execution-scope.yaml';
+export const TERMINAL_REF = '.yss-backend-delivery.json';
+const read = (root, ref) => {
+  const file = safe(root, ref);
+  const doc = parseDocument(readFileSync(file, 'utf8'), { uniqueKeys: true });
+  if (doc.errors.length) throw new TypeError(doc.errors[0].message);
+  return doc.toJS({ maxAliasCount: 0 });
+};
+const check = (ok, message) => { if (!ok) throw new TypeError(`execution-scope-blocked: ${message}`); };
+
+/** The project opt-in selects a policy; callers cannot supply a replacement policy. */
+export function loadExecutionScope(root = ROOT) {
+  const marker = path.join(root, '.yss-plugin.json');
+  const plugin = existsSync(marker) ? read(root, '.yss-plugin.json') : null;
+  const file = path.join(root, SCOPE_REF);
+  if (!existsSync(file)) {
+    check(!['yss-plan-to-backend', 'yss-backend-delivery'].includes(plugin?.plugin), '插件项目缺少职责范围；迁移后才能继续');
+    return null;
+  }
+  const config = read(root, SCOPE_REF), identity = read(root, 'yss-project.yaml');
+  check(identity.schema_version === 1 && identity.repository_mode === 'project-instance', '职责范围仅适用于项目实例');
+  check(config.schema_version === 1 && config.scope_id === 'plan-to-backend'
+    && Object.keys(config).every(key => ['schema_version', 'scope_id'].includes(key)), '未知或被扩大的职责配置');
+  if (plugin) check(['yss-plan-to-backend', 'yss-backend-delivery'].includes(plugin.plugin) && plugin.execution_scope === config.scope_id, '插件与项目职责绑定不一致');
+  const contract = read(root, '.agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml');
+  const policy = contract.execution_scopes?.[config.scope_id];
+  check(policy?.terminal_work_unit === 'work-unit.backend-delivery' && Array.isArray(policy.allowed_work_units), '匹配版本的主控合同缺少职责策略');
+  return { ...policy, scope_id: config.scope_id };
+}
+
+export function verifyDeliveryTerminal(root = ROOT) {
+  check(existsSync(path.join(root, TERMINAL_REF)), '缺少正式后端交付终点记录');
+  const result = spawnSync(process.execPath, [path.join(root, 'scripts/complete-backend-delivery'), 'verify', '--root', root], {
+    cwd: root, encoding: 'utf8', input: '', timeout: 120000, maxBuffer: 8 * 1024 * 1024,
+    env: { ...process.env, NODE_OPTIONS: '', NODE_PATH: '' },
+  });
+  check(!result.error && result.status === 0, result.error?.message || result.stderr || '后端交付终点复验失败');
+  return JSON.parse(result.stdout);
+}
+
+export function assertScopeWorkUnit(workUnit, { root = ROOT, readOnly = false } = {}) {
+  const scope = loadExecutionScope(root);
+  if (!scope) { check(workUnit !== 'work-unit.backend-delivery', '后端终点需要显式职责范围'); return null; }
+  check(scope.allowed_work_units.includes(workUnit), `职责范围不允许 ${workUnit}`);
+  if (existsSync(path.join(root, TERMINAL_REF))) {
+    verifyDeliveryTerminal(root);
+    check(readOnly, '后端交付已完成；不能恢复实现或自动发布');
+  }
+  return scope;
+}
+
+export function scopedNextRoutes(workUnit, routes, { root = ROOT } = {}) {
+  const scope = loadExecutionScope(root);
+  if (!scope) return routes.filter(id => id !== 'work-unit.backend-delivery');
+  assertScopeWorkUnit(workUnit, { root, readOnly: true });
+  if (existsSync(path.join(root, TERMINAL_REF))) return [];
+  return (scope.route_overrides[workUnit] || routes).filter(id => scope.allowed_work_units.includes(id));
+}
+
+export function assertScopeTransition(current, next, state, { root = ROOT } = {}) {
+  const scope = loadExecutionScope(root);
+  if (!scope) { check(current !== 'work-unit.backend-delivery' && next !== 'work-unit.backend-delivery', '后端终点需要显式职责范围'); return; }
+  if (current === scope.terminal_work_unit && next === null) { verifyDeliveryTerminal(root); return; }
+  assertScopeWorkUnit(current, { root });
+  if (next) assertScopeWorkUnit(next, { root });
+  check(next !== null, '不能把中间阶段声明为后端交付完成');
+  assertScopeImpacts(state, { root });
+}
+
+export function assertScopeImpacts(state, { root = ROOT } = {}) {
+  if (!loadExecutionScope(root)) return;
+  check(state?.delivery_impacts?.frontend !== true, '产品 UI 设计保留，生产前端实现必须交给下游');
+  if (state?.ui_impact === true) {
+    const deferred = state.downstream_frontend;
+    check(deferred && ['owner', 'ticket_ref', 'verification_plan', 'target_version'].every(key => typeof deferred[key] === 'string' && deferred[key].trim()), 'UI 产品须明确下游前端责任、Ticket、验证计划和目标版本');
+  }
+}
+
+export function assertScopeSlice(contract, { root = ROOT } = {}) {
+  if (!loadExecutionScope(root)) return;
+  check(contract.backend?.status === 'required' && contract.frontend?.status === 'not-applicable', '本职责仅允许后端 Slice；产品 UI 设计不能混作前端实现批准');
+  check(!(contract.common?.impacted_areas || []).some(x => ['ui', 'frontend'].includes(x)), 'Slice 仍包含生产前端实现影响');
+  const roles = (contract.work_units || []).map(unit => unit.role_id);
+  check(!roles.includes('role.frontend-engineer'), '禁止派发前端实现');
+}

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

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
-import { readFileSync, writeFileSync } from "node:fs";
+import { writeFileSync } from 'node:fs';
+import { readFileSync } from './validation-phase.mjs';
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseDocument } from "../vendor/yaml.mjs";

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

@@ -1,3 +1,5 @@
+import { assertTrackingTransition } from './stage-tracking.mjs';
+import { assertScopeTransition, assertScopeImpacts, assertScopeWorkUnit, scopedNextRoutes } from './lifecycle-execution-scope.mjs';
 // Wire capability marker: profile-local readiness rules are not interchangeable.
 export const SLICE_REPOSITORY_PREPARATION_PROTOCOL = 1;
 import { createHash } from "node:crypto";
@@ -43,7 +45,8 @@ const NEXT_ROUTES = deepFreeze({
   [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"],
-  "work-unit.code-review": ["work-unit.release-and-retrospective", IMPLEMENTATION_WORK_UNIT],
+  "work-unit.code-review": ["work-unit.release-and-retrospective", IMPLEMENTATION_WORK_UNIT, "work-unit.backend-delivery"],
+  "work-unit.backend-delivery": [],
   "work-unit.release-and-retrospective": [],
 });
 
@@ -249,7 +252,11 @@ function validateTicketReference(ref, trackerKind) {
  * by `validateWorkflowExecutionResult` before this function is called.
  */
 export function validateNextRoute(currentWorkUnit, nextRoute, decisionState, options = {}) {
-  if (currentWorkUnit === "work-unit.code-review" && nextRoute === "work-unit.release-and-retrospective") {
+  try { assertTrackingTransition(currentWorkUnit, nextRoute, decisionState, { root: options.root || ROOT }); }
+  catch (error) { return blockedResult(['stage-tracking-blocked'], [error.message]); }
+  try { assertScopeTransition(currentWorkUnit, nextRoute, decisionState, options); }
+  catch (error) { return blockedResult(['execution-scope-blocked'], [error.message]); }
+  if (currentWorkUnit === "work-unit.code-review" && ["work-unit.release-and-retrospective", "work-unit.backend-delivery"].includes(nextRoute)) {
     try {
       if (decisionState?.review_input?.scope_kind !== "change") throw new Error("只读基线审计不能关闭实现审查");
       validateBackendReview(decisionState, { root: options.root || ROOT });
@@ -262,7 +269,7 @@ export function validateNextRoute(currentWorkUnit, nextRoute, decisionState, opt
     try { enforceFrontendDelivery(decisionState, { root: options.root, phase: nextRoute === IMPLEMENTATION_WORK_UNIT ? "implementation" : "inputs" }); }
     catch (error) { return blockedResult(["frontend-delivery-blocked"], [error.message]); }
   }
-  const routes = NEXT_ROUTES[currentWorkUnit];
+  const routes = NEXT_ROUTES[currentWorkUnit] && scopedNextRoutes(currentWorkUnit, NEXT_ROUTES[currentWorkUnit], options);
   if (!routes) return blockedResult([BLOCKING_SIGNALS.invalidRoute], ["known_current_work_unit"]);
   if (nextRoute === REPOSITORY_PREPARATION_WORK_UNIT && currentWorkUnit !== "work-unit.technical-analysis") {
     return blockedResult([BLOCKING_SIGNALS.technicalAnalysisRequired], ["work-unit.technical-analysis predecessor"]);
@@ -299,6 +306,8 @@ export function validateNextRoute(currentWorkUnit, nextRoute, decisionState, opt
  * generated and verified scaffold. Unaffected roles need an explicit reason.
  */
 export function validateImplementationRepositoriesReady(state, { exists = existsSync, read = (ref) => readFileSync(ref, "utf8"), root = ROOT } = {}) {
+  try { assertScopeImpacts(state, { root }); }
+  catch (error) { return blockedResult(['execution-scope-blocked'], [error.message]); }
   const preparation = state?.implementation_repository_preparation;
   const impacts = state?.delivery_impacts;
   const signals = [];
@@ -411,6 +420,13 @@ function validateDecisionBoundary(workUnit, state, options) {
  * `exists` is injectable so external adapters can resolve their own tracker refs.
  */
 export function validateTicketFormalization(state, { exists = existsSync, read = (ref) => readFileSync(ref, "utf8"), ...decisionOptions } = {}) {
+  if ((state?.tracker_kind ?? "local-markdown") === "local-markdown" && state?.vertical_slice_ticket?.ref && isReadable(state.vertical_slice_ticket.ref, exists)) {
+    try {
+      const header = read(state.vertical_slice_ticket.ref).match(/^---\r?\n([\s\S]*?)\r?\n---/);
+      const kind = header ? parseDocument(header[1], { uniqueKeys: true }).toJS({ maxAliasCount: 0 })?.kind : null;
+      if (kind === "stage-work-item") return blockedResult(["stage-work-item-not-implementable"], ["vertical-slice-ticket required"]);
+    } catch { return blockedResult(["ticket-content-unreadable"], ["readable vertical slice content"]); }
+  }
   try { enforceFrontendDelivery(state, { root: decisionOptions.root, phase: "implementation" }); }
   catch (error) { return blockedResult(["frontend-delivery-blocked"], [error.message]); }
   const repositoryResult = validateImplementationRepositoriesReady(state, { exists, read, ...decisionOptions });
@@ -532,6 +548,8 @@ export function validateTicketFormalization(state, { exists = existsSync, read =
  * Validate the complete implementation entry seam after ready-for-agent promotion.
  */
 export function validateImplementationEntry(state, options = {}) {
+  try { assertScopeWorkUnit(IMPLEMENTATION_WORK_UNIT, options); assertScopeImpacts(state, options); }
+  catch (error) { return blockedResult(['execution-scope-blocked'], [error.message]); }
   const ticketResult = validateTicketFormalization(state, options);
   if (ticketResult.result === "blocked") return ticketResult;
   if (state?.predecessor_work_unit !== TICKET_DECOMPOSITION_WORK_UNIT) {

package/template/scripts/lib/openapi-draft-validation.mjs

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
-import { existsSync, lstatSync, readFileSync, realpathSync } from "node:fs";
+import { realpathSync } from "node:fs";
+import { existsSync, lstatSync, readFileSync } from "./validation-phase.mjs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseAllDocuments, parseDocument } from "../vendor/yaml.mjs";