create-yss-spec 3.0.0 → 3.1.0

package/template/.codex/skills/yss-implementation-contract-compiler/references/slice-implementation-contract.md

@@ -0,0 +1,201 @@
+# Slice Implementation Contract
+
+后端合同还必须绑定 `architecture_identity`（schema 见 `docs/process/schemas/backend-architecture-identity.schema.json`），并与工程基线、登记和 Manifest 一致。将同一身份复制到 `resolution`、backend 工作单元和执行结果；Profile 的成熟度/Recipe 来源是技能注册表，draft 不得 ready-for-agent。旧 backend.domain-behavior/persistence-mybatis/http-api Recipe 只读退役，重新编译时显式选择 backend.ddd-* 或 backend.mvc-*。
+
+`yss-implementation-contract-compiler` 生成草案；`yss-product-lifecycle` 核验、批准并持久化。合同缺少必填字段时状态为 `blocked`。schema v1 已停止支持，必须重新编译为 v2，不提供自动升级。
+
+```yaml
+slice_contract:
+  schema_version: 2
+  contract_id:
+  contract_version: 1
+  slice_id:
+  status: draft
+  suggested_owner_role_id: # role.frontend-engineer | role.backend-engineer | role.test-engineer；编译器只建议，生命周期编排器派活并批准
+  lifecycle_refs:
+    spec:
+    ticket:
+    requirement_freeze:
+    low_fidelity_review:
+    prototype_review:
+    prototype_profile_decision:
+    prototype_deliverable:
+    prototype_deliverable_verification:
+    prototype_confirmation:
+    openapi_freeze_or_no_impact:
+    architecture_review:
+    data_architecture:
+    engineering_baseline:
+    tactical_design:
+    build_architecture_checklist:
+    implementation_repository:
+    frontend_repository:
+    backend_repository:
+    maven_wrapper:
+  readiness:
+    blockers: []
+    stale_inputs: []
+    not_applicable:
+      - item:
+        reason:
+  resolution:
+    required_capabilities: []
+    required_skills: []
+    recipe_ids: []
+    conditions: []
+    reason_chains: {}
+    registry_digest: # sha256 of normalized docs/agents/yss-skill-registry.yaml
+    compiler_contract_digest: # sha256 of normalized compiler-contract.yaml
+    compiled_at:
+    freshness: current # digest 变化后为 stale
+  common:
+    impacted_areas: []
+    implementation_path_policy: harness-apps-multi-project # or external-repository-native | git-submodule-harness-apps
+    project_roots: []
+    required_capabilities: []
+    required_skills: []
+    optional_skills: []
+    unavailable_skills:
+      - skill:
+        provider:
+        fallback: blocked | approved-equivalent
+        resolution:
+    allowed_write_paths: []
+    forbidden_patterns: []
+    expected_evidence_files: []
+    verification_commands: []
+    human_review_points: []
+    full_reroute_triggers: []
+    quality_baseline_ref:
+    context_plan:
+      required_context_refs: []
+      on_demand_context_refs: []
+      context_stop_rule: minimal-sufficient-evidence
+      missing_context_action: blocked # or reroute
+    doubt_driven_review:
+      status: not-applicable # or required / completed / blocked
+      trigger_impacts: []
+      claim:
+      counterclaim:
+      evidence_refs: []
+      residual_risks: []
+      reviewer_ref:
+  frontend:
+    status: not-applicable
+    required_skills: []
+    approved_prototype_ref:
+    state_matrix_ref:
+    visual_baseline_ref:
+    visual_baseline_case_ids: []
+    generated_api_client_ref:
+    allowed_write_paths: []
+    component_test_seams: []
+    e2e_paths: []
+  backend:
+    status: not-applicable
+    affected_layers: []
+    component_impacts: []
+    required_skills: []
+    application_boundary:
+    transaction_boundary:
+    persistence_strategy:
+    tactical_design_ref:
+    tactical_design_version:
+    aggregate_refs: []
+    invariant_refs: []
+    state_behavior_refs: []
+    gateway_boundary_ref:
+    domain_test_seams: []
+    application_test_seams: []
+    tactical_ddd:
+      status: not-applicable
+      tactical_design_ref:
+      tactical_design_version:
+      aggregate_refs: []
+      invariant_refs: []
+      state_behavior_refs: []
+      gateway_boundary_ref:
+      domain_test_seams: []
+      application_test_seams: []
+    allowed_write_paths: []
+    forbidden_patterns: []
+    expected_evidence_files: []
+    seam_deferred: []
+    verification_commands: []
+  contract:
+    api_impact: false
+    freeze_ref:
+    no_api_impact_ref:
+    generated_clients: []
+    contract_tests: []
+    regeneration_commands: []
+  cross_repo:
+    repositories: []
+    delivery_order: []
+    integration_verification: []
+    rollback_order: []
+  work_units:
+    - id: slice-frontend
+      role_id: role.frontend-engineer
+      runtime_id: runtime.skill-projection
+      execution_state: Worker
+      workflow_status: not-started
+      task_package_ref:
+      contract_id: # must equal slice_contract.contract_id
+      contract_version: # must equal slice_contract.contract_version
+      downstream_consumers: []
+      convergence_ref:
+      work_unit:
+        behavior:
+        primary_skill:
+        supporting_skills: []
+        tdd_mode: behavior-tdd
+        allowed_write_paths: []
+        expected_evidence: []
+        verification_commands: []
+    - id: slice-backend
+      role_id: role.backend-engineer
+      runtime_id: runtime.skill-projection
+      execution_state: Worker
+      workflow_status: not-started
+      task_package_ref:
+      contract_id:
+      contract_version:
+      downstream_consumers: []
+      convergence_ref:
+      work_unit:
+        behavior:
+        primary_skill:
+        supporting_skills: []
+        tdd_mode: behavior-tdd
+        allowed_write_paths: []
+        expected_evidence: []
+        verification_commands: []
+```
+
+工作单元：
+
+```yaml
+work_unit:
+  id:
+  behavior:
+  primary_skill:
+  supporting_skills: []
+  tdd_mode: behavior-tdd
+  allowed_write_paths: []
+  expected_evidence: []
+  verification_commands: []
+  controlled_generation:
+    exception_reason:
+    generator:
+    generator_inputs: []
+    expected_files: []
+    verification_commands: []
+    behavior_tests_after_generation: []
+```
+
+`controlled_generation` 仅在 `tdd_mode: controlled-generation` 时必填；其他模式标记 `not-applicable`。明确写入需求的权限业务行为仍使用 `behavior-tdd`；API schema 与 database schema 分别触发契约或数据架构回退，不得用一个含糊的 schema 类型决定路线。
+
+`work_units` 中的前端、后端和测试任务是切片级子任务，不是新的生命周期阶段。每个子任务必须引用独立任务包；任务包只能消费同一份已批准且版本当前的 Slice Contract。`workflow_status` 追踪执行过程，不能替代生命周期状态；`contract_id`、`contract_version` 或 resolution digest 不一致时必须阻断并回到实现合同编译器。
+
+一个切片可以组合多个窄 Recipe，但只计算一次闭包。Recipe 只能引用 capability；合同同时冻结 `required_capabilities`、`required_skills`、完整原因链和 Registry/Compiler digest。任一 digest 或 Visual Baseline 版本 / digest 改变时，当前合同标记 `stale`，重新编译后仍须由 `yss-product-lifecycle` 再批准。UI 切片只消费 `visual_baseline_case_ids` 指定的图片，并先读取 manifest 与语义引用，禁止按目录 glob 猜测图片含义。

