create-yss-spec 1.1.3 → 2.0.0

package/template/.trae/skills/yss-cache/scripts/verify-cache-component.sh

@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+set -u
+
+source_root=""
+consumer_root=""
+consumer_module=""
+
+usage() {
+  echo "Usage: $0 [--source-root PATH] [--consumer-root PATH --consumer-module MODULE]" >&2
+}
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --source-root) [ "$#" -ge 2 ] || { usage; exit 2; }; source_root=$2; shift 2 ;;
+    --consumer-root) [ "$#" -ge 2 ] || { usage; exit 2; }; consumer_root=$2; shift 2 ;;
+    --consumer-module) [ "$#" -ge 2 ] || { usage; exit 2; }; consumer_module=$2; shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    *) usage; exit 2 ;;
+  esac
+done
+
+if [ -z "$source_root" ]; then
+  source_root=${YSS_SOURCE_ROOT:-}
+fi
+if [ -z "$source_root" ]; then
+  for candidate in "$PWD" "$PWD/.." "$HOME/Projects/yss-cloud-microservice" "$HOME/Documents/yss-project/yss-cloud-microservice"; do
+    if [ -d "$candidate/yss-microservice-components/yss-component-cache-parent" ]; then
+      source_root=$candidate
+      break
+    fi
+  done
+fi
+
+parent="${source_root%/}/yss-microservice-components/yss-component-cache-parent"
+if [ -z "$source_root" ] || [ ! -f "$parent/pom.xml" ]; then
+  echo "ERROR: cannot locate cache parent; use --source-root or YSS_SOURCE_ROOT" >&2
+  exit 2
+fi
+if [ ! -x "$source_root/mvnw" ]; then
+  echo "ERROR: Maven wrapper is missing or not executable: $source_root/mvnw" >&2
+  exit 2
+fi
+if { [ -n "$consumer_root" ] && [ -z "$consumer_module" ]; } || { [ -z "$consumer_root" ] && [ -n "$consumer_module" ]; }; then
+  echo "ERROR: --consumer-root and --consumer-module must be provided together" >&2
+  exit 2
+fi
+
+echo "== Cache reactor verify =="
+(cd "$source_root" && ./mvnw -f "$parent/pom.xml" verify) || exit 1
+
+echo "== Docker integration status =="
+report="$parent/yss-component-redis-cache/target/surefire-reports/TEST-com.yss.cloud.cache.redis.config.RedisStandaloneIntegrationTest.xml"
+if command -v docker >/dev/null 2>&1 && docker info >/dev/null 2>&1; then
+  if [ ! -f "$report" ]; then
+    echo "ERROR: Docker is available but Redis integration report is missing" >&2
+    exit 1
+  fi
+  if grep -Eq 'skipped="[1-9]' "$report"; then
+    echo "ERROR: Docker is available but Redis integration test was skipped" >&2
+    exit 1
+  fi
+  echo "PASS: real Redis integration test executed"
+else
+  echo "SKIP: Docker is unavailable; Redis integration test may be skipped by assumption"
+fi
+
+echo "== Diff whitespace =="
+if command -v git >/dev/null 2>&1 && git -C "$source_root" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  git -C "$source_root" diff --check || exit 1
+else
+  echo "SKIP: source root is not a Git worktree"
+fi
+
+echo "== Java 8 bytecode =="
+classes=$(find "$parent" -path '*/target/classes/*.class' -type f | head -1)
+if [ -z "$classes" ]; then
+  echo "ERROR: no compiled cache class found" >&2
+  exit 1
+fi
+if ! command -v javap >/dev/null 2>&1; then
+  echo "ERROR: javap is required for bytecode verification" >&2
+  exit 2
+fi
+majors=$(find "$parent" -path '*/target/classes/*.class' -type f -exec javap -verbose {} \; 2>/dev/null | sed -n 's/.*major version: *//p' | sort -u)
+if [ "$majors" != "52" ]; then
+  echo "ERROR: expected only Java 8 major version 52, found: $majors" >&2
+  exit 1
+fi
+echo "PASS: all cache classes use major version 52"
+
+if [ -n "$consumer_root" ]; then
+  echo "== Consumer build =="
+  if [ ! -x "$consumer_root/mvnw" ] || [ ! -f "$consumer_root/pom.xml" ]; then
+    echo "ERROR: invalid consumer root: $consumer_root" >&2
+    exit 2
+  fi
+  (cd "$consumer_root" && ./mvnw -pl "$consumer_module" -am -DskipTests package) || exit 1
+fi
+
+echo "RESULT: cache verification passed"
+exit 0

package/template/AGENTS.md

@@ -1,299 +1,138 @@
-# AGENTS.md — AI 开发指令
+# AGENTS.md — AI 开发入口规则
 
-> **本文档是 AI Harness 的核心载体。所有 AI Agent 启动时必须读取本文档。**
+> 本文件只保存 Agent 必须首先遵守的仓库身份路由、硬门禁和禁止事项。完整生命周期、流程裁剪和 YSS 实现细则以下文引用的权威资产为准。
 
----
+## 1. 首先识别仓库身份
 
-## 项目概述
+每个任务开始时先读取根目录 `yss-project.yaml`：
 
-- **项目名称：** [填写]
-- **业务领域：** [填写]
-- **团队规模：** [填写]
+- `repository_mode: template-source`：使用“模板维护流程”，不默认生成具体产品的 Spec、原型、OpenAPI 或垂直切片 Ticket。
+- `repository_mode: project-instance`：按产品研发生命周期分诊任务。
+- 文件缺失、schema 版本不支持或模式值非法时，停止路由并执行迁移检查；不根据目录、Git 远程或占位符猜测身份。
 
----
+仓库身份契约见 `docs/adr/0002-yss-project-repository-mode.md`。
 
-## 测试要求
+## 2. 单一事实来源
 
