create-yss-spec 2.1.0 → 2.1.2

package/template/docs/templates/build-architecture-checklist-template.md

@@ -19,6 +19,8 @@ owner: ai
 | 系统 / 数据架构设计 |  |  |
 | 风险 / 回滚约束 | `AGENTS.md` |  |
 | Slice Implementation Contract |  | 填写 contract_id / contract_version / 生命周期批准状态 |
+| 后端脚手架策略 | `orchestration-contract.yaml` / `yss-ddd-scaffold-generator` |  | backend `scaffold_status=required` 时填写结构化合同身份、批准/持久化引用、生成器输入、预期文件、实际 `./mvnw` 结果和后置 Router 重编译 |
+| 工程项目路径策略 | `docs/process/implementation-repo-integration.md` / Router Contract |  | Harness 内必须是 `apps/backend/<project>/` 或 `apps/frontend/<project>/`；`apps/backend/`、`apps/frontend/` 仅为容器，`app/backend/`、`app/frontend/` 及其子路径阻断 |
 | 垂直切片工作单元 |  |  |
 | YSS Skill Execution Result |  | 每个 skill / work_unit 的结果文件引用 |
 
@@ -30,15 +32,18 @@ owner: ai
 | 后端切片必须回勾 `Backend Slice Implementation Contract`：required skills、允许写范围、禁止模式、证据文件、延期 seam 和验证命令完整 | implementation routing / 垂直切片 Ticket / `AGENTS.md` |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 缺合同或合同不完整时暂停并记录替代方案 |
 | 统一合同版本：实现消费的 contract_id / contract_version 与生命周期批准并持久化的版本一致，Router 未自行批准合同或推进 `ready-for-agent` | Slice Implementation Contract / 生命周期证据 |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 版本不一致时将工作单元标记 `stale` 并暂停 build |
 | 合同子项闭环：Common、Frontend、Backend、Contract、Cross-repo 子合同按影响面填写，不适用项有原因 | Slice Implementation Contract |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 缺失适用子合同时回到 Router |
+| 原型确认后的后端脚手架顺序：工程基线 → Router 脚手架合同 draft / 生命周期批准 → `yss-ddd-scaffold-generator` → `yss-backend-scaffold-parent` → Router 重编译；脚手架不得生成业务行为 | `yss-product-lifecycle` / `yss-ddd-scaffold-generator` |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 顺序缺失、生成器混入业务行为或缺 Execution Result 时阻断 |
 | 写路径与证据：Execution Result 的 changed_files 均位于 allowed_write_paths，expected_evidence_files 已实际生成 | Slice Implementation Contract / YSS Skill Execution Result |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 路径越界或证据缺失标记 `violation` 并阻断 build |
 | TDD 模式：每个工作单元唯一选择 `behavior-tdd` 或 `controlled-generation`；生成器未承载状态、权限、业务过滤、事务、错误映射或用户可见交互 | Slice Implementation Contract / 垂直切片 Ticket / Execution Result |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 模式不匹配时拆分工作单元并完整重路由 |
