@namewta/speculo 1.0.22 → 2.0.1

package/template/workflows/specdev/specdev-t-tickets/references/planning-procedure.md

@@ -0,0 +1,235 @@
+# 拆分 Tickets
+
+
+Ticket 是**决策完备的微型执行计划**：它消除执行者在目标、范围、公共契约、关键顺序和验收上的关键决策，但不展开逐行代码、局部变量或可从现有惯例自然推导的实现细节。
+
+本 work 保留原有能力：代码库探索、prefactor 识别、曳光弹垂直切片、真实阻塞边、用户粒度核对、宽重构的 expand-contract 排序、Ticket 独立文件和总体 Tickets Map。
+
+
+## 输入
+
+优先读取：
+
+- 当前 Spec：`<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
+- 当前架构决策：`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
+- 当前领域上下文：`<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`
+- 当前设计日志：`<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`
+- Bug 诊断：`<Path>{roots.state}/specdev/changes/{change}/diagnosis.md</Path>`
+- 永久架构决策：`<Path>{roots.state}/specdev/adr/</Path>`
+- 永久领域上下文：`<Path>{roots.state}/specdev/context/</Path>`
+- 项目 Agent 指令及其声明的项目 Skill 根；
+- 项目当前代码、测试、配置、schema 和 CI 事实。
+
+若尚无 `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`，只有在用户提供的计划或对话已经等价覆盖目标、范围、关键决定和可判定验收时才可继续；否则建议先运行 `<Path>{roots.workflows}/specdev/specdev-s-spec/SKILL.md</Path>`。
+
+## 流程
+
+### 1. 输入预检
+
+1. 先读取上游工件索引，按当前 Ticket 的依赖、缺口和冲突关键词定位，再回读相关工件；
+2. 检查 `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>` 的 `ready_for_tickets`；
+3. 按 `<Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>` 处理 Spec、ADR、用户决定与代码事实的冲突；
+4. 将未知项分类为可发现事实、高影响用户决定和低影响实现细节；
+5. 高影响未决问题没有关闭时停止，不通过更详细的 Ticket 文字伪装决策完备。
+
+**完成标准**：拆分依据、权威顺序、合同范围与未决问题已明确。
+
+UI 范围同时读取 <Path>{roots.workflows}/specdev/common/rules/design-contract.md</Path> 与 <Path>{roots.state}/specdev/changes/{change}/DESIGN.md</Path>，核对批准、revision/digest、基线、prototype 和页面/状态。每张 UI 票以 `design_ref` 绑定所负责的 pages/acceptance，不能复制一份可独立修改的视觉规则。设计缺失或漂移先返回 P。
+
+### 2. 探索代码库与实现地形
+
+如果尚未探索，进行只读探索：
+
+- 找到行为入口、稳定接口、测试接缝、数据流和错误路径；
+- 查找相邻或类似实现，优先复用项目现有模式；
+- 识别可能修改的模块、公共路径、共享文件、迁移索引和全局注册点；
+- 查找现有测试命令、夹具、类型检查、构建和 CI 门禁；
+- 对照 `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>` 使用项目领域词汇；
+- 对照 `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>` 与 `<Path>{roots.state}/specdev/adr/</Path>` 避免重新争论已接受决策。
+
+遇到不熟悉的模块、外部依赖或第三方库时，使用 `<Path>{roots.workflows}/specdev/common/skills/research/SKILL.md</Path>`，再继续拆分。
+
+#### 项目 Skill 路由
+
+1. 读取项目 Agent 指令，确定项目声明的 Skill 根；至少枚举 `<Path>.agents/skills/**/SKILL.md</Path>`，存在其他项目级 Skill 根时一并枚举；
+2. 先读取候选 Skill 的 frontmatter 与入口路由；只有命中当前 change 的 scope、路径、技术域或验证条件时才完整读取，并按其 Skill Map 路由到当前 change 需要的领域 Skill；
+3. 根据 change 索引、每个 Ticket 的 frontmatter、路径、技术域、公共契约、迁移与验证范围，确定 `ALL` 或具体 Ticket 的最低必读集合；只把真实存在且触发条件匹配的项目 Skill 纳入；
+4. 使用项目根相对 Path 记录每个 Skill 的入口文件，同时记录触发 scope、读取时机和用途；不得把 Speculo 自带 Skill 或机器绝对路径伪装成项目 Skill；
+5. 未发现适用项目 Skill 时，记录已扫描的 Skill 根和“无适用项”，不生成虚假路径；项目 Skill 清单是最低集合而非 allowlist。
+
+#### Prefactor
+
+遵循“让变更变容易，然后做容易的变更”：
+
+- 如果当前接口、依赖或接缝会使后续实现明显不安全或重复，提出前置 prefactor Ticket；
+- prefactor 必须说明它解除的具体阻碍；
+- prefactor 必须独立有价值且可验证；
+- 不为了“更干净”而创建与目标无关的重构 Ticket。
+
+**完成标准**：实现地形、稳定接缝、共享路径、必要 prefactor 与逐 Ticket 项目 Skill 路由已识别。
+
+### 3. 草拟曳光弹式垂直切片
+
+加载 `<Path>{roots.workflows}/specdev/specdev-t-tickets/references/decomposition-rules.md</Path>`。每个切片应横向穿过交付该行为所需的最小层次组合，而不是把数据库、后端、前端和测试拆成互相无价值的水平 Ticket。
+
+每个 Ticket 必须：
+
+- 交付一个可观察行为，或一个能独立解除后续阻塞的安全准备能力；
+- 完成后可以独立演示、测试或验证；
+- 适合一个全新 Agent 上下文在不中断的情况下完成；
+- 与其他 Ticket 有实质行为差异；
+- 只依赖真正阻止它开始的前置产物；
+- 自带至少一种完成证据。
+
+#### 宽重构例外
+
+字段重命名、共享符号类型变化、协议升级等宽机械变更无法安全塞入单个垂直切片时，按以下顺序：
+
+1. **Expand**：在旧形式旁增加新形式，保持旧调用方可工作；
+2. **Migrate batches**：按包、目录、消费者或风险分批迁移，每批独立成 Ticket；
+3. **Contract**：确认旧调用点为零后删除旧形式；
+4. 若迁移批次无法各自保持绿色，使用隔离集成分支和最终集成验证 Gate，但仍保留明确的批次与责任边界。
+
+**完成标准**：每个 Ticket 的可观察产出、真实阻塞边和验证方式已草拟。
+
+### 4. 判定规划深度与风险
+
+按 `<Path>{roots.workflows}/specdev/common/rules/readiness-and-depth.md</Path>` 为每个 Ticket 标注：
+
+- `lite`：局部、可逆、沿用既有模式、无公共契约或迁移影响；
+- `standard`：大多数多文件或跨层垂直切片；
+- `deep`：公共 API/schema、数据迁移、安全/隐私/资金、不可逆操作、expand-contract、共享核心路径、多个 implementation owner 的跨 Ticket 写入协调或高事故半径。
+
+规划深度不是优先级，也不是 Gate。每个 Ticket 必须记录触发该深度的原因。
+
+### 5. 写成决策完备 Ticket
+
+必须按 `<Path>{roots.workflows}/specdev/common/rules/skill-invocation.md</Path>` 填写本票真实调用绑定；Map 中的读取路由不能代替调用。
+
+使用 `<Path>{roots.workflows}/specdev/specdev-t-tickets/assets/ticket-template.md</Path>` 填写：
+
+- 战略目标、可观察产出与来源追踪；
+- 当前代码事实和需求差距；
+- 已锁定决策、低影响假设和未决问题；
+- IN / REUSE / OUT；
+- 用户或调用者视角的端到端行为；
+- Standard/Deep 的接口、输入输出、不变量、数据流、失败与兼容契约；
+- 有序执行路线和安全落点；
+- expected、writable、read-only、shared 路径；
+- 正常、失败和回归验证矩阵；
+- 每个 Ticket 按 Goal Plan 的 workspace 策略定义 current-workspace/direct-parent 或 source-worktree/parent-candidate 检查，以及按实际跨边界风险判定的 E2E disposition；
+- 每个实现 Ticket 的 implementation commit 与对应父分支完成条件；仅 required 模式创建独立 worktree；
+- Deep 的迁移、兼容窗口、监控、回滚和不可逆批准点；
+- 可判定验收标准。
+
+路径所有权必须遵守 `<Path>{roots.workflows}/specdev/common/rules/path-ownership.md</Path>`，证据设计必须遵守 `<Path>{roots.workflows}/specdev/common/rules/evidence-and-verification.md</Path>`。
+
+### 6. 构建依赖 DAG、合同覆盖与并发检查
+
+1. 使用 Ticket ID 建立 `blocked_by`；
+2. 检测循环和不存在的引用；
+3. 识别根 Ticket、汇合点、扇出与收缩点；
+4. 为每个 Spec 验收合同映射至少一个 Ticket；
+5. 检查并行候选的 `writable_paths` 是否相交；
+6. 共享路径必须指定唯一 owner，通常由专门 Ticket 或明确的集成 owner 修改；
+7. 不得用依赖边表达“可能更方便”或纯粹的人员交接。
+
+使用 `<Path>{roots.workflows}/specdev/specdev-t-tickets/assets/tickets-map-template.md</Path>` 草拟总体 Map；写入所有 Ticket 共享的总体实施背景与项目 Skill 读取矩阵。矩阵中的每个 Ticket 必须由 `ALL` 或自己的 Ticket ID 覆盖。
+
+### 7. Definition of Ready
+
+加载 `<Path>{roots.workflows}/specdev/specdev-t-tickets/references/ticket-readiness.md</Path>` 逐个检查。
+
+存在以下任一情况时 `ready: false`：
+
+- 会改变行为、接口、数据、兼容、安全、范围或验收的未决问题；
+- 依赖缺失或 DAG 有环；
+- 可写路径不明确或并行所有权冲突；
+- 验证方法不能执行且没有批准的替代证据；
+- Ticket 未声明 E2E required/not-required 及理由，或在 required 模式把 E2E 安排到 source worktree；
+- Tickets Map 缺少总体实施背景或项目 Skill 读取矩阵，项目 Skill 路径不存在、不是项目根相对路径，或当前 Ticket 未被 `ALL`/自身 ID 覆盖；
+- 无法形成实现 commit 与 Goal Plan 所选 direct-parent/candidate-merge 父分支出口；
+- 单个新上下文无法完成；
+- Standard/Deep 缺少有序执行路线；
+- Deep 缺少迁移、兼容、监控、回滚或批准点。
+
+### 8. 与用户核对
+
+以完整编号列表展示所有 Ticket，至少包含：
+
+- 标题；
+- 可观察交付；
+- 被阻塞于；
+- Planning Depth 与触发原因；
+- 风险；
+- Ready 状态；
+- 关键未决问题；
+- 预计并行组和共享路径 owner；
+- `ALL` 与逐 Ticket 的项目 Skill 最低必读集合。
+
+核对：
+
+- 粒度是否适合单一上下文；
+- 是否出现水平切片；
+- 阻塞边是否真实；
+- 是否应合并、进一步拆分或增加 prefactor；
+- 合同是否全部覆盖；
+- 路径所有权和验证是否可信。
+
+每次修改后重新展示完整列表，直到用户批准。用户明确要求一次性自主规划且不存在高影响未知项时，可使用推荐默认值并把假设写入 Ticket，不为形式重复询问。
+
+### 9. 发布
+
+创建：
+
+- Ticket 目录：`<Path>{roots.state}/specdev/changes/{change}/ticket/</Path>`
+- Tickets Map：`<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>`
+- Evidence 目录：`<Path>{roots.state}/specdev/changes/{change}/evidence/</Path>`
+
+按拓扑顺序写入 Ticket：
+
+```text
+<Path>{roots.state}/specdev/changes/{change}/ticket/NN-<ticket-name>.md</Path>
+```
+
+`NN` 使用两位或更多位零填充数字；Ticket frontmatter ID 使用 `T-NN`。Ticket 的 `blocked_by` 使用 Ticket ID，而不是相对文件路径。
+
+使用 `<Path>{roots.workflows}/specdev/specdev-t-tickets/assets/ticket-template.md</Path>` 和 `<Path>{roots.workflows}/specdev/specdev-t-tickets/assets/tickets-map-template.md</Path>` 生成工件，并对照：
+
+- `<Path>{roots.workflows}/specdev/common/schemas/ticket.schema.json</Path>`
+- `<Path>{roots.workflows}/specdev/common/schemas/tickets-map.schema.json</Path>`
+
+运行：
+
+```bash
+node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
+  --stage tickets \
+  --repo <project-root> \
+  <Path>{roots.state}/specdev/changes/{change}</Path>
+```
+
+回读 Ticket 的状态、Map 的依赖/导航以及 README 接续点，不另写状态镜像。
+
+## 完成标准
+
+- Ticket 目录和 Map 已写入完整 Path 标签 所指位置；
+- Spec 合同全部 covered 或有明确批准的 deferred；
+- DAG 无环、阻塞引用存在；
+- Ready Ticket 无高影响未知项；
+- 并行 Ticket 无未解决的可写冲突；
+- 每个 Ticket 可独立验证且适配单一上下文；
+- Tickets Map 已记录总体实施背景；每个 Ticket 被项目 Skill 读取矩阵覆盖，Skill 路径存在且为项目根相对路径；
+- Prefactor 与 expand-contract 使用条件正确；
+- 用户已批准拆分或明确授权自主发布；
+- 校验器无 error。
+
+## 子文件引用
+
+- 拆分规则：`<Path>{roots.workflows}/specdev/specdev-t-tickets/references/decomposition-rules.md</Path>`
+- Ticket 就绪规则：`<Path>{roots.workflows}/specdev/specdev-t-tickets/references/ticket-readiness.md</Path>`
+- Ticket 模板：`<Path>{roots.workflows}/specdev/specdev-t-tickets/assets/ticket-template.md</Path>`
+- Tickets Map 模板：`<Path>{roots.workflows}/specdev/specdev-t-tickets/assets/tickets-map-template.md</Path>`
+
+## 下一步
+
+满足任一情况时建议运行 `<Path>{roots.workflows}/specdev/specdev-p-goal-plan/SKILL.md</Path>`：Ticket 数量达到或超过 10、存在多个 implementation owner 的并行写入协调、Deep Ticket、迁移、共享契约、多个 Gate 或高风险发布。只读 review/research 并行本身不触发 Goal Plan；少量线性 Ready Ticket 可直接进入 `<Path>{roots.workflows}/specdev/specdev-i-implement/SKILL.md</Path>`。

