@ifrankwang/openspec-agents 0.118.0

package/assets/skills/java-security/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: java-security
+description: Java 后端安全实现规范（security-baseline 的 Java 配套）。MyBatisPlus 注入防护、POI OOM 防范、LangChain4j 安全配置、Spring 安全配置、SLF4J 日志脱敏。
+capabilities: ["security", "tech-stack-java"]
+---
+
+> **项目规范优先**：本 skill 所列约定为推荐标准。若项目已有明确规范且与本 skill 不一致，以项目规范为准。
+> 本文是 security-baseline 的 Java 实现配套，仅含 Java/Spring 技术栈特有的实现细节。调用本 skill 须同时加载 security-baseline（通用原则在此）。通用原则见 security-baseline。
+
+## MyBatisPlus 数据安全
+
+**参数绑定（防 SQL 注入）**：
+```java
+@Select("SELECT * FROM {table_name} WHERE id = #{id}")
+EntityPO selectById(@Param("id") Long id);
+```
+
+XML Mapper 和注解 SQL 必须使用 `#{param}` 形式，严禁 `+` 字符串拼接。`${}` 仅可用于表名列名等不可参数化的位置，且值须白名单校验。
+
+**PO ↔ Domain 转换**：使用 MapStruct Converter（按项目 MapStruct 规范）
+
+## Apache POI
+
+**大文件流式读取**：
+```java
+SXSSFWorkbook wb = new SXSSFWorkbook(new XSSFWorkbook(inputStream), 100);
+```
+
+禁止直接用 `XSSFWorkbook` 加载全量数据（OOM 风险）。测试底稿放 `src/test/resources/`。导出使用 `XSSFComment` 添加批注、`XSSFCellStyle` 设置样式。
+
+## LangChain4j
+
+- API Key 从环境变量读取，见 security-baseline §凭证管理
+- 生产环境关闭请求/响应日志，见 security-baseline §日志脱敏 和 §LLM 调用安全
+- 调用超时默认 120s（Spring 配置见 application.yml）
+- 测试仅断言响应结构，见 security-baseline §LLM 调用安全
+
+## Spring 安全配置
+
+**文件上传**：
+- `spring.servlet.multipart.max-file-size` 限制文件大小，值按项目实际业务需求配置
+- Controller 层校验 MIME / Content-Type，见 security-baseline §文件上传安全
+
+**跨环境凭证一致性**（见 security-baseline §凭证管理）：
+- docker-compose 中的密码与 application-*.yml 中的密码必须一致
+- `.env` 不得提交仓库
+
+## SLF4J 日志脱敏
+
+- 参数化日志（SLF4J 语法）：`log.info("{} {}", user.getId(), action)`
+- 通用原则见 security-baseline §日志脱敏
+
+## 外部调用超时（Spring HTTP 客户端）
+
+- RestTemplate：通过 `SimpleClientHttpRequestFactory` 设 connectTimeout / readTimeout
+- WebClient：通过 `HttpClient.responseTimeout()` / `.option()` 设超时
+- Spring Cloud OpenFeign：`feign.client.config.<service>.connect-timeout` / `read-timeout`
+- 所有超时值 > 0，普通 HTTP 建议 10-30s
+- 通用原则见 security-baseline §外部调用超时与重试

package/assets/skills/java-technical-debt/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: java-technical-debt
+description: 仅限 Java 后端开发场景。Java 项目技术债识别（架构维度）——Spring 版本 EOL、javax→jakarta 迁移残留、双持久层并存、手写基础设施 vs 框架内置、临时方案固化、契约不一致（枚举 vs 数字码）等 Java 特有形态。通用技术债识别框架见 technical-debt。
+capabilities: ["architecture", "tech-stack-java"]
+---
+
+> **项目规范优先**：本 skill 所列约定为推荐标准。若项目已有明确规范且与本 skill 不一致，以项目规范为准。
+> 本 skill 是 technical-debt 的 Java 实现配套，仅含 Java/Spring 技术栈特有的债务形态。通用技术债识别框架见 technical-debt。调用本 skill 须同时加载 technical-debt。
+
+## 过时技术选型（Java 形态）
+
+- Spring Boot / Spring Framework 版本已 EOL（官方支持周期结束）仍在使用，且无升级计划
+- 框架/库级弃用 API 大面积使用——整个组件被官方替换（如旧版 Web 框架、旧缓存客户端、旧消息客户端），区别于单点方法 `@Deprecated`（单点 API 弃用不作架构债务，按维护性规范处理）
+
+## 技术迁移债（Java 形态）
+
+- javax → jakarta 迁移残留：代码中 `javax.*` 与 `jakarta.*` 混用，迁移只完成部分模块
+- Spring 大版本升级中断：项目声明目标版本但代码仍大量依赖旧版特性，升级中途停止
+
+## 平行实现与迁移缺失（Java 形态）
+
+- 双持久层并存：MyBatis 与 JPA 同时承载同类数据访问
+- 双消息框架并存：新旧消息客户端/中间件同时使用
+- 手写基础设施 vs 框架内置：手写限流/线程池/缓存等与 Spring 内置能力（Spring Cache、Resilience4j 等）功能重叠
+
+## 临时方案固化（Java 形态）
+
+- 临时 mock bean（`@Primary`/`@MockBean` 声明的临时代替 Bean）进入生产长期滞留
+- `@Profile` 临时 profile（mock/local 专用分支）长期保留且被生产路径依赖
+- 绕过分层直连的 hack：Service 直连 Mapper、Controller 直连 Repository/外部服务
+
+## 契约不一致与模型漂移（Java 形态）
+
+- 同一状态/类型字段一处为枚举、另一处为 Integer/String 数字码
+- 金额字段一处 BigDecimal、另一处 Double（精度不一致）
+- 时间字段一处 LocalDateTime、另一处 String 或 java.util.Date

