@chenmk/superflow 0.5.21 → 0.5.22

package/assets/skills/superflow-pipeline/references/reviewer-checklist.md

@@ -1,8 +1,102 @@
 # 代码评审清单
 
+## 五维评审与独立上下文（规范入口）
+
+适用于日常代码评审、Quick 验证、完整 SDD 和托管 Host 评审。输入为当前差异、
+确认合同、适用路径规则与原始证据；输出复用现有 reviewer 报告或 Host review JSON。
+本清单是五维、评审深度、隔离包和 finding 复核的唯一规范；superflow-verify 路由执行。
+需求/设计符合度仍核对既有合同，五维不另建需求评审入口。脚本只校验路径、状态标记
+与锚点，不能证明五维充分性；最终风险判断与结论由主 Agent / Host 持有。
+
+### 五维覆盖
+
+| 维度 | 关注点 | 最小证据 |
+|---|---|---|
+| security | 鉴权/权限边界、注入、敏感信息、外部输入 | 当前入口、参数绑定和权限调用链 |
+| performance | 查询范围/N+1、处理规模、CPU/内存/I/O、资源上限 | 实际执行链、规模依据；风险需要时才跑基准 |
+| correctness | 边界、失败恢复、状态、事务、并发、幂等 | 真实调用/写入链、对应断言与失败路径 |
+| maintainability | 重复实现、命名、复杂度、异常处理、测试 seam | 现有复用点、具体源码与测试边界 |
+| architecture | 模块 owner、调用方向、契约兼容、抽象边界 | 调用方/消费方及职责证据 |
+
+每维记录 CHECKED / NOT_APPLICABLE / BLOCKED 与源码/证据依据。CHECKED 表示已检查，
+不自动表示无缺陷；小改动可以一名 reviewer 覆盖五维，不按维度强制派五名 Agent。
+专业视角 reviewer 可只检查明确分配的维度；主 Agent 必须合并覆盖记录，补齐遗漏，
+不能把“未分配/未读取”当不适用。完整 SDD 的真实验收义务保持不变。
+
+### 按实际影响选择深度
+
+`superflow review-coverage` 的 `risk.basis=path-hint`、
+`risk.requiresSemanticAssessment=true` 表示路径定位提示。主 Agent 读取差异、真实调用方
+及写入/消费路径，记录提示档位、实际档位、源码依据和调整理由；文件名、行数或实现者
+自述不作最终风险裁决。风险未知时至少按中档补证据，无法判断记录 NEEDS_CONTEXT。
+
+| 实际影响 | 深度 |
+|---|---|
+| 小范围且已证实无契约、写入、并发、安全、跨模块影响 | 低档，可内联；仍覆盖适用五维 |
+| 其余已明确范围的改动 | 中档，使用一个隔离的独立 reviewer |
+| 有证据的公共契约破坏、迁移/数据一致性、锁/共享状态、安全边界或跨模块影响 | 高档，独立 reviewer + 对命名风险的专项视角；存在独立风险簇且宿主支持时才扇出 |
+
+例如：只追加参数化 SELECT 条件，确认契约/schema/写路径未变且消费范围已核对，
+可由 Mapper 路径提示 high 调整为实际 medium；普通文件新增原子占用/共享状态写入，
+即使路径提示 low 也应升 high。上述示例须由当前源码证据确认，不能按描述自动套档。
+高档不固定代理数、模型名或模型供应商；使用宿主原生配置。用户覆盖深度时记录理由，
+必查范围、合同义务与已知风险不随深度覆盖而删除。
+
+### 隔离包与派发
+
+主 Agent 在临时目录组织下列包，再用宿主原生子代理派发；新 reviewer 不继承实现聊天
+历史（支持 fork_turns 时用 none）。不可用时生成同一包供独立 reviewer 使用，明确独立
+评审尚未执行；不能把主 Agent 自评改名为独立评审或把它计为完整覆盖。
+
+1. 已确认的目标、范围、排除项、真实合同路径和本轮评审问题；自述标记为待核验。
+2. baseline/head 或工作树状态、准确 diff、枚举文件和相关 bundle；不能只给 diff stat。
+3. 当前适用的路径规则、相关源码/调用方/消费方路径、必要环境与原始测试证据路径。
+4. 实际风险判断与本 reviewer 分配的维度/文件；规范清单及四状态/锚点报告要求。
+
+包只保留必要内容与路径，不复制全部仓库、个人规则目录、凭据或整段聊天；遵守原任务
+可读取范围。reviewer 从 diff 起读，只因命名风险扩查相关调用方，记录扩查原因；发现包
+与当前源码/合同漂移时返回 NEEDS_CONTEXT，不凭旧包评当前代码。Reviewer 只读，不改
+源码、运行应用、查写业务库或启动嵌套监督；需要新的运行证据交回实施方。
+
+### 主 Agent 复核和合并
+
+读取全部 reviewer 的覆盖表、原始 finding 与 concern；逐条重读 file:line、调用方、
+冻结合同和相应原始测试证据，尝试用实际源码证伪。不能因“测试全绿”直接接受或拒绝。
+按“根因 + 受影响路径 + 业务后果”合并重复项，保留各 reviewer 的来源和完整影响范围；
+不能只按相同行号、措辞或严重度去重。冲突的判断列出证据，补查后裁决，不取多数票。
+
+每项记录 accepted / rejected / needs-evidence 与理由；无证据的结论标记待证，不伪造
+严重度。实际影响决定严重度，建议与阻断缺陷分开；缺陷无第二调用方时不强推通用抽象。
+五维与纳入文件全部有记录后，主 Agent 一次提交全部实质 finding。托管继续使用已有
+finding ID / acceptanceContractRefs，协议、预算和状态 owner 不变；子代理报告不能直接
+晋升 pass，格式检查通过也不等于代码正确。只重跑失效或合同要求的证据。
+
+### Reviewer 报告形状
+
+沿用现有四状态报告，不另建机器协议；托管只在临时报告完成这些记录，最终投影进原
+Host review JSON 的 summary/findings/coverage。`--report` 只检查原状态与锚点，五维完整性、
+实际风险与结论仍由主 Agent 核实。历史未带五维记录的报告保留，但不能称已按本规范全查。
+
+```markdown
+DONE
+## Impact
+路径提示 / 实际深度 / 源码依据 / 调整理由 / diff 与合同版本
+## Axes
+维度 | CHECKED / NOT_APPLICABLE / BLOCKED | 文件范围与依据
+# 逐项填写 security / performance / correctness / maintainability / architecture
+## Findings
+- src/example.ts:12: [维度][严重度] 根因、后果、证据、修复与验收建议
+# 无 finding 时写 None；不要用带 - 的占位 finding
+## Concerns
+未解决问题与缺少证据；DONE_WITH_CONCERNS 必须提供此段
+```
+
+旧专项检查按适用路径继续使用；不能用任一不适用项强加运行要求，也不能删减冻结的
+必查项。以下细则提供五维的场景检查，不另持有分档、派发或最终结论。
+
 ## 使用方式
 