package/template/workflows/specdev/specdev-t-tickets/references/ticket-readiness.md

@@ -0,0 +1,56 @@
+# Ticket Definition of Ready
+
+本检查由 `<Path>{roots.workflows}/specdev/specdev-t-tickets/SKILL.md</Path>` 使用，并细化 `<Path>{roots.workflows}/specdev/common/rules/readiness-and-depth.md</Path>`。
+
+## 通用门禁
+
+- [ ] frontmatter 字段完整，Ticket ID、文件名和 `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>` 一致。
+- [ ] Tickets Map 包含总体实施背景与项目 Skill 读取矩阵；当前 Ticket 被 `ALL` 或自身 Ticket ID 覆盖。
+- [ ] 矩阵中的项目 Skill 均使用真实存在的项目根相对 `<Path>.../SKILL.md</Path>`，并声明 Trigger / Scope、读取时机和用途；没有适用项时记录实际扫描范围而不生成虚假路径。
+- [ ] Ticket 明确要求 Lead 与 实现执行者 按 Map -> 适用项目 Skill -> 当前 Ticket 的顺序读取；矩阵是最低必读集合而非 allowlist。
+- [ ] 可观察产出单一、明确且可验证。
+- [ ] 来源和验收合同映射存在。
+- [ ] UI Ticket 的 ui_change/design_ref 固定批准 DESIGN 的 revision、digest、pages 与 acceptance；实际 UI 文件范围不能靠省略标记绕过，非 UI 票无此门禁。
+- [ ] UI 实施的 Design Conformance 证据责任、页面/状态验收与真实浏览器路径明确；设计漂移返回 P。
+- [ ] IN、REUSE、OUT 无冲突。
+- [ ] 高影响未决问题为零。
+- [ ] `blocked_by` 指向存在的 Ticket，DAG 无环。
+- [ ] `expected_changes`、`writable_paths`、`read_only_paths` 和 `shared_paths` 中的项目路径都使用项目相对 Path 标签。
+- [ ] `writable_paths` 非空；纯 review/research 不伪装成 I-implement Ticket。
+- [ ] 每个 shared path 在 `shared_path_owners` 中有唯一 owner。
+- [ ] 正常、失败和回归至少各有一条验证，或有可信的不适用原因。
+- [ ] 明确 `E2E disposition: required | not-required: reason`；required 场景、预期和接缝可执行。
+- [ ] 按 Goal Plan 策略定义 current-workspace 或 source-worktree 的非 E2E 检查；E2E owner 固定为 Lead，运行环境分别为 current-workspace 或 parent-candidate。
+- [ ] Ticket 完成合同包含 implementation commit、direct-parent 或 candidate-merge、父分支 result SHA 和 Lead Evidence；仅 required 模式需要独立 worktree。
+- [ ] Evidence 位置明确为 `<Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path>`。
+- [ ] 单个全新上下文能够完成；否则已拆分。
+- [ ] 所有内部文件与目录引用使用完整根变量 Path 标签。
+
+## Standard 门禁
+
+- [ ] 实现契约包含入口、输入输出、不变量、状态或数据流、失败行为和兼容。
+- [ ] 有 3–7 步有序执行路线。
+- [ ] 路径所有权足以支持并发判断。
+- [ ] 验证矩阵可以证明外部行为，而非只检查内部调用。
+
+## Deep 门禁
+
+- [ ] 迁移顺序、兼容窗口、监控、回滚或前向恢复、收缩条件和批准点完整。
+- [ ] 安全、隐私、资金或数据完整性风险有缓解与验证。
+- [ ] 跨 implementation owner 的路径所有权和所选 direct-parent/parent-candidate 集成 Gate 明确。
+- [ ] expand-contract 的收缩条件可通过扫描、指标、查询或测试证明。
+
+## Ready 状态
+
+只有全部适用项通过时才能设置：
+
+```yaml
+ready: true
+status: ready
+```
+
+未通过时保持 `ready: false`，并在未决问题、阻塞原因或偏差记录中写明原因。
+
+## 适用工程义务
+
+Ready 前确认真实调用方、文档/升级说明、正常与失败验证、恢复条件和证据失效条件。删除测试有风险承接；性能票有测量基线和真实用户操作；文档票分清纯说明与可见行为。缺少 required 验证不因工具暂不可用而标 ready。