package/assets/skills/orchestrator/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: orchestrator
+description: 编排主代理行为准则——身份定位、分派范式、禁止事项与无人值守行为约定。供承担编排者职责的主代理加载。
+capabilities: ["orchestrator"]
+---
+
+## 身份定位
+
+你是编排流程的主代理，唯一职责是分派子代理完成各阶段工作。
+
+你不亲自修改代码、不亲自审查、不亲自运行测试，也不向子代理转述动态上下文——所有子代理通过状态查询工具按角色路由自行获取所需上下文。
+
+## 行为准则
+
+- 每次子代理返回后，调用状态查询工具获取权威「下一步」指令并严格遵循；推进被拦时按工具给出的阻塞原因与修复建议处理，不自行推断其他动作
+- 分派/推进决策一律以工具返回为准：工具已给出明确分派指令时直接分派，不得先读状态文件交叉验证；仅门禁拒绝或工具给出修复建议时才读取状态文件核对
+- 分派子代理前先查询状态确认当前阶段/层，确保不跳阶段或错层分派；工具视图呈现 worktree 未就绪时不得分派
+- 不过度沟通：任务组内部不停下来向用户汇报，持续执行直到阻塞或完成
+- 断点续传：子代理因步骤限制中断后重新分派即可继续，无需保存已完成子任务列表
+- 工具列出多个子代理时并排分派（单条消息中同时发送），不串行等待
+- 分派前校验分派 prompt：按「禁止事项」中禁止转述的动态内容清单逐项检查，校验通过后再分派
+
+## 禁止事项
+
+- 禁止修改代码/文档（edit/write 权限已强制禁止）
+- **禁止自行阅读/探查被编排项目的业务源码**——收到子代理的 issue 反馈时不得用 read 或其他工具理解 issue 技术内容。issue 的理解与修复是子代理职责，编排者只负责按状态流转分派，不解读 issue 内容；read 仅限状态文件做状态交叉验证
+- 禁止代子代理提交 step 裁决——step 提交必须由对应子代理独立调用提交工具完成；仅检查点决策可由编排者执行推进
+- **禁止居中代问/代记 blocker 的用户答复**——需用户拍板的问题由对应子代理直接向用户确认（有人值守）或自行裁决（无人值守），编排者不转述答复、不代记
+- 禁止使用通用子代理代替专用审查子代理——各子代理角色按工具返回的分派指令确定
+- **禁止通过状态查询工具修正状态异常**——发现状态机不一致：有人值守向用户报告并暂停；无人值守按工具建议自动执行
+- **禁止向子代理转述动态上下文**（worktree 路径、执行边界、问题清单等）——这些信息已持久化，子代理通过状态查询工具自取；分派 prompt 仅包含分派指令 + 轮次/阶段标识 + `_agent` 身份指令（见分派范式）+ 必要时用户原话片段
+- **禁止在「下一步」已给出明确指令时改走恢复/重建或其他推断动作**——严格按「下一步」指令执行；有疑问：有人值守向用户报告并暂停，无人值守重新查询获取下一步
+- **禁止将状态查询返回内容判定为"输出被压缩/不完整"**——按角色渲染视图属正常设计，推进被拦时会显式给出阻塞原因与下一步，按视图指引执行
+
+## 分派范式
+
+分派子代理时，prompt 仅限以下模板，除 `_agent` 身份指令外严禁增减内容：
+
+```
+## 任务：<动词> — 任务组 <id> <轮次> — Change: <changeId>
+
+轮次：<N>/<MAX>  |  阶段：<phase>
+
+请调用 `opx_status(change_id="<changeId>")` 获取你所需的上下文，
+按本 agent md 中定义的规范执行，完成后调用 `opx_agent_submit` 提交。
+```
+
+子代理经 MCP 接入（非 OpenCode 直载形态）时，模板末尾追加一行 `_agent` 身份指令——角色名以分派指令中的 agent 名为准；不追加时子代理首次调用 `opx_status` 会按编排主代理视角返回，永远拿不到自身角色的执行视图：
+
+```
+请以 `_agent` 参数传自身角色名调用 `opx_*` 工具（`_agent: "<角色名>"`，如 `_agent: "openspec-developer"`）。
+```
+
+OpenCode 直载形态无需追加（工具按会话 agent 自动推导身份）。
+
+不包含任何 task/issue 明细、文件清单、执行边界具体值等动态内容——一切交给状态查询工具。
+
+## 无人值守行为约定
+
+无人值守模式下，所有需拍板事项由你依据工具返回与已加载 skill 的规范自行裁决，**不向用户提问**：
+
+- 检查点决策：按质量门覆盖度要求附结构化降级理由后直接提交推进，不暂停等待用户
+- 状态异常/门禁拒绝：按工具给出的建议自行修复或恢复，不中断流程
+- 子代理需要的用户确认类信息：由对应子代理依据其规范自行裁决处理
+- 推进动作全部按工具「下一步」指令执行，无指令时重新查询获取，不自作主张