-| 实际验证：Execution Result 包含实际命令、结果和执行时间；只列计划命令不构成 fresh verification | YSS Skill Execution Result |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 缺实际结果或时间时不得进入完成结论 |
+| 所有后续生成代码：必须消费当前批准合同、主 YSS skill、依赖闭包、允许写路径、预期证据和 YSS Skill Execution Result；业务行为使用 `behavior-tdd` | `post_scaffold_generated_code_policy` |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 缺任一条件或以时间压力豁免时阻断 build |
+| 实际验证：Execution Result 包含实际命令、exit_code、`duration_ms`、stdout/stderr 引用和执行时间；只列计划命令或生成器打印不构成 fresh verification | YSS Skill Execution Result / `orchestration-contract.yaml` |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 缺实际结果或时间时不得进入完成结论 |
 | 新影响与偏离：`new_impacts`、`deviations`、`drift`、`violation` 已核验并触发相应重路由、Architecture Re-check 或生命周期回退 | YSS Skill Execution Result / implementation routing |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 非空新影响使当前合同相关部分失效并暂停工作单元 |
 | Web Adapter / DTO：必须按 `yss-dto` 定义或复用 CMD / Query / VO / Result；不得在 Controller 内部类或非约定包临时定义主要 DTO，不得手工分页主要业务集合 | `yss-web-controller` / `yss-dto` / OpenAPI Freeze |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 命中时回到 Controller / DTO 设计 |
 | Application：负责用例编排、事务边界和跨聚合协调，不承载核心领域规则 | `yss-backend-scaffold-application` / 系统架构 |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 领域规则下沉 Domain，事务边界留在 Application |
 | Infrastructure：需要持久化的切片必须有 PO / Repository / Convertor / GatewayImpl；`InMemory*Gateway` 只能作为显式 `seam-deferred` | `yss-repository` / `yss-backend-scaffold-infrastructure` / 数据架构 |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 未补齐时不得声称生产持久化完成 |
 | POJO / Convertor：DTO / VO / CMD / Query / PO / Domain Model 样板代码默认使用 Lombok；对象转换默认使用 MapStruct，禁止 `BeanUtils.copyProperties`、反射拷贝和重复手写字段赋值 | `lombok` / `mapstruct` / `AGENTS.md` |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 未加载 skill、缺注解处理器配置、缺 Convertor 或无例外说明时标记 `violation` |
 | 后端工程工具链：构建、测试、运行、OpenAPI 生成、CI 和 Release 命令必须使用项目根目录 `./mvnw ...`；裸 `mvn ...` 必须有受控例外记录 | `yss-ddd-scaffold-generator` / `yss-backend-scaffold-parent` / implementation routing |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 无例外记录时改为 `./mvnw ...`，否则不得进入完成 / 可合并结论 |
+| 工程项目路径：每个 Harness 内项目必须有具体项目段，禁止直接写入容器根或单数 `app/...` | `docs/process/implementation-repo-integration.md` / implementation path validator |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 路径违规时停止 build，并回到实现路由 |
 | 文档语言：持久化生命周期文档、实施记录、审查报告、发布说明和 Git checkpoint 正文必须使用中文，英文 skill / 模板不得原样落地 | `AGENTS.md` / `yss-product-lifecycle` |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 仅保留必要英文技术标识、命令和 metadata |
 | 高风险变更：认证 / 授权、SQL / DDL、迁移、加密、公共基础库 API 变更必须记录验证证据、责任人和回滚约束 | `AGENTS.md` |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 缺验证证据或责任人时不得发布或合并 |
 |  |  |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  |  |
@@ -90,6 +95,7 @@ owner: ai
 > 命中不等于必然失败；`SingleResult` / `PageResult`、`CMD` / `Query` / `VO` 是 `yss-dto` 合法产物。命中项必须说明是否复用了既有 DTO 体系、是否位于约定包路径、是否继承约定基类；无法解释或未回勾合同即为 `violation`。
 
 ```bash
+scripts/verify-implementation-path-scenarios
 rg -n "class (SingleResult|MultiResult|PageResult|Result)<|public static class .*(Command|Cmd|Query|VO)|subList\\(|InMemory.*Gateway|implements .*Gateway|extends .*Repository|@TableName|Mappers\\.getMapper|BeanUtils\\.copyProperties|copyProperties\\(|new [A-Za-z0-9]+VO\\(|new [A-Za-z0-9]+DTO\\(" apps/backend
 rg -n "class .*(PO|DTO|VO|Cmd|Query)\\b|private final .* log =|LoggerFactory\\.getLogger|public .*(get|set)[A-Z]" apps/backend
 ```

package/template/docs/templates/cross-repo-slice-template.md

@@ -37,6 +37,7 @@ owner: ai
 | backend_mr_pr |  |
 | backend_ci |  |
 | backend_verification |  |