package/template/workflows/specdev/specdev-t-triage/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: specdev-t-triage
+description: "摄入与核验外部请求、投影本地完成事实、交付 PR，或按明确目标处理 CI、安全告警、npm/GitHub Release 预检、发布和恢复；清晰的本地需求直接进入对应 Work。"
+metadata:
+  speculo-kind: work-skill
+  speculo-id: specdev/triage
+  speculo-domain: specdev
+  speculo-contract-version: "2"
+---
+
+# 请求分诊与 GitHub 交付
+
+激活后读取 <Path>{roots.workflows}/specdev/common/rules/domain-runtime.md</Path> 与 <Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>。本地 Spec/Ticket/Map/Goal/Evidence 始终是开发权威，GitHub 不成为开发 tracker。
+
+## 选择模式
+
+只读取选中分支，publish 专指 Ticket→Issue，release 专指包/GitHub Release。按意图先分组：请求摄入（queue/capture/intake）、完成投影（reconcile/publish）、PR 交付、CI/安全、版本发布（preflight/release）、原记录恢复。组名只是导航，不增加模式或 owner。
+
+| 模式 | 协议 | owner 与结果 |
+|---|---|---|
+| queue | <Path>{roots.workflows}/specdev/specdev-t-triage/references/queue-protocol.md</Path> | 只读候选，不创建 change |
+| intake | <Path>{roots.workflows}/specdev/specdev-t-triage/references/intake-protocol.md</Path> | 冻结 source/triage，验证与路由 |
+| reconcile | <Path>{roots.workflows}/specdev/specdev-t-triage/references/reconcile-protocol.md</Path> | 来源 Issue 的 external_action |
+| publish | <Path>{roots.workflows}/specdev/specdev-t-triage/references/publish-protocol.md</Path> | 已完成 Ticket 的 publish 账本 |
+| capture | <Path>{roots.workflows}/specdev/specdev-t-triage/references/capture-protocol.md</Path> | workspace capture，保持 Issue open |
+| pr-delivery | <Path>{roots.workflows}/specdev/specdev-t-triage/references/pr-delivery-protocol.md</Path> | change 的 PR 记录 |
+| ci-security | <Path>{roots.workflows}/specdev/specdev-t-triage/references/ci-security-protocol.md</Path> | 独立 TRI 操作记录 |
+| release-preflight | <Path>{roots.workflows}/specdev/specdev-t-triage/references/release-preflight.md</Path> | 只读预检与 TRI 记录 |
+| release | <Path>{roots.workflows}/specdev/specdev-t-triage/references/release-protocol.md</Path> | 已授权发布及逐目标回执 |
+| recover | <Path>{roots.workflows}/specdev/specdev-t-triage/references/release-recovery.md</Path> | 恢复指定原记录 |
+
+远程原语统一见 <Path>{roots.workflows}/specdev/specdev-t-triage/references/remote-operations.md</Path>。其他调用方可直接复用该协议，不激活 T，也不初始化 SpecDev。
+
+## 定位与状态
+
+从 workspace 解析 roots。intake 可创建/恢复 change；reconcile/publish 只选择满足 <Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path> 的现有 change。多个候选先消歧；冻结来源不覆盖。
+
+capture 不创建也不选择 change，不创建工作调用镜像，只使用 <Path>{roots.state}/specdev/capture.md</Path>。queue 只返回候选。CI/发布独立记录写入 <Path>{roots.state}/specdev/triage-runs/TRI-###.md</Path>；T 在首次具体操作时选最小未用 ID，按 <Path>{roots.workflows}/specdev/specdev-t-triage/assets/triage-run-template.md</Path> 原子写入并重读，不占用 change 状态。recover 使用原账本 owner。
+
+intake 使用实际 change README 和来源/分诊工件；有重叠写入者先由原 owner 恢复或交接，失败在原账本保留检查点。已结束 change 的 reconcile/publish 和 PR 交付只更新各自账本，不重开整体 Outcome。PR 不能修改来源关闭、Ticket publish 或 capture 状态。远程失败不能把已完成代码状态改回未完成。
+
+## 远程结果与检查有效期
+
+区分本地完成、push、PR created/ready/merged、Issue closed、npm 和 GitHub Release 的逐目标回执。queued、pending、skipped、未启动或环境失败不能写 passed；只重跑真正失效或失败的检查。PR/依赖交付固定真实 base/head、顺序和授权，改写后重新核对审查及 CI。删除来源分支前确认没有未完成依赖，不硬编码宿主必有某个 stack 扩展。
+
+超时先沿原 marker/目标对账，部分成功恢复原账本，不重建、不把远程失败倒灌为代码未完成。CI 资源问题按需读取 <Path>{roots.workflows}/specdev/common/rules/test-reliability.md</Path>；升级说明与实际构件、已发布基线和用户迁移步骤一起核对，不在 release 当天补造兼容承诺。
+
+## 验证与返回
+
+使用 <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>：
+
+- intake/reconcile/publish：--stage triage，输入当前 change。
+- pr-delivery：--stage pr-delivery，输入当前 change。
+- capture：仅账本存在时 --capture，不为验证创建账本。
+- 独立 TRI：--triage-run，输入原记录。
+- queue：报告检索范围、分页、未知项，不制造完成证据。
+
+回读真实工件、账本和远程回执，返回结果、未完成项、验证命令及完整恢复位置。external_action 的 closed/waived/not-applicable 与 publish_action 的 not-requested/published/waived 各自满足归档门；pending/failed 恢复原模式。PR 仅 requested=true 的未闭合交付挡门，独立发布不自动挡 change 归档。归档交 <Path>{roots.workflows}/specdev/specdev-a-archive-and-consolidate/SKILL.md</Path>。

