create-yss-spec 2.1.10 → 2.1.13

package/template/.cursor/skills/alibaba-java-code-style/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: alibaba-java-code-style
+description: Apply Alibaba Java Development Manual conventions when implementing, refactoring, or reviewing Java/JVM code, Spring-style services, MyBatis/ORM mappings, SQL, Maven dependencies, unit tests, exception/logging behavior, security checks, and design documentation. Use when the user asks for Java code规范, 阿里规范, P3C-style review, Java code style, or compliance with Alibaba Java coding guidelines.
+---
+
+# Alibaba Java Code Style
+
+This skill distills the provided `阿里巴巴 Java 开发手册` 1.4.0 PDF into execution rules for Codex. Treat rules marked mandatory as review blockers unless the repository's own `AGENTS.md`, security constraints, or existing framework conventions explicitly require a different pattern.
+
+## Workflow
+
+1. Identify the touched surface:
+   - Java source, naming, constants, OOP, collections, concurrency, control flow, comments: read `references/java-programming.md`.
+   - Exceptions, logging, unit tests, or security: read `references/reliability-test-security.md`.
+   - MySQL, ORM/MyBatis, Maven dependencies, layering, server/JVM settings, or design artifacts: read `references/database-engineering-design.md`.
+2. Apply mandatory rules first, then use recommended rules to improve maintainability, performance, and readability.
+3. When reviewing, report mandatory violations as findings. Mention recommended violations when they create real risk or are already in the changed area.
+4. When implementing, prefer the repository's existing framework helpers and code generation skills over inventing new local infrastructure.
+5. If a rule touches a project safety boundary such as auth, payment, encryption, raw SQL, database migration scripts, or public base library API changes, produce a draft or `TODO-HUMAN-REVIEW` rather than silently finalizing risky code.
+
+## Core Priorities
+
+- Keep names readable, English, and consistent with Java layer conventions.
+- Avoid null, equality, wrapper comparison, collection, and concurrency traps that compile cleanly but fail at runtime.
+- Make logs useful without wasting CPU, disk, or alert budget.
+- Keep unit tests automatic, independent, repeatable, and close to public behavior.
+- Bind SQL parameters, define explicit ORM mappings, and never rely on string-concatenated SQL.
+- Preserve layering: web/controller code validates and adapts; service/manager code owns business orchestration; DAO/repository code owns persistence.
+
+## Review Checklist
+
+- Naming and formatting are consistent: camel case, constants, package names, braces, spacing, line length, UTF-8/Unix line endings.
+- POJO, DTO, DO, VO, Query, enum, interface, implementation, and test names follow the expected suffixes and boolean naming rules.
+- `equals`, `hashCode`, wrapper comparisons, `toString`, `serialVersionUID`, constructors, access modifiers, and getters/setters avoid known pitfalls.
+- Collection code avoids unsafe `subList`, `Arrays.asList`, raw `toArray`, foreach removal, null-unsafe maps, and invalid comparators.
+- Thread code uses named thread pools, avoids `Executors` factories in production code, and handles locking order, date formatting, and scheduled tasks safely.
+- Exceptions are handled at the right layer, logged once with context and stack, and never swallowed or used for normal control flow.
+- Tests use assertions, avoid external dependence, live under `src/test/java`, and cover boundaries, correct cases, design cases, and error cases.
+- Security-sensitive inputs are validated, authorized, escaped, CSRF-protected, rate-limited, and never concatenated into SQL.
+- MySQL DDL/SQL/ORM code uses explicit fields, mappings, indexes, timestamps, `#{}`
+  parameter binding, and avoids dangerous cascades, stored procedures, `select *`, and uncontrolled pagination.
+
+## Source
+
+Based on the user-provided PDF: `阿里巴巴 Java 开发手册` version 1.4.0, Alibaba Group technical team, update date 2018-05-20.
+
+## 阶段 7 执行结果
+
+- 消费当前合同版本、changed files 和 verification results，只审查合同允许范围。
+- 必须把 mandatory violation 返回为 `violation`，并提供文件/位置/规则证据；高风险项保留 `TODO-HUMAN-REVIEW`。
+- 按统一 `YSS Skill Execution Result` 返回审查证据、偏离和新增安全/SQL/公共 API 影响，不得仅输出“符合规范”。

package/template/.cursor/skills/alibaba-java-code-style/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Alibaba Java Code Style"
+  short_description: "Apply Alibaba Java development guidelines"
+  default_prompt: "Use $alibaba-java-code-style to implement or review Java code against Alibaba Java development conventions."

package/template/.cursor/skills/alibaba-java-code-style/references/database-engineering-design.md