package/assets/skills/quality-gate/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: quality-gate
+description: 确定性质量门框架——定义检查流程、统一 issue 结构、环境准备与降级。技术栈无关。
+capabilities: ["quality-gate"]
+# 机器可读必做清单：与下方「检查流程」表格 0~7 检查类别一一对应（8 降级口径、9 汇总产出属流程元项，不作为必做申报项）。
+# env=工具环境检查，compile=编译检查，format=代码格式检查，architecture=架构约束检查，
+# static_analysis=静态代码分析，unit_test=单元测试，coverage=覆盖率，deep_scan=深度扫描，config_check=质量工具配置检查。
+must_do: ["env", "compile", "format", "architecture", "static_analysis", "unit_test", "coverage", "deep_scan", "config_check"]
+---
+
+> **项目规范优先**：本 skill 所列约定为推荐标准。若项目已有明确规范且与本 skill 不一致，以项目规范为准。
+
+## 检查流程（概览）
+
+检查须按以下类别依次执行。每项不可跳跃——要么执行并报告结果，要么注明跳过理由：
+
+| 序号 | 检查类别 | 含义 |
+|------|---------|------|
+| 0 | 工具环境检查 | 确保运行环境就绪，不可用则降级 |
+| 1 | 编译检查 | 项目能否成功编译 |
+| 2 | 代码格式检查 | 是否符合代码风格标准 |
+| 3 | 架构约束检查 | 层间依赖、架构规则是否遵守 |
+| 4 | 静态代码分析 | 代码质量规则（复杂度、错误模式等）|
+| 5 | 单元测试 + 覆盖率 | 测试是否通过、覆盖是否达标 |
+| 6 | 深度扫描 | 扩展静态分析（规则数量更多）。工具若存在独立类别的输出（独立端点、独立指标），每类均须获取并纳入检查结果，禁止默认只取单一类别 |
+| 7 | 质量工具配置检查 | 质量门规则/配置未被弱化 |
+| 8 | 降级/无基线口径 | 无法按变更来源归类时，全量扫描结果按统一 issue 结构、原始严重级别产出检查结果与 issue 清单，不区分是否本轮引入 |
+| 9 | 汇总与产出 | 全部结果汇总为统一 issue 清单（含通过/不通过结论） |
+
+具体工具的检查命令和输出解析由各技术栈对应的 quality-gate skill 提供。
+
+## 0. 工具环境检查
+
+在执行工具检查前，先确保工具运行环境就绪。环境检查失败时先按自愈性步骤尝试恢复；不可自愈或自愈失败后，提请用户处理或裁定。用户裁定降级跳过时，在报告中注明降级理由，不阻塞其他检查。
+
+所有环境检查结果在报告中如实记录工具可用状态。具体处理方式由审查者按当前上下文判定。
+
+## 1-6 确定性检查
+
+每项检查的结果处理原则：
+
+- **通过**：正常记录结果
+- **不通过**：生成统一结构 issue，阻塞 task 完成
+
+## 失败定位
+
+构建/检查失败时，失败的完整输出文本是定位全部失败项的唯一可靠依据；仅依据报错尾部数行做出修复决策会导致全量问题被遗漏并触发反复重试，视为不合规的故障处理方式。
+
+## 7. 质量工具配置检查
+
+检查本轮变更中是否包含质量工具规则/配置文件的改动。若包含，逐项检查：
+
+- 规则是否被删除或降级
+- 是否新增了过宽的 exclude/include 配置
+- 质量工具插件配置是否被弱化（跳过执行、降低阻塞等级）
+
+配置无削弱 → 通过；存在削弱 → 工具层 issue。
+
+## 8. 降级/无基线口径
+
+SCM 数据不可用或历史基线不可靠时，扫描结果无法按变更来源归类，此时全量扫描结果同样按统一 issue 结构、按原始严重级别产出检查结果与 issue 清单，不区分是否本轮变更引入。
+
+- 无法可靠归类的边界情况，按常规口径处理
+
+## 9. 工具输出 → 统一 issue 结构
+
+每个工具的输出必须翻译为统一 issue 结构：
+
+```json
+{
+  "file": "<相对路径>",
+  "line": <行号>,
+  "dimension": "style|architecture|performance|security|maintainability",
+  "severity": "Critical|High|Medium|Low|Info",
+  "description": "<问题描述>",
+  "suggestion": "<修改建议>"
+}
+```
+
+各技术栈的 quality-gate skill 定义各自工具的输出到 dimension 和 severity 映射关系。
+
+## 10. 汇总与产出
+
+全部检查完成后，产出检查结果与 issue 清单（含通过/不通过结论）。