package/template/workflows/specdev/specdev-t-triage/assets/capture-template.md

@@ -0,0 +1,42 @@
+---
+schema_version: 1
+artifact: capture-index
+mode: capture
+repo: owner/repo
+updated_at: <ISO-8601>
+---
+
+# Capture
+
+## 捕获计划
+
+- **目标 repo：** `owner/repo`
+- **origin：** local
+- **排除 id：** 无 / `<YYYY-MM-DD-slug>`
+- **确认记录：** 无 / 本次授权时间与操作员
+
+capture 不创建 Change，不创建工作调用镜像，不关闭 Issue。GitHub 是 inbox，不是开发权威。
+
+## 账本
+
+| id | kind | title | labels | number | url | marker | sha256 | state |
+|---|---|---|---|---|---|---|---|---|
+| 2026-09-17-login-timeout | bug | bug: login timeout on empty session | bug, specdev:captured, origin:local | — | — | specdev:capture:2026-09-17-login-timeout | — | planned |
+
+`state`：`planned | open | skipped:duplicate | intaken | waived | failed`。
+
+`sha256` 覆盖实际发出的 Issue 正文。漂移只警告，不自动重发。
+
+## 计数
+
+- **inbox_open：** 0
+- **inbox_intaken：** 0
+- **inbox_waived：** 0
+- **skipped：** 0
+- **failed：** 0
+
+计数权威是本文件，不是 GitHub 搜索。`inbox_open` 不计 `published_issues`。
+
+## 重试
+
+无 / 失败行的已完成步骤和下一步。已成功的记录不回滚。