-| 层级 | 覆盖率要求 |
-|------|-----------|
-| Domain / Application 层 | >= 90% |
-| API 层 | >= 80% |
-| 前端组件 | >= 75% |
-| 关键流程 | 100% (E2E) |
+| 事实类型 | 权威资产 |
+|---|---|
+| 领域与流程词汇 | `CONTEXT.md` |
+| Agent 入口、硬门禁、禁止事项 | `AGENTS.md` |
+| 主阶段、门禁、产物和退出标准 | `docs/process/lifecycle-artifact-map.md` |
+| 影响面触发与 `not-applicable` | `docs/process/harness-process-tailoring.md` |
+| 技能清单、来源、版本、哈希和投影目标 | `skills-lock.json` |
 
----
+README、用户指南和其他说明文档只引用或解释上述事实，不重复定义同一规则。
 
-## 安全红线（AI 绝对不可触碰）
+## 3. 标准文档语言与规范语汇
 
-| 场景 | AI 权限 |
-|------|---------|
-| 支付相关逻辑 | 仅生成草案 |
-| 数据库迁移脚本 | 仅生成模板 |
-| 认证/授权中间件 | 仅生成草案 |
-| 加密算法实现 | **禁止生成** |
-| SQL 原生查询 | 仅生成草案 |
-| 公共基础库 API 变更 | 仅生成草案 |
+- 所有面向业务、产品、架构、实施、审查、发布和复盘的落地文档，正文统一使用简体中文。
+- 英文专有名词、代码标识、API 路径、schema、类名、方法名、枚举值、错误码、命令、文件名和协议 metadata 保持原样。
+- 新流程统一使用 Spec、Ticket、`to-spec`、`to-tickets`。过时术语和技能名只能出现在迁移指南或明确标注的旧项目上下文。
+- 实施前读取 `CONTEXT.md`；与词汇或 ADR 冲突时立即指出并先解决冲突。
 
-触碰安全红线时，必须标记 `ready-for-human` 或 `TODO-HUMAN-REVIEW`，Agent 只能生成草案或模板，不得直接交付生产实现。
-
----
-
-## 研发协作体系：Matt Engineering Skills × YSS × OpenAPI
-
-| 层级 | 组件 | 职责 |
-|------|------|------|
-| 规格驱动层 | PRD / OpenAPI 3.1 / OpenSpec-style Spec Delta / Vertical Slice Issue | 固化需求、接口契约、条件行为差异、验收标准和端到端任务边界 |
-| 领域与工程基线层 | `CONTEXT.md` / ADR / YSS DDD skills / Gateway / Repository | 统一领域语言、模块边界、依赖方向和业务行为 |
-| 方法论层 | Matt Pocock Engineering Skills | 提供需求澄清、PRD、Issue 拆分、TDD、Bug 诊断、代码审查和架构治理流程 |
-| 可视化辅助层 | Excalidraw diagrams / prototypes / architecture diagrams | 将流程、架构、状态、依赖和切片关系可视化，辅助共识和审查 |
-| 执行与追踪层 | Issue tracker / CI / review / Git checkpoint | 追踪阶段状态、验证证据、阻塞项、人审点和发布记录 |
-
-一句话：
+## 4. `template-source` 模板维护流程
 
 ```text
-PRD 定义要做什么，OpenAPI 定义前后端契约，YSS 定义工程边界；Matt skills 让澄清、拆分、实现、审查和验证保持轻量可追溯。
+影响面分析
+→ 修改对应单一事实来源
+→ 同步技能投影和派生文档
+→ 执行压力场景与 scripts/verify-template
+→ 独立审查和 Git checkpoint
 ```
 
----
+硬门禁：
 
-## Agent skills
+- 修改 skill、`AGENTS.md`、流程规则或模板时，必须使用 `writing-skills` 的 RED / GREEN / REFACTOR 思路，保留基线失败、压力场景和修订后验证证据。
+- `.agents/skills` 是跨 Agent 共享技能的权威内容；`.claude/skills`、`.codex/skills`、`.hermes/skills`、`.pi/skills`、`.trae/skills` 中的共享技能是生成投影，禁止分别手工修改。
+- `scripts/verify-template` 是模板发布阻断门禁。模板与外部 `create-yss-spec` 的跨仓库契约未完成集成验证时，不得声称可发布。
 
-本仓库已内置 Matt Pocock Engineering Skills，Codex、Claude、Hermes、Pi、Trae 等项目 Agent 目录均可读取。固定来源为 `mattpocock/skills` 的 `skills/engineering`，快照提交 `272f99b22574f50e4266791c86b9302682970e23`。竞品分析额外内置 `competitive-intelligence`，来源为 `anthropics/knowledge-work-plugins` 的 `sales/skills/competitive-intelligence`。
+## 5. `project-instance` 产品研发路由
 
-能力说明见 `docs/process/MATT-POCOCK-ENGINEERING-SKILLS.md`。常用链路：
+任务开始时先根据 `docs/process/harness-process-tailoring.md` 判断小改动、中等变更或新模块 / 高风险变更，定位最近可信阶段。日常骨架为：
 
 ```text
-yss-product-lifecycle
--> competitive-intelligence (需要竞品 / 市场事实时)
--> grill-with-docs
--> to-prd
--> product overview design / functional architecture
--> product-design:index
--> prototype-review
--> Product Design focused skill 产出高保真 HTML 原型并经用户确认
--> OpenAPI Draft
--> OpenSpec-style Spec Delta (中高风险行为变化时)
--> OpenAPI Freeze
--> to-issues
--> implement / tdd
--> code-review
--> fresh verification
+入口分诊
+→ 机会与 Discovery
+→ 业务 / Spec / 功能架构
+→ 产品设计与需求冻结
+→ 系统 / 数据架构与工程契约设计审查
+→ 契约冻结与 Ticket 正式化
+→ 垂直切片与 TDD 实现
+→ 验证发布与复盘
 ```
 
-### Issue tracker
+执行原则：
 