-每批实现完成后，Reviewer Agent 按此清单逐条检查。任一检查项未通过，不得进入下一批次。
+每批实现后按冻结合同与适用路径检查；主 Agent 复核全部实质 finding 后决定是否需要整改。建议、不适用项与阻断缺陷分开记录，不能用计数直接裁决交付。
 
 ---
 
@@ -31,7 +125,7 @@
 |---|--------|----------|----------|
 | 5 | 是否破坏历史枚举 | 检查枚举修改是否影响既有值 | 不删除/重命名已有枚举值，新增值只能追加 |
 | 6 | 是否 fail-open | 检查服务间调用失败时的处理 | 失败时返回错误/降级，不返回成功或默认放行 |
-| 7 | 是否缺少幂等 | 检查创建/更新/消费操作 | 关键操作有幂等控制（唯一键/幂等键/状态机去重） |
+| 7 | 是否缺少幂等 | 检查创建/更新/消费操作 | 按业务幂等键独立短事务原子占用并明确成功/失败/重试；唯一索引仅作合同认可的兜底 |
 | 8 | 是否缺少事务边界 | 检查多表操作和消息发送 | @Transactional 覆盖正确，消息发送不在事务内或已做补偿 |
 
 ## 架构边界检查
@@ -169,7 +263,7 @@
 ```
 批次评审报告：P{n} - {名称}
 
-检查项总数：66
+检查项总数：按本轮适用范围统计
 通过：X 项
 未通过：X 项
 不适用：X 项
@@ -183,3 +277,5 @@
 
 结论：通过 / 不通过（需修复后重新评审）
 ```
+
+报告容器围栏使用空格缩进并明确闭合。列表/引用中含制表符的围栏目前明确拒绝结构核验；先规范格式，不用早期 DONE/PASS 绕过。原始执行日志中的制表符保留，不能为修格式改写证据。

package/assets/skills/superflow-pipeline/references/superpower-technical-design-template.md

@@ -45,6 +45,23 @@ canonical_sources:
 - If this document conflicts with canonical sources, stop and return to
   `$superflow-docs`; do not let implementation prompts carry the conflict forward.
 
+## Directory Changes / 目录范围
+
+逐项列出 Created / Modified / Deleted / Not created 的模块和关键文件，说明职责与复用依据。
+可用树或列表，但路径不能只列名称：标明各项动作、owner 与原因；无变更类别明确写 None。
+Not created 记录已考虑但不新增的模块、工具、缓存、状态或平行入口及拒绝理由。
+纯实现内 helper/方法调整仍回填实际清单，不自动扩大业务范围；已确认模块内且不改变合同
+的实现细节不重开需求确认，若需更新冻结 HOW 则由文档 owner 刷新交接并走既有复审。
+新增职责、跨模块依赖、允许路径范围或验收义务变化时先回澄清/文档确认，不能以普通 helper
+名义扩展。运行保护、源覆盖与已有确认规则保持适用；目录清单不成为另一套状态。
+
+| Action | Module/file | Owner and responsibility | Reuse/evidence or rejection reason |
+|---|---|---|---|
+| Created | None / `<path>` | | |
+| Modified | None / `<path>` | | |
+| Deleted | None / `<path>` | | |
+| Not created | None / `<candidate>` | | |
+
 ## Source-Level HOW
 
 | Requirement/Scenario | Code anchor     | Current behavior | Target HOW                | Files/methods | Risk   |

package/assets/skills/superflow-pipeline/references/test-execution-template.md

