create-yss-spec 3.2.0 → 3.3.0

package/template/.agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml

@@ -294,6 +294,17 @@ work_unit_routes:
     human_gate: openapi-freeze_if_api_impact
     applies_when: technical_or_contract_impact
     not_applicable_reason: no_technical_or_contract_impact
+  work-unit.implementation-repository-preparation:
+    native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
+    primary_skill: implementation-repo-onboarding
+    supporting_skills: [yss-implementation-contract-compiler, yss-ddd-scaffold-generator, yss-layered-mvc-scaffold-generator, yss-frontend-scaffold-generator]
+    skills: [implementation-repo-onboarding, yss-implementation-contract-compiler, yss-ddd-scaffold-generator, yss-layered-mvc-scaffold-generator, yss-frontend-scaffold-generator]
+    applies_when: before_ticket_formalization
+    not_applicable_reason: no_frontend_or_backend_delivery_impact
+    decision_boundary: scaffold-choice
+    completion_states: [existing-and-onboarded, initialized-and-verified, not-applicable]
+    aggregate_gate: gate.implementation-repositories-ready
+    must_complete_before: work-unit.ticket-decomposition
   work-unit.ticket-decomposition:
     native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
     primary_skill: yss-product-lifecycle
@@ -342,8 +353,8 @@ work_unit_routes:
   work-unit.code-review:
     native: {source: yss-product-lifecycle, skill: code-review, invocation_mode: model-invoked}
     primary_skill: code-review
-    supporting_skills: [alibaba-java-code-style, yss-ui, yss-design-system, yss-ui-business-page-generation, yss-domain, yss-application, yss-repository, yss-web-controller, yss-dto, mapstruct, lombok]
-    skills: [code-review, alibaba-java-code-style, yss-ui, yss-design-system, yss-ui-business-page-generation, yss-domain, yss-application, yss-repository, yss-web-controller, yss-dto, mapstruct, lombok]
+    supporting_skills: [alibaba-java-code-style, yss-ui, yss-design-system, yss-ui-business-page-generation, yss-domain, yss-application, yss-repository, yss-mybatis, yss-web-controller, yss-dto, mapstruct, lombok]
+    skills: [code-review, alibaba-java-code-style, yss-ui, yss-design-system, yss-ui-business-page-generation, yss-domain, yss-application, yss-repository, yss-mybatis, yss-web-controller, yss-dto, mapstruct, lombok]
     review_standards_route:
       unique_default_skill: code-review
       second_generic_review_skill: forbidden
@@ -354,8 +365,13 @@ work_unit_routes:
         run_if_present: true
         missing_tooling: not-applicable-with-reason
         checkable_rule_without_machine: not-a-pass
+      project_scope:
+        sources: [candidate-project-root, implementation-repository-registry, slice-project-roots, allowed-write-paths]
+        include: [project-itself, registered-backend-development-projects]
+        exclude: [frontend-projects, unrelated-submodules, vendor, unregistered-directories]
+        fixed_apps_backend_assumption: forbidden
       conditional_skills:
-        backend_impact: [alibaba-java-code-style, yss-domain, yss-application, yss-repository, yss-web-controller, yss-dto, mapstruct, lombok]
+        backend_impact: [alibaba-java-code-style, yss-domain, yss-application, yss-repository, yss-mybatis, yss-web-controller, yss-dto, mapstruct, lombok]
         ui_impact: [yss-ui, yss-design-system, yss-ui-business-page-generation]
       not_applicable_reasons:
         backend_impact: no_backend_impact
@@ -399,7 +415,7 @@ compatibility_flow_preconditions:
     evidence: [user_problem, mvp_and_non_goals, success_criteria, test_seam, terminology_review]
     output_role: ready-for-human
   to-tickets:
-    required: [openapi_freeze_or_no_api_impact, required_gates_satisfied, vertical_slice_scope, blocking_edges]
+    required: [openapi_freeze_or_no_api_impact, required_gates_satisfied, implementation_repositories_ready, vertical_slice_scope, blocking_edges]
     output: vertical-slice-tickets
     output_role: ready-for-human
   implement:
@@ -407,6 +423,7 @@ compatibility_flow_preconditions:
     applies_to_single_session: true
 
 ticket_formalization:
+  repository_predecessor: work-unit.implementation-repository-preparation
   implementation_predecessor: work-unit.ticket-decomposition
   result_ref_required: true
   result_must_be: completed
@@ -424,7 +441,37 @@ ticket_formalization:
     current_version: true
   validator:
     module: scripts/lib/lifecycle-transition.mjs
-    functions: [validateNextRoute, validateTicketFormalization, validateImplementationEntry]
+    functions: [validateNextRoute, validateImplementationRepositoriesReady, validateTicketFormalization, validateImplementationEntry]
+
+implementation_repository_preparation:
+  stage: stage.system-data-engineering
+  work_unit: work-unit.implementation-repository-preparation
+  gate: gate.implementation-repositories-ready
+  applies_per_delivery_role: [backend, frontend]
+  affected_role_allowed_states: [existing-and-onboarded, initialized-and-verified]
+  unaffected_role_state: not-applicable
+  not_applicable_reason_required: true
+  existing_repository:
+    required: [repository_ref, project_root, repository_scope, onboarding_result]
+    onboarding_skill: implementation-repo-onboarding
+    architecture_migration: separate-initiative
+  new_repository:
+    default_scope: external-repository
+    allowed_scopes: [external-repository, harness-apps, git-submodule]
+    user_confirmation_required: [scope, project_root, init_git]
+    remote_repository_creation: explicit-authorization-only
+    approved_project_scaffold_contract_required: true
+    frontend_contract_minimum_schema_version: 4
+    backend_contract_compatibility_schema_versions: [3, 4]
+    target_policy: nonexistent-or-empty
+    force_overwrite: forbidden
+    completion_requires: [scaffold_manifest_ref, scaffold_verification]
+  aggregate_result:
+    required: [result, current_version, projects, evidence_refs]
+    result: completed
+    evidence_refs_readable: true
+    stale_action: return-to-work-unit.implementation-repository-preparation
+  blocking_signals: [implementation-repository-decision-required, implementation-repository-location-required, implementation-repository-onboarding-incomplete, scaffold-choice-required, scaffold-contract-unapproved, scaffold-generation-incomplete, scaffold-verification-failed, frontend-template-unavailable, implementation-repositories-stale]
 
 transition_graph:
   validator: scripts/lib/lifecycle-transition.mjs
