create-yss-spec 2.1.15 → 2.2.1

package/template/wiki/raw/skills-maintenance.md

@@ -1,90 +0,0 @@
-# Skills 维护说明
-
-本文说明项目级 skills 的权威目录、投影方式、锁文件语义和升级验证。Agent 实际加载的入口仍是各目录中的 `SKILL.md`。
-
-## 权威内容与投影
-
-- `.agents/skills` 是跨 Agent 共享技能的唯一权威内容。
-- `.claude/skills`、`.codex/skills`、`.cursor/skills`、`.hermes/skills`、`.pi/skills`、`.qoder/skills`、`.trae/skills` 中的同名共享技能是生成投影，不得分别手工修改。
-- Cursor 的契约运行时入口是 `.cursor/skills`。若客户端同时枚举 `.claude/skills`，仍以 `.cursor/skills` 为 Cursor 投影契约，不得把两套同名 skill 解释为两个来源。
-- 分层、别名和默认可发现性以 `docs/agents/yss-skill-registry.yaml` 为准；该文件当前为 shadow，不改变 Agent 实际发现列表，也不允许 Router 按其裁剪闭包。
-- 只属于某个平台的 skill 继续保留在对应 root，并由 `skills-lock.json` 的 `platform` 分组记录。
-- 共享技能投影可以是指向权威目录的符号链接，也可以是完整同步副本；`scripts/sync-skills --check` 会检查链接目标或完整目录哈希。
-
-## 来源与锁定
-
-| 来源 | 固定版本 / 路径 | 用途 |
-|---|---|---|
-| `mattpocock/skills` | `0ab1b63a410a03d3627979a109c8695de27af954` / `skills/engineering` 及锁文件记录的关联路径 | 通用工程流程及关联 skills |
-| `anthropics/knowledge-work-plugins` | `sales/skills/competitive-intelligence` | 竞品与市场事实研究 |
-| 项目本地 | `.agents/skills` 或平台专属 root | YSS 适配与项目治理 skills |
-
-`skills-lock.json` 是技能清单、来源、上游哈希、当前有效内容哈希和投影目标的权威记录：
-
-- `upstreamHash`：能够追溯时记录未经项目适配的上游内容哈希。
-- `effectiveHash`：当前实际生效的完整 skill 目录树哈希。
-- `targets`：权威内容应投影到的 Agent roots。
-
-项目允许按 YSS 流程适配上游 skill，但必须同时保留可追溯的上游信息和适配后的有效哈希。
-
-当前 Matt 快照为 `0ab1b63a410a03d3627979a109c8695de27af954`。`ask-matt` 的关联入口包括 `to-questionnaire`、`wait-what`、`writing-for-agents` 和 `PHASE-BOUNDARIES.md`；这些支持文件随共享 skill 目录一起计算 `effectiveHash`，不得单独投影或维护。
-
-本轮升级还将生命周期适配固定为：阶段边界只写可选 `phase_boundary` 证据；`to-questionnaire` 使用 `external-input-required` 暂停并在答案回流后重新分类影响面；Matt `prototype` 使用 `prototype/<name>` 分支和单文件 HTML，YSS 高保真原型继续执行 Prototype Review、AntD CLI 校验和用户确认。人工 checkpoint 与 `diagnosing-bugs` 的输出必须脱敏，`wait-what` 不改变生命周期状态。
-
-## 维护流程
-
-1. 在临时目录读取或下载锁定来源，不直接覆盖工作区。
-2. 只在 `.agents/skills/<skill-name>/` 修改共享技能；平台专属技能只在所属 root 修改。
-3. 创建、修改或退役 skill 时使用 `maintaining-skills`，并先按 `docs/process/harness-process-tailoring.md` 判定验证与审查强度：L1 执行相关检查，L2 记录最小反例和 fresh verification，L3 记录完整 RED 基线、压力场景、GREEN 结果和 REFACTOR 检查。未定义分级的外部仓库按实际风险执行结构校验和针对性行为验证，不强制为每次普通修改构造失败基线。
-4. 生成共享投影并更新锁文件：
-
-   ```bash
-   scripts/sync-skills
-   scripts/update-skill-lock
-   ```
-
-   若来源来自可访问的 Matt checkout，还应显式校验锁定 revision 与每个上游目录哈希：
-
-   ```bash
-   scripts/verify-upstream-skill-source --source-root <matt-skills-checkout>
-   ```
-
-   新增共享 skill 时先显式登记：`scripts/update-skill-lock --add=<skill-name>`；新增平台专属 skill 使用 `scripts/update-skill-lock --add-platform=<root>:<skill-name>`。脚本不会把工作区中偶然出现的未跟踪目录自动纳入发布清单。
-
-5. 执行发布阻断校验：
-
-   ```bash
-   scripts/verify-template
-   ```
-
-   若模板维护引入或更新分发到实例的 Node 工具，先在 `.template-source/tooling/node/` 使用 `pnpm install --frozen-lockfile`，再运行 `pnpm build:vendor` 与 `pnpm check:vendor`；实例门禁不得安装依赖或重建 vendor。运行时、公开入口和跨仓回滚规则以 `.template-source/adr/0009-zero-install-node-tooling-runtime.md` 及对应契约为准。
-
-6. 需要重新加载技能的客户端在变更落地后重启或刷新项目。
-
-## 单独检查
-
-```bash
-scripts/sync-skills --check
-scripts/update-skill-lock --check
-# 可选：对照锁文件中的 mattpocock/skills revision 与上游目录哈希
-scripts/verify-upstream-skill-source --source-root <matt-skills-checkout>
-```
-
-前者检查所有共享投影是否指向或匹配权威内容，后者检查 `skills-lock.json` 是否与当前完整目录树一致。过时技能不会保留兼容别名；旧版项目按 `docs/user-guide/规格与任务迁移指南.md` 一次性迁移。
-
-## skills.sh 公开发布
-
-YSS 技能的公开发布仓库为 `iloveZzz/yss-spec-dev-skills`，它是本模板 `.agents/skills` 的单向发布投影，不是新的权威来源。
-
-- `yss-public-skills.json` 冻结允许公开的 YSS 技能清单；新增技能必须显式加入该清单。
-- `scripts/export-yss-skills --output <目录>` 从 canonical skills 生成公开目录；`--check --output <目录>` 只验证已有导出，不写入文件。
-- 公开仓库只包含 `skills/`、README、许可证、`skills.sh.json` 和发布校验；不得复制 `AGENTS.md`、`CONTEXT.md`、`skills-lock.json` 或各 Agent 投影目录。
-- 导出器会将本机绝对路径、Agent root 和模板内部路径转换为公开可移植形式，并阻断重复 skill 名、疑似凭据、符号链接和失效仓库内链接。
-- 发布顺序为：同步 canonical projections → 更新 lock → `scripts/verify-template` → 导出并检查 → 独立审查 → 在 `yss-spec-dev-skills` 提交人工 PR。不得从目标仓库反向覆盖 `.agents/skills`。
-- skills.sh 通过 `npx skills add iloveZzz/yss-spec-dev-skills` 的安装遥测自动发现技能，不需要手工注册；遥测可用 `DISABLE_TELEMETRY=1` 或 `DO_NOT_TRACK` 关闭。
-
-已退休、personal 或由 YSS 有意排除的条目（`design-an-interface`、`qa`、`request-refactor-plan`、`ubiquitous-language`、`edit-article`、`obsidian-vault`、`writing-great-skills`、`web-design-engineer`、`web-video-presentation`、`wireframe-prototype`、`wizard`、`git-guardrails-claude-code`、`claude-handoff`、`batch-grill-me`）不再进入 `.agents/skills`、六个共享投影根或 `skills-lock.json`。其中 `wizard` 是最新上游仍存在但 YSS 当前有意排除的人工步骤技能，不应描述为上游已退休。迁移时使用 `codebase-design`、`triage + to-tickets`、`to-spec + improve-codebase-architecture`、`domain-modeling`、`product-design:index`、普通人工 checkpoint 或 `handoff` 等现行路由，不创建兼容目录。
-
-## 外部工作流工具
-
-维护者可按需使用本机的 `gitlab-workflow`、`glab`、`gh` 或 `scripts/gitworks`。这些工具不是共享技能投影的一部分；平台选择与发布规则见 `docs/agents/issue-tracker.md`。