@@ -1,5 +1,9 @@
 # 测试执行与结果记录模板
 
+先读 [test-guide.md](test-guide.md)，继承 tests.md / Quick Spec 已冻结的验证信号。
+下列模板按适用用例填写，不适用项写源码依据；必测项缺环境记录 BLOCKED/PARTIAL。
+沿既有 coverage/receipt 核对事实，不用模板示例新建测试策略或降低冻结门禁。
+
 记录测试的执行环境、执行过程和结果，作为交付物的一部分。
 
 运行验收必须使用 tests.md 冻结的环境，不能擅自以本地容器或 Mock 替代共享开发环境。
@@ -21,7 +25,7 @@
 | 执行人 | ____ |
 | 操作系统 | Linux / macOS / Windows |
 | JDK 版本 | 17 |
-| 数据库 | MySQL 8.0 / H2 |
+| 数据库 | tests.md 冻结的引擎/主版本（如 MySQL 8.0） |
 | Spring Profile | dev / test / cmk |
 | 应用端口 | 9527 |
 | 上下文路径 | / |
@@ -195,9 +199,9 @@ HTTP 200、字段非空、mock-only、DB-only、`BUILD SUCCESS`、`Tests are ski
 - 验证时间：
 ```
 
-## 任务完成 Checklist（全部满足才能标记完成）
+## 任务完成 Checklist（冻结的适用项全部满足）
 
-以下 checklist 用于判定一个实现任务是否真正完成。每完成一项勾选一项，**全部勾选后才能标记任务完成**。
+先按 tests.md 的用例和信号确定适用项；全部必测项成立才能完成。纯函数不要求应用、登录或数据库；完整 SDD 的真实入口义务不得删减。独立核验复用有效原始证据，只有失效或合同明确要求的路径才重跑。
 
 ### 开发阶段（Worker 执行）
 - [ ] 已从 tests.md 提取本批次用例 ID、自动化命令和断言
@@ -208,11 +212,11 @@ HTTP 200、字段非空、mock-only、DB-only、`BUILD SUCCESS`、`Tests are ski
 - [ ] 代码自审通过（无 CRITICAL/HIGH 问题，检查空指针/异常/事务/日志）
 - [ ] 编译通过（`mvn clean compile -DskipTests` BUILD SUCCESS）
 - [ ] 已执行同一命令确认 GREEN，并回填通过证据
-- [ ] 旧进程已停止（`pkill` + 端口确认无占用）
-- [ ] 应用已重新启动（`mvn spring-boot:run` 或 `./gradlew bootRun`）
-- [ ] 进程已验证（PID 存在、启动时间接近当前时间、端口绑定正确）
+- [ ] 需重启时仅通过 owner 校验的清理入口停止本任务进程，确认端口释放
+- [ ] 已启动当前待测构建，或核验健康实例的构建/配置未变后复用
+- [ ] 进程已验证（PID/启动指纹、当前构建与端口绑定正确）
 - [ ] 健康检查通过（`curl /actuator/health` 返回 UP）
-- [ ] 日志确认是本次启动（时间戳匹配当前时间）
+- [ ] 日志与本次验证的实例/构建身份一致
 
 ### 接口测试阶段（Worker 逐项执行）
 - [ ] Token 已获取（完整的 `/captcha/image` + `/login` 流程，token 非空）
@@ -239,15 +243,15 @@ HTTP 200、字段非空、mock-only、DB-only、`BUILD SUCCESS`、`Tests are ski
 - [ ] 包含：进程验证证据（PID、启动时间、端口）
 
 ### 独立验证阶段（Tester 执行）
-- [ ] Tester 独立执行全部用例（不参考 Worker 报告）
+- [ ] Tester 独立核对全部必测用例与原始证据，重跑失效或合同指定路径
 - [ ] Tester 客观报告通过/失败
 
 ### Leader 验证阶段（Leader 执行）
-- [ ] Leader 抽查至少 30% 关键用例
-- [ ] Leader 确认进程是新启动的
+- [ ] Leader 按合同与风险检查关键用例和未关闭 finding
+- [ ] Leader 确认运行实例对应当前待测构建/配置
 - [ ] Leader 确认接口有真实调用证据
 
-**以上 checklist 全部勾选后，才能标记任务完成。**
+**冻结的全部适用项通过、无必测阻塞后，才能标记任务完成。**
 
 ## 质量红线
 
