create-yss-spec 3.0.0 → 3.1.0

package/template/.claude/skills/yss-mvc-scaffold-generator/scripts/lib/runtime.mjs

@@ -0,0 +1,115 @@
+import { existsSync } from "node:fs";
+import { stat } 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";
+
+export const MODULES = ["server", "core", "client", "repository", "adapter", "feign-client"];
+export const SKILL_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+export const HARNESS_ROOT = findHarnessRoot();
+export const SHARED_SKILLS_ROOT = path.join(HARNESS_ROOT, ".agents", "skills");
+export const SKILL_UTILS_NAME = "skillUtils";
+export const SKILL_UTILS_DIRECTORIES = [
+  ".agents/skills", ".claude/skills", ".codex/skills", ".cursor/skills",
+  ".pi/skills", ".qoder/skills", ".trae/skills"
+];
+export const PROJECT_SCRIPT_FILES = [
+  "check-agent-environment.mjs", "implementation-path-policy", "repository-mode", "repository-scope-policy",
+  "generate-lifecycle-artifacts", "node-generate-lifecycle-artifacts.mjs", "node-verify-lifecycle-registry.mjs",
+  "verify-lifecycle-registry", "verify-lifecycle-checkpoint", "verify-frontend-implementation-evidence",
+  "verify-yss-dto-openapi-profile"
+];
+
+export function findHarnessRoot() {
+  let candidate = SKILL_ROOT;
+  while (true) {
+    if (existsSync(path.join(candidate, ".agents", "skills")) && existsSync(path.join(candidate, "AGENTS.md"))) return candidate;
+    const parent = path.dirname(candidate);
+    if (parent === candidate) break;
+    candidate = parent;
+  }
+  throw new Error(`未找到插件 Harness 根目录: ${SKILL_ROOT}`);
+}
+
+export function fail(message) { throw new Error(message); }
+
+export function parseArgs(argv) {
+  const options = { database: "oracle", withMock: false, dryRun: false };
+  const fields = {
+    "--project-name": "projectName", "--base-package": "basePackage", "--target-dir": "targetDir",
+    "--database": "database", "--maven-settings": "mavenSettings"
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    let token = argv[index];
+    if (token === "--with-mock") { options.withMock = true; continue; }
+    if (token === "--dry-run") { options.dryRun = true; continue; }
+    if (token === "--help" || token === "-h") { options.help = true; continue; }
+    const equals = token.indexOf("=");
+    let value = equals >= 0 ? token.slice(equals + 1) : undefined;
+    if (equals >= 0) token = token.slice(0, equals);
+    if (!fields[token]) fail(`不支持的参数: ${token}`);
+    if (value === undefined) value = argv[++index];
+    if (!value || value.startsWith("--")) fail(`参数 ${token} 缺少值`);
+    options[fields[token]] = value;
+  }
+  if (options.help) return options;
+  if (!options.projectName || !/^[a-z][a-z0-9-]*$/.test(options.projectName)) fail("--project-name 必须是小写连字符名称");
+  if (!options.basePackage || !/^[a-zA-Z_$][\w$]*(\.[a-zA-Z_$][\w$]*)+$/.test(options.basePackage)) fail("--base-package 不是合法 Java 包名");
+  if (!options.targetDir) fail("必须提供 --target-dir");
+  if (!["oracle", "oceanbase-oracle"].includes(options.database)) fail("--database 只支持 oracle 或 oceanbase-oracle");
+  options.targetDir = path.resolve(options.targetDir);
+  if (options.mavenSettings) options.mavenSettings = path.resolve(options.mavenSettings);
+  return options;
+}
+
+export async function exists(target) {
+  try { await stat(target); return true; } catch (error) {
+    if (error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+export function xml(value) { return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;"); }
+export function packagePath(name) { return name.replaceAll(".", "/"); }
+export function generatedAtLocal() {
+  const now = new Date();
+  const pad = (value) => String(value).padStart(2, "0");
+  return `${now.getFullYear()}/${pad(now.getMonth() + 1)}/${pad(now.getDate())} ${pad(now.getHours())}:${pad(now.getMinutes())}`;
+}
+
+export function runGit(args, cwd) { return spawnSync("git", args, { cwd, encoding: "utf8" }); }
+export function assertGitAvailable() {
+  const result = runGit(["--version"], process.cwd());
+  if (result.status !== 0) fail("未检测到可用的 Git，无法初始化独立项目仓库");
+}
+export function resolveGitAuthor() {
+  const result = runGit(["config", "--get", "user.name"], process.cwd());
+  const author = result.status === 0 ? result.stdout.trim() : "";
+  if (!author) fail("未配置 Git user.name；请先执行 git config --global user.name \"你的姓名\"");
+  if (/[\r\n]|\*\//.test(author)) fail("Git user.name 包含不能安全写入 Javadoc 的字符");
+  return author;
+}
+export function initializeGit(root) {
+  let result = runGit(["init", "--initial-branch=main"], root);
+  if (result.status !== 0) {
+    result = runGit(["init"], root);
+    if (result.status === 0) result = runGit(["branch", "-M", "main"], root);
+  }
+  if (result.status !== 0) fail(`Git 仓库初始化失败: ${(result.stderr || result.stdout).trim()}`);
+}
+
+export async function resolveMavenSettings(options) {
+  if (options.mavenSettings) {
+    if (!await exists(options.mavenSettings)) fail(`Maven settings 不存在: ${options.mavenSettings}`);
+    return { path: options.mavenSettings, source: "explicit", available: true };
+  }
+  if (process.env.YSS_MAVEN_SETTINGS) {
+    const environmentPath = path.resolve(process.env.YSS_MAVEN_SETTINGS);
+    if (!await exists(environmentPath)) fail(`Maven settings 不存在: ${environmentPath}`);
+    return { path: environmentPath, source: "environment", available: true };
+  }
+  const userSettings = path.join(os.homedir(), ".m2", "settings.xml");
+  if (await exists(userSettings)) return { path: userSettings, source: "user-home", available: true };
+  return { path: null, source: "maven-default", available: false };
+}

package/template/.claude/skills/yss-mvc-scaffold-generator/scripts/lib/storage.mjs

@@ -0,0 +1,90 @@
+import { cp, mkdir, mkdtemp, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import {
+  HARNESS_ROOT,
+  SKILL_ROOT,
+  SKILL_UTILS_DIRECTORIES,
+  SKILL_UTILS_NAME,
+  fail,
+  exists
+} from "./runtime.mjs";
+
+const BOOTSTRAP_ONLY_SKILLS = ["yss-mvc-scaffold-generator"];
+
+async function distributedSkillLock() {
+  const source = path.join(HARNESS_ROOT, "skills-lock.json");
+  if (!await exists(source)) fail(`技能工具包源锁文件不存在: ${source}`);
+  const lock = JSON.parse(await readFile(source, "utf8"));
+  for (const name of BOOTSTRAP_ONLY_SKILLS) {
+    delete lock.skills?.shared?.[name];
+    for (const platform of Object.values(lock.skills?.platform ?? {})) delete platform?.[name];
+  }
+  return `${JSON.stringify(lock, null, 2)}\n`;
+}
+
+export async function assertEmpty(target) {
+  if (!await exists(target)) return;
+  if ((await readdir(target)).length) fail(`目标目录非空，拒绝生成: ${target}`);
+}
+
+export async function put(root, relative, content, author) {
+  const target = path.join(root, relative);
+  const rendered = author ? content.replaceAll("@author system", `@author ${author}`) : content;
+  await mkdir(path.dirname(target), { recursive: true });
+  await writeFile(target, `${rendered.trim()}\n`, "utf8");
+}
+
+export async function renderAsset(name, replacements) {
+  let content = await readFile(path.join(SKILL_ROOT, "assets", name), "utf8");
+  for (const [token, value] of Object.entries(replacements)) content = content.replaceAll(`{{${token}}}`, value);
+  return content;
+}
+
+async function populateSkillUtils(destination) {
+  await mkdir(destination, { recursive: true });
+  for (const relative of SKILL_UTILS_DIRECTORIES) {
+    const source = path.join(HARNESS_ROOT, relative);
+    if (!await exists(source)) fail(`技能工具包源目录不存在: ${source}`);
+    await cp(source, path.join(destination, relative), { recursive: true });
+  }
+  for (const root of SKILL_UTILS_DIRECTORIES) {
+    for (const name of BOOTSTRAP_ONLY_SKILLS) {
+      await rm(path.join(destination, root, name), { recursive: true, force: true });
+    }
+  }
+  await writeFile(path.join(destination, "skills-lock.json"), await distributedSkillLock(), "utf8");
+  const publicSkills = path.join(HARNESS_ROOT, "yss-public-skills.json");
+  if (!await exists(publicSkills)) fail(`技能工具包源文件不存在: ${publicSkills}`);
+  await cp(publicSkills, path.join(destination, "yss-public-skills.json"));
+  await writeFile(path.join(destination, "skill-utils.yaml"), `schema_version: 1\nkind: yss-skill-utils\ntool_version: 1.0.0\ncompatibility: skill-utils-v1\nsource: ${path.basename(HARNESS_ROOT)}\ncanonical_root: .agents/skills\nprojection_roots:\n  - .codex/skills\n  - .claude/skills\n  - .cursor/skills\nexcluded_skills:\n  - yss-mvc-scaffold-generator\n`, "utf8");
+}
+
+export async function ensureSkillUtils(targetDir, { apply = true } = {}) {
+  const parent = path.dirname(targetDir);
+  const skillUtils = path.join(parent, SKILL_UTILS_NAME);
+  const marker = path.join(skillUtils, "skill-utils.yaml");
+  const expectedLock = await distributedSkillLock();
+  if (await exists(skillUtils)) {
+    if (!await exists(marker)) fail(`技能工具包目录已存在但不是受支持的 skillUtils: ${skillUtils}`);
+    const installedLock = path.join(skillUtils, "skills-lock.json");
+    const current = await exists(installedLock) ? await readFile(installedLock, "utf8") : "";
+    if (current === expectedLock) return { path: skillUtils, created: false, refreshed: false, backup: null };
+    if (!apply) return { path: skillUtils, created: false, refreshed: true, backup: null };
+    const staging = await mkdtemp(path.join(parent, ".skillUtils.refresh-"));
+    const backup = path.join(parent, `.skillUtils.backup-${Date.now()}`);
+    try {
+      await populateSkillUtils(staging);
+      await rename(skillUtils, backup);
+      try { await rename(staging, skillUtils); }
+      catch (error) { await rename(backup, skillUtils); throw error; }
+    } catch (error) {
+      if (await exists(staging)) await rm(staging, { recursive: true, force: true });
+      throw error;
+    }
+    return { path: skillUtils, created: false, refreshed: true, backup };
+  }
+  if (!apply) return { path: skillUtils, created: true, refreshed: false, backup: null };
+  await populateSkillUtils(skillUtils);
+  return { path: skillUtils, created: true, refreshed: false, backup: null };
+}

package/template/.claude/skills/yss-mvc-scaffold-generator/scripts/lib/templates.mjs

@@ -0,0 +1,54 @@
+import { generatedAtLocal, packagePath, xml } from "./runtime.mjs";
+
+export function parentPom(o) {
+  const modules = o.modules.map((module) => `    <module>${module}</module>`).join("\n");
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion><parent><groupId>com.yss.cloud</groupId><artifactId>yss-cloud-microservice</artifactId><version>2.0.0-SNAPSHOT</version><relativePath/></parent>
+  <groupId>${xml(o.basePackage)}</groupId><artifactId>${o.projectName}</artifactId><version>2.0.0-SNAPSHOT</version><packaging>pom</packaging>
+  <properties><java.version>1.8</java.version><maven.compiler.source>1.8</maven.compiler.source><maven.compiler.target>1.8</maven.compiler.target><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding><yss-components.version>2.0.0-SNAPSHOT</yss-components.version></properties>
+  <modules>\n${modules}\n  </modules>
+  <dependencyManagement><dependencies><dependency><groupId>com.yss.cloud</groupId><artifactId>yss-components-bom</artifactId><version>\${yss-components.version}</version><type>pom</type><scope>import</scope></dependency></dependencies></dependencyManagement>
+  <build><plugins><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId></plugin><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-source-plugin</artifactId></plugin><plugin><groupId>com.coveo</groupId><artifactId>fmt-maven-plugin</artifactId><version>2.9.1</version></plugin></plugins></build>
+</project>`;
+}
+
+export function modulePom(o, module) {
+  const artifact = (name) => `<dependency><groupId>${xml(o.basePackage)}</groupId><artifactId>${o.projectName}-${name}</artifactId><version>\${project.version}</version></dependency>`;
+  const yss = (name) => `<dependency><groupId>com.yss.cloud</groupId><artifactId>${name}</artifactId></dependency>`;
+  const databaseDriver = o.database === "oceanbase-oracle" ? `<dependency><groupId>com.oceanbase</groupId><artifactId>oceanbase-client</artifactId><version>2.4.3</version></dependency>` : `<dependency><groupId>com.oracle.database.jdbc</groupId><artifactId>ojdbc8</artifactId><version>19.8.0.0</version></dependency>`;
+  const dependencies = {
+    client: `${yss("yss-component-dto")}\n${yss("yss-component-validation-jsr303")}\n<dependency><groupId>com.yss.cloud</groupId><artifactId>yss-component-excel-mvc</artifactId><version>\${yss-components.version}</version></dependency>\n<dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><scope>provided</scope></dependency>`,
+    core: `${artifact("client")}\n${yss("yss-component-exception")}\n<dependency><groupId>com.yss.datamiddle</groupId><artifactId>yss-component-userinfo-starter</artifactId></dependency>\n<dependency><groupId>org.mapstruct</groupId><artifactId>mapstruct</artifactId></dependency>`,
+    repository: `${artifact("core")}\n${artifact("client")}\n${yss("yss-component-mybatis-starter")}\n${yss("yss-component-distributed-id")}\n${databaseDriver}`,
+    adapter: `${artifact("core")}\n${artifact("client")}\n<dependency><groupId>org.springframework</groupId><artifactId>spring-context</artifactId></dependency>\n<dependency><groupId>org.springframework.cloud</groupId><artifactId>spring-cloud-openfeign-core</artifactId></dependency>`,
+    "feign-client": `${artifact("client")}\n<dependency><groupId>org.springframework.cloud</groupId><artifactId>spring-cloud-openfeign-core</artifactId></dependency>`,
+    server: `<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency>\n<dependency><groupId>org.springframework.cloud</groupId><artifactId>spring-cloud-starter-bootstrap</artifactId></dependency>\n${artifact("repository")}\n${artifact("adapter")}\n${artifact("client")}\n${yss("yss-component-audit-log")}\n${yss("yss-component-cache-starter")}\n<dependency><groupId>com.yss.cloud</groupId><artifactId>yss-component-excel-mvc</artifactId><version>\${yss-components.version}</version></dependency>\n${yss("yss-component-distributed-id")}\n<dependency><groupId>com.yss.datamiddle</groupId><artifactId>yss-component-userinfo-starter</artifactId></dependency>\n<dependency><groupId>org.springframework.cloud</groupId><artifactId>spring-cloud-starter-openfeign</artifactId></dependency>\n<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-actuator</artifactId></dependency>\n<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope></dependency>`
+  }[module];
+  const profiles = module === "server" ? `<profiles><profile><id>nacos</id><activation><activeByDefault>true</activeByDefault></activation><properties><app.env>dev</app.env><app.profiles>nacos</app.profiles></properties><dependencies><dependency><groupId>com.alibaba.cloud</groupId><artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId></dependency><dependency><groupId>com.alibaba.cloud</groupId><artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId></dependency></dependencies></profile></profiles>` : "";
+  const plugin = module === "server" ? `<build><plugins><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId></plugin><plugin><groupId>com.ly.smart-doc</groupId><artifactId>smart-doc-maven-plugin</artifactId><version>3.0.5</version><configuration><configFile>src/main/resources/smart-doc.json</configFile><includes><include>com.yss.cloud:yss-component-dto</include><include>com.yss.cloud:yss-component-exception</include><include>com.yss.cloud:yss-component-cache-starter</include><include>${xml(o.basePackage)}:${o.projectName}-client</include><include>${xml(o.basePackage)}:${o.projectName}-core</include><include>${xml(o.basePackage)}:${o.projectName}-repository</include></includes><projectName>\${project.artifactId}</projectName></configuration></plugin></plugins></build>` : "";
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"><modelVersion>4.0.0</modelVersion><parent><groupId>${xml(o.basePackage)}</groupId><artifactId>${o.projectName}</artifactId><version>2.0.0-SNAPSHOT</version></parent><artifactId>${o.projectName}-${module}</artifactId><dependencies>${dependencies}</dependencies>${profiles}${plugin}</project>`;
+}
+
+export async function writeJavaSources(o, put) {
+  const root = o.targetDir;
+  const pkg = o.basePackage;
+  const pp = packagePath(pkg);
+  const generatedAt = generatedAtLocal();
+  await put(root, `client/src/main/java/${pp}/client/query/AnalysisQuery.java`, `package ${pkg}.client.query;\n\nimport lombok.AllArgsConstructor;\nimport lombok.Data;\nimport lombok.NoArgsConstructor;\n\n/** 数据分析分页查询。 */\n@Data\n@NoArgsConstructor\n@AllArgsConstructor\npublic class AnalysisQuery {\n    private int pageNo;\n    private int pageSize;\n    private String sql;\n}`, o.gitAuthor);
+  await put(root, `client/src/main/java/${pp}/client/response/AnalysisResult.java`, `package ${pkg}.client.response;\n\nimport java.util.List;\nimport java.util.Map;\nimport lombok.AllArgsConstructor;\nimport lombok.Data;\nimport lombok.NoArgsConstructor;\n\n/** 数据分析分页结果。 */\n@Data\n@NoArgsConstructor\n@AllArgsConstructor\npublic class AnalysisResult {\n    private int pageNo;\n    private int pageSize;\n    private long total;\n    private List<Map<String, Object>> rows;\n    private String source;\n}`, o.gitAuthor);
+  await put(root, `core/src/main/java/${pp}/core/gateway/AnalysisQueryExecutor.java`, `package ${pkg}.core.gateway;\n\nimport ${pkg}.client.query.AnalysisQuery;\nimport ${pkg}.client.response.AnalysisResult;\n\n/** 数据分析执行接口。 */\npublic interface AnalysisQueryExecutor {\n    AnalysisResult execute(AnalysisQuery query);\n}`, o.gitAuthor);
+  await put(root, `core/src/main/java/${pp}/core/service/AnalysisQueryService.java`, `package ${pkg}.core.service;\n\nimport ${pkg}.client.query.AnalysisQuery;\nimport ${pkg}.client.response.AnalysisResult;\nimport ${pkg}.core.gateway.AnalysisQueryExecutor;\n\n/** 数据分析查询服务。 */\npublic final class AnalysisQueryService {\n    private final AnalysisQueryExecutor analysisQueryExecutor;\n\n    public AnalysisQueryService(AnalysisQueryExecutor analysisQueryExecutor) {\n        this.analysisQueryExecutor = analysisQueryExecutor;\n    }\n\n    public AnalysisResult execute(AnalysisQuery query) {\n        return analysisQueryExecutor.execute(query);\n    }\n}`, o.gitAuthor);
+  await put(root, `adapter/src/main/java/${pp}/adapter/oracle/OracleAnalysisQueryExecutor.java`, `package ${pkg}.adapter.oracle;\n\nimport ${pkg}.client.query.AnalysisQuery;\nimport ${pkg}.client.response.AnalysisResult;\nimport ${pkg}.core.gateway.AnalysisQueryExecutor;\n\n/** Oracle 数据分析执行器占位实现。 */\npublic final class OracleAnalysisQueryExecutor implements AnalysisQueryExecutor {\n    @Override\n    public AnalysisResult execute(AnalysisQuery query) {\n        throw new UnsupportedOperationException("Oracle execution requires an approved vertical slice");\n    }\n}`, o.gitAuthor);
+  if (o.withMock) await put(root, `adapter/src/main/java/${pp}/adapter/mock/MockAnalysisQueryExecutor.java`, `package ${pkg}.adapter.mock;\n\nimport ${pkg}.client.query.AnalysisQuery;\nimport ${pkg}.client.response.AnalysisResult;\nimport ${pkg}.core.gateway.AnalysisQueryExecutor;\nimport java.util.ArrayList;\nimport java.util.HashMap;\nimport java.util.List;\nimport java.util.Map;\n\n/** 本地联调数据分析执行器。 */\npublic final class MockAnalysisQueryExecutor implements AnalysisQueryExecutor {\n    @Override\n    public AnalysisResult execute(AnalysisQuery query) {\n        Map<String, Object> row = new HashMap<String, Object>();\n        row.put("metric", "mock-value");\n        row.put("value", 100);\n        List<Map<String, Object>> rows = new ArrayList<Map<String, Object>>();\n        rows.add(row);\n        return new AnalysisResult(query.getPageNo(), query.getPageSize(), 1, rows, "mock");\n    }\n}`, o.gitAuthor);
+  await put(root, `server/src/main/java/${pp}/Application.java`, `package ${pkg};\n\nimport com.yss.cloud.audit.EnableAuditLog;\nimport com.yss.cloud.cache.EnableYssCloudRedisCache;\nimport com.yss.cloud.excel.annotation.EnableExcelControl;\nimport org.springframework.boot.SpringApplication;\nimport org.springframework.boot.autoconfigure.SpringBootApplication;\nimport org.springframework.cloud.openfeign.EnableFeignClients;\nimport org.springframework.context.annotation.ComponentScan;\nimport org.springframework.context.annotation.FilterType;\n\n/** 数据分析服务启动入口。 */\n@EnableYssCloudRedisCache\n@EnableExcelControl\n@EnableAuditLog\n@EnableFeignClients\n@ComponentScan(\n    value = {"${pkg}", "com.yss.cloud"},\n    excludeFilters = @ComponentScan.Filter(\n        type = FilterType.REGEX,\n        pattern = {"com\\\\.yss\\\\.cloud\\\\.mybatis\\\\..*", "com\\\\.yss\\\\.cloud\\\\.sankuai\\\\..*"}))\n@SpringBootApplication\npublic class Application {\n    public static void main(String[] args) {\n        SpringApplication.run(Application.class, args);\n    }\n}`, o.gitAuthor);
+  await put(root, `server/src/main/java/${pp}/server/configuration/DatabaseInfrastructureConfiguration.java`, `package ${pkg}.server.configuration;\n\nimport com.yss.cloud.EnableDistributedId;\nimport com.yss.cloud.mybatis.config.MapperConfiguration;\nimport org.springframework.context.annotation.Configuration;\nimport org.springframework.context.annotation.Import;\nimport org.springframework.context.annotation.Profile;\n\n/** 数据库及分布式 ID 基础设施配置。 */\n@Configuration\n@Profile("!mock")\n@EnableDistributedId\n@Import(MapperConfiguration.class)\npublic class DatabaseInfrastructureConfiguration {\n}`, o.gitAuthor);
+  const mockImport = o.withMock ? `import ${pkg}.adapter.mock.MockAnalysisQueryExecutor;\n` : "";
+  const mockBean = o.withMock ? `\n    @Bean\n    @Profile("mock")\n    AnalysisQueryExecutor mockAnalysisQueryExecutor() {\n        return new MockAnalysisQueryExecutor();\n    }\n` : "";
+  const databaseRuntimeProfile = o.database === "oceanbase-oracle" ? "oceanbase-oracle" : "oracle";
+  const oracleProfile = o.withMock ? `${databaseRuntimeProfile} & !mock` : databaseRuntimeProfile;
+  await put(root, `server/src/main/java/${pp}/server/configuration/AnalysisConfiguration.java`, `package ${pkg}.server.configuration;\n\n${mockImport}import ${pkg}.adapter.oracle.OracleAnalysisQueryExecutor;\nimport ${pkg}.core.gateway.AnalysisQueryExecutor;\nimport ${pkg}.core.service.AnalysisQueryService;\nimport org.springframework.context.annotation.Bean;\nimport org.springframework.context.annotation.Configuration;\nimport org.springframework.context.annotation.Profile;\n\n/** 数据分析服务 Bean 配置。 */\n@Configuration\npublic class AnalysisConfiguration {${mockBean}\n    @Bean\n    @Profile("${oracleProfile}")\n    AnalysisQueryExecutor oracleAnalysisQueryExecutor() {\n        return new OracleAnalysisQueryExecutor();\n    }\n\n    @Bean\n    AnalysisQueryService analysisQueryService(AnalysisQueryExecutor analysisQueryExecutor) {\n        return new AnalysisQueryService(analysisQueryExecutor);\n    }\n}`, o.gitAuthor);
+  await put(root, `server/src/main/java/${pp}/server/controller/AnalysisController.java`, `package ${pkg}.server.controller;\n\nimport ${pkg}.client.query.AnalysisQuery;\nimport ${pkg}.client.response.AnalysisResult;\nimport ${pkg}.core.service.AnalysisQueryService;\nimport org.springframework.web.bind.annotation.PostMapping;\nimport org.springframework.web.bind.annotation.RequestBody;\nimport org.springframework.web.bind.annotation.RequestMapping;\nimport org.springframework.web.bind.annotation.RestController;\n\n/**\n * 数据分析查询接口。\n *\n * @author system\n * @date ${generatedAt}\n */\n@RestController\n@RequestMapping("/api/analysis")\npublic class AnalysisController {\n    private final AnalysisQueryService analysisQueryService;\n\n    public AnalysisController(AnalysisQueryService analysisQueryService) {\n        this.analysisQueryService = analysisQueryService;\n    }\n\n    /**\n     * 分页查询数据分析结果。\n     *\n     * @author system\n     * @date ${generatedAt}\n     * @param query 数据分析分页查询条件\n     * @return 数据分析分页结果\n     */\n    @PostMapping("/query")\n    public AnalysisResult query(@RequestBody AnalysisQuery query) {\n        return analysisQueryService.execute(query);\n    }\n}`, o.gitAuthor);
+  if (o.withMock) await put(root, `server/src/test/java/${pp}/server/controller/AnalysisControllerTest.java`, `package ${pkg}.server.controller;\n\nimport org.junit.jupiter.api.Test;\nimport org.springframework.beans.factory.annotation.Autowired;\nimport org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;\nimport org.springframework.boot.test.context.SpringBootTest;\nimport org.springframework.test.context.ActiveProfiles;\nimport org.springframework.test.web.servlet.MockMvc;\n\nimport static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;\nimport static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;\nimport static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;\n\n@SpringBootTest\n@AutoConfigureMockMvc\n@ActiveProfiles("mock")\nclass AnalysisControllerTest {\n    @Autowired private MockMvc mockMvc;\n\n    @Test\n    void returnsMockAnalysis() throws Exception {\n        mockMvc.perform(post("/api/analysis/query").contentType("application/json").content("{\\\"pageNo\\\":1,\\\"pageSize\\\":10}"))\n            .andExpect(status().isOk())\n            .andExpect(jsonPath("$.source").value("mock"));\n    }\n}`, o.gitAuthor);
+}

package/template/.claude/skills/yss-mvc-scaffold-generator/scripts/verify_project.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+import { readFile, stat } from "node:fs/promises";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+
+const modules = ["server", "core", "client", "repository", "adapter", "feign-client"];
+const args = process.argv.slice(2); const index = args.indexOf("--project-root");
+if (index < 0 || !args[index + 1]) { console.error("必须提供 --project-root"); process.exit(1); }
+const root = path.resolve(args[index + 1]);
+async function required(relative) { try { await stat(path.join(root, relative)); } catch { throw new Error(`缺少必需路径: ${relative}`); } }
+try {
+  await Promise.all([".git", ".gitignore", ".artifact-workspace.yaml", "yss-project.yaml", "AGENTS.md", "CONTEXT.md", "skills-lock.json", "scripts/check-agent-environment.mjs", "docs/service/service-overview.md", "docs/service/module-map.md", "docs/service/current-capabilities.md", "docs/agents/issue-tracker.md", "docs/process/lifecycle-registry.yaml", "docs/process/harness-process-tailoring.md", "docs/process/implementation-repo-registry.yaml", "docs/templates/approval-record-template.yaml", "docs/templates/implementation-routing-template.md", "docs/templates/verification-record-template.md", "docs/templates/vertical-slice-ticket-template.md", ".yss/scaffold-generation.json"].map(required));
+  const manifest = JSON.parse(await readFile(path.join(root, ".yss/scaffold-generation.json"), "utf8"));
+  if (manifest.skill !== "yss-mvc-scaffold-generator" || !["oracle", "oceanbase-oracle"].includes(manifest.database)) throw new Error("生成清单与 YSS MVC 脚手架合同不一致");
+  if (manifest.runtime_java !== "8" || manifest.project_version !== "2.0.0-SNAPSHOT" || manifest.persistence_profile !== "yss-mybatis-plus") throw new Error("Java 8/YSS MyBatis-Plus 技术基线不正确");
+  const skillUtils = path.resolve(root, manifest.skill_utils_dir);
+  await Promise.all(["skill-utils.yaml", "skills-lock.json", ".agents/skills/yss-product-lifecycle/SKILL.md", ".agents/skills/yss-implementation-contract-compiler/SKILL.md"].map((relative) => required(path.join(manifest.skill_utils_dir, relative))));
+  for (const projection of [".agents", ".claude", ".codex", ".cursor", ".pi", ".qoder", ".trae"]) {
+    const nestedGenerator = path.join(skillUtils, projection, "skills", "yss-mvc-scaffold-generator");
+    if (await stat(nestedGenerator).then(() => true).catch(() => false)) throw new Error(`skillUtils 不应分发创建期生成器: ${projection}/skills/yss-mvc-scaffold-generator`);
+  }
+  for (const forbidden of [".agents", ".claude", ".codex", ".cursor", ".pi", ".qoder", ".trae"]) if (await stat(path.join(root, forbidden)).then(() => true).catch(() => false)) throw new Error(`项目不应携带技能投影目录: ${forbidden}`);
+  if (JSON.stringify(manifest.modules) !== JSON.stringify(modules)) throw new Error("模块集合或顺序不正确");
+  const backendRoot = path.join(root, manifest.backend_root || "");
+  await Promise.all(["pom.xml", "mvnw", "mvnw.cmd", ...modules.map((item) => `${item}/pom.xml`)].map((relative) => required(path.join(manifest.backend_root || "", relative))));
+  const packagePath = manifest.base_package.replaceAll(".", "/");
+  await Promise.all([
+    `server/src/main/java/${packagePath}/Application.java`,
+    `server/src/main/java/${packagePath}/server/controller/AnalysisController.java`,
+    `server/src/main/java/${packagePath}/server/configuration/AnalysisConfiguration.java`,
+    `server/src/main/java/${packagePath}/server/configuration/DatabaseInfrastructureConfiguration.java`,
+    `core/src/main/java/${packagePath}/core/gateway/AnalysisQueryExecutor.java`,
+    `core/src/main/java/${packagePath}/core/service/AnalysisQueryService.java`,
+    `client/src/main/java/${packagePath}/client/query/AnalysisQuery.java`,
+    `client/src/main/java/${packagePath}/client/response/AnalysisResult.java`,
+    `adapter/src/main/java/${packagePath}/adapter/oracle/OracleAnalysisQueryExecutor.java`,
+  ].map(required));
+  const all = await readFile(path.join(backendRoot, "pom.xml"), "utf8");
+  for (const module of modules) if (!all.includes(`<module>${module}</module>`)) throw new Error(`父 POM 未声明模块: ${module}`);
+  for (const expected of ["yss-cloud-microservice", "yss-components-bom", "<java.version>1.8</java.version>", "<version>2.0.0-SNAPSHOT</version>"]) if (!all.includes(expected)) throw new Error(`父 POM 缺少技术基线: ${expected}`);
+  await Promise.all(["server/src/main/resources/bootstrap.yml", "server/src/main/resources/bootstrap-nacos.yml", "server/src/main/resources/application-mock.yml", `server/src/main/resources/application-${manifest.database}.yml`, "server/src/main/resources/logback-spring.xml", "server/src/main/resources/smart-doc.json"].map(required));
+  if (manifest.mock_enabled) await required("server/src/main/resources/bootstrap-mock.yml");
+  const bootstrap = await readFile(path.join(backendRoot, "server/src/main/resources/bootstrap.yml"), "utf8");
+  const databaseProfile = manifest.database === "oceanbase-oracle" ? "oceanbase-oracle" : "oracle";
+  const expectedProfiles = `active: \${app.env:dev},datasource,nacos,${databaseProfile}${manifest.mock_enabled ? ",mock" : ""}`;
+  if (!bootstrap.includes(expectedProfiles) || /mock,\s*$/m.test(bootstrap)) throw new Error("Bootstrap profile 顺序或格式不正确");
+  const bootstrapNacos = await readFile(path.join(backendRoot, "server/src/main/resources/bootstrap-nacos.yml"), "utf8");
+  for (const expected of ["${nacosserver:192.168.165.58:8848}", "${nacos_group:yss-dm}", "enabled: true"]) if (!bootstrapNacos.includes(expected)) throw new Error(`Nacos Bootstrap 配置不完整: ${expected}`);
+  if (manifest.mock_enabled) {
+    const bootstrapMock = await readFile(path.join(backendRoot, "server/src/main/resources/bootstrap-mock.yml"), "utf8");
+    if (!/discovery:\s*\n\s*enabled: false/.test(bootstrapMock) || !/config:\s*\n\s*enabled: false/.test(bootstrapMock)) throw new Error("Mock Bootstrap 未禁用 Nacos Discovery/Config");
+    const applicationMock = await readFile(path.join(backendRoot, "server/src/main/resources/application-mock.yml"), "utf8");
+    if (!/leaf:\s*\n\s*leafSegmentEnable: false\s*\n\s*leafSnowflakeEnable: false/.test(applicationMock)) throw new Error("Mock Profile 未禁用 Leaf Segment/Snowflake");
+  }
+  const serverPom = await readFile(path.join(backendRoot, "server/pom.xml"), "utf8");
+  for (const expected of ["spring-boot-maven-plugin", "smart-doc-maven-plugin", "<id>nacos</id>", "<activeByDefault>true</activeByDefault>", "<app.env>dev</app.env>", "<app.profiles>nacos</app.profiles>", `${manifest.project_name}-client`, `${manifest.project_name}-core`, `${manifest.project_name}-repository`]) {
+    if (!serverPom.includes(expected)) throw new Error(`server POM 缺少标准配置: ${expected}`);
+  }
+  const smartDocPlugin = serverPom.match(/<plugin>(?:(?!<\/plugin>)[\s\S])*?<artifactId>smart-doc-maven-plugin<\/artifactId>(?:(?!<\/plugin>)[\s\S])*?<\/plugin>/)?.[0];
+  if (!smartDocPlugin) throw new Error("server POM 缺少 Smart-doc 人工文档能力");
+  if (smartDocPlugin.includes("<executions>")) throw new Error("Smart-doc 不得绑定 Maven execution");
+  const smartDoc = await readFile(path.join(backendRoot, "server/src/main/resources/smart-doc.json"), "utf8");
+  for (const expected of [`"projectName": "${manifest.project_name}"`, `"packageFilters": "${manifest.base_package}.server.controller.*"`, '"showAuthor": true', '"appToken": ""']) {
+    if (!smartDoc.includes(expected)) throw new Error(`Smart-doc 配置不完整: ${expected}`);
+  }
+  if (/43fd1d4bc1c743c1b83bf4843e8167bf|192\.168\./.test(smartDoc)) throw new Error("Smart-doc 不得携带示例项目的内网地址或 Token");
+  const logback = await readFile(path.join(backendRoot, "server/src/main/resources/logback-spring.xml"), "utf8");
+  for (const expected of ['springProfile name="dev,mock"', 'springProfile name="uat,pro,oracle,oceanbase-oracle"', manifest.base_package, "RollingFileAppender", "<maxFileSize>100MB</maxFileSize>", "<maxHistory>7</maxHistory>"]) {
+    if (!logback.includes(expected)) throw new Error(`Logback 配置不完整: ${expected}`);
+  }
+  const controller = await readFile(path.join(backendRoot, `server/src/main/java/${packagePath}/server/controller/AnalysisController.java`), "utf8");
+  for (const expected of [`@author ${manifest.javadoc_author}`, "@date ", "@param query", "@return "]) if (!controller.includes(expected)) throw new Error(`Controller Javadoc 不完整: ${expected}`);
+  const application = await readFile(path.join(backendRoot, `server/src/main/java/${packagePath}/Application.java`), "utf8");
+  if (application.includes("@EnableDistributedId")) throw new Error("启动类不得在 Mock profile 无条件启用分布式 ID");
+  const databaseInfrastructure = await readFile(path.join(backendRoot, `server/src/main/java/${packagePath}/server/configuration/DatabaseInfrastructureConfiguration.java`), "utf8");
+  for (const expected of ['@Profile("!mock")', "@EnableDistributedId", "@Import(MapperConfiguration.class)"]) if (!databaseInfrastructure.includes(expected)) throw new Error(`数据库基础设施 Profile 隔离不完整: ${expected}`);
+  const configuration = await readFile(path.join(backendRoot, `server/src/main/java/${packagePath}/server/configuration/AnalysisConfiguration.java`), "utf8");
+  const expectedOracleProfile = manifest.mock_enabled ? `@Profile("${databaseProfile} & !mock")` : `@Profile("${databaseProfile}")`;
+  if (!configuration.includes(expectedOracleProfile)) throw new Error("Oracle/Mock 执行器 Profile 隔离不正确");
+  const identity = await readFile(path.join(root, "yss-project.yaml"), "utf8");
+  if (!identity.includes("repository_mode: project-instance")) throw new Error("项目身份不是 project-instance");
+  const registry = await readFile(path.join(root, "docs/process/implementation-repo-registry.yaml"), "utf8");
+  if (/smart-doc(?:-maven-plugin[^\n]*:openapi|-verification\.md|:html|:torna-rest)/i.test(registry)) throw new Error("AI Coding 默认验证不得执行 Smart-doc 或要求其证据");
+  const expectedRegistryLines = [
+    `    project_name: ${manifest.project_name}`,
+    `    project_root: ${manifest.backend_root}`,
+    "    git_root: .",
+    "    repository_scope: external-repository",
+    "      - .",
+  ];
+  for (const line of expectedRegistryLines) {
+    if (!registry.split(/\r?\n/).includes(line)) throw new Error(`实现仓登记与生成清单不一致: ${line.trim()}`);
+  }
+  const gitRoot = spawnSync("git", ["-C", root, "rev-parse", "--show-toplevel"], { encoding: "utf8" });
+  if (gitRoot.status !== 0 || path.resolve(gitRoot.stdout.trim()).toLowerCase() !== root.toLowerCase()) throw new Error("目标目录不是独立 Git 仓库根");
+  const branch = spawnSync("git", ["-C", root, "branch", "--show-current"], { encoding: "utf8" });
+  if (branch.status !== 0 || branch.stdout.trim() !== "main") throw new Error("独立 Git 仓库默认分支不是 main");
+  const commits = spawnSync("git", ["-C", root, "rev-list", "--all", "--count"], { encoding: "utf8" });
+  if (commits.status !== 0 || commits.stdout.trim() !== "0") throw new Error("生成器不得创建 Git commit");
+  const remotes = spawnSync("git", ["-C", root, "remote"], { encoding: "utf8" });
+  if (remotes.status !== 0 || remotes.stdout.trim()) throw new Error("生成器不得配置 Git remote");
+  console.log(`项目结构验证通过：${manifest.project_name}，${modules.length} 个模块，mock=${manifest.mock_enabled}`);
+} catch (error) { console.error(error.message); process.exitCode = 1; }

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

@@ -16,18 +16,18 @@ 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` 传递链路和拦截器是否生效。
 
 ## 源码索引
 
-- 源码位置不要假设固定目录；先按 `yss-source-index/references/source-location.md` 定位。
+- 源码位置不要假设固定目录；先按 `yss-skill-source-index-refresh/references/source-location.md` 定位。
 - 当前技能索引：`references/source-index.md`
 - 重点源码入口通常包括 `BaseRepository`、`BasePlusRepository`、`EntityQueryAspect`、`PageQueryEntityConfigration`、`MybatisBaseConfiguration`、`MybatisPlusConfiguration`、`MultiDataSourceConfiguration`、`MultiDataSourceHolder`。
 
-当组件源码变化后，用 `yss-source-index` 刷新索引；刷新或读取前先按源码定位策略确认真实位置。
+当组件源码变化后，用 `yss-skill-source-index-refresh` 刷新索引；刷新或读取前先按源码定位策略确认真实位置。
 
 ## 实施建议
 
@@ -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/.claude/skills/yss-mybatis/references/source-index.md

@@ -5,7 +5,7 @@ Source commit: `38b556a5081e6c66c0c538cbc1ef839b19996ed3`
 Source worktree: `dirty`
 Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT` to reproduce or refresh.
 
-This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.mjs`. Do not hand-edit generated sections.
+This file is generated by `yss-skill-source-index-refresh/scripts/refresh-yss-skill-index.mjs`. Do not hand-edit generated sections.
 
 Paths below are source path hints captured at refresh time. If they do not exist in the current workspace, locate sources using `YSS_SOURCE_ROOT`, CodeGraph, package/class names, Maven artifact names, or repository search before assuming the source is unavailable.
 

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

@@ -16,13 +16,15 @@ description: 编排 YSS 产品或模块从机会调研到 Spec、原型、技术
 
 Matt 的 `grill-with-docs`、`to-spec`、`to-tickets`、`implement` 等保留为显式兼容入口；默认路径是本 skill 持有的原生工作单元，由本编排器创建正式资产、维护状态并在会签门禁暂停（级别见数字人角色注册表）。兼容入口不得自动调用它们或代替其创建正式资产；Matt 只导航，不得写生命周期资产或改变门禁/Ticket 状态；任何写入前回交本编排器。
 
-技能调用先消费 `docs/agents/yss-skill-registry.yaml` 的 `invocation_contract`：它只约束调用模式、触发/排除条件、主要输出和依赖，不替代生命周期证据或门禁。进入实现后，Slice Contract 的 `common.context_plan` 只加载当前切片的最小充分上下文；缺失权威上下文必须 `blocked` 或回 Router，不得猜测补齐。质量标准由 `engineering-baseline` 一次定义并由切片、Execution Result、审查和发布复用；命中高风险影响时在途记录 Doubt-Driven 主张、反证、证据和残余风险。Wayfinder 仅作为超长或决策前沿不清晰工作的可选 Discovery → Spec 规划模式，完成后回到 `handoff → to-spec`，不改变生命周期状态。
+技能调用先消费 `docs/agents/yss-skill-registry.yaml` 的 `invocation_contract`：它只约束调用模式、触发/排除条件、主要输出和依赖，不替代生命周期证据或门禁。进入实现后，Slice Contract 的 `common.context_plan` 只加载当前切片的最小充分上下文；缺失权威上下文必须 `blocked` 或回 实现合同编译器，不得猜测补齐。质量标准由 `engineering-baseline` 一次定义并由切片、Execution Result、审查和发布复用；命中高风险影响时在途记录 Doubt-Driven 主张、反证、证据和残余风险。Wayfinder 仅作为超长或决策前沿不清晰工作的可选 Discovery → Spec 规划模式，完成后回到 `handoff → to-spec`，不改变生命周期状态。
 
 ## 不可裁剪的主链
 
+新后端工程先按注册表选择 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,44 @@ 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` | 交互说明、低保真、状态矩阵、高保真 HTML、评审记录 | `work-unit.prototype-design`；`yss-prototype-stage` 为主合同，依次消费 `yss-design-system`、独立 `prototype-review`、`yss-antd-design` pre-build facts、Codex `product-design:index` focused workflow、post-build/浏览器/无障碍验证（非 Codex 交付等价合同）。前端落地改用 `yss-ui` | `gate.prototype-reviewed`、`gate.prototype-verified`、`gate.user-confirmation` 均有 schema v2 证据 |
-| 系统 / 数据架构与工程契约 `stage.system-data-engineering` | OpenAPI Draft/Freeze、数据架构、工程基线、架构审查；按领域影响执行 Tactical DDD Check | `work-unit.technical-analysis`；`yss-router` + `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-router`；`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-router` + `tdd`；前端按 `yss-ui` + `yss-page-module-development`，后端按 Router 最小闭包；`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 回 Router）；同一候选快照通过全部审查轴、专项覆盖与验证；UI 影响追加 `gate.frontend-implementation-verified`；`gate.release-ready` 仍须生物人 |
+| 产品设计 `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-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。
+原型通过不等于前端实现通过。`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/.claude/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 锚点绕过。