+| backend_project_root | `apps/backend/<project>/` 或外部真实路径 |
 | backend_status | pending / ready / blocked / not-applicable |
 
 ## 4. Frontend
@@ -48,6 +49,7 @@ owner: ai
 | frontend_mr_pr |  |
 | frontend_ci |  |
 | frontend_verification |  |
+| frontend_project_root | `apps/frontend/<project>/` 或外部真实路径 |
 | frontend_status | pending / ready / blocked / not-applicable |
 
 ## 5. Fresh Verification

package/template/docs/templates/implementation-repo-registry-template.md

@@ -17,6 +17,11 @@ owner: ai
 | git_url |  |
 | default_branch |  |
 | local_worktree |  |
+| repository_scope | external-repository / harness-apps |
+| project_type | backend / frontend / fullstack / other |
+| project_name |  |
+| project_root | 外部仓库相对路径，或 `apps/backend/<project>/` / `apps/frontend/<project>/` |
+| layout_policy | `harness-apps-multi-project` / `external-repository-native` |
 | scaffold_status | existing / required / initialized |
 | scaffold_skill | `yss-ddd-scaffold-generator` / `yss-frontend-scaffold-generator` / none |
 | scaffold_target_confirmed | 是 / 否 / 不适用 |
@@ -36,6 +41,15 @@ owner: ai
 | typecheck_command |  |  |
 | ci_pipeline |  |  |
 
+Harness 内项目路径约束：`apps/backend/`、`apps/frontend/` 只能作为项目容器；工程必须位于具体的 `apps/backend/<project>/` 或 `apps/frontend/<project>/`。`app/backend/`、`app/frontend/` 及其子路径禁止登记或生成。外部实现仓库填写真实项目根路径，不使用本表的 Harness 占位路径。
+
+## 2.1 项目清单（同一 monorepo 可登记多个项目）
+
+| project_name | project_type | project_root | test_command | build_command | rollback_point |
+|---|---|---|---|---|---|
+| project1 | backend / frontend | `apps/backend/project1/` 或 `apps/frontend/project1/` |  |  |  |
+| project2 | backend / frontend | `apps/backend/project2/` 或 `apps/frontend/project2/` |  |  |  |
+
 ## 3. 契约与设计接入
 
 | 接入项 | 状态 | 证据 / 路径 | 缺口 |

package/template/docs/templates/implementation-routing-template.md

@@ -21,6 +21,7 @@ owner: ai
 | Design Review |  |  |  |
 | 实现仓库 / 实现位置 |  |  |  |
 | 前后端工程存在性判定 |  |  | 记录 frontend / backend 是否已存在且可复用 |
+| 工程路径策略 |  |  | Harness 内使用 `apps/backend/<project>/` / `apps/frontend/<project>/`；外部仓库记录真实项目根 |
 | `垂直切片 Ticket 状态` |  |  | ready / blocked / in-progress |
 
 ## 2. 实现前门禁
@@ -36,6 +37,10 @@ owner: ai
 | 受影响 frontend 工程已存在可复用，或已登记 `scaffold_status=required` 并确认外部脚手架目标 | 是 / 否 / 不适用 |  |
 | 受影响 backend 工程已存在可复用，或已登记 `scaffold_status=required` 并确认外部脚手架目标 | 是 / 否 / 不适用 |  |
 | 缺失工程时已路由到对应脚手架 skill | 是 / 否 / 不适用 | `yss-ddd-scaffold-generator` / `yss-frontend-scaffold-generator` |