-Issues、PRD 和 triage 不得写死到单一平台；必须按用户明确选择或当前仓库主远端在 GitLab Issues / GitHub Issues 间路由。详见 `docs/agents/issue-tracker.md`。
+- 21 个门禁全部是条件强制门禁。命中触发条件时必须完成；未命中时只记录 `not-applicable` 及原因，不生成空文档。
+- 新功能或较大变更先用 `grill-with-docs` 澄清，再用 `to-spec` 形成 Spec。
+- 只要进入 Spec 基线，必须产出产品总体设计或功能架构；只有存在 UI 影响时，才强制低保真页面草图、状态矩阵、Ant Design v6 高保真 HTML 原型和用户确认。
+- API 契约变更先形成 OpenAPI 3.1 Draft，经必要的工程基线、系统 / 数据架构和设计审查后 Freeze，再进入实现。
+- Spec Delta 只记录相对既有冻结 Spec 基线的高风险行为差异；全新产品、全新模块和低风险调整不生成 Spec Delta。
+- OpenAPI Freeze 或无 API 影响记录完成后，使用 `to-tickets` 拆成可独立验证的窄垂直切片，禁止只按 Adapter / Application / Domain / Infrastructure 横向拆分。
 
-流程状态必须同步到选定 issue tracker：PRD、需求冻结、OpenAPI Freeze、垂直切片、阶段完成、验证结果、阻塞项和安全人审点都必须更新到对应 Issue / 里程碑 / 评论中，不得只停留在本地文档。
+## 6. Ticket 与状态
 
-### Triage labels
+- 每个功能先建立功能父 Ticket，用于汇总 Spec、设计、审查、OpenAPI Freeze、阻塞项和阶段证据。
+- Spec 初稿、产品设计、原型、OpenAPI Draft 和待冻结资产使用 `ready-for-human`。
+- 只有通过必要门禁、阻塞边已清除并具备直接实现条件的垂直切片 Ticket，才能使用 `ready-for-agent`。
+- Ticket、Spec 和阶段证据必须按用户选择或当前主远程路由到 GitHub / GitLab；平台不可用时生成本地待发布草案，不自动改投其他平台。
 
-使用标准五态标签：`needs-triage`、`needs-info`、`ready-for-agent`、`ready-for-human`、`wontfix`。详见 `docs/agents/triage-labels.md`。
+平台规则和五态标签见 `docs/agents/issue-tracker.md` 与 `docs/agents/triage-labels.md`。
 
-### Domain docs
+## 7. 实现与 YSS 路由硬门禁
 
-使用单上下文领域文档布局：根目录 `CONTEXT.md` + `docs/adr/`。详见 `docs/agents/domain.md`。
+进入实现前：
 
-### Documentation language
+1. 确认受影响的 frontend / backend 工程是 `existing`、`required` 还是 `initialized`，并登记实现仓库、分支、CI、验证命令和回滚点。
+2. 无可复用工程时，先确认外部目标仓库或输出目录，再分别使用 `yss-ddd-scaffold-generator` / `yss-frontend-scaffold-generator`；不因当前仓库缺少 frontend / backend 目录而绕过脚手架路由。
+3. 使用 `yss-router` 选择最小 YSS skill 集合。后端领域、Application、Repository / Gateway、Web / DTO 分别路由到对应 YSS skill；涉及 POJO 样板或对象转换时必须加载 `lombok`、`mapstruct` 和 `alibaba-java-code-style`。
+4. 后端切片必须先形成 Backend Slice Implementation Contract，至少包含 `required_skills`、`allowed_write_paths`、`forbidden_patterns`、`expected_evidence_files`、`seam_deferred`、`verification_commands`。
+5. 把系统 / 数据架构、ADR、工程基线、OpenAPI Freeze 和风险 / 回滚约束转译为 Build Architecture Checklist。
 
-面向业务用户、产品、架构、YSS lifecycle、Issue、Review、Release、Implementation 和 Retro 的持久化文档默认使用中文落地。保留英文专有名词、代码标识、API 路径、schema 名称、类名、方法名、文件名、枚举值、错误码和命令，不强行翻译。若外部工具模板或协议要求英文 frontmatter / key / metadata，仅 metadata 使用英文，正文仍使用中文。用户明确要求英文或目标读者为英文团队时除外。
+禁止绕过上述合同、检查清单或专项 skill，直接在 `AGENTS.md` 中自行发明细则。详细实现约束以 YSS skills、`docs/process/implementation-repo-integration.md` 和对应模板为准。
 
-### Skill artifact language
+## 8. 专项任务的强制入口
 
-Matt skills 与 YSS skills 产物正文默认使用中文，包括澄清记录、PRD、Issue、设计说明、实施说明、审查报告、验证记录和复盘说明。英文名称、接口名、路径、字段名、命令和其他必要 metadata 仍按原样保留。
+| 触发情形 | 必须使用 |
+|---|---|
+| 技术事实、标准、第三方 API 或框架行为影响决策 | `research` 或等价的一手资料记录 |
+| 竞品、市场或用户口碑事实 | `competitive-intelligence` |
+| UI 设计、原型、组件或主题 | `yss-design-system` 后路由 `product-design:index`；产出前用 `antd` 查询 Ant Design v6 事实 |
+| Bug、测试失败或性能回退 | `diagnosing-bugs` 建立可复现反馈，再用 `tdd` |
+| merge / rebase 冲突 | `resolving-merge-conflicts` |
+| 架构治理、难测模块或深模块设计 | `improve-codebase-architecture` / `codebase-design` |
+| 跨线程、跨仓库、上下文过长或原型结论回流 | `handoff` 或等价交接记录 |
 
----
+业务行为默认按 `tdd` 使用已确认的公开 seam 逐切片实现。一次性生成、纯配置或流程文档不适用代码 TDD 时，必须记录例外理由和可执行验证方式。
 
-## Recommended flow
+## 9. 工作区与实现仓库边界
 