@@ -0,0 +1,147 @@
+# Database, Engineering, And Design Rules
+
+Use this reference for MySQL DDL/SQL, ORM mappings, Maven/library dependency rules, application layering, server/JVM settings, and design artifacts.
+
+## MySQL Table Design
+
+Mandatory:
+
+- Boolean database fields must be named `is_xxx` and use `unsigned tinyint`, where `1` means yes and `0` means no. POJO boolean fields must not use `is` prefix, so define explicit ORM mappings.
+- Table and field names must be lowercase letters or digits. Do not start with digits, use uppercase, or use patterns such as `level_3_name`.
+- Table names must be singular.
+- Do not use MySQL reserved words such as `desc`, `range`, `match`, or `delayed`.
+- Index names: primary key `pk_字段名`, unique index `uk_字段名`, normal index `idx_字段名`.
+- Use `decimal` for decimals. Do not use `float` or `double` for precise stored values.
+- Use `char` for nearly fixed-length strings.
+- `varchar` length must not exceed 5000. For longer content, use `text` in a separate table keyed by the primary key to avoid hurting other index efficiency.
+- Every table must include `id`, `gmt_create`, and `gmt_modified`. `id` is `bigint unsigned` primary key with auto-increment step 1 for single tables; timestamps are `datetime`.
+
+Recommended/reference:
+
+- Prefer table names like `业务名称_表作用`.
+- Keep database name aligned with application name where possible.
+- Update field comments when field meaning or status values change.
+- Redundant fields are allowed for performance only when consistency is considered, the value is not frequently changed, and the field is not long `varchar` or `text`.
+- Consider sharding only when a single table exceeds about 5 million rows or 2 GB, or when projections clearly require it.
+- Choose compact unsigned integer types where domain ranges allow.
+
+## Indexes
+
+Mandatory:
+
+- Business-unique fields must have unique indexes, even when uniqueness is also checked in application code.
+- Do not join more than 3 tables. Join column types must be exactly consistent and associated columns must have indexes.
+- When indexing `varchar`, specify an index length based on real selectivity instead of indexing the whole field.
+- Page search must not use left fuzzy or full fuzzy queries such as `%keyword` or `%keyword%`; use a search engine when needed.
+
+Recommended/reference:
+
+- For `order by`, align the ordered field with the last part of the composite index where possible, such as `where a=? and b=? order by c` with index `a_b_c`.
+- Use covering indexes to avoid table lookups where suitable.
+- For deep pagination, use delayed join/subquery techniques to locate IDs first, or cap total pages.
+- SQL optimization target: at least `range`, preferably `ref`, best `const`.
+- Put the most selective equality column on the left side of composite indexes. When mixed with range conditions, place equality conditions first.
+- Avoid implicit type conversion, which can invalidate indexes.
+- Avoid both extremes: indexing every query and resisting necessary indexes such as unique indexes.
+
+## SQL And ORM
+
+Mandatory:
+
+- Use `count(*)` for row counts, not `count(column)` or `count(constant)`.
+- Know `count(distinct col)` ignores nulls; `sum(col)` over all-null rows returns null, so guard against NPE.
+- Use `ISNULL()` or the project-standard equivalent to test nulls; direct equality comparisons with null do not behave as true/false.
+- In pagination code, return immediately when count is 0 instead of running the page query.
+- Do not use foreign keys or cascades; model those relationships in application logic for distributed/high-concurrency systems.
+- Do not use stored procedures in application code.
+- For data correction, especially delete/update, select first and confirm before mutating.
+- In queries, never use `*`; explicitly list required fields.
+- POJO boolean fields must not use `is` prefix, while database fields must use `is_`; define explicit result mappings.
+- Do not rely on `resultClass` for ORM returns. Define `resultMap` or equivalent explicit mappings.
+- MyBatis/iBATIS XML parameters must use `#{}`. Do not use `${}` for user-controlled values because it risks SQL injection.
+- Do not return raw `HashMap`/`Hashtable` as query results; use typed objects.
+- Every update to a table record must update `gmt_modified` to the current time.
+
+Recommended/reference:
+
+- Avoid large `IN` lists; keep them under about 1000 items if unavoidable.
+- For internationalized storage, use UTF-8; use `utf8mb4` when storing emoji.
+- Avoid `TRUNCATE TABLE` in application code; it has no transaction and does not trigger delete behavior.
+- Do not create a large all-fields update API. Update only changed target fields to reduce mistakes, binlog size, and work.
+- Do not overuse `@Transactional`; consider database QPS and rollback/compensation for cache, search, messages, and statistics.
+
+## Application Layering
+
+Recommended/reference:
+
+- Follow downward dependencies:
+  - Open API layer: exposes service methods as RPC/HTTP, handles gateway security and traffic controls.
+  - Terminal display layer: templates, JavaScript rendering, JSP, or mobile display.
+  - Web layer: forwarding, access control, basic parameter validation, and simple non-reused business handling.
+  - Service layer: concrete business logic.
+  - Manager layer: common business handling, third-party platform adaptation, service common capability extraction, cache/middleware handling, and DAO composition.
+  - DAO layer: persistence interaction with MySQL, Oracle, HBase, etc.
+  - External interfaces: other departments' RPC APIs, base platforms, or third-party HTTP APIs.
+- Exception handling by layer:
+  - DAO catches broad persistence exceptions and wraps them as `DAOException`; do not log again if the upper layer will log.
+  - Service logs exceptions with parameters and context.
+  - Manager follows DAO behavior when deployed with Service, or Service behavior when independently deployed.
+  - Web should not keep throwing to users; render friendly errors when the page cannot proceed.
+  - Open API converts exceptions to error code and message.
+- Domain model meanings:
+  - `DO`: database table object, passed upward by DAO.
+  - `DTO`: transfer object from Service/Manager outward.
+  - `BO`: business object output by Service.
+  - `AO`: application object between Web and Service, close to display and not highly reusable.
+  - `VO`: view object for Web/template rendering.
+  - `Query`: query request object. If a query has more than 2 parameters, wrap them; do not pass `Map`.
+
+## Maven And Library Dependencies
+
+Mandatory:
+
+- Use GAV conventions where applicable: `GroupId` as `com.{company/BU}.business[.subBusiness]`, `ArtifactId` as `product-module`, version as `major.minor.patch`.
+- Version meaning: major for direction/large incompatibility/architecture changes, minor for mostly compatible major features, patch for compatible bugfixes/minor features. Initial formal release should be `1.0.0`.
+- Online applications must not depend on `SNAPSHOT` versions except explicitly allowed security packages.
+- Adding/upgrading a library must preserve dependency mediation outside the intended functional change. Compare `dependency:resolve`/`dependency:tree` and exclude accidental differences.
+- Library APIs may define enum types and accept enum parameters, but should not return enum values or POJOs containing enum values across external library boundaries.
+- Define one version variable for a group of related libraries to avoid version drift.
+- Do not declare the same `GroupId` and `ArtifactId` with different versions across subprojects.
+
+Recommended/reference:
+
+- Put dependency declarations under `<dependencies>` and version mediation under `<dependencyManagement>`.
+- Avoid adding configuration items to reusable libraries unless truly necessary.
+- Library publishers should keep APIs/dependencies minimal and behavior stable/traceable.
+
+## Server And JVM
+
+Recommended/reference:
+
+- For high-concurrency servers, reduce TCP `time_wait` timeout where operations policy allows.
+- Increase maximum file descriptors for high concurrent connection counts.
+- Set `-XX:+HeapDumpOnOutOfMemoryError` so OOM events produce diagnostic dumps.
+- In production, set JVM `Xms` and `Xmx` to the same size to avoid heap resizing pressure after GC.
+- Use `forward` for internal redirects. Generate external redirect URLs through URL builder utilities to avoid inconsistent maintenance and potential security risk.
+
+## Design Rules
+
+Mandatory:
+
+- Storage schemes and base data structures must pass review and be documented before production execution. Data structure changes such as adding fields also need review.
+- If more than one user type interacts with the system and related use cases exceed 5, use a use-case diagram.
+- If a business object's states exceed 3, use a state diagram and define trigger conditions for state transitions.
+- If a feature call chain involves more than 3 objects, use a sequence diagram and define inputs/outputs at each call.
+- If model classes exceed 5 and dependencies are complex, use a class diagram.
+- If more than 2 objects collaborate and the process is complex, use an activity diagram with swimlanes where useful.
+
+Recommended/reference:
+
+- Consider exception flows and business boundaries during requirements analysis and system design.
+- Classes should follow single responsibility.
+- Prefer composition/aggregation over inheritance. If inheritance is necessary, obey Liskov substitution.
+- Depend on abstractions and interfaces where it improves extension and maintenance.
+- Design for extension and closed modification in stable business domains.
+- Extract common business behavior or public behavior into shared modules, config, classes, or methods to avoid duplicated code/config.
+- Do not treat agile as only stories plus coding plus release; keep necessary design and documentation for key decisions.
+- Design identifies hard parts, variation points, boundaries, module relations, evolution principles, and nonfunctional requirements such as security, availability, and extensibility.