package/assets/skills/security-baseline/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: security-baseline
+description: 数据安全通用审查基线。不限于所列维度。凭证管理、日志脱敏、注入防护、文件上传、LLM 调用安全、认证与会话、CORS、错误信息泄露、速率限制、XSS 输出编码。
+capabilities: ["security"]
+---
+
+> **项目规范优先**：本 skill 所列约定为推荐标准。若项目已有明确规范且与本 skill 不一致，以项目规范为准。
+> 本文列出**最低审查基线**，不限于所列维度。AI 审查时必须结合自身安全知识做拓展覆盖，下列任何可能遗漏的安全维度均须纳入审查。
+
+## 凭证管理
+
+- API Key / Token / 密码从环境变量或外部配置中心读取，禁止在代码、配置文件、注释中硬编码
+- 跨环境凭证一致性：dev/staging/prod 各环境的凭证须与对应配置文件一致
+- 敏感文件（.env / .secrets）不得提交仓库，已提交者立即轮换并移除
+- 定期轮换密钥，禁止使用默认/弱凭据
+- API Key / Token / 敏感标识通过 HTTP Header（`Authorization` / `X-API-Key`）或 Body 传递，禁止通过 GET 查询参数传递（防日志泄露、URL 缓存、Referrer 外泄）
+
+## 日志脱敏
+
+- 禁止在日志中输出：密码、Token、API Key、身份证号、手机号、银行卡号等 PII 和认证凭据
+- 生产环境关闭请求/响应详细日志（如 LLM 调用的 log-requests / log-responses）
+- 使用参数化日志 API 构造日志消息，禁止字符串拼接引入敏感数据
+- 审计日志须脱敏后落盘
+
+## 外部调用超时与重试
+
+- 所有 HTTP / LLM / 消息队列 / RPC 调用必须有超时配置，不允许无超时的阻塞等待
+- 循环内同步外部调用必须在循环层级之上做批量聚合或异步并发；循环内逐条同步调用视为 High 级别问题
+- 外部调用须有重试策略（含退避与熔断），避免无限制重试
+
+## 文件上传安全
+
+- 限制上传文件大小，配置级别限流
+- 按项目实际需求校验 MIME / Content-Type，不准使用与项目无关的硬编码白名单
+- 上传接口对外暴露时必须有鉴权，内部接口也应有来源校验
+- 文件存储路径须防路径遍历（使用随机名或用户 ID 隔离，不使用用户传入文件名）
+- 上传文件存入非执行目录，防止 RCE
+
+## 数据访问注入防护
+
+- 所有 SQL / NoSQL / GraphQL 查询必须使用参数化绑定或预编译 API，严禁字符串拼接
+- 白名单校验 + 参数化 API 双重防御，不依赖黑名单/转义
+- 批量查询或 JOIN 替代循环内逐条查询（N+1 防范）
+- 状态/类别等确定性标记优先使用枚举映射，不在业务代码中判断魔数
+
+## LLM 调用安全
+
+- API Key 从环境变量读取，禁止硬编码
+- 生产环境关闭 prompt/response 详细日志
+- 调用必须有超时配置；循环内调用 LLM 必须异步或有超时保护
+- 自动化测试仅断言响应结构（JSON schema / HTTP status），不断言 LLM 输出内容
+- 防 prompt injection：不将用户输入直接拼入 system prompt，对用户消息做输入边界隔离
+
+## 认证与会话安全
+
+- JWT：签名密钥强度合规，token 有过期时间，payload 不存放敏感数据
+- cookie-based auth 必须启用 CSRF 防护
+- 会话有超时策略（空闲超时 + 绝对超时）
+- 认证凭据不出现在 URL 参数、日志、response body 中
+- 密码传输必须加密（HTTPS），存储须加盐哈希
+- 登录/OTP 类端点禁止暴露用户存在/不存在差异（枚举攻击防护）
+
+## CORS 与安全响应头
+
+- CORS：不允许 `Access-Control-Allow-Origin: *` 与凭据（credentials: include）同时使用
+- 至少配置：`X-Content-Type-Options: nosniff`、`X-Frame-Options: DENY/SAMEORIGIN`、`Content-Security-Policy`
+- 默认拒绝，白名单放行特定 origin
+
+## 错误处理与信息泄露
+
+- 生产环境禁止输出 stack trace、SQL 语句、内部文件名路径等内部结构信息
+- 统一错误响应体，不暴露用户是否存在、数据库结构等枚举信息
+- 调试接口、管理接口、Swagger UI 在生产路由不得注册
+
+## 输入校验（跨注入类型）
+
+- 系统性覆盖各注入面：SQL 注入、命令注入（Shell 拼接）、路径遍历（文件路径拼接）、模板注入、NoSQL 注入
+- 统一防御原则：白名单校验 + 安全 API（参数化/转义），不依赖黑名单
+- 输入长度限制，对数值、枚举、文件扩展名等字段采用白名单校验
+
+## 速率限制
+
+- 登录、注册、密码重置、OTP 验证等认证类接口必须限流
+- 通用 API 建议按用户/资源维度限流，防批量爬取
+- 限流触发后返回 429 + Retry-After 头
+
+## 输出编码（XSS 防护）
+
+- 数据出站时按输出上下文做编码：HTML entity、JS 字符串、URL、CSS 上下文各有不同
+- 禁止将用户可控内容直接拼入 HTML / XML / JavaScript / CSS 输出
+- 文件下载 Content-Disposition 中的文件名须过滤或编码，防反射 XSS
+- JSON API 响应中的字符串须做上下文安全编码
+
+## 第三方依赖安全（SCA）
+
+- 定期扫描项目依赖中的已知漏洞（CVE），纳入 CI/CD 流水线
+- SCA 工具拦截 High+ 级别的漏洞引入，阻塞构建
+- 维护软件物料清单（SBOM，SPDX/CycloneDX 格式），随发布物归档
+- 防范 Dependency Confusion 攻击：私有包注册源优先于公共源，名称冲突时阻断构建
+- 依赖许可合规检查（GPL/AGPL 等传染性许可评估），按项目开源策略执行
+- 禁止引入已弃用或不再维护的依赖

package/assets/skills/technical-debt/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: technical-debt
+description: 项目技术债识别（架构维度）——过时技术选型、技术迁移债、平行实现与迁移缺失、临时方案固化、契约不一致与模型漂移五类债务的识别信号、判据、利息评估与处置分级。技术栈无关。
+capabilities: ["architecture"]
+---
+
+> **项目规范优先**：本 skill 所列约定为推荐标准。若项目已有明确规范且与本 skill 不一致，以项目规范为准。
+> 本文列出**架构维度技术债识别的最低基线**，不限于所列维度。AI 审查时必须结合自身架构知识做拓展覆盖。
+
+## 定位
+
+本 skill 是架构维度的技术债识别框架——识别债务、评估利息（代价）、给出处置分级。只覆盖架构维度可归口的债务类型，不替代各维度规范：识别出的问题按各维度规范归口，同一问题不在多个维度重复报。
+
+### 归口边界
+
+| 债务信号 | 归口 |
+|---------|------|
+| 测试债（缺测试、断言放水、覆盖空洞） | 测试与行为验证职责 |
+| 代码级重复、死代码、魔法数、结构债（方法长度、类职责）、未使用的依赖 | maintainability 维度 |
+| 性能债（N+1、缓存缺失、异步滥用） | performance 维度 |
+| 安全债（含 EOL 组件的已知安全漏洞） | security 维度 |
+| 本次变更引入且未生效的 stub/降级（仅打状态标记未实际生效） | 行为真实性验证职责 |
+| 长期滞留的存量临时方案（已生效但为临时代替/降级形态） | 本 skill（临时方案固化） |
+
+## 债务类型
+
+### 过时技术选型
+
+采用已 EOL（End of Life）或被官方弃用的框架、中间件、核心库，或选型决策遗留导致升级成本随时间递增。
+
+- 识别信号：框架/中间件/核心库版本已停止官方支持；官方宣布弃用并给出替代路线；新代码继续基于将被替换的技术栈编写
+- 判据：官方支持周期已结束或明确宣布弃用，项目仍长期停留在旧版本且无升级计划
+- 利息：安全漏洞无官方修复、新特性缺失、升级成本随时间递增
+- 处置：采用 EOL/弃用技术选型且无升级计划 → 至少 Medium 级别 issue
+
+### 技术迁移债
+
+技术栈级新旧并存与迁移中断残留——跨大版本迁移中途停止、新旧技术栈并行运行、迁移只完成部分模块。
+
+- 识别信号：同一技术栈两种大版本并存；迁移后的模块与迁移前模块并行运行；迁移中断留下的过渡状态
+- 判据：存在明确的目标技术栈（迁移方向），但存量仍以旧技术栈运行且无完成计划
+- 利息：双轨维护成本、行为不一致风险、迁移中断越久重启成本越高
+- 处置：迁移中断且无完成计划 → 至少 Medium 级别 issue
+
+### 平行实现与迁移缺失
+
+同类能力多套方案并存且无迁移方案——引入与既有实现功能重叠的新实现且不改动原实现，同类能力多套方案并存。
+
+本类债务从识别与分级视角描述；方案层面引入新实现时的复用与迁移要求属方案规范约束，识别与要求分工互补，不在本 skill 重复。
+
+- 识别信号：同类能力存在 ≥2 套实现；新引入实现与既有实现功能重叠；新旧并存无迁移方案
+- 判据：同类能力已有既有实现仍另建实现；并存状态无迁移方案
+- 利息：维护与认知成本翻倍、修复不同步、新增场景遗漏调用
+- 处置：平行引入且无迁移方案 → 至少 Medium 级别 issue
+
+### 临时方案固化
+
+架构级临时方案长期滞留——绕过分层直连、应急 hack、stub 降级形态进入生产且无跟进。
+
+- 识别信号：绕开架构约束的直连/hack；临时 stub 或降级形态已进入生产；带临时标记但长期未跟进
+- 判据：明确标记为临时但滞留超过合理周期；或长期以临时形态运行且无替代计划
+- 利息：行为偏差风险、架构一致性破坏、后续变更在此之上叠加
+- 处置：临时方案长期固化 → 至少 Medium 级别 issue
+
+### 契约不一致与模型漂移
+
+同一业务语义的数据字段在不同接口/模块间类型或表达不一致——如某接口以枚举表达状态，另一接口以数字码表达同一状态，调用方需维护两套认知与转换。
+
+单点字段类型选型不当（单一接口内字段类型/表达的选择问题）属命名与通用语言约定范畴；跨接口/模块表达不一致才归本类债务。
+
+- 识别信号：同一语义字段在不同接口/模块的 DTO 中类型不一致；同一状态/类型概念有多种表达形态（枚举/数字码/字符串）；跨接口取值需额外转换逻辑
+- 判据：同一业务语义存在 ≥2 种表达形态且无统一计划
+- 利息：调用方认知与转换成本、语义漂移风险（数字码与枚举映射歧义）、新增接口易沿用错误形态
+- 处置：契约不一致且无统一计划 → 至少 Medium 级别 issue
+
+## 存量债务处置
+
+存量（非本轮引入）技术债与新增债务同等识别，不得因非本轮引入而沉默丢弃。存量可识别债务 → 至少 Low+ 级别 issue；纯建议性优化 → Info。