-默认日常执行使用 8 个主阶段，21 个门禁 / 职责点只用于审查和补齐缺失资产，不作为每次需求都必须逐项执行的主流程。
-
-```text
-入口分诊
--> 机会与 Discovery
--> 业务 / PRD / 功能架构
--> 产品设计与需求冻结
--> 系统 / 数据架构与工程契约设计审查
--> 契约冻结与 Issue formalization
--> 垂直切片与 TDD 实现
--> 验证发布与复盘
-```
-
-阶段、产物、模板和 21 个门禁 / 职责点的权威映射见 `docs/process/lifecycle-artifact-map.md`。流程裁剪规则见 `docs/process/harness-process-tailoring.md`。
-
----
-
-## Mandatory skill rules
-
-- 新产品、新模块或较大变更必须先判断生命周期阶段、缺失资产和下一步；可用 `yss-product-lifecycle`，已有等价记录时可复用。
-- 小需求变更或迭代不从头重跑完整链路；必须先做影响面评估，找到最近可信阶段，只补齐受影响阶段及其下游资产。
-- 任务开始前必须先参考 `docs/process/harness-process-tailoring.md` 判断小改动 / 中等变更 / 新模块或高风险变更；裁剪只能减少不相关产物，不能裁剪安全人审、Issue 追踪、Git checkpoint 和 fresh verification。
-- 新功能或较大改动必须先用 `grill-with-docs` 澄清需求，再用 `to-prd` 形成 PRD，并在 PRD、实施计划或 Issue 中引用澄清记录。
-- PRD 基线阶段必须同步明确功能架构：功能域、模块边界、优先级、MVP / 非目标范围和模块依赖；不清晰时不得进入 PRD 校准。
-- 只要进入 PRD 初稿 / 需求基线流程，产品总体设计 / 功能架构就是必要产物，默认路径为 `docs/design/<feature>-product-overview-design.md`，且必须包含低保真原型 / 页面草图。不得直接从 PRD 初稿进入页面 / 原型 / 交互设计、OpenAPI Draft、PRD 校准、需求冻结或实现；不进入 PRD 生命周期的小文案、低风险 Bug 或局部配置变更，必须在影响面评估中说明不适用原因。
-- 涉及页面设计、原型评审、UI 实现、组件选型、主题 token、颜色排版间距或 Ant Design / YSS UI 风格一致性的任务，必须先用 `yss-design-system` 作为设计系统基线；详细规范引用 `docs/design/design-system.md`。
-- 有用户界面的功能在 PRD 初稿和产品总体设计 / 功能架构后必须先引用 `yss-design-system`，再以 `product-design:index` 作为产品原型产出主入口，按 Product Design plugin 路由到 `$get-context`、`$ideate`、`$prototype`、`$image-to-code`、`$url-to-code` 等 focused skill，产出页面、原型、交互状态、PRD 回填项和 OpenAPI 反推清单；低保真 `prototype-review` 通过后，必须产出高保真 HTML 原型，默认路径为 `docs/design/prototypes/<feature>/index.html`，且必须使用 Ant Design v6。原型产出前必须使用 `antd` CLI 查询设计语言、组件 API、demo、token 和 semantic 信息；原型完成后必须记录 AntD v6 校验证据。该高保真 HTML 原型是流程必需产物，可由系统 / Agent 在低保真评审通过后自动产出，不要求用户手工提供；产出后必须获得用户确认并记录确认结果，未产出或未确认前不得进入 PRD 校准 / 需求冻结和 UI 驱动的 OpenAPI Draft。
-- 任何 API 契约变更必须先在 `docs/api/specs/*.yaml` 形成 Draft；OpenAPI 不得只基于 PRD 反推，必须结合产品总体设计 / 功能架构；有 UI 的功能还必须结合页面/原型/交互说明、状态矩阵、`prototype-review` 结论和 Ant Design v6 高保真 HTML 原型，经工程基线（如适用）、系统 / 数据架构和设计审查后 Freeze，再实现前后端和测试。
-- API、权限、状态机、数据模型、跨端、新模块或高风险行为变化，应在 Design Review / OpenAPI Freeze 前补充 OpenSpec-style Spec Delta，落点为 `docs/specs/<feature>-spec-delta.md`；小文案、局部样式、配置微调和低风险 Bug 默认不需要。Spec Delta 只记录行为差异、验收场景和测试映射，不恢复 OpenSpec CLI、额外变更目录或状态机。
-- OpenAPI Freeze 后进入 `to-issues`，将冻结范围拆成端到端垂直切片 Issue；不得要求额外状态机或变更目录作为交付前置。
-- 涉及服务边界、部署、集成、性能、安全、可靠性或运维的变更，必须在设计审查前产出系统总体架构或等价设计记录。
-- 涉及持久化、Repository、元数据、版本、血缘、搜索或查询策略的变更，必须在开发前产出数据架构；数据模型、元数据管理、ER 设计、版本管理或血缘分析类产品必须在 Design Review 和 OpenAPI Freeze 前完成数据架构。
-- 进入实现前，必须先判断当前需求涉及的前端 / 后端运行时代码工程是否已存在且可复用；若不存在、不可复用或目录约定缺失，必须先在 implementation routing 中记录原因，并路由到 `yss-ddd-scaffold-generator` 或 `yss-frontend-scaffold-generator` 初始化对应脚手架后再进入业务实现。
-- 进入实现前，必须把系统架构、数据架构、ADR、工程基线、OpenAPI Freeze 结论和安全红线转译为当前切片的 `Build Architecture Checklist`。
-- 每个垂直切片完成时必须回勾 `Build Architecture Checklist`：已落实项给出代码、测试或文档证据；延期项说明原因、风险、补齐切片和是否允许继续；漂移项必须触发 Architecture Re-check；违反项必须停止实现并回到设计审查或架构修正。
-- 涉及 Repository / Gateway / 持久化边界、权限 / 认证 / 授权、审计日志、SQL / DDL / 迁移、文件上传下载 / 临时 URL、版本快照 / 元数据 / 血缘 / 查询索引、跨模块接口、部署、回滚或运维约束时，必须在当前切片的实现记录中写明架构对齐状态和 `TODO-HUMAN-REVIEW` 补齐落点。
-- 当需求、架构、流程、状态机、数据流或垂直切片关系仅靠文字难以说明时，可用 `excalidraw-diagram-generator` 生成 `.excalidraw` 图作为辅助材料；图不能替代 PRD、OpenAPI、ADR 或测试。
-- 任何 Bug、测试失败或性能回退必须先用 `diagnosing-bugs` 建立可复现反馈命令，再修复。
-- 业务行为实现默认使用 `tdd`：先写一个会失败的行为测试并确认失败，再写最小实现；生成代码、配置或一次性原型如不适用 TDD，必须明确例外原因和验证方式。
-- 架构治理、难测模块、深模块设计必须使用 `improve-codebase-architecture` / `codebase-design` 的 module、interface、seam、adapter 术语。
-- `to-issues` 产出的任务必须是端到端垂直切片，不允许只按 Adapter / Application / Domain / Infrastructure 横向拆分。
-- 每个生命周期阶段完成后必须执行 Git checkpoint 判断：列出阶段产物、Issue 同步状态、排除无关脏文件，并在用户已授权时按范围提交和推送。
-- 任何“完成 / 可合并 / 可发布”结论必须有 fresh verification 证据；不得只凭实现者自述通过。
-- 发布后或阶段性完成后必须做复盘判断；若发生架构返工、verify 返工、IMPORTANT / CRITICAL review findings 或 `TODO-HUMAN-REVIEW` 延期，必须落中文复盘记录，并把流程修订回写到 `AGENTS.md`、`docs/process/lifecycle-artifact-map.md`、ADR 或模板中。
-
----
-
-## 工程基线与编码入口
-
-`AGENTS.md` 只保存 Agent 必须先遵守的入口级规则，不承载完整编码手册。后端脚手架、DDD 分层、命名、Repository、MapStruct、统一响应等细则以 YSS skills 为准。
-
-### 实现工作区目录约定
-
-本仓库默认作为研发管理仓库，管理 PRD、OpenAPI、架构、垂直切片、验证、发布和复盘；前端 / 后端代码默认位于独立实现仓库。任何脚手架生成步骤，在写入业务代码、生成后端 / 前端工程骨架或创建实现目录前，必须先检查并记录实现仓库或实现位置。
-
-默认推荐：外部实现仓库。
-
-- 后端、前端或其他运行时代码优先落在各自 Git 仓库，并在 PRD、实施计划、Issue 或实现路由记录中登记 repo URL、分支、MR / PR、CI、测试命令和验证证据。
-- 已有工程目录不得被强制搬迁；继续使用时必须记录为当前需求的实现位置，并说明是否计划后续迁移。
-- 进入实现前必须先判断受影响的 frontend / backend 工程是否已经存在、是否仍可复用、是否满足当前契约与技术基线；若任一受影响端不存在可用工程，必须先补实现仓库决策，再分别路由 `yss-ddd-scaffold-generator` 或 `yss-frontend-scaffold-generator` 初始化。
-- 实现仓库接入、跨仓库切片绑定和验证回流见 `docs/process/implementation-repo-integration.md`。
-
-例外：只有用户明确选择本仓库承载实现代码时，才按需创建轻量 monorepo 目录：
+当前仓库默认是研发管理仓库，前端、后端和其他运行时代码优先位于独立实现仓库。只有用户明确选择当前仓库承载实现代码时，才可按需创建：
 
 ```text
 apps/backend/
 apps/frontend/
-docs/releases/
-docs/implementation/
-```
-
-不得由 Agent 自行理解并新建任意顶层业务代码目录；如果目录约定缺失或与现状冲突，先停在工程基线 / implementation routing，补齐决策后再进入实现。
-
-### YSS 实现规范加载门禁
-
-`yss-ddd-scaffold-generator` 只用于生成后端工程骨架和工程基线输入，不代表后续业务代码天然符合 YSS 规范。垂直切片实现、代码生成或重构只要涉及 YSS 后端 / 前端实现，必须先完成以下门禁：
-
-1. 先判断当前切片受影响的 frontend / backend 运行时代码工程是否已存在且可复用，并把结论记录到实施计划或切片 issue 中。
-2. 若受影响的后端工程不存在或不能复用，先用 `yss-ddd-scaffold-generator` 初始化；若受影响的前端工程不存在或不能复用，先用 `yss-frontend-scaffold-generator` 初始化。缺失实现仓库决策时，不得跳过该步骤直接写业务代码。
-3. 从零后端骨架生成后，必须用 `yss-backend-scaffold-parent` 做工程基线检查；不得把脚手架 sample 代码当作业务实现交付。
-4. 先使用 `yss-router` 判断最小 YSS skill 集合，并把路由结果记录到实施计划或切片 issue 中。
-5. 每个垂直切片在写业务代码前，按影响面加载专项规范：
-   - 领域建模 / 聚合 / 状态流：`yss-domain-modeling`，落代码时接 `yss-domain` / `yss-backend-scaffold-domain`。
-   - Repository / PO / Convertor / GatewayImpl：`yss-repository`，需要 MyBatis 细节时接 `yss-mybatis` / `yss-backend-scaffold-infrastructure`。
-   - Controller / DTO / VO / Web Convertor：`yss-web-controller`、`yss-dto`、`yss-backend-scaffold-web`。
-   - 前端页面、组件、API 接入、YSS UI：按 `yss-router` 选择 `yss-page-module-development`、`yss-components`、`api-integration` 等最小集合。
-6. Java 后端实现和审查必须同时遵守 `alibaba-java-code-style`；命名、异常、日志、集合、单元测试、ORM/MyBatis、Maven 和安全相关强制项作为 review blocker 处理。
-7. 实现计划和 review 记录必须列出本切片实际使用的 YSS / Alibaba 规范输入、验证命令和未覆盖原因；不得用“符合 YSS”笼统替代具体 skill 证据。
-
-### YSS DDD 分层红线
-
-后端服务默认采用 YSS DDD 多模块架构，不再以传统 `Controller -> Service -> Repository` 三层作为唯一模型。
-
-```text
-Adapter -> Application -> Domain
-Infrastructure -> Domain Gateway / Repository Interface
-Bootstrap -> 组装启动、配置和依赖
 ```
 