package/template/.codex/skills/yss-implementation-contract-compiler/references/yss-skill-execution-result.md

@@ -0,0 +1,71 @@
+# YSS Skill Execution Result
+
+核心 YSS skill 必须消费已批准合同版本，并返回：
+
+后端结果顶层带与当前 resolution 完全一致的 `architecture_identity`；每条验证记录还须有整数 `exit_code`。身份缺失、Profile 未 supported、验证非零或没有执行时间均不得 accepted。
+
+```yaml
+execution_result:
+  schema_version: 2
+  skill:
+  slice_id:
+  work_unit_id:
+  status: implemented
+  consumed_contract:
+    contract_ref:
+    contract_id:
+    contract_version:
+    registry_digest:
+    compiler_contract_digest:
+    quality_baseline_ref:
+    context_plan_ref:
+  changed_files:
+    - path:
+      contract_area: common | frontend | backend | contract | cross_repo
+  evidence_files:
+    - path:
+      evidence_type: code | test | generated | review | verification
+      behavior_ref:
+  verification_results:
+    - command:
+      result:
+      executed_at:
+  constraint_results:
+    - constraint:
+      status: passed | failed | not-applicable
+      evidence_ref:
+  doubt_driven_review:
+    status: not-applicable | completed | blocked
+    record_ref:
+  seam_deferred:
+    - risk:
+      owner:
+      follow_up_ticket:
+      verification_plan:
+      target_version_or_release_date:
+  deviations:
+    - rule:
+      reason:
+      approval_ref:
+  new_impacts:
+    - impact_type:
+      evidence_ref:
+  not_applicable_reason:
+```
+
+允许状态：`implemented`、`seam-deferred`、`drift`、`violation`、`not-applicable`。
+
+实现合同编译器必须验证：
+
+1. `consumed_contract.contract_version` 与当前批准版本一致，两个 resolution digest 与批准合同一致且保持 current。
+2. `changed_files` 全部位于工作单元和切片允许路径内。
+3. `expected_evidence_files` 全部存在并能回指行为。
+4. 验证命令包含实际结果和时间；计划命令不算证据。
+5. `seam_deferred` 有风险、责任人、补齐 Ticket、验证计划和目标版本 / 发布日期。
+6. `new_impacts` 非空时暂停并重路由。
+7. `drift` 触发 Architecture Re-check；`violation` 阻断 build。
+8. `status: not-applicable` 必须填写 `not_applicable_reason`；其他状态保留字段但可为空。
+
+专项 skill 自报 `implemented` 不等于最终通过，生命周期编排器和独立 Reviewer 必须复核。
+
+`verification_results` 不得为空，每项必须包含非空 `command`、`result` 和 `executed_at`。路径校验按完整目录边界判断，`apps/backend/project1-escape` 不属于 `apps/backend/project1/`；Harness 内路径还必须通过项目路径策略。完整重路由时旧合同必须标记 `stale`，新合同版本递增并保留旧合同引用、失效原因和触发器。