+| Harness 内项目根路径符合 `apps/<backend|frontend>/<project>/` | 是 / 否 / 不适用 | `apps/backend/`、`apps/frontend/` 仅为容器 |
+| 未使用 `app/backend/`、`app/frontend/` 及其子路径 | 是 / 否 / 不适用 | 命中即阻断生成和实现 |
+| 原型确认后先完成后端脚手架，再进入业务代码路由 | 是 / 否 / 不适用 | `backend_scaffold_policy_satisfied` |
+| 后端脚手架合同字段完整且版本当前 | 是 / 否 / 不适用 | `contract_id`、`contract_version`、Router draft、生命周期批准、持久化引用、允许写路径、预期证据、验证命令 |
 | 后端构建 / 测试 / OpenAPI / CI 命令均使用项目根目录 `./mvnw ...`，或已记录受控例外 | 是 / 否 / 不适用 | 裸 `mvn ...` 默认为规范偏离 |
 | 持久化文档正文和章节标题已转换为中文，仅保留必要英文技术标识 / metadata | 是 / 否 | 英文 skill / 模板不得原样落地为交付文档 |
 | YSS skill 路由已完成 | 是 / 否 |  |
@@ -79,6 +84,8 @@ owner: ai
 | 字段 | 内容 |
 |---|---|
 | impacted_areas |  |
+| implementation_path_policy | `harness-apps-multi-project` / `external-repository-native` |
+| project_roots | Harness 内填写 `apps/backend/<project>/` / `apps/frontend/<project>/`；外部仓库填写真实项目根 |
 | required_skills |  |
 | optional_skills |  |
 | unavailable_skills | 写明 provider、fallback 和阻断结论；不得静默跳过 |
@@ -180,11 +187,13 @@ owner: ai
 
 ## 4. 外部实现仓库
 
-| repo_role | git_url | default_branch | working_branch | MR / PR | CI | test_command | build_command | 状态 |
-|---|---|---|---|---|---|---|---|---|
-| backend |  |  |  |  |  |  |  | pending / ready / blocked / not-applicable |
-| frontend |  |  |  |  |  |  |  | pending / ready / blocked / not-applicable |
-| other |  |  |  |  |  |  |  | pending / ready / blocked / not-applicable |
+> 当前仓库默认不承载运行时代码。若用户明确选择 Harness 内实现，项目根必须是 `apps/backend/<project>/` 或 `apps/frontend/<project>/`；`apps/backend/`、`apps/frontend/` 不能作为项目根，`app/backend/`、`app/frontend/` 及其子路径禁止使用。
+
+| repo_role | project_root | git_url | default_branch | working_branch | MR / PR | CI | test_command | build_command | 状态 |
+|---|---|---|---|---|---|---|---|---|---|
+| backend | `apps/backend/<project>/` 或外部真实路径 |  |  |  |  |  |  |  | pending / ready / blocked / not-applicable |
+| frontend | `apps/frontend/<project>/` 或外部真实路径 |  |  |  |  |  |  |  | pending / ready / blocked / not-applicable |
+| other | 真实路径 |  |  |  |  |  |  |  | pending / ready / blocked / not-applicable |
 
 说明：当前仓库默认作为 Harness / 研发管理仓库；前后端实现默认位于外部实现仓库。缺少实现仓库登记时，先使用 `implementation-repo-onboarding`，并按 `docs/templates/implementation-repo-registry-template.md` 补齐登记。
 
@@ -195,6 +204,8 @@ owner: ai
 | backend | 是 / 否 / 不适用 | existing / required / initialized / not-applicable | 是 / 否 / 不适用 | 复用现有 / 初始化 / 阻塞 | `yss-ddd-scaffold-generator` / none |  |  |
 | frontend | 是 / 否 / 不适用 | existing / required / initialized / not-applicable | 是 / 否 / 不适用 | 复用现有 / 初始化 / 阻塞 | `yss-frontend-scaffold-generator` / none |  |  |
 
+脚手架输出位置必须回指具体项目根：后端为 `apps/backend/<project>/`，前端为 `apps/frontend/<project>/`；不得把 `apps/backend/`、`apps/frontend/` 容器根或任何 `app/backend/`、`app/frontend/` 路径作为生成目标。
+
 ## 4.2 人工确认结论
 
 | 人工确认项 | 是否涉及 | 结论 | 证据 / 链接 | 补齐落点 |