-调用方向：
-
-```text
-Web Adapter
--> Application Use Case / Command Handler
--> Domain Model / Domain Service
--> Domain Gateway
--> Infrastructure GatewayImpl / Repository
--> Database / External System
-```
-
-红线：
-
-- Domain 层不得依赖 Adapter、Infrastructure、Mapper、Controller 或 Web DTO。
-- Gateway 接口定义在 Domain，GatewayImpl / Repository 实现在 Infrastructure。
-- Controller 只做协议适配、参数校验和响应包装，不穿透 Repository。
-- 对象转换优先使用 MapStruct，不手写大段重复 mapping。
-- PO、VO、CMD、Query 命名沿用 YSS 约定；分页 Query 继承项目约定的分页基类。
-
-### API 与前后端契约
-
-- API 路径默认版本化：`/api/v1/`。
-- 后端返回统一响应包装：`SingleResult<T>`、`MultiResult<T>`、`PageResult<T>`。
-- 以 OpenAPI 3.1 Spec 作为 API 契约。
-- 契约变更必须先形成 Draft，经工程基线、系统 / 数据架构和设计审查后 Freeze，再分别实现前后端和测试。
-
----
-
-## AI Agent 协作规范
-
-这些阶段不是死流程。Agent 必须先判断任务类型，再选择最小必要流程；明确 Bug、小调整和探索任务不应被强行套入完整新功能链路。
-
-### 任务入口分流
-
-| 任务类型 | 推荐路径 | 关键门禁 |
-|------|------|------|
-| 模糊想法 / 产品机会 | 机会探索环 -> `grill-with-docs` -> PRD | 进入 PRD 前必须收敛用户、痛点、MVP 和非目标范围 |
-| 已有竞品 / 用户 / 行业材料 | `competitive-intelligence` -> Discovery -> 机会构想 -> `grill-with-docs` -> `to-prd` | 事实输入必须转化为 MVP 边界和验收标准 |
-| 新模块 / API / 跨端改动 | 入口分诊 -> Discovery -> PRD / 功能架构 -> 产品设计与需求冻结（有 UI 时）-> 系统 / 数据架构与工程契约设计审查 -> OpenAPI Freeze -> `to-issues` -> `implement` / `tdd` -> `code-review` | 契约变更先形成 API 影响记录和契约草案 / review-only OpenAPI Draft，经工程基线、系统 / 数据架构和 Design Review 后再 Freeze |
-| 小需求变更 / 已有功能迭代 | 影响面评估 -> 选择最近可信阶段 -> 更新受影响资产 -> 必要评审 -> TDD / verify | 不重跑机会探索和全量 PRD；若影响 API、状态机、权限、数据模型、跨端协作或安全红线，则从对应阶段延伸并补齐下游门禁 |
-| 明确 Bug / 测试失败 / 性能回退 | `diagnosing-bugs` -> `tdd` -> verify | 先建立可复现反馈命令，再修复 |
-| 小文案 / 局部样式 / 配置调整 | 直接最小改动 -> verify | 扩散到 API、状态、权限或多模块时，升级到最早受影响阶段并补齐下游门禁 |
-| 架构治理 / 难测模块 | `improve-codebase-architecture` / `codebase-design` -> ADR / Issue | 使用 module、interface、seam、adapter 术语 |
-
-### 审查闭环
-
-审查不是最后一步，而是阶段门禁。任何阻断项都必须回到产生该问题的阶段修正，修正后重新审查。
-
-| 审查点 | 触发时机 | 主审 | 阻断项 |
-|------|----------|------|--------|
-| PRD Review | PRD 完成后 | Product / Domain Review Agent | 用户、痛点、非目标范围、验收标准或安全红线不清 |
-| Grilling Review | 新功能 / 较大改动 PRD 前、Architecture Review 前 | Product / Domain / Architecture Agent with `grill-with-docs` | 用户价值、边界、状态、反例、架构约束、验收标准或安全红线经不起质询 |
-| Prototype Review | 有 UI 的 PRD 初稿完成后、高保真 HTML 原型前 | Product Design / UX / Frontend / API Agent | 页面清单、原型/线框、用户流、状态矩阵、PRD 回填项、权限状态或 OpenAPI 反推清单不清 |
-| High-fidelity HTML Prototype Review | 低保真原型评审通过后、PRD 校准前 | Product Design / UX / Frontend Agent | Ant Design v6 高保真 HTML 原型缺失、主流程/关键状态/响应式/权限体验不可审查 |
-| API Review | OpenAPI Draft 后 | API + Frontend + Backend Agent | schema、错误结构、分页、权限、契约测试不可落地 |
-| Architecture Review | 系统/数据架构后 | Architecture Review Agent | 业务/功能/系统/数据架构、DDD 分层、模块依赖、ADR、状态流或回滚策略不清 |
-| Plan Review | 垂直切片生成后 | Planning / Test Agent | 切片横向拆层、缺测试命令、缺回滚点或范围过大 |
-| Code Review | 每个 slice 完成后 | 独立 Review Agent / `code-review` | 实现者自审、契约不一致、分层穿透、测试不足 |
-| Security Review | 触碰安全红线时 | Security / Human Review | 权限、认证、SQL、加密、迁移或公共 API 风险未人工确认 |
-| Release Review | 发布前 | Verify / Release Agent | fresh verification 不足、发布说明、实施步骤或回滚方案缺失 |
-
-### Agent 铁律
-
-1. **实现者 != 审查者** — 同一段代码不能由同一个 Agent 审查。
-2. **无测试不写代码** — 业务行为默认先写失败测试，再写实现。
-3. **Fail-Closed 审查** — 无法确认安全性时自动拒绝。
-4. **安全红线不可逾越** — 触碰红线时标记 `TODO-HUMAN-REVIEW`。
-
----
-
-## 项目专属约定
-
-<!-- 随项目推进持续补充 -->
-### 业务规则
+不得自行新建其他顶层业务代码目录。
 