@@ -437,14 +484,16 @@ transition_graph:
     work-unit.intensity-aware-verification: [work-unit.intensity-aware-review]
     work-unit.intensity-aware-review: [work-unit.release-and-rollback]
     work-unit.release-and-rollback: []
-    work-unit.spec-synthesis: [work-unit.prototype-design, work-unit.technical-analysis, work-unit.ticket-decomposition]
-    work-unit.prototype-design: [work-unit.technical-analysis, work-unit.ticket-decomposition]
-    work-unit.technical-analysis: [work-unit.ticket-decomposition]
+    work-unit.spec-synthesis: [work-unit.prototype-design, work-unit.technical-analysis, work-unit.implementation-repository-preparation]
+    work-unit.prototype-design: [work-unit.technical-analysis, work-unit.implementation-repository-preparation]
+    work-unit.technical-analysis: [work-unit.implementation-repository-preparation]
+    work-unit.implementation-repository-preparation: [work-unit.ticket-decomposition]
     work-unit.ticket-decomposition: [work-unit.slice-implementation]
   forbidden_shortcuts:
     - {from: work-unit.spec-synthesis, to: work-unit.slice-implementation}
     - {from: work-unit.prototype-design, to: work-unit.slice-implementation}
     - {from: work-unit.technical-analysis, to: work-unit.slice-implementation}
+    - {from: work-unit.technical-analysis, to: work-unit.ticket-decomposition}
 
 grill_exit:
   required: [frontier_empty, facts_resolved_or_routed, decisions_confirmed, shared_understanding_confirmed, no_unresolved_runnable_blocker]
@@ -470,6 +519,10 @@ review_input:
   second_generic_review_skill: forbidden
   axes: [standards, spec, ui_fidelity_if_ui_impact]
   standards_sources: [repo_coding_standards, slice_contract_required_skills, specialist_check_inputs, review_report_template]
+  scope_resolution:
+    sources: [candidate-project-root, implementation-repository-registry, slice-project-roots, allowed-write-paths]
+    backend_includes: [project-itself, registered-backend-development-projects]
+    excludes: [frontend-projects, unrelated-submodules, vendor, unregistered-directories]
   completed_requires_specialist_coverage: true
   finding_disposition_required: true
   completed_requires_no_open_mandatory_violations: true
@@ -618,7 +671,11 @@ backend_scaffold:
     layered-mvc: { recipe: backend.mvc-scaffold, generator_skill: yss-layered-mvc-scaffold-generator, baseline_skills: [] }
   tdd_mode: controlled-generation
   contract_schema:
-    schema_version: 3
+    schema_version: 4
+    current_schema_version: 4
+    schema_ref: docs/process/schemas/project-scaffold-contract.schema.json
+    compatible_backend_versions: [3, 4]
+    frontend_minimum_version: 4
     identity: service-engineering-baseline
     required: [contract_id, contract_version, scaffold_request_id, status, compiler_draft_ref, lifecycle_approval_ref, persisted_ref, current_version, implementation_repository, backend_repository, scaffold_status, project_name, target_output_dir, base_package, architecture_family, generator_skill, decision_ref, decision_id, decision_digest, maven_coordinates, profiles, module_profile, allowed_write_paths, expected_evidence_files, verification_commands, approval, work_unit, generation_policy]
     status_by_owner:
@@ -796,7 +853,7 @@ quality_baseline_reuse:
   redefinition: forbidden
 
 ready_for_agent:
-  required: [gates_satisfied, no_stale_artifacts, blockers_closed, implementation_context_ready, context_plan, quality_baseline_ref, implementation_repo, implementation_branch, ci, verification_commands, rollback_point, predecessor_work_unit, ticket_decomposition_result_ref, ticket_decomposition_result_status, vertical_slice_ticket_ref, vertical_slice_ticket_role, vertical_slice_ticket_kind, slice_contract_approved, slice_contract_persisted, slice_contract_current_version, build_architecture_checklist, backend_slice_contract_if_applicable, backend_scaffold_policy_satisfied, frontend_implementation_plan_if_ui_impact]
+  required: [gates_satisfied, no_stale_artifacts, blockers_closed, implementation_context_ready, context_plan, quality_baseline_ref, implementation_repositories_ready, implementation_repository_preparation_ref, implementation_repo, implementation_branch, ci, verification_commands, rollback_point, predecessor_work_unit, ticket_decomposition_result_ref, ticket_decomposition_result_status, vertical_slice_ticket_ref, vertical_slice_ticket_role, vertical_slice_ticket_kind, slice_contract_approved, slice_contract_persisted, slice_contract_current_version, build_architecture_checklist, backend_slice_contract_if_applicable, backend_scaffold_policy_satisfied, frontend_implementation_plan_if_ui_impact]
   ticket_formalization_validator: scripts/lib/lifecycle-transition.mjs
   requires_vertical_slice_ticket: true
   parent_ticket_as_implementation_ref: forbidden

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