@@ -203,6 +214,23 @@ owner: ai
 | 权限接入 / 认证 / 授权 | 是 / 否 | 通过 / 草案 / 阻断 / 不适用 |  |  |
 | 审计日志 | 是 / 否 | 通过 / 草案 / 阻断 / 不适用 |  |  |
 
+### 4.3 后端脚手架工作单元
+
+当 backend `scaffold_status=required` 时，先登记一个 `controlled-generation` 工作单元：`primary_skill=yss-ddd-scaffold-generator`，并在后续追加 `yss-backend-scaffold-parent` 基线校验和 `yss-router` 合同重编译。`existing` / `initialized` 不重复全量生成，但必须提供等价基线和 Wrapper 证据。
+
+| 项 | 内容 |
+|---|---|
+| 前置 | `prototype_confirmation`、工程基线、实现仓库和脚手架目标已确认；Router 脚手架合同 draft 已经生命周期批准并持久化为结构化 JSON，生成器通过 `--contract-file` 消费 |
+| 生成器 | `yss-ddd-scaffold-generator` |
+| 模式 | `controlled-generation` |
+| 允许生成 | Domain / Application / Infrastructure / Adapter / Bootstrap 目录骨架、POM、配置、Wrapper、Smart Doc 和非业务机械模板 |
+| 禁止生成 | 业务规则、状态机、权限、事务、复杂查询、错误映射、业务字段和用户可见行为 |
+| 生成选项 | 关闭 `--with-example`；非空目录 `--force` 默认阻断，覆盖范围、备份、回滚点和批准引用齐全后才能单独审查 |
+| 验证 | 受控验证器实际执行项目根目录 `./mvnw validate`、`./mvnw test`、`./mvnw package`，逐条记录 `exit_code`、`duration_ms`、stdout/stderr 引用和执行时间；打印命令不算证据 |
+| 后置 | `yss-backend-scaffold-parent`、`yss-router` 业务合同重编译、YSS Skill Execution Result |
+
+所有后续生成代码必须绑定当前批准且版本一致的 Slice Implementation Contract、主 YSS skill、依赖闭包、允许写路径、预期证据和 Execution Result。业务行为必须使用 `behavior-tdd`；缺任一条件即阻断，不得以脚手架成功或时间压力豁免。
+
 ## 5. TDD 与验证策略
 
 > 每个工作单元必须且只能选择 `behavior-tdd` 或 `controlled-generation`。领域规则、状态机、事务、复杂查询、权限 / 错误映射、页面交互和用户可见状态必须使用 `behavior-tdd`；`controlled-generation` 只用于机械脚手架、样板、冻结客户端和配置。
@@ -234,7 +262,7 @@ owner: ai
 
 ## 5.3 YSS Skill Execution Result 回填
 
-> 每个结果必须引用当前 `contract_id` / `contract_version` 和 `work_unit_id`。只列计划命令、缺实际结果或时间戳，不构成 fresh verification。
+> 每个结果必须引用当前 `contract_id` / `contract_version` 和 `work_unit_id`。只列计划命令、缺实际结果、`duration_ms` 或时间戳，不构成 fresh verification。
 
 | schema_version | skill | slice_id | work_unit_id | status | consumed contract ref / version | changed_files | evidence_files | verification result / executed_at | constraint_results | seam_deferred | deviations | new_impacts | 结果文件引用 |
 |---|---|---|---|---|---|---|---|---|---|---|---|---|---|
@@ -277,6 +305,7 @@ owner: ai
 - [ ] 后端切片如适用，已填写 `Backend Slice Implementation Contract`，并且 required skills、禁止模式、证据文件、延期 seam 和验证命令完整。
 - [ ] 受影响外部实现仓库已登记，并绑定分支、MR / PR、CI 和验证命令。
 - [ ] 受影响 frontend / backend 工程存在性已判定；0-1 缺失工程已登记 `scaffold_status=required`、确认外部脚手架目标并路由对应脚手架 skill。