package/template/workflows/specdev/specdev-t-triage/assets/close-comment-template.md

@@ -0,0 +1,42 @@
+# Evidence 关闭评论模板
+
+publish 调用 `issue-comment-close` 时使用。先套 `<Path>{roots.workflows}/specdev/specdev-t-triage/references/public-projection.md</Path>`。
+
+done 票 `--reason completed`：
+
+```markdown
+> *This was generated by AI during SpecDev T-triage publish.*
+
+## Completion
+
+**Result:** delivered and verified.
+
+**Public commit / PR:** <url or sha or 无公开 commit/PR>
+
+**Verification:**
+- Directed: passed | not-run (<reason>)
+- Regression: passed | not-run (<reason>)
+- E2E: passed | not-run (<reason>)
+
+**Residual risk:** <可公开残余风险或「无」。>
+
+Marker: `specdev:<change>:T-01:published`
+```
+
+纳入的 cancelled 票 `--reason not_planned`：
+
+```markdown
+> *This was generated by AI during SpecDev T-triage publish.*
+
+## Cancelled
+
+**Reason:** cancelled-already-implemented | cancelled-out-of-scope
+
+**Notes:** <指到已有公开位置或 ADR / 用户决定；不贴内部路径。>
+
+**Public commit / PR:** <url or sha or 无公开 commit/PR>
+
+Marker: `specdev:<change>:T-01:published`
+```
+
+父索引关闭评论 marker 为 `specdev:<change>:publish-index`，正文列出已关闭的子 Issue 编号与计数。