@@ -27,6 +27,10 @@ Matt phase boundary 是工作阶段之间的上下文决策，不是新的生命
 
 ## 原型到后端脚手架的接力
 
+阶段 5 在技术分析后固定进入 `work-unit.implementation-repository-preparation`。编排器按 backend / frontend 影响逐项目展示已有或新建工程、Agent 推荐、仓库 scope、目标路径、Git 初始化、验证命令和风险，取得真实用户确认后再执行。已有工程调用 `implementation-repo-onboarding`；新后端按已确认架构调用对应生成器；新前端调用 `yss-frontend-scaffold-generator`。默认 `external-repository`，`harness-apps` / `git-submodule`、`git init` 和远端仓库创建均须显式选择或授权。
+
+所有命中项目必须达到 `existing-and-onboarded` 或 `initialized-and-verified`，未命中的交付面必须有带原因的 `not-applicable`。聚合结果、Manifest、验证和 onboarding 证据必须可读且当前；否则 `gate.implementation-repositories-ready` 阻断 Ticket 正式化。旧实例恢复时保留已有 Ticket，但将相关 Ticket / Slice Contract 标为 `blocked` / `stale` 并返回本工作单元。
+
 `prototype_confirmation` 通过后，先判断实现仓库登记中的 backend `scaffold_status`。当状态为 `required` 时，在工程基线中先完成脚手架架构选择：Agent 按领域复杂度给出 `domain-driven` / `layered-mvc` 推荐和依据，本体选择作为子项目预填默认值，用户通过批量表确认全部项目或逐项覆盖。选择写入 `scaffold-architecture-decisions.yaml`；处于 `undecided`、`recommended`、`awaiting-user-decision` 或 `stale` 时必须阻断，不得默认 DDD，也不得在生成器内交互。
 
 选择达到 `lifecycle-approved` 且 digest 当前后，由 `yss-implementation-contract-compiler` 编译脚手架 schema v3 `controlled-generation` 工作单元合同，生命周期批准并持久化后才能运行对应生成器。顺序为：工程基线与架构推荐 → 用户确认与选择持久化 → 实现合同编译器脚手架合同 draft → 生命周期批准/持久化 → `domain-driven` 使用 `yss-ddd-scaffold-generator` 或 `layered-mvc` 使用 `yss-layered-mvc-scaffold-generator` → 对应基线/Manifest v3 校验 → 实现合同编译器业务合同重编译。`existing` / `initialized` 不重复生成；架构转换必须单独立项。
@@ -58,7 +62,7 @@ tracker 选择和冲突按 `docs/agents/issue-tracker.md` 裁决：已持久化
 - `work-unit.discovery-requirements` 实际调用 `grilling` 和 `domain-modeling`；`work-unit.discovery-opportunity` 按事实类型路由 `competitive-intelligence` 或 `yss-research`。`yss-research:quick` 只用于探索；外部证据进入领域战略、阶段决策或其他生命周期批准输入前必须升级为 `evidence-audited`。生命周期原生工作单元默认负责 Spec、Ticket 和实现资产；`to-spec`、`to-tickets`、`implement` 仅保留为显式兼容入口，结果必须回交生命周期验收。
 - 原生 `work-unit.ticket-decomposition` 只能在 OpenAPI Freeze 或无 API 影响记录后创建垂直切片，初始 Ticket 状态统一为 `ready-for-human`；生命周期复算完整公式后才能提升 `ready-for-agent`。该工作单元必须返回 `ticket_decomposition_result_ref` 和垂直切片引用，并作为实现的必经前置证据。
 - 原生 `work-unit.slice-implementation` 必须在生命周期批准并持久化 Slice Implementation Contract 和 Build Architecture Checklist 后执行；用户显式 `implement` 仍走兼容入口，不得绕过生命周期。
-- `Workflow Execution Result.next_route` 必须通过生命周期转换校验；Spec、原型和技术分析不得直接跳转到 `work-unit.slice-implementation`，只能先进入 `work-unit.ticket-decomposition`。
+- `Workflow Execution Result.next_route` 必须通过生命周期转换校验；Spec、原型和技术分析不得直接跳转到 Ticket 正式化或实现，必须先完成 `work-unit.implementation-repository-preparation`，再进入 `work-unit.ticket-decomposition`。
 - `implement` 遇到 backend `scaffold_status=required` 时，还必须满足原型确认后的脚手架策略：脚手架 Execution Result、`yss-backend-scaffold-parent` 基线、Wrapper 验证和 实现合同编译器 合同重编译均已回写；否则停在工程基线，不得写业务代码。
 - `Workflow Execution Result` 出现 `drift`、`new_impacts`、`stale_candidates`、`violation`、`missing_evidence`、空 `evidence_refs` 或缺少必需字段时暂停当前工作单元；旧结果只能先经只读兼容 adapter 归一化。
 

package/template/.agents/skills/yss-product-lifecycle/references/state-model.md

@@ -41,6 +41,8 @@ required gates ∈ {approved, not-applicable}
 AND 关键决定及当前切片实施范围已有可追溯、当前且未撤回的真实用户批准
 AND related artifacts 不含 stale（若命中技术设计影响，`artifact.technical-design` 必须已批准且版本当前、架构一致；旧 DDD 合同仅按显式兼容入口消费）
 AND blocking edges 全部关闭
+AND `gate.implementation-repositories-ready` 已通过，所有命中的前后端项目均为 `existing-and-onboarded` 或 `initialized-and-verified`，未命中的交付面有带原因的 `not-applicable`
+AND `work-unit.implementation-repository-preparation` 已返回当前且证据可读的 `completed` 结果
 AND implementation repo/branch/CI/test/rollback 已明确
 AND `work-unit.ticket-decomposition` 已返回 `completed`，且其 `ticket_decomposition_result_ref` 证据可读取
 AND `vertical_slice_ticket_ref` 指向 `docs/.scratch/<feature>/issues/` 下的垂直切片 Ticket