+- [ ] 原型确认后已满足 `backend_scaffold_policy_satisfied`；脚手架只生成工程骨架，所有后续生成代码均经批准合同和 YSS skill 路由。
 - [ ] DDL / SQL / 数据库迁移、权限接入和审计日志的人工确认结论已记录；未通过时记录阻塞原因、责任人和补齐计划。
 - [ ] 若使用 subagent，已记录任务包、写范围、独立 review、verification 命令和主控采纳结论。
 - [ ] 每个切片包含测试命令、验证方式和回滚点。

package/template/docs/user-guide//344/272/247/345/223/201/347/224/237/345/221/275/345/221/250/346/234/237/345/267/245/344/275/234/346/265/201.md

@@ -27,13 +27,14 @@
 推荐把真实工程代码放在独立实现仓库。本仓库默认作为 Harness / 研发管理仓库，保存产品、契约和过程资产。如果用户明确选择把代码放入本仓库，才按需新增：
 
 ```text
-apps/backend/
-apps/frontend/
+apps/
+├── backend/<project>/
+└── frontend/<project>/
 docs/releases/
 docs/implementation/
 ```
 
-不得由 Agent 自行新建任意顶层业务代码目录。实现仓库接入和跨仓库切片绑定见 `docs/process/implementation-repo-integration.md`。
+`apps/backend/` 和 `apps/frontend/` 只能作为项目容器，不能直接生成工程；`app/backend/`、`app/frontend/` 及其子路径禁止使用。不得由 Agent 自行新建任意顶层业务代码目录。实现仓库接入和跨仓库切片绑定见 `docs/process/implementation-repo-integration.md`。
 
 ## 2. 工具分工
 

package/template/docs/user-guide//347/224/237/345/221/275/345/221/250/346/234/237/346/234/200/344/275/263/345/256/236/350/267/265.md

@@ -41,6 +41,8 @@ Draft 阶段允许调整接口，但不能被当成稳定实现契约；Freeze
 
 从零创建后端服务时，工程基线由 `yss-ddd-scaffold-generator` 产出；设计和审查阶段用 `yss-backend-scaffold-parent` 校验。功能开发阶段只补充本次变更需要的局部约束，不重新发明分层架构。
 
+如果功能已有高保真原型和用户确认，原型确认后先完成工程基线和脚手架受控生成合同；合同经生命周期批准/持久化后再生成后端脚手架，顺序为：`engineering-baseline -> yss-router scaffold-contract -> lifecycle approval -> yss-ddd-scaffold-generator -> yss-backend-scaffold-parent -> yss-router`。脚手架合同必须记录 `contract_id`、`contract_version`、Router draft、生命周期批准、持久化引用、允许写路径和预期证据。脚手架只生成工程骨架和机械模板；所有后续生成的后端代码都必须消费批准且版本当前的 Slice Implementation Contract、对应 YSS skills 和 YSS Skill Execution Result。
+
 ### 1.4 一个垂直切片 Ticket 只解决一个目标
 
 垂直切片 Ticket 应该围绕一个清晰目标。
@@ -292,20 +294,26 @@ Vue + AntDV 页面优先复用 YSS UI 体系：
 
 ### 4.3 后端按 YSS DDD 顺序推进
 
-从零创建后端服务时先使用 `yss-ddd-scaffold-generator` 生成骨架，确认项目名、基础包名、输出目录和数据库类型。生成后再业务化定制，不要把脚手架直接当最终代码。
+从零创建后端服务时先确认项目名、基础包名、输出目录和数据库类型，由 `yss-router` 编译结构化脚手架工作单元合同并经生命周期批准、持久化为 JSON 后，再使用 `yss-ddd-scaffold-generator --contract-file ...` 生成骨架。生成后再业务化定制，不要把脚手架直接当最终代码；原型确认后的脚手架必须先经过 `yss-backend-scaffold-parent` 和 `yss-router` 合同重编译。
 
 如果只是开发现有服务中的一个功能，不需要重新生成全量脚手架；先读取 `yss-backend-scaffold-parent` 和对应层级 skill，确认本次变更落在哪些层。
 
 推荐顺序：
 
 ```text
-yss-ddd-scaffold-generator
+yss-router（脚手架合同）
+-> 生命周期批准 / 持久化
+-> yss-ddd-scaffold-generator
+-> yss-backend-scaffold-parent
+-> yss-router（合同重编译）
 -> yss-domain / yss-backend-scaffold-domain
 -> yss-repository
 -> yss-mybatis
 -> yss-web-controller
 ```
 