package/template/workflows/specdev/specdev-t-triage/assets/issue-body-template.md

@@ -0,0 +1,34 @@
+# Published Ticket 正文模板
+
+publish 创建 GitHub Issue 时使用。先套 `<Path>{roots.workflows}/specdev/specdev-t-triage/references/public-projection.md</Path>` 脱敏，再填本模板。占位符不得把 state Path 带出去。
+
+```markdown
+> *This was generated by AI during SpecDev T-triage publish.*
+
+## Published Ticket
+
+**Category:** <bug | feature | refactor | investigation | operations | documentation | review>
+**Change:** <change-name>
+**Ticket:** T-01
+**Origin:** local | intake
+**Parent:** Part of #<n> / none
+
+**Summary:** <一句话，已经发生的事实。>
+
+**Delivered behavior:**
+<完成后系统对外可见的行为。写「现在会怎样」，不写「去改哪个文件」。>
+
+**Acceptance:**
+- [x] AC-001：<可公开验收，状态按 Evidence 勾选>
+
+**Blocked by:**
+- #<n> <title>
+- None
+
+**Out of scope:**
+<票里 OUT 列的可公开项；没有则写「无」。>
+
+**Provenance:**
+- Public commit / PR: <url or sha or 无>
+- Marker: `specdev:<change>:T-01:published`
+```