package/template/.codex/skills/yss-implementation-contract-compiler/tests/backend-profiles.test.mjs

@@ -0,0 +1,45 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { compileDefaultImplementationContract } from "../../../../scripts/lib/implementation-contract-compiler.mjs";
+import { validateArchitectureIdentity } from "../../../../scripts/lib/backend-architecture.mjs";
+import { loadSkillRegistry } from "../../../../scripts/lib/skill-registry.mjs";
+
+const registry = loadSkillRegistry();
+function input(name) {
+  const profile = registry.architecture_profiles[name];
+  const identity = { architecture_family: profile.architecture_family, architecture_profile: name,
+    generator_skill: profile.generator_skill, requested_capabilities: [], resolved_modules: profile.core_modules,
+    verification_database: "h2", production_database: "not-bound", contract_digest: "a".repeat(64) };
+  return { architecture_identity: identity, architecture_evidence: {
+    engineering_baseline: identity, repository_registration: identity, manifest: identity
+  }};
+}
+
+for (const name of Object.keys(registry.architecture_profiles)) {
+  test(`${name} selects architecture recipe and explicit Skill Profile`, () => {
+    const data = input(name);
+    const mvc = data.architecture_identity.architecture_family === "layered-mvc";
+    const result = compileDefaultImplementationContract({ ...data,
+      recipeIds: [mvc ? "backend.mvc-service-behavior" : "backend.ddd-domain-behavior", mvc ? "backend.mvc-http-api" : "backend.ddd-http-api"] });
+    assert.equal(result.required_skills.includes("yss-domain"), !mvc);
+    assert.equal(result.skill_profiles["yss-application"], name);
+    assert.equal(result.skill_profiles["yss-web-controller"], name);
+    assert.ok(result.readiness_blockers.includes("backend-profile-not-supported"));
+  });
+}
+
+test("rejects missing identity, deprecated recipe, wrong family and stale evidence", () => {
+  assert.throws(() => compileDefaultImplementationContract({ recipeIds: ["backend.mvc-http-api"] }), /architecture_identity/);
+  assert.throws(() => compileDefaultImplementationContract({ recipeIds: ["backend.http-api"] }), /deprecated/);
+  assert.throws(() => compileDefaultImplementationContract({ ...input("layered-mvc-service"), recipeIds: ["backend.ddd-http-api"] }), /架构族/);
+  const stale = input("layered-mvc-service");
+  stale.architecture_evidence.manifest = { ...stale.architecture_identity, contract_digest: "b".repeat(64) };
+  assert.throws(() => compileDefaultImplementationContract({ ...stale, recipeIds: ["backend.mvc-http-api"] }), /stale/);
+});
+
+test("rejects unsupported capability closure and production driver defaults", () => {
+  const identity = input("mvc-data-analysis-v1").architecture_identity;
+  assert.throws(() => validateArchitectureIdentity({ ...identity, resolved_modules: ["server"] }), /模块闭包/);
+  assert.throws(() => validateArchitectureIdentity({ ...identity, production_database: "oracle" }), /H2/);
+  assert.throws(() => compileDefaultImplementationContract({ ...input("layered-mvc-service"), requiredCapabilities: ["layer.domain"] }), /不匹配/);
+});

