create-yss-spec 3.0.0 → 3.1.0

package/template/.pi/skills/yss-layered-mvc-scaffold-generator/scripts/scaffold-generator.test.mjs

@@ -0,0 +1,159 @@
+import { attachScaffoldDecisionFixture } from "../../../../scripts/fixtures/user-decision/build-fixture.mjs";
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { mkdtemp, mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+const script = path.join(path.dirname(fileURLToPath(import.meta.url)), "generate_scaffold.mjs");
+const digest = (value) => `sha256:${createHash("sha256").update(value).digest("hex")}`;
+const capabilityModules = {
+  basic: { capabilities: [], modules: ["server", "service", "repository"] },
+  adapter: { capabilities: ["external-integration"], modules: ["server", "service", "repository", "adapter"] },
+  client: { capabilities: ["published-client"], modules: ["server", "service", "repository", "client"] },
+  feign: { capabilities: ["feign-client"], modules: ["server", "service", "repository", "client", "feign-client"] },
+  combined: { capabilities: ["external-integration", "feign-client"], modules: ["server", "service", "repository", "adapter", "client", "feign-client"] }
+};
+
+async function fixture(t, { profile = capabilityModules.basic, architectureProfile = "layered-mvc-service", skillId = "yss-layered-mvc-scaffold-generator" } = {}) {
+  const root = await mkdtemp(path.join(os.tmpdir(), "yss-layered-mvc-"));
+  t.after(() => rm(root, { recursive: true, force: true }));
+  const output = path.join(root, "backend");
+  await mkdir(output);
+  let decisionText = `${JSON.stringify({ schema_version: 1, kind: "scaffold-architecture-decisions", template: false, status: "current", decisions: [{ decision_id: "scaffold-decision.demo-service", project_id: "demo-service", parent_project_id: null, status: "lifecycle-approved", recommended_architecture: "layered-mvc", recommendation_reasons: ["薄 CRUD 服务"], confirmed_architecture: "layered-mvc", override_reason: null, inheritance_mode: "root-default", inherited_from: null, platform_profile: "spring-boot-2.7-jdk8", architecture_profile: architectureProfile, verification_database: "h2", production_database: "not-bound", requested_capabilities: profile.capabilities, resolved_modules: profile.modules, resolution_version: 1, user_confirmation: { confirmed_by: "tester", channel: "test", confirmation_ref: "test://confirmation", confirmed_at: "2026-09-05T00:00:00Z", normalized_text: "确认使用 MVC" }, decision_inputs_digest: `sha256:${"1".repeat(64)}` }] }, null, 2)}\n`;
+  const decisionSet = JSON.parse(decisionText);
+  decisionSet.decisions = decisionSet.decisions.map((decision) => attachScaffoldDecisionFixture(path.join(root, "user-decision"), decision));
+  decisionText = JSON.stringify(decisionSet, null, 2) + "\n";
+  const decisionFile = path.join(root, "scaffold-architecture-decisions.yaml");
+  await writeFile(decisionFile, decisionText);
+  const contract = {
+    schema_version: 3,
+    contract_id: "scaffold.demo-service.v1",
+    contract_version: 1,
+    scaffold_request_id: "request.demo-service",
+    status: "approved",
+    compiler_draft_ref: "compiler://demo/1",
+    lifecycle_approval_ref: "approval://demo/1",
+    persisted_ref: "contract://demo/1",
+    current_version: 1,
+    implementation_repository: "external",
+    backend_repository: "external",
+    scaffold_status: "required",
+    project_name: "demo-service",
+    target_output_dir: output,
+    base_package: "com.yss.demo",
+    architecture_family: "layered-mvc", architecture_profile: architectureProfile,
+    generator_skill: skillId,
+    decision_ref: decisionFile,
+    decision_id: "scaffold-decision.demo-service",
+    decision_digest: digest(decisionText),
+    maven_coordinates: { group_id: "com.yss.demo", project_version: "1.0.0-SNAPSHOT", parent: { group_id: "com.yss.cloud", artifact_id: "yss-cloud-microservice", version: "2.0.0-SNAPSHOT" }, yss_components_version: "2.0.0-SNAPSHOT" },
+    profiles: { architecture: "layered-mvc", persistence: "mybatis-plus", verification_database: "h2", production_database: "not-bound", platform: "spring-boot-2.7-jdk8", validation_namespace: "javax", repository: "yss-internal" },
+    module_profile: { requested_capabilities: profile.capabilities, resolved_modules: profile.modules, resolution_version: 1 },
+    allowed_write_paths: ["."],
+    expected_evidence_files: [".yss/scaffold-generation.json"],
+    verification_commands: ["./mvnw validate", "./mvnw test", "./mvnw package"],
+    approval: { approval_ref: "approval://demo/1", approver: "lifecycle", persisted_ref: "contract://demo/1", current_version: 1 },
+    work_unit: { id: "scaffold.demo", behavior: "project-scaffold", primary_skill: skillId, supporting_skills: ["yss-implementation-contract-compiler"], tdd_mode: "controlled-generation", allowed_write_paths: ["."], expected_evidence: [".yss/scaffold-generation.json"], verification_commands: ["./mvnw validate", "./mvnw test", "./mvnw package"], controlled_generation: true },
+    generation_policy: { mode: "initialize-only", existing_target: "unsupported", old_project_migration: "unsupported", template_upgrade: "unsupported" }
+  };
+  const contractFile = path.join(root, "contract.json");
+  await writeFile(contractFile, `${JSON.stringify(contract, null, 2)}\n`);
+  const args = ["--project-name", "demo-service", "--base-package", "com.yss.demo", "--output-dir", output, "--contract-file", contractFile, "--contract-id", contract.contract_id, "--contract-version", "1", "--approval-ref", contract.lifecycle_approval_ref, "--compiler-draft-ref", contract.compiler_draft_ref, "--persisted-ref", contract.persisted_ref, "--group-id", "com.yss.demo", "--project-version", "1.0.0-SNAPSHOT", "--parent-group-id", "com.yss.cloud", "--parent-artifact-id", "yss-cloud-microservice", "--parent-version", "2.0.0-SNAPSHOT", "--yss-components-version", "2.0.0-SNAPSHOT"];
+  return { root, output, decisionFile, contractFile, contract, args, project: path.join(output, "demo-service") };
+}
+
+test("数据分析初始化生成 H2 六模块和独立治理信封", async (t) => {
+  const skillId = "yss-mvc-data-analysis-project-initializer";
+  const data = await fixture(t, { architectureProfile: "mvc-data-analysis-v1", skillId, profile: { capabilities: [], modules: ["server", "core", "client", "repository", "adapter", "feign-client"] } });
+  const context = "---\ncontext_schema_version: 1\n---\n# 业务上下文\n\n## 业务术语\n\n| 术语 | 含义 | 英文标识 | 适用业务责任区 | 避免 / 备注 |\n|---|---|---|---|---|\n";
+  await writeFile(path.join(data.root, "context-handoff.md"), context);
+  data.contract.context_handoff_ref = "context-handoff.md";
+  data.contract.context_handoff_digest = digest(context);
+  await writeFile(data.contractFile, JSON.stringify(data.contract));
+  const initializer = path.resolve(path.dirname(script), `../../${skillId}/scripts/generate_project.mjs`);
+  const result = spawnSync(process.execPath, [initializer, ...data.args], { encoding: "utf8" });
+  assert.equal(result.status, 0, result.stderr);
+  const manifest = JSON.parse(await readFile(path.join(data.project, ".yss/scaffold-generation.json"), "utf8"));
+  assert.equal(manifest.architecture_identity.architecture_profile, "mvc-data-analysis-v1");
+  assert.equal(manifest.generator_skill, skillId);
+  assert.equal(await readFile(path.join(data.project, "CONTEXT.md"), "utf8"), context);
+  await stat(path.join(data.project, ".git"));
+  await stat(path.join(data.output, "skillUtils/skills-lock.json"));
+  assert.ok(!manifest.ownership.generated_files.some((entry) => entry.path.startsWith(".git/")));
+  const core = await readFile(path.join(data.project, "demo-service-core/pom.xml"), "utf8");
+  assert.doesNotMatch(core, /demo-service-client|spring-web|ojdbc|mysql-connector/);
+});
+
+test("旧数据库和 Mock 参数在写入前被拒绝", async (t) => {
+  const data = await fixture(t);
+  for (const args of [["--database", "mysql"], ["--with-mock"]]) {
+    const result = spawnSync(process.execPath, [script, ...data.args, ...args], { encoding: "utf8" });
+    assert.notEqual(result.status, 0);
+    await assert.rejects(stat(data.project), { code: "ENOENT" });
+  }
+});
+
+test("可选离线 Maven 可行性检查（不替代受控仓库验收）", { skip: process.env.YSS_BACKEND_OFFLINE_PROBE !== "1" }, async (t) => {
+  const data = await fixture(t);
+  const generated = spawnSync(process.execPath, [script, ...data.args], { encoding: "utf8" });
+  assert.equal(generated.status, 0, generated.stderr);
+  for (const phase of ["validate", "test", "package"]) {
+    const result = spawnSync(path.join(data.project, "mvnw"), ["-o", phase], { cwd: data.project, encoding: "utf8", timeout: 60_000 });
+    t.diagnostic(`./mvnw -o ${phase}: exit=${result.status}; ${result.error?.message ?? ""}`);
+    assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
+  }
+});
+
+for (const database of ["h2"]) {
+  test(`生成 ${database} 基础 Profile`, async (t) => {
+    const data = await fixture(t, { database });
+    const result = spawnSync(process.execPath, [script, ...data.args], { encoding: "utf8" });
+    assert.equal(result.status, 0, result.stderr);
+    const manifest = JSON.parse(await readFile(path.join(data.project, ".yss/scaffold-generation.json"), "utf8"));
+    assert.equal(manifest.schema_version, 3);
+    assert.equal(manifest.architecture_family, "layered-mvc");
+    assert.equal(manifest.profiles.verification_database, database);
+    assert.equal(manifest.profiles.production_database, "not-bound");
+    assert.equal(manifest.architecture_identity.architecture_profile, "layered-mvc-service");
+    const config = await readFile(path.join(data.project, "demo-service-server/src/main/resources/application.yml"), "utf8");
+    assert.doesNotMatch(config, /datasource|profiles|jdbc:/);
+    const local = await readFile(path.join(data.project, "demo-service-server/src/main/resources/application-scaffold-local.yml"), "utf8");
+    assert.match(local, /jdbc:h2:mem:/);
+    assert.deepEqual(manifest.module_profile.resolved_modules, capabilityModules.basic.modules);
+    await stat(path.join(data.project, "demo-service-server/src/main/java/com/yss/demo/DemoServiceApplication.java"));
+    await assert.rejects(stat(path.join(data.project, "demo-service-server/src/main/java/com/yss/demo/server/controller")), { code: "ENOENT" });
+  });
+}
+
+for (const [name, profile] of Object.entries(capabilityModules)) {
+  test(`能力闭包 ${name}`, async (t) => {
+    const data = await fixture(t, { profile });
+    const result = spawnSync(process.execPath, [script, ...data.args], { encoding: "utf8" });
+    assert.equal(result.status, 0, result.stderr);
+    const pom = await readFile(path.join(data.project, "pom.xml"), "utf8");
+    for (const module of profile.modules) assert.match(pom, new RegExp(`<module>demo-service-${module}</module>`));
+    for (const module of ["adapter", "client", "feign-client"].filter((item) => !profile.modules.includes(item))) assert.doesNotMatch(pom, new RegExp(`<module>demo-service-${module}</module>`));
+  });
+}
+
+test("选择缺失、digest 漂移和非空目标均阻断", async (t) => {
+  const missing = await fixture(t);
+  missing.contract.decision_id = "decision.missing";
+  await writeFile(missing.contractFile, `${JSON.stringify(missing.contract)}\n`);
+  assert.notEqual(spawnSync(process.execPath, [script, ...missing.args], { encoding: "utf8" }).status, 0);
+
+  const drift = await fixture(t);
+  drift.contract.decision_digest = `sha256:${"0".repeat(64)}`;
+  await writeFile(drift.contractFile, `${JSON.stringify(drift.contract)}\n`);
+  assert.notEqual(spawnSync(process.execPath, [script, ...drift.args], { encoding: "utf8" }).status, 0);
+
+  const existing = await fixture(t);
+  await mkdir(existing.project);
+  const blocked = spawnSync(process.execPath, [script, ...existing.args], { encoding: "utf8" });
+  assert.notEqual(blocked.status, 0);
+  assert.match(blocked.stderr, /目标已存在/);
+});

package/template/.pi/skills/yss-mvc-data-analysis-project-initializer/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: yss-mvc-data-analysis-project-initializer
+description: 在生命周期批准的初始化合同下创建独立 Git 管理的数据分析 project-instance；固定 mvc-data-analysis-v1 六模块、Java 8 和本地测试 H2。
+---
+
+# 数据分析 MVC 项目初始化
+
+这是 `work-unit.service-project-initialization` 的执行器，不是通用 MVC 脚手架。通用 MVC 使用 `yss-layered-mvc-scaffold-generator`；DDD 使用 `yss-ddd-scaffold-generator`。旧 `yss-mvc-scaffold-generator` 已退役且不提供自动别名。
+
+## 执行合同
+
+- 必须有生命周期批准且当前的 schema v3 scaffold contract，绑定 `architecture_profile=mvc-data-analysis-v1`、本生成器及已批准的架构决策。
+- 固定 server/core/client/repository/adapter/feign-client；core 是薄应用层，规则见 `docs/agents/backend-architecture-profiles.md`。不生成业务接口、SQL、DDL、Mock、生产数据库配置或额外数据源。
+- `verification_database=h2` / `production_database=not-bound`；Java 8 / Boot 2.7 / javax。目标不存在，禁止覆盖、迁移、自动提交和推送。
+- 合同必须包含 `context_handoff_ref`、`context_handoff_digest`：批准交接的完整根 CONTEXT.md（含 schema frontmatter），不得用跨仓路径替代本仓词汇表。初始化只复制已确认内容，不创造业务术语；父项目只保留服务引用和 handoff 证据。
+- `allowed_write_paths` 必须覆盖目标项目及同级 skillUtils。已有 skillUtils 锁不匹配即 blocked，不替换别的项目正在使用的工具包。
+
+## 命令与结果
+
+`node scripts/generate_project.mjs` 使用通用 MVC 生成器相同的批准合同与 Maven 坐标参数（`--output-dir` 是父容器）；无 `--database`、`--with-mock` 或交互选项。
+
+输出独立 project-instance、初始化但未提交的 main Git、生命周期资产、完整锁定 skillUtils、架构身份及 Manifest。使用共享 `run_scaffold_verification.mjs <project> <evidence>` 实跑三条 Wrapper 命令；只在实际成功后报告 empty-scaffold-verified。Profile 仍须独立首切片 fixture 达标才能晋升 supported。

package/template/.pi/skills/yss-mvc-data-analysis-project-initializer/scripts/generate_project.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { cp, lstat, mkdir, mkdtemp, readFile, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { generate, parseArgs } from "../../yss-layered-mvc-scaffold-generator/scripts/generate_scaffold.mjs";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../..");
+const skillId = "yss-mvc-data-analysis-project-initializer";
+const digest = (value) => `sha256:${createHash("sha256").update(value).digest("hex")}`;
+async function present(target) { try { await lstat(target); return true; } catch (error) { if (error.code === "ENOENT") return false; throw error; } }
+async function put(target, text) { await mkdir(path.dirname(target), { recursive: true }); await writeFile(target, `${text.trimEnd()}\n`); }
+function within(parent, target) { const relative = path.relative(parent, target); return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative)); }
+
+async function sharedTools(outputDir, contract) {
+  const destination = path.join(outputDir, "skillUtils");
+  if (!contract.allowed_write_paths.some((item) => within(path.resolve(outputDir, item), destination))) throw new Error("skillUtils 不在批准写范围内");
+  const lock = await readFile(path.join(root, "skills-lock.json"));
+  if (await present(destination)) {
+    if (!await present(path.join(destination, "skill-utils.yaml")) || !lock.equals(await readFile(path.join(destination, "skills-lock.json")))) throw new Error("已有 skillUtils 不匹配；须独立批准刷新，初始化不会覆盖");
+    return digest(lock);
+  }
+  const staging = await mkdtemp(path.join(outputDir, ".skillUtils.staging-"));
+  try {
+    for (const relative of [".agents/skills", ".codex/skills", ".claude/skills", ".cursor/skills", ".pi/skills", ".qoder/skills", ".trae/skills", "scripts", "docs/agents", "docs/process", "AGENTS.md", "skills-lock.json"]) {
+      await mkdir(path.dirname(path.join(staging, relative)), { recursive: true });
+      await cp(path.join(root, relative), path.join(staging, relative), { recursive: true });
+    }
+    await put(path.join(staging, "skill-utils.yaml"), "schema_version: 1\nkind: yss-skill-utils\ncompatibility: skill-utils-v1\ncanonical_root: .agents/skills");
+    await rename(staging, destination);
+  } catch (error) { await rm(staging, { recursive: true, force: true }); throw error; }
+  return digest(lock);
+}
+
+export async function initialize(options) {
+  // Shared generation validates approval, decision, target and write scope before invoking this callback.
+  return generate(options, { skillId, architectureProfile: "mvc-data-analysis-v1", finalize: async ({ projectRoot, contract, architectureIdentity }) => {
+    if (!contract.context_handoff_ref || !contract.context_handoff_digest) throw new Error("缺少批准的 context_handoff_ref/context_handoff_digest");
+    const handoffPath = path.resolve(path.dirname(path.resolve(options.contractFile)), contract.context_handoff_ref);
+    const context = await readFile(handoffPath);
+    if (digest(context) !== contract.context_handoff_digest || !/^---\r?\ncontext_schema_version: 1\r?\n---/m.test(context.toString())) throw new Error("CONTEXT handoff schema/digest 不匹配");
+    if (spawnSync("git", ["--version"]).status !== 0) throw new Error("Git 不可用");
+    for (const relative of ["docs/agents", "docs/process", "docs/templates", "docs/architecture/templates"]) {
+      await mkdir(path.dirname(path.join(projectRoot, relative)), { recursive: true });
+      await cp(path.join(root, relative), path.join(projectRoot, relative), { recursive: true });
+    }
+    await put(path.join(projectRoot, "CONTEXT.md"), context.toString());
+    const agents = (await readFile(path.join(root, "AGENTS.md"), "utf8"))
+      .replace(/## 4\. `template-source` 模板维护路由[\s\S]*?(?=## 5\.)/, "## 4. 模板维护\n\n本仓为 project-instance；模板维护回上游执行。\n\n")
+      .replaceAll(".agents/skills", "../skillUtils/.agents/skills");
+    await put(path.join(projectRoot, "AGENTS.md"), agents);
+    await put(path.join(projectRoot, "yss-project.yaml"), "schema_version: 1\nrepository_mode: project-instance");
+    await put(path.join(projectRoot, ".artifact-workspace.yaml"), `schema_version: 1\nkind: service\nservice_id: ${options.projectName}`);
+    await cp(path.join(root, "scripts/lib"), path.join(projectRoot, "scripts/lib"), { recursive: true });
+    await cp(path.join(root, "scripts/vendor"), path.join(projectRoot, "scripts/vendor"), { recursive: true });
+    for (const name of ["repository-mode", "implementation-path-policy", "repository-scope-policy", "generate-lifecycle-artifacts", "node-generate-lifecycle-artifacts.mjs", "verify-lifecycle-registry", "node-verify-lifecycle-registry.mjs", "verify-lifecycle-checkpoint", "verify-context-reconciliation", "verify-approval-record", "verify-user-decision", "verify-digital-human-task-package", "verify-yss-dto-openapi-profile", "verify-frontend-implementation-evidence"]) {
+      await cp(path.join(root, "scripts", name), path.join(projectRoot, "scripts", name));
+    }
+    const lockDigest = await sharedTools(path.resolve(options.outputDir), contract);
+    await put(path.join(projectRoot, "skills-lock.json"), JSON.stringify({ version: 1, distribution: { mode: "sibling-directory", skillUtilsDir: "../skillUtils", required: true, compatibility: "skill-utils-v1", lock_digest: lockDigest } }, null, 2));
+    await put(path.join(projectRoot, "docs/process/engineering-baseline.json"), JSON.stringify({ schema_version: 1, architecture_identity: architectureIdentity, platform_profile: contract.profiles.platform, scaffold_completion: "generated" }, null, 2));
+    await put(path.join(projectRoot, "docs/process/implementation-repo-registry.yaml"), JSON.stringify({ schema_version: 1, projects: [{ project_type: "backend", project_name: options.projectName, project_root: ".", git_root: ".", repository_scope: "external-repository", scaffold_status: "initialized", default_branch: "main", architecture_identity: architectureIdentity, allowed_write_paths: ["."], verification_commands: contract.verification_commands, expected_evidence_files: contract.expected_evidence_files, ci: "not-configured", rollback_point: "initial-empty-repository" }] }, null, 2));
+    await put(path.join(projectRoot, "docs/process/service-initialization.json"), JSON.stringify({ work_unit: "work-unit.service-project-initialization", context_handoff_ref: contract.context_handoff_ref, context_handoff_digest: contract.context_handoff_digest, contract_id: contract.contract_id, architecture_identity: architectureIdentity, status: "generated" }, null, 2));
+    await put(path.join(projectRoot, ".gitignore"), "target/\n**/target/\n.idea/\n*.iml\n.env\n.env.*\n.local/");
+    const git = spawnSync("git", ["init", "--initial-branch=main"], { cwd: projectRoot, encoding: "utf8" });
+    if (git.status !== 0) throw new Error(`Git 初始化失败: ${git.stderr}`);
+  } });
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  try {
+    const options = parseArgs(process.argv.slice(2));
+    if (options.help) process.stdout.write("使用批准的 MVC schema v3 合同与 Maven 坐标参数；输出独立数据分析项目，无数据库/Mock 选项。\n");
+    else await initialize(options);
+  } catch (error) { process.stderr.write(`数据分析项目初始化失败: ${error.message}\n`); process.exitCode = 1; }
+}

package/template/.pi/skills/yss-mvc-data-analysis-project-initializer/scripts/run_scaffold_verification.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { run } from "../../yss-ddd-scaffold-generator/scripts/run_scaffold_verification.mjs";
+try {
+  const [projectRoot, evidenceDir] = process.argv.slice(2);
+  if (!projectRoot || !evidenceDir) throw new Error("用法: run_scaffold_verification.mjs <project-root> <evidence-dir>");
+  const report = await run(projectRoot, evidenceDir);
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  process.exitCode = report.status === "passed" ? 0 : 1;
+} catch (error) { process.stderr.write(`${error.message}\n`); process.exitCode = 1; }

package/template/.pi/skills/yss-mvc-scaffold-generator/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: yss-mvc-scaffold-generator
+description: 已退役的数据分析 MVC 初始化旧入口；仅用于识别历史合同并指引重新批准，不执行生成或自动迁移。
+---
+
+# 已退役入口
+
+本 ID 为 deprecated，只读保留历史合同解释。通用 MVC 使用 yss-layered-mvc-scaffold-generator；独立数据分析项目使用 yss-mvc-data-analysis-project-initializer。旧 Oracle/Mock 合同不得静默别名或重放；经生命周期确认 Profile 与 H2 新合同后才执行新入口。历史说明位于 references/history/skill.md，不是现行执行规范。

package/template/.pi/skills/yss-mvc-scaffold-generator/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "YSS MVC Scaffold Generator"
+  short_description: "初始化独立 Git 的 YSS MVC 数据分析项目实例"
+  default_prompt: "Use $yss-mvc-scaffold-generator to initialize an independent Git-managed YSS MVC data-analysis project-instance with six Oracle backend modules and a mock HTTP profile."

package/template/.pi/skills/yss-mvc-scaffold-generator/assets/logback-spring.xml.template

@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<configuration>
+  <include resource="org/springframework/boot/logging/logback/defaults.xml"/>
+  <include resource="org/springframework/boot/logging/logback/console-appender.xml"/>
+
+  <property name="CONSOLE_LOG_PATTERN"
+            value="%clr(%d{yyyy-MM-dd HH:mm:ss.SSS}){faint} %clr(${LOG_LEVEL_PATTERN:-%5p}) %clr(${PID:- }){magenta} %clr(---){faint} %clr([%15.15t]){faint} %clr(%-40.40logger{39}){cyan} %clr(:){faint} %m%n${LOG_EXCEPTION_CONVERSION_WORD:-%wEx}"/>
+  <springProperty name="APP_NAME" scope="context" source="spring.application.name" defaultValue="{{PROJECT_NAME}}"/>
+  <springProperty name="LOG_PATH" scope="context" source="logging.file.path" defaultValue="logs"/>
+
+  <springProfile name="dev,mock">
+    <logger level="DEBUG" name="org.apache.ibatis"/>
+    <logger level="DEBUG" name="{{BASE_PACKAGE}}"/>
+    <root level="INFO">
+      <appender-ref ref="CONSOLE"/>
+    </root>
+  </springProfile>
+
+  <springProfile name="uat,pro,oracle,oceanbase-oracle">
+    <logger level="INFO" name="org.apache.ibatis"/>
+    <logger level="INFO" name="com.yss.cloud.log"/>
+    <logger level="INFO" name="com.yss.cloud.breaker"/>
+    <logger level="INFO" name="com.yss.cloud.exception"/>
+    <logger level="INFO" name="{{BASE_PACKAGE}}"/>
+    <logger level="INFO" name="com.alibaba"/>
+    <logger level="INFO" name="org.apache.commons"/>
+    <logger level="INFO" name="org.springframework"/>
+    <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
+      <encoder>
+        <pattern>%d{yy-MM-dd.HH:mm:ss.SSS} [%-16t] %-5p %-22c{0} - %m%n</pattern>
+      </encoder>
+      <prudent>true</prudent>
+      <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
+        <fileNamePattern>${LOG_PATH}/${APP_NAME}_%d{yyyyMMdd}_%i.log</fileNamePattern>
+        <maxHistory>7</maxHistory>
+        <timeBasedFileNamingAndTriggeringPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedFNATP">
+          <maxFileSize>100MB</maxFileSize>
+        </timeBasedFileNamingAndTriggeringPolicy>
+      </rollingPolicy>
+    </appender>
+    <root level="INFO">
+      <appender-ref ref="FILE"/>
+      <appender-ref ref="CONSOLE"/>
+    </root>
+  </springProfile>
+
+  <root level="INFO">
+    <appender-ref ref="CONSOLE"/>
+  </root>
+</configuration>

package/template/.pi/skills/yss-mvc-scaffold-generator/assets/smart-doc.json.template

@@ -0,0 +1,42 @@
+{
+  "serverUrl": "http://localhost:8080",
+  "pathPrefix": "",
+  "isStrict": true,
+  "allInOne": true,
+  "outPath": "target/openapi",
+  "coverOld": true,
+  "createDebugPage": true,
+  "packageFilters": "{{BASE_PACKAGE}}.server.controller.*",
+  "md5EncryptedHtmlName": false,
+  "style": "xt256",
+  "projectName": "{{PROJECT_NAME}}",
+  "skipTransientField": true,
+  "sortByTitle": false,
+  "ignoreRequestParams": [
+    "com.yss.cloud.excel.annotation.RequestExcel",
+    "com.yss.cloud.excel.ExcelDataRequest"
+  ],
+  "showAuthor": true,
+  "requestFieldToUnderline": false,
+  "responseFieldToUnderline": false,
+  "inlineEnum": true,
+  "recursionLimit": 7,
+  "allInOneDocFileName": "{{PROJECT_NAME}}-v2.0.0",
+  "requestExample": true,
+  "responseExample": true,
+  "displayActualType": false,
+  "componentType": "NORMAL",
+  "appToken": "",
+  "openUrl": "",
+  "debugEnvName": "local",
+  "debugEnvUrl": "http://localhost:8080",
+  "revisionLogs": [
+    {
+      "version": "2.0.0",
+      "revisionTime": "{{GENERATED_AT}}",
+      "status": "create",
+      "author": "system",
+      "remarks": "项目初始化版本v2.0.0"
+    }
+  ]
+}

package/template/.pi/skills/yss-mvc-scaffold-generator/references/architecture.md

@@ -0,0 +1,28 @@
+# 固定架构
+
+| 模块 | 职责 |
+|---|---|
+| `client` | HTTP DTO 与稳定调用契约 |
+| `core` | 查询用例和 `AnalysisQueryExecutor` seam |
+| `repository` | 查询定义、元数据和后续持久化扩展 |
+| `adapter` | Oracle 与 Mock 执行器实现 |
+| `feign-client` | 面向其他服务的客户端契约扩展点 |
+| `server` | Spring Boot 装配和 REST Controller |
+
+依赖方向：
+
+```text
+server -> core + adapter + client
+core -> client
+repository -> client
+adapter -> core + client
+feign-client -> client
+```
+
+`core` 不依赖 Spring MVC、Oracle 驱动或具体数据源。Mock 和 Oracle 不能形成两套 HTTP 接口；二者只在 `AnalysisQueryExecutor` 的实现与 Profile 上不同。
+
+## 项目边界
+
+`target-dir` 同时是 `project-instance`、独立 Git 根和 Maven 聚合项目根。六个模块直接位于项目根；模板工具仓库只提供生成器；每个生成项目自行持有生命周期事实源、共享 skills、业务上下文、草案目录及 `external-repository` 实现仓库登记。Git 初始化只建立 `main` 分支，不创建 commit、remote 或跨项目父仓关系。
+
+工程基线固定为 Java 8、项目版本 `2.0.0-SNAPSHOT`、`com.yss.cloud:yss-cloud-microservice:2.0.0-SNAPSHOT` 父 POM 和同版本 `yss-components-bom`。标准预设包含审计、分布式 ID、Excel、Nacos、Redis Cache、OpenFeign、Smart-doc、Userinfo、Actuator 与 Mock；持久层使用 YSS MyBatis-Plus，数据库在 Oracle 与 OceanBase Oracle 中选择且驱动互斥。Smart-doc 只是人工按需生成 Controller 辅助文档的工具，不绑定 Maven 生命周期，不进入默认 AI Coding 验证链路，也不替代冻结的 OpenAPI 3.1 YAML。

package/template/.pi/skills/yss-mvc-scaffold-generator/references/history/generate_project.mjs.txt

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+// Historical source only; not an executable entrypoint.
+/** YSS MVC 脚手架编排入口；参数、文件、模板和项目治理分别位于 scripts/lib。 */
+import { cp, mkdir, mkdtemp, rename, rm, rmdir } from "node:fs/promises";
+import path from "node:path";
+
+import {
+  MODULES,
+  SHARED_SKILLS_ROOT,
+  fail,
+  parseArgs,
+  assertGitAvailable,
+  resolveGitAuthor,
+  resolveMavenSettings,
+  initializeGit,
+  exists,
+} from "./lib/runtime.mjs";
+import { assertEmpty, ensureSkillUtils, put, renderAsset } from "./lib/storage.mjs";
+import { writeProjectEnvelope } from "./lib/envelope.mjs";
+import { modulePom, parentPom, writeJavaSources } from "./lib/templates.mjs";
+
+const SKILL_ID = "yss-mvc-scaffold-generator";
+let generatedJavadocAuthor;
+
+function usage() {
+  console.log(`YSS MVC 脚手架生成器\n\n用法: node scripts/generate_project.mjs --project-name <name> --base-package <package> --target-dir <dir> [选项]\n\n选项: --database oracle|oceanbase-oracle --with-mock --maven-settings <path> --dry-run`);
+}
+
+async function writeGenerated(root, relative, content) {
+  await put(root, relative, content, generatedJavadocAuthor);
+}
+
+async function copyWrapper(root) {
+  const source = path.join(SHARED_SKILLS_ROOT, "yss-ddd-scaffold-generator", "assets", "wrapper");
+  if (!await exists(source)) fail(`Maven Wrapper 资产不存在: ${source}`);
+  await cp(source, root, { recursive: true });
+}
+
+function buildPlan(o, skillUtils, mavenSettings) {
+  const driver = o.database === "oceanbase-oracle" ? "com.oceanbase:oceanbase-client:2.4.3" : "com.oracle.database.jdbc:ojdbc8:19.8.0.0";
+  return {
+    project_name: o.projectName,
+    project_version: "2.0.0-SNAPSHOT",
+    base_package: o.basePackage,
+    target_dir: o.targetDir,
+    backend_root: ".",
+    skill_utils_dir: path.relative(o.targetDir, skillUtils.path).replaceAll(path.sep, "/"),
+    skill_utils_created: skillUtils.created,
+    skill_utils_refreshed: skillUtils.refreshed,
+    skill_utils_backup: skillUtils.backup,
+    repository_scope: "external-repository",
+    database: o.database,
+    database_driver: driver,
+    runtime_java: "8",
+    parent_pom: "com.yss.cloud:yss-cloud-microservice:2.0.0-SNAPSHOT",
+    components_bom: "com.yss.cloud:yss-components-bom:2.0.0-SNAPSHOT",
+    persistence_profile: "yss-mybatis-plus",
+    id_strategy: "ASSIGN_ID",
+    javadoc_author: o.gitAuthor,
+    maven_settings_mode: "external",
+    maven_settings_source: mavenSettings.source,
+    maven_settings_available: mavenSettings.available,
+    maven_settings_required: mavenSettings.available,
+    dependency_resolution: "deferred",
+    network_access_during_generation: "disabled",
+    features: ["audit", "distributed-id", "excel", "nacos", "redis", "openfeign", "smart-doc", "userinfo", "actuator"],
+    modules: MODULES,
+    mock_enabled: o.withMock,
+    project_instance: true,
+    git_initialized: true,
+    default_branch: "main",
+    endpoint: o.withMock ? "POST /api/analysis/query" : null
+  };
+}
+
+async function generate(o) {
+  await assertEmpty(o.targetDir);
+  const skillUtils = await ensureSkillUtils(o.targetDir, { apply: !o.dryRun });
+  assertGitAvailable();
+  o.gitAuthor = resolveGitAuthor();
+  generatedJavadocAuthor = o.gitAuthor;
+  const mavenSettings = await resolveMavenSettings(o);
+  const plan = buildPlan(o, skillUtils, mavenSettings);
+  if (o.dryRun) {
+    console.log(JSON.stringify({ mode: "dry-run", ...plan }, null, 2));
+    return;
+  }
+
+  const targetParent = path.dirname(o.targetDir);
+  await mkdir(targetParent, { recursive: true });
+  const staging = await mkdtemp(path.join(targetParent, `.${path.basename(o.targetDir)}.staging-`));
+  const work = { ...o, targetDir: staging, modules: MODULES };
+  try {
+    for (const module of MODULES) {
+      await writeGenerated(work.targetDir, `${module}/pom.xml`, modulePom(work, module));
+      await mkdir(path.join(work.targetDir, module, "src/main/resources"), { recursive: true });
+    }
+    await writeGenerated(work.targetDir, "pom.xml", parentPom(work));
+    await writeJavaSources(work, writeGenerated);
+    const activeProfiles = `\${app.env:dev},datasource,nacos,${o.database === "oceanbase-oracle" ? "oceanbase-oracle" : "oracle"}${o.withMock ? ",mock" : ""}`;
+    await writeGenerated(work.targetDir, "server/src/main/resources/bootstrap.yml", `server:\n  port: \${SERVER_PORT:8080}\nspring:\n  application:\n    name: \${APP_NAME:${o.projectName}}\n  profiles:\n    active: ${activeProfiles}\n  main:\n    allow-bean-definition-overriding: true\n  servlet:\n    multipart:\n      max-file-size: \${MAX_FILE_SIZE:100MB}\n      max-request-size: \${MAX_REQUEST_SIZE:100MB}`);
+    await writeGenerated(work.targetDir, "server/src/main/resources/bootstrap-nacos.yml", `spring:\n  cloud:\n    nacos:\n      discovery:\n        server-addr: \${nacosserver:192.168.165.58:8848}\n        group: \${nacos_group:yss-dm}\n        namespace: \${namespace:yss-datamiddle}\n        enabled: true\n      config:\n        import-check:\n          enabled: false\n        server-addr: \${nacosserver:192.168.165.58:8848}\n        namespace: \${namespace:yss-datamiddle}\n        group: \${nacos_group:yss-dm}\n        file-extension: yml\n        enabled: true`);
+    if (o.withMock) await writeGenerated(work.targetDir, "server/src/main/resources/bootstrap-mock.yml", `spring:\n  cloud:\n    nacos:\n      discovery:\n        enabled: false\n      config:\n        enabled: false\n        import-check:\n          enabled: false`);
+    await writeGenerated(work.targetDir, "server/src/main/resources/application-mock.yml", `spring:\n  autoconfigure:\n    exclude:\n      - org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration\n      - com.yss.cloud.mybatis.MybatisPlusConfiguration\n      - com.yss.cloud.sankuai.config.LeafDataSourceConfiguration\n  leaf:\n    leafSegmentEnable: false\n    leafSnowflakeEnable: false\nyss:\n  audit:\n    enabled: false`);
+    const driver = o.database === "oceanbase-oracle" ? "com.oceanbase.jdbc.Driver" : "oracle.jdbc.OracleDriver";
+    await writeGenerated(work.targetDir, `server/src/main/resources/application-${o.database}.yml`, `spring:\n  datasource:\n    driver-class-name: ${driver}\n    url: \${DB_URL:}\n    username: \${DB_USERNAME:}\n    password: \${DB_PASSWORD:}\nyss:\n  id:\n    strategy: ASSIGN_ID`);
+    await writeGenerated(work.targetDir, "server/src/main/resources/logback-spring.xml", await renderAsset("logback-spring.xml.template", { PROJECT_NAME: o.projectName, BASE_PACKAGE: o.basePackage }));
+    await writeGenerated(work.targetDir, "server/src/main/resources/smart-doc.json", await renderAsset("smart-doc.json.template", { PROJECT_NAME: o.projectName, BASE_PACKAGE: o.basePackage, GENERATED_AT: new Date().toISOString() }));
+    await writeGenerated(staging, "README.md", `# ${o.projectName}\n\n项目根即 Maven 后端工程根，固定模块：${MODULES.join("、")}。\n\n## 依赖解析\n\n初始化阶段只生成文件和 Git 根，不执行 Maven，不下载依赖。未提供 settings 时仍会完整生成；后续验证时请使用 \`mvnw.cmd -s <settings.xml> validate\`（Windows）或 \`./mvnw -s <settings.xml> validate\`（Unix）。`);
+    await writeProjectEnvelope(work);
+    await copyWrapper(work.targetDir);
+    if (process.env.NODE_ENV === "test" && process.env.YSS_SCAFFOLD_TEST_FAIL_AFTER_STAGING === "1") fail("测试注入：staging 后失败");
+    initializeGit(staging);
+    await writeGenerated(staging, ".yss/scaffold-generation.json", JSON.stringify({ schema_version: 1, skill: SKILL_ID, generation_mode: "controlled-generation", generated_at: new Date().toISOString(), ...plan }, null, 2));
+    if (process.env.NODE_ENV === "test" && process.env.YSS_SCAFFOLD_TEST_WRITE_TARGET_DURING_STAGING === "1") await writeGenerated(o.targetDir, "keep.txt", "concurrent content");
+    if (await exists(o.targetDir)) await rmdir(o.targetDir);
+    await rename(staging, o.targetDir);
+  } catch (error) {
+    if (await exists(staging)) await rm(staging, { recursive: true, force: true });
+    throw error;
+  }
+  console.log(JSON.stringify({ mode: "generated", ...plan }, null, 2));
+}
+
+async function main() {
+  try {
+    const options = parseArgs(process.argv.slice(2));
+    if (options.help) { usage(); return 0; }
+    await generate(options);
+    return 0;
+  } catch (error) {
+    process.stderr.write(`\n❌ 生成失败: ${error.message}\n`);
+    return 1;
+  }
+}
+
+process.exitCode = await main();