-- （待补充）
+## 10. 独立审查、验证和追踪
 
-### 已知陷阱
+- 实现者不能审查自己的代码。模板发布、代码切片和高风险变更必须由其他 Agent 或人工独立审查；低风险文档变更可使用显式人工 checkpoint。
+- 任何“完成 / 可合并 / 可发布”结论必须基于 fresh verification，不接受“之前跑过”或实现者自述。
+- 每个阶段或垂直切片结束时，同步对应 Ticket 的范围、验证证据、风险、人工审查点和下一步。
+- 每个阶段结束时执行 Git checkpoint 判断：列出本阶段产物和 Ticket 同步状态，排除无关脏文件，只在用户已授权时按明确范围提交或推送。
+- 发布后或阶段性完成后做复盘判断；出现架构返工、验证返工、IMPORTANT / CRITICAL review finding 或人工确认延期时，落简体中文复盘并修订权威资产。
 
-- 生命周期阶段产物只在本地生成但未提交 / 推送，会导致过程决策、评审依据和后续实现输入不可追溯。阶段结束时必须主动提出或执行 Git checkpoint，并使用显式路径分组提交，避免把环境目录或无关用户改动混入提交。
+## 11. Subagent 协同
 
-### 性能基线
+使用 subagent 前必须定义任务包：输入资产、输出产物、可写范围、禁止事项、验收标准和汇合方式。写入范围不得重叠，实现者不得同时担任审查者。
 