package/template/.codex/skills/yss-implementation-contract-compiler/tests/compiler-scenarios.test.mjs

@@ -0,0 +1,91 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  compileImplementationContract,
+  digestDocument,
+  evaluateContractFreshness,
+  loadCompilerContract,
+  validateExecutionResult
+} from "../../../../scripts/lib/implementation-contract-compiler.mjs";
+import { loadSkillRegistry } from "../../../../scripts/lib/skill-registry.mjs";
+
+const registry = loadSkillRegistry();
+const compilerContract = loadCompilerContract();
+const fixed = "2026-09-04T00:00:00.000Z";
+const identity = { architecture_family: "domain-driven", architecture_profile: "target-domain-model", generator_skill: "yss-ddd-scaffold-generator", requested_capabilities: [], resolved_modules: ["domain", "application", "infrastructure", "adapter", "bootstrap"], verification_database: "h2", production_database: "not-bound", contract_digest: "a".repeat(64) };
+const architecture = { architecture_identity: identity, architecture_evidence: { engineering_baseline: identity, repository_registration: identity, manifest: identity } };
+const compile = (input) => compileImplementationContract({ registry, compilerContract, compiledAt: fixed, ...architecture, ...input });
+
+test("combines narrow recipes once and preserves deterministic output", () => {
+  const input = {
+    recipeIds: ["backend.ddd-http-api", "backend.ddd-domain-behavior", "backend.ddd-persistence-mybatis"],
+    conditions: ["mybatis", "conversion", "pojo", "request-validation", "error-mapping"]
+  };
+  const first = compile(input);
+  const second = compile({ ...input, recipeIds: [...input.recipeIds].reverse(), conditions: [...input.conditions].reverse() });
+  assert.deepEqual(first, second);
+  assert.deepEqual(first.recipe_ids, ["backend.ddd-domain-behavior", "backend.ddd-persistence-mybatis", "backend.ddd-http-api"]);
+  for (const skill of ["yss-domain", "yss-application", "yss-repository", "yss-mybatis", "yss-web-controller", "yss-dto", "yss-validation", "yss-exception", "mapstruct", "lombok", "alibaba-java-code-style"]) {
+    assert.equal(first.required_skills.filter((candidate) => candidate === skill).length, 1, `${skill} should appear once`);
+  }
+});
+
+test("does not promote conditional or component dependencies without explicit input", () => {
+  const persistence = compile({ requiredCapabilities: ["layer.persistence"] });
+  assert.deepEqual(persistence.required_skills, ["alibaba-java-code-style", "yss-repository"]);
+  assert.equal(persistence.required_skills.includes("yss-mybatis"), false);
+  assert.equal(persistence.required_skills.includes("mapstruct"), false);
+  assert.equal(persistence.required_skills.includes("lombok"), false);
+
+  const validation = compile({ requiredCapabilities: ["contract.request-validation"] });
+  assert.deepEqual(validation.required_skills, ["yss-validation"]);
+  assert.equal(validation.required_skills.includes("yss-exception"), false);
+  assert.ok(validation.non_expanding_dependencies.some((edge) => edge.from === "yss-validation" && edge.skill === "yss-exception"));
+});
+
+test("loads only explicitly satisfied context-conditional dependencies", () => {
+  const persistence = compile({ requiredCapabilities: ["layer.persistence"], conditions: ["mybatis"] });
+  assert.equal(persistence.required_skills.includes("yss-mybatis"), true);
+  assert.equal(persistence.required_skills.includes("mapstruct"), false);
+  assert.equal(persistence.required_skills.includes("lombok"), false);
+});
+
+test("rejects recipes that reference skills and context-required cycles", () => {
+  const invalidRecipeRegistry = structuredClone(registry);
+  invalidRecipeRegistry.recipes[0].skills = ["yss-domain"];
+  assert.throws(() => compileImplementationContract({ ...architecture, registry: invalidRecipeRegistry, compilerContract, recipeIds: [invalidRecipeRegistry.recipes[0].id] }), /不得直接引用 skills/);
+
+  const cyclicRegistry = structuredClone(registry);
+  cyclicRegistry.skill_dependencies["alibaba-java-code-style"] = [{ skill: "yss-domain", type: "context-required" }];
+  assert.throws(() => compileImplementationContract({ ...architecture, registry: cyclicRegistry, compilerContract, requiredCapabilities: ["layer.domain"] }), /依赖循环/);
+});
+
+test("rejects removed ids and schema v1 without compatibility", () => {
+  assert.throws(() => compile({ recipeIds: ["yss-router"] }), /已移除 skill id/);
+  assert.throws(() => compileImplementationContract({ registry: { ...registry, schema_version: 1 }, compilerContract, requiredCapabilities: ["layer.domain"] }), /schema v1 已停止支持/);
+  assert.throws(() => compileImplementationContract({ registry, compilerContract: { ...compilerContract, schema_version: 1 }, requiredCapabilities: ["layer.domain"] }), /schema v1 已停止支持/);
+});
+
+test("marks digest drift stale and validates v2 execution evidence", () => {
+  const resolution = compile({ requiredCapabilities: ["contract.request-validation"], architecture_identity: undefined, architecture_evidence: undefined });
+  const contract = { schema_version: 2, contract_id: "slice-1", contract_version: 1, resolution };
+  assert.deepEqual(evaluateContractFreshness(contract, { registry, compilerContract }), { freshness: "current", reasons: [] });
+  const changedRegistry = structuredClone(registry);
+  changedRegistry.description += " changed";
+  assert.equal(evaluateContractFreshness(contract, { registry: changedRegistry, compilerContract }).freshness, "stale");
+
+  const result = {
+    schema_version: 2,
+    status: "implemented",
+    consumed_contract: {
+      contract_id: "slice-1",
+      contract_version: 1,
+      registry_digest: digestDocument(registry),
+      compiler_contract_digest: digestDocument(compilerContract)
+    },
+    verification_results: [{ command: "./mvnw test", exit_code: 0, executed_at: fixed }],
+    new_impacts: []
+  };
+  assert.deepEqual(validateExecutionResult(result, contract, { registry, compilerContract }), { status: "accepted", blockers: [] });
+  assert.deepEqual(validateExecutionResult({ ...result, new_impacts: [{ impact_type: "cache" }] }, contract, { registry, compilerContract }), { status: "blocked", blockers: ["new-impacts"] });
+});

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