package/assets/workflows/task.yaml

@@ -0,0 +1,177 @@
+# task workflow：OpenSpec change 的通用任务流转
+# 对应现有编排阶段：分析（todo）→ 实现（in_progress）→ 三重审查+收尾验证（review）
+# 语义归属：step 级 instructions/constraints 定义各 step 专属语义；
+# 跨所有 step 共享内容收敛到顶层 common（step 自动继承）；非 step 归属的引擎状态文案不进配置。
+# 占位符 {{key}} 经 interpolateText 注入动态值，缺值保留原文。
+id: task
+name: Task Workflow
+max_retries: 10
+
+# 跨所有 step 共享的通用指引/约束：渲染时 common 在前、step 在后合并进对应视图区块
+common:
+  instructions:
+    - "非 OpenCode 直载形态（经 MCP 接入的 agent 客户端）调用 opx_* 工具时，须携带 `_agent` 参数并传自身角色名（如 openspec-developer）；缺省会被视为编排主代理视角，将拿不到自身角色的执行视图与操作指引"
+    - "调用 opx_status 获取动态上下文（{{worktree_path}}、变更范围、上轮会话摘要）"
+    - "按 Skill 加载清单加载匹配的 skill 并遵循其全部规范"
+    - "读取 `{{worktree_path}}/openspec/changes/{{change_id}}/` 下的相关文档：tasks.md（任务清单，按行内 `[spec:xxx]` 溯源定位 specs/ 下相关 spec.md）、design.md、proposal.md"
+    - "阅读 `{{worktree_path}}/AGENTS.md` 项目规范"
+    - "需要外部框架/工具的权威文档（规则语义、API 用法、配置说明）时，优先通过文档检索渠道获取，禁止直接翻源码"
+    - "完成后调用 opx_agent_submit 提交裁决或失败上报"
+  constraints:
+    - "所有 edit/write 操作限定在 {{worktree_path}} 内，严禁修改主仓库路径下的文件"
+    - "禁止为获取外部框架/工具的规则语义、API 用法等知识而解析其源码、jar 包或执行 AST dump；此类知识一律通过文档检索渠道获取；声明式规则定义来源（规则定义 XML 直拉、工具官方 Web API 返回、官方文档页）属于文档检索渠道范畴"
+    - "不跳步骤、不自行推断阶段流转，next-step 以 opx_status 为准"
+    - "禁止调用任何 opx_orch_* 工具（编排者专属）"
+    - "以视图「变更范围」命令产出的文件清单作为本次工作范围"
+
+phases:
+  - name: todo
+    steps:
+      - id: analyze
+        agents:
+          - id: openspec-architect
+            capability_tags: [architecture, api-design, db-design, efficiency]
+        transitions:
+          on_pass: implement
+          on_fail: analyze
+        instructions:
+          - "校验 design.md 与 tasks.md、specs/ 下相关 spec.md 的一致性（据 tasks.md 各行 `[spec:xxx]` 溯源定位相关 spec.md 一并复核）"
+          - "按评估维度逐项审查 design.md 并给出结论：architecture / api-design / db-design（无问题也需简要确认），不以假设替代确认"
+          - "校验设计文档与任务前提的一致性，评估架构模式合规性"
+          - "输出执行边界：allowed_directories（含测试目录）与 allowed_packages 白名单，notes 仅填实施建议（关键坑位/组件复用/边缘场景/框架应用/通用做法），不重复目录与包路径，无补充时留空"
+          - "存在缺口时提交 blocker（category: architecture_design / info_gap），不以假设替代确认"
+          - "需用户拍板的问题由你直接确认，不提交用户确认型 blocker：有人值守时用 question 工具向用户提问（拿到答复当场继续，不留档）；无人值守时（依据视图「确认模式」标识）自行选择最优解继续。确认/裁决后当场继续执行，本轮未干完下一轮重新确认"
+          - "存在未解决 blocker 时无法以 passed 提交，先经 blocker_updates 逐条置 resolved（user_response 填确认/裁决结论）后再提交"
+          - "提交 opx_agent_submit，必传参数 execution_boundary"
+        constraints:
+          - "工具调用边界：仅可调用 opx_status、opx_agent_submit、question（需用户拍板时使用）"
+          - "只审当前任务组范围：除任务排列是否合理需阅览全部任务组标题外，其它检查聚焦当前任务组直接相关的文档章节；评估整体架构契合与重构历史逻辑贴合时，可阅览项目整体结构与既有实现建立架构脉络（不含其它任务组设计文档），审查结论仍聚焦当前方案，不扩散为对既有代码的全面审查"
+          - "仅可 edit 修复 md 文档；设计/架构验证问题与信息缺口一律走 blocker"
+  - name: in_progress
+    steps:
+      - id: implement
+        agents:
+          - id: openspec-developer
+            capability_tags: [efficiency, api-testing, quality-gate, dev-practices, db-design, style, architecture, performance, security, maintainability]
+        transitions:
+          on_pass: verify_tool
+          on_fail: analyze
+        instructions:
+          - "tasks.md 当前任务组任务项 + `[spec:xxx]` 溯源 specs/ 下相关 spec.md（需求细节与验收标准）；存在时读取 clarify.md（架构方向结论）"
+          - "按 Task 项顺序逐个实现，聚焦当前子任务，不超出执行边界"
+          - "实施前识别 spec 描述的一并操作行为组（如状态变更与数据入队这类需同时发生的多个行为）；实施后逐项自证每个行为真实生效，禁止以单一状态字段的实现替代其他行为"
+          - "环境/基础设施问题（schema 缺失、DDL 未执行、依赖未安装）应通过 migration/初始化脚本等代码层面解决；仅生产级凭据、真实第三方资源、人工运维才走 blocker/豁免"
+          - "issue 指向文件的目录已并入执行边界，修复这些文件（含回归引入问题）不算越界；issue 的 file 字段指向 openspec/changes/ 下文档时，按该 issue 要求修复对应文档同样不算越界（仅限该 issue 指定文件，不得扩大范围）；可按 issue 的 suggestion 直接执行修复；reviewer 的 boundary_expansion 已并入边界"
+          - "按视图 Issue 清单分类实施：Low+ 必办，Info 建议修复不阻塞提交"
+          - "对修复未过次数≥2 的 issue 须先完成 5-Why 根因分析再动手，不得跳过分析直接改代码"
+          - "全部实现完成后先 git commit 再提交"
+          - "提交前按已加载的质量门类 skill 完成本地构建验证并核对覆盖率门禁达标后再提交"
+          - "提交前完成自检并经 self_check_results 汇总"
+          - "提交前按已加载的维度规范类 skill（style/architecture/performance/security/maintainability 能力类别）对本次变更文件逐项自检（聚焦本轮变更文件，不扩散全量代码），自检结论与工具检查结果一并汇总进 self_check_results；修复被驳回 issue 后再次提交前同样须按维度规范类 skill 对变更文件自检后再提交"
+          - "自检须覆盖已加载的维度规范类 skill 的全部检查点，self_check_results 按维度逐项列结论（通过/遗留及理由），禁止仅汇总工具检查结果"
+          - "修复完成的 issue 经 fixed_issue_ids 上报后进入待复核（review）状态，终态由对应 reviewer 复核裁定；不可修 issue 经 exempt_issue_ids 申请豁免（申请后进入待裁定（review）状态，由报源 reviewer 在后续审查轮次裁定，被驳回的 issue 回待修复）；Info 级 issue 不阻塞提交，无需申请豁免；全部 blocking issue 均已上报修复或申请豁免后才可 passed 提交推进"
+          - "遇外部依赖、凭证、真实输入或必须 stub/降级/跳过验收才能继续时，以 verdict=failed 提交 blocker（含 source_role、task_id、category、description、evidence、attempted_actions、options）"
+          - "提交 opx_agent_submit：passed 时存在未完成或被驳回（open/rejected）的子任务必须全部列入 completed_task_ids（数字 id 如 1、2，或任务编号如 1.1），全部子任务已验证时可省略；不可修 issue 申请豁免（exempt_issue_ids）"
+        constraints:
+          - "禁用 edit/write 修改 `{{worktree_path}}/openspec/changes/` 下任何文档（spec/design/tasks/clarify）；唯一例外：所提交 fixed_issue_ids 中某 issue 的 file 字段指向该目录下文档时，仅允许按该 issue 的要求修改对应文档，不得扩大范围；本约束为提示词级约束，工具层不校验实际改动的文件"
+          - "允许变更目录范围：{{allowed_directories}}"
+          - "允许引用包范围：{{allowed_packages}}"
+          - "实施前请注意遵守：{{notes}}"
+          - "生产路径禁止 stub/fake/空实现/硬编码成功"
+          - "提交前自检必须覆盖已加载的全部 skill（含维度规范类）检查点，不得以工具检查结果替代维度规范自检"
+          - "需以 verdict=failed + blocker 上报的条件：需求模糊 / design 问题 / 技术阻塞 / 超出执行边界"
+          - "禁止以 SonarQube 平台状态修改（SAFE/WONTFIX/False Positive/Confirmed 等）作为豁免手段：平台状态仅作用于当前 SonarQube 项目实例，每次 change 使用独立项目 key，不跨 change 生效；存量问题跨 change 豁免必须经 exempt_issue_ids 申请 → 报源 reviewer 裁定 dismissed 的流程"
+  - name: review
+    steps:
+      - id: verify_tool
+        agents:
+          - id: openspec-reviewer-tool
+            capability_tags: [quality-gate, efficiency, api-testing]
+        transitions:
+          on_pass: verify_task
+          on_fail: implement
+        instructions:
+          - "依据 opx_status 提供的变更检测结果分流：无代码/配置变更且本层无待复核/待裁定项 → 直接提交 passed，不运行全量工具检查，并以一条 step 名首段为 no_change 的 validation_steps 声明本轮整体豁免必做清单（completed=false + 结构化 skip_reason 注明判定依据）；无变更但有本层待复核/待裁定项 → 仅复核/裁定待处理项后提交，不跑全量工具扫描；有变更 → 加载质量门类 skill 获取工具清单与映射规则，按已加载质量门 skill 必做清单逐项执行全部确定性工具检查（代码格式/架构约束/静态分析/单元测试编译/深度扫描——按必做清单中的对应项逐项执行并逐项申报），将工具输出映射为统一 issue 结构后提交"
+          - "「有变更」分支先审查上方「本次变更证据」区块的变更文件清单与区间 diff 内容后自行判断：若确认本次变更仅为注释/文档性且无逻辑影响（非注释掉代码、非结构性/格式化变更、非文件重命名），可自行决定跳过全量工具检查直接提交 passed（validation_steps 以 step=no_change 申报整体豁免必做清单）；无法确认或含逻辑/结构变更，必须顺序运行全部确定性工具检查；裁量仅免除全量工具扫描，不免除复核/裁定——本层 blocking issue 仍须处理至终态后提交"
+          - "报 issue 时必须显式声明归因维度 dimension（style/architecture/performance/security/maintainability）：本 reviewer 不归属任一质量维度，dimension 即该 issue 归属的目标质量维度"
+          - "无变更直提分支不执行全量工具扫描，该分支下存量工具违规不重复扫描；实质代码/配置变更必须按全量覆盖：工具检查覆盖全量代码，非本轮变更文件的工具违规同样映射为 issue 提交，禁止因非本轮引入静默丢弃；仅注释/文档性变更（经审查确认）可免全量工具检查；命中项目级豁免清单（视图标注）的存量问题按 Info 提报，不重新豁免，其余非本轮引入问题仍按原严重级别上报"
+          - "当发现修复需要调整 openspec/changes/ 下文档时，所报 issue 的 file 字段必须指向目标文档"
+          - "复核本层已修复待复核（review 态）issue：通过置 done，不通过驳回（附驳回原因，issue 回待修复并累计修复未过次数）"
+          - "对视图「待裁定是否可豁免」区块中的豁免申请经 exempt_adjudications 裁定（dismissed/rejected）"
+          - "提交 opx_agent_submit，必带 verdict 参数（passed / failed）"
+          - "validation_steps 必须按已加载质量门 skill 必做清单逐项申报（completed=true 附执行结果；无法执行的必做项置 completed=false，并以结构化 skip_reason 申报降级理由，格式：{\"item\":\"<必做项>\",\"category\":\"<降级类别>\",\"adjudication\":\"user_response|unattended_auto|env_unavailable\",\"note\":\"<说明>\"}）；遗漏必做项或缺结构化降级理由的 passed 提交会被提交门禁拒绝"
+          - "报静态分析类 issue 时，rule 字段必填官方规则全名（命名格式遵循已加载的质量门类 skill 的规则导航索引），漏填将导致项目级豁免清单无法生效"
+          - "报静态分析类 issue 时，description 必须含：①复现命令（非静默形态，含必要开关）；②实测数据（命中类清单/计数）；③规则默认阈值与当前项目配置对比（引用可改的配置文件路径）"
+        constraints:
+          - "工具调用边界：仅可调用 opx_status、opx_agent_submit、question（需要用户协助处理时）；可 bash 运行工具但不得 edit/write 任何文件"
+          - "即使无 issue 也必须提交 verdict=passed（不通过必须有至少一个 Low+ issue 作为理由）"
+          - "Info 级 issue 的 description/suggestion 禁止阶段/时机表述（如'可后续处理'）"
+          - "禁止以 SonarQube 平台状态修改（SAFE/WONTFIX/False Positive/Confirmed 等）作为豁免手段：平台状态仅作用于当前 SonarQube 项目实例，每次 change 使用独立项目 key，不跨 change 生效；存量问题跨 change 豁免必须经 exempt_issue_ids 申请 → 报源 reviewer 裁定 dismissed 的流程"
+      - id: verify_task
+        agents:
+          - id: openspec-reviewer-task
+            capability_tags: [api-testing, efficiency, dev-practices]
+        transitions:
+          on_pass: verify_quality
+          on_fail: implement
+        instructions:
+          - "逐项验证：①task 产出完整性 ②启动服务并检查健康 ③独立执行全量 API 测试并审查质量（含 API 测试自闭环链路：创建后可检索、状态变更后可见、删除后不可见；测试数据贴近业务语义，禁止无意义占位值） ④审查测试代码质量（断言放水/Mock 过度/覆盖不足）⑤业务行为真实性：对照 spec 逐项核验每个业务行为的实现与断言证据（含一并操作的行为组、连带效果、下游消费），识别『仅打状态标记未实际生效』类缺陷"
+          - "本次变更仅含测试代码（判定：视图「变更范围」文件清单全部命中已加载技术栈 skill 定义的测试代码路径，且无生产代码、接口契约、构建与测试配置等非测试文件）时，豁免②启动服务并检查健康与③独立执行全量 API 测试，仅验证①④；豁免时 validation_steps 中②③置 completed=false，并以结构化 skip_reason 申报（格式：{\"item\":\"<对应验证项>\",\"category\":\"<降级类别>\",\"adjudication\":\"user_response|unattended_auto|env_unavailable\",\"note\":\"<说明>\"}），note 注明「本次变更仅含测试代码，豁免启动服务与 API 测试」及判定依据；⑤的实现核验在纯测试代码变更场景无对象，其断言证据核验并入④测试代码质量"
+          - "读取 design.md 的 API 定义（请求/响应结构、数据模型）与 specs/ 下相关 spec.md（需求细节与验收标准），用于准备测试数据与对照 API 合约"
+          - "有 task 未通过时必须 verdict=failed 并经 failed_tasks 上报（task_id + reason）；passed 时不允许提供 failed_tasks"
+          - "当发现修复需要调整 openspec/changes/ 下文档时，所报 issue 的 file 字段必须指向目标文档"
+          - "报 issue 时必须显式声明归因维度 dimension（style/architecture/performance/security/maintainability）：本 reviewer 不归属任一质量维度，dimension 即该 issue 归属的目标质量维度"
+          - "复核本层已修复待复核（review 态）issue：通过置 done，不通过驳回（附驳回原因，issue 回待修复并累计修复未过次数）"
+          - "对视图「待裁定是否可豁免」区块中的豁免申请经 exempt_adjudications 裁定"
+          - "按 opx_status 操作指引完成全部验证项，提交前将每项验证结果与证据填入 validation_steps 参数（未执行的项须填 skip_reason 注明原因），不得省略任何一项"
+          - "提交 opx_agent_submit，必带 verdict 与 verified_tasks（覆盖全部待验证 task）"
+        constraints:
+          - "工具调用边界：仅可调用 opx_status、opx_agent_submit；可 bash 启动服务/执行检查，但不得 edit/write 业务代码"
+          - "即使无 issue / 无待验证 task 也必须提交 verdict=passed（不通过必须有至少一个 Low+ issue 作为理由）"
+      - id: verify_quality
+        agents:
+          - id: openspec-reviewer-style
+            capability_tags: [style, efficiency, tool-improvement]
+          - id: openspec-reviewer-architecture
+            capability_tags: [architecture, efficiency, tool-improvement]
+          - id: openspec-reviewer-performance
+            capability_tags: [performance, efficiency, tool-improvement]
+          - id: openspec-reviewer-security
+            capability_tags: [security, efficiency, tool-improvement]
+          - id: openspec-reviewer-maintainability
+            capability_tags: [maintainability, efficiency, tool-improvement]
+        transitions:
+          on_pass: verify_cleanup
+          on_fail: implement
+        instructions:
+          - "加载匹配维度 skill，以本轮 diff/变更文件为锚点结合 skill 规范与领域知识做拓展审查（skill 仅为最低基准）；顺带发现的非本轮缺陷按本维度严重级别标准报 issue，禁止静默丢弃"
+          - "审查新 issue 前先查看视图「待复核」区块中的既有 issue（仅本维度报源），避免语义重复"
+          - "当发现修复需要调整 openspec/changes/ 下文档时，所报 issue 的 file 字段必须指向目标文档"
+          - "报本维度新 issue 前先判断该问题能否通过调整确定性质量扫描工具配置（规则收紧/新增规则/配置增强）统一收敛：可工具化 → 双报业务 issue（file=违规现场）与工具改进 issue（file=规则/配置文件，suggestion 含规则草案+验证命令，末尾标 [tool_eligible]，且与业务 issue 同维度），两条 file 不同、方案不同，不构成语义重复，必须双报；工具改进 issue 目标文件在执行边界外时附 boundary_expansion（仅 verdict=failed 时可附）；不可工具化 → 仅报业务 issue。工具化判断细节与规则草案模板遵循已加载的工具改进类 skill，未加载工具改进类 skill 时仅报业务 issue、跳过工具改进环节；提交时在 validation_steps 中记录工具化判断结论"
+          - "复核自己报的本维度已修复待复核（review 态）issue：通过置 done，不通过驳回（附驳回原因，issue 回待修复并累计修复未过次数）"
+          - "对视图「待裁定是否可豁免」区块中的豁免申请经 exempt_adjudications 裁定（dismissed/rejected）"
+          - "提交 opx_agent_submit，必带 verdict 与 validation_steps（验证步骤执行摘要）"
+        constraints:
+          - "禁止运行确定性工具检查（包括但不限于 linter/formatter/静态分析/编译/测试/架构约束检查等）；运行权归 tool review 层，本约束不排斥基于已加载 skill 做工具化可行性判断并提交工具改进 issue"
+          - "工具调用边界：仅可调用 opx_status、opx_agent_submit；不得 edit/write 任何文件，仅输出审查报告"
+          - "即使无 issue 也必须提交 verdict=passed；passed=false 时必须有至少一个归属本维度的 Low+ issue 作为理由"
+      - id: verify_cleanup
+        agents:
+          - id: openspec-developer
+            capability_tags: [cleanup, api-testing, dev-practices, efficiency]
+        transitions:
+          on_pass: done
+          on_fail: verify_cleanup
+        instructions:
+          - "将基准分支（{{base_branch}}）最新代码合并进当前工作分支（git merge 基准分支），解决合并冲突；修复范围仅限合并冲突涉及文件与回归失败定位文件（改动仅用于解决合并引入的问题，可超出现有执行边界，禁止借机扩大范围）"
+          - "合并后回归复验：按已加载的开发实践规范执行构建验证；按已加载的接口测试规范启动服务并执行接口测试；全部通过才算通过，不分失败来源（含基准分支新代码引入的失败）"
+          - "按已加载的清理规范执行幂等清理：停止残留的服务实例、清理本 change 的隔离环境、删除残留的扫描分析项目；无对应 skill 规范时跳过并在申报中注明"
+          - "清理后确认工作分支 git status 干净（含未跟踪文件）"
+          - "逐项申报 validation_steps（completed + 证据；未执行项以 completed=false + 结构化 skip_reason 申报：{\"item\":\"<必做项>\",\"category\":\"<降级类别>\",\"adjudication\":\"user_response|unattended_auto|env_unavailable\",\"note\":\"<说明>\"}）"
+          - "自报 issue 必须在本 step 内收敛至终态（修复后自行复核通过，或申请豁免后自行裁定）后再提交；报 issue 时显式声明归因维度 dimension（该维度仅作归因标签，不代表对应维度 reviewer 会复核此 issue）"
+          - "存在无法解决的残留或回归失败 → verdict=failed 并报 Low+ issue（显式声明归因维度 dimension）"
+          - "完成后调用 opx_agent_submit 提交裁决"
+        constraints:
+          - "可 bash 执行构建/测试/清理命令；禁止 edit/write 任何 {{worktree_path}} 之外的文件"
+          - "工具调用边界：仅可调用 opx_status、opx_agent_submit、question"
+          - "禁止提报与收尾验证无关的 issue"