@@ -50,7 +52,8 @@ AND Slice Implementation Contract 已由生命周期编排器批准并持久化
 AND Slice Implementation Contract 的 `ticket_ref` 与 `vertical_slice_ticket_ref` 完全一致
 AND 当前工作单元消费的 contract_id/version 与最新批准版本一致
 AND Backend Slice Implementation Contract（后端适用）和 Build Architecture Checklist 已完成
-AND backend 影响且 scaffold_status=required 时，脚手架架构选择已由用户确认并达到 lifecycle-approved、schema v3 合同与 Manifest v3 当前、对应 DDD / Layered MVC 基线、Wrapper 验证和 实现合同编译器重编译均已完成
+AND backend 影响且 scaffold_status=required 时，脚手架架构选择已由用户确认并达到 lifecycle-approved、兼容 schema v3 或统一 schema v4 合同与 Manifest 当前、对应 DDD / Layered MVC 基线、Wrapper 验证和 实现合同编译器重编译均已完成
+AND frontend 影响且无已有工程时，统一 schema v4 Project Scaffold Contract 已批准、持久化且当前，模板 commit 已锁定，`pnpm install --frozen-lockfile` 与工程基线要求的 lint/type-check/build 已实际通过
 AND 所有后续生成代码均绑定主 YSS skill、依赖闭包、允许写路径、预期证据和 YSS Skill Execution Result
 AND UI 影响切片的前端实现还原计划已通过 schema 校验、`template=false`、`status=approved`，且基线引用可读取
 ```
@@ -61,7 +64,7 @@ AND UI 影响切片的前端实现还原计划已通过 schema 校验、`templat
 
 任何 `project-instance` 工作单元进入下一步、任何阶段会签暂停或阶段完成 checkpoint，还必须引用当前工作单元的 `context_reconciliation`。其中 `status=reconciled`、`context_ref=CONTEXT.md`、`document_digest` 与 `referenced_terms_digest` 必须和根目录唯一 `CONTEXT.md` 一致；该证据不改变门禁数量。`template-source` 仅允许以带原因的 `not-applicable` 表示它只校验模板合同，不产生产品业务术语。
 
-用户显式运行 `to-tickets` 后，垂直切片初始 Ticket 状态固定为 `ready-for-human`。原生路径执行 `work-unit.ticket-decomposition` 时同样必须产生等价的垂直切片和 `Workflow Execution Result` 证据。只有 `yss-product-lifecycle` 复算上述公式全部为真后，才能把它提升为 `ready-for-agent`；生命周期不会自动调用 `to-tickets`，但不得跳过 Ticket 正式化工作单元。其默认标签也不参与该裁决。
+用户显式运行 `to-tickets` 后，垂直切片初始 Ticket 状态固定为 `ready-for-human`。原生路径执行 `work-unit.ticket-decomposition` 时同样必须产生等价的垂直切片和 `Workflow Execution Result` 证据。只有 `yss-product-lifecycle` 复算上述公式全部为真后，才能把它提升为 `ready-for-agent`；生命周期不会自动调用 `to-tickets`，但不得跳过实现仓库准备和 Ticket 正式化工作单元。旧实例恢复时若缺少当前工程准备结果，保留既有 Ticket，将 Ticket 与 Slice Contract 标为 `blocked` / `stale` 并回到阶段 5。其默认标签也不参与该裁决。
 
 ## Review 与 Git 授权状态
 

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

@@ -1,86 +1,44 @@
 ---
 name: yss-repository
-description: Use when generating or refactoring YSS Infrastructure persistence models, repositories, MapStruct convertors, Domain Gateway implementations, or metadata/DDL-backed queries.
+description: 用于按批准的 YSS 架构与持久化合同实现或重构 PO、Repository、Convertor、Domain Gateway/Query Adapter；负责结构路由、分层边界和验证，不内置可照抄的业务代码模板。
 ---
 
 # yss-repository
 
-## 架构分流（先执行）
+本 Skill 消费批准合同，将持久化责任落到选定架构 Profile。它不是完整脚手架，也不从 DDL、表名或示例反向创造领域/API 合同。
 
-读取当前合同的 architecture_identity 并与工程基线、仓库登记及 Manifest 核对；再且只读取 `references/profiles/<architecture_profile>.md`。支持的分支为 target-domain-model、layered-mvc-service、mvc-data-analysis-v1；成熟度以注册表为准，不能把 draft 称为受支持。MVC 不执行下文 DDD 专属规则，也不加载其旧分层 guide；组件、安全、批准合同、允许路径及执行证据规则仍共用。
+## 架构分流
 
-以下 Application / Domain Gateway / Infrastructure / Web module 叙述仅适用于 target-domain-model；MVC 的 service/core/repository/server/client 所有权由所选 Profile 引用定义。
+1. 读取当前 Slice Implementation Contract 的 `architecture_identity`、`persistence_profile`、实现仓登记、数据合同、`allowed_write_paths` 和预期证据。
+2. 将架构身份与工程基线、Manifest 和 `docs/agents/yss-skill-registry.yaml` 核对；成熟度以注册表为准，不能把 `draft` 称为已支持。
+3. 根据 `architecture_profile` **且只**加载一个文件：
+   - [target-domain-model](references/profiles/target-domain-model.md)
+   - [layered-mvc-service](references/profiles/layered-mvc-service.md)
+   - [mvc-data-analysis-v1](references/profiles/mvc-data-analysis-v1.md)
+4. Profile 缺失、身份冲突、Manifest 漂移或数据输入不完整时返回 `blocked` / `drift` / `new_impacts`，不得选择“最像”的分支继续。
 