-- （待补充）
+subagent 可收集证据、产出草案、实现局部切片和执行独立审查 / 验证，但不得替代主控 Agent 作出仓库身份判定、Spec baseline、需求冻结、OpenAPI Freeze、架构放行、Ticket 最终状态、Git checkpoint 范围或“完成 / 可合并 / 可发布”结论。
 
----
+详细规则见 `docs/process/subagent-collaboration.md`。
 
-## 版本历史
+## 12. 测试质量基线
 
-| 日期 | 版本 | 变更内容 |
-|------|------|---------|
-| | v1.0 | 从 yss-spec-project-template 初始化 |
+模板推荐值为 Domain / Application `>= 90%`、API `>= 80%`、前端组件 `>= 75%`、已明确的关键流程 `100% E2E`。这些数字只是模板推荐；项目实例必须在测试策略中明确采纳或覆盖后，才构成 CI 门禁。未定义关键流程清单时，不得声称其 E2E 覆盖率达到 100%。

package/template/CONTEXT.md

@@ -7,24 +7,37 @@
 | 术语 | 含义 | 避免 / 备注 |
 |---|---|---|
 | Agent | 执行特定工作流步骤的 AI 协作者。 | 不要与人工审查者混用。 |
-| Matt Engineering Skills | 来自 `mattpocock/skills` 的轻量工程流程技能集合。 | 用于澄清、PRD、Issue、实现、TDD、诊断、审查和架构治理，不替代 YSS 专项规范。 |
+| Agent 入口规则 | Agent 启动任务时必须先遵守的全局路由、硬门禁和禁止事项。 | 不作为 YSS 后端、前端或其他专项编码规范的完整手册。 |
+| 标准文档语言 | 面向业务、产品、架构、实施、审查、发布和复盘的持久化文档所使用的默认语言。 | 统一使用简体中文；英文专有名词、代码标识、API 路径、schema、文件名和协议 metadata 保持原样。 |
+| Matt Engineering Skills | 来自 `mattpocock/skills` 的轻量工程流程技能集合。 | 用于澄清、Spec、Ticket、实现、TDD、诊断、审查和架构治理，不替代 YSS 专项规范。 |
 | YSS skills | 本项目内置的 YSS 工程规范技能。 | 用于 DDD、UI、OpenAPI、Repository、Controller、DTO、组件和编码规范。 |
-| PRD | 产品需求文档，用于记录用户问题、解决方案、用户故事、关键决策和测试 seam。 | 除非作为既有参考，否则不要写入具体实现文件路径。 |
+| 技能投影 | 从权威共享技能生成、供特定 Agent root 加载的同步副本。 | 投影不是独立维护的技能源，不应在各 Agent root 中分别修改。 |
+| Spec | 记录用户问题、解决方案、用户故事、关键决策、验收标准和测试 seam 的产品研发规格。 | 新资产统一使用 Spec；旧规格称谓只在迁移记录中保留。 |
+| Spec Delta | 记录相对于既有冻结 Spec 基线的 `ADDED / MODIFIED / REMOVED` 行为、验收场景和测试映射。 | 不用于全新产品或全新模块，也不替代完整 Spec、OpenAPI 或架构资产。 |
+| Ticket | 在追踪平台上承载功能生命周期或可实现工作单元的通用追踪对象。 | GitHub Issues / GitLab Issues 是具体平台对象名称；领域资产统一称为 Ticket。 |
+| 功能父 Ticket | 汇总一个功能从 Spec 到契约冻结的阶段状态、资产链接、审查结论和阻塞项的 Ticket。 | 不作为 Agent 直接实现的垂直切片。 |
+| 垂直切片 Ticket | 契约冻结后生成的可独立验证实现单元，记录范围、阻塞关系、验收标准和验证证据。 | 只有通过必要门禁并具备直接实现条件时才能标记 `ready-for-agent`。 |
+| `ready-for-human` | 表示 Spec、设计、契约草案或其他资产仍需人工审查或确认的流程状态。 | 此状态不表示可以直接进入实现。 |
+| `ready-for-agent` | 表示垂直切片已通过必要门禁并具备直接实现条件的流程状态。 | 不得用于 Spec 初稿、原型、OpenAPI Draft 或其他未冻结资产。 |
 | OpenAPI Draft | review-only 的 OpenAPI 3.1 契约草案。 | Freeze 前不得作为前后端稳定实现契约。 |
 | OpenAPI Freeze | 已通过评审、可作为前后端实现和契约测试输入的 OpenAPI 3.1 契约。 | Freeze 后变更必须回到 API 影响分析和设计审查。 |