package/template/wiki/raw/spec-template.md

@@ -1,102 +0,0 @@
----
-pipeline: <feature-id>
-stage: open
-status: ready-for-human
-owner: ai
----
-
-# 产品研发规格：<功能名称>
-
-## 功能父 Ticket
-
-<Local：`docs/.scratch/<feature>/parent-ticket.md`；GitHub / GitLab：Issue URL / 编号>
-
-## 问题陈述
-
-（从用户视角描述要解决的问题。）
-
-## 解决方案
-
-（从用户视角描述解决方案。）
-
-## 用户故事
-
-1. 作为<角色>，我希望<能力>，以便<收益>。
-
-## 功能需求
-
-| ID | 需求 | 优先级 | 备注 |
-|---|---|---|---|
-| FR-001 | | P0/P1/P2 | |
-
-## 非功能需求
-
-| 类别 | 需求 | 目标 |
-|---|---|---|
-| 性能 | | |
-| 可靠性 | | |
-
-## 验收标准
-
-```gherkin
-假如 <上下文>
-当 <操作>
-那么 <可观察结果>
-```
-
-## 产品总体设计 / 功能架构
-
-- 功能域与模块边界：
-- MVP / 非目标：
-- UI 影响：是 / 否
-- 产品总体设计：`docs/.scratch/<feature>/design/<feature>-product-overview-design.md`
-
-> 只有存在 UI 影响时，才强制低保真页面草图、状态矩阵、高保真 HTML 原型和用户确认；否则记录 `not-applicable` 及原因。
-
-## OpenAPI 影响
-
-- [ ] 无
-- [ ] 需要 API 影响分析 / 契约草案
-- [ ] 需要 review-only OpenAPI Draft：`docs/.scratch/<feature>/api/<feature>.yaml`
-
-> OpenAPI Draft 在 OpenAPI Freeze 前仅用于评审和架构反审，不作为实现或生成客户端的稳定契约。
-
-受影响端点：
-
-| 方法 | 路径 | 变更 |
-|---|---|---|
-| | | |
-
-## DDD 影响判断
-
-> 仅做轻量判断，不新增流程阶段。若均为“否”，后续不需要单独 DDD 设计；若触发边界、模型或一致性变化，在产品总体设计 / 系统概要设计中补齐对应小节。
-
-| 检查项 | 是 / 否 | 说明 / 处理 |
-|---|---|---|
-| 是否新增或改变统一语言 / 核心术语 |  | 需要回写 `CONTEXT.md` 的中文术语和 PascalCase `英文标识` |
-| 是否新增或改变限界上下文 / 模块边界 |  | 需要在产品总体设计中完成 Strategic DDD Check |
-| 是否改变上下文间协作关系 |  | 说明上游 / 下游 / 防腐层 / 共享内核关系 |
-| 是否新增或改变聚合、不变量、状态机 |  | 需要在系统概要设计 / 数据架构中完成 Tactical DDD Check |
-| 是否影响 API、权限、数据、审计或风险 / 回滚约束 |  | 进入对应契约、架构或人工审查门禁 |
-
-## 测试决策
-
-- 主要测试 seam：
-- 代码库中的相似测试：
-- 必需测试：
-  - [ ] 单元 / 领域行为
-  - [ ] API / 契约
-  - [ ] 前端组件
-  - [ ] E2E 关键路径
-
-## AI / 人工审查点
-
-| 范围 | Agent 权限 | 是否需要人工审查 | 备注 |
-|---|---|---|---|
-| 支付逻辑 | 记录验证证据 | 是 | |
-| 原生 SQL | 记录验证证据 | 是 | |
-| 公共基础库 API | 记录验证证据 | 是 | |
-
-## 非目标范围
-
-## 风险