-这是一个偏代码生成和结构补全的 skill，适合在已有工程里补 Repository 层，不适合替代完整脚手架。
+## 共用规则
 
-## 何时使用
+- 只实现批准合同已有的结构与 seam，不创建或改写 Domain Gateway、Application Query Port、service/core 接口或 Web/API DTO。
+- 持久化 Profile 命中 MyBatis 时加载 `yss-mybatis`，以当前组件能力索引核验基类、分页、批量、扫描、XML 和数据源行为；本 Skill 不复制这些规则。
+- POJO、转换和 Java 规范分别消费 Registry 编译出的 `lombok`、`mapstruct`、`alibaba-java-code-style`；不在此重复其注解和处理器规则。
+- 数据合同必须显式覆盖主键、逻辑删除、审计字段、空值、枚举/值对象映射和敏感字段；动态排序、分组与过滤必须使用批准白名单和参数绑定。
+- 事务归所选 Profile 的用例边界。Repository/Gateway Adapter 不临时新增业务事务，也不把数据库异常原文或凭据暴露给上层。
+- 基础机械结构只有在合同标记 `controlled-generation`、metadata 完整且目标文件不存在时才可受控生成；查询语义、分页、并发、事务和迁移行为使用 `behavior-tdd`。
+- 发现 SQL、DDL、索引、数据模型或 API schema 新影响时立即暂停并返回 `new_impacts`，不能以 TODO 代替合同重编译。
 
-- 用户要生成 `PO / Repository / Convertor / GatewayImpl`。
-- 用户已有 Domain 模型，缺基础设施持久层落地。
-- 用户要基于表结构、DDL、metadata 补齐持久层代码。
+## 产物与证据
 
-## 不适用
+实际产物由所选 Profile 和合同共同决定，不以固定示例类名或固定包路径推断。完成前至少证明：
 
-- 只做 Controller 时，优先 `yss-web-controller`。
-- 只做领域建模时，优先 `yss-domain`。
-- 从零建多模块工程时，优先 `yss-ddd-scaffold-generator`。
+- 每个实现类对应已批准的端口或用例调用方；
+- Mapper/Repository、XML、扫描和转换实现可编译且被运行时发现；
+- 保存/重载、查询、分页、空结果、排序白名单和回滚等命中行为有测试；
+- 所有写入位于 `allowed_write_paths`；
+- 使用各后端项目根的 `./mvnw ...` 记录实际命令、退出码和时间。
 
-## 工作方式
+按 [YSS Skill Execution Result v2](../yss-implementation-contract-compiler/references/yss-skill-execution-result.md) 返回实际文件、测试、约束结果、`seam_deferred`、`deviations`、`new_impacts`、`drift` 和 `violation`。
 
-1. 先确认批准且版本当前的 Slice Implementation Contract、数据架构、领域模型和既有 Domain Gateway/Application Query Port；缺任一前置项即返回 `blocked` / `new_impacts`，不得从 DDL 反向猜测领域端口。
-2. 确认持久化 Profile 为 `mybatis-plus` 与 `PO <-> Domain Model`；`Entity + BaseRepository + DTO/VO GatewayImpl` 等旧架构对新脚手架为 `unsupported`。
-3. 如果 metadata 不完整，先补齐 metadata、数据库表结构或 DDL 输入。
-4. 加载并遵守固定 Profile 的 `yss-mybatis`，不得在本 skill 内维护第二套 Mapper、分页或 SQL 安全规则。
-5. 涉及 POJO 字段、getter/setter、constructor、builder 或日志时，必须加载并遵守 `lombok`。
-6. 涉及持久化模型与 Domain/Application Result 转换时，必须加载并遵守 `mapstruct`；Infrastructure 不生成 Web VO/CMD 转换。
-7. 生成代码时严格保持 Domain 与 Infrastructure 分层边界。
-8. 默认先生成基础 CRUD 骨架，把复杂查询留给手工实现。
+## Review 输入
 
