create-yss-spec 2.1.4 → 2.1.6

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

@@ -1,154 +0,0 @@
-# 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-2026-08-10.md

@@ -1,141 +0,0 @@
-# `create-yss-spec` 与当前模板初始化契约兼容性研究
-
-> 访问时间：2026-08-10 16:22（Asia/Shanghai，GitHub / npm 一手来源）。
-> 研究范围：只核对当前工作区模板与 `iloveZzz/create-yss-spec` 默认分支及 npm `latest` 发布包；本笔记之外未修改仓库文件。
-
-## 结论先行
-
-需要迭代，而且当前不是“只需重新发布 npm 包”的级别：`create-yss-spec` `main` 与当前模板 `main` 已出现可复现的初始化阻断。
-
-- 现有 CLI 对 `yss-project.yaml` 的初始化转换已经覆盖当前契约：模板保留 `template-source`，生成实例改写为 `project-instance`，并严格要求 `schema_version: 1` 与两个字段。
-- 但当前模板的 `skills-lock.json` / `scripts/sync-skills` 已加入 `.qoder/skills` 投影，CLI 的 `template.manifest.json` 仍排除整个 `.qoder`。新鲜集成测试实际得到 13 个测试 7 失败、6 通过；初始化失败在 `scripts/sync-skills --check`，大量报 `missing projection: .qoder/skills/...`。
-- npm `create-yss-spec@2.0.0` 的发布时间是 2026-07-21，而模板 `main` 当前提交为 2026-08-10；已发布包是旧模板快照，不能代表当前模板。
-- README 声称升级时会迁移 Spec / Ticket 旧路径、删除旧 skill 并在冲突时 fail closed，但当前 `src/cli.js` / `sync-template.js` 中未发现对应迁移逻辑；`sync` 实际是基于 `.yss-template.json` 的文件哈希同步。该声明与源码和测试不一致，应在发布前修复或降级为未支持能力。
-
-## 证据与事实
-
-### 1. 仓库身份与当前模板契约
-
-本地事实：
-
-- [`yss-project.yaml`](../../yss-project.yaml#L1) 当前为 `schema_version: 1`、`repository_mode: template-source`。
-- [`docs/implementation/create-yss-spec-repository-mode-contract.md`](../implementation/create-yss-spec-repository-mode-contract.md) 明确要求 CLI 生成实例改写为 `project-instance`，保留 `.agents/skills` 权威内容和所有声明的投影，并在写入后执行 `scripts/sync-skills --check`、`scripts/update-skill-lock --check`、`scripts/verify-template`。
-- 当前 [`skills-lock.json`](../../skills-lock.json#L1-L12) 为 v3，canonical root 是 `.agents/skills`，投影根包含 `.claude/skills`、`.codex/skills`、`.hermes/skills`、`.pi/skills`、`.qoder/skills`、`.trae/skills`。
-- 当前 [`scripts/sync-skills`](../../scripts/sync-skills#L12-L19) 同样遍历上述六个投影根；本地执行 `scripts/sync-skills --check` 和 `scripts/update-skill-lock --check` 均通过。
-- 当前模板 `main` 的最近提交是 [`a85560614536aa6fb20bbada91a08a1b89ea6e`](https://github.com/iloveZzz/yss-spec-project-template/commit/a85560614536aa6fb20bbada91a08a1b89ea6e)，提交信息为 `fix: unify local tracker artifacts under docs/.scratch`；其 [`AGENTS.md`](https://github.com/iloveZzz/yss-spec-project-template/blob/main/AGENTS.md#L80) 已把完整 Local Markdown 功能包定位到 `docs/.scratch/<feature>/`。
-
-### 2. CLI 发布入口、模板来源与版本绑定
-
-外部一手源码：
-
-- [`package.json`](https://github.com/iloveZzz/create-yss-spec/blob/main/package.json#L1-L28) 当前 `version` 为 `2.0.0`；`files` 包含 `bin`、`src`、`template`、`template.manifest.json`；发布入口是 `bin.create-yss-spec: ./bin/create-yss-spec.js`；`prepack` 会执行 `node scripts/sync-template.js`。
-- [`bin/create-yss-spec.js`](https://github.com/iloveZzz/create-yss-spec/blob/main/bin/create-yss-spec.js#L1-L10) 只负责把参数转交给 `src/cli.runCli`，没有另一个隐藏入口。
-- [`scripts/sync-template.js`](https://github.com/iloveZzz/create-yss-spec/blob/main/scripts/sync-template.js#L7-L16) 的默认模板仓库固定为 `https://github.com/iloveZzz/yss-spec-project-template.git`，默认引用固定为 `main`；两者可分别由 `YSS_SPEC_TEMPLATE_REPO`、`YSS_SPEC_TEMPLATE_REF` 覆盖。
-- 同一脚本 [`scripts/sync-template.js`](https://github.com/iloveZzz/create-yss-spec/blob/main/scripts/sync-template.js#L150-L166) 在打包前执行 `git clone --depth 1 --branch <ref>`，以 `git ls-files` 获取跟踪文件，把模板快照替换进 npm 包的 `template/`。因此：构建时依赖远程 Git、发布包运行时不再访问模板仓库；当前默认是浮动的 `main`，不是不可变 commit / tag。
-- 该脚本会解析内部目录 symlink 并复制其目标文件到投影路径（[`scripts/sync-template.js`](https://github.com/iloveZzz/create-yss-spec/blob/main/scripts/sync-template.js#L34-L71)、[`#L73-L110`](https://github.com/iloveZzz/create-yss-spec/blob/main/scripts/sync-template.js#L73-L110)）。生成的实例因此得到物理文件树，不保留模板仓库中的 symlink 语义；后续由 `scripts/sync-skills` 按哈希检查 / 修复。
-- CLI `main` 当前提交是 [`87cd7207e3e0d3b8dc29c0df2817d8bac7ff31ea`](https://github.com/iloveZzz/create-yss-spec/commit/87cd7207e3e0d3b8dc29c0df2817d8bac7ff31ea)，默认分支页面确认是 `main`：[`create-yss-spec`](https://github.com/iloveZzz/create-yss-spec/tree/main)。
-
-npm 一手发布元数据：
-
-- [`https://registry.npmjs.org/create-yss-spec`](https://registry.npmjs.org/create-yss-spec) 当前 `latest` 是 `2.0.0`，发布时间 `2026-07-21T04:04:14.128Z`，tarball 为 [`create-yss-spec-2.0.0.tgz`](https://registry.npmjs.org/create-yss-spec/-/create-yss-spec-2.0.0.tgz)。
-- 对该 tarball 的只读核验显示包内仍有 `template/yss-project.yaml`，内容是 `repository_mode: template-source`；这不是错误，初始化阶段源码会再渲染为 `project-instance`。但包发布时间早于当前模板 `main`，所以 `npx create-yss-spec@latest` 当前不会得到 2026-08-10 模板快照。
-
-### 3. 初始化实际复制、渲染和验证什么
-
-依据 [`template.manifest.json`](https://github.com/iloveZzz/create-yss-spec/blob/main/template.manifest.json#L1-L33) 与 [`src/cli.js`](https://github.com/iloveZzz/create-yss-spec/blob/main/src/cli.js#L314-L373)：
-
-- 从 npm 包内的 `template/` 递归复制文件；根排除项包括 `.git`、`.codegraph`、`.codebuddy`、`.idea`、`.uploads`、`node_modules`、`.qoder`、`.qwen`、`packages`；根排除文件包括 `package-lock.json`、`package.json`、`template.manifest.json`。
-- 额外排除 `.claude/settings.local.json`、`.codex/hooks.json`、`.codex/settings.local.json`、`.codex/skills/.DS_Store`、`.pi/settings.json`。
-- `AGENTS.md`、`README.md`、`yss-project.yaml` 是渲染文件；可选的 `docs/discovery/IDEATION.md` 由 `--include-example-docs` / `--no-example-docs` 控制。
-- 初始化后写入 `.yss-template.json`，记录 CLI 包版本、模板来源、变量和受管文件 hash；它是后续 `sync` 的前置条件。
-- `yss-project.yaml` 渲染逻辑见 [`src/cli.js`](https://github.com/iloveZzz/create-yss-spec/blob/main/src/cli.js#L194-L243)：只接受两个字段、`schema_version: 1`，要求源模式为 `template-source`，然后把它改写为 `project-instance`。
-- 初始化写入完成后，CLI 依次执行 `scripts/sync-skills --check`、`scripts/update-skill-lock --check`、`scripts/verify-template --check`（[`src/cli.js`](https://github.com/iloveZzz/create-yss-spec/blob/main/src/cli.js#L483-L509)、[`#L749-L785`](https://github.com/iloveZzz/create-yss-spec/blob/main/src/cli.js#L749-L785)）。这使得遗漏的投影或过时锁文件会直接阻断初始化。
-
-### 4. 覆盖、保留与 sync 行为
-
-- 初始化目标不存在时创建目录；目标非空且未传 `--force` 时拒绝（[`src/cli.js`](https://github.com/iloveZzz/create-yss-spec/blob/main/src/cli.js#L385-L405)）。
-- 传 `--force` 时会遍历并递归删除目标目录下的全部已有条目，再写入模板（[`src/cli.js`](https://github.com/iloveZzz/create-yss-spec/blob/main/src/cli.js#L407-L447)）。因此 `--force` 不保留用户文件，属于全量清空后初始化。
-- `--dry-run` 只打印复制计划，不写入或删除目标目录。
-- `sync` 只接受带 `.yss-template.json` 的受管实例；比较受管文件 hash，未被本地修改的文件可更新，缺失文件可补回；本地已修改文件跳过并报告，模板已删除文件只报告、不自动删除（[`src/cli.js`](https://github.com/iloveZzz/create-yss-spec/blob/main/src/cli.js#L535-L624)、[`#L626-L747`](https://github.com/iloveZzz/create-yss-spec/blob/main/src/cli.js#L626-L747)）。
-- 事实：`runSync` 只调用 `syncTemplateInstance`（[`src/cli.js`](https://github.com/iloveZzz/create-yss-spec/blob/main/src/cli.js#L786-L797)），同步完成后没有再次执行三个模板验证脚本。
-
-## 可复现兼容性核验
-
-在临时目录 clone CLI `main`，设置 `YSS_SPEC_TEMPLATE_REPO=https://github.com/iloveZzz/yss-spec-project-template.git`、`YSS_SPEC_TEMPLATE_REF=main`，执行 `npm test`。结果：13 个测试中 6 个通过、7 个失败；所有失败的初始化路径均在 `生成项目校验失败：scripts/sync-skills` 阶段报告 `.qoder/skills/*` 缺失。
-
-原因链是可直接对齐的：
-
-1. 当前模板 [`skills-lock.json`](https://github.com/iloveZzz/yss-spec-project-template/blob/main/skills-lock.json#L5-L12) 与 [`scripts/sync-skills`](https://github.com/iloveZzz/yss-spec-project-template/blob/main/scripts/sync-skills#L12-L19) 都声明 `.qoder/skills`。
-2. CLI 当前 [`template.manifest.json`](https://github.com/iloveZzz/create-yss-spec/blob/main/template.manifest.json#L2-L11) 排除 `.qoder`，所以打包快照和初始化目标都不会有该投影。
-3. CLI 当前初始化测试只断言五个投影根 `.claude`、`.codex`、`.hermes`、`.pi`、`.trae`，没有 `.qoder`（[`tests/init-cli.test.js`](https://github.com/iloveZzz/create-yss-spec/blob/main/tests/init-cli.test.js#L58-L74)），与当前模板的六根投影契约已经漂移。
-
-这是实测事实，不只是静态推断。
-
-## 升级迁移核验
-
-README 的声明与源码不一致：
-
-- README 声称升级会迁移 Spec / Ticket 路径、删除 `to-prd` / `to-issues`，并在旧新资产冲突时 fail closed（[`README.md`](https://github.com/iloveZzz/create-yss-spec/blob/main/README.md#L27-L34)、[`#L47-L56`](https://github.com/iloveZzz/create-yss-spec/blob/main/README.md#L47-L56)）。
-- 当前 `src/cli.js` 的 `sync` 实现只有受管文件 hash 分类、更新、跳过和删除差异报告；当前源码中没有 `to-prd`、`to-issues`、旧 Spec / Ticket 路径迁移函数或迁移目标冲突处理。
-- 当前 [`tests/init-cli.test.js`](https://github.com/iloveZzz/create-yss-spec/blob/main/tests/init-cli.test.js) 与 [`tests/sync-template.test.js`](https://github.com/iloveZzz/create-yss-spec/blob/main/tests/sync-template.test.js) 覆盖身份转换、投影、哈希同步、跳过本地修改和 symlink 展开，但没有 README 所述旧路径迁移与迁移冲突测试。
-
-结论：对已经由旧 CLI 初始化的实例，不能仅凭 README 断言 `sync` 会完成从旧路径到当前 `docs/.scratch/<feature>` 或其他新路径的迁移；这是高风险的未实现 / 未验证能力。该判断是“源码未发现 + 测试未覆盖”的推断，需维护者确认是否存在未检出的运行时模块；基于当前默认分支源码，未发现该模块。
-
-## 差距矩阵
-
-| 兼容点 | 当前模板契约 | CLI 当前实现 / 发布状态 | 判定 | 风险与建议 |
-|---|---|---|---|---|
-| `yss-project.yaml` 身份 | `template-source` 仅存在模板源；实例必须是 `project-instance` | 已严格校验并在初始化渲染转换 | 兼容 | 保留现实现；schema 或新增字段时必须同步 CLI，当前代码会 fail closed |
-| `.qoder` 投影 | v3 lock 和 `sync-skills` 声明六个投影根 | manifest 排除 `.qoder`；初始化校验仍检查 lock 中的 `.qoder` | 不兼容（已实测） | 更新 manifest、测试、快照和发布包；或明确从模板契约中移除 `.qoder`，不能只改一边 |
-| 共享 skill / 平台 skill | `.agents/skills` 权威内容，投影按 lock 管理 | 内部 symlink 会被展开为物理文件；旧五根快照可工作 | 部分兼容 | 重新打包后对每个 projection root 做 tree hash、`sync-skills --check`、`update-skill-lock --check` |
-| 验证门禁 | 初始化后需执行三个检查；模板 `verify-template` 还含压力场景 | 初始化执行三个检查；`sync` 完成后不再执行检查 | 部分兼容 | `sync` 后补 fresh verification，或明确同步可能留下未验证状态 |
-| 模板版本来源 | 当前模板 `main` 已在 2026-08-10 更新 | npm latest 仍为 2026-07-21 发布的 2.0.0 快照 | 不兼容 / 已过期 | 绑定已验证的模板 commit/tag，构建并发布新 CLI；不要仅依赖浮动 `main` |
-| `docs/.scratch` 新路径 | 当前模板把 Local Markdown 功能包放在 `docs/.scratch/<feature>` | 已发布 2.0.0 快照早于该提交；当前 sync 源码无显式路径迁移 | 未完成 | 对旧实例补一次性迁移及冲突矩阵测试，或明确不支持旧实例迁移 |
-| 非空目录与覆盖 | 初始化应避免误伤；`--force` 是显式破坏性操作 | 默认拒绝；`--force` 清空目标全部条目 | 行为明确但高风险 | README 和 CLI help 应明确“全量删除”；发布前增加用户确认 / 更强路径保护测试 |
-| README 与实现一致性 | 文档应反映可验证能力 | README 宣称迁移与冲突 fail closed，但源码 / 测试未体现 | 不一致 | 在实现完成前修正文档，避免把未实现升级能力当成兼容承诺 |
-
-## 迭代建议（仅研究结论，不在本轮实施）
-
-1. 先修复 CLI 与当前模板的投影集合：将 `.qoder` 纳入生成快照并更新初始化断言，或者在模板侧回滚该投影；随后以当前模板 `main` 的确定 commit 做一次 fresh `npm test`。
-2. 将 `YSS_SPEC_TEMPLATE_REF` 从发布流程中的默认浮动 `main` 改为已审查 commit / tag；环境变量保留给开发测试，不作为正式发布基线。
-3. 选择并落实升级策略：实现 `docs/.scratch` 等旧路径的一次性迁移、目标已存在时冲突停止、旧 skill 删除与测试；或删除 README 中尚未实现的迁移承诺。
-4. `sync` 完成后运行 `scripts/sync-skills --check`、`scripts/update-skill-lock --check`、`scripts/verify-template --check`，并将结果写进集成测试；同步不应只更新 hash 元数据。
-5. 发布前核对 npm tarball 的实际内容，而不是只看 GitHub `main`：至少检查 `yss-project.yaml`、六个 projection roots、`skills-lock.json`、三个验证脚本、`docs` 新路径和 `.yss-template.json` 行为。
-
-## 待验证问题
-
-- `.qoder/skills` 是否是当前模板对所有实例的正式投影，还是只应在模板源仓库保留、由 CLI 有意排除？当前 lock / sync 脚本给出的事实是“正式声明”，但需要维护者确认产品决策。
-- `docs/.scratch` 迁移的旧源路径、文件归属、已存在目标的冲突规则和删除规则是什么？当前模板文档已给出新目标路径，但 CLI 默认分支源码未给出迁移实现。
-- 正式发布是否允许模板包跟随 `main`，还是必须由模板 tag / commit 驱动？当前 CLI 支持环境变量覆盖，但默认 `main` 仍会产生不可复现构建。
-- 是否要求 `sync` 对没有 `.yss-template.json` 的旧实例提供 attach / migration 模式？当前实现直接拒绝缺少元数据的目录。
-- 模板新增或变更验证脚本时，CLI 是否应从模板 manifest 动态发现门禁，而不是在 `src/cli.js` 固定三个脚本？
-
-## 实际读取的源
-
-### 本地源
-
-- `/Users/zhudaoming/Projects/yss-spec-project-template/yss-project.yaml`
-- `/Users/zhudaoming/Projects/yss-spec-project-template/CONTEXT.md`
-- `/Users/zhudaoming/Projects/yss-spec-project-template/docs/implementation/create-yss-spec-repository-mode-contract.md`
-- `/Users/zhudaoming/Projects/yss-spec-project-template/AGENTS.md`
-- `/Users/zhudaoming/Projects/yss-spec-project-template/skills-lock.json`
-- `/Users/zhudaoming/Projects/yss-spec-project-template/scripts/sync-skills`
-- `/Users/zhudaoming/Projects/yss-spec-project-template/scripts/update-skill-lock`
-- `/Users/zhudaoming/Projects/yss-spec-project-template/scripts/verify-template`
-
-### 外部一手源
-
-- [`create-yss-spec` GitHub 默认分支](https://github.com/iloveZzz/create-yss-spec/tree/main)
-- [`README.md`](https://github.com/iloveZzz/create-yss-spec/blob/main/README.md)
-- [`package.json`](https://github.com/iloveZzz/create-yss-spec/blob/main/package.json)
-- [`bin/create-yss-spec.js`](https://github.com/iloveZzz/create-yss-spec/blob/main/bin/create-yss-spec.js)
-- [`src/cli.js`](https://github.com/iloveZzz/create-yss-spec/blob/main/src/cli.js)
-- [`scripts/sync-template.js`](https://github.com/iloveZzz/create-yss-spec/blob/main/scripts/sync-template.js)
-- [`template.manifest.json`](https://github.com/iloveZzz/create-yss-spec/blob/main/template.manifest.json)
-- [`tests/init-cli.test.js`](https://github.com/iloveZzz/create-yss-spec/blob/main/tests/init-cli.test.js)
-- [`tests/sync-template.test.js`](https://github.com/iloveZzz/create-yss-spec/blob/main/tests/sync-template.test.js)
-- [`npm registry metadata`](https://registry.npmjs.org/create-yss-spec)
-- [`npm 2.0.0 tarball`](https://registry.npmjs.org/create-yss-spec/-/create-yss-spec-2.0.0.tgz)
-- [`yss-spec-project-template` 当前 `main` 的 `AGENTS.md`](https://github.com/iloveZzz/yss-spec-project-template/blob/main/AGENTS.md)
-- [`yss-spec-project-template` 当前 `main` 的 `skills-lock.json`](https://github.com/iloveZzz/yss-spec-project-template/blob/main/skills-lock.json)
-- [`yss-spec-project-template` 当前 `main` 的 `scripts/sync-skills`](https://github.com/iloveZzz/yss-spec-project-template/blob/main/scripts/sync-skills)

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

@@ -1,164 +0,0 @@
-# `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

@@ -1,43 +0,0 @@
----
-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

@@ -1,41 +0,0 @@
-# 模板发布审查修复 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/reviews/yss-local-tracker-red-green-2026-08-10.md

@@ -1,50 +0,0 @@
----
-status: completed
-owner: ai
----
-
-# Local `docs/.scratch` 与 YSS 生命周期修订验证
-
-## RED 基线
-
-本轮 RED 先将压力场景目标切换为 `docs/.scratch/<feature>/`，再在权威文档修改前运行。当前根 `.scratch` 配置导致 Local root、远程 fallback、持久化 tracker root、Matt/YSS adapter 和各 feature skill 路径断言失败；这证明旧路径仍会被默认使用。
-
-迁移规则同时要求：旧根 `.scratch/` 或 `docs/requirements/tickets/` 只能被只读识别；仅有旧资产时记录 `migration_ref` 并暂停写入；新旧资产并存时返回 `conflict`。
-
-本轮开始时的仓库基线还存在独立的历史问题：`80eecb6 chore: remove local workspace directories` 删除了 `docs/process/` 下的生命周期文件，而 `scripts/verify-template`、`scripts/verify-lifecycle-scenarios` 和 `scripts/verify-yss-router-scenarios` 仍将其列为必需输入。该问题没有通过生成临时产品资产或绕过校验来隐藏。
-
-## GREEN 场景
-
-集成压力脚本现在覆盖：
-
-1. GitHub `origin` + 持久化 Local 配置仍选择 `local-markdown`，写入 `docs/.scratch`，不规划远程 Issue 命令。
-2. 显式选择 GitHub / GitLab 后，平台不可用只生成 `docs/.scratch/<feature>/` 草案，在 `parent-ticket.md` 标记 `publication: pending`，并保留原目标平台。
-3. 多个持久化配置声明不同平台时返回 `conflict`，不覆盖任何配置。
-4. 仅有旧路径资产时返回迁移所需结果；新旧路径并存时返回 `conflict`，两种情况都不写入。
-5. `template-source` 只做模板契约验证，不创建产品 `docs/.scratch`、Spec 或 Ticket。
-
-## REFACTOR 结果
-
-- `docs/agents/issue-tracker.md` 成为 tracker 单一事实来源，默认 `local-markdown`，完整功能包位于 `docs/.scratch/<feature>/`。
-- Matt Local seed、Local-aware skills 和 YSS adapter 已统一到 `docs/.scratch`；Matt 核心流程和五态语义保持不变。
-- setup-matt-pocock-skills 只提供 `local-markdown`、`github`、`gitlab` 三种显式选择；Git remote 不参与排序，unsupported tracker 不写入配置。
-- YSS 原型、OpenAPI、架构图和 Discovery 主动执行 skill 的功能资产路径已归一到 `docs/.scratch/<feature>/`；项目级设计系统仍保留在 `docs/design/`。
-- YSS active 时，`to-spec` 的独立 `ready-for-agent` 提示被适配层收敛为 `ready-for-human`。
-- `Status: claimed/resolved` 只保留为 Wayfinder 临时工作状态，交付 Ticket 必须提升为五态角色。
-- 远程降级保留 `tracker`、`publication: pending` 和 `pending_publication_to`，不自动切换平台。
-- `docs/.scratch` 不应被 `.gitignore` 忽略；模板校验现在显式检查这一契约。
-- `template-source` 模式显式拒绝非空产品 `docs/.scratch` 或根 `.scratch` 目录。
-
-## 验证证据
-
-- `ruby scripts/verify-matt-yss-integration-scenarios`：通过。
-- setup tracker choice / unsupported platform 断言：通过（集成脚本覆盖）。
-- `scripts/verify-yss-ui-scenarios`：通过。
-- `scripts/sync-skills --check`：通过。
-- `scripts/update-skill-lock --check`：通过。
-- `git diff --check`：通过。
-- `ruby -c`：同步、锁文件和两类场景脚本均通过。
-- `scripts/verify-template`：被既有缺失的 `docs/process/lifecycle-artifact-map.md` 阻断。
-- `scripts/verify-lifecycle-scenarios`：被既有缺失的 `docs/process/harness-executive-blueprint.md` 阻断。
-- `scripts/verify-yss-router-scenarios`：被既有缺失的 `docs/process/lifecycle-artifact-map.md` 阻断。
-- 上述 `docs/process` 缺失源于本轮前的 `80eecb6 chore: remove local workspace directories`，未通过生成产品资产或绕过校验来隐藏。