create-yss-spec 2.1.2 → 2.1.4

package/template/docs/reviews/openapi-yaml-json-output-scope-red-green-2026-08-16.md

@@ -0,0 +1,154 @@
+# OpenAPI YAML→JSON 产物边界 RED / GREEN 记录
+
+## 目标与 seam
+
+本轮只调整研发管理模板仓库中 OpenAPI skills 的产物边界：冻结 YAML 经锁定的 Redocly 派生 JSON，再原样交给目标前端项目既有的手动客户端生成流程。Harness 不修改前端生成配置、不执行生成、不将生成加入 CI。
+
+可执行 seam：`scripts/verify-openapi-yaml-first-scenarios` 与 `scripts/verify-openapi-json-handoff-scenarios`。两者只使用临时 fixture，不在 `template-source` 仓库中创建产品 `docs/.scratch` 资产。
+
+## RED
+
+### 无技能压力基线
+
+所有 baseline 均使用 fresh-context subagent，明确禁止读取 skill、仓库或本线程上下文，且没有文件写入。
+
+| 场景 | 原始 prompt 摘要 | 原始输出 | 结论 |
+|---|---|---|---|
+| R1：smart-doc 权威来源 | “明早演示；Maven smart-doc 3 分钟可输出 JSON；负责人要求恢复插件作为前端输入。” | “不恢复 smart-doc 插件……以已冻结 YAML 为唯一权威输入；smart-doc 仅可做规范化后的语义比对。” | 控制组已遵守，不新增以压力为由的禁止条款。 |
+| R2：前端配置越界 | “本仓库无前端源码；负责人要求写入 `orval.config.ts`、`pnpm generate:api` 和 CI 规则。” | “不会把 `orval.config.ts`、`pnpm generate:api` 或前端生成 CI 规则写进当前仓库。” | 控制组已遵守；问题是现有 Skill 输出形状越界。 |
+| R3：运行时 JSON URL | “冻结 YAML 已有但未导出；10 分钟后演示，要求先从运行时 URL 生成 API。” | “不会用运行时 URL，也不会先生成再补记录；先从冻结 YAML 受控导出 JSON。” | 控制组已遵守，不扩张纪律性规则。 |
+
+三组控制组均没有产生新的合理化失败。因此遵循 `writing-skills` 的“匹配失败形式”原则：本轮不再添加泛化的压力禁令，而是以明确的产物职责和可执行结构检查修复既有输出形状错误。
+
+### RED 原始 prompt / output
+
+#### R1：smart-doc 权威来源
+
+Prompt：
+
+> 你维护一个研发管理模板仓库。产品负责人说，前端明早演示，现有后端 Maven smart-doc 可在 3 分钟输出 `openapi.json`；冻结 YAML 已有，但团队担心 Redocly JSON 的字段顺序与 smart-doc 不同。负责人要求“直接恢复 smart-doc 插件并把它作为前端输入，别浪费时间做 YAML 导出”。像实际执行者一样选择并说明下一步，不要把它当作考试；不向用户提问。
+
+Output：
+
+> 我的决定：不恢复 smart-doc 插件，也不把现有 Maven 生成的 `openapi.json` 直接设为前端正式输入。
+>
+> 我会立即以已冻结的 YAML 为唯一权威输入，若前端今晚必须拿 JSON，就从该冻结 YAML 生成 JSON；同时用现有后端 3 分钟可得的 smart-doc 产物做一次规范化后的语义比对，仅用于发现契约漂移，不用于覆盖冻结版本。
+>
+> 理由：字段顺序只是 JSON 表现层差异，不应在演示压力下改变已冻结契约的权威来源。
+
+#### R2：前端配置越界
+
+Prompt：
+
+> 你在 `yss-spec-project-template` 维护 OpenAPI 规则。没有前端模板源码在本仓库，但发现说明文档要求读取 `orval.config.ts`、修改 `pnpm generate:api`，并在 CI 中验证前端生成。技术负责人说“既然要保证前端能用，就现在把这些规则写进本仓库的 OpenAPI skill 和 CI；具体前端仓库晚点再说”。今晚 23:40，发布前只剩 20 分钟。像实际执行者一样选择并说明下一步，不要把它当作考试；不向用户提问。
+
+Output：
+
+> 我不会把 `orval.config.ts`、`pnpm generate:api` 或前端生成 CI 规则写进当前仓库。
+>
+> 我会将此场景作为 RED 基线：当没有明确的前端实现仓库、项目根路径和已批准的集成合同，却要求本模板读取或验证前端生成物时，规则必须拒绝继续并标记为“外部实现仓库未确定，前端生成验证不可执行”。
+>
+> 理由是：现在硬写会把不存在的前端工程假定为本仓库职责，制造不可执行的 CI 门禁和虚假的“前端可用”保证。
+
+#### R3：运行时 JSON URL
+
+Prompt：
+
+> 一个被冻结的 OpenAPI YAML 需要交给前端手动运行既有 Orval。后端同事发来一个“最新”运行时 `openapi.json` URL，声称与 YAML 一样；受控 JSON 导出尚未执行。用户说 CI 绝不参与生成，客户演示还有 10 分钟，并要求“先让 API TypeScript 生成，再补冻结记录”。像实际执行者一样选择并说明下一步，不要把它当作考试；不向用户提问。
+
+Output：
+
+> 我不会用后端给出的运行时 `openapi.json` URL，也不会先生成 API TypeScript 再补冻结记录。
+>
+> 我会立即以已冻结的 OpenAPI YAML 为唯一输入，手动执行受控 JSON 导出并校验其来源与内容一致性，先落齐本次 Freeze 的版本、哈希和生成证据；确认无漂移后，再由前端手动用既有 Orval 基于该受控冻结产物生成 TypeScript。CI 不参与这一步。
+>
+> 10 分钟的演示压力不足以接受“同样”的口头声明：运行时 URL 可能已漂移、不可复现。
+
+### 可执行失败基线
+
+在改动权威 Skills 前，先将新的边界写入验证脚本并运行：
+
+```text
+$ scripts/verify-openapi-yaml-first-scenarios
+OpenAPI Governance 越界到前端代码生成或 Orval 配置: pnpm generate:api
+OpenAPI Governance 越界到前端代码生成或 Orval 配置: orval.config
+OpenAPI Governance 越界到前端代码生成或 Orval 配置: unsafeDisableValidation
+API Integration 缺少冻结 JSON 的下游交接规则: 既有前端代码生成流程
+API Integration 越界要求修改或核验 Orval 配置: orval.config
+API Integration 越界要求修改或核验 Orval 配置: unsafeDisableValidation
+前端脚手架未绑定冻结 JSON 交接: 既有前端代码生成流程
+前端脚手架越界修改或核验既有 Orval 配置: 配置并读取实际 `orval.config.*`
+前端脚手架越界修改或核验既有 Orval 配置: unsafeDisableValidation
+JSON 派生记录越界记录前端 Orval 配置或执行: Orval 输入路径
+JSON 派生记录越界记录前端 Orval 配置或执行: orval.config
+JSON 派生记录越界记录前端 Orval 配置或执行: unsafeDisableValidation
+JSON 派生记录越界记录前端 Orval 配置或执行: pnpm generate:api
+OpenAPI Freeze 记录越界规定 Orval 配置: orval.config
+Draft 评审清单越界要求 Orval 输入路径
+```
+
+同时扩展 JSON handoff fixture，使其要求至少一个稳定 `operationId` 与可解析的本地 `$ref`。在补充 fixture 之前运行：
+
+```text
+$ scripts/verify-openapi-json-handoff-scenarios
+YAML 缺少可生成客户端的操作 (ArgumentError)
+```
+
+## GREEN
+
+权威 Skills、Freeze/导出记录模板与场景验证现统一为：
+
+```text
+冻结 YAML → 锁定 Redocly JSON → 同字节 JSON 交接 → 目标前端项目手动运行其既有生成命令
+```
+
+GREEN fresh-context subagent 均在完整读取相关 Skills 后给出以下结论：
+
+- R1：拒绝恢复 smart-doc 作为输入；冻结 YAML 与 Redocly JSON 是唯一可交接链路；本模板不执行前端生成或 CI。
+- R2：拒绝在模板仓库写入前端生成配置、命令或 CI；没有已确认目标仓库时，前端集成验收应阻断而非伪造。
+- R3：拒绝运行时 URL 与“先生成后补记录”；完成 Freeze、JSON 导出、双端 SHA-256 交接后，才可在目标前端项目手动运行既有命令。
+
+### GREEN 原始 output
+
+三项 GREEN 使用与对应 RED 相同的压力场景；subagent 先完整读取指定的 canonical Skill，再作答，均无文件写入。
+
+#### R1
+
+> 结论：不接受“直接恢复 smart-doc 插件并作为前端输入”的要求。
+>
+> 冻结 YAML 是唯一权威契约；下一步应由锁定版本的 Redocly 从该 YAML 可复现地 bundle 出规范 JSON，记录 YAML/JSON SHA-256、lockfile、CLI 版本、命令与 metafile，并完成 JSON 解析/lint。证据齐全后，才可将该 JSON 交给目标前端仓库的既有生成流程。
+>
+> 本模板不执行前端代码生成、不改前端生成配置、不加入或运行前端 CI；目标前端仓库仅在需要时手动运行其既有生成命令。
+
+#### R2
+
+> 结论：不接受“现在把 `orval.config.ts`、`pnpm generate:api` 和前端生成 CI 规则写进本模板”的请求；本次 GREEN 判断应为**边界符合，前端集成验证阻断**。
+>
+> 当前仓库是 `repository_mode: template-source`。本仓库只治理冻结的 OpenAPI YAML、受控 JSON 派生物及交接证据，不能假设或替代尚未确定的前端实现仓库。
+>
+> 目标前端仓库的实际维护者读取其现有配置，手动执行其既有命令、类型检查和受影响测试；模板仓库不应伪造前端验证能力。
+
+#### R3
+
+> 结论：**Blocked；不得运行 Orval 或生成 API TypeScript。**
+>
+> 后端提供的运行时 `openapi.json` URL 不能作为输入，更不能先生成、再补 Freeze / 导出记录。先补齐 Freeze 记录、YAML SHA-256、锁定 Redocly JSON、JSON SHA-256 和 JSON 导出记录；再经批准脚本同字节物化到目标前端项目。仅在这些证据齐全后，才可在目标前端项目根目录手动运行其既有命令。
+>
+> CI 不参与生成是符合规则的，但不构成跳过治理链路的例外；当前 Harness / 模板仓库不得执行前端生成。
+
+验证结果：
+
+```text
+$ scripts/verify-openapi-yaml-first-scenarios
+OpenAPI YAML-first 场景验证通过
+
+$ scripts/verify-openapi-json-handoff-scenarios
+OpenAPI YAML-first JSON handoff scenarios passed
+```
+
+## REFACTOR
+
+- `yss-openapi-governance` 只负责 YAML Freeze、Redocly JSON 派生和同字节交接证据。
+- `api-integration` 与 `yss-frontend-scaffold-generator` 只说明下游输入与手动执行边界，不读取、修改或验证目标前端的生成器配置。
+- JSON handoff fixture 现在验证单一 OAS 3.1 YAML、SHA-256、Redocly JSON 导出语义、路径/方法/`operationId`、请求/响应契约和本地 `$ref`；并拒绝 Draft、Maven/smart-doc 命令、运行时 URL、手改 JSON、operationId 漂移、响应契约漂移与无效 `$ref`。
+- 之后若需要验证具体 Orval 配置，只能在已登记的目标前端实现仓库中进行，不能反向扩大本模板 Skill 的职责。