@@ -0,0 +1,64 @@
+---
+name: yss-layered-mvc-scaffold-generator
+description: 用于在生命周期已批准的脚手架合同下生成通用 YSS Java 8 分层 MVC 后端工程；核心模块为 server、service、repository，并按能力确定性增加 adapter、client、feign-client。
+---
+
+# YSS Layered MVC Scaffold Generator
+
+本 skill 只为已登记的全新 backend project 生成机械工程骨架，不创建 `project-instance`、不初始化 Git、不生成业务 Controller、DTO、查询、状态机或 Mock 数据。
+
+## 进入条件
+
+- backend `scaffold_status=required`，目标目录已确认且不存在。
+- `scaffold-architecture-decisions.yaml` 中对应项目已达到 `lifecycle-approved`，确认架构为 `layered-mvc`。
+- `yss-implementation-contract-compiler` 已编译 scaffold contract schema v3，生命周期已批准并持久化。
+- 合同中的 `decision_id`、文件 digest、Profile、能力闭包、写路径和验证命令仍为当前版本。
+
+任一条件缺失时返回 `blocked`。本生成器无交互、无默认回退；用户选择由 `yss-product-lifecycle` 在 `work-unit.technical-analysis` 的工程基线内完成。
+
+## 架构与 Profile
+
+- 固定核心模块：`server`、`service`、`repository`。
+- `external-integration` 增加 `adapter`。
+- `published-client` 增加 `client`。
+- `feign-client` 增加 `client`、`feign-client`。
+- 固定平台：Java 8、Spring Boot 2.7、`javax`、YSS BOM、MyBatis-Plus。
+- 固定 architecture_profile=layered-mvc-service；verification_database=h2、production_database=not-bound。测试使用 H2，本地运行显式启用 scaffold-local；不引入外部驱动/数据源。
+
+能力解析规则、模块职责和依赖方向见 [architecture.md](references/architecture.md)。生成器必须同时校验 `requested_capabilities` 与 `resolved_modules`，不得自行补猜模块。
+
+## 执行
+
+优先使用一键入口：
+
+```bash
+node scripts/generate_and_verify_scaffold.mjs \
+  --project-name my-service \
+  --base-package com.yss.myservice \
+  --output-dir /path/to/backend-container \
+  --contract-file /path/to/approved-scaffold-contract.json \
+  --contract-id <id> \
+  --contract-version <version> \
+  --approval-ref <approval-ref> \
+  --compiler-draft-ref <compiler-ref> \
+  --persisted-ref <persisted-ref> \
+  --group-id com.yss.example \
+  --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 \
+  --evidence-dir /path/to/evidence
+```
+
+受控工作流必须在项目根实际执行 `./mvnw validate`、`./mvnw test`、`./mvnw package`，逐条记录退出码、时间、stdout/stderr 和失败分类。全部通过后只得到 `empty-scaffold-verified`。
+
+## 硬约束
+
+- 只接受 scaffold contract schema v3 和 Manifest schema v3；历史 v2 只读兼容，不用于新生成。
+- `architecture_family` 必须为 `layered-mvc`，`generator_skill` 必须为本 skill。
+- 目标存在、`--force`、旧项目迁移、模板升级均为 `unsupported`。
+- Harness 内只允许以 `apps/backend/` 为输出父容器；外部实现仓库使用已登记真实路径。
+- 不生成业务示例。健康检查、上下文加载测试和架构测试只能验证机械工程能力，不定义用户可见 API。
+- 生成后业务实现必须回到当前批准的 Slice Implementation Contract，使用适用 YSS skills 和 `behavior-tdd`。
+- DDD/MVC 互转不属于脚手架生成；已生成项目改变架构时必须建立独立迁移工作单元。

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "YSS Layered MVC Scaffold Generator"
+  short_description: "Generate an approved YSS layered MVC backend skeleton."
+  default_prompt: "Use $yss-layered-mvc-scaffold-generator only after a user-confirmed scaffold architecture decision and a lifecycle-approved schema v3 scaffold contract."

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