+脚手架和后续代码生成的边界：领域规则、状态机、权限、事务、复杂查询和错误映射必须拆成 `behavior-tdd` 垂直切片；只有工程结构、样板、配置和冻结客户端可使用 `controlled-generation`。`./mvnw validate` 通过不能替代合同批准或 `ready-for-agent`；三条 `./mvnw` 命令必须真实执行并记录 `exit_code`、`duration_ms`、stdout/stderr 引用和执行时间，生成器打印命令不算验证证据。
+
 领域层：
 
 - 先抽业务术语、聚合边界和状态变化。

package/template/scripts/implementation-path-policy.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+# Harness 内运行时代码路径的机器可执行策略。
+module YssImplementationPathPolicy
+  PROJECT_NAME = /\A[a-z][a-z0-9-]*\z/
+  IMPLEMENTATION_KINDS = %w[backend frontend].freeze
+  CONTAINER_ROOTS = %w[apps/backend apps/frontend].freeze
+  FORBIDDEN_ROOTS = %w[app/backend app/frontend].freeze
+
+  module_function
+
+  def normalize(path)
+    return nil unless path.is_a?(String) && !path.empty?
+
+    candidate = path.sub(%r{/$}, "")
+    clean = Pathname.new(candidate).cleanpath.to_s
+    return nil if clean != candidate || Pathname.new(clean).absolute? || clean.start_with?("../")
+
+    clean
+  rescue ArgumentError
+    nil
+  end
+
+  def violation(path, enforce_harness: true)
+    clean = normalize(path)
+    return "implementation path must be a clean relative path" unless clean
+    return nil unless enforce_harness
+
+    parts = clean.split("/")
+    root = parts.take(2).join("/")
+
+    if parts.length >= 2 && parts[0] == "app" && IMPLEMENTATION_KINDS.include?(parts[1])
+      return "singular app implementation root is forbidden: #{root}/"
+    end
+
+    return nil unless parts[0] == "apps" && IMPLEMENTATION_KINDS.include?(parts[1])
+    return "implementation container root is not a project root: #{root}/" if parts.length < 3
+
+    project = parts[2]
+    return "implementation project segment must be a concrete project name: #{project}" unless project.match?(PROJECT_NAME)
+
+    nil
+  end
+
+  def valid?(path, enforce_harness: true)
+    violation(path, enforce_harness: enforce_harness).nil?
+  end
+end

package/template/scripts/sync-skills

@@ -59,6 +59,11 @@ def tree_hash(root)
   digest = Digest::SHA256.new
   root.glob("**/*", File::FNM_DOTMATCH)
       .reject { |item| item.directory? || item.basename.to_s == ".DS_Store" }
+      .reject do |item|
+        relative = item.relative_path_from(root)
+        relative.each_filename.include?("__pycache__") ||
+          %w[.pyc .pyo].include?(item.extname)
+      end
       .sort_by { |item| item.relative_path_from(root).to_s }
       .each do |item|
     relative = item.relative_path_from(root).to_s

package/template/scripts/update-skill-lock

@@ -66,7 +66,13 @@ end
 def tree_hash(root)
   digest = Digest::SHA256.new
   root.glob("**/*", File::FNM_DOTMATCH)
-      .reject { |item| item.directory? || item.basename.to_s == ".DS_Store" }
+      .reject do |item|
+        relative = item.relative_path_from(root)
+        item.directory? ||
+          item.basename.to_s == ".DS_Store" ||
+          relative.each_filename.include?("__pycache__") ||
+          %w[.pyc .pyo].include?(item.extname)
+      end
       .sort_by { |item| item.relative_path_from(root).to_s }
       .each do |item|
     relative = item.relative_path_from(root).to_s