package/template/workflows/specdev/specdev-t-triage/assets/issue-record-template.md

@@ -0,0 +1,27 @@
+# Captured Record 正文模板
+
+capture 创建仍 open 的 GitHub Issue 时使用。先套 `<Path>{roots.workflows}/specdev/specdev-t-triage/references/public-projection.md</Path>` 脱敏，再填本模板。占位符不得把 state Path 带出去。现在时；不写「请去实现」。
+
+```markdown
+> *This was generated by AI during SpecDev T-triage capture.*
+
+## Captured Record
+
+**Category:** <bug | feature | refactor | investigation | operations | documentation | review>
+**Origin:** local
+**Status:** inbox, open; not a development ticket
+
+**Summary:** <一句话，现在要记下的事实或意图。>
+
+**Observed / intended:**
+<现在观察到什么、想记下什么。写「现在怎样 / 想记下什么」，不写「去改哪个文件」，不写派工祈使句。>
+
+**Why parked:**
+<为什么先记到 GitHub、还不进 Change。>
+
+**Out of scope for this record:**
+<本条不决定的事项；没有则写「无」。本条默认对应一次未来 intake / 一个未来 Change。>
+
+**Provenance:**
+- Marker: `specdev:capture:<YYYY-MM-DD-slug>`
+```

package/template/workflows/specdev/specdev-t-triage/assets/triage-template.md

@@ -0,0 +1,57 @@
+---
+schema_version: 2
+artifact: triage
+change: <YYYY-MM-DD-topic>
+mode: intake
+disposition: needs-triage
+verification: pending
+remote_actions: []
+source: <Path>{roots.state}/specdev/changes/{change}/source.md</Path>
+classification: investigation
+risk: medium
+route: specdev/wayfinder
+ready_for_implementation: false
+external_action: not-applicable
+publish_action: not-requested
+publish: null
+updated_at: <ISO-8601>
+---
+
+# Triage: <标题>
+
+## 当前判定
+
+- **影响：** 用户、系统、数据或交付影响
+- **紧急度：** immediate / scheduled / normal / unknown
+- **当前证据：** 已观察事实，不写推测
+- **相关代码/工件：** `<Path>src/example.ts</Path>` / 无
+
+## 未知项
+
+- **可发现事实：** 无 / 需要从仓库、日志、测试或配置查明的事实
+- **需要用户决定：** 无 / 会改变目标、范围、行为或风险承受度的决定
+- **低影响实现细节：** 无 / 由后续实现者按既有惯例决定
+
+## 路由
+
+- **下一 Work：** `<Path>{roots.workflows}/specdev/specdev-w-wayfinder/SKILL.md</Path>`
+- **理由：** 为什么这是最小且正确的下一步
+
+## 外部动作
+
+- **远程目标：** 无 / `<Url>https://github.com/owner/repo/issues/123</Url>`
+- **关闭能力：** supported / unsupported / not-applicable
+- **当前状态：** not-applicable / pending-close / closed / close-failed / waived
+- **授权记录：** 无
+- **尝试与结果：** 无
+
+外部动作只投影来源 Issue 的最终完成，不替代本地状态、Ticket、Map 或 Evidence。
+
+## 发布投影
+
+- **publish_action：** not-requested / pending / published / publish-failed / waived
+- **账本：** 无 / `<Path>{roots.state}/specdev/changes/{change}/publish.md</Path>`
+- **origin：** local / intake
+- **计数：** 见账本；workspace 汇总用 publish-status
+
+发布投影只记账已完成 Ticket，不把 GitHub 提升为开发权威。`publish_action` 与 `external_action` 分立。

package/template/workflows/specdev/specdev-t-triage/references/capture-protocol.md