package/template/.cursor/skills/alibaba-java-code-style/references/java-programming.md

@@ -0,0 +1,178 @@
+# Java Programming Rules
+
+Use this reference for Java implementation and review: naming, constants, formatting, OOP, collections, concurrency, control flow, comments, and general coding traps.
+
+## Naming
+
+Mandatory:
+
+- Do not start or end identifiers with `_` or `$`.
+- Do not mix pinyin and English; do not use Chinese identifiers. Widely recognized names such as `alibaba`, `taobao`, `youku`, and `hangzhou` are acceptable.
+- Use `UpperCamelCase` for classes, except suffix acronyms such as `DO`, `BO`, `DTO`, `VO`, `AO`, `PO`, and `UID`.
+- Use `lowerCamelCase` for methods, parameters, member variables, and local variables.
+- Use uppercase words separated by underscores for constants, with complete semantics such as `MAX_STOCK_COUNT`.
+- Name abstract classes with `Abstract` or `Base` prefixes, exception classes with `Exception` suffixes, and test classes as the tested class name plus `Test`.
+- Put brackets next to the type for arrays: `String[] args`, not `String args[]`.
+- Do not prefix POJO boolean properties with `is`; frameworks may mis-detect the property name. Map database `is_xxx` fields explicitly.
+- Package names must be lowercase, singular, dot-separated, and each segment should be one natural English word.
+- Avoid nonstandard abbreviations that hide meaning.
+
+Recommended/reference:
+
+- Prefer complete words for self-explanatory names.
+- If a module, interface, class, or method uses a design pattern, reflect the pattern in the name, such as `OrderFactory`, `LoginProxy`, or `ResourceObserver`.
+- Interface methods and fields should omit redundant `public` modifiers and include useful Javadoc.
+- For `Service` and `DAO`, expose interfaces and name implementations with `Impl`.
+- Capability interfaces may use adjective names such as `Translatable`.
+- Enum class names may end with `Enum`; enum members use uppercase underscores.
+- Layer method prefixes: `get` for one object, `list` for multiple objects, `count`, `save`/`insert`, `remove`/`delete`, and `update`.
+- Model suffixes: `xxxDO`, `xxxDTO`, `xxxVO`; do not name a class `xxxPOJO`.
+
+## Constants
+
+Mandatory:
+
+- Do not use magic values directly in code. Define named constants.
+- Use uppercase `L` for `long`/`Long` literals, never lowercase `l`.
+
+Recommended:
+
+- Do not keep every constant in one universal constant class. Group by function and scope.
+- Choose the smallest sensible reuse scope: cross-application library, application, submodule, package, or class-local `private static final`.
+- Use `enum` when values vary only within a fixed set, especially when values have attributes.
+
+## Formatting
+
+Mandatory:
+
+- For non-empty blocks, put `{` on the same line, newline after `{`, newline before `}`, and keep `} else {` on one line. Empty blocks may be `{}`.
+- Do not put spaces immediately inside parentheses. Put one space before `{`.
+- Put one space between reserved words and `(` for `if`, `for`, `while`, `switch`, and `do`.
+- Put one space around binary and ternary operators.
+- Use 4 spaces for indentation; do not use tab characters.
+- `//` comments must have exactly one space after the slashes.
+- Keep lines at or below 120 characters. When wrapping, indent the second line 4 spaces, keep operators and dots with the following line, wrap method arguments after commas, and do not break before `(`.
+- Add a space after commas in method definitions and calls.
+- Use UTF-8 and Unix line endings.
+
+Recommended:
+
+- Keep a single method under 80 lines, including signature, braces, code, comments, blank lines, and invisible characters.
+- Do not align variables by adding decorative spaces.
+- Insert one blank line between different logical or business sections; avoid multiple blank lines.
+
+## OOP And POJO
+
+Mandatory:
+
+- Access static members through the class name, not an object reference.
+- Add `@Override` to all overridden methods.
+- Use varargs only for same-type, same-meaning arguments; avoid `Object...`.
+- Do not change method signatures of externally used APIs or library APIs. Deprecate old interfaces with `@Deprecated` and document replacements.
+- Do not use deprecated classes or methods.
+- Call `equals` on constants or known non-null objects, or use `Objects.equals`.
+- Compare wrapper objects of the same type with `equals`, not `==`.
+- Use wrapper types for all POJO fields and RPC parameters/returns; prefer primitive types for local variables.
+- Do not set default values on DO/DTO/VO fields.
+- When adding fields to serializable classes, do not change `serialVersionUID` unless the change is intentionally incompatible.
+- Do not put business logic in constructors; use an init method or lifecycle hook.
+- POJO classes must implement `toString`; include `super.toString()` when extending another POJO.
+- Do not define both `isXxx()` and `getXxx()` for the same POJO property.
+
+Recommended:
+
+- Before indexing into `String.split` results, account for trailing separators.
+- Keep overloaded methods and multiple constructors adjacent.
+- Order methods as public/protected methods, private methods, then getters/setters, except overloaded groups.
+- Setter parameter names should match field names and use `this.field = field`.
+- Do not add business logic to getters or setters.
+- Use `StringBuilder.append` for string concatenation inside loops.
+- Use `final` for non-inheritable classes, non-overridable methods, immutable references, non-reassigned locals, or to avoid variable reuse confusion.
+- Be careful with `Object.clone`; default clone is shallow.
+- Minimize access scope: private constructors for non-instantiable classes, no public/default constructors in utility classes, private fields and methods unless broader access is truly required, and consider `final` for static fields.
+
+## Collections
+
+Mandatory:
+
+- If overriding `equals`, also override `hashCode`.
+- Objects stored in `Set` or used as `Map` keys must implement both `equals` and `hashCode`.
+- Do not cast `ArrayList.subList` results to `ArrayList`; it is a view.
+- Do not structurally modify the original list while iterating or changing a `subList`.
+- Convert collections to arrays with `toArray(new T[list.size()])`, not raw `toArray()`.
+- Do not call mutating methods on `Arrays.asList` results.
+- Respect PECS: `? extends T` is for producers/readers and cannot safely accept `add`; `? super T` is for consumers/writers and cannot safely provide typed `get`.
+- Do not remove/add elements inside foreach loops; use an `Iterator` and `iterator.remove()`. Lock the iterator if operations are concurrent.
+- Comparators must be symmetric, transitive, and handle equality consistently.
+
+Recommended:
+
+- Use diamond syntax or type inference where supported.
+- Specify initial collection capacity where size is known; for `HashMap`, use roughly `expectedSize / 0.75 + 1`, or default 16 when unknown.
+- Iterate maps with `entrySet` or `Map.forEach` when both key and value are needed.
+- Know map null support: `ConcurrentHashMap` and `Hashtable` reject null keys/values; `TreeMap` rejects null keys; `HashMap` allows null keys/values.
+- Use set uniqueness to de-duplicate rather than repeated `List.contains`.
+
+## Concurrency
+
+Mandatory:
+
+- Singleton acquisition and singleton methods must be thread-safe.
+- Name threads and thread pools meaningfully.
+- Provide thread resources through thread pools; do not create raw application threads casually.
+- Do not create production thread pools through `Executors`; use `ThreadPoolExecutor` so queue size, thread count, rejection policy, and resource limits are explicit.
+- Do not use static `SimpleDateFormat` without synchronization. Prefer `DateTimeFormatter`/`java.time`, `ThreadLocal`, or a safe date utility.
+- In high concurrency, minimize lock cost: prefer lock-free structures, small locked blocks, and object locks over class locks where suitable.
+- Keep a consistent lock acquisition order across resources to avoid deadlock.
+- For concurrent updates to one record, use application/cache locks or database optimistic locks with a `version` field; retry optimistic locks at least 3 times.
+- Prefer `ScheduledExecutorService` over `Timer` for multiple scheduled tasks, because one uncaught `TimerTask` exception stops other tasks.
+
+Recommended/reference:
+
+- With `CountDownLatch`, call `countDown` in `finally` or otherwise guarantee it runs even on exceptions.
+- Prefer `ThreadLocalRandom` over shared `Random`/`Math.random` in concurrent code.
+- If using double-checked locking on JDK 5+, declare the target field `volatile`.
+- `volatile` solves visibility for one writer/many readers but not compound writes; use `AtomicInteger`, `AtomicLong`, or `LongAdder` for counters.
+- Avoid unsynchronized high-concurrency `HashMap` resizing; use concurrent collections or locking.
+- Declare `ThreadLocal` fields as `static` when the per-thread value should be shared by all instances of the class.
+
+## Control Flow And Parameters
+
+Mandatory:
+
+- Every `switch` case must end with `break`, `return`, or a comment explaining fallthrough. Every `switch` must have a final `default`.
+- Always use braces for `if`, `else`, `for`, `while`, and `do`, even for one line.
+- In high-concurrency exit logic, avoid equality-only checks; prefer range checks that cannot be skipped by concurrent changes.
+- Do not exceed 3 levels of `if/else`; use guard clauses, strategy, or state pattern.
+
+Recommended:
+
+- Prefer guard clauses for exceptional branches.
+- Do not put complex expressions inside conditions. Assign them to well-named boolean variables first.
+- Move object creation, connection acquisition, unnecessary try/catch, and other expensive operations outside loops where possible.
+- Avoid negated logic when an equivalent positive condition is available.
+- Protect interface parameters, especially batch operations.
+- Validate parameters for low-frequency, expensive, high-stability, external, or sensitive-permission methods.
+- You may omit repeated validation for hot private or low-level methods only when callers have already validated and method docs state the expectation.
+
+## Comments And General Rules
+
+Mandatory:
+
+- Use Javadoc (`/** ... */`) for classes, fields, and methods. Do not use `//` as class or method API documentation.
+- Abstract methods and interface methods need Javadoc explaining purpose, parameters, returns, exceptions, and implementation notes.
+- Classes must include creator and creation date if the repository convention requires Alibaba manual compliance; otherwise follow local project header policy.
+- Place single-line comments above the code they explain. Align multi-line block comments with code.
+- Every enum value must have a comment explaining its purpose.
+- Precompile regular expressions; do not call `Pattern.compile` repeatedly inside method bodies.
+- Use `System.currentTimeMillis()` for current milliseconds, not `new Date().getTime()`. Use `System.nanoTime()` for elapsed time measurement; Java 8 may use `Instant`.
+
+Recommended/reference:
+
+- Prefer clear Chinese comments over awkward English; keep technical terms in English.
+- Update comments when changing parameters, returns, exceptions, or core logic.
+- Delete dead code. If temporarily commenting code, explain why above it.
+- Keep comments concise and focused on design intent, business meaning, and non-obvious logic.
+- Mark `TODO`/`FIXME` with owner, date, and expected handling time when possible.
+- Do not put complex logic in view templates.
+- Specify data structure capacity where possible.