package/template/scripts/verify-implementation-path-scenarios

@@ -0,0 +1,43 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "implementation-path-policy"
+
+valid_paths = {
+  "backend project 1" => "apps/backend/project1/",
+  "backend project 2 nested source" => "apps/backend/project2/src/main/java/",
+  "frontend project 1" => "apps/frontend/project1/",
+  "external repository native path" => "src/main/java/"
+}.freeze
+
+invalid_paths = {
+  "singular backend root" => "app/backend/project1/",
+  "singular frontend root" => "app/frontend/project1/",
+  "backend container root" => "apps/backend/",
+  "frontend container root" => "apps/frontend/",
+  "wildcard project root" => "apps/backend/*/",
+  "traversal" => "apps/backend/project1/../project2/"
+}.freeze
+
+external_native_paths = {
+  "external repository app directory" => "app/backend/src/main/java/",
+  "external repository apps directory" => "apps/backend/project1/src/"
+}.freeze
+
+failures = []
+valid_paths.each do |name, path|
+  failures << "应允许 #{name}: #{YssImplementationPathPolicy.violation(path)}" unless YssImplementationPathPolicy.valid?(path)
+end
+invalid_paths.each do |name, path|
+  failures << "应阻断 #{name}" if YssImplementationPathPolicy.valid?(path)
+end
+external_native_paths.each do |name, path|
+  failures << "外部 native root 不应被 Harness 路径策略误伤 #{name}" unless YssImplementationPathPolicy.valid?(path, enforce_harness: false)
+end
+
+unless failures.empty?
+  warn failures.join("\n")
+  exit 1
+end
+
+puts "实现项目路径策略压力场景验证通过"

package/template/scripts/verify-lifecycle-scenarios

@@ -114,6 +114,10 @@ semantic_markers = {
     "才构成产品设计影响",
     "Spec Delta 只记录相对既有冻结 Spec 基线",
     "template-source",
+    "apps/backend/<project>/",
+    "apps/frontend/<project>/",
+    "app/backend/",
+    "app/frontend/",
     "集中同步",
     "集中记录不得丢失各阶段因果关系"
   ],
@@ -123,6 +127,20 @@ semantic_markers = {
     "最近可信阶段",
     "同一独立执行者",
     "集中 checkpoint"
+  ],
+  "docs/process/implementation-repo-integration.md" => [
+    "apps/backend/<project>/",
+    "apps/frontend/<project>/",
+    "app/backend/",
+    "app/frontend/",
+    "项目容器"
+  ],
+  ".agents/skills/yss-product-lifecycle/SKILL.md" => [
+    "apps/backend/<project>/",
+    "apps/frontend/<project>/",
+    "app/backend/",
+    "app/frontend/",
+    "项目路径策略"
   ]
 }.freeze
 

package/template/scripts/verify-matt-yss-integration-scenarios

@@ -182,7 +182,7 @@ preconditions = contract.fetch("flow_preconditions", {})
 {
   "to-spec" => %w[grill_exit no_unresolved_runnable_blocker],
   "to-tickets" => %w[openapi_freeze_or_no_api_impact required_gates_satisfied vertical_slice_scope blocking_edges],
-  "implement" => %w[ready_for_agent slice_contract_approved slice_contract_persisted slice_contract_current_version build_architecture_checklist implementation_repo implementation_branch ci verification_commands rollback_point backend_slice_contract_if_applicable]
+  "implement" => %w[ready_for_agent slice_contract_approved slice_contract_persisted slice_contract_current_version build_architecture_checklist implementation_repo implementation_branch ci verification_commands rollback_point backend_slice_contract_if_applicable backend_scaffold_policy_satisfied]
 }.each do |flow, required|
   actual = preconditions.dig(flow, "required") || []
   required.each { |field| require_include(failures, "#{flow} preconditions", actual, field) }