@@ -260,6 +264,6 @@ HTTP 200、字段非空、mock-only、DB-only、`BUILD SUCCESS`、`Tests are ski
 - 不允许用测试 Controller、mock endpoint、绕过鉴权端点证明真实外部入口已通过
 - 不允许把泛化外部失败当作通过，除非需求明确要求该失败结果
 - 不允许只检查主仓数据库结构就关闭跨仓共享表任务；必须覆盖全部消费仓实体/Mapper/SQL
-- **不允许"编译成功 + 单元测试通过"就标记任务完成，必须完成上述 checklist 全部项**
+- **不允许"编译成功 + 单元测试通过"就标记任务完成，必须完成冻结的全部适用验证项**
 
 执行凭证格式与持久化前后对照遵循 [document-review-coverage.md](document-review-coverage.md)，不要另建格式；历史局部结论保留，以最后一个中英文一致的验证结果为最终汇总。

package/assets/skills/superflow-pipeline/references/test-guide.md

@@ -1,30 +1,82 @@
-# 测试失败修复指南
-
-## 失败类型与修复方向
-
-| 失败现象 | 可能原因 | 修复方向 |
-|---|---|---|
-| 应用启动失败 | 配置文件错误 / 端口冲突 / Bean 初始化失败 | 检查 `application.yml`，确认端口未被占用，检查 Bean 依赖注入 |
-| 接口返回 404 | URL 路径错误 / 上下文路径未拼接 / 接口未注册 | 核对 Controller 的 `@RequestMapping` 路径，确认 context-path 已拼接 |
-| 接口返回 500 | 空指针 / SQL 异常 / 事务回滚 | 查看日志栈追踪，定位具体异常行号，检查入参是否为空 |
-| 数据库断言失败 | SQL 未生效 / 事务未提交 / 缓存未更新 | 确认方法上有 `@Transactional`，检查 `updateByPrimaryKeySelective` 返回值 |
-| 日志断言失败 | 日志级别过滤 / 异步日志未刷新 | 检查 `logback.xml` 日志级别，确认日志输出时机 |
-| 并发测试失败 | 竞态条件 / 锁未生效 / 事务隔离级别 | 检查锁的实现（数据库锁 / 分布式锁），确认事务传播行为 |
-| 灯色下发验证失败 | DMS 未连接 / 异步任务未执行 | 确认 DMS 服务可用，检查 `@Async` 线程池配置 |
-| Excel 导出验证失败 | 文件格式错误 / 字段映射错误 | 检查 EasyExcel 或 POI 配置，确认字段注解正确 |
-
-## 修复流程
-
-1. **复现问题**：根据测试用例的前置条件和执行步骤，手动复现失败场景
-2. **查看日志**：启动应用时添加 `--debug` 或检查 `logs/` 目录下的日志文件
-3. **定位代码**：根据日志中的异常栈追踪，找到具体的源码位置（类名 + 方法名 + 行号）
-4. **分析根因**：对照 design.md 中的设计方案，确认实现是否与设计一致
-5. **修改代码**：修复 bug，确保不引入新的问题（回归测试）
-6. **重新测试**：重新执行失败的测试用例，确认修复成功
-7. **更新文档**：如果修复涉及设计变更，同步更新 design.md 和 tasks.md
-
-## 质量红线
-
-- 不允许跳过失败的测试用例直接提交代码
-- 不允许修改测试用例的断言标准来"让测试通过"
-- 不允许在没有测试覆盖的情况下修改核心逻辑
+# 测试选择与验证闭环
+
+## 适用范围与唯一 owner
+
+在生成 tests.md、实现任务开始、整改和交付核验时读取本指南。输入是已确认需求、
+源码差异、项目测试与冻结合同；输出写入现有 tests.md / Quick Spec 和 test-report.md。
+纯文档修改只核验文档合同；纯函数只核验对应 seam，不虚构应用或数据库。
+
+superflow-docs 冻结验证方案；实施方执行并留存证据；superflow-verify / Host 判断
+充分性和历史证据适用性；既有 coverage/receipt/lint 核对确定事实，状态仍由原状态机持有。
+数据库机器合同只引用 [document-review-coverage.md](document-review-coverage.md#数据库分层合同)，
+沿用 testLayer、mockBoundary 和 execution-receipt.v1，不引入另一套级别或证据格式。
+本指南由 Superflow 分发；无需安装 ake 的验证技能或创建 .ake 记忆。
+
+## 开工前选择信号
+
+先检索现有测试、构建接线、环境配置和项目规则，复用相同 seam、命令与工具。
+在生产代码修改前，把每个受影响行为映射到下面的信号，并冻结用例 ID、命令、断言和证据位置。
+不适用项写明源码依据；环境缺失的必测项是 BLOCKED/PARTIAL，不能写“不适用”。
+已冻结的必测项不得由实施方删减；发现遗漏返回文档 owner 修复合同。
+
+| 改动/风险 | 需要冻结的信号 |
+|---|---|
+| 纯函数或局部算法 | 窄化单测、边界/失败断言、项目适用的构建与静态检查 |
+| 组件注册、装配、配置 | 上述检查 + 真实应用/上下文启动、就绪条件 |
+| SQL、Mapper、持久化、事务、CAS、数据驱动行为 | 窄化逻辑检查 + 生产 statement 的同类型数据库验证；完整 SDD 还覆盖真实消费入口 |
+| API、公开字段或鉴权 | 项目已有契约测试/快照 + 真实受影响入口；新增契约建立基线 |
+| 新增贯穿接口、业务与存储的能力 | 构建、单测、装配、真实数据库、接口契约和至少一条真实主流程 |
+| Bug 修复 | 同一症状的 RED → GREEN + 受影响回归；环境错误不算业务 RED |
+| MQ、设备、回调、缓存或第三方语义 | 冻结真实协议/后端/入口验证与可隔离边界，缺环境保留阻塞 |
+| 仅报告格式或测试隔离变更 | 核验受影响合同/证据，不自动重跑无关业务链路 |
+
+保留现有项目用例的层级编号，不把 ake 的 L1/L3/L5/L7/L8/L10 编号移植进 Superflow。
+数据库 testLayer 与入口验收 level 是不同维度，不能用同一编号掩盖真实后端缺失。
+
+## Mock 与环境
+
+[Mock 指南](mock-strategy-guide.md)只说明隔离边界。逻辑单测可 mock 数据访问依赖，
+但该结果不能证明 SQL、事务或落库。必测数据库 case 禁止 mock 生产 Service/Mapper；
+允许隔离的外部客户端由 mockBoundary 冻结。MySQL 不可用 H2/SQLite 的通过结果替代。
+真实同引擎容器数据库不是 Mock；必须冻结引擎/主版本、schema 来源、生产 statement 和清理。
+有共享环境要求就使用该环境；没有该要求且合同认可容器方案时，复用项目已有容器基建。
+没有可执行环境时保留局部逻辑证据，真实数据库用例 BLOCKED/PARTIAL，不降低验收等级。
+
+## 可留存的业务场景测试
+
+优先把关键业务主流程和 Bug 复现写成项目内已有框架的可重复回归测试，复用现有目录、
+夹具、登录、查库和运行脚本。已有等价测试时扩展它；不新建平行场景框架或公共 helper。
+低层测试已能证明的纯逻辑留在低层。Java 可沿已有 JUnit/RestAssured/JdbcTemplate；
+其他技术栈使用项目原生工具，不为执行本指南强制引入 Java 依赖。
+
+业务场景分别断言：响应中的具体业务值；同业务 ID 的数据库状态；合同要求的消息、
+日志或其他副作用。数据库前后值、影响行数、非目标记录保持不变按规范合同冻结。
+HTTP 200、非空、调用次数或 affectedRows=1 都不能单独证明正确落库。
+
+主体数据按每轮/用例唯一化，稳定基础数据按业务键或逻辑名解析，缺失在 setup 阶段报错。
+复用项目环境配置与登录获取命令；只记录凭据来源，不把密码/token 固化进文档或源码。
+共享基础数据不自动 seed 或删除；造数权限、owner、清理范围与失败清理由合同明确。
+依赖环境的场景测试用项目已有 tag/profile/脚本单独执行，避免污染纯单测；分组不等于跳过
+交付必测项，完整验收必须显式运行所需分组并核对执行数。轮次互不依赖、不共享可变主体。
+
+## 执行、复核与证据继承
+
+先执行窄化测试，再执行合同要求的构建、启动和真实调用；读退出码、执行数、原始输出，
+按 [执行模板](test-execution-template.md)回填用例证据。断言冻结后不为迎合错误输出而修改。
+通过结论只能覆盖实际执行的层级；零用例、skipped 和未执行项不能晋升 PASS。
+
+整改先建立“当前差异 → 失效证据 → 重跑命令”映射。生产代码、SQL、配置、鉴权、公开
+契约、运行入口或环境变化使相关证据失效；仅报告格式修改不自动失效旧源码的运行结果。
+历史证据必须匹配源码/构建、后端/入口与合同，由独立评审确认适用；不能放行另一源码版本。
+健康实例与待测构建一致时复用，代码/配置或身份不匹配时重启并重验；停止仅使用合同的
+owner 校验与清理入口，不能用宽泛 pkill/killall。纯函数不要求进程；必测真实入口不能豁免。
+评审方只读核验源码和原始证据，实施方负责运行与清理；独立评审不等于机械重跑全部环境。
+
+## 失败修复
+
+按用例前置条件复现，读取实际 SQL/绑定参数、事务边界、响应和日志定位根因。
+数据库失败先查生产 statement、写入字段、schema 与同 ID 前后值，不凭症状直接加事务
+注解或换 Mapper 方法。修复后跑同一路径和受影响回归；方案变化先修复规范合同。
+不跳过失败项、不改断言迎合实现、不隐瞒阻塞。
+
+跨轮复用对命令/目录/调用环境敏感的检查时，按 [声明式上下文](document-review-coverage.md#声明式执行上下文与证据复用)冻结 executionContext；保留历史证据，但不得把未绑定旧记录标为新上下文完整通过。

package/assets/skills/superflow-pipeline/scripts/superflow-archive.sh

@@ -29,7 +29,8 @@ resolve_doc_path() {
     printf '%s\n' "$CHANGE_DIR/$value"
     return 0
   fi
-  if [[ -f "$value" ]]; then
+  if [[ "$value" == /* && -f "$value" ]]; then
+    [[ ! -L "$value" ]] || die "symbolic document link rejected: $value"
     printf '%s\n' "$value"
     return 0
   fi
@@ -47,11 +48,13 @@ annotate_frontmatter() {
   local tmp
 
   [[ -f "$file" ]] || return 0
+  [[ ! -L "$file" ]] || die "symbolic document link rejected: $file"
   tmp="$(mktemp)"
   chmod 600 "$tmp"
 
   if head -1 "$file" | grep -q '^---'; then
     awk -v archive="$archive_name" -v status_field="$status_field" '
+      closed { print; next }
       /^archived-with:/ { next }
       status_field != "" && /^status:/ { next }
       NR == 1 && /^---/ { print; next }
@@ -59,6 +62,7 @@ annotate_frontmatter() {
         print "archived-with: " archive
         if (status_field != "") print "status: " status_field
         print
+        closed = 1
         next
       }
       { print }
@@ -129,13 +133,45 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 STATE="$SCRIPT_DIR/superflow-state.sh"
 GUARD="$SCRIPT_DIR/superflow-guard.sh"
 VALIDATE="$SCRIPT_DIR/superflow-yaml-validate.sh"
-CHANGE_DIR="$(cd "$CHANGE_DIR" && pwd)"
+[[ ! -L "${CHANGE_DIR%/}" ]] || die "canonical change directory required; symbolic link rejected"
+CHANGE_DIR="$(cd "$CHANGE_DIR" && pwd -L)"
+for component in "$CHANGE_DIR" "$(dirname "$CHANGE_DIR")" "$(dirname "$(dirname "$CHANGE_DIR")")" "$(dirname "$(dirname "$(dirname "$CHANGE_DIR")")")"; do
+  [[ ! -L "$component" ]] || die "canonical directory required; symbolic link rejected: $component"
+done
+CHANGE_DIR="$(cd "$CHANGE_DIR" && pwd -P)"
 CHANGE_NAME="$(basename "$CHANGE_DIR")"
-PROJECT_ROOT="$(cd "$CHANGE_DIR/../../.." && pwd)"
+IS_MOVED=false
+IS_STANDARD=false
+case "$CHANGE_DIR" in
+  */openspec/changes/archive/*)
+    [[ "$(basename "$(dirname "$CHANGE_DIR")")" == archive ]] || die "canonical archive directory required"
+    PROJECT_ROOT="$(cd "$CHANGE_DIR/../../../.." && pwd -P)"
+    IS_MOVED=true
+    ;;
+  */openspec/changes/*)
+    [[ "$(basename "$(dirname "$CHANGE_DIR")")" == changes ]] || die "canonical change directory required"
+    IS_STANDARD=true
+    PROJECT_ROOT="$(cd "$CHANGE_DIR/../../.." && pwd -P)"
+    ;;
+  *) PROJECT_ROOT="$(cd "$CHANGE_DIR/../../.." && pwd -P)" ;;
+esac
+for component in "$PROJECT_ROOT/openspec" "$PROJECT_ROOT/openspec/changes" "$PROJECT_ROOT/openspec/changes/archive"; do
+  [[ ! -L "$component" ]] || die "canonical directory required; symbolic link rejected: $component"
+done
 ARCHIVE_ROOT="$PROJECT_ROOT/openspec/changes/archive"
 ARCHIVE_NAME="$CHANGE_NAME"
 
 "$VALIDATE" "$CHANGE_DIR"
+if [[ "$IS_STANDARD" == true && ( "$(field_value archived)" == true || "$(field_value phase)" == done ) ]]; then
+  die "active standard directory has archived state: $CHANGE_DIR; confirm the physical archive location first. If this was state-only closeout, repair through the existing state owner: SUPERFLOW_FORCE_PHASE=1 $STATE set '$CHANGE_DIR' phase archive; $STATE set '$CHANGE_DIR' archived false; then rerun --apply with OpenSpec available"
+fi
+if [[ "$IS_STANDARD" == true ]] && ! command -v openspec >/dev/null 2>&1; then
+  die "OpenSpec is required for standard change directory: $CHANGE_DIR; install/restore openspec, then rerun this command"
+fi
+if [[ "$(field_value archived)" == true && "$(field_value phase)" == done ]]; then
+  printf 'already archived: %s; no changes required\n' "$CHANGE_DIR"
+  exit 0
+fi
 "$GUARD" "$CHANGE_DIR" archive
 
 printf 'Archive summary:\n'
@@ -148,7 +184,11 @@ if [[ "$CHANGE_DIR" == "$PROJECT_ROOT/openspec/changes/$CHANGE_NAME" ]] && comma
   printf '%s\n' "- openspec_archive: openspec archive $CHANGE_NAME --yes"
   ARCHIVE_NAME="$(date -u '+%Y-%m-%d')-$CHANGE_NAME"
 else
-  printf '%s\n' "- openspec_archive: unavailable; fallback to state-only archive"
+  if [[ "$IS_MOVED" == true ]]; then
+    printf '%s\n' "- openspec_archive: already moved; recover remaining closeout"
+  else
+    printf '%s\n' "- openspec_archive: unavailable; fallback to state-only archive"
+  fi
 fi
 
 if [[ "$MODE" == "--dry-run" ]]; then
@@ -159,13 +199,20 @@ fi
 
 if [[ "$CHANGE_DIR" == "$PROJECT_ROOT/openspec/changes/$CHANGE_NAME" ]] && command -v openspec >/dev/null 2>&1; then
   (cd "$PROJECT_ROOT" && openspec archive "$CHANGE_NAME" --yes)
-  archived_dir=""
-  if [[ -d "$ARCHIVE_ROOT/$CHANGE_NAME" ]]; then
-    archived_dir="$ARCHIVE_ROOT/$CHANGE_NAME"
-  else
-    archived_dir="$(find "$ARCHIVE_ROOT" -maxdepth 1 -mindepth 1 -type d -name "*-$CHANGE_NAME" 2>/dev/null | head -1 || true)"
+  candidates=()
+  if [[ -d "$ARCHIVE_ROOT" ]]; then
+    for candidate in "$ARCHIVE_ROOT"/*; do
+      [[ -d "$candidate" ]] || continue
+      candidate_name="$(basename "$candidate")"
+      if [[ "$candidate_name" == "$CHANGE_NAME" || "$candidate_name" == *-"$CHANGE_NAME" ]]; then
+        [[ ! -L "$candidate" ]] || die "canonical archive directory required; symbolic link rejected"
+        candidates+=("$candidate")
+      fi
+    done
   fi
-  [[ -n "$archived_dir" && -d "$archived_dir" ]] || die "openspec archive completed but archive dir was not found"
+  [[ "${#candidates[@]}" -gt 0 ]] || die "openspec archive completed but archive dir was not found; supply explicit archive path"
+  [[ "${#candidates[@]}" -eq 1 ]] || die "multiple archive targets found; supply explicit archive path"
+  archived_dir="${candidates[0]}"
   ARCHIVE_NAME="$(basename "$archived_dir")"
   CHANGE_DIR="$(cd "$archived_dir" && pwd)"
   annotate_archive_docs "$ARCHIVE_NAME"

package/assets/skills/superflow-pipeline/scripts/superflow-guard.sh

@@ -235,16 +235,33 @@ verification_report_path() {
 
 require_closeout_markers() {
   local report="${1:-$CHANGE_DIR/test-report.md}"
+  local lint output
   if [[ ! -f "$report" ]]; then
     issues+=("verification report path does not exist: $report")
     return 0
   fi
-  if ! grep -Eiq '(Verification Result|验证结果|验证结论)[[:space:]:：|*-]*(PASS|通过)' "$report"; then
-    issues+=("verification result PASS marker not found in verification report")
-  fi
-  if ! grep -Eiq '(Archive Readiness|归档就绪)[[:space:]:：|*-]*(PASS|READY|通过|就绪)' "$report"; then
-    issues+=("archive readiness PASS marker not found in verification report")
-  fi
+  for lint in \
+    "${SUPERFLOW_REPORT_LINT:-$SCRIPT_DIR/../../../scripts/superflow-test-report-lint.py}" \
+    "$SCRIPT_DIR/../../../hooks/superflow-test-report-lint.py"; do
+    [[ -f "$lint" ]] || continue
+    if ! output="$(python3 - "$lint" "$report" <<'PYCLOSEOUT'
+import runpy, sys
+from pathlib import Path
+module = runpy.run_path(sys.argv[1])
+text = Path(sys.argv[2]).read_text()
+if module["final_report_result"](text) != "PASS":
+    print("verification result PASS marker not found in verification report")
+if module["archive_readiness_result"](text) != "PASS":
+    print("archive readiness PASS marker not found in verification report")
+PYCLOSEOUT
+)"; then
+      issues+=("verification report closeout parser failed")
+    elif [[ -n "$output" ]]; then
+      issues+=("$output")
+    fi
+    return
+  done
+  issues+=("superflow-test-report-lint.py not found for closeout guard")
 }
 
 require_branch_handled() {

package/assets/skills/superflow-quick-dev/SKILL.md

@@ -28,7 +28,7 @@ ake-harness 的 `ssd-propose`，不得因为它可见就自动改派；只有用
 
 - Intent / Non-goals；
 - Current behavior / Target behavior；
-- 已确认的测试 seam；
+- 已确认的测试 seam，以及按[测试指南](../superflow-pipeline/references/test-guide.md)选择的适用信号、命令、断言和证据位置；
 - 按依赖排序的实施步骤；
 - Given / When / Then 验收条件；
 - 风险、升级条件和 deferred；
@@ -37,8 +37,8 @@ ake-harness 的 `ssd-propose`，不得因为它可见就自动改派；只有用
 用户批准前不得修改运行时代码；收到当前磁盘版本的明确批准后，才运行
 `superflow quick "<request>" --path <files...> --seam <existing-file> --spec <spec> --approve`。
 CLI 将当前内容摘要绑定到批准状态。Intent、Non-goals 或 Acceptance Criteria 变化时回到
-`draft`，重新批准后才实施。按 TDD 和 verification-loop 逐项跑 RED/GREEN 信号，完成后
-复用 `superflow review-coverage` 和 `superflow eval` 的证据格式收口。
+`draft`，重新批准后才实施。先读取[测试指南](../superflow-pipeline/references/test-guide.md)，核对当前批准的 Quick Spec 已冻结适用信号、命令、
+断言和证据位置；缺项先补齐并重新批准；按 TDD 逐项跑 RED/GREEN，完成后复用 `superflow review-coverage` 和 `superflow eval` 的证据格式收口。
 
 Quick 路径不创建 OpenSpec checkpoint，也不自动提交、推送或发布；一旦范围扩大，保留
 spec 作为线索并转正式 SDD。

package/assets/skills/superflow-verify/SKILL.md

@@ -1,10 +1,16 @@
 ---
 name: superflow-verify
-description: Use when an SDD/OpenSpec change is ready for verification, test-report closure, code review, branch/worktree handling, or retry decisions after implementation.
+description: Use when reviewing code changes or verifying an SDD/OpenSpec implementation, test evidence, branch/worktree handling, or retry decisions.
 ---
 
 # SDD Verify
 
+## 验证信号复核
+
+读取[测试指南](../superflow-pipeline/references/test-guide.md)，核对当前差异、冻结用例及
+实际执行数；区分逻辑、数据库和真实入口结论。先判断历史证据是否失效，再要求实施方
+重跑受影响验证；仅报告格式变更不自动重跑全链路。评审方只读核验原始输出与源码。
+
 Before semantic code review, run `superflow review-coverage --json` (or pass
 `--base <ref>` for a branch review). Use its included/excluded inventory and
 path-specific rules to account for every changed file. Review related Java
@@ -12,16 +18,23 @@ and Mapper XML files together when they share a bundle. Do not treat this
 mechanical inventory as a correctness verdict: findings still need source
 anchors, a fresh reading of the affected call path, and independent judgment.
 
-Use the reported risk tier to choose review depth: low may be reviewed inline;
-medium requires an independent view; high requires focused coverage of the
-named high-impact paths in addition to the ordinary Host review. Every
-reviewer report starts with `DONE`, `DONE_WITH_CONCERNS`, `BLOCKED`, or
-`NEEDS_CONTEXT`. Run `superflow review-coverage --report <file> --json` to
-validate that marker and every `file:line` finding anchor. `BLOCKED` and
-`NEEDS_CONTEXT` require more evidence before triage; `DONE_WITH_CONCERNS`
-requires Host investigation of each concern before deciding. Re-read each
-anchor and attempt to disprove the finding before assigning severity. Keep
-unverifiable claims separate rather than giving them a guessed severity.
+复用检查存在 executionContext 声明时，独立核对当前命令、cwd、已选环境、源码、
+构建和入口；调用环境与冻结要求不同时不能沿用 PASS。未声明旧证据保留原边界，
+不以 JSON 存在或哈希一致代替执行真实性/业务充分性。
+
+
+## 五维与独立评审入口
+
+代码质量评审必须读取[统一 Reviewer 清单](../superflow-pipeline/references/reviewer-checklist.md)，
+按其中的实际影响分档、隔离包、五维覆盖、finding 证伪与合并步骤执行。
+`review-coverage` 的 risk.tier 是路径提示，不能直接决定实际深度；打印提示与实际档位及依据。
+普通代码评审可以直接进入此入口，不要求先创建 SDD 状态；有冻结合同则同时核验符合度。
+主 Agent 持有最终判断，Reviewer 只提供只读独立视角，Runner 不裁决语义风险。
+
+沿现有四状态报告执行 `superflow review-coverage --report <file> --json`，检查标记与锚点。
+它不证明五维充分性；主 Agent 仍须逐项核验原始证据。BLOCKED/NEEDS_CONTEXT 先补证据，
+DONE_WITH_CONCERNS 先调查全部 concern，再决定。原生子代理支持时，中档以上以隔离上下文
+派发；高档按独立风险簇追加专项视角，不固定代理数或模型。无法独立评审时如实记录缺口。
 
 ## 评审回应纪律
 
@@ -55,7 +68,10 @@ revert that simplification. Keep simplification in a separate commit from the
 feature, and stop if it reaches files outside the original change. This is a
 readability pass, not a second code review or a license for unrelated cleanup.
 
-## Entry Check
+## Entry Check (SDD only)
+
+普通代码评审完成上述五维/独立核验后直接返回评审结论；以下阶段状态、
+测试交付、分支和归档步骤仅适用于关联的 SDD/OpenSpec 交付，不为裸 diff 新建状态。
 
 Run:
 

package/assets/skills-en/openspec-apply-change/SKILL.md

@@ -11,6 +11,14 @@ metadata:
 
 Implement tasks from an OpenSpec change.
 
+## Superflow implementation verification entry
+
+Within the Superflow workflow, before the first task read the
+[test guide](../superflow-pipeline/references/test-guide.md) and frozen tests.md/project
+tests. Execute inherited RED/GREEN and required real verification per task; mark
+complete only with evidence. Missing contracts return to superflow-docs; missing
+environments remain blocked. Plain OpenSpec work follows project verification rules.
+
 **Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
 
 **Steps**

package/assets/skills-en/openspec-archive-change/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: openspec-archive-change
-description: Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete.
+description: Use when the user wants to archive a completed pure OpenSpec change without .sdd/state.yaml.
 license: MIT
 compatibility: Requires openspec CLI.
 metadata:
@@ -13,6 +13,22 @@ Archive a completed change in the experimental workflow.
 
 **Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
 
+## SDD Archive Routing (Run First)
+
+Resolve the target change directory; if ambiguous, use the selection step below
+to confirm it, then check that directory for `.sdd/state.yaml`. When it exists,
+immediately load `$superflow-archive` and stop the remaining steps in this skill.
+If verification has not passed or tasks remain incomplete, follow that skill back
+to verification/implementation; do not fall back to this skill to archive.
+SDD changes cannot use the incomplete-task confirmation, `Archive without syncing`,
+or `mv` shortcuts below. `superflow-archive` owns readiness, confirmation, OpenSpec
+merging, and state closeout. Moved SDD directories use that owner's recovery flow
+with the explicit archive path.
+
+Run the pure OpenSpec workflow below only when the target has no `.sdd/state.yaml`.
+This is Agent semantic routing; the command Hook is not an operating-system-level
+interceptor and must not be assumed to block arbitrary `mv` commands.
+
 **Steps**
 
 1. **If no change name provided, prompt for selection**