create-yss-spec 3.4.1 → 3.4.4

package/template/.cursor/skills/yss-web-controller/scripts/generate_controller.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { loadBackendPlatforms, assertPlatformAgreement } from "../../../../scripts/lib/backend-platform.mjs";
 import { createHash } from "node:crypto";
 import { constants, access, copyFile, mkdir, mkdtemp, readFile, rm, unlink, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
@@ -10,8 +11,8 @@ import { assertArchitectureAgreement, validateArchitectureIdentity } from "../..
 
 const TYPE_MAPPING = { bigint: "Long", int: "Integer", integer: "Integer", smallint: "Integer", tinyint: "Integer", number: "Long", numeric: "BigDecimal", decimal: "BigDecimal", float: "Float", double: "Double", real: "Float", varchar: "String", varchar2: "String", nvarchar2: "String", char: "String", nchar: "String", text: "String", clob: "String", nclob: "String", date: "LocalDateTime", datetime: "LocalDateTime", timestamp: "LocalDateTime", "timestamp with time zone": "LocalDateTime", boolean: "Boolean", bool: "Boolean", bit: "Boolean", json: "String", jsonb: "String", uuid: "String" };
 const PLATFORM_VALIDATION_NAMESPACES = {
-  "spring-boot-2.7-jdk8": "javax",
-  "spring-boot-3-jdk17": "jakarta"
+  ...Object.fromEntries(loadBackendPlatforms().profiles.map(profile => [profile.id, profile.validation_namespace])),
+  "spring-boot-3-jdk17": "jakarta" // Existing-project compatibility only; new scaffolds use exact catalog profiles.
 };
 const required = ["metadata-file", "contract-file", "dto-wire-profile-file", "base-package", "module-name", "domain-segment"];
 const valued = new Set([...required, "output-dir", "web-project-dir", "web-output-dir", "author", "application-service-package", "validation-namespace", "scaffold-manifest-file"]);
@@ -170,6 +171,8 @@ async function validateContract(contract, args) {
   if (implementationRoot !== scaffoldRoot) throw new Error("implementation_project_root does not match the scaffold manifest project root");
   const expectedWebProject = mvc ? path.join(scaffoldRoot, `${manifest.project_name}-server`) : path.join(scaffoldRoot, `${manifest.project_name}-adapter`, `${manifest.project_name}-web`);
   if (!args["web-project-dir"] || path.resolve(args["web-project-dir"]) !== expectedWebProject) throw new Error("--web-project-dir does not match the scaffold manifest project layout");
+  if (manifest.platform_verification === "candidate") throw new Error("backend-platform: candidate scaffold is not ready for downstream generation");
+  if (manifest.platform_configuration) assertPlatformAgreement(manifest.platform_configuration, contract.architecture_identity?.platform_configuration);
   const profilePairs = mvc ? [["platform", "platform_profile"], ["validation_namespace", "validation_namespace"]] : [["architecture", "architecture_profile"], ["platform", "platform_profile"], ["validation_namespace", "validation_namespace"], ["dto_placement", "dto_placement"]];
   for (const [manifestField, contractField] of profilePairs) {
     if (manifest.profiles?.[manifestField] !== contract[contractField]) throw new Error(`scaffold manifest ${manifestField} profile does not match the approved Web contract`);

package/template/.cursor/skills/ytable-usage/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ytable-usage
-description: 指导 YSS UI 业务列表页、CRUD 表格、远程分页、操作列、气泡确认、列筛选、字典翻译、行拖拽、工具栏和自定义插槽正确使用 @yss-ui/components 的 YTable；当需要配置 YTableColumn、YTableActionConfig、pagination、filter-change 或表格实例方法时使用。
+description: "配置或修复 YSS UI YTable 的列、分页、行操作、筛选、拖拽与插槽；完整列表流程用 page-list-module。"
 ---
 
 # YTable 使用

package/template/.cursor/skills/ytree-usage/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ytree-usage
-description: 指导 YSS UI 左树右表、组织树、分类树、目录树和节点管理页使用 @yss-ui/components 的 YTree，覆盖 fieldNames 字段映射、搜索过滤、受控选中、节点动作、删除确认、虚拟滚动和自适应高度；当生成或修改树形筛选、左树右表、树搜索或树节点操作时使用。
+description: "配置或修复 YSS UI YTree 的字段映射、搜索、选中与节点操作；用于树形筛选和节点管理。"
 ---
 
 # YTree 使用

package/template/.pi/skills/archify/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: archify
-description: Create polished, validated architecture, workflow, sequence, data-flow, and lifecycle/state diagrams as explorable standalone HTML with inline SVG, dark/light themes, optional trace motion, and PNG/JPEG/WebP/SVG/WebM export. Accept plain-language requirements or pasted Mermaid flowchart, sequenceDiagram, and stateDiagram input; inspect repository evidence when the diagram must reflect real code. Use when the user asks to visualize system architecture, infrastructure, cloud/security/network topology, technical workflows, API call sequences, request lifecycles, data pipelines, ETL/ELT, data lineage, state machines, or to convert/beautify Mermaid.
+description: "Create interactive HTML architecture, workflow, sequence, data-flow or state diagrams. Use for requested diagrams or Mermaid conversion."
 license: MIT
 metadata:
   version: "2.16"

package/template/.pi/skills/code-review/SKILL.md

@@ -9,7 +9,7 @@ Review of a pinned candidate against a fixed point on two core axes, plus UI fid
 - **Spec** — does the code faithfully implement the originating issue / spec?
 - **UI fidelity** (only when the change has UI impact) — does the candidate match the confirmed prototype and `yss-design-system` / `yss-ui`? Type-check or claiming "already aligned" is not a pass. Invoke those skills' verification notes; do not collapse this axis into Standards or Spec. YSS page-module conventions stay on Standards.
 
-Standards and Spec run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings. When UI is in scope, add a separate UI fidelity pass after those two reports (do not merge it into either axis).
+普通功能默认由一名与实现者独立的审查者完成 Standards、Spec 和适用的 UI fidelity 检查，分别报告结论。只有专业能力缺口、结论冲突、明确外部制度或用户指定时，才拆成多个审查者；多个无依赖审查可以并行。检查轴不等于会签人数，不能要求用户为每个轴重复确认。
 
 If `docs/agents/issue-tracker.md` is missing, tell the user to run `/setup-matt-pocock-skills`; do not invoke another user-invoked skill yourself.
 
@@ -34,7 +34,7 @@ Choose one candidate mode from the request or an upstream review contract:
   - each untracked file's content, using `git diff --no-index --no-ext-diff --binary --full-index -- /dev/null <path>` when a diff representation is useful. Exit code `1` from this command means a difference was found, not that review failed;
   - `git log <fixed-point>..HEAD --oneline` for the committed portion of the candidate.
 
-Record one **candidate manifest** before spawning reviewers:
+Record one **candidate manifest** before review:
 
 ```yaml
 review_mode: committed # or worktree
@@ -51,9 +51,9 @@ commit_list_command: <command>
 
 For a Committed candidate, resolve `HEAD` to an immutable commit and tree before review. Its manifest must include `merge_base`, `tracked_diff_command` and `commit_list_command`. For a Worktree candidate, the manifest must additionally include `untracked_inventory_command`, `untracked_diff_command` and the exact `untracked_files` inventory.
 
-For a Worktree candidate, capture the tracked binary diff and every untracked file's bytes once into an immutable snapshot, compute `candidate_digest`, and make that **captured candidate** available to both reviewers. The following is normative, not illustrative: use the `yss-worktree-candidate-v1` byte stream. Start with ASCII `YSS-WORKTREE-CANDIDATE-V1` followed by one NUL byte. Append one tracked record: byte `0x54`, unsigned 64-bit big-endian binary-diff byte length, then the exact stdout bytes from `git diff --no-ext-diff --binary --full-index <merge-base>`. Then append one untracked record for each NUL-delimited raw path from `git ls-files -z --others --exclude-standard`, sorted bytewise by the raw path: byte `0x55`, unsigned 64-bit big-endian path length, raw path bytes, unsigned 32-bit big-endian `lstat` mode, entry-kind byte (`0x52` regular or `0x4c` symlink), unsigned 64-bit big-endian content length, then raw regular-file bytes or raw symlink-target bytes. Other entry kinds block capture. This is the sole length-prefixed framing and bytewise path order for the digest. SHA-256 is calculated over exactly this stream. New captures use a previously nonexistent directory under `.template-source/evidence/maintenance/`, land atomically, and store exactly `candidate-manifest.yaml`, `candidate.bin` and `tracked.diff`; `candidate.bin` already contains every untracked byte, so do not duplicate hundreds of `untracked-content/000xxx` files. Explicit exclusions are fail-closed to `.template-source/evidence/maintenance/` evidence and cannot exclude implementation or authority assets. Historical per-file snapshots remain readable. Both reviewers must consume the captured stream and must not independently treat a live worktree as the reviewed candidate.
+For a Worktree candidate, capture the tracked binary diff and every untracked file's bytes once into an immutable snapshot, compute `candidate_digest`, and make that **captured candidate** available to the assigned reviewer(s). The following is normative, not illustrative: use the `yss-worktree-candidate-v1` byte stream. Start with ASCII `YSS-WORKTREE-CANDIDATE-V1` followed by one NUL byte. Append one tracked record: byte `0x54`, unsigned 64-bit big-endian binary-diff byte length, then the exact stdout bytes from `git diff --no-ext-diff --binary --full-index <merge-base>`. Then append one untracked record for each NUL-delimited raw path from `git ls-files -z --others --exclude-standard`, sorted bytewise by the raw path: byte `0x55`, unsigned 64-bit big-endian path length, raw path bytes, unsigned 32-bit big-endian `lstat` mode, entry-kind byte (`0x52` regular or `0x4c` symlink), unsigned 64-bit big-endian content length, then raw regular-file bytes or raw symlink-target bytes. Other entry kinds block capture. This is the sole length-prefixed framing and bytewise path order for the digest. SHA-256 is calculated over exactly this stream. New captures use a previously nonexistent directory under `.template-source/evidence/maintenance/`, land atomically, and store exactly `candidate-manifest.yaml`, `candidate.bin` and `tracked.diff`; `candidate.bin` already contains every untracked byte, so do not duplicate hundreds of `untracked-content/000xxx` files. Explicit exclusions are fail-closed to `.template-source/evidence/maintenance/` evidence and cannot exclude implementation or authority assets. Historical per-file snapshots remain readable. Every assigned reviewer must consume the captured stream and must not independently treat a live worktree as the reviewed candidate.
 
-Before going further, confirm the fixed point and merge-base resolve. A committed candidate must have a non-empty committed diff. A Worktree candidate is non-empty when either its tracked diff or untracked inventory is non-empty. A bad ref, missing candidate part or empty candidate should fail here — not inside two parallel sub-agents. Do not silently downgrade Worktree review to `HEAD`-only review.
+Before going further, confirm the fixed point and merge-base resolve. A committed candidate must have a non-empty committed diff. A Worktree candidate is non-empty when either its tracked diff or untracked inventory is non-empty. A bad ref, missing candidate part or empty candidate should fail here — not during professional review. Do not silently downgrade Worktree review to `HEAD`-only review.
 
 ### 2. Identify the spec source
 
@@ -66,7 +66,7 @@ Look for the originating spec, in this order:
 
 ### 3. Identify the standards sources
 
-Compile sources **before** spawning reviewers. For YSS implementation candidates follow [yss-review-standards.md](references/yss-review-standards.md): run machine checks that exist in the implementation repo; then collect repo docs (`CODING_STANDARDS.md` / `CONTRIBUTING.md` if present), every Slice `required_skills` skill file, the impact-conditioned specialist inputs (`alibaba-java-code-style`, `yss-ui`, `yss-domain`, …), and `docs/templates/review-report-template.md`. Missing applicable coverage is `missing_evidence`, not a pass.
+Compile sources **before** review. For YSS implementation candidates follow [yss-review-standards.md](references/yss-review-standards.md): run machine checks that exist in the implementation repo; then collect repo docs (`CODING_STANDARDS.md` / `CONTRIBUTING.md` if present), every Slice `required_skills` skill file, the impact-conditioned specialist inputs (`alibaba-java-code-style`, `yss-ui`, `yss-domain`, …), and `docs/templates/review-report-template.md`. Missing applicable coverage is `missing_evidence`, not a pass.
 
 For YSS backend review, derive the review roots from the candidate project root, implementation-repository registry, Slice `project_roots` and `allowed_write_paths`. Review only the project itself and registered backend development projects; exclude frontend roots, unrelated submodules/vendor trees and unregistered directories. Never replace this resolution with a fixed `apps/backend` assumption.
 
@@ -94,7 +94,9 @@ Each smell reads *what it is* → *how to fix*; match it against the diff:
 - **Middle Man** — a class or function that mostly just delegates onward. → cut it, call the real target direct.
 - **Refused Bequest** — a subclass or implementer that ignores or overrides most of what it inherits. → drop the inheritance, use composition.
 
-### 4. Spawn both sub-agents in parallel
+### 4. Complete each applicable review axis
+
+默认由当前独立 Reviewer 连续完成下列两份检查提纲，按轴保留结论，不派发额外 subagent。需要多专业参与时，按角色表和协作协议派发对应提纲；只增加缺少的能力，不默认启动两个额外 Agent。下面的 sub-agent prompts 同样是单 Reviewer 的检查清单。
 
 **Standards sub-agent prompt** — include:
 
@@ -111,13 +113,15 @@ Each smell reads *what it is* → *how to fix*; match it against the diff:
 
 If the spec is missing, skip the Spec sub-agent and note this in the final report.
 
+普通审查只复验修复影响的结论及其依赖；候选摘要变化后仍须重新绑定当前候选，不能沿用过期证据。未受影响项记录依据后复用。已明确采用下节历史候选/多轴合同的审查继续遵守其约定。
+
 ### 5. Aggregate
 
 For template-maintenance task packages carrying `review_round`, preserve the frozen scope and apply the two-round convergence contract. A hard requirement added during review must cite a rule that already applied when the candidate was frozen; otherwise report it as `judgement-call` for the backlog. Round 1 blocking findings return to the implementer and require a new digest plus all review axes. If Round 2 still has an open `violation`, `drift`, or `new_impacts`, return `needs-human` and stop; do not silently start Round 3. Candidate byte changes invalidate every earlier axis report.
 
-Present the reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. If UI is in scope, add `## UI fidelity` from the separate pass. Fill `docs/templates/review-report-template.md` specialist tables as part of Standards evidence, not a fourth axis. Do **not** merge or rerank findings — the axes are deliberately separate (see _Why separate axes_). A YSS candidate with blank applicable specialist rows, skipped `required_skills`, or unaddressed mandatory violations is `blocked`, not `completed`. Do not close findings by writing implementation in the review session. `violation` / machine-check failure / blank applicable rows go back to the implementer on the original contract path, then recapture the candidate and rerun every axis. `drift` / `new_impacts` / `required_skills` mismatch mark the contract `stale` and return to 实现合同编译器; do not keep coding on the old contract. `not-applicable` is only for untriggered impacts; mandatory gates have no waiver, only repair or a complete `seam-deferred` record.
+Present the reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. If UI is in scope, add `## UI fidelity` from the separate pass. Fill `docs/templates/review-report-template.md` specialist tables as part of Standards evidence, not a fourth axis. Do **not** merge or rerank findings — the axes are deliberately separate (see _Why separate axes_). A YSS candidate with blank applicable specialist rows, skipped `required_skills`, or unaddressed mandatory violations is `blocked`, not `completed`. Do not close findings by writing implementation in the review session. `violation` / machine-check failure / blank applicable rows go back to the implementer on the original contract path, then recapture the candidate and rerun affected axes and their dependencies; explicitly rebind unchanged evidence. `drift` / `new_impacts` / `required_skills` mismatch mark the contract `stale` and return to 实现合同编译器; do not keep coding on the old contract. `not-applicable` is only for untriggered impacts; mandatory gates have no waiver, only repair or a complete `seam-deferred` record.
 
-For Worktree mode, recapture the candidate digest after both reports return. If it differs from `candidate_digest`, mark both reports as reviewing a **stale candidate** and return `blocked`; the caller may start a new review against a new capture, but this invocation must not aggregate findings from different bytes. Recheck the same digest again at the completion/checkpoint boundary.
+For Worktree mode, recapture the candidate digest after all applicable checks finish. If it differs from `candidate_digest`, mark the affected reports as reviewing a **stale candidate** and return `blocked`; the caller may start a new review against a new capture, but this invocation must not aggregate findings from different bytes. Recheck the same digest again at the completion/checkpoint boundary.
 
 State the reviewed `review_mode`, fixed point, candidate digest and coverage before the two reports. End with a one-line summary: total findings per axis, and the worst issue _within each axis_ (if any). Don't pick a single winner across axes — that's the reranking the separation exists to prevent.
 

package/template/.pi/skills/file-export-download/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: file-export-download
-description: 指导 Vue3 YSS UI 微应用实现文件导出、报表下载、模板下载和附件下载，覆盖 OpenAPI binary 响应、Orval 生成方法检查、responseType blob 兜底、Blob 响应类型、Content-Disposition 文件名、handleBlobResponse、loading 与错误处理；当需求出现导出、下载、Excel、CSV、PDF、ZIP、Blob 或文件流时使用。
+description: "在 Vue3 YSS UI 中实现或修复文件下载与导出，处理 Orval 文件流、Blob、文件名和错误响应。"
 ---
 
 # YSS 文件导出下载 Skill

package/template/.pi/skills/frontend-commit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: frontend-commit
-description: 分析并提交 Vue、React、TypeScript、JavaScript、Vite、微前端和前端 monorepo 项目的 Git 改动；当用户要求生成 commit message、检查提交规范、拆分原子提交、暂存并执行 git commit，或修复 commitlint 与 commit-msg hook 拒绝时使用。读取仓库实际规则和 diff，选择业务 scope，生成英文 type/scope 与中文标题和正文，并安全验证提交。
+description: "为前端改动生成提交信息、审查原子提交或修复 Git hook；用户明确要求提交时执行 git commit。"
 ---
 
 # 前端规范提交

package/template/.pi/skills/java-backend-commit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: java-backend-commit
-description: 分析并提交 Java、Spring Boot、Maven、Gradle、单体服务和多模块后端项目的 Git 改动；当用户要求生成 commit message、检查提交规范、拆分原子提交、暂存并执行 git commit，或修复 commitlint 与 commit-msg hook 拒绝时使用。读取仓库实际规则、模块结构和 diff，选择服务或业务域 scope，生成英文 type/scope 与中文标题和正文，并安全验证提交。
+description: "为 Java 后端改动生成提交信息、审查原子提交或修复 Git hook；用户明确要求提交时执行 git commit。"
 ---
 
 # Java 后端规范提交

package/template/.pi/skills/llm-wiki/SKILL.md

@@ -1,11 +1,6 @@
 ---
 name: llm-wiki
-description: >
-  Compile and maintain a Karpathy-pattern LLM wiki (raw + wiki + schema) with
-  init, incremental refresh, global rebuild, lint, and narrow ingest. Use when
-  the user wants a local knowledge wiki, incremental wiki refresh, wiki rebuild,
-  compiling a named research note into the wiki, `/llm-wiki`, or an answer from
-  an existing wiki.
+description: "Build or refresh a local LLM wiki; use for wiki init, ingest, rebuild, lint, or source-backed wiki questions."
 ---
 
 # llm-wiki

package/template/.pi/skills/lombok/SKILL.md

@@ -1,22 +1,9 @@
 ---
 name: lombok
-description: |
-  Project Lombok for reducing Java boilerplate. Covers annotations for getters,
-  setters, constructors, builders, logging, and more. Based on production
-  patterns from castellino and gestionale-presenze projects.
-
-  USE WHEN: user mentions "lombok", "@Data", "@Builder", "@Slf4j", asks about
-  "boilerplate reduction", "getters/setters", "@RequiredArgsConstructor", "@Value"
-
-  DO NOT USE FOR: Java language features - use `java` skill instead
-  DO NOT USE FOR: MapStruct integration - use `mapstruct` skill
-  DO NOT USE FOR: Spring annotations - use `backend-spring-boot` skill
-allowed-tools: Read, Grep, Glob, Write, Edit
+description: "配置或排查 Lombok 注解、构造器、Builder 和注解处理器；按对象身份与敏感字段选择生成范围。"
 ---
 # Project Lombok
 
-> **Deep Knowledge**: Use `mcp__documentation__fetch_docs` with technology: `lombok` for comprehensive documentation.
-
 ## YSS 阶段 7 执行结果
 
 - 消费工程 Java 与处理器基线；三个新后端 Profile 为 Java 8。MapStruct binding 进入 annotationProcessorPaths，不作为业务依赖单独引入；示例不授权升级依赖。MVC PO 的身份/敏感字段风险与 DDD 相同，不能默认全量 @Data。
@@ -24,329 +11,16 @@ allowed-tools: Read, Grep, Glob, Write, Edit
 - 受控生成必须记录对象类型、选用/排除注解、实体关系和敏感字段风险、编译/测试实际结果。
 - 按 `yss-implementation-contract-compiler` 的统一 Execution Result 返回 changed files、证据、偏离和新增影响；`@Data` 实体风险、处理器配置缺失或越界路径返回 `violation`。
 
-## Maven Configuration
-
-```xml
-<dependency>
-    <groupId>org.projectlombok</groupId>
-    <artifactId>lombok</artifactId>
-    <version>1.18.34</version>
-    <optional>true</optional>
-</dependency>
-
-<!-- For MapStruct compatibility -->
-<dependency>
-    <groupId>org.projectlombok</groupId>
-    <artifactId>lombok-mapstruct-binding</artifactId>
-    <version>0.2.0</version>
-</dependency>
-```
-
-## Common Annotations
-
-### @Data (All-in-One)
-
-```java
-@Data
-public class User {
-    private Long id;
-    private String name;
-    private String email;
-}
-
-// Generates:
-// - @Getter for all fields
-// - @Setter for all non-final fields
-// - @ToString
-// - @EqualsAndHashCode
-// - @RequiredArgsConstructor
-```
-
-### @Getter / @Setter
-
-```java
-public class User {
-    @Getter @Setter
-    private String name;
-
-    @Getter // Read-only
-    private final String email;
-
-    @Setter(AccessLevel.PROTECTED)
-    private String internalId;
-}
-```
-
-### @NoArgsConstructor / @AllArgsConstructor / @RequiredArgsConstructor
-
-```java
-@NoArgsConstructor
-@AllArgsConstructor
-public class User {
-    private Long id;
-    private String name;
-}
-
-@RequiredArgsConstructor
-public class UserService {
-    private final UserRepository userRepository; // Included in constructor
-    private final UserMapper userMapper;         // Included in constructor
-    private String cacheName;                    // NOT included
-}
-```
-
-### @Builder
-
-```java
-@Data
-@Builder
-public class User {
-    private Long id;
-    private String name;
-    private String email;
-    @Builder.Default
-    private UserStatus status = UserStatus.ACTIVE;
-}
-
-// Usage
-User user = User.builder()
-    .name("John")
-    .email("john@example.com")
-    .build();
-
-// With toBuilder for updates
-User updated = user.toBuilder()
-    .name("Jane")
-    .build();
-```
-
-### @Value (Immutable)
-
-```java
-@Value
-public class UserResponse {
-    Long id;
-    String name;
-    String email;
-    LocalDateTime createdAt;
-}
-
-// Generates:
-// - All fields are private final
-// - @AllArgsConstructor
-// - @Getter (no setters)
-// - @ToString
-// - @EqualsAndHashCode
-```
-
-## Entity Pattern
-
-```java
-@Entity
-@Table(name = "users")
-@Getter
-@Setter
-@NoArgsConstructor(access = AccessLevel.PROTECTED)
-@AllArgsConstructor(access = AccessLevel.PRIVATE)
-@Builder
-@EntityListeners(AuditingEntityListener.class)
-public class User {
-
-    @Id
-    @GeneratedValue(strategy = GenerationType.IDENTITY)
-    private Long id;
-
-    @Column(nullable = false)
-    private String name;
-
-    @Column(unique = true, nullable = false)
-    private String email;
-
-    @Enumerated(EnumType.STRING)
-    @Builder.Default
-    private UserStatus status = UserStatus.ACTIVE;
-
-    @CreatedDate
-    @Column(updatable = false)
-    private LocalDateTime createdAt;
-
-    @LastModifiedDate
-    private LocalDateTime updatedAt;
-
-    @ManyToOne(fetch = FetchType.LAZY)
-    @JoinColumn(name = "department_id")
-    private Department department;
-}
-```
-
-JPA/DDD entities must not default to `@Data`; choose equality and `toString` deliberately from stable identity and exclude lazy, relationship, and sensitive fields.
+## 按需读取
 
-## Service Pattern with Constructor Injection
+先确认当前任务涉及的对象与批准合同，只读取对应参考段落：
 
-```java
-@Service
-@RequiredArgsConstructor
-@Slf4j
-public class UserServiceImpl implements UserService {
-
-    private final UserRepository userRepository;
-    private final UserMapper userMapper;
-    private final PasswordEncoder passwordEncoder;
-
-    @Override
-    public UserResponse create(CreateUserRequest dto) {
-        log.info("Creating user: {}", dto.getEmail());
-        User user = userMapper.toEntity(dto);
-        return userMapper.toResponse(userRepository.save(user));
-    }
-}
-```
-
-## Logging
-
-```java
-@Slf4j  // SLF4J logger
-public class UserService {
-    public void process() {
-        log.info("Processing...");
-        log.debug("Debug info: {}", data);
-        log.error("Error occurred", exception);
-    }
-}
-
-@Log4j2  // Log4j2 logger
-@CommonsLog  // Apache Commons Logging
-@JBossLog  // JBoss Logging
-```
-
-## DTO Pattern
-
-```java
-// Request DTO
-@Data
-public class CreateUserRequest {
-    @NotBlank
-    private String name;
-    @Email
-    private String email;
-    @Size(min = 8)
-    private String password;
-}
-
-// Response DTO (immutable)
-@Value
-@Builder
-public class UserResponse {
-    Long id;
-    String name;
-    String email;
-    UserStatus status;
-    LocalDateTime createdAt;
-}
-```
-
-## @Cleanup
-
-```java
-public void readFile(String path) throws IOException {
-    @Cleanup InputStream in = new FileInputStream(path);
-    // in.close() called automatically
-}
-```
-
-## @SneakyThrows
-
-```java
-@SneakyThrows  // Wraps checked exception
-public String readConfig() {
-    return new String(Files.readAllBytes(Paths.get("config.json")), StandardCharsets.UTF_8);
-}
-```
-
-## @Synchronized
-
-```java
-public class Counter {
-    @Synchronized
-    public void increment() {
-        // Thread-safe
-    }
-}
-```
-
-## @With (Immutable Updates)
-
-```java
-@Value
-@With
-public class Point {
-    int x;
-    int y;
-}
-
-Point p1 = new Point(1, 2);
-Point p2 = p1.withX(5);  // Point(5, 2)
-```
-
-## Key Annotations
-
-| Annotation | Purpose |
-|------------|---------|
-| `@Data` | Getter, Setter, ToString, Equals, Constructor |
-| `@Value` | Immutable class |
-| `@Builder` | Builder pattern |
-| `@RequiredArgsConstructor` | Constructor for final fields |
-| `@Slf4j` | Logger field |
-| `@ToString.Exclude` | Exclude from toString |
-| `@EqualsAndHashCode.Exclude` | Exclude from equals/hashCode |
-
----
-
-## When NOT to Use This Skill
-
-| Scenario | Use Instead |
-|----------|-------------|
-| Java core language | `java` skill |
-| MapStruct mapping | `mapstruct` skill |
-| Spring annotations | `backend-spring-boot` skill |
-| JPA entities complex logic | Manual implementation |
-| Public API design | Explicit methods for clarity |
-
----
-
-## Anti-Patterns
-
-| Anti-Pattern | Why It's Bad | Correct Approach |
-|--------------|--------------|------------------|
-| @Data on JPA entities | toString/equals issues | Use @Getter/@Setter selectively |
-| Not excluding lazy relations | LazyInitializationException | Use @ToString.Exclude |
-| @EqualsAndHashCode on entities | Proxy issues | Use @EqualsAndHashCode(onlyExplicitlyIncluded = true) |
-| @SneakyThrows everywhere | Hides exceptions | Use proper exception handling |
-| @Builder without @Default | Null fields | Add @Builder.Default |
-| @Value with mutable fields | Breaks immutability | Use only immutable types |
-| Mixing @Data and manual methods | Confusing API | Be consistent |
-| Not configuring in lombok.config | Inconsistent behavior | Use lombok.config file |
-
----
-
-## Quick Troubleshooting
-
-| Issue | Cause | Solution |
-|-------|-------|----------|
-| "Cannot find symbol" for getters | IDE not processing | Enable annotation processing |
-| LazyInitializationException | toString on lazy relation | Add @ToString.Exclude |
-| MapStruct not working | Wrong processor order | Lombok before MapStruct |
-| Builder missing fields | No @Builder.Default | Add defaults or check config |
-| StackOverflowError in equals | Circular reference | Exclude relation fields |
-| IDE shows errors but compiles | IDE cache | Invalidate caches/restart |
-| @Slf4j logger not found | SLF4J not in classpath | Add SLF4J dependency |
-| Generated code not visible | delombok needed | Run delombok task |
-
----
+| 任务 | 参考 |
+|---|---|
+| 构造器、Builder、默认值或不可变对象 | [Common Annotations](references/annotation-examples.md#common-annotations) |
+| 实体身份、关联与敏感字段 | [Entity Pattern](references/annotation-examples.md#entity-pattern) |
+| 注解处理器与 MapStruct 集成 | [Maven Configuration](references/annotation-examples.md#maven-configuration)，映射逻辑交给 `mapstruct` |
 
-## Reference Documentation
-- [Lombok Documentation](https://projectlombok.org/features/)
-- [Stable Features](https://projectlombok.org/features/all)
-- [Configuration](https://projectlombok.org/features/configuration)
+选择注解前核查生成的 equals/hashCode/toString 是否符合对象身份与数据边界。敏感字段不能进入生成的 toString 或日志；实体不默认使用全量 `@Data`。依赖和处理器版本复用工程基线，修改生成行为后编译受影响模块，并验证实际生成的访问器、构造器或身份行为。
 
-> **Deep Knowledge**: Use `mcp__documentation__fetch_docs` with technology: `lombok` for comprehensive documentation.
+查第三方行为时使用 `yss-research`，来源为 [Lombok 官方文档](https://projectlombok.org/features/)；不假定某个 MCP 工具已安装。