package/template/wiki/raw/triage-labels.md

@@ -1,15 +0,0 @@
-# Triage 标签
-
-本文定义 Agent 分诊时使用的五种标准角色，以及它们在当前 Ticket tracker 中对应的标签。
-
-| 标准角色 | Tracker 标签 | 含义 |
-| --- | --- | --- |
-| `needs-triage` | `needs-triage` | 等待维护者评估 Ticket |
-| `needs-info` | `needs-info` | 等待报告者补充信息 |
-| `ready-for-agent` | `ready-for-agent` | 必要门禁已通过、阻塞边已清除，可由 Agent 直接实现的垂直切片 Ticket |
-| `ready-for-human` | `ready-for-human` | Spec、设计、契约草案或其他资产需要人工审查、判断或特权访问 |
-| `wontfix` | `wontfix` | 不会处理 |
-
-当 skill 提及某个标准角色时，使用表中对应的 Tracker 标签。
-
-Local Markdown 主 tracker 不调用远程标签：在 Ticket 文件顶部使用同名 `Status:` 值记录标准角色。Wayfinder 的 `claimed` / `resolved` 仅是临时工作状态，不属于本表五态；进入交付 Ticket 前必须转换为标准 `Status:`。

package/template/wiki/raw/vertical-slice-ticket-template.md