package/template/.cursor/skills/alibaba-java-code-style/references/reliability-test-security.md

@@ -0,0 +1,89 @@
+# Reliability, Test, And Security Rules
+
+Use this reference for exception handling, logging, unit testing, and security-sensitive Java work.
+
+## Exception Handling
+
+Mandatory:
+
+- Do not catch avoidable runtime exceptions such as `NullPointerException` or `IndexOutOfBoundsException`; prevent them with prechecks.
+- Do not use exceptions for normal process or branch control.
+- Keep try blocks focused on unstable code. Catch specific exception types where behavior differs.
+- Never swallow caught exceptions. Handle them, translate them to user-understandable content at the outer business boundary, or rethrow.
+- In transactional code, if a caught exception requires rollback, explicitly trigger rollback according to the framework.
+- Always close resources and streams in `finally` or use try-with-resources. Handle close exceptions appropriately.
+- Do not `return` from a `finally` block.
+- Caught exception types must match thrown exceptions exactly or be an appropriate parent type.
+
+Recommended/reference:
+
+- A method may return `null`, but must document when that can happen. Callers remain responsible for NPE prevention.
+- Check common NPE sources: auto-unboxing wrapper return values, database nulls, null elements inside non-empty collections, remote calls, session reads, and chained calls such as `a.getB().getC()`.
+- Distinguish unchecked and checked exceptions. Avoid `new RuntimeException()`, `Exception`, or `Throwable` without business meaning; prefer domain-specific exceptions such as `DAOException` or `ServiceException`.
+- Public external HTTP/API interfaces should use error codes. Internal application code may throw exceptions. Cross-application RPC can prefer a result wrapper with success flag, code, and brief message.
+- Avoid duplicate code; extract common validation or behavior into methods/classes/components.
+
+## Logging
+
+Mandatory:
+
+- Use SLF4J facade APIs, not direct Log4j/Logback APIs:
+
+```java
+private static final Logger logger = LoggerFactory.getLogger(Abc.class);
+```
+
+- Keep application logs for at least 15 days when configuring retention.
+- Name extension logs as `appName_logType_logName.log`, where `logType` can be `stats`, `monitor`, `access`, etc.
+- For `trace`/`debug`/`info`, use placeholder logging or guard with `isXxxEnabled`; do not eagerly concatenate strings.
+- Avoid duplicate log printing, such as missing `additivity=false` in Log4j configuration.
+- Exception logs must include both scene/context information and stack trace. If not handled locally, throw upward.
+
+Recommended:
+
+- Production must not output debug logs. Emit info selectively.
+- Use `warn` for user input errors when no system fault occurred; reserve `error` for system logic errors, exceptions, or important failures.
+- Prefer English error messages where possible; use Chinese only when English would be unclear. Internationalized or overseas deployments require English logs/comments.
+- Before adding logs, ask whether someone will read them and what action they enable.
+
+## Unit Tests
+
+Mandatory:
+
+- Unit tests must follow AIR: Automatic, Independent, Repeatable.
+- Tests must be fully automated and non-interactive. Use assertions, not `System.out`, for verification.
+- Tests must not call each other or depend on execution order.
+- Tests must be repeatable and isolated from external environments such as network, remote services, or middleware. Inject local or mock dependencies.
+- Unit test granularity should be small: usually method-level, at most class-level.
+- Incremental code for core businesses, core applications, and core modules must pass unit tests.
+- Test code belongs under `src/test/java`, not production source directories.
+
+Recommended/reference:
+
+- Basic target: statement coverage at least 70%; core modules should reach 100% statement and branch coverage where feasible.
+- Use BCDE coverage thinking:
+  - Border: boundary values, loop boundaries, special values, special times, data ordering.
+  - Correct: valid inputs and expected outputs.
+  - Design: cases derived from design documents.
+  - Error: invalid data, exception flows, and disallowed business inputs.
+- Database tests should prepare data through programmatic insert/import, not manual pre-existing database edits.
+- Database tests should rollback automatically or mark generated data with a clear prefix.
+- Refactor untestable code instead of writing awkward tests to satisfy coverage.
+- Avoid business code that makes tests hard: heavy constructors, excessive globals/statics, too many external dependencies, and deep conditionals.
+
+## Security
+
+Mandatory:
+
+- User-owned pages or functions must perform authorization checks, including horizontal permission checks.
+- Sensitive user data must be masked before display, such as mobile numbers with hidden middle digits.
+- SQL parameters from users must use parameter binding or metadata-limited fields. Do not concatenate SQL strings.
+- Every user request parameter must be validated. Consider memory overflow, malicious `order by`, open redirect, SQL injection, deserialization injection, and ReDoS risks.
+- Do not output user data to HTML without proper filtering or escaping.
+- Forms and AJAX submissions must enforce CSRF protection.
+- Platform resources such as SMS, email, phone calls, orders, and payments must implement replay prevention, rate limits, fatigue control, or captcha as appropriate.
+
+Recommended:
+
+- User-generated content such as posts, comments, and instant messages should have anti-abuse, rate-limit, and prohibited-content controls.
+- Treat auth, payment, encryption, raw SQL, and database migration work as high-risk. If repository instructions mark them human-review-only, add `TODO-HUMAN-REVIEW` and do not present drafts as production-ready.