-## 产物范围
-
-- `infrastructure/persistence/po/*PO.java`
-- `infrastructure/persistence/repository/*Repository.java`
-- `infrastructure/persistence/convertor/*Convertor.java`
-- `infrastructure/persistence/gateway/*GatewayImpl.java`
-- `infrastructure/query/adapter/*QueryAdapter.java`（实现 Application Query Port）
-- `infrastructure/query/convertor/*QueryConvertor.java`
-
-## 约束
-
-- Domain 不依赖 Infrastructure。
-- Gateway 定义在 Domain，实现放在 Infrastructure。
-- `yss-repository` 不创建或改写 Domain Gateway interface；缺少或需要改变 Gateway 时返回 `new_impacts`，由 实现合同编译器 回到 `yss-domain` / `yss-tactical-design`。
-- Domain Gateway 只交换 Domain Model、领域值和标识；分页、列表和读模型走 Application Query Port，禁止返回 Web VO 或把 `PageQuery` 带入 Domain。
-- PO / Domain Model 等 POJO 样板代码优先使用 Lombok；不要成片手写 getter/setter、constructor、builder 或 logger。
-- Convertor 必须优先使用 `@Mapper(componentModel = "spring")` 和构造器注入；禁止静态 `INSTANCE`、`BeanUtils.copyProperties`、反射式通用拷贝和重复手写字段赋值，除非实现合同记录受控例外、测试和 review 证据。
-- MapStruct 与 Lombok 同时使用时，必须确认注解处理器顺序和 `lombok-mapstruct-binding` 配置；构建命令使用项目根目录 `./mvnw ...`。
-- 逻辑删除、审计字段、主键策略要显式处理，不要隐式略过。
-- 事务放在批准的 Application 用例边界；检测到旧 GatewayImpl 事务布局时返回 `unsupported`，不在 scaffold 链路内迁移。
-
-## 质量门禁
-
-- 生成代码必须可编译。
-- 命名、包路径、注解要与工程现有规范一致。
-- Convertor 必须有 MapStruct 接口 / 抽象类、生成实现可编译，必要时补 mapper 单测或覆盖核心字段转换的行为测试。
-- POJO 使用 Lombok 时不得引入 `@Data` 造成实体 equals / toString 风险；有关系字段、敏感字段或懒加载字段时按 `lombok` skill 排除。
-- 遇到无法自动判断的字段、映射或查询规则时返回 `new_impacts` / `drift` 并暂停，不要把 TODO 当作已完成实现。
-
-## 协同顺序
-
-- metadata / DDL 输入准备：确认输入完整
-- 领域建模：`yss-domain`
-- 用例编排：`yss-application`
-- POJO 样板代码：`lombok`
-- 对象转换：`mapstruct`
-- Web 补齐：`yss-web-controller`
-
-## 分层开发规范
-
-实现 PO / Repository / GatewayImpl 前，必须加载 `references/infrastructure-layer-guide.md`：其中定义持久化对象、Repository、Convertor 与 Gateway 实现的结构与示例。
-
-## 阶段 7 合同
-
-- 前置条件：数据架构、领域元数据、实现仓库和批准后的 `Slice Implementation Contract` 均可用；否则不执行本 skill，由 实现合同编译器 返回 `blocked`。
-- PO/Repository/Convertor 骨架可使用 `controlled-generation`；复杂过滤、分页语义、并发、事务和迁移行为必须拆为 `behavior-tdd`。
-- 写入仅限合同 `allowed_write_paths`，证据必须包含实际 PO、Repository、Convertor、GatewayImpl、测试和 `./mvnw ...` 结果。
-- 按统一 `YSS Skill Execution Result` 返回 `seam_deferred/deviations/new_impacts`；发现数据模型、DDL、SQL、索引或 API schema 变化时暂停并重路由。
+`code-review` 仅对本体项目及合同/实现仓登记的后端研发项目执行本 Skill。候选命中持久化结构或数据访问时，Standards 轴必须读取所选 Profile 并引用规则与代码证据；未命中时记录带原因的 `not-applicable`。Reviewer 只报告 finding，不写实现。

package/template/.agents/skills/yss-repository/agents/openai.yaml

@@ -1,5 +1,5 @@
 version: 1
 interface:
   display_name: "YSS Repository"
-  short_description: "Infrastructure Repository、Mapper、Convertor 与端口实现规范"
-  default_prompt: "Use $yss-repository to implement Infrastructure persistence and query adapters against existing Domain Gateway and Application Query Port interfaces without creating domain contracts."
+  short_description: "按架构 Profile 实现并验证 YSS 持久层结构"
+  default_prompt: "Use $yss-repository to route and implement persistence structures from an approved architecture profile and contract without inventing domain, service, or API contracts."

package/template/.agents/skills/yss-repository/references/profiles/layered-mvc-service.md

@@ -1,3 +1,21 @@
 # layered-mvc-service
 
-先读仓库 `docs/agents/backend-architecture-profiles.md`。依据批准的数据合同写入 repository 的 po/repository/convertor 及 Mapper XML；无需领域模型或 Gateway。使用 `yss-mybatis` 的 MyBatis-Plus 体系；保留 cause，避免向上暴露原始 SQL/凭据。事务由 service 用例拥有。测试覆盖查询、分页、回滚与字段转换；H2 不证明生产方言。生产驱动/数据源接入须另有批准的存储工作单元。
+仅适用于注册表中 `architecture_family=layered-mvc`、用例层为 `service` 的当前合同。先读仓库 `docs/agents/backend-architecture-profiles.md`；Profile 的成熟度沿用注册表。
+
+## 前置与所有权
+
+- 已有批准的 service 用例接口、数据合同和查询/写入语义；不得从表结构反推 service 或 HTTP API。
+- repository module 拥有 PO、Repository/Mapper、XML 和持久化 Convertor；不生成 DDD Domain Gateway、Application Query Port 或 Web DTO。
+- repository 不反向依赖 service、server、client；事务、业务规则和幂等归 service 用例。
+
+## 结构决策
+
+- 包、module、Mapper 扫描和 XML 路径来自 `architecture_identity`、当前工程基线及合同，不使用 DDD Infrastructure 固定布局。
+- MyBatis-Plus 基类、分页、批量和数据源能力由 `yss-mybatis` 当前能力矩阵决定。
+- repository 输出 service 已批准的内部模型或结果，不泄漏 PO、原始 SQL、数据库异常原文或凭据。
+
+## 必须验证
+
+- service 是唯一业务事务边界，Controller 不直连 Repository。
+- Repository/Mapper 覆盖查询、写入、分页、回滚、字段转换和批准数据库 fixture。
+- H2 仅作为验证数据库；生产驱动和数据源必须由单独批准的存储工作单元接入。

package/template/.agents/skills/yss-repository/references/profiles/mvc-data-analysis-v1.md

@@ -1,3 +1,21 @@
 # mvc-data-analysis-v1
 