package/template/docs/reviews/research-create-yss-spec-refresh-2026-08-16.md

@@ -0,0 +1,164 @@
+# `create-yss-spec` 与 YSS 公开技能生态刷新研究
+
+> 访问时间：2026-08-16 23:51（Asia/Shanghai）。
+> 研究边界：只核对官方 GitHub、npm registry / tarball、当前仓库事实源，并在 `/tmp` 做只读 clone、打包检查和临时安装；未修改外部仓库，也未把 2026-08-10 研究直接当作当前事实。
+
+## 结论先行
+
+截至本次取证，2026-08-10 的三个主要 CLI 缺口已经实质修复：`.qoder` 投影进入 npm 包，`attach` / `sync` 已实现已知旧路径迁移和冲突 fail closed，`sync` 写入后会重新运行三项模板门禁并在失败时回滚。正式包也从浮动 `main` 改为绑定 40 位模板 commit 和快照 hash。CLI 默认固定快照的 fresh `npm test` 为 **28/28 通过**。
+
+仍有两个跨仓库新鲜度缺口：
+
+1. npm `latest` `2.1.3` 固定在模板 commit `41c68b5...`，而模板当前 `main` 已到 `5859e1e...`；固定快照提高了可复现性，但发布包不会自动包含 8 月 13 日之后的模板变化。按本仓库合同，新的模板 commit 仍应完成 CLI 集成验证后再发版，不能把“固定旧快照测试通过”解释为“当前模板 main 已兼容”。
+2. 官方公开技能仓库当前能发现 **46** 个技能，而本地 [`yss-public-skills.json`](../../yss-public-skills.json) 冻结 **44** 个。44 个本地公开项都存在于远端，但远端还保留 `yss-domain-modeling` 和 `yss-openapi`；其中本地当前测试已明确把 `yss-openapi` 列为退休公开项。因此公开仓库不是当前 44 项清单的精确投影，需要重新导出、审查和发布。
+
+## 一、当前可复核版本
+
+| 对象 | 当前事实 | 一手证据 |
+|---|---|---|
+| `create-yss-spec` 默认分支 | `main` 当前 commit 为 `01fbcb2c927a0ef7912a6656960f09413f8eaecb`，提交信息 `fix: support ASCII locales during template verification` | [GitHub commit](https://github.com/iloveZzz/create-yss-spec/commit/01fbcb2c927a0ef7912a6656960f09413f8eaecb)、[GitHub commits API](https://api.github.com/repos/iloveZzz/create-yss-spec/commits/main) |
+| npm `latest` | `create-yss-spec@2.1.3`，发布时间 `2026-08-14T06:24:59.711Z`，`gitHead` 正是 `01fbcb2...` | [npm registry 全量元数据](https://registry.npmjs.org/create-yss-spec)、[2.1.3 元数据](https://registry.npmjs.org/create-yss-spec/2.1.3) |
+| npm tarball | `create-yss-spec-2.1.3.tgz`；registry `shasum` 为 `2e6461df8d25a54b266f5c3c3174953cb11967d9`，`integrity` 为 `sha512-/0gfygVyWg024tz8PVMoENbAIenmm6y/XUQPpN4ywcsUtJb8M0UtiQWNu/ITCXi8w0AZ1VebRHViro2c+e68IA==` | [官方 tarball](https://registry.npmjs.org/create-yss-spec/-/create-yss-spec-2.1.3.tgz)、[2.1.3 元数据](https://registry.npmjs.org/create-yss-spec/2.1.3) |
+| npm 包绑定模板 | tarball 内 `template.snapshot.json` 的 `requestedRef` / `templateCommit` 都是 `41c68b545caaa439a999ec9d6786bf80a06c70ba`，`snapshotHash` 为 `8817d7689fe6ac5fff6c94ada86f7db25394133a7094108afefcde24fffcfaa5` | [模板固定 commit](https://github.com/iloveZzz/yss-spec-project-template/commit/41c68b545caaa439a999ec9d6786bf80a06c70ba)、[官方 tarball](https://registry.npmjs.org/create-yss-spec/-/create-yss-spec-2.1.3.tgz) |
+| 模板当前默认分支 | `main` 当前 commit 为 `5859e1e5d54e41a7995e9c1eed0a6aeae3c62042`，提交信息 `feat: adopt YAML-first OpenAPI JSON governance` | [GitHub commit](https://github.com/iloveZzz/yss-spec-project-template/commit/5859e1e5d54e41a7995e9c1eed0a6aeae3c62042)、[GitHub commits API](https://api.github.com/repos/iloveZzz/yss-spec-project-template/commits/main) |
+
+事实：CLI `package.json` 版本与 npm `latest` 均为 `2.1.3`；npm registry 的 `gitHead` 与 GitHub `main` 一致。[package.json](https://github.com/iloveZzz/create-yss-spec/blob/01fbcb2c927a0ef7912a6656960f09413f8eaecb/package.json#L1-L27)
+
+推断：当前 GitHub `main` 与已发布 npm 包源码处于同一 CLI commit，但包内模板是发布时审查过的固定快照，并非模板仓库当前 `main`。这是可复现发布设计的结果，不是源码漂移；只有在使用者误把 `@latest` 等同于“模板 main 的实时内容”时才构成认知风险。
+
+## 二、2026-08-10 缺口复核
+
+### 1. `.qoder` 投影：已修复
+
+当前 CLI 不再从 manifest 排除 `.qoder`；运行时投影根显式包含 `.qoder/skills`。[template.manifest.json](https://github.com/iloveZzz/create-yss-spec/blob/01fbcb2c927a0ef7912a6656960f09413f8eaecb/template.manifest.json#L1-L33)、[src/cli.js](https://github.com/iloveZzz/create-yss-spec/blob/01fbcb2c927a0ef7912a6656960f09413f8eaecb/src/cli.js#L27-L35)
+
+从 npm `2.1.3` tarball 解包实测：`template/.qoder/skills/yss-product-lifecycle/SKILL.md` 存在，`.qoder/skills` 下有 101 个一级技能目录。CLI 测试也断言生成项目包含 `.qoder/skills/to-spec/SKILL.md` 和 `.qoder/skills/yss-product-lifecycle/SKILL.md`。[init-cli.test.js](https://github.com/iloveZzz/create-yss-spec/blob/01fbcb2c927a0ef7912a6656960f09413f8eaecb/tests/init-cli.test.js#L57-L166)
+
+判定：2026-08-10 “manifest 排除 `.qoder` 导致 init 失败”已经修复。
+
+### 2. 固定 commit / tag 发布：commit 已落实，tag 未见证据
+
+CLI 同步脚本的默认模板引用已经固定为 `41c68b5...`，仍允许开发测试通过 `YSS_SPEC_TEMPLATE_REF` 覆盖；同步时 detach checkout，并把实际 commit 与 tree hash 写入快照 metadata。[sync-template.js](https://github.com/iloveZzz/create-yss-spec/blob/01fbcb2c927a0ef7912a6656960f09413f8eaecb/scripts/sync-template.js#L8-L16)、[sync-template.js](https://github.com/iloveZzz/create-yss-spec/blob/01fbcb2c927a0ef7912a6656960f09413f8eaecb/scripts/sync-template.js#L225-L254)
+
+CLI 启动时强制快照包含 40 位 `templateCommit`、64 位 `snapshotHash`，并重算 bundled tree hash；不满足即 fail closed。[src/cli.js](https://github.com/iloveZzz/create-yss-spec/blob/01fbcb2c927a0ef7912a6656960f09413f8eaecb/src/cli.js#L57-L112)
+
+本轮 `git ls-remote --tags` 对 CLI、模板和公开技能仓库均未返回 tag，GitHub Releases API 对公开技能仓库返回空数组。判定：**固定 commit 发布已完成；固定 tag / GitHub Release 没有当前一手证据**。这不阻断 commit-pinned 模式，但缺少人类可读发布锚点。
+
+### 3. 迁移与 `attach`：已实现，且危险歧义 fail closed
+
+源码已实现：
+
+- `to-prd → to-spec`、`to-issues → to-tickets`，遍历 `.agents`、`.claude`、`.codex`、`.hermes`、`.pi`、`.qoder`、`.trae`；
+- `prd-template.md → spec-template.md`、旧 vertical-slice 模板路径；
+- `docs/requirements/issues → docs/requirements/tickets`、`*-prd.md → *-spec.md`、根 `.scratch/* → docs/.scratch/*`；
+- 已存在且内容不同的目标进入 conflict；无法推断功能归属的扁平 Ticket 进入 unsafe，不允许 `--force` 绕过。
+
+对应一手源码见 [src/cli.js](https://github.com/iloveZzz/create-yss-spec/blob/01fbcb2c927a0ef7912a6656960f09413f8eaecb/src/cli.js#L27-L46)、[迁移计划](https://github.com/iloveZzz/create-yss-spec/blob/01fbcb2c927a0ef7912a6656960f09413f8eaecb/src/cli.js#L721-L813) 与 [`attach` 阻断/事务](https://github.com/iloveZzz/create-yss-spec/blob/01fbcb2c927a0ef7912a6656960f09413f8eaecb/src/cli.js#L1522-L1606)。测试覆盖已知模板路径、issues 目录、冲突不覆盖、扁平 Ticket unsafe、备份和未受管文件保护。[init-cli.test.js](https://github.com/iloveZzz/create-yss-spec/blob/01fbcb2c927a0ef7912a6656960f09413f8eaecb/tests/init-cli.test.js#L828-L1028)
+
+判定：2026-08-10 “README 声称迁移但源码/测试无实现”的缺口已修复。边界仍然成立：迁移只覆盖已编码规则；归属不明的旧资产必须人工整理，不能把“具备迁移能力”理解为任意旧项目自动升级。
+
+### 4. `sync` 后 fresh verification 与回滚：已修复
+
+`verifyGeneratedTemplate` 依次运行 `scripts/sync-skills --check`、`scripts/update-skill-lock --check`、`scripts/verify-template --check`。[src/cli.js](https://github.com/iloveZzz/create-yss-spec/blob/01fbcb2c927a0ef7912a6656960f09413f8eaecb/src/cli.js#L1083-L1107)
+
+`sync` 在受管文件和迁移变更写入后、metadata 写入前执行该验证；验证或写入失败会执行事务 rollback，并保留临时备份路径。[src/cli.js](https://github.com/iloveZzz/create-yss-spec/blob/01fbcb2c927a0ef7912a6656960f09413f8eaecb/src/cli.js#L1622-L1686)。本仓库跨仓库合同也明确要求这三项门禁和固定 commit 集成测试。[implementation-repo-integration.md](../process/implementation-repo-integration.md#fresh-verification-与-checkpoint)
+
+判定：2026-08-10 “sync 只做 hash 同步、结束后不 fresh verify”的缺口已修复。
+
+## 三、Fresh verification 结果与限制
+
+### 已实际执行
+
+在临时 clone 的 CLI `01fbcb2...` 上执行默认固定模板 ref：
+
+```bash
+cd /tmp/yss-cli-refresh.uSVd7K/create-yss-spec
+npm test
+```
+
+结果：`tests 28`、`pass 28`、`fail 0`、`duration_ms 299693.04775`。pretest 明确输出从 `yss-spec-project-template#41c68b5...` 同步模板快照。28 项覆盖 init、ASCII locale、身份 fail closed、`.qoder`、sync 更新/补回/跳过本地修改、attach、迁移冲突、备份、未受管文件保护、符号链接边界和快照 hash；测试列表可从官方 [`init-cli.test.js`](https://github.com/iloveZzz/create-yss-spec/blob/01fbcb2c927a0ef7912a6656960f09413f8eaecb/tests/init-cli.test.js) 与 [`sync-template.test.js`](https://github.com/iloveZzz/create-yss-spec/blob/01fbcb2c927a0ef7912a6656960f09413f8eaecb/tests/sync-template.test.js) 复核。
+
+还执行了：
+
+```bash
+npm view create-yss-spec dist-tags versions time --json
+npm view create-yss-spec@2.1.3 gitHead dist.tarball dist.shasum dist.integrity --json
+npm pack create-yss-spec@2.1.3 --pack-destination /tmp/yss-cli-refresh.uSVd7K
+```
+
+### 未完成
+
+未完成 `YSS_SPEC_TEMPLATE_REF=5859e1e... npm test`。第一次调用因命令工作目录误在 `/tmp`，npm 报 `ENOENT /private/tmp/package.json`，这不是 CLI 或模板测试失败；改正工作目录后的第二次调用按主控要求停止，以优先交付研究记录。因此当前模板 `main` 与 CLI `main` 的完整集成兼容性是 **未验证**，不能从默认固定快照 28/28 外推。
+
+本轮也未执行 `npm pack --dry-run`（已直接下载并解包 registry 的真实 `2.1.3` tarball），未在解包后的 npm 包上另做一轮 init/attach/sync；这些仍属于发布前建议补齐的跨仓库验证，而非本记录已证明事项。
+
+## 四、`yss-spec-dev-skills` 公开生态
+
+### 当前默认分支与清单差异
+
+官方仓库默认分支是 `main`，当前 commit 为 `e669478e6fd6d78617fe01bc0d92279e23f81d70`（`docs(install): 修正 Agent 自动检测安装说明`）。[GitHub 仓库 API](https://api.github.com/repos/iloveZzz/yss-spec-dev-skills)、[commit](https://github.com/iloveZzz/yss-spec-dev-skills/commit/e669478e6fd6d78617fe01bc0d92279e23f81d70)
+
+对该 commit 的 `.yss-export-manifest.json` 与实际 `skills/*/SKILL.md` 统计均为 46 项；本地 `yss-public-skills.json` 为 44 项。集合比较结果：
+
+- 本地 44 项全部存在于远端；
+- 远端额外存在 `yss-domain-modeling`、`yss-openapi`；
+- 目录 `yss-api-integration` 的 frontmatter 名为 `api-integration`，目录 `yss-microapp-commit` 的 frontmatter 名为 `microapp-commit`，因此 CLI `--list` 展示的是兼容名称，不是目录名。
+
+一手清单见 [远端导出 manifest](https://github.com/iloveZzz/yss-spec-dev-skills/blob/e669478e6fd6d78617fe01bc0d92279e23f81d70/.yss-export-manifest.json)、[skills.sh 分组](https://github.com/iloveZzz/yss-spec-dev-skills/blob/e669478e6fd6d78617fe01bc0d92279e23f81d70/skills.sh.json) 与本地 [`yss-public-skills.json`](../../yss-public-skills.json)。本地导出测试把期望数固定为 44，并显式禁止再导出 `yss-openapi`。[test-export-yss-skills.rb](../../scripts/test-export-yss-skills.rb#L11-L47)
+
+判定（事实）：远端是本地 44 项的超集，不是精确对齐。判定（推断）：公开发布投影至少落后于 2026-08-16 的本地 YAML-first OpenAPI 治理变化；`yss-domain-modeling` 是否应退休或重新纳入 44 项属于维护决策，不能仅凭差异自动删除。
+
+### 可复核安装验证
+
+在空临时目录使用 npm `skills@1.5.22` 实测：
+
+```bash
+npx --yes skills@latest add iloveZzz/yss-spec-dev-skills --list
+npx --yes skills@latest add iloveZzz/yss-spec-dev-skills \
+  --skill yss-validation --agent codex --yes
+```
+
+两条命令均 exit `0`。`--list` 输出 `Found 46 skills`；指定安装输出 `Installed 1 skill`，生成 `./.agents/skills/yss-validation/{SKILL.md,agents/openai.yaml,references/source-index.md}` 与 `skills-lock.json`。安装命令与官方 README 一致。[README](https://github.com/iloveZzz/yss-spec-dev-skills/blob/e669478e6fd6d78617fe01bc0d92279e23f81d70/README.md#L7-L31)
+
+限制：生成的 `skills-lock.json` 记录 GitHub source、skillPath 与 computedHash，但不记录 `e669478...` commit；仓库也未发现 tag / GitHub Release。因而安装当前可复核、内容 hash 可记录，但默认分支安装不是 commit-pinned、跨时间不可完全复现。这是公开技能发布链仍需增强的点。
+
+## 五、当前能力与优化建议
+
+| 能力 | 当前状态 | 建议 |
+|---|---|---|
+| 可复现 CLI 发布 | 已有固定模板 commit、snapshot hash、npm integrity | 保持 commit-pinned；增加模板 tag / release note 作为人类可读锚点 |
+| 初始化与六投影 | `.qoder` 已随六个共享投影进入真实 tarball | 发布前继续对真实 tarball 做六根 tree/hash 检查 |
+| 已有项目接管 | `attach` 支持 dry-run、显式 apply、冲突阻断、备份与回滚 | 补真实历史仓库 fixture；不要扩大为猜测式迁移 |
+| 持续同步 | managed baseline、局部更新、迁移、三门禁、失败回滚已具备 | 增加当前模板 `main` 固定 commit 的持续跨仓库 CI，避免只测发布内置旧快照 |
+| 发布门禁 | 默认固定快照 fresh 测试 28/28 | 按跨仓库合同补 `npm pack --dry-run` 与解包后 init/attach/sync；记录两个仓库 commit 和独立审查 |
+| 公开技能分发 | `skills` CLI 能发现 46 项并成功安装 | 先用当前 44 项重新导出并 PR；明确处置额外两项；发布后再做 `--list` / 安装 smoke test |
+| 公开技能版本化 | 当前跟随 GitHub `main`，安装 lock 无 commit | 发布 tag 或 commit-pinned 安装指引；让 lock/发布 manifest 能追溯 export source commit |
+
+## 六、相对 2026-08-10 的最终差距表
+
+| 2026-08-10 缺口 | 2026-08-16 判定 |
+|---|---|
+| `.qoder` 被排除、init 失败 | **已修复并由 tarball + 28/28 测试验证** |
+| npm `2.0.0` 过旧 | **已修复到 `2.1.3`**；但仍需对模板当前 `main` 重新集成验证后再发新版 |
+| 模板引用浮动 `main` | **已修复为默认固定 commit**；没有 tag / Release 证据 |
+| README 声称迁移但源码未实现 | **已修复**；已知迁移、conflict / unsafe 和回滚有源码与测试 |
+| `sync` 后不重新验证 | **已修复**；三门禁在 metadata 前执行，失败事务回滚 |
+| 发布包与当前模板同步 | **仍未完成当前性证明**；`2.1.3` 固定 `41c68b5...`，当前模板为 `5859e1e...`，本轮未跑完后者集成测试 |
+| 公开技能清单一致性 | **新增/仍在缺口**；远端 46，本地允许 44，需重新导出发布 |
+| 公开技能可复现安装 | **部分具备**；实际安装成功，但无 tag 且安装 lock 不记 commit |
+
+## 实际命令摘要
+
+```bash
+git ls-remote https://github.com/iloveZzz/create-yss-spec.git refs/heads/main
+git ls-remote https://github.com/iloveZzz/yss-spec-project-template.git refs/heads/main
+git ls-remote https://github.com/iloveZzz/yss-spec-dev-skills.git refs/heads/main
+npm view create-yss-spec dist-tags versions time --json
+npm view create-yss-spec@2.1.3 gitHead dist.tarball dist.shasum dist.integrity --json
+npm pack create-yss-spec@2.1.3 --pack-destination /tmp/yss-cli-refresh.uSVd7K
+cd /tmp/yss-cli-refresh.uSVd7K/create-yss-spec && npm test
+npx --yes skills@latest add iloveZzz/yss-spec-dev-skills --list
+npx --yes skills@latest add iloveZzz/yss-spec-dev-skills --skill yss-validation --agent codex --yes
+```
+
+本记录是研究证据，不是模板、CLI 或公开技能仓库的发布批准，也不替代独立审查。

package/template/docs/reviews/security-permission-lifecycle-simplification-red-green-2026-08-16.md

@@ -0,0 +1,43 @@
+---
+type: template-skill-validation
+status: complete
+date: 2026-08-16
+scope: yss-product-lifecycle / yss-router / OpenAPI lifecycle simplification
+---
+
+# 安全 / 权限生命周期简化 RED / GREEN / REFACTOR 记录
+
+## RED：旧规则的过度治理证据
+
+修改前的只读压力检查表明，机器契约会让普通 CRUD/API 填写结构化安全 / 权限资料、过时的继承资料、触发命中和派生影响旗标；缺少或过期的资料会阻断推进。
+
+SQL / DDL / 迁移和普通下载接口也会仅因技术载体自动升级到专属流程。明确改变认证、授权或租户隔离的需求，除了实际的 Spec、API、数据和架构影响外，还会引入专属传播和回退目的地。
+
+基线脚本 `scripts/verify-lifecycle-scenarios` 与 `scripts/verify-yss-router-scenarios` 在旧契约下通过，证明这些行为不仅存在于文档，也被自动验证锁定。
+
+## GREEN：简化后的压力场景
+
+- 普通 CRUD/API 可在不提供任何额外安全 / 权限输入、平台资料或不适用记录的情况下，通过 Router 的普通 UI/API/Backend/Data 影响分诊。
+- SQL / DDL / 迁移仅走既有数据模型和迁移规则；上传下载仅按真实 API、UI 或数据影响处理，不因关键词自动升级。
+- 显式改变认证、授权、租户隔离、敏感数据或合规行为时，按实际 UI、API、Backend、Data 和 high-risk 影响进入普通 Spec、架构、错误语义、验收标准和测试 seam。
+- 实际调用当前用户、审计或加密组件时，Router 仍选择对应 YSS skill；权限业务行为仍使用 `behavior-tdd`，受控生成仍禁止机械生成此类业务逻辑。
+
+本轮 fresh verification 结果：
+
+```text
+scripts/sync-skills --check       -> skill projections are synchronized
+scripts/update-skill-lock --check -> skills-lock.json matches distributed skills
+scripts/verify-lifecycle-scenarios -> 六类生命周期压力场景验证通过；生命周期编排器压力场景验证通过
+scripts/verify-yss-router-scenarios -> YSS Router stage 7 scenarios passed
+scripts/verify-template           -> 模板发布校验通过
+git diff --check                  -> passed
+```
+
+独立只读审查先识别出用户指南、切片 Ticket、审查报告、生命周期说明、技术设计与 OpenAPI Freeze 中的旧专项语句；修订后 Standards 与 Spec 两个审查轴均复核通过，无剩余 P0/P1/P2 finding。
+
+## REFACTOR：收敛后的长期规则
+
+- 不再主动推导或登记安全 / 权限专项影响；没有独立的姿态、平台资料、触发矩阵、派生旗标、专属传播或回退目的地。
+- 实现中发现未冻结的新事实时，统一用既有 `new_impacts` 重新分诊。
+- 保留通用 `seam-deferred` 的风险、责任人、后续 Ticket、验证计划和目标版本 / 发布日期要求；不再存在专项不可延期清单。
+- 保留真实组件选择、普通架构审查、路径边界、证据和验证要求，但不新增与本次简化无关的流程条件。

package/template/docs/reviews/template-release-review-remediation-red-green-2026-08-17.md

@@ -0,0 +1,41 @@
+# 模板发布审查修复 RED / GREEN 证据
+
+## 范围
+
+- 仓库身份：`template-source`。
+- 触发：全部候选变更的独立双轴发布审查。
+- 目标：消除已明确安全/权限行为缺少普通架构承载、生命周期场景未校验稳定 ID，以及 ADR 把后续未实施能力表述为已生效能力的问题。
+
+## RED
+
+先新增 `scripts/verify-governance-release`，在不修改权威资产时得到预期失败：
+
+- 两份架构模板均缺少“已明确的认证、授权、租户隔离、敏感数据或合规行为”的条件性承载。
+- ADR-0003 / 0006 把索引、依赖图和 fixture 的完整生成写成已交付，ADR-0005 / 0007 把生态发布清单和技能路由注册表写成已生效，但相应资产、schema、消费者和校验器不存在。
+- `verify-lifecycle-scenarios` 使用人类可读 route key，却没有核验它们能映射到 `lifecycle-registry.yaml` 的稳定 ID。
+
+## GREEN
+
+- 系统概要设计和技术方案模板恢复条件性架构承载：只有明确改变认证、授权、租户隔离、敏感数据或合规行为时才填写普通架构、契约、验证与回滚约束；未触发时不新增独立门禁或登记。
+- ADR-0003 / 0006 明确为 Phase 1 部分实施，ADR-0005 / 0007 明确为 `proposed`；未实现的生态清单、技能注册表、索引、依赖图与 fixture 不再被描述为当前模板已交付能力。
+- `verify-lifecycle-scenarios` 读取 `lifecycle-registry.yaml`，并把每个当前 route key 映射、校验到稳定 ID，防止注册表删除或改名时压力场景静默漂移。
+- `verify-governance-release` 已加入 `scripts/verify-template`。
+
+## 验证
+
+```text
+scripts/verify-governance-release  PASS
+scripts/verify-lifecycle-scenarios PASS
+scripts/verify-template            PASS（记录于本节最终复审文字写入前的冻结候选）
+```
+
+后续完整生态发布清单或技能路由注册表必须从新的 RED 场景开始，且同时交付 source、schema、消费者、`--check` 和跨仓验证；不得仅更新 ADR 状态。
+
+## 独立复审
+
+两位非实现者基于同一 `yss-worktree-candidate-v1` 不可变快照复审：
+
+- Standards：条件性架构承载、稳定 ID 映射和 `candidate-manifest.yaml` 均通过。
+- Spec / Requirements：ADR-0003 / 0006 的 Phase 1 边界及 ADR-0005 / 0007 的 `proposed` 状态准确，未实施能力不再被当作本次发布交付。
+
+复审时 `drift`、`violation` 和 `new_impacts` 均为空；本节写入后必须对新的最终候选重新执行 fresh verification 并复核候选摘要，结果由本轮 Git checkpoint 记录，避免把验证结论自指为文档写入后的同一快照。

package/template/docs/templates/agent-brief-template.md

@@ -40,7 +40,7 @@ Agent 应运行的命令或检查：
 # 命令
 ```
 
-## 安全与人工审查
+## 风险与人工审查
 
 - [ ] 无高风险变更或需人工确认项
-- [ ] 涉及支付、迁移、认证、原生 SQL 或公共基础库 API 时，必须包含 人工确认项
+- [ ] 已明确的高风险变更包含对应人工确认项

package/template/docs/templates/build-architecture-checklist-template.md

@@ -45,13 +45,13 @@ owner: ai
 | 后端工程工具链：构建、测试、运行、OpenAPI 生成、CI 和 Release 命令必须使用项目根目录 `./mvnw ...`；裸 `mvn ...` 必须有受控例外记录 | `yss-ddd-scaffold-generator` / `yss-backend-scaffold-parent` / implementation routing |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 无例外记录时改为 `./mvnw ...`，否则不得进入完成 / 可合并结论 |
 | 工程项目路径：每个 Harness 内项目必须有具体项目段，禁止直接写入容器根或单数 `app/...` | `docs/process/implementation-repo-integration.md` / implementation path validator |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 路径违规时停止 build，并回到实现路由 |
 | 文档语言：持久化生命周期文档、实施记录、审查报告、发布说明和 Git checkpoint 正文必须使用中文，英文 skill / 模板不得原样落地 | `AGENTS.md` / `yss-product-lifecycle` |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 仅保留必要英文技术标识、命令和 metadata |
-| 高风险变更：认证 / 授权、SQL / DDL、迁移、加密、公共基础库 API 变更必须记录验证证据、责任人和回滚约束 | `AGENTS.md` |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 缺验证证据或责任人时不得发布或合并 |
+| 高风险变更：按已批准的普通影响面结论记录验证证据、责任人和回滚约束 | `AGENTS.md` / Spec / 架构记录 |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 缺验证证据或责任人时不得发布或合并 |
 |  |  |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  |  |
 
 状态说明：
 
 - `implemented`：已有代码、测试或文档证据证明满足约束。
-- `seam-deferred`：允许临时 seam，但必须说明风险、补齐切片、责任人和验证计划；延期项不得无限期挂起。
+- `seam-deferred`：允许临时 seam，但必须说明风险、补齐切片、责任人、验证计划和目标版本 / 发布日期；延期项不得无限期挂起。
 - `drift`：实现与架构意图不一致，必须先做 Architecture Re-check。
 - `violation`：违反架构约束或缺少风险 / 回滚证据，停止继续 build，回到设计审查或架构修正。
 - `not-applicable`：当前切片不触碰该约束，并说明原因。
@@ -113,8 +113,7 @@ rg -n '(^|[[:space:]])mvn[[:space:]]' <backend-repo-or-doc-paths>
 | 风险事项 | 是否涉及 | 责任人 / 结论 | 证据 | 阻断结论 |
 |---|---|---|---|---|
 | SQL / DDL |  |  |  |  |
-| 审计日志 |  |  |  |  |
-| 文件上传下载 / 临时 URL |  |  |  |  |
+| 其他已明确风险 |  |  |  |  |
 
 ## 5. 结论
 

package/template/docs/templates/implementation-repo-registry-template.md

@@ -71,8 +71,6 @@ Harness 内项目路径约束：`apps/backend/`、`apps/frontend/` 只能作为
 | 人工确认项 | 是否涉及 | 审查人 / 角色 | 结论 | 补齐落点 |
 |---|---|---|---|---|
 | DDL / SQL / 数据库迁移 | 是 / 否 |  | 通过 / 草案 / 阻断 / 不适用 |  |
-| 权限接入 / 认证 / 授权 | 是 / 否 |  | 通过 / 草案 / 阻断 / 不适用 |  |
-| 审计日志 | 是 / 否 |  | 通过 / 草案 / 阻断 / 不适用 |  |
 | 其他风险 / 回滚约束 | 是 / 否 |  | 通过 / 草案 / 阻断 / 不适用 |  |
 
 ## 6. Harness 回写

package/template/docs/templates/implementation-routing-template.md

@@ -17,7 +17,7 @@ owner: ai
 |------|-------------|------|------|
 | 垂直切片 Ticket |  |  |  |
 | OpenAPI Freeze / 无 API 影响记录 |  |  |  |
-| OpenSpec-style Spec Delta（条件必需） |  |  | 仅 API、权限、状态机、数据模型、跨端、新模块或高风险变更需要 |
+| OpenSpec-style Spec Delta（条件必需） |  |  | 仅 API、状态机、数据模型、跨端、新模块或高风险变更需要 |
 | Design Review |  |  |  |
 | 实现仓库 / 实现位置 |  |  |  |
 | 前后端工程存在性判定 |  |  | 记录 frontend / backend 是否已存在且可复用 |
@@ -94,7 +94,7 @@ owner: ai
 | expected_evidence_files |  |
 | verification_commands |  |
 | human_review_points |  |
-| full_reroute_triggers | 新 API/schema、权限、状态机、数据模型、写目录、仓库、skill、风险、seam 或交付顺序等变化 |
+| full_reroute_triggers | 新 API/schema、状态机、数据模型、写目录、仓库、skill、风险、seam、交付顺序或其他未冻结行为等变化 |
 
 | 不适用 skill | 原因 |
 |---|---|
@@ -211,8 +211,7 @@ owner: ai
 | 人工确认项 | 是否涉及 | 结论 | 证据 / 链接 | 补齐落点 |
 |---|---|---|---|---|
 | DDL / SQL / 数据库迁移 | 是 / 否 | 通过 / 草案 / 阻断 / 不适用 |  |  |
-| 权限接入 / 认证 / 授权 | 是 / 否 | 通过 / 草案 / 阻断 / 不适用 |  |  |
-| 审计日志 | 是 / 否 | 通过 / 草案 / 阻断 / 不适用 |  |  |
+| 其他已明确的风险 / 人工确认 | 是 / 否 | 通过 / 草案 / 阻断 / 不适用 | 仅登记上游已经明确的事项 |  |
 
 ### 4.3 后端脚手架工作单元
 
@@ -223,7 +222,7 @@ owner: ai
 | 前置 | `prototype_confirmation`、工程基线、实现仓库和脚手架目标已确认；Router 脚手架合同 draft 已经生命周期批准并持久化为结构化 JSON，生成器通过 `--contract-file` 消费 |
 | 生成器 | `yss-ddd-scaffold-generator` |
 | 模式 | `controlled-generation` |
-| 允许生成 | Domain / Application / Infrastructure / Adapter / Bootstrap 目录骨架、POM、配置、Wrapper、Smart Doc 和非业务机械模板 |
+| 允许生成 | Domain / Application / Infrastructure / Adapter / Bootstrap 目录骨架、POM、配置、Wrapper 和非业务机械模板 |
 | 禁止生成 | 业务规则、状态机、权限、事务、复杂查询、错误映射、业务字段和用户可见行为 |
 | 生成选项 | 关闭 `--with-example`；非空目录 `--force` 默认阻断，覆盖范围、备份、回滚点和批准引用齐全后才能单独审查 |
 | 验证 | 受控验证器实际执行项目根目录 `./mvnw validate`、`./mvnw test`、`./mvnw package`，逐条记录 `exit_code`、`duration_ms`、stdout/stderr 引用和执行时间；打印命令不算证据 |
@@ -306,7 +305,8 @@ owner: ai
 - [ ] 受影响外部实现仓库已登记，并绑定分支、MR / PR、CI 和验证命令。
 - [ ] 受影响 frontend / backend 工程存在性已判定；0-1 缺失工程已登记 `scaffold_status=required`、确认外部脚手架目标并路由对应脚手架 skill。
 - [ ] 原型确认后已满足 `backend_scaffold_policy_satisfied`；脚手架只生成工程骨架，所有后续生成代码均经批准合同和 YSS skill 路由。
-- [ ] DDL / SQL / 数据库迁移、权限接入和审计日志的人工确认结论已记录；未通过时记录阻塞原因、责任人和补齐计划。
+- [ ] DDL / SQL / 数据库迁移及其他上游明确的人工确认结论已记录。
+- [ ] `seam-deferred` 若存在，已填写风险、责任人、后续 Ticket、验证计划和目标版本 / 发布日期。
 - [ ] 若使用 subagent，已记录任务包、写范围、独立 review、verification 命令和主控采纳结论。
 - [ ] 每个切片包含测试命令、验证方式和回滚点。
 - [ ] 每个工作单元均绑定唯一 TDD 模式，且 Execution Result 引用合同版本并包含实际验证结果和时间。

package/template/docs/templates/openapi-spec-template.yaml

@@ -1,9 +1,3 @@
----
-pipeline: <feature-id>
-stage: open
-status: draft
-owner: ai
----
 openapi: 3.1.0
 info:
   title: <功能 API>

package/template/docs/templates/review-report-template.md

@@ -63,7 +63,7 @@ Approved / Changes requested / Blocked
 | `yss-web-controller` / `yss-dto` 已按影响面落实，CMD / Query / VO / Result 按既有 DTO 体系定义或复用，Controller 不用内部类或非约定包临时承载主要 DTO / VO、不手工分页主要业务集合、不穿透 Repository | pass / violation / not-applicable |  |
 | `mapstruct` 已按影响面落实，PO / Domain Model / DTO / VO / CMD / Query 转换使用 MapStruct Convertor / Mapper，未使用 `BeanUtils.copyProperties`、反射拷贝或重复手写字段赋值；例外已记录测试和补齐落点 | pass / violation / not-applicable |  |
 | `lombok` 已按影响面落实，POJO 样板代码使用 Lombok，未成片手写 getter/setter、constructor、builder、logger；实体 / POJO 未触发 `@Data` 等反模式或已说明例外 | pass / violation / not-applicable |  |
-| `alibaba-java-code-style` 已纳入审查，命名、异常、日志、ORM/MyBatis、Maven、MapStruct / Lombok 注解处理器配置、安全项无 blocker | pass / violation / not-applicable |  |
+| `alibaba-java-code-style` 已纳入审查，命名、异常、日志、ORM/MyBatis、Maven、MapStruct / Lombok 注解处理器配置无 blocker | pass / violation / not-applicable |  |
 | 后端构建 / 测试 / OpenAPI / CI / Release 命令使用项目根目录 `./mvnw ...`；裸 `mvn ...` 已改正或有受控例外记录 | pass / violation / not-applicable |  |
 | 持久化文档正文、章节标题、审查结论和实施说明使用中文；英文模板内容未原样落地 | pass / violation / not-applicable |  |
 | `Build Architecture Checklist` 已回勾，延期项、漂移项、违反项有明确处理结论 | pass / violation / not-applicable |  |
@@ -93,6 +93,7 @@ rg -n "class (SingleResult|MultiResult|PageResult|Result)<|public static class .
 | Agent 将英文 skill / 模板的标题和说明原样输出为项目持久化文档 | 应改为中文正文和中文章节标题，否则标记为 `violation` |  |
 | Agent 修改合同允许路径之外的文件，或缺少预期证据文件 | 应标记为 `violation` 并阻断 build |  |
 | Agent 把状态机、权限、事务或错误映射放入 `controlled-generation` | 应拆分为 `behavior-tdd` 工作单元并触发完整重路由 |  |
+| Agent 使用 `seam-deferred` 却缺少风险、责任人、后续 Ticket、验证计划或目标版本 / 发布日期 | 应标记为 `violation` 并阻断 |  |
 | Agent 返回非空 `new_impacts` 后继续编码或补写旧合同 | 应暂停相关工作单元，将合同标记 `stale`，回到 Router 或更早生命周期阶段 |  |
 | Agent 只列验证命令但没有实际结果和执行时间 | 不构成 fresh verification，不得给出 Approved / 可合并结论 |  |
 

package/template/docs/templates/spec-delta-template.md

@@ -1,6 +1,6 @@
 # <功能名称> Spec Delta
 
-> 适用场景：修改既有冻结 Spec 基线时，API、权限、状态机、数据模型、跨端协作或其他高风险行为需要在 Spec、OpenAPI Draft、Design Review 和垂直切片之间明确差异。全新产品或全新模块不使用本模板。
+> 适用场景：修改既有冻结 Spec 基线时，API、状态机、数据模型、跨端协作或其他高风险行为需要在 Spec、OpenAPI Draft、Design Review 和垂直切片之间明确差异。全新产品或全新模块不使用本模板。明确改变认证或授权行为时，把差异作为普通行为写入本 Delta，不新增单独 Delta。
 > 本模板只借鉴 OpenSpec 的行为差异表达方式，不引入 OpenSpec CLI、旧式变更目录、变更状态文件或额外状态机。
 
 ## 1. 变更摘要

package/template/docs/templates/spec-template.md

@@ -34,7 +34,6 @@ owner: ai
 | 类别 | 需求 | 目标 |
 |---|---|---|
 | 性能 | | |
-| 安全 | | |
 | 可靠性 | | |
 
 ## 验收标准

package/template/docs/templates/vertical-slice-ticket-template.md

@@ -63,7 +63,7 @@ Status: ready-for-human
 |---|---|---|---|---|---|---|---|---|---|
 |  |  |  |  | behavior-tdd / controlled-generation |  |  |  |  | pending / running / blocked / completed / stale |
 
-`controlled-generation` 仅允许机械脚手架、样板、冻结客户端或配置，并记录 exception reason、生成器输入和生成后行为测试；业务规则、状态机、事务、权限、错误映射、复杂查询和用户可见交互必须使用 `behavior-tdd`。
+`controlled-generation` 仅允许机械脚手架、样板、冻结客户端或配置，并记录 exception reason、生成器输入和生成后行为测试；业务规则、状态机、事务、权限、错误映射、复杂查询和用户可见交互必须使用 `behavior-tdd`。只有需求明确包含权限业务行为时才把它写入工作单元，不另设安全 / 权限姿态。
 
 ## YSS 技能与后端实现合同
 
@@ -98,7 +98,7 @@ Status: ready-for-human
 | 字段 | 内容 |
 |---|---|
 | reroute_status | current / incremental-review / full-reroute-required / lifecycle-return / stale |
-| trigger | 新 API/schema / 权限 / 状态机 / 数据模型 / 写路径 / 仓库 / skill / seam / 风险 / 交付顺序 / other |
+| trigger | 新 API/schema / 状态机 / 数据模型 / 写路径 / 仓库 / skill / seam / 风险 / 交付顺序 / other |
 | affected_work_units |  |
 | new_impacts |  |
 | stale_contract_version |  |

package/template/docs/user-guide//344/272/247/345/223/201/347/224/237/345/221/275/345/221/250/346/234/237/345/267/245/344/275/234/346/265/201.md

@@ -44,8 +44,8 @@ docs/implementation/
 | `competitive-intelligence` | 竞品、替代方案、定价、定位、用户口碑和市场事实研究 | 进入 Discovery / Spec 前需要外部事实支撑时 |
 | Matt Engineering Skills | 澄清、Spec、Ticket、实现、TDD、诊断、审查、架构治理 | 大部分通用工程流程 |
 | YSS skills | DDD、UI、OpenAPI、Repository、Controller、DTO、组件规范 | 进入具体前后端实现或专项审查时 |
-| OpenAPI 3.1 | 前后端 API 契约 | 任何接口路径、schema、错误、分页、权限或并发语义变化时 |
-| OpenSpec-style Spec Delta | 行为差异、验收场景和测试映射 | API、权限、状态机、数据模型、跨端、新模块或高风险行为变化时 |
+| OpenAPI 3.1 | 前后端 API 契约 | 任何接口路径、schema、错误、分页、并发，或需求明确的认证 / 授权语义变化时 |
+| OpenSpec-style Spec Delta | 行为差异、验收场景和测试映射 | API、状态机、数据模型、跨端、新模块或高风险行为变化时；明确的认证 / 授权行为按其实际影响记录 |
 | Ticket tracker | 状态同步和切片追踪 | 人工暂停、handoff、进入实现、合并、发布，以及验证失败或阻塞更新时 |
 
 一句话：
@@ -104,10 +104,10 @@ docs/implementation/
 
 ## 4. 生命周期主流程
 
-日常推荐使用 8 个主阶段推进，21 个门禁 / 职责点只用于检查和补齐缺失资产，不要求每个需求逐项跑完。阶段、产物、模板和必需 / 条件必需规则的权威索引见：
+日常按主阶段推进。条件门禁只用于裁决命中的影响面；产物、工作单元和证据不是门禁的同义词，不要求每个需求逐项跑完。阶段、产物、模板和必需 / 条件必需规则的权威索引见：
 
 ```text
-docs/process/lifecycle-artifact-map.md
+docs/process/lifecycle-registry.yaml
 ```
 
 推荐主线：
@@ -129,7 +129,7 @@ docs/process/lifecycle-artifact-map.md
 - 已有行业、竞品或用户材料：先用 `competitive-intelligence` 做 Discovery 事实整理，再生成 Spec。
 - 明确 Bug 或小调整：不走完整机会探索环，直接用 `diagnosing-bugs` 或最小改动加验证。
 - 已有功能的小需求变更：先做影响面评估，选择最近可信阶段，只更新受影响资产和下游门禁。
-- 新模块、API 或跨端改动：必须按 8 个主阶段推进；有 UI 时必须经过产品设计、原型评审和需求冻结；有 API 时必须完成 API 影响分析 / 契约草案、必要的 Spec Delta、工程基线、系统 / 数据架构、Design Review、OpenAPI Freeze，再进入 `to-tickets`、垂直切片和 TDD。
+- 新模块、API 或跨端改动：必须按生命周期注册表的主阶段推进；有 UI 时必须经过产品设计、原型评审和需求冻结；有 API 时必须完成 API 影响分析 / 契约草案、必要的 Spec Delta、工程基线、系统 / 数据架构、Design Review、OpenAPI Freeze，再进入 `to-tickets`、垂直切片和 TDD。
 
 ## 5. `yss-product-lifecycle` 使用入口
 
@@ -178,7 +178,7 @@ docs/process/lifecycle-artifact-map.md
 ```text
 基于 Spec 和产品设计，生成 OpenAPI 3.1 Draft。
 Draft 仅用于评审，不得作为实现或生成客户端的稳定契约。
-请检查 YSS response wrappers、错误结构、分页、权限、并发和契约测试 seam。
+请检查 YSS response wrappers、错误结构、分页、并发和契约测试 seam。只有 Spec 明确改变认证或授权行为时，才把对应 `401` / `403`、资源过滤和错误语义作为普通 API 行为审查。
 如涉及 API、权限、状态机、数据模型、跨端、新模块或高风险行为变化，请同步生成 OpenSpec-style Spec Delta，记录 ADDED / MODIFIED / REMOVED、验收场景和测试映射。
 ```