@@ -0,0 +1,29 @@
+# 通用分层 MVC 架构合同
+
+## 模块闭包
+
+| 能力 | 解析模块 |
+|---|---|
+| 核心 | `server`、`service`、`repository` |
+| `external-integration` | `adapter` |
+| `published-client` | `client` |
+| `feign-client` | `client`、`feign-client` |
+
+合同保存 `requested_capabilities`、`resolved_modules` 和 `resolution_version: 1`。模块按 `server`、`service`、`repository`、`adapter`、`client`、`feign-client` 的稳定顺序生成。
+
+## 职责和依赖
+
+| 模块 | 职责 | 允许依赖 |
+|---|---|---|
+| `server` | Spring Boot 启动、Controller 装配和 Web 配置 | `service`、可选 `client` |
+| `service` | 应用服务、事务脚本和用例编排 | `repository`、可选 `adapter` / `feign-client` |
+| `repository` | PO、Mapper、SQL 与数据库访问 | 无本项目上游模块 |
+| `adapter` | 外部系统适配实现 | 无本项目上游模块 |
+| `client` | 对外稳定调用契约 | 无本项目上游模块 |
+| `feign-client` | `client` 的 Feign 实现 | `client` |
+
+MVC 模式不等于禁止领域分析。若技术分析发现聚合不变量、复杂状态机、跨聚合一致性、Domain Event 或复杂并发，Agent 应推荐 `domain-driven`；用户仍选择 MVC 时必须记录覆盖理由和残余风险。局部 Tactical DDD Check 仍可按真实领域影响触发。
+
+## 生成边界
+
+允许生成 POM、Wrapper、启动入口、环境配置、包级占位、架构测试与上下文加载测试。禁止生成业务 API、DTO、字段、查询、状态、事务规则、权限、错误映射和 Mock 业务数据。