@@ -1,132 +0,0 @@
----
-status: ready-for-human
----
-
-# 垂直切片 Ticket：<标题>
-
-Status: ready-for-human
-
-## 父级
-
-<Spec：`docs/.scratch/<feature>/spec.md`；功能父 Ticket：`docs/.scratch/<feature>/parent-ticket.md` 或远程 Issue URL>
-
-## 要构建什么
-
-描述本 Ticket 要交付的窄而完整的端到端行为。它必须贯穿所有受影响层，是可独立验证的垂直切片，不能只是某一层的横向任务。
-
-## 覆盖的用户故事
-
-- <用户故事 ID 或文本>
-
-## OpenAPI 影响
-
-- [ ] 无
-- [ ] 基于冻结 OpenAPI：`docs/.scratch/<feature>/api/<feature>.yaml`
-
-受影响端点：
-
-| 方法 | 路径 | 变更 |
-|---|---|---|
-| | | |
-
-## 验收标准
-
-- [ ] 标准 1
-- [ ] 标准 2
-- [ ] 标准 3
-
-## 测试 Seam
-
-- 主要公共接口：
-- 必需测试：
-  - [ ] 行为 / 领域测试
-  - [ ] API / 契约测试
-  - [ ] UI / 组件测试
-  - [ ] E2E 测试
-
-## Slice Implementation Contract
-
-| 字段 | 内容 |
-|---|---|
-| contract_id |  |
-| contract_version |  |
-| contract_ref |  |
-| Router 状态 | draft / blocked / ready-for-lifecycle-review |
-| 生命周期批准状态 | pending / approved / rejected |
-| Build Architecture Checklist |  |
-
-> Router 不得自行将合同批准或将本 Ticket 推进为 `ready-for-agent`。只有生命周期编排器核验并持久化当前版本合同、清除阻塞边后，才能推进状态。
-
-### 工作单元
-
-| work_unit_id | 验收行为 / 目标 | primary_skill | supporting_skills | tdd_mode | allowed_write_paths | expected_evidence | verification_commands | Execution Result 引用 | 状态 |
-|---|---|---|---|---|---|---|---|---|---|
-|  |  |  |  | behavior-tdd / controlled-generation |  |  |  |  | pending / running / blocked / completed / stale |
-
-`controlled-generation` 仅允许机械脚手架、样板、冻结客户端或配置，并记录 exception reason、生成器输入和生成后行为测试；业务规则、状态机、事务、权限、错误映射、复杂查询和用户可见交互必须使用 `behavior-tdd`。只有需求明确包含权限业务行为时才把它写入工作单元，不另设安全 / 权限姿态。
-
-## YSS 技能与后端实现合同
-
-> 涉及后端时必须填写；不涉及时写明 `not-applicable`。不得只写“符合 YSS”。
-
-| 影响面 | 必需 skill | 需要 / 不需要的理由 | 预期证据 |
-|---|---|---|---|
-| Domain / 领域行为 | `yss-domain` |  |  |
-| Application / 用例编排 | `yss-application` |  |  |
-| Infrastructure / Repository | `yss-repository` / `yss-mybatis` |  |  |
-| Web Adapter / DTO | `yss-web-controller` / `yss-dto` |  |  |
-| POJO / 对象转换 | `lombok` / `mapstruct` |  |  |
-| Java 规范 | `alibaba-java-code-style` |  |  |
-
-### 后端阻断规则
-
-- [ ] 未填写 `Backend Slice Implementation Contract` 时不得写后端业务代码。
-- [ ] `CMD` / `Query` / `VO` / `SingleResult` / `MultiResult` / `PageResult` 按 `yss-dto` 定义或复用；不私自新建 / 混用响应包装。
-- [ ] Controller 不用内部类或非约定包临时承载主要 DTO / VO；写操作参数继承 `CommandDTO`，读操作参数继承 `QueryDTO` 或 `PageQuery`，分页查询优先继承 `PageQuery`。
-- [ ] Controller 不手工分页主要业务集合，不穿透 Repository / Mapper / PO。
-- [ ] Application 只做用例编排、事务边界和跨聚合协调，核心领域规则放入 Domain。
-- [ ] 需要持久化的切片必须补 PO / Repository / Convertor / GatewayImpl；临时 `InMemory*Gateway` 必须标记 `seam-deferred`。
-- [ ] POJO 样板代码默认使用 Lombok；成片手写 getter/setter、constructor、builder、logger 必须说明例外原因、测试证据和 review 结论。
-- [ ] MapStruct / Convertor 强制优先；`BeanUtils.copyProperties`、反射式通用拷贝或重复手写 mapping 必须说明例外原因、测试证据和 review 结论。
-
-## 阻塞关系
-
-- 无，可立即开始
-
-## 重路由状态
-
-| 字段 | 内容 |
-|---|---|
-| reroute_status | current / incremental-review / full-reroute-required / lifecycle-return / stale |
-| trigger | 新 API/schema / 状态机 / 数据模型 / 写路径 / 仓库 / skill / seam / 风险 / 交付顺序 / other |
-| affected_work_units |  |
-| new_impacts |  |
-| stale_contract_version |  |
-| return_stage | Router / Architecture Re-check / 产品设计 / OpenAPI Draft-Review-Freeze / 系统或数据架构 / other |
-| recovery_conditions |  |
-
-出现 `drift`、`violation` 或非空 `new_impacts` 时暂停受影响工作单元，不得先完成代码再补合同；更新合同版本并通过生命周期审查后才能恢复。
-
-## 状态
-
-`ready-for-agent`
-
-> 仅当阻塞关系为“无”且必要门禁已通过时填写 `ready-for-agent`；否则写明被哪个 Ticket 阻塞。
-
-## AI / 人工审查点
-
-- [ ] 无高风险变更或需人工确认项
-- [ ] 原生 SQL：记录验证证据
-- [ ] 公共基础库 API：记录验证证据
-
-## 完成定义
-
-- [ ] 如有需要，已基于冻结 OpenAPI Spec 拆分切片
-- [ ] 实现完成
-- [ ] 已新增测试且测试通过
-- [ ] 已移除调试 / 原型代码
-- [ ] 已回勾 `Backend Slice Implementation Contract` 和 `Build Architecture Checklist`
-- [ ] 已回勾当前 `contract_id` / `contract_version`、全部工作单元和对应 `YSS Skill Execution Result`
-- [ ] 实际 changed files 均在合同允许路径内，预期证据齐全，验证结果包含执行时间
-- [ ] `new_impacts`、`drift`、`violation` 和重路由状态均有明确结论，合同未处于 `stale`
-- [ ] 如领域或架构决策变化，已更新 `CONTEXT.md` / ADR；新增业务术语含 PascalCase `英文标识`，代码与契约字段能追溯到该词干

package/template/wiki/raw/yss-project.yaml

@@ -1,2 +0,0 @@
-schema_version: 1
-repository_mode: template-source