-遵守 `layered-mvc-service.md`，但事务所有者为 `core`。repository 不依赖 core/client/server，不生成 DDD Gateway。数据分析的动态排序、分组、过滤均须白名单及参数绑定；只消费批准的数据和查询合同。
+仅适用于注册表中的数据分析 MVC Profile。先读仓库 `docs/agents/backend-architecture-profiles.md`；Profile 的成熟度沿用注册表。
+
+## 前置与所有权
+
+- 已有批准的数据合同、查询语义和 core 用例接口；不得从 DDL 或报表字段反推对外 API。
+- repository module 拥有 PO、Repository/Mapper、XML 和持久化 Convertor；不生成 DDD Gateway，也不依赖 core、client、server。
+- 事务、业务规则和查询编排归 core；repository 只实现批准的数据访问 seam。
+
+## 数据分析约束
+
+- 动态排序、分组、过滤、聚合字段和表来源必须来自批准白名单并使用参数绑定；客户端输入不得直接拼接 SQL 标识符或表达式。
+- MyBatis-Plus 基类、分页、批量和数据源能力由 `yss-mybatis` 当前能力矩阵决定，不假设组件提供动态数据源路由。
+- repository 不返回 HTTP DTO，不暴露原始 SQL、数据库错误原文或连接凭据。
+
+## 必须验证
+
+- 查询覆盖白名单边界、空值、空结果、分页 total、稳定排序和大数据量限制。
+- 数据库 fixture 验证实际 Mapper/XML 与方言；H2 不能证明生产数据库的函数、排序或执行计划。
+- core 是唯一业务事务边界，server 不直连 Repository。

package/template/.agents/skills/yss-repository/references/profiles/target-domain-model.md

@@ -1,3 +1,23 @@
 # target-domain-model
 
-完整执行规则见 `../infrastructure-layer-guide.md`。Domain Gateway 和 Application Query Port 必须已存在；本 Skill 只在 Infrastructure 实现，不反向创建领域端口。事务归 Application。
+仅适用于注册表中 `architecture_family=domain-driven` 的当前合同。Profile 的成熟度沿用注册表，不因加载本文件而升级。
+
+## 前置与所有权
+
+- 写模型必须已有批准的 Domain Gateway；读模型必须已有批准的 Application Query Port。缺失或需要改变签名时返回 `new_impacts`，由 `yss-domain` / `yss-application` 和实现合同编译器处理。
+- Infrastructure 实现既有端口，拥有 PO、Repository/Mapper、XML、持久化 Convertor、GatewayImpl 和 QueryAdapter；不拥有领域规则、HTTP DTO 或业务事务。
+- Domain Gateway 只交换 Aggregate、Domain Model、领域值和标识；分页、列表和读模型走 Application Query Port，`PageQuery` 不进入 Domain。
+
+## 结构决策
+
+- 包与 module 必须来自 `architecture_identity` 和现有工程基线；新脚手架的持久化责任位于 Infrastructure，既有工程不得因本 Skill 自动迁移目录。
+- 写模型转换覆盖 `PO <-> Domain Model`；读模型转换只到 Application Result。Infrastructure 不生成或返回 Web VO/CMD。
+- Repository 基类、Mapper/XML、分页与批量能力由 `yss-mybatis` 当前能力矩阵决定，不把组件版本方法名写成领域规则。
+- 事务归 Application 用例。GatewayImpl/QueryAdapter 只执行端口语义，不新增业务编排。
+
+## 必须验证
+
+- Domain 不反向依赖 Infrastructure、Mapper、PO 或组件类型。
+- 经 Domain Gateway 保存后可重新加载语义等价的 Aggregate。
+- Query Port 覆盖分页 total、空结果、排序/过滤白名单和字段转换。
+- Mapper/Repository 使用批准数据库 fixture；H2 不能证明生产方言。

package/template/.agents/skills/yss-repository/tests/profile-routing.test.mjs