package/template/.cursor/skills/ask-matt/PHASE-BOUNDARIES.md

@@ -0,0 +1,55 @@
+# Phase boundaries
+
+A **phase** is a chunk of work inside a session — the grilling, the implementation, the QA. The definition is fuzzy on purpose: a phase ends when you think *"ok, we're done with that"*.
+
+The **phase boundary** is the gap between two phases, and it is the only place this decision belongs. Mid-phase there is no decision to make — continue, or split the work that's left into subagents. Compacting mid-phase makes the agent lose the thread.
+
+## The five options
+
+| Option       | What it does                                                    |
+| ------------ | --------------------------------------------------------------- |
+| **Continue** | Stay in the session. No context switch at all.                    |
+| **`/clear`** | Empty the context window and start from nothing.                  |
+| **`/handoff`** | Write a portable markdown file and seed a session anywhere with it. |
+| **Subagent** | Send the task to its own context window and get a report back.     |
+| **`/compact`** | Compress this context and seed a fresh session with the summary.  |
+
+## The tree
+
+Work top to bottom at the boundary. The first **yes** wins.
+
+**1. Can you continue in this session?** Two things make the answer yes: the next phase needs this phase as a **primary source**, or you have enough [smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone) left (~150k tokens) for the next phase to fit. Grilling → implementation is the standard yes: the implementation wants the reasoning verbatim, not a summary of it. Continue costs nothing and loses nothing, so rule it out before anything else.
+
+**2. Is the context irrelevant to what comes next?** Is everything in this session — the exploration, the decisions, the dead ends — disposable? If so, **`/clear`**. It is the cheapest move on the board: it takes no time and hands back the whole window. `/clear` also isn't terminal — the old session stays resumable.
+
+The cost of getting this wrong is one-way. Clear a *relevant* context and you lose the **why** behind what you built, and no amount of reading the diff back gets it returned.
+
+**3. Do you need to hand off?** `/handoff` is narrow. You need it only when you are:
+
+- swapping to a **new harness** (Claude → Codex),
+- moving to a **new directory** or repo,
+- sending the work to a **colleague**,
+- or forking a side task you found **mid-phase** without derailing what you're doing.
+
+That list is the whole clause. What `/handoff` buys is **portability** — a file that travels. If nothing is travelling, you don't need it.
+
+**4. Can the task be done AFK?** Is it scoped tightly enough to run with you away from the keyboard, no steering? Then send it to a **subagent** and leave this session untouched. Automated review is the standard case: the agent reads the diff and reports, and you aren't needed while it does.
+
+**5. Otherwise, `/compact`.** Relevant context, same harness, same directory, and you need to stay in the loop — this is where the tree lands, and it lands here often. Pass it an instruction (`/compact we're going to QA this area`) so the summary keeps what the next phase needs.
+
+`/compact` is the **default, not the first reach**. It sits at the bottom because the four questions above it are all cheaper or more precise. The failure mode when people start here is a fresh session that is confidently wrong about a decision the summary flattened.
+
+## Primary and secondary sources
+
+Every move except **Continue** turns a **primary source** into a **secondary source** — the session as it happened, replaced by a summary of it. The trade is always the same shape:
+
+| Source                            | Information | Noise | Room to move |
+| --------------------------------- | ----------- | ----- | ------------ |
+| Primary (Continue)                | Full        | Lots  | Little       |
+| Secondary (`/compact`, `/handoff`) | Lossy       | Less  | Lots         |
+
+This is why question 1 comes first. You only pay the lossiness when staying costs more than it saves.
+
+## These are judgement calls
+
+The questions are not objective — each has taste in it, and the same boundary can go two ways on two days. The value is in asking them **in order**, at the boundary rather than in the middle of the work.