package/template/.codex/skills/yss-layered-mvc-scaffold-generator/scripts/generate_and_verify_scaffold.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+import { execFile } from "node:child_process";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { run } from "./run_scaffold_verification.mjs";
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const GENERATOR = path.join(SCRIPT_DIR, "generate_scaffold.mjs");
+
+function parseArgs(argv) {
+  const generatorArgs = [];
+  let evidenceDir;
+  let outputDir;
+  let projectName;
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === "--evidence-dir" || token.startsWith("--evidence-dir=")) {
+      evidenceDir = token.includes("=") ? token.slice(token.indexOf("=") + 1) : argv[++index];
+      continue;
+    }
+    generatorArgs.push(token);
+    if (token === "--output-dir") outputDir = argv[index + 1];
+    if (token.startsWith("--output-dir=")) outputDir = token.slice(token.indexOf("=") + 1);
+    if (token === "--project-name") projectName = argv[index + 1];
+    if (token.startsWith("--project-name=")) projectName = token.slice(token.indexOf("=") + 1);
+  }
+  if (!evidenceDir || !outputDir || !projectName) throw new Error("必须提供 --evidence-dir、--output-dir 和 --project-name");
+  return { evidenceDir: path.resolve(evidenceDir), generatorArgs, projectRoot: path.join(path.resolve(outputDir), projectName) };
+}
+
+function executeGenerator(args) {
+  return new Promise((resolve) => execFile(process.execPath, [GENERATOR, ...args], { encoding: "utf8" }, (error, stdout, stderr) => resolve({ exitCode: error?.code ?? 0, stdout, stderr })));
+}
+
+async function main() {
+  try {
+    const args = parseArgs(process.argv.slice(2));
+    await mkdir(args.evidenceDir, { recursive: true });
+    const generation = await executeGenerator(args.generatorArgs);
+    await writeFile(path.join(args.evidenceDir, "generation.stdout.log"), generation.stdout, "utf8");
+    await writeFile(path.join(args.evidenceDir, "generation.stderr.log"), generation.stderr, "utf8");
+    if (generation.exitCode !== 0) throw new Error(`生成失败: ${generation.stderr.trim()}`);
+    const verification = await run(args.projectRoot, args.evidenceDir);
+    await writeFile(path.join(args.evidenceDir, "scaffold-verification.json"), `${JSON.stringify(verification, null, 2)}\n`, "utf8");
+    if (verification.status !== "passed") return 1;
+    const manifestPath = path.join(args.projectRoot, ".yss/scaffold-generation.json");
+    const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+    manifest.completion_level = "empty-scaffold-verified";
+    manifest.empty_scaffold_verification_ref = path.join(args.evidenceDir, "scaffold-verification.json");
+    manifest.empty_scaffold_verified_at = new Date().toISOString();
+    await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+    return 0;
+  } catch (error) {
+    process.stderr.write(`❌ MVC 脚手架工作流失败: ${error.message}\n`);
+    return 1;
+  }
+}
+
+process.exitCode = await main();