@@ -0,0 +1,59 @@
+import assert from "node:assert/strict";
+import { access, readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+const repositorySkillRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const skillsRoot = path.resolve(repositorySkillRoot, "..");
+const projectRoot = path.resolve(skillsRoot, "../..");
+
+async function text(target) {
+  return readFile(target, "utf8");
+}
+
+test("repository router exposes exactly the registered profile entry points", async () => {
+  const profilesRoot = path.join(repositorySkillRoot, "references/profiles");
+  const profiles = (await readdir(profilesRoot)).filter((name) => name.endsWith(".md")).sort();
+  assert.deepEqual(profiles, ["layered-mvc-service.md", "mvc-data-analysis-v1.md", "target-domain-model.md"]);
+
+  const skill = await text(path.join(repositorySkillRoot, "SKILL.md"));
+  for (const profile of profiles) assert.match(skill, new RegExp(`references/profiles/${profile.replace(".md", "")}`));
+  assert.match(skill, /且只.*加载一个文件/);
+  assert.doesNotMatch(skill, /infrastructure-layer-guide/);
+});
+
+test("normative persistence skills do not contain business-specific templates or production source mirrors", async () => {
+  const normativeFiles = [
+    path.join(repositorySkillRoot, "SKILL.md"),
+    ...["layered-mvc-service.md", "mvc-data-analysis-v1.md", "target-domain-model.md"]
+      .map((name) => path.join(repositorySkillRoot, "references/profiles", name)),
+  ];
+  for (const target of normativeFiles) {
+    const contents = await text(target);
+    assert.doesNotMatch(contents, /QualityTemplate|id\.value\(\)|insertOrUpdate\(/);
+  }
+
+  const mybatisAssets = path.join(skillsRoot, "yss-mybatis/assets");
+  try {
+    const javaMirrors = (await readdir(mybatisAssets)).filter((name) => name.endsWith(".java"));
+    assert.deepEqual(javaMirrors, []);
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+});
+
+test("code review wires Repository and MyBatis with registered backend scope", async () => {
+  const standards = await text(path.join(skillsRoot, "code-review/references/yss-review-standards.md"));
+  const report = await text(path.join(projectRoot, "docs/templates/review-report-template.md"));
+  const lifecycle = await text(path.join(skillsRoot, "yss-product-lifecycle/references/orchestration-contract.yaml"));
+
+  for (const source of [standards, report, lifecycle]) {
+    assert.match(source, /yss-repository/);
+    assert.match(source, /yss-mybatis/);
+  }
+  assert.match(standards, /本体项目和已登记后端研发项目/);
+  assert.match(report, /<review-root\.\.\.>/);
+  assert.match(lifecycle, /registered-backend-development-projects/);
+  await access(path.join(skillsRoot, "yss-mybatis/references/source-index.md"));
+});

package/template/.agents/skills/yss-skill-source-index-refresh/SKILL.md

@@ -28,10 +28,11 @@ node "$YSS_SKILLS_ROOT/yss-skill-source-index-refresh/scripts/refresh-yss-skill-
 ```
 
 Backend-only refreshes may set `YSS_REFRESH_FRONTEND=false` to avoid unrelated frontend timestamp churn.
+Use `YSS_REFRESH_BACKEND_SKILLS=yss-mybatis` (comma-separated) to refresh only selected backend indexes and avoid unrelated component churn.
 
 The script updates `references/source-index.md` for backend component skills and `references/frontend-docs.md` for frontend YSS UI skills. Read `references/source-map-config.md` for the full skill-to-source mapping.
 
-中文说明：脚本不会复制大段源码，只会生成可追踪的文档路径、模块路径和关键 Java 入口类，方便 Agent 后续精准读取。
+中文说明：脚本不会复制大段源码；通用组件生成可追踪的入口索引，持久化组件额外生成公开 API、配置开关和能力边界矩阵，方便 Agent 按需读取真实源码。
 
 If `YSS_SOURCE_ROOT` is omitted, the script tries to find a repository containing `yss-microservice-components` from the current workspace and common local project folders. If it cannot find one, set `YSS_SOURCE_ROOT` explicitly.
 
@@ -39,18 +40,20 @@ If `YSS_SOURCE_ROOT` is omitted, the script tries to find a repository containin
 
 Generated source indexes should contain:
 
-- source root and generated timestamp
-- exact source Git commit and worktree state
+- generated timestamp and trace-only source Git commit
+- component-relative tree hashes and component-scoped worktree state
 - component directories and documentation files
 - Maven modules
-- key Java classes matched by names such as annotations, auto configurations, properties, aspects, interceptors, handlers, repositories, DTOs, and result objects
+- source file hashes and relocatable paths
+- for capability-sensitive components, concise public signatures, configuration keys/defaults, conditional activation and capability boundaries extracted from source
+- for other components, key Java classes matched by names such as annotations, auto configurations, properties, aspects, interceptors, handlers, repositories, DTOs, and result objects
 - recommended next reads for Agent when performing implementation or troubleshooting
 
 Do not paste full component source into `SKILL.md`. Keep `SKILL.md` short and let specialists read generated indexes or targeted assets only when needed.
 
 ## Freshness Gate
 
-Before exact class/config/security guidance, compare the index `Source commit` with `git -C "$YSS_SOURCE_ROOT" rev-parse HEAD`. A mismatch or `dirty` indexed state means `stale`: refresh the index or return `blocked`; do not silently rely on the old snapshot. Historical path hints may still be used only to locate current source.
+Before exact class/config/security guidance, compare each indexed `Component tree` with `git -C "$YSS_SOURCE_ROOT" rev-parse HEAD:<component-path>` and check `git status --porcelain -- <component-path>`. A tree mismatch or component-local dirty state means `stale`: refresh the index or return `blocked`; do not silently rely on the old snapshot. A repository commit difference alone is trace metadata and does not make the index stale when the component tree is unchanged. Historical path hints may still be used only to locate current source.
 
 中文说明：`SKILL.md` 保持短小，细节放到 `references/`，这是为了降低每次触发技能时的上下文成本。
 

package/template/.agents/skills/yss-skill-source-index-refresh/references/source-location.md

@@ -6,7 +6,7 @@ YSS skill references may mention paths such as `yss-microservice-components/yss-
 
 1. Check the current workspace first. If `.codegraph/` exists, use `codegraph explore "<class, module, or path hint>"` before text search.
 2. If the component source is outside the workspace, use `YSS_SOURCE_ROOT` when it is set. It should point to the repository root that contains `yss-microservice-components`.
-   Compare `git -C "$YSS_SOURCE_ROOT" rev-parse HEAD` with the selected index `Source commit`; mismatch is `stale` and blocks exact implementation guidance until refresh.
+   Compare every indexed `Component tree` with `git -C "$YSS_SOURCE_ROOT" rev-parse HEAD:<component-path>` and check `git status --porcelain -- <component-path>`. A tree mismatch or component-local dirty state is `stale` and blocks exact implementation guidance until refresh. `Source commit` is trace metadata only; unrelated monorepo changes do not stale an unchanged component tree.
 3. If `YSS_SOURCE_ROOT` is not set, search common local roots such as the current repository parents, `~/Projects`, `~/Documents`, and `~/Documents/yss-project`.
 4. If the source still cannot be found, use the generated `references/source-index.md` as a stale-but-useful map of module names, package names, class names, and Maven artifacts. Do not assume listed files exist locally.
 
@@ -15,4 +15,5 @@ YSS skill references may mention paths such as `yss-microservice-components/yss-
 - Say "source path hints" instead of "source root" unless you have verified the directory in the current environment.
 - Keep generated indexes useful for search, but do not require agents to open those exact paths.
 - Prefer symbols, package names, Maven artifact names, and annotations in instructions; they survive repository relocation better than absolute paths.
+- Keep full production source out of skill `assets/`; generate concise signatures, activation conditions and file hashes instead.
 - When refreshing indexes, export `YSS_SOURCE_ROOT=/absolute/path/to/yss-cloud-microservice` if auto-detection cannot find the component repository.