package/template/.cursor/skills/ask-matt/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: ask-matt
+description: Ask which skill or flow fits your situation. A router over the skills in this repo.
+disable-model-invocation: true
+---
+
+# Ask Matt
+
+You don't remember every skill, so ask.
+
+## YSS default (read this first)
+
+In this template, **`yss-product-lifecycle` is the default orchestrator**. Native work-units own Spec, tickets, implementation authorization, and gates.
+
+This skill is a **Matt compatibility map**. Use `/grill-with-docs`, `/to-spec`, `/to-tickets`, and `/implement` only when the user **explicitly** names them. Do not treat the idea→ship list below as the YSS default. `/implement` does not grant git commit/push. Spec drafts from `/to-spec` stay `ready-for-human` until a human approves the Spec baseline.
+
+A **flow** is a path through the skills. Most paths run along one **main flow**, and two **on-ramps** merge onto it. Everything else is standalone, or a vocabulary layer that runs underneath.
+
+## Matt compatibility flow: idea → ship
+
+The route most work travels. You have an idea and want it built.
+
+1. **`/grill-with-docs`** — sharpen the idea by interview. Start here whenever you are **working in a working directory**: it's stateful, retaining what it learns in `CONTEXT.md` and ADRs. (No working directory? Use `/grill-me` — see Standalone. Both run the same `/grilling` primitive; `grill-with-docs` is the one that leaves a paper trail, which makes it the better of the two whenever a repo is there to leave it in.)
+2. **Branch — can you settle every question in conversation?** If a question needs a runnable answer (state, business logic, a UI you have to see), detour through a prototype, bridged by **`/handoff`** in both directions (a prototype lives in its own directory, which is exactly what `/handoff` is for — see Phase boundaries):
+   - **`/handoff`** out, then open a fresh session against that file,
+   - **`/prototype`** to answer the question with throwaway code,
+   - **`/handoff`** back what you learned, and reference it from the original idea thread.
+3. **Branch — is this a multi-session build?**
+   - **Yes** → **`/to-spec`** (turn the thread into a spec), then **`/to-tickets`** to split it into tracer-bullet tickets, each declaring its **blocking edges**. On a local tracker that's one file per ticket under `docs/.scratch/<feature>/issues/`, worked blockers-first by hand; on a real tracker the edges become native blocking links, so any ticket whose blockers are done can be grabbed — kick off **`/implement`** per ticket, **`/clear`ing context between each one**. Each ticket is self-contained, so the last one's context is disposable.
+   - **No** → **`/implement`** right here, in the same context window.
+
+   Either way, **`/implement`** builds each issue by driving **`/tdd`** internally — one red-green slice at a time — then closes out by running **`/code-review`** (Standards + Spec, plus UI fidelity when UI is in scope). Do not commit or push from `/implement`. Reach for **`/tdd`** on its own when you just want to build a concrete behaviour test-first without a full spec, and **`/code-review`** on its own whenever you want to review a branch or PR against a fixed point.
+
+### Context hygiene
+
+Keep steps 1–3 in **one unbroken context window** — don't compact or clear until after `/to-tickets` — so the grilling, spec, and tickets all build on the same thinking. Each `/implement` then starts fresh, working from the ticket.
+
+The limit on this is the **[smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone)**: the window (~150k tokens on state-of-the-art models) within which the model still reasons sharply. If a session approaches it before `/to-tickets`, don't push on degraded — `/compact` at the nearest phase boundary and carry on (see Phase boundaries).
+
+## On-ramps
+
+A starting situation that generates work, then merges onto the main flow.
+
+- **Bugs and requests piling up** → **`/triage`**. It moves issues through triage roles and produces agent-ready issues, which **`/implement`** later picks up.
+
+  Triage is only for issues **you didn't create** — bug reports, incoming feature requests, anything that arrives raw. Tickets that `/to-tickets` produced are already agent-ready, so **don't triage them**.
+
+- **Something's broken** → **`/diagnosing-bugs`**. For the hard ones: the bug that resists a first glance, the intermittent flake, the regression that crept in between two known-good states. It refuses to theorise until it has a **tight feedback loop** — one command that already goes red on *this* bug — then fixes with a regression test. Its post-mortem hands off to **`/improve-codebase-architecture`** when the real finding is that there's no good seam to lock the bug down.
+
+- **A huge, foggy effort — a greenfield project or a huge feature build, too big for one session** → **`/wayfinder`**, the most cognitively demanding flow here. When the way from here to the destination isn't visible yet, it charts a **shared map** of **decision tickets** on the issue tracker and resolves them one at a time — producing **decisions, not deliverables** — until the fog is pushed back and the way is clear. Where **`/grill-with-docs`** sharpens an idea you can hold in one session, wayfinder is for the idea you can't — and it's slower and denser, so save it for exactly that, never a well-scoped feature.
+
+  When the map clears, **it hands off, it doesn't build**: merge onto the main flow at **`/to-spec`**, which collapses the map's linked decisions into a buildable plan, then `/to-tickets` and `/implement` as usual. Looping the map straight into `/implement` skips that collapse and throws the linked detail away — go straight to `/implement` only when the effort turned out genuinely small.
+
+## Codebase health
+
+Not feature work — upkeep.
+
+- **`/improve-codebase-architecture`** — run whenever you have a spare moment to keep the codebase good for agents to operate in. It surfaces **deepening opportunities**; picking one _generates an idea_ you can take into the main flow at `/grill-with-docs`. It's the survey that finds the candidates; **`/codebase-design`** (below) is the bench you design the chosen one on.
+
+## Vocabulary underneath
+
+Two model-invoked references that run *beneath* the other skills — each the single source of truth for its vocabulary. Reach for them directly when the **words**, not the process, are the problem; or let the skills above pull them in.
+
+- **`/domain-modeling`** — sharpen the project's *domain* language: challenge a fuzzy term, resolve an overloaded word ("account" doing three jobs), record a hard-to-reverse decision as an ADR. It's the active discipline `/grill-with-docs` drives to keep `CONTEXT.md` a clean glossary.
+- **`/codebase-design`** — the deep-module vocabulary (module, interface, depth, seam, adapter, leverage, locality) for designing a module's *shape*: a lot of behaviour behind a small interface at a clean seam. `/tdd` and `/improve-codebase-architecture` both speak it.
+
+## Phase boundaries
+
+A **phase** is a chunk of work inside a session — the grilling, the implementation, the QA. At the **boundary** between two of them you have five options, and picking between them is the fuzziest decision in this whole map:
+
+- **Continue** — stay put. Costs nothing, loses nothing.
+- **`/clear`** — empty the window, when nothing here matters to what's next.
+- **`/handoff`** — write a portable markdown file. Narrow: only for a **new harness**, a **new directory**, a **colleague**, or forking a side task **mid-phase**. What it buys is portability.
+- **Subagent** — send a tightly-scoped task to its own window and get a report back.
+- **`/compact`** — compress this context and seed a fresh session with it. The **default**, at the bottom of the tree rather than the first reach.
+
+Read [PHASE-BOUNDARIES.md](PHASE-BOUNDARIES.md) for the ordered tree — the five questions, the reasoning behind each branch, and why the primary-source cost makes **Continue** the one to rule out first. Make the decision **at** a boundary; mid-phase, continue or split the rest into subagents.
+
+## Standalone
+
+Off the main flow entirely.
+
+- **`/grill-me`** — the same relentless interview as `/grill-with-docs`, but **stateless**: it saves nothing locally and builds no `CONTEXT.md`. Reach for it when you are **not working in a working directory** — sharpening a plan, a design, a piece of writing, anything with no repo under it. If you are in a working directory, use `/grill-with-docs` instead: it runs the same interview and leaves a paper trail, so it is strictly the better one.
+- **`/grilling`** — the interview primitive itself: rounds, the frontier, facts are the agent's job and decisions are yours. `/grill-me` and `/grill-with-docs` are the two named ways in, and `/triage`, `/wayfinder` and `/improve-codebase-architecture` all run it internally. Reach for it directly only when you want the interview with no wrapper around it.
+- **`/resolving-merge-conflicts`** — work an in-progress merge or rebase conflict hunk by hunk, resolving by **intent** traced to each side's primary source rather than by picking lines, then finish the operation. It never runs `--abort`. Standalone and off every flow: reach for it when you are already mid-conflict.
+- **`/prototype`** — a small, throwaway program that answers one design question: does this state model feel right, or what should this UI look like. Throwaway is a constraint on how the code is written, not a promise to destroy it: the answer folds into the real code, and the prototype itself is kept as a **primary source** on a `prototype/<name>` branch out of main, pointed at from the implementation issue. It's the detour in step 2 of the main flow, but reach for it any time a design question is hard to settle on paper.
+- **`/research`** — delegate reading legwork to a **background agent**: it investigates a question against **primary sources**, then leaves a cited Markdown file in the repo. Keep working while it reads. The file it produces is something to take *into* the main flow at `/grill-with-docs` — research feeds the thinking, it doesn't replace it.
+- **`/to-questionnaire`** — when the thing blocking you isn't in your head or the codebase but in **someone else's**, this writes them a questionnaire to fill in. It's the inverse of `/grill-me`: instead of interviewing you about the subject, it interviews you about the **send** — who it's going to, what you need back — and aims the questions at the gap. What comes back is material for `/grill-with-docs` or `/to-spec`.
+- **`/wait-what`** — the corrective for a message that didn't land. Use it mid-conversation, inside any other skill, and the agent re-pitches what it just said with the context you were missing, in plain English, using the `CONTEXT.md` vocabulary. It works after the fact; `/grill-with-docs` is the upfront cure, because a shared language agreed early is what stops the jargon arriving at all.
+- **`/teach`** — learn a concept over multiple sessions, using the current directory as a stateful workspace.
+- **`/writing-for-agents`** — reference for writing documents agents consume: skills, AGENTS.md, pointed-at docs.
+
+## Precondition
+
+**`/setup-matt-pocock-skills`** — run before your first engineering flow to configure the issue tracker, triage labels, and doc layout the other skills assume. Custom issue trackers also work.