-| 高保真 HTML 原型 | 低保真原型评审通过后，用于在浏览器中审查真实视觉密度、交互状态和页面流的产品设计资产。 | 不等同于生产前端实现，也不替代 OpenAPI、PRD 校准或垂直切片。 |
+| UI 影响 | 会改变用户可见页面、导航、交互流程、状态呈现或权限体验的功能影响。 | 纯后端、API、批处理或数据变更不自动构成 UI 影响。 |
+| 高保真 HTML 原型 | 低保真原型评审通过后，用于在浏览器中审查真实视觉密度、交互状态和页面流的产品设计资产。 | 不等同于生产前端实现，也不替代 OpenAPI、Spec 校准或垂直切片。 |
 | 垂直切片（Vertical Slice） | 贯穿所有受影响层、可独立验证的窄功能路径。 | 优先使用垂直切片，避免只按层拆分的横向任务。 |
 | ADR | 架构决策记录，用于沉淀难以回滚、非显而易见且存在真实取舍的技术决策。 | 常规实现选择不要写 ADR。 |
 | Fresh Verification | 完成前重新执行的验证证据，包括测试命令、契约校验、关键路径检查或人工审查结论。 | 不等同于“之前跑过”或实现者自述。 |
-| 流程模板资产 | 可被不同项目复用的文档模板、技能说明、校验脚本、流程规范和目录占位文件。 | 不包含某个具体产品的 PRD、设计、OpenAPI 或 Issue。 |
+| 测试质量基线 | 项目实例明确采纳的覆盖率阈值、关键流程清单和受控例外。 | 模板推荐值本身不构成可执行门禁；未定义关键流程时，不得声称其 E2E 覆盖率达到 100%。 |
+| 条件强制门禁 | 只有当影响面命中触发条件时才必须完成的生命周期审查点。 | 未触发时记录 `not-applicable` 及原因，不生成空文档；不要理解为所有任务默认执行全部门禁。 |
+| 单一事实来源（Single Source of Truth） | 对某一类流程事实拥有唯一定义权的权威资产。 | 其他资产只引用或解释，不重复定义同一规则。 |
+| 流程模板资产 | 可被不同项目复用的文档模板、技能说明、校验脚本、流程规范和目录占位文件。 | 不包含某个具体产品的 Spec、设计、OpenAPI 或 Ticket。 |
+| 模板维护流程 | 用于评估影响、修改权威资产、同步投影、执行压力验证并审查模板演进的工作流。 | 面向模板源仓库，不默认生成具体产品的 Spec、原型、OpenAPI 或垂直切片 Ticket。 |
+| 模板发布门禁 | 模板源发布前必须通过的结构、技能同步、流程语义和压力场景验证集合。 | 不等同于只检查文件存在、Markdown 链接或 YAML 语法。 |
 | Harness 工程 | 串联研发生命周期阶段、门禁、产物、Agent/Skill 编排和追踪证据的工程化治理载体。 | 不等同于单个 CI 流水线或零散提示词集合。 |
-| 研发管理仓库 | 承载 PRD、OpenAPI、架构、垂直切片、验证、发布和复盘等研发管理资产的仓库。 | 不等同于前端 / 后端代码 monorepo。 |
+| 研发管理仓库 | 承载 Spec、OpenAPI、架构、Ticket、验证、发布和复盘等研发管理资产的仓库。 | 不等同于前端 / 后端代码 monorepo。 |
 | 实现仓库 | 承载前端、后端或其他运行时代码及其 Git、CI、MR / PR、测试命令和发布流水线的仓库。 | 不要把实现仓库的源码所有权混入研发管理仓库。 |
-| 模板源仓库 | 承载 `yss-spec-project-template` 权威模板内容及其演进规则的仓库。 | 不等同于实例化后的具体项目仓库。 |
-| 模板实例仓库 | 由模板初始化后生成、面向某个具体项目使用的仓库。 | 不要与模板源仓库混用。 |
-| 模板初始化 CLI | 用于把模板源仓库实例化为新项目初始仓库的命令行工具。 | 不等同于业务运行时代码脚手架。 |
-| 模板同步 | 将已有模板实例仓库与某个更新后的模板快照进行对齐的过程。 | 不等同于重新初始化；通常要考虑本地改动保留、冲突提示和可回滚性。 |
-| 模板快照版本 | 某次发布时模板内容的可识别版本标识，通常对应 npm 包版本、Git tag 或 commit。 | 需要用于判断实例仓库当前基线和目标同步版本。 |
-| 受管模板文件 | 被 CLI 明确纳入同步策略的文件或目录集合。 | 只有受管文件才应被自动更新、跳过或冲突提示。 |
+| 跨仓库契约变更 | 需要两个或多个独立仓库协同实现、验证和按顺序发布的共享契约变化。 | 任一参与仓库未完成契约对齐和集成验证时，不得单独声称整体可发布。 |
+| 模板源仓库（`template-source`） | 承载 `yss-spec-project-template` 权威模板资产及其演进规则的仓库身份。 | 只管理可复用模板，不承载某个具体产品的研发生命周期资产。 |
+| 模板实例仓库（`project-instance`） | 由模板初始化后生成、承载某个具体产品研发生命周期资产的仓库身份。 | 不作为通用流程模板的权威来源。 |
+| 仓库身份清单 | 显式声明仓库身份和清单结构版本的机器可读资产。 | 不承载项目名称、团队规模、Tracker 或其他易变业务配置。 |
 
 只有在计划、分诊、调试或架构讨论中明确沉淀出稳定语言时，才新增术语。