create-yss-spec 3.0.1 → 3.1.3

package/template/.agents/skills/yss-mvc-scaffold-generator/scripts/generate_project.test.mjs

@@ -1,337 +1,9 @@
 import test from "node:test";
 import assert from "node:assert/strict";
-import { mkdtemp, readFile, readdir, rm, stat, writeFile, mkdir } from "node:fs/promises";
 import { spawnSync } from "node:child_process";
-import os from "node:os";
-import path from "node:path";
 import { fileURLToPath } from "node:url";
-
-const script = path.join(path.dirname(fileURLToPath(import.meta.url)), "generate_project.mjs");
-const verifyScript = path.join(path.dirname(fileURLToPath(import.meta.url)), "verify_project.mjs");
-const harnessRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../..");
-const gitAuthorEnvironment = {
-  GIT_CONFIG_COUNT: "1",
-  GIT_CONFIG_KEY_0: "user.name",
-  GIT_CONFIG_VALUE_0: "Scaffold Tester"
-};
-function run(args, options = {}) {
-  return spawnSync(process.execPath, [script, ...args], {
-    encoding: "utf8",
-    ...options,
-    env: { ...process.env, ...gitAuthorEnvironment, ...(options.env ?? {}) }
-  });
-}
-async function expectedDistributedLock() {
-  const lock = JSON.parse(await readFile(path.join(harnessRoot, "skills-lock.json"), "utf8"));
-  delete lock.skills?.shared?.["yss-mvc-scaffold-generator"];
-  for (const platform of Object.values(lock.skills?.platform ?? {})) delete platform?.["yss-mvc-scaffold-generator"];
-  return `${JSON.stringify(lock, null, 2)}\n`;
-}
-test("生成固定六模块和 mock endpoint", async (t) => {
-  const base = await mkdtemp(path.join(os.tmpdir(), "data-analysis-scaffold-")); t.after(() => rm(base, { recursive: true, force: true }));
-  const target = path.join(base, "item1"); const result = run(["--project-name", "data-analysis-item1", "--base-package", "com.yss.dataanalysis.item1", "--target-dir", target, "--database", "oracle", "--with-mock"]);
-  assert.equal(result.status, 0, result.stderr); const backend = target; const pom = await readFile(path.join(backend, "pom.xml"), "utf8");
-  const skillUtils = path.join(base, "skillUtils");
-  for (const module of ["server", "core", "client", "repository", "adapter", "feign-client"]) assert.match(pom, new RegExp(`<module>${module}</module>`));
-  const controller = await readFile(path.join(backend, "server/src/main/java/com/yss/dataanalysis/item1/server/controller/AnalysisController.java"), "utf8"); assert.match(controller, /\/api\/analysis/); assert.doesNotMatch(controller, /;[ \t]+import /);
-  assert.match(controller, /\* \u6570\u636e\u5206\u6790\u67e5\u8be2\u63a5\u53e3\u3002/);
-  assert.match(controller, /@author Scaffold Tester/);
-  assert.match(controller, /@date \d{4}\/\d{2}\/\d{2} \d{2}:\d{2}/);
-  assert.match(controller, /\* \u5206\u9875\u67e5\u8be2\u6570\u636e\u5206\u6790\u7ed3\u679c\u3002[\s\S]*@param query[\s\S]*@return \u6570\u636e\u5206\u6790\u5206\u9875\u7ed3\u679c/);
-  const mock = await readFile(path.join(backend, "adapter/src/main/java/com/yss/dataanalysis/item1/adapter/mock/MockAnalysisQueryExecutor.java"), "utf8"); assert.match(mock, /source|"mock"/);
-  const configuration = await readFile(path.join(backend, "server/src/main/java/com/yss/dataanalysis/item1/server/configuration/AnalysisConfiguration.java"), "utf8"); assert.match(configuration, /Profile\("mock"\)/); assert.match(configuration, /Profile\("oracle & !mock"\)/);
-  await readFile(path.join(backend, "server/src/main/java/com/yss/dataanalysis/item1/Application.java"), "utf8");
-  const controllerTest = await readFile(path.join(backend, "server/src/test/java/com/yss/dataanalysis/item1/server/controller/AnalysisControllerTest.java"), "utf8");
-  assert.match(controllerTest, /pageNo/);
-  assert.match(await readFile(path.join(target, "yss-project.yaml"), "utf8"), /repository_mode: project-instance/);
-  assert.match(await readFile(path.join(target, "CONTEXT.md"), "utf8"), /AnalysisDataset/);
-  assert.match(await readFile(path.join(target, ".artifact-workspace.yaml"), "utf8"), /kind: service/);
-  assert.match(await readFile(path.join(target, "docs/service/module-map.md"), "utf8"), /feign-client/);
-  assert.match(await readFile(path.join(target, "docs/service/current-capabilities.md"), "utf8"), /普通功能开发不手工修改/);
-  assert.match(await readFile(path.join(target, "docs/process/implementation-repo-registry.yaml"), "utf8"), /repository_scope: external-repository/);
-  const analysisProject = await readFile(path.join(target, "docs/process/analysis-project.yaml"), "utf8"); assert.match(analysisProject, /project_name: data-analysis-item1/); assert.doesNotMatch(analysisProject, /galaxy-data-analysis|fegin-client/);
-  assert.match(await readFile(path.join(target, "docs/process/lifecycle-registry.yaml"), "utf8"), /schema_version:/);
-  assert.match(await readFile(path.join(target, "docs/templates/vertical-slice-ticket-template.md"), "utf8"), /status: ready-for-human/);
-  assert.match(await readFile(path.join(target, "docs/templates/local-parent-ticket-template.md"), "utf8"), /lifecycle_status \| routing \/ running \/ paused-human-gate \/ blocked \/ completed/);
-  const lifecycleContract = await readFile(path.join(skillUtils, ".agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml"), "utf8");
-  assert.match(lifecycleContract, /entry_routing:/);
-  assert.match(lifecycleContract, /workflow_execution_result:/);
-  assert.match(lifecycleContract, /work_unit_routes:/);
-  assert.match(await readFile(path.join(target, "docs/templates/approval-record-template.yaml"), "utf8"), /gate_id:/);
-  assert.match(await readFile(path.join(target, "docs/templates/implementation-routing-template.md"), "utf8"), /implementation/);
-  assert.match(await readFile(path.join(target, "docs/templates/verification-record-template.md"), "utf8"), /verification/i);
-  await readFile(path.join(skillUtils, ".agents/skills/yss-product-lifecycle/SKILL.md"), "utf8");
-  for (const projection of [".agents", ".claude", ".codex", ".cursor", ".pi", ".qoder", ".trae"]) {
-    await assert.rejects(stat(path.join(skillUtils, projection, "skills/yss-mvc-scaffold-generator")), { code: "ENOENT" });
-  }
-  assert.equal(path.resolve(spawnSync("git", ["-C", target, "rev-parse", "--show-toplevel"], { encoding: "utf8" }).stdout.trim()), path.resolve(target));
-  assert.equal(spawnSync("git", ["-C", target, "branch", "--show-current"], { encoding: "utf8" }).stdout.trim(), "main");
-  assert.equal(spawnSync("git", ["-C", target, "rev-list", "--all", "--count"], { encoding: "utf8" }).stdout.trim(), "0");
-  assert.equal(spawnSync("git", ["-C", target, "remote"], { encoding: "utf8" }).stdout.trim(), "");
-  const verification = spawnSync(process.execPath, [verifyScript, "--project-root", target], { encoding: "utf8" });
-  assert.equal(verification.status, 0, verification.stderr);
-  await assert.rejects(stat(path.join(skillUtils, ".agents/skills/data-analysis-java-implementation")), { code: "ENOENT" });
-  const implementationRegistry = await readFile(path.join(target, "docs/process/implementation-repo-registry.yaml"), "utf8");
-  assert.doesNotMatch(implementationRegistry, /data-analysis-java-implementation|verify_java_web_style\.mjs/);
-  assert.match(implementationRegistry, /fmt-maven-plugin:2\.9\.1:check/);
-  assert.doesNotMatch(implementationRegistry, /smart-doc-maven-plugin:[^\s]+:openapi/);
-  assert.doesNotMatch(implementationRegistry, /smart-doc-verification\.md/);
-  const projectInstanceDocs = await Promise.all([
-    "AGENTS.md",
-    "docs/agents/skills-maintenance.md",
-    "docs/agents/gitlab-workflow-skills.md",
-    "docs/agents/issue-tracker.md",
-    "docs/process/implementation-repo-integration.md",
-    "docs/process/harness-process-tailoring.md",
-    "docs/templates/build-architecture-checklist-template.md"
-  ].map((relative) => readFile(path.join(target, relative), "utf8")));
-  const staleProjectCommands = /scripts\/(?:verify-template|sync-skills|update-skill-lock|export-yss-skills|verify-upstream-skill-source|verify-maintenance-checkpoint|verify-implementation-path-scenarios|gitworks)/;
-  for (const body of projectInstanceDocs) assert.doesNotMatch(body, staleProjectCommands);
-  const serverPom = await readFile(path.join(backend, "server/pom.xml"), "utf8");
-  assert.match(serverPom, /<profiles>[\s\S]*<id>nacos<\/id>[\s\S]*<activeByDefault>true<\/activeByDefault>/);
-  assert.match(serverPom, /<app\.env>dev<\/app\.env>[\s\S]*<app\.profiles>nacos<\/app\.profiles>/);
-  assert.match(serverPom, /spring-boot-maven-plugin/);
-  assert.match(serverPom, /<includes>[\s\S]*data-analysis-item1-client[\s\S]*data-analysis-item1-core[\s\S]*data-analysis-item1-repository[\s\S]*<\/includes>/);
-  const smartDocPlugin = serverPom.match(/<plugin>(?:(?!<\/plugin>)[\s\S])*?<artifactId>smart-doc-maven-plugin<\/artifactId>(?:(?!<\/plugin>)[\s\S])*?<\/plugin>/)?.[0];
-  assert.ok(smartDocPlugin);
-  assert.doesNotMatch(smartDocPlugin, /<executions>/);
-  const smartDoc = await readFile(path.join(backend, "server/src/main/resources/smart-doc.json"), "utf8");
-  assert.match(smartDoc, /"projectName": "data-analysis-item1"/);
-  assert.match(smartDoc, /"packageFilters": "com\.yss\.dataanalysis\.item1\.server\.controller\.\*"/);
-  assert.match(smartDoc, /"showAuthor": true/);
-  assert.match(smartDoc, /"appToken": ""/);
-  assert.doesNotMatch(smartDoc, /43fd1d4bc1c743c1b83bf4843e8167bf|192\.168\./);
-  const logback = await readFile(path.join(backend, "server/src/main/resources/logback-spring.xml"), "utf8");
-  assert.match(logback, /springProfile name="dev,mock"/);
-  assert.match(logback, /springProfile name="uat,pro,oracle,oceanbase-oracle"/);
-  assert.match(logback, /com\.yss\.dataanalysis\.item1/);
-  const bootstrap = await readFile(path.join(backend, "server/src/main/resources/bootstrap.yml"), "utf8");
-  assert.match(bootstrap, /active: \$\{app\.env:dev\},datasource,nacos,oracle,mock/);
-  assert.doesNotMatch(bootstrap, /mock,\s*$/m);
-  const bootstrapNacos = await readFile(path.join(backend, "server/src/main/resources/bootstrap-nacos.yml"), "utf8");
-  assert.match(bootstrapNacos, /server-addr: \$\{nacosserver:192\.168\.165\.58:8848\}/);
-  assert.match(bootstrapNacos, /group: \$\{nacos_group:yss-dm\}/);
-  assert.match(bootstrapNacos, /discovery:[\s\S]*enabled: true[\s\S]*config:[\s\S]*enabled: true/);
-  const bootstrapMock = await readFile(path.join(backend, "server/src/main/resources/bootstrap-mock.yml"), "utf8");
-  assert.match(bootstrapMock, /discovery:[\s\S]*enabled: false/);
-  assert.match(bootstrapMock, /config:[\s\S]*enabled: false[\s\S]*import-check:[\s\S]*enabled: false/);
-  const applicationMock = await readFile(path.join(backend, "server/src/main/resources/application-mock.yml"), "utf8");
-  assert.match(applicationMock, /leaf:[\s\S]*leafSegmentEnable: false[\s\S]*leafSnowflakeEnable: false/);
-  assert.match(applicationMock, /com\.yss\.cloud\.mybatis\.MybatisPlusConfiguration/);
-  assert.match(applicationMock, /com\.yss\.cloud\.sankuai\.config\.LeafDataSourceConfiguration/);
-  const application = await readFile(path.join(backend, "server/src/main/java/com/yss/dataanalysis/item1/Application.java"), "utf8");
-  assert.doesNotMatch(application, /@EnableDistributedId/);
-  const databaseInfrastructure = await readFile(path.join(backend, "server/src/main/java/com/yss/dataanalysis/item1/server/configuration/DatabaseInfrastructureConfiguration.java"), "utf8");
-  assert.match(databaseInfrastructure, /@Profile\("!mock"\)/);
-  assert.match(databaseInfrastructure, /@EnableDistributedId/);
-  assert.match(databaseInfrastructure, /@Import\(MapperConfiguration.class\)/);
-});
-
-test("已有 skillUtils 落后时原子刷新并保留备份", async (t) => {
-  const base = await mkdtemp(path.join(os.tmpdir(), "data-analysis-skill-refresh-"));
-  t.after(() => rm(base, { recursive: true, force: true }));
-  const skillUtils = path.join(base, "skillUtils");
-  await mkdir(skillUtils, { recursive: true });
-  await writeFile(path.join(skillUtils, "skill-utils.yaml"), "schema_version: 1\nkind: yss-skill-utils\n", "utf8");
-  await writeFile(path.join(skillUtils, "skills-lock.json"), "{\"version\":0}\n", "utf8");
-  await writeFile(path.join(skillUtils, "local-marker.txt"), "preserve old installation\n", "utf8");
-  const target = path.join(base, "item-refresh");
-  const result = run(["--project-name", "data-analysis-refresh", "--base-package", "com.yss.dataanalysis.refresh", "--target-dir", target]);
-  assert.equal(result.status, 0, result.stderr);
-  const output = JSON.parse(result.stdout);
-  assert.equal(output.skill_utils_created, false);
-  assert.equal(output.skill_utils_refreshed, true);
-  assert.ok(output.skill_utils_backup);
-  assert.equal(await readFile(path.join(output.skill_utils_backup, "local-marker.txt"), "utf8"), "preserve old installation\n");
-  assert.equal(await readFile(path.join(skillUtils, "skills-lock.json"), "utf8"), await expectedDistributedLock());
-});
-
-test("已有 skillUtils 与源锁一致时直接复用", async (t) => {
-  const base = await mkdtemp(path.join(os.tmpdir(), "data-analysis-skill-reuse-"));
-  t.after(() => rm(base, { recursive: true, force: true }));
-  const first = run(["--project-name", "data-analysis-reuse-a", "--base-package", "com.yss.dataanalysis.reusea", "--target-dir", path.join(base, "item-a")]);
-  assert.equal(first.status, 0, first.stderr);
-  const second = run(["--project-name", "data-analysis-reuse-b", "--base-package", "com.yss.dataanalysis.reuseb", "--target-dir", path.join(base, "item-b")]);
-  assert.equal(second.status, 0, second.stderr);
-  const output = JSON.parse(second.stdout);
-  assert.equal(output.skill_utils_created, false);
-  assert.equal(output.skill_utils_refreshed, false);
-  assert.equal(output.skill_utils_backup, null);
-});
-
-test("dry-run 仅报告 skillUtils 将刷新且不修改旧目录", async (t) => {
-  const base = await mkdtemp(path.join(os.tmpdir(), "data-analysis-skill-dry-refresh-"));
-  t.after(() => rm(base, { recursive: true, force: true }));
-  const skillUtils = path.join(base, "skillUtils");
-  await mkdir(skillUtils, { recursive: true });
-  await writeFile(path.join(skillUtils, "skill-utils.yaml"), "schema_version: 1\nkind: yss-skill-utils\n", "utf8");
-  await writeFile(path.join(skillUtils, "skills-lock.json"), "{\"version\":0}\n", "utf8");
-  const result = run(["--project-name", "data-analysis-dry-refresh", "--base-package", "com.yss.dataanalysis.dryrefresh", "--target-dir", path.join(base, "item"), "--dry-run"]);
-  assert.equal(result.status, 0, result.stderr);
-  const output = JSON.parse(result.stdout);
-  assert.equal(output.skill_utils_refreshed, true);
-  assert.equal(output.skill_utils_backup, null);
-  assert.equal(await readFile(path.join(skillUtils, "skills-lock.json"), "utf8"), "{\"version\":0}\n");
-  assert.deepEqual((await readdir(base)).sort(), ["skillUtils"]);
-});
-
-test("Git 当前用户写入 Javadoc 且缺失时拒绝生成", async (t) => {
-  const base = await mkdtemp(path.join(os.tmpdir(), "data-analysis-author-")); t.after(() => rm(base, { recursive: true, force: true }));
-  const target = path.join(base, "author-project");
-  const generated = run(["--project-name", "author-project", "--base-package", "com.yss.author", "--target-dir", target], {
-    env: { GIT_CONFIG_VALUE_0: "张三" }
-  });
-  assert.equal(generated.status, 0, generated.stderr);
-  const controller = await readFile(path.join(target, "server/src/main/java/com/yss/author/server/controller/AnalysisController.java"), "utf8");
-  assert.match(controller, /@author 张三/);
-  assert.doesNotMatch(controller, /@author system/);
-
-  const missingTarget = path.join(base, "missing-author");
-  const missing = run(["--project-name", "missing-author", "--base-package", "com.yss.missing", "--target-dir", missingTarget], {
-    env: { GIT_CONFIG_COUNT: "0", GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: path.join(base, "not-found.gitconfig") }
-  });
-  assert.notEqual(missing.status, 0);
-  assert.match(missing.stderr, /Git user\.name/);
-  await assert.rejects(stat(missingTarget), { code: "ENOENT" });
-});
-
-test("不启用 Mock 时不生成 bootstrap-mock 且不激活 mock profile", async (t) => {
-  const base = await mkdtemp(path.join(os.tmpdir(), "data-analysis-no-mock-profile-")); t.after(() => rm(base, { recursive: true, force: true }));
-  const target = path.join(base, "data-analysis-no-mock");
-  const result = run(["--project-name", "data-analysis-no-mock", "--base-package", "com.yss.dataanalysis.nomock", "--target-dir", target]);
-  assert.equal(result.status, 0, result.stderr);
-  const bootstrap = await readFile(path.join(target, "server/src/main/resources/bootstrap.yml"), "utf8");
-  assert.match(bootstrap, /active: \$\{app\.env:dev\},datasource,nacos,oracle/);
-  assert.doesNotMatch(bootstrap, /,mock/);
-  await assert.rejects(stat(path.join(target, "server/src/main/resources/bootstrap-mock.yml")), { code: "ENOENT" });
-});
-
-test("Maven settings \u4f5c\u4e3a外部验证输入且不写入项目", async (t) => {
-  const base = await mkdtemp(path.join(os.tmpdir(), "data-analysis-settings-")); t.after(() => rm(base, { recursive: true, force: true }));
-  const settings = path.join(base, "settings.xml");
-  await writeFile(settings, "<settings/>\n");
-  const target = path.join(base, "data-analysis-item-settings");
-  const result = run(["--project-name", "data-analysis-item-settings", "--base-package", "com.yss.dataanalysis.settings", "--target-dir", target, "--maven-settings", settings]);
-  assert.equal(result.status, 0, result.stderr);
-  const manifest = await readFile(path.join(target, ".yss/scaffold-generation.json"), "utf8");
-  assert.match(manifest, /"maven_settings_mode": "external"/);
-  assert.match(manifest, /"maven_settings_required": true/);
-  assert.doesNotMatch(manifest, new RegExp(settings.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")));
-  assert.equal((await readdir(target)).includes("settings.xml"), false);
-});
-test("Maven settings 支持环境变量且显式参数优先", async (t) => {
-  const base = await mkdtemp(path.join(os.tmpdir(), "data-analysis-settings-resolution-")); t.after(() => rm(base, { recursive: true, force: true }));
-  const environmentSettings = path.join(base, "environment-settings.xml");
-  const explicitSettings = path.join(base, "explicit-settings.xml");
-  await writeFile(environmentSettings, "<settings/>\n");
-  await writeFile(explicitSettings, "<settings/>\n");
-  const environmentTarget = path.join(base, "environment-project");
-  const fromEnvironment = run(["--project-name", "environment-project", "--base-package", "com.yss.environment", "--target-dir", environmentTarget, "--dry-run"], { env: { YSS_MAVEN_SETTINGS: environmentSettings } });
-  assert.equal(fromEnvironment.status, 0, fromEnvironment.stderr);
-  assert.match(fromEnvironment.stdout, /"maven_settings_source": "environment"/);
-  const explicitTarget = path.join(base, "explicit-project");
-  const fromExplicit = run(["--project-name", "explicit-project", "--base-package", "com.yss.explicit", "--target-dir", explicitTarget, "--maven-settings", explicitSettings, "--dry-run"], { env: { YSS_MAVEN_SETTINGS: environmentSettings } });
-  assert.equal(fromExplicit.status, 0, fromExplicit.stderr);
-  assert.match(fromExplicit.stdout, /"maven_settings_source": "explicit"/);
-});
-test("未指定 settings 时仍完整生成，并将依赖解析延后到验证阶段", async (t) => {
-  const base = await mkdtemp(path.join(os.tmpdir(), "yss-mvc-no-settings-"));
-  t.after(() => rm(base, { recursive: true, force: true }));
-  const target = path.join(base, "no-settings-project");
-  const result = run(["--project-name", "no-settings-project", "--base-package", "com.yss.nosettings", "--target-dir", target], {
-    env: { YSS_MAVEN_SETTINGS: "", USERPROFILE: path.join(base, "missing-user"), HOME: path.join(base, "missing-home") }
-  });
-  assert.equal(result.status, 0, result.stderr);
-  const output = JSON.parse(result.stdout);
-  assert.equal(output.maven_settings_source, "maven-default");
-  assert.equal(output.maven_settings_available, false);
-  assert.equal(output.dependency_resolution, "deferred");
-  assert.equal(output.network_access_during_generation, "disabled");
-  for (const module of ["server", "core", "client", "repository", "adapter", "feign-client"]) {
-    await stat(path.join(target, module, "pom.xml"));
-  }
-  await stat(path.join(target, "mvnw"));
-  assert.equal((await readdir(target)).includes("settings.xml"), false);
-});
-test("拒绝非空目标目录", async (t) => {
-  const base = await mkdtemp(path.join(os.tmpdir(), "data-analysis-scaffold-nonempty-")); t.after(() => rm(base, { recursive: true, force: true })); await mkdir(base, { recursive: true }); await writeFile(path.join(base, "keep.txt"), "keep");
-  const result = run(["--project-name", "data-analysis-item1", "--base-package", "com.yss.dataanalysis.item1", "--target-dir", base]); assert.notEqual(result.status, 0); assert.match(result.stderr, /目标目录非空/);
-});
-test("允许已存在的空目标目录", async (t) => {
-  const base = await mkdtemp(path.join(os.tmpdir(), "data-analysis-empty-target-")); t.after(() => rm(base, { recursive: true, force: true }));
-  const target = path.join(base, "data-analysis-item-empty"); await mkdir(target);
-  const result = run(["--project-name", "data-analysis-item-empty", "--base-package", "com.yss.dataanalysis.empty", "--target-dir", target]);
-  assert.equal(result.status, 0, result.stderr);
-  assert.equal(path.resolve(spawnSync("git", ["-C", target, "rev-parse", "--show-toplevel"], { encoding: "utf8" }).stdout.trim()), path.resolve(target));
-});
-test("嵌套在父仓目录时仍初始化为独立 Git 根", async (t) => {
-  const parent = await mkdtemp(path.join(os.tmpdir(), "data-analysis-parent-repo-")); t.after(() => rm(parent, { recursive: true, force: true }));
-  assert.equal(spawnSync("git", ["init", "--initial-branch=parent-main", parent], { encoding: "utf8" }).status, 0);
-  const target = path.join(parent, "data-analysis-item2");
-  const result = run(["--project-name", "data-analysis-item2", "--base-package", "com.yss.dataanalysis.item2", "--target-dir", target]);
-  assert.equal(result.status, 0, result.stderr);
-  assert.equal(path.resolve(spawnSync("git", ["-C", target, "rev-parse", "--show-toplevel"], { encoding: "utf8" }).stdout.trim()), path.resolve(target));
-  assert.equal(spawnSync("git", ["-C", target, "branch", "--show-current"], { encoding: "utf8" }).stdout.trim(), "main");
-});
-test("dry-run 不创建目录或 Git 仓库", async (t) => {
-  const base = await mkdtemp(path.join(os.tmpdir(), "data-analysis-dry-run-")); t.after(() => rm(base, { recursive: true, force: true }));
-  const target = path.join(base, "data-analysis-item3");
-  const result = run(["--project-name", "data-analysis-item3", "--base-package", "com.yss.dataanalysis.item3", "--target-dir", target, "--dry-run"]);
-  assert.equal(result.status, 0, result.stderr);
-  assert.match(result.stdout, /"mode": "dry-run"/);
-  assert.equal(spawnSync("git", ["-C", target, "rev-parse", "--show-toplevel"], { encoding: "utf8" }).status, 128);
-});
-test("Git 预检失败时不留下目标目录或 staging", async (t) => {
-  const base = await mkdtemp(path.join(os.tmpdir(), "data-analysis-no-git-")); t.after(() => rm(base, { recursive: true, force: true }));
-  const target = path.join(base, "data-analysis-item4");
-  const result = run(["--project-name", "data-analysis-item4", "--base-package", "com.yss.dataanalysis.item4", "--target-dir", target], { env: { ...process.env, PATH: "" } });
-  assert.notEqual(result.status, 0); assert.match(result.stderr, /未检测到可用的 Git/);
-  await assert.rejects(stat(target), { code: "ENOENT" });
-  assert.deepEqual((await readdir(base)).filter((name) => name.includes(".staging-")), []);
-});
-test("staging 创建后中间步骤失败时只清理本轮 staging", async (t) => {
-  const base = await mkdtemp(path.join(os.tmpdir(), "data-analysis-git-init-fail-")); t.after(() => rm(base, { recursive: true, force: true }));
-  const occupied = path.join(base, ".data-analysis-item5.staging-occupied"); await mkdir(occupied); await writeFile(path.join(occupied, "keep.txt"), "keep");
-  const target = path.join(base, "data-analysis-item5");
-  const result = run(["--project-name", "data-analysis-item5", "--base-package", "com.yss.dataanalysis.item5", "--target-dir", target], { env: { ...process.env, NODE_ENV: "test", YSS_SCAFFOLD_TEST_FAIL_AFTER_STAGING: "1" } });
-  assert.notEqual(result.status, 0); assert.match(result.stderr, /staging 后失败/);
-  await assert.rejects(stat(target), { code: "ENOENT" });
-  assert.equal(await readFile(path.join(occupied, "keep.txt"), "utf8"), "keep");
-  assert.deepEqual((await readdir(base)).filter((name) => name.startsWith(".data-analysis-item5.staging-") && name !== path.basename(occupied)), []);
-});
-test("生成期间空目标目录被写入时保留新内容并拒绝替换", async (t) => {
-  const base = await mkdtemp(path.join(os.tmpdir(), "data-analysis-target-race-")); t.after(() => rm(base, { recursive: true, force: true }));
-  const target = path.join(base, "data-analysis-item6"); await mkdir(target);
-  const result = run(["--project-name", "data-analysis-item6", "--base-package", "com.yss.dataanalysis.item6", "--target-dir", target], { env: { ...process.env, NODE_ENV: "test", YSS_SCAFFOLD_TEST_WRITE_TARGET_DURING_STAGING: "1" } });
-  assert.notEqual(result.status, 0);
-  assert.equal(await readFile(path.join(target, "keep.txt"), "utf8"), "concurrent content\n");
-  assert.deepEqual((await readdir(base)).filter((name) => name.startsWith(".data-analysis-item6.staging-")), []);
-});
-test("结构验证器拒绝与生成清单不一致的实现仓登记", async (t) => {
-  const base = await mkdtemp(path.join(os.tmpdir(), "data-analysis-registry-drift-")); t.after(() => rm(base, { recursive: true, force: true }));
-  const target = path.join(base, "data-analysis-item7");
-  const result = run(["--project-name", "data-analysis-item7", "--base-package", "com.yss.dataanalysis.item7", "--target-dir", target]);
-  assert.equal(result.status, 0, result.stderr);
-  const registryPath = path.join(target, "docs/process/implementation-repo-registry.yaml");
-  const registry = await readFile(registryPath, "utf8");
-  await writeFile(registryPath, registry.replace("repository_scope: external-repository", "repository_scope: harness-apps"));
-  const verification = spawnSync(process.execPath, [verifyScript, "--project-root", target], { encoding: "utf8" });
-  assert.notEqual(verification.status, 0);
-  assert.match(verification.stderr, /实现仓登记与生成清单不一致/);
-});
-test("OceanBase Oracle 仅生成指定驱动并保持 Java 8 基线", async (t) => {
-  const base = await mkdtemp(path.join(os.tmpdir(), "data-analysis-oceanbase-")); t.after(() => rm(base, { recursive: true, force: true }));
-  const target = path.join(base, "data-analysis-item8");
-  const result = run(["--project-name", "data-analysis-item8", "--base-package", "com.yss.dataanalysis.item8", "--target-dir", target, "--database", "oceanbase-oracle", "--with-mock"]);
-  assert.equal(result.status, 0, result.stderr);
-  const parentPom = await readFile(path.join(target, "pom.xml"), "utf8");
-  const repositoryPom = await readFile(path.join(target, "repository/pom.xml"), "utf8");
-  assert.match(parentPom, /<java.version>1.8<\/java.version>/);
-  assert.match(parentPom, /<version>2.0.0-SNAPSHOT<\/version>/);
-  assert.match(repositoryPom, /oceanbase-client/);
-  assert.doesNotMatch(repositoryPom, /ojdbc8/);
-  const querySource = await readFile(path.join(target, "client/src/main/java/com/yss/dataanalysis/item8/client/query/AnalysisQuery.java"), "utf8");
-  assert.doesNotMatch(querySource, /\brecord\b|List\.of|Map\.of|jakarta\./);
-  const verification = spawnSync(process.execPath, [verifyScript, "--project-root", target], { encoding: "utf8" });
-  assert.equal(verification.status, 0, verification.stderr);
+test("退役入口拒绝旧数据库和 Mock，不作静默别名", () => {
+  const result = spawnSync(process.execPath, [fileURLToPath(new URL("./generate_project.mjs", import.meta.url)), "--database", "oracle", "--with-mock"], { encoding: "utf8" });
+  assert.equal(result.status, 1);
+  assert.match(result.stderr, /deprecated.*yss-mvc-data-analysis-project-initializer/);
 });

package/template/.agents/skills/yss-mvc-scaffold-generator/scripts/lib/envelope.mjs

@@ -5,20 +5,28 @@ import { HARNESS_ROOT, MODULES, PROJECT_SCRIPT_FILES, exists, fail } from "./run
 import { put } from "./storage.mjs";
 
 const TEMPLATE_SOURCE_COMMAND = /scripts\/(?:verify-template(?:-fast|-candidate)?|sync-skills|update-skill-lock|export-yss-skills|verify-upstream-skill-source|verify-maintenance-checkpoint|verify-implementation-path-scenarios|gitworks)/g;
+const TEMPLATE_SOURCE_SECTION = /(^## 4\. `template-source` 模板维护路由[^\S\r\n]*$)[\s\S]*?(?=^## 5\. `project-instance` 产品研发路由[^\S\r\n]*$)/m;
 
 function removeTemplateSourceCommands(content) {
   return content.replace(TEMPLATE_SOURCE_COMMAND, "上游 Harness 专用命令");
 }
 
+export function renderProjectInstanceAgents(content) {
+  if (!TEMPLATE_SOURCE_SECTION.test(content)) fail("无法定位 AGENTS.md 的模板维护章节边界");
+  return content.replace(
+    TEMPLATE_SOURCE_SECTION,
+    "$1\n\n当前仓库是 `project-instance`，模板维护只在上游 Harness 执行。\n\n"
+  );
+}
+
 export async function writeProjectEnvelope(o) {
   await put(o.targetDir, "yss-project.yaml", "schema_version: 1\nrepository_mode: project-instance");
   await put(o.targetDir, ".artifact-workspace.yaml", `schema_version: 1\nkind: service\nservice_id: ${o.projectName}\nowner: ${JSON.stringify(o.gitAuthor)}`);
   await cp(path.join(HARNESS_ROOT, "AGENTS.md"), path.join(o.targetDir, "AGENTS.md"));
   const generatedAgents = await readFile(path.join(o.targetDir, "AGENTS.md"), "utf8");
-  await writeFile(path.join(o.targetDir, "AGENTS.md"), generatedAgents
+  await writeFile(path.join(o.targetDir, "AGENTS.md"), renderProjectInstanceAgents(generatedAgents)
     .replaceAll(".agents/skills", "../skillUtils/.agents/skills")
-    .replaceAll(".codex/skills", "../skillUtils/.codex/skills")
-    .replace("- 模板维护默认以 `scripts/verify-template-fast` 完成 `implementation-ready`；显式晋级审查时用 `scripts/verify-template-candidate`，首次冻结前和最终发布前仍必须执行完整 `scripts/verify-template`。后者是不可裁剪的模板发布阻断门禁。模板与外部 `create-yss-spec` 的跨仓库契约未完成集成验证时，不得声称可发布。", "- 模板发布门禁只在上游 Harness 模板源执行；当前项目实例不分发或运行模板验证命令。"), "utf8");
+    .replaceAll(".codex/skills", "../skillUtils/.codex/skills"), "utf8");
   await put(o.targetDir, "CONTEXT.md", "# 领域上下文\n\n## 业务术语\n\n| 术语 | 定义 | 英文标识 | 避免 / 备注 |\n|---|---|---|---|\n| 分析数据集 | 支撑一个数据分析功能的表结构、字段语义和查询边界。 | AnalysisDataset | 具体业务术语在需求分析后补充 |\n| 分析结果 | 数据分析接口返回的分页明细或聚合结果。 | AnalysisResult | 不表示未经约束的原始结果集 |");
   for (const relative of ["docs/agents", "docs/process", "docs/templates", "docs/architecture/templates"]) {
     const source = path.join(HARNESS_ROOT, relative);

package/template/.agents/skills/yss-mvc-scaffold-generator/scripts/lib/envelope.test.mjs

@@ -0,0 +1,36 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { renderProjectInstanceAgents } from "./envelope.mjs";
+
+test("按章节边界把模板维护路由转换为项目实例说明", () => {
+  const source = `# AGENTS.md
+
+## 3. 上文
+
+保留。
+
+## 4. \`template-source\` 模板维护路由
+
+这里的自然语言允许持续精简，不应参与匹配。
+
+- 模板源命令也不应进入项目实例。
+
+## 5. \`project-instance\` 产品研发路由
+
+继续保留。
+`;
+
+  const result = renderProjectInstanceAgents(source);
+
+  assert.match(result, /## 4\. `template-source` 模板维护路由\n\n当前仓库是 `project-instance`，模板维护只在上游 Harness 执行。/);
+  assert.doesNotMatch(result, /这里的自然语言允许持续精简/);
+  assert.match(result, /## 5\. `project-instance` 产品研发路由\n\n继续保留/);
+});
+
+test("模板维护章节边界缺失时明确失败", () => {
+  assert.throws(
+    () => renderProjectInstanceAgents("# AGENTS.md\n\n## 5. `project-instance` 产品研发路由\n"),
+    /无法定位 AGENTS\.md 的模板维护章节边界/
+  );
+});

package/template/.agents/skills/yss-mybatis/SKILL.md

@@ -16,7 +16,7 @@ description: 用于 YSS MyBatis 与 MyBatis-Plus 持久层规范、配置和排
 
 ## 工作方式
 
-1. 先读取批准的 `persistence_profile`。新 DDD scaffold 当前只支持 `mybatis-plus`；普通 MyBatis 必须有独立 fixture 和批准 Profile，禁止自动猜测或混用。
+1. 先读取批准的 `persistence_profile` 和 `architecture_identity`。新 DDD / MVC scaffold 都使用 `mybatis-plus`；普通 MyBatis 必须有独立 fixture 和批准 Profile，禁止自动猜测或混用。模块所有权按 `docs/agents/backend-architecture-profiles.md`；H2 仅用于本地/测试，生产数据库另行批准接入。
 2. 涉及真实类名、配置项、模块依赖或排障时，先读 `references/source-index.md`，再定位源码或文档。
 3. 先复用现有基类与配置，不手搓新的基础设施。
 4. 涉及分页时，先验证 `PageQuery` 传递链路和拦截器是否生效。
@@ -35,7 +35,7 @@ description: 用于 YSS MyBatis 与 MyBatis-Plus 持久层规范、配置和排
 - MP 模式优先继承项目既有的 `BasePlusRepository`
 - 批量导入优先使用真正的 SQL 级批量方法，不要默认循环单条插入
 - 多数据源问题优先先看配置和扫描范围，再怀疑业务代码
-- 分页查询经 Application Query Port 进入 Infrastructure；可以在适配层转换为组件所需 `PageQuery`，但不得把 `PageQuery` 带入 Domain Gateway，也不得在 Repository 内临时发明分页参数。
+- DDD 分页经 Application Query Port 进入 Infrastructure；MVC 经 service/core 进入 Repository。不把 `PageQuery` 带入 Domain Gateway，也不得在 Repository 内临时发明分页参数。
 - 生成或重构持久层时，先看当前模块已有 Repository/Mapper 命名、包路径、XML 位置。
 
 ## 检查清单

package/template/.agents/skills/yss-product-lifecycle/SKILL.md

@@ -20,9 +20,11 @@ Matt 的 `grill-with-docs`、`to-spec`、`to-tickets`、`implement` 等保留为
 
 ## 不可裁剪的主链
 
+新后端工程先按注册表选择 architecture_profile（target-domain-model / layered-mvc-service / mvc-data-analysis-v1），禁止从模块目录反推。全部新骨架只绑定 H2 本地/测试，不绑定生产数据库。独立数据分析 project-instance 走 `work-unit.service-project-initialization` 和 `yss-mvc-data-analysis-project-initializer`；通用 MVC 不调用该初始化器。父项目只保留交接/服务引用，子项目有自己的根 CONTEXT、Git 和生命周期。规则见 `docs/agents/backend-architecture-profiles.md`；Profile 为 draft 时不得 ready-for-agent。
+
 入口分诊 → Discovery → Spec / 功能架构 → 产品设计 → 系统 / 数据架构与工程契约 → Ticket 正式化 → 垂直切片实现（前后端 TDD）→ 验证 / 发布 / 复盘。
 
-裁剪只允许将未命中的条件门禁标记为 `not-applicable` 并写原因；不得删除主阶段、已命中的门禁或必需产物。阶段是否完成取决于“内容 + 审查结论 + 上游新鲜度 + 可读证据”，文件存在不算通过。
+裁剪只允许将未命中的条件门禁标记为 `not-applicable` 并写原因；不得删除主阶段、已命中的门禁或必需产物。阶段是否完成取决于“内容 + 审查结论 + 上游新鲜度 + 可读证据”，文件存在不算通过。每个 `project-instance` 工作单元在请求批准或进入下一工作单元前，必须先把已确认稳定术语回写到项目根目录唯一的 `CONTEXT.md`，再产出通过 `scripts/verify-context-reconciliation` 的 `context_reconciliation`；它是横切证据，不新增门禁。存在候选术语、错误路径、无法解析的 `<ContextId>/<EnglishIdentifier>`、摘要漂移或未决冲突时返回 `blocked`。
 
 ## 阶段路由与技能
 
@@ -31,22 +33,46 @@ Matt 的 `grill-with-docs`、`to-spec`、`to-tickets`、`implement` 等保留为
 | 主阶段 | 必需产物/门禁 | 原生工作单元与技能 | 通过条件 |
 |---|---|---|---|
 | 入口分诊 `stage.entry-triage` | 身份、影响面、最近可信阶段 | `work-unit.entry-triage`；`yss-product-lifecycle` | `yss-project.yaml` 合法且影响面可解释 |
-| Discovery `stage.discovery` | Discovery、用户/MVP/非目标/成功标准、测试 seam；命中 DDD 影响时补充领域战略设计与阶段决策包 | `work-unit.discovery-opportunity` + `work-unit.discovery-requirements` + `work-unit.domain-strategy-design` + `work-unit.stage-decision`；市场/竞品事实用 `competitive-intelligence`，技术/标准事实用 `yss-research:technical-evidence`，领域战略与阶段决策证据用 `yss-research:strategy-evidence`；需求澄清用 `grilling`，领域建模用 `domain-modeling` / `yss-stage-decision`；`grill-with-docs` 为兼容入口 | 未决事实已由 `yss-research` 核验或 handoff，进入战略 / 阶段门禁的决策证据已 `evidence-audited`，领域边界和统一语言可审查，阶段决策包完成必要批准；`gate.domain-strategy-approved`、`gate.stage-decision-package-approved` |
+| Discovery `stage.discovery` | 机会与目标、业务故事、用户/MVP/非目标/成功标准、测试 seam；需要时补充业务边界与规则设计和方案决策包 | `work-unit.discovery-opportunity` + `work-unit.discovery-requirements` + `work-unit.domain-strategy-design` + `work-unit.stage-decision`；市场/竞品事实用 `competitive-intelligence`，技术/标准事实用 `yss-research:technical-evidence`，业务边界与方案决策证据用 `yss-research:strategy-evidence`；需求澄清用 `grilling`，业务词汇和责任区梳理用 `domain-modeling` / `yss-stage-decision`；`grill-with-docs` 为兼容入口 | 未决事实已由 `yss-research` 核验或 handoff；业务板块、责任区、统一业务词汇、协作关系和不可违反规则可审查；方案决策包完成必要批准；`gate.domain-strategy-approved`、`gate.stage-decision-package-approved` |
 | Spec / 功能架构 `stage.spec-architecture` | Spec、产品总体设计、功能架构；必要时 Spec Delta | 原生 `work-unit.spec-synthesis`；`to-spec` 为兼容入口 | 初稿先为 `ready-for-human`；只有 Spec baseline 会签批准后资产才为 `approved` 并进入下游 |
-| 产品设计 `stage.product-design` | 交互说明、低保真、状态矩阵、H1/H2 原型交付物、评审记录 | `work-unit.prototype-design`；`yss-prototype-stage` 先消费 `yss-design-system`、低保真与独立 `prototype-review`，再按风险选择 H1 静态视觉或 H2 可运行流程；`yss-antd-design` 只在相关 H2 条件调用，原型阶段禁止调用 `yss-ui` | `gate.prototype-reviewed`、`gate.prototype-verified`、`gate.user-confirmation` 均有 schema v3 证据；真实组件待验事项已交接到前端实现计划 |
+| 产品设计 `stage.product-design` | 交互说明、低保真、状态矩阵、H1/H2 原型交付物、评审记录 | `work-unit.prototype-design`；`yss-prototype-stage` 先消费 `yss-design-system`、低保真与独立 `prototype-review`，再按风险选择 H1 静态视觉或 H2 可运行流程；H2 默认调用 `yss-antdv-next-design`，显式 `react-antd-6` 兼容路线才调用 `yss-antd-design`，原型阶段禁止调用 `yss-ui` | `gate.prototype-reviewed`、`gate.prototype-verified`、`gate.user-confirmation` 均有 schema v3 证据；真实组件待验事项已交接到前端实现计划 |
 | 系统 / 数据架构与工程契约 `stage.system-data-engineering` | OpenAPI Draft/Freeze、数据架构、工程基线、架构审查；按领域影响执行 Tactical DDD Check | `work-unit.technical-analysis`；`yss-implementation-contract-compiler` + `yss-openapi-governance` / `yss-openapi-draft-review`、`codebase-design`、`implementation-repo-onboarding`、`yss-tactical-design`；用户或合同明确要求架构可视化时条件追加 `archify` | API/架构契约冻结；无 API 影响有明确记录；战术模型无未解释冲突；脚手架策略满足；Archify 图只作派生审查证据；`gate.openapi-draft-reviewed`、`gate.design-reviewed`、`gate.openapi-frozen`、`gate.engineering-baseline-accepted`、`gate.architecture-reviewed` |
 | Ticket 正式化 `stage.ticket-formalization` | 功能父 Ticket、垂直切片、Slice Implementation Contract | 原生 `work-unit.ticket-decomposition`；`yss-implementation-contract-compiler`；`to-tickets` 为兼容入口；生命周期复算 | 依赖、验收、测试 seam 可执行；合同已批准、持久化且为当前版本；`gate.slice-contract-approved`、`gate.slice-ready-for-agent` |
-| 垂直切片实现 `stage.vertical-slice-implementation` | 前端/后端代码、TDD 证据、YSS Skill Execution Result | 原生 `work-unit.slice-implementation`；`yss-implementation-contract-compiler` + `tdd`；前端按 `yss-ui` + `yss-page-module-development`，后端按 实现合同编译器 最小闭包；`implement` 为兼容入口 | 仅接收已完成 Ticket 正式化、已绑定垂直切片且 `ready-for-agent` 公式通过的输入；只写允许路径；业务行为用 `tdd` 的 `behavior-tdd` 模式；UI 影响必须有还原计划 |
+| 垂直切片实现 `stage.vertical-slice-implementation` | 前端/后端代码、TDD 证据、YSS Skill Execution Result | 原生 `work-unit.slice-implementation`；`yss-implementation-contract-compiler` + `tdd`；前端按 `yss-ui` + `yss-ui-business-page-generation`，后端按 实现合同编译器 最小闭包；`implement` 为兼容入口 | 仅接收已完成 Ticket 正式化、已绑定垂直切片且 `ready-for-agent` 公式通过的输入；只写允许路径；业务行为用 `tdd` 的 `behavior-tdd` 模式；UI 影响必须有还原计划 |
 | 验证 / 发布 / 复盘 `stage.verification-release-retrospective` | 不可变候选快照、review 结论、fresh verification、发布 / 回滚证据、复盘记录 | `work-unit.frontend-implementation-verification` + `work-unit.code-review` + `work-unit.release-and-retrospective`；`code-review` 独立于实现者，Standards 消费合同 `required_skills` 与 YSS / Alibaba 专项检查输入；UI 影响追加 `yss-ui` + `yss-design-system` 的 UI fidelity 轴；发布 / 复盘由生命周期持有 | findings 已按合同分流处理（修复后全轴复审或 stale 回 实现合同编译器）；同一候选快照通过全部审查轴、专项覆盖与验证；UI 影响追加 `gate.frontend-implementation-verified`；`gate.release-ready` 仍须生物人 |
 
+## 面向业务角色的默认入口
+
+Discovery 默认通过 Agent 引导，不要求产品、需求或商务直接填写内部模型字段。按以下主线推进：
+
+`机会与目标 → 业务故事 → 责任与交接 → 规则、例子与疑问 → 可验收需求 → 页面验证 → 业务任务 → 交接研发`
+
+Agent 先问清六件事：谁遇到什么问题并想得到什么结果；事情通常怎样发生；每一步由谁负责并交给谁；有哪些规则、例外和未决问题；哪一小段可以独立交付；用哪些例子和证据证明结果正确。需要分类业务板块时，改问“是否直接决定关键结果、是否有独特规则、是否可复用或外购”，再提出“重点业务、必要支撑、通用能力”建议，由业务负责人确认。
+
+每轮路由先输出一页派生的“业务方案总览”，引用机会与目标、业务故事、业务责任区、规则与例子、Spec、页面验证、Ticket 和交接状态。总览只显示状态、权威资产引用、未决问题、责任人和下一步，不复制正文、不成为新的事实源，也不新增门禁。内部稳定 ID 和兼容字段只在 Agent 运行结果或维护者诊断中显示。
+
 ## 前端实现还原硬检查
 
-原型通过不等于前端实现通过。`ready-for-agent` 前先产生 `frontend_implementation_plan`（原型/Spec、路由与页面清单、桌面/窄屏验收用例、加载/空态/错误/权限/关键交互状态、拟执行的 `pnpm` 命令）；实现完成、发布前再产生 `frontend_implementation_verification`，补齐截图或视觉回归、console warning、命令退出码、未覆盖差异与责任人。差异未解释、截图缺失、只做 type-check 或只声称“已对齐”均为 `blocked`；发现新 API、状态或视觉行为时返回 `new_impacts`/`drift` 并重新路由。优先使用 `yss-ui/references/verification.md` 的分层验证和既有 `pnpm` scripts。
+采用专职前端 profile 或显式 `frontend_delivery` 绑定时，先按 `docs/process/frontend-backend-delivery.md` 实际核验战略与后端联合交付。缺任一输入只能诊断和回交；输入通过后准备计划/合同，正式实现、生成和恢复仍须当前批准的 Slice Contract 冻结接收摘要。接口或部署版本漂移时重新接收，不复用旧成功输出。
+
+原型通过不等于前端实现通过。`ready-for-agent` 前先产生 `frontend_implementation_plan`，绑定批准且 digest 当前的 Visual Baseline manifest，并按垂直切片选择 `case_id`；实现完成、发布前再产生 `frontend_implementation_verification`，逐 case 配对基准图、实现图、diff/mask 与差异解释，同时补齐交互、console warning、实际 `pnpm` 命令和退出码。模型必须先读 manifest 与语义引用再查看图片，禁止通过目录 glob 猜测含义。差异未解释、图片或摘要缺失、只做 type-check 或只声称“已对齐”均为 `blocked`；Visual Baseline 版本或 digest 变化使实现计划和 Slice Contract `stale`，新 API、状态或视觉行为返回 `new_impacts`/`drift` 并重新路由。优先使用 `yss-ui/references/verification.md` 的分层验证和既有 `pnpm` scripts。
+
+## 真实用户决定
+
+关键决定按 `docs/agents/digital-human-roles.yaml.user_decision_policy` 强制取得提问者或其明确指定的生物人负责人的原始回复。先展示资产、版本、变化、风险、推荐方案、批准范围和后续动作，再等待决定；超时、默认选项、数字人同意、无反对意见均无效。数字人审查不能替代用户批准；已有同版本同范围的有效确认复用，依据变化或撤回后重新展示并确认。单项“同意”有效，多项“继续”不算全部批准。独立工作可继续，依赖工作不得流转。
+
+统一记录、跨平台来源、机器校验、批量批准、历史兼容和实施范围绑定见 [user-decisions.md](references/user-decisions.md)。批准、恢复和实施入口必须重读来源与当前资产；不得只填 `approved`、自行创建用户同意或用旧数字人记录关闭关键门禁。
 
 ## 结果与暂停
 
-凡主控向数字人角色或独立运行时正式派发生命周期工作单元，都必须通过结构化任务包派发，并返回 `Workflow Execution Result`（workflow reference、skill、changed files、evidence refs、actual verification、deferred seams、drift/new impacts）。任务包使用 `docs/process/schemas/digital-human-task-package.schema.json`，由 `scripts/verify-digital-human-task-package` 校验；其中 `role_id`、`runtime_id`、`execution_state`、`contract.kind/id/version`、允许写路径、预期证据和汇合引用必须完整。`slice-implementation` 任务包额外绑定批准且当前版本的 Slice Implementation Contract；Discovery、Spec、原型、技术分析、Ticket、Review、发布和模板维护分别绑定各自的生命周期资产或维护 checkpoint，不得伪造 Slice Contract。缺少可读证据、`stale`、`violation`、`drift`、`new_impacts` 或阻塞信号时不得标记 completed。实现授权不包含 Git commit/push 授权；“做完提交”等自然语言意向不构成上述结构化 Git 授权。
+凡主控向数字人角色或独立运行时正式派发生命周期工作单元，都必须通过结构化任务包派发，并返回 `Workflow Execution Result`（workflow reference、skill、changed files、`context_reconciliation`、evidence refs、actual verification、deferred seams、drift/new impacts）。任务包使用 `docs/process/schemas/digital-human-task-package.schema.json`，由 `scripts/verify-digital-human-task-package` 校验；其中 `role_id`、`runtime_id`、`execution_state`、`contract.kind/id/version`、允许写路径、预期证据和汇合引用必须完整。`slice-implementation` 任务包额外绑定批准且当前版本的 Slice Implementation Contract；Discovery、Spec、原型、技术分析、Ticket、Review、发布和模板维护分别绑定各自的生命周期资产或维护 checkpoint，不得伪造 Slice Contract。缺少可读证据、`context_reconciliation` 未通过、`stale`、`violation`、`drift`、`new_impacts` 或阻塞信号时不得标记 completed。实现授权不包含 Git commit/push 授权；仅自然语言意向不构成上述结构化 Git 授权。用户已明确授权的具体动作可从原始回复整理为结构化授权并复用，不重复要求用户填写内部字段。
 
-输出固定包含：模式、当前阶段、影响面、资产/门禁状态、证据、Ticket 正式化状态、垂直切片引用、`ready-for-agent` 计算结果、阻塞项、本轮动作、下一工作单元、暂停/继续理由、Ticket 同步和 Git checkpoint 判断。原生路径未出现 `to-tickets` / `implement` 名称本身不构成异常；但没有完成 `work-unit.ticket-decomposition`、垂直切片仍为 `ready-for-human`、引用父 Ticket 或 `next_route` 越过 Ticket 正式化时必须返回 `blocked`。暂停会签时必须输出门禁 ID、指定 `role_id`、`runtime_id` 和会签文件路径（`docs/.scratch/<feature>/gates/<gate-id>-approval.yaml`）。恢复前运行 `scripts/verify-approval-record`；错误会签记为 `blocked`，不得把该门禁标为 `approved`。任务包的 `core_skills` / `forbidden_skills` 必须从 `docs/agents/digital-human-roles.yaml` 复制（`taskPackageDefaults`），禁止手写第二套。
+输出固定包含：模式、当前阶段、影响面、资产/门禁状态、证据、Ticket 正式化状态、垂直切片引用、`ready-for-agent` 计算结果、阻塞项、本轮动作、下一工作单元、暂停/继续理由、Ticket 同步和 Git checkpoint 判断。原生路径未出现 `to-tickets` / `implement` 名称本身不构成异常；但没有完成 `work-unit.ticket-decomposition`、垂直切片仍为 `ready-for-human`、引用父 Ticket 或 `next_route` 越过 Ticket 正式化时必须返回 `blocked`。暂停会签时必须输出门禁 ID、指定 `role_id`、`runtime_id` 和会签文件路径（`docs/.scratch/<feature>/gates/<gate-id>-approval.yaml`）。恢复前运行 `scripts/verify-approval-record --require-approved`；错误会签记为 `blocked`，不得把该门禁标为 `approved`。任务包的 `core_skills` / `forbidden_skills` 必须从 `docs/agents/digital-human-roles.yaml` 复制（`taskPackageDefaults`），禁止手写第二套。
 
 详细执行循环、readiness、脚手架（包括 `controlled-generation`）、审查快照、状态传播和 Matt 边界见 [orchestration.md](references/orchestration.md)、[orchestration-contract.yaml](references/orchestration-contract.yaml)、[artifact-dependencies.md](references/artifact-dependencies.md) 和 [state-model.md](references/state-model.md)。
+
+## 战略交接快照包
+
+跨仓交接使用 `scripts/strategic-handoff export / verify / import`。正式导出前补齐源战略的稳定规则 ID、关键场景和当前批准绑定；源资产原字节冻结、包内路径通过清单解析。目标导入只产生快照和对账/承接草案，正式 reconciliation 通过后才能进入战术设计。流程与字段见 `docs/process/strategic-handoff-package.md`。
+
+战术合同必须绑定 `strategic_handoff` 导入收据、包摘要、正式目标对账及逐条承接 rows。来自导入包时禁止仅填 `upstream_current: true`。批准前执行 `scripts/verify-strategic-handoff-consumption --root <target> <tactical>`；存在受控延期时按切片执行 `--slice <slice-id>`，实际核验通过且合同批准后才可继续相关切片。最新源规则、关键场景或资产变化使依赖项 stale；未知依赖扩大阻断，业务冲突回交战略方。结果绑定当前包与战术摘要，不能复用旧输出宣布 ready-for-agent。

package/template/.agents/skills/yss-product-lifecycle/references/artifact-dependencies.md

@@ -4,6 +4,7 @@
 
 ```text
 Discovery → Spec → Product Overview / Functional Architecture
+Root CONTEXT.md + current work-unit changes → Context Reconciliation → approval / next work unit
 Spec + Product Overview → Product Design / Requirement Freeze
 Spec + Product Overview → API Impact / OpenAPI Draft
 Spec + Product Overview → System / Data Architecture
@@ -34,3 +35,5 @@ Implementation → Independent Review → Fresh Verification → Release
 OpenAPI Freeze 后发生上游变化时，不得仅因父 Ticket 仍写阶段 6 就继续实现。先做影响分析，再精准更新相关资产和门禁。
 
 战术设计合同上游引用发生版本变化时，先将 tactical-design 标记为 `stale`，再传播到 Slice Contract；发现新的聚合、状态、不变量、一致性或 Gateway 影响时标记 `drift` / `new_impacts` 并重新路由。
+
+`CONTEXT.md` 全文摘要变化时，先复核当前和下游资产保存的 `document_digest`；只有其 `referenced_terms_digest` 也变化，才将实际引用这些术语的资产精准标记为 `stale`。无法解析、作用域变化或候选术语未确认时阻断批准/流转，不得用嵌套文件、跨仓路径或 Markdown 锚点绕过。

package/template/.agents/skills/yss-product-lifecycle/references/matt-yss-adapter.md

@@ -7,16 +7,14 @@ Matt skills 决定如何工作；YSS 生命周期决定是否允许推进；YSS
 ## 入口与仓库身份裁决
 
 - 所有入口先读取 `yss-project.yaml`。缺失、解析失败、schema 不支持或 `repository_mode` 非法时，停止路由并进入 migration-check。
-- **直接调用 `ask-matt`** 时，它只能提供通用 Matt flow 导航，不得写生命周期资产、改变门禁或 Ticket 状态；有效 YSS 仓库必须在任何写入前把最终阶段、影响面、门禁和状态裁决交回 `yss-product-lifecycle`。
-- **直接调用生命周期管理的 Matt user-invoked skill**（`setup-matt-pocock-skills`、`grill-with-docs`、`to-spec`、`to-tickets`、`implement`）时，用户仍是正式资产的创建者；生命周期先校验前置条件，再接受结果并重新计算阶段、门禁和状态。它们不适用 `ask-matt` 的 `navigate-only` 限制。其他 user-invoked skill 同样不得由生命周期自动调用；只有在其专属适配合同存在时才进入 YSS 流程。
+- **直接调用生命周期管理的 Matt user-invoked skill**（`setup-matt-pocock-skills`、`grill-with-docs`、`to-spec`、`to-tickets`、`implement`）时，用户仍是正式资产的创建者；生命周期先校验前置条件，再接受结果并重新计算阶段、门禁和状态。其他 user-invoked skill 同样不得由生命周期自动调用；只有在其专属适配合同存在时才进入 YSS 流程。
 - **直接调用 `yss-product-lifecycle`** 时，不机械嵌套调用任何 Matt user-invoked skill；编排器直接使用原生工作单元和允许的 model-invoked 原语。Matt user-invoked skill 保持显式兼容入口，生命周期负责准备、校验并验收其结果。
-- `template-source` 只允许进入模板维护流程。命中 `to-spec`、`to-tickets`、`implement`、Release 或 Retrospective 时返回 `blocked`，原因是 `template-source-product-artifact-forbidden`；`ask-matt` 和 `setup-matt-pocock-skills` 都不得为具体产品生成 Spec、prototype、OpenAPI 或垂直切片 Ticket。
+- `template-source` 只允许进入模板维护流程。命中 `to-spec`、`to-tickets`、`implement`、Release 或 Retrospective 时返回 `blocked`，原因是 `template-source-product-artifact-forbidden`；`setup-matt-pocock-skills` 不得为具体产品生成 Spec、prototype、OpenAPI 或垂直切片 Ticket。
 - `project-instance` 才允许进入产品 Discovery → Spec → 设计 → 契约 → Ticket → 实现 → Release / Retrospective 链路。
 
 | 情形 | Matt flow | 生命周期验收 |
 |---|---|---|
 | 首次启用或配置缺失 | `setup-matt-pocock-skills`（用户显式） | `needs-human`，说明缺失项；用户完成 setup 后重新计算 readiness |
-| 通用入口 | `ask-matt` | 检测到 YSS 后由本编排器最终裁决 |
 | 需求澄清 | `grill-with-docs`（用户显式）或 `grilling`、`domain-modeling`（生命周期原语） | 按退出判定检查未决项和回流 |
 | 信息在其他人手中 | `to-questionnaire` | 使用 `external-input-required` 暂停；答案回流后记录 response、重新分类影响面，再进入 `grill-with-docs` 或 `to-spec` |
 | 大型模糊工作 | `wayfinder`（可选） | 仅在跨会话 / 跨 Agent 或 frontier 不清晰时启用；map 真正完成后 `handoff → to-spec` |
@@ -28,7 +26,7 @@ Matt skills 决定如何工作；YSS 生命周期决定是否允许推进；YSS
 | Bug | `diagnosing-bugs`、`tdd` | 先建立红色反馈；高风险影响升级上游门禁 |
 | 审查 | `code-review` | 唯一默认代码审查入口；审查者独立且不得写实现；Standards 消费 Spec、仓库治理规则、Slice `required_skills` 和 YSS / Alibaba 专项检查输入；finding 按合同分流修复或 stale 回 实现合同编译器 |
 | 跨上下文 | `handoff` | 保存来源、阶段、未决项、命令和下一责任人 |
-| 阶段边界 | `PHASE-BOUNDARIES.md` | 按 `Continue → /clear → /handoff → subagent → /compact` 选择上下文动作；只记录证据，不扩展生命周期状态 |
+| 阶段边界 | 生命周期 phase-boundary 合同 | 按 `Continue → /clear → /handoff → subagent → /compact` 选择上下文动作；只记录证据，不扩展生命周期状态 |
 | 解释未落地 | `wait-what` | 只重新解释当前结论，不改变阶段、门禁、Ticket 或 `ready-for-agent` |
 | 人工步骤 | 人工 checkpoint | 记录 Agent 无法替代的点击、审批、凭据和迁移步骤；秘密值必须隐藏并脱敏 |
 | 编写 Agent 文档 | `writing-for-agents`；维护 skill 时使用 `maintaining-skills` | 共享 skill 只改 `.agents/skills`；流程文档保持简体中文 |
@@ -119,4 +117,4 @@ Matt 的上下文建议不能覆盖 YSS 的 phase-boundary 契约。固定按 `C
 
 ## Release / Retrospective
 
-Release 和 Retrospective 是生命周期编排器拥有的工作单元，不由 `ask-matt` 的默认 `idea → ship` 流程隐式完成。进入发布或完成结论前必须重新取得 fresh verification、发布/回滚证据和独立审查结果；复盘同样必须有 fresh verification，再按模板治理规则回流 `AGENTS.md`、`CONTEXT.md`、ADR 或 Skill。
+Release 和 Retrospective 是生命周期编排器拥有的工作单元，不由任何兼容流程隐式完成。进入发布或完成结论前必须重新取得 fresh verification、发布/回滚证据和独立审查结果；复盘同样必须有 fresh verification，再按模板治理规则回流 `AGENTS.md`、`CONTEXT.md`、ADR 或 Skill。