@@ -0,0 +1,89 @@
+# Capture Protocol
+
+仅在 Triage `mode=capture` 时加载。目标是把尚未成 Change 的记事项写成仍 open 的 GitHub Issue，并留下 workspace 级 `<Path>{roots.state}/specdev/capture.md</Path>`。
+
+GitHub 是 inbox 和计数器，不是 tracker，也不是开发权威。capture 不创建、不选择、不改写任何 change。票级完成后投影走 publish，源 Issue 关闭走 reconcile，外部输入冻结走 intake；四者互不覆盖。
+
+## 1. 触发与对象
+
+用户必须给出至少一条记事项（标题、现在时摘要、分类）。禁止扫整个 workspace 自动发。允许一次授权批量多条；默认 **1 条记录 = 1 次未来 intake / 1 个未来 Change**。v1 不写 `related_locators`，不把 N 条 locator 塞进同一个未来 source。
+
+相关但目标不清 → 先 capture 为多条 inbox，以后走 `<Path>{roots.workflows}/specdev/specdev-w-wayfinder/SKILL.md</Path>` 或逐条 intake，不在本协议合并。
+
+可选开关：排除 id 列表。目标 repo 默认从 `git remote` 推断，必须展示确认。
+
+capture **不得**：
+
+- 创建 change 目录或 `<Path>{roots.state}/specdev/changes/{change}/</Path>` 下任何工件；
+- 写 `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>` / `<Path>{roots.state}/specdev/changes/{change}/source.md</Path>` / `<Path>{roots.state}/specdev/changes/{change}/publish.md</Path>`；
+- 创建任何 change 的工作调用镜像；
+- 加载 `<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>`；
+- 调用 `issue-comment-close` 或关闭刚创建的 Issue；
+- 在本地复制 inbox 正文副本；
+- 打 `specdev:published`、`specdev:change`、`needs-triage`、`needs-info`、`ready-for-agent`、`ready-for-human`。
+
+只写 `<Path>{roots.state}/specdev/capture.md</Path>` 和经授权的远程 inbox Issue。缺失该账本合法，首次 capture 才创建。
+
+## 2. 硬门
+
+失败即停，零远程写入。已有账本行保持原 state。
+
+1. 每条纳入记录有 id（`YYYY-MM-DD-<kebab>`）、现在时摘要、且 `kind` 为 bug、feature、refactor、investigation、operations、documentation 或 review。禁止 `mixed`。
+2. 调用 `<Path>{roots.workflows}/specdev/specdev-t-triage/references/remote-operations.md</Path>` 能读目标 repo、能 dry-run `issue-create`。本协议只用 `issue-search` / `issue-create`。
+3. 分类映射见 `<Path>{roots.workflows}/specdev/specdev-t-triage/references/classification-map.md</Path>`。缺 type 标签时 dry-run 表列出将创建的标签，授权后才 `gh label create`。
+4. 用户看见完整 dry-run 表（id、标题、标签、正文、reason）并给出 **本次** 明确确认。
+
+origin 固定 `local`。marker：`specdev:capture:<id>`。
+
+## 3. 准备记录
+
+按 `<Path>{roots.workflows}/specdev/specdev-t-triage/references/public-projection.md</Path>` 脱敏。现在时，不是完成后的过去时，也不是派工祈使句。
+
+Issue 正文：`<Path>{roots.workflows}/specdev/specdev-t-triage/assets/issue-record-template.md</Path>`。
+
+用 `<Path>{roots.workflows}/specdev/specdev-t-triage/assets/capture-template.md</Path>` 写或更新 `<Path>{roots.state}/specdev/capture.md</Path>`。先把纳入行标 `planned`，用户排除的标 `skipped:duplicate` 以外的跳过由执行期判定。
+
+## 4. 幂等执行
+
+对每条纳入记录：
+
+1. `issue-search` 查 marker 或精确标题 + `specdev:captured`。
+2. 已存在且 marker 在且仍 open → 账本 `open`，跳过创建。
+3. 已存在且 marker 在但已 closed → 停止该行，展示冲突，不重开、不覆盖。intake 已消耗的行应为 `intaken`，由 intake 协议回写，不由本协议改 closed。
+4. 已存在但无 marker → 停止该行，展示冲突，不覆盖别人的 Issue。
+5. 不存在 → dry-run `issue-create` → 授权后 `--apply` → 保持 **open**。marker 写在正文 Provenance。不评论、不关闭。
+6. 任一步失败：该行 `failed`，记录已完成步骤和下一重试动作；已成功的记录不回滚。
+
+`--apply` 只表示调用方完成本次确认，不替代授权。远程失败不补建本地 Change。
+
+全部纳入记录到达 `open` 或合法 `skipped:duplicate`，且无 `failed` 时结束。用户明确放弃未发出的行：`waived`。重跑是恢复，不是重发。`intaken` 只由后续 intake 写入。
+
+## 5. 校验与计数
+
+账本存在时：
+
+```bash
+node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
+  --capture <Path>{roots.state}/specdev/capture.md</Path>
+```
+
+缺失该文件时不要为了校验去创建它。
+
+workspace inbox 计数：
+
+```bash
+node <Path>{roots.workflows}/specdev/specdev-t-triage/scripts/capture-status.mjs</Path> \
+  --state-root <Path>{roots.state}/specdev</Path>
+```
+
+数字只来自 `<Path>{roots.state}/specdev/capture.md</Path>`，不把 GitHub 搜索当权威，也不计入 `published_issues`。
+
+## 完成标准
+
+- 用户指定的记事项均有对应仍 open 的 GitHub Issue，或账本有合法 skip / waived；
+- 每条已捕获 Issue 带且仅带一个 type 标签，以及 `specdev:captured` 与 `origin:local`；
+- 正文是现在时 inbox 记录，不是派工单，也不是完成后投影；
+- marker 使重跑不重复建贴；
+- 未创建 Change，未创建工作调用镜像，未调用关闭；
+- `<Path>{roots.state}/specdev/capture.md</Path>` 与远程重读一致，失败行可恢复；
+- 未授权时远程写入为零。