@wwkit/harness 1.0.17 → 1.0.19

package/skills/work-ledger/SKILL.md

@@ -1,73 +0,0 @@
----
-name: work-ledger
-description: |
-  [work 专属 runbook] 仅供 work agent 通过 skill 工具显式调用（name=work-ledger），其他 agent / 普通对话禁止触发
-  运行会话管理技能：创建产物目录（doc_dir 树 + .gitignore）、生成/恢复 session_id、起始检查（git 仓库 / 工作树 stash / 运行元数据 branch+initial_base+merge_base）、
-  以及 Ledger（progress.md）的格式与读写恢复规则（短 SHA 7 位 + 大小写映射约定）。
-  适用：work agent 第三步「产物目录与 Ledger」及 compaction 后恢复进度。
-  不适用：规划阶段（用 work-plan）；任务派发/审查正文；非 work 流程的普通文档管理。
-license: MIT
-metadata:
-  workflow: sequential
----
-
-# work-ledger 技能
-
-## 触发时机
-
-work agent 进入第三步「产物目录与 Ledger」时（创建运行时）、以及 compaction 后需要恢复进度时加载本技能。
-
-## 输入
-
-从 work.md 流程传入：
-
-| 输入 | 说明 |
-|------|------|
-| `root_dir` | 工程根目录，产物目录位于 `<root_dir>/.webwork/harness/work/<session_id>/` |
-| `target` | 目标摘要，写入 Ledger 首行命名、plan.md 标题 |
-| `constraints` | 约束（每个任务 brief 的 `forbidden` 至少包含其全部内容） |
-| git 状态 | 起始检查时读取的分支名、HEAD、工作树状态 |
-
-## 工作流程
-
-### 阶段 1：加载 references
-
-用 `read` 工具加载本技能 `references/` 下的全部流程文件（相对路径基于本 skill 目录）：
-
-- `references/layout.md` → 产物目录结构（doc_dir 树 + `.gitignore` + archive 约定）
-- `references/bootstrap.md` → session_id 生成与恢复、产物目录创建、起始检查、后续约束
-- `references/ledger-format.md` → Ledger（progress.md）格式、条目规则、恢复逻辑、短 SHA/大小写约定
-
-### 阶段 2：创建产物目录
-
-按 `references/layout.md` 与 `references/bootstrap.md`：生成 `session_id`，创建 `<root_dir>/.webwork/harness/work/<session_id>/`，写入 `<root_dir>/.webwork/harness/work/.gitignore`（内容 `*` + `!.gitignore`）。
-
-### 阶段 3：起始检查（仅此一次）
-
-按 `references/bootstrap.md`：确认在 Git 仓库内；检查工作树干净（非空则 `git stash push -u` 并把脏文件清单记入 Ledger，此为人工确认点之一）；记录运行元数据 `branch`/`initial_base`/`merge_base` 并写入 Ledger 首行。
-
-### 阶段 4：Ledger 读写维护
-
-按 `references/ledger-format.md`：每次派发前写 `T<N>: base=` 与 `T<N>: session=`，review/re-review 后写 `T<N>: reviewed_head=`，implementer 返回后写状态行；恢复时按该文件的恢复逻辑执行（先读 `plan.md` 恢复计划，再读 `progress.md` 恢复进度）。
-
-## 输出
-
-- `<root_dir>/.webwork/harness/work/` 目录树（`.gitignore` + `<session_id>/` 下的 plan.md/progress.md 等文件）
-- Ledger 首行元数据块（`doc_dir`/`branch`/`initial_base`/`merge_base`），作为恢复入口
-- 按阶段 4 维护的 `T<N>: key=value` 进度条目
-
-## 约束
-
-- 唯一约束：Ledger 字段名与产物文件格式固定（对照 `references/ledger-format.md`），不得改动。
-- 短 SHA 一律取 7 位（`${sha:0:7}`）；大小写映射约定（见 ledger-format）：Ledger 元数据字段小写、任务条目 `T<N>: key=value`、内存/命令变量大写。
-- 产物目录绝对路径是恢复入口，compaction 后以 Ledger 首行 `doc_dir=` 为准，不以记忆为准。
-- 本技能只维护产物目录与 Ledger，不派发/审查任务、不写任务 brief。
-
-## 资源目录
-
-```
-references/
-├── layout.md        # 产物目录结构（doc_dir 树 + .gitignore + archive）
-├── bootstrap.md     # session_id 生成与恢复、创建产物目录、起始检查、后续约束
-└── ledger-format.md # Ledger 格式、条目规则、恢复逻辑、短 SHA/大小写约定
-```

package/skills/work-ledger/references/bootstrap.md

@@ -1,28 +0,0 @@
-# session_id 生成与恢复 + 起始检查（提取自 docs/plans/work-copy.md L225-249）
-
-## session_id 生成与恢复（L225-234）
-
-`session_id` 唯一标识一次编排运行的产物目录，由创建时生成（要求：唯一、可排序、含时间戳）并**写入 Ledger 首行**作为恢复入口。
-
-**恢复规则**：
-- compaction 后从 Ledger 头部元数据块的 `doc_dir=` 读取绝对路径恢复；无法读取时退化为：定位 `<root_dir>/.webwork/harness/work/` 中时间戳最新的 `<session_id>` 目录。
-- **产物目录绝对路径是 Ledger 首条元数据**（见 Ledger 格式），恢复时以它为准，不以记忆为准。
-- 并发隔离：不同运行用不同 `session_id` 目录，天然隔离，无额外机制。
-
-**创建产物目录**：创建 `<root_dir>/.webwork/harness/work/<session_id>/` 目录，并写入 `<root_dir>/.webwork/harness/work/.gitignore`（内容为 `*` + `!.gitignore`：忽略所有中间产物，但保留 `.gitignore` 自身）。归档目录 `<root_dir>/.webwork/harness/archive/` **不写** `.gitignore`——保留审计产物，可纳入版本控制。
-
-## 起始检查（仅一次，创建产物目录时执行，L236-245）
-
-派发任何 subagent 前，先确认工作树安全并记录运行元数据：
-
-1. **在 Git 仓库内**：非 Git 仓 → 报告用户并停止。
-2. **工作树是否干净**（`git status --porcelain`）：非空 → 默认 `git stash push -u` 后继续，并把 existing 文件清单记录到 Ledger。**这是人工确认点之一（另一处在范围闸门）**：若用户在场可询问 stash/保留，但全自动运行不因询问卡住。
-3. **记录运行元数据**（写入 Ledger 首行，字段语义如下）：
-   - `branch` = 当前分支名
-   - `initial_base` = 当前 HEAD
-   - `merge_base` = `initial_base`（本次启动时的 HEAD；使 `MERGE_BASE..HEAD` 恰好覆盖**本次编排产出的提交**，不混入运行前已有提交）。仅当用户**显式要求审查整个分支**时才取 `git merge-base HEAD <main_branch>`。
-
-## 后续约束（L247-249）
-
-- **脏文件不得被 implementer 一起提交**：每个任务 brief 的 `forbidden` 中追加「不得 add/commit 任何未在 `writable` 白名单中的文件」。
-- 回滚锚点：`initial_base` 是本运行所有提交的回滚参照（见「中断与回滚」）。

package/skills/work-ledger/references/layout.md

@@ -1,25 +0,0 @@
-# 产物目录（提取自 docs/plans/work-copy.md L204-223、L234）
-
-所有中间产物统一存放在 `doc_dir`（`<root_dir>/.webwork/harness/work/<session_id>/`）目录：
-
-```
-<root_dir>/.webwork/harness/work/
-  .gitignore                    # 内容: * + !.gitignore（忽略所有产物，保留 .gitignore 自身）
-  <session_id>/
-    plan.md                     # 完整计划（第二步产出，compaction 后恢复用）
-    progress.md                 # Ledger（进度持久化）
-    task-<N>-brief.md           # 任务 N 的完整文本（implementer 读取）
-    task-<N>-report.md          # 任务 N implementer 的报告（fix 追加到同一文件）
-    task-<N>-review.md          # 任务 N reviewer 的审查结果
-    task-<N>-rereview-<R>.md    # 任务 N 第 R 轮 re-review 结果
-    task-<N>-review-<base7>..<head7>.diff   # 任务 N 的 review package（diff 包）
-    final-review.md                     # 全分支 final review 结果
-    final-fix-report.md                 # final 阶段一次 fix 的 report（第七步）
-    final-review-<merge_base7>..<head7>.diff  # final review package
-    final-fix-review-<final_review_head7>..<head7>.diff  # 该 fix 的 scoped re-review diff
-```
-
-## .gitignore 约定
-
-- `<root_dir>/.webwork/harness/work/.gitignore`：内容为 `*` + `!.gitignore` —— 忽略所有中间产物，但保留 `.gitignore` 自身。
-- 归档目录 `<root_dir>/.webwork/harness/archive/` **不写** `.gitignore`——保留审计产物，可纳入版本控制。

package/skills/work-ledger/references/ledger-format.md

@@ -1,57 +0,0 @@
-# Ledger 格式（提取自 docs/plans/work-copy.md L251-294；全局约束 L27）
-
-Ledger 是你的恢复地图——compaction 后你的 context 会丢失，但文件不会。Ledger 即 `<doc_dir>/progress.md`。
-
-## 全局约束（L27）
-
-- 短 SHA 一律取 7 位（`${sha:0:7}`）。
-- **大小写映射约定**：
-  - Ledger **元数据字段**小写（`doc_dir`/`branch`/`initial_base`/`merge_base`）；
-  - **任务条目**用 `T<N>: key=value` 形式（如 `T1: base=...`）；
-  - 内存/命令变量同名大写（`BASE`/`HEAD`/`FIX_BASE`/`MERGE_BASE`/`INITIAL_BASE`）。
-- 唯一约束：Ledger 字段名与产物文件格式固定，不得改动。
-
-## 模板
-
-```markdown
-# Work ledger — target: <target 摘要>
-doc_dir: <root_dir>/.webwork/harness/work/<session_id>
-branch: <branch name>
-initial_base: <sha — 启动时 HEAD>
-merge_base: <sha — 本次运行起点，= initial_base>
-
-T1: base=a1b2c3d
-T1: session=abc123
-T1: complete (commits a1b2c3d..d4e5f6a, review clean)
-T1: reviewed_head=d4e5f6a
-T2: base=d4e5f6a
-T2: session=def456
-T2: fix round 1/5 (2 addressed, 0 open; commits d4e5f6a..b7c8d9e)
-T2: reviewed_head=b7c8d9e
-T2: complete (commits d4e5f6a..b7c8d9e, review clean)
-T3: base=b7c8d9e
-T3: session=ghi789
-T3: reviewed_head=e8f9a0b
-T3: parked — <finding> — ruling: <why the code stands>
-T3: complete (commits b7c8d9e..e8f9a0b, 1 parked)
-```
-
-## 每条规则
-
-- 创建 `doc_dir` 时：写首行元数据块（`doc_dir`/`branch`/`initial_base`/`merge_base`），这是恢复入口。
-- 派发 implementer 前：写 `T<N>: base=<BASE_SHA>`（review 和 fix 依赖此 SHA）与 `T<N>: session=<session_ref>`（fix 复用 / 重派时更新）。
-- 每次 review / re-review 结束后：写 `T<N>: reviewed_head=<REVIEW_HEAD_SHA>`（供 FIX_BASE 取用）。
-- final review 结束后、final fix 派发前：写 `final_review_head=<sha>`（= final review 时的 HEAD，供 final fix 的 scoped re-review 作 `FIX_BASE`）。
-- implementer 返回后：立即写状态行（complete/fix round/blocked）。
-- compaction 后恢复：先读 `plan.md` 恢复计划，再读 `progress.md` 恢复进度，信任 Ledger 和 `git log` 胜过你的记忆。
-
-## 恢复逻辑
-
-- 首行元数据 `doc_dir=` → 定位会话产物目录绝对路径（恢复入口）。
-- 首行命名 target → 确认归属。
-- `initial_base` → 启动时的 HEAD；`merge_base` → diff 的起点（默认 = `initial_base`）。
-- `T<N>: base=<sha>` → 该任务的 BASE SHA（用于生成 review package）。
-- `T<N>: reviewed_head=<sha>` → 该任务上次 review 看到的 HEAD（用于 fix 的 scoped re-review）。
-- `final_review_head=<sha>` → final review 时的 HEAD（final fix 的 `FIX_BASE`）。
-- `T<N>: complete` → 已完成，不重新派发。
-- 最后一行是 fix round → 中断在 loop 中，从下一轮恢复。

package/skills/work-plan/SKILL.md

@@ -1,81 +0,0 @@
----
-name: work-plan
-description: |
-  [work 专属 runbook] 仅供 work agent 通过 skill 工具显式调用（name=work-plan），其他 agent / 普通对话禁止触发
-  规划阶段技能：按 1.1 任务拆分把 target 拆成 ≤10 分钟、可布尔验收的任务，按 2.1 填写 11 字段任务计划，
-  按 2.2 写入 plan.md，按 2.3 自审（范围闸门 + 8 项），核对 2.4 并发硬规则（explore ≤5 并行 / general 串行 / BASE=上一 HEAD）。
-  适用：work agent 第一步规划到派发前的「规划 → 落单」环节。
-  不适用：执行/派发/审查/产物目录与 Ledger（用 work-ledger）；非 work 流程的普通规划。
-license: MIT
-metadata:
-  workflow: sequential
----
-
-# work-plan 技能
-
-## 触发时机
-
-work agent 完成第一步解析用户输入（`target`/`root_dir`/`constraints` 三字段）后、派发任何 subagent 前加载本技能，执行「任务拆分 → 字段填写 → plan.md 落盘 → 计划自审」。
-
-## 输入
-
-从 work.md 流程传入三个贯穿全程的字段：
-
-| 字段 | 说明 | 默认 |
-|------|------|------|
-| `target` | 要达成的目标（定义验收标准，第五步按它判定成败） | 必填 |
-| `root_dir` | 工程根目录（所有任务路径、`writable`/`forbidden`、prompt 内路径、bash 命令的基准） | 当前工作目录 |
-| `constraints` | 约束（不改的文件、禁止的操作等；展开为全局禁改/禁操作清单，每个任务的 `forbidden` 至少包含它的全部内容） | 无 |
-| `doc_dir` | 产物目录绝对路径（来自 work-ledger，`plan.md` 写入其下） | 必填 |
-
-## 工作流程
-
-### 阶段 1：加载 references
-
-用 `read` 工具加载本技能 `references/` 下的全部流程文件（相对路径基于本 skill 目录）：
-
-- `references/split-rules.md` → 1.1 任务拆分规则（第一约束、拆分维度、3 个反模式、不需要拆分的情况）
-- `references/task-fields.md` → 2.1 任务 11 字段 + agent 类型选择 + 2.4 并发硬性规则
-- `references/plan-file.md` → 2.2 plan.md 持久化格式
-- `references/self-review.md` → 2.3 计划自审（范围闸门 + 8 项）
-
-### 阶段 2：任务拆分
-
-按 `references/split-rules.md` 的规则，把 `target` 拆成任务列表（可能仅 1 个任务）。
-
-### 阶段 3：填写任务字段
-
-按 `references/task-fields.md` 为每个任务填写全部 11 个字段：
-`task_id`/`goal`/`files`/`interfaces`/`accept`/`verify`/`agent`/`writable`/`forbidden`/`depends`/`budget`。`agent` 类型与并发安排按同一文件的规则与 2.4 硬性规则确定。
-
-### 阶段 4：写 plan.md
-
-按 `references/plan-file.md` 的模板，将完整计划写入 `<doc_dir>/plan.md`（`doc_dir` 的确定见 work-ledger skill）。
-
-### 阶段 5：计划自审
-
-按 `references/self-review.md` 先查范围闸门（任务数 >20 暂停向用户确认），再逐项自检 8 项；任何一项不通过则修正计划后再进入派发。
-
-## 输出
-
-- 完整任务计划（写入 `<doc_dir>/plan.md`，compaction 后恢复用）
-- 每个任务的 11 字段已确定，可供派发 implementer / reviewer 使用
-- 本技能**不派发、不执行、不写任务 brief**（派发与 Ledger 属 work agent 流程的其他环节）
-
-## 约束
-
-- 拆分第一约束：每个任务 ≤10 分钟可完成，且能独立写出可布尔判定的 `accept`；超预算必须继续拆，宁可多小任务串行。
-- 反模式禁止：按 TDD 步骤拆 / 按文件数硬拆 / 一个任务塞多个不相关目标。
-- 并发硬规则：`explore`（只读）可并行且 ≤5 个/轮；`general`（可写）必须串行，须在上一任务 review close 后才派发下一个；下一个 `general` 的 `BASE` 自动等于上一任务 `HEAD`。
-- 范围闸门：任务数 >20 或 `target` 无法在 ≤20 个独立验收单元内覆盖 → 暂停规划，向用户确认拆分范围。
-- 本技能不读写代码、不执行验证命令，只产出计划与 plan.md。
-
-## 资源目录
-
-```
-references/
-├── split-rules.md   # 1.1 任务拆分（第一约束/维度/反模式/不需拆分）
-├── task-fields.md   # 2.1 任务 11 字段 + 1.2 agent 类型选择 + 2.4 并发硬规则
-├── plan-file.md     # 2.2 plan.md 持久化格式
-└── self-review.md   # 2.3 计划自审（范围闸门 + 8 项）
-```

package/skills/work-plan/references/plan-file.md

@@ -1,29 +0,0 @@
-# 2.2 计划文件持久化（提取自 docs/plans/work-copy.md L154-176）
-
-规划完成后，将完整计划写入 `<doc_dir>/plan.md`（`doc_dir` 见 work-ledger 第三步，即 `<root_dir>/.webwork/harness/work/<session_id>/`）。
-
-## plan.md 格式
-
-```markdown
-# Plan — target: <target>
-## Global Constraints
-<constraints 原文>
-## Tasks
-### T1: <goal>
-files: ...
-interfaces: ...
-accept: ...
-verify: ...
-agent: ...
-writable: ...
-forbidden: ...
-depends: ...
-budget: ...
-### T2: ...
-```
-
-结构要点：`# Plan — target: <target>` 标题 + `## Global Constraints`（constraints 原文）+ `## Tasks`（下挂 `### T<N>: <goal>` 及全部任务字段）。
-
-## 恢复约定
-
-compaction 后：先读 `plan.md` 恢复计划，再读 `progress.md` 恢复进度。

package/skills/work-plan/references/self-review.md

@@ -1,18 +0,0 @@
-# 2.3 计划自审（提取自 docs/plans/work-copy.md L178-191）
-
-## 范围闸门（先于逐项自检，人工确认点之一）
-
-若任务数 > 20，或 `target` 无法在 ≤20 个独立验收单元内覆盖 → **暂停规划**，向用户确认拆分范围（本次只做 A 部分，还是分批多次运行）。避免大 target 在规划期就写爆 plan、派出一堆任务，直到运行时总预算才触发。
-
-## 逐项自检（8 项）
-
-产出计划后逐项自检，**任何一项不通过则修正后再派发**：
-
-1. **Spec 覆盖**：`target` 的每个要求是否有任务覆盖？列出未覆盖的 gap 并补任务。
-2. **接口一致性**：跨任务的类型名、函数签名、属性名是否匹配？T1 Produces 的 `clearLayers()` 在 T3 中是否也叫 `clearLayers()` 而非 `clearFullLayers()`？
-3. **占位符扫描**：有无 "TBD"、"加错误处理"、"类似 T1"、"按需实现" 等模糊描述？有则补具体。
-4. **依赖完整性**：`depends` 引用的 `task_id` 是否存在？有无循环依赖？有依赖的任务是否串行？
-5. **文件所有权分区**：可写任务（`general`）强制串行，故无并发写冲突；只读任务（`explore`）不产生文件变更。此条仅用于校验 `files`/`writable` 不落在 `constraints` 禁改范围之内。
-6. **路径合规**：`writable`/`forbidden`/`files` 都落在 `root_dir` 内且不与 `constraints` 冲突。
-7. **验收可判定**：每条 `accept` 是否可布尔判定？`verify` 命令是否具体可执行？
-8. **工时约束**：每个任务的 `budget` 是否 ≤10 分钟？超过的必须继续拆。

package/skills/work-plan/references/split-rules.md

@@ -1,23 +0,0 @@
-# 1.1 任务拆分（提取自 docs/plans/work-copy.md L65-82）
-
-所有任务都必须经过规划→派发→review 流程，无论任务是 1 个还是多个。
-
-## 拆分第一约束
-
-每个任务必须在 10 分钟内可完成，且能独立写出可布尔判定的 `accept`。这是 subagent 的硬预算（implementer 最多 50 次工具调用）；超过预算的任务必须继续拆，直到每个子任务都在预算内。宁可拆成多个小任务串行，也不要留 1 个超出预算的任务。若平台支持 `maxSteps`，用它作为工具调用次数的硬兜底。
-
-## 拆分维度
-
-按可独立验收的单元拆。一个任务拆出来后，必须能独立写出 `accept` 验收标准，reviewer 能不依赖其他任务的结果就判断它是否完成。如果 accept 必须引用其他任务的中间产物，说明拆错了边界。
-
-## 拆分反模式（禁止）
-
-| 反模式 | 问题 |
-|--------|------|
-| 按 TDD 步骤拆（RED 一个任务、GREEN 一个任务） | TDD 是一个任务内的流程，拆开导致 RED 任务的测试代码无法独立验收 |
-| 按文件数硬拆（每个文件一个任务） | 一个验收单元可能跨多文件，强行按文件拆产生大量微依赖 |
-| 一个任务塞多个不相关目标 | subagent context 膨胀，focus 下降 |
-
-## 不需要拆分的情况
-
-- 单一验收单元，预计 ≤10 分钟，不可再分（派 1 个 subagent）。

package/skills/work-plan/references/task-fields.md

@@ -1,44 +0,0 @@
-# 2.1 任务字段（提取自 docs/plans/work-copy.md L133-151）
-
-产出任务计划，每项含全部 11 个字段：
-
-```
-task_id:      T1 / T2 / ...
-goal:         目标，≤1 句话，可验收（必须服务于 target 的验收标准）
-files:        Create: path/to/new.ts | Modify: path/to/existing.ts:120-145 | Touch: path/to/config.json
-              （路径相对 root_dir；为空 ⇒ 该任务不涉及文件改动）
-interfaces:   Consumes: funcA(x: string) → number（来自 T1，T2 需调用）
-              Produces: class Foo { bar(): void }（本任务产出，供后续任务使用）
-              （无跨任务接口依赖时填 无）
-accept:       验收标准，≤3 条，每条可布尔判定（如 "Foo.bar() 返回 true"、"npm test 通过"）
-verify:       验证命令（如 `npm test -- src/foo.test.ts`；无测试时填 `无`）
-agent:        explore（只读调研）| general（执行改动/多步）— 选择规则见下
-writable:     可写文件白名单（为空 ⇒ 该任务只读；路径相对 root_dir；须与 files 的 Create/Modify 一致）
-forbidden:    禁改文件清单（至少含 constraints 全部内容）
-depends:      依赖任务：T1, T3（必须先完成）| 无
-budget:       预计 ≤10 分钟
-```
-
-## 1.2 agent 类型选择（提取自 L84-100）
-
-| agent 类型 | 适用场景 | 工具权限 |
-|-----------|---------|---------|
-| `explore` | 只读调研：搜索代码、读取文件、理解结构、验证假设 | read/grep/glob（只读） |
-| `general` | 可写改动：编辑代码、执行命令、多步实现、写测试 | 全部工具 |
-
-**选择规则**：
-- 任务涉及任何文件创建/修改/删除 → `general`
-- 任务只读不改（调研、审查、验证） → `explore`
-- 不确定时按 `general`（权限更大不会卡住）
-
-**注意**：审查类 subagent 取 `general`（需写审查文件），以 prompt 强约束「只读源码 + 写白名单仅审查文件」；审查处于任务串行链上，天然满足串行。
-
-## 2.4 并发硬性规则（提取自 L193-200）
-
-- **并发分型（Git 隔离的核心约束）**：
-  - `explore`（只读）**绝不提交、绝不改写工作树/index/HEAD**，只做搜索/读取/理解；可并行，**≤ 5 个/轮**。
-  - `general`（可写）**必须串行**，同一轮最多 1 个在跑，且须在上一任务的 review close 后才派发下一个；下一个 general 的 `BASE` 自动等于上一任务的 `HEAD`，保证 `BASE..HEAD` 恰好是本任务自己的改动。
-- 凡任务可能产生任何文件或 git 变更，一律 `general`（从而落入串行）。
-- 串行还是并行由 `depends` 字段 + agent 类型共同决定：有依赖必须串行；无依赖但写操作同样串行；仅只读任务可并行。
-- 一个 subagent 对应一个可独立验收的任务，不把多个不相关目标塞给一个 subagent。
-- 状态如需跨轮保留，把状态写进 Ledger/文件，不要依赖子代理记忆。

package/skills/work-recovery/SKILL.md

@@ -1,80 +0,0 @@
----
-name: work-recovery
-description: |
-  [work 专属 runbook] 仅供 work agent 通过 skill 工具显式调用（name=work-recovery），其他 agent / 普通对话禁止触发
-  恢复与护栏技能：覆盖重规划（触发条件 3 种、规则=复用 session_id/增量调整/不重做已完成、上限 3 轮超限升级用户）+ 退出条件（target 验收/重规划≤3/阻塞/预算超限/ESCALATE）+ 预算与超时（单任务超时=平台 timeout 优先/否则 prompt 软上限+maxSteps 硬兜底、等待纪律有界等待不静默阻塞、总预算护栏 4 项≤20 任务/≤30 分钟/并行≤5）+ 中断与回滚（用户中断保留现场、回滚限本任务 BASE..HEAD/工作树脏禁--hard/forbidden 文件强制 checkout/绝不 reset 早于 initial_base）+ 防失控护栏 5 条。
-  适用：work agent 运行期遇到计划级失败 / 超时 / 中断 / 需回滚 / 防失控检查时加载。
-  不适用：单任务 review fix（用 work-review）；最终交付（用 work-finalize）；非 work 流程的普通恢复。
-license: MIT
-metadata:
-  workflow: on-demand
----
-
-# work-recovery 技能
-
-## 触发时机
-
-work agent 运行期遇到以下任一情况时加载本技能对应阶段：
-
-- 计划级失败（多任务失败 / 某任务反复失败且换模型拆任务均无效 / 计划自审结构性冲突在实现后成真）→ 加载 `references/replan.md`
-- 判定退出（target 验收 / 重规划超限 / 阻塞 / 预算超限 / ESCALATE）→ 加载 `references/budget.md` 退出条件段
-- 单任务超时 / 等待 child / 总预算护栏检查 → 加载 `references/budget.md` 预算段
-- 用户中断 / implementer 提交有误需回滚 / forbidden 文件被改 → 加载 `references/rollback.md`
-- 防失控周期自检 → 加载 `references/rollback.md` 护栏段
-
-## 输入
-
-从 work.md 流程传入：
-
-| 字段 | 说明 | 默认 |
-|------|------|------|
-| `target` | 要达成的目标（退出条件按其验收标准判定） | 必填 |
-| `root_dir` | 工程根目录 | 当前工作目录 |
-| `doc_dir` | 本次 session 产物目录（Ledger / plan.md 所在） | 必填 |
-| `session_id` | 本次 session id（重规划复用，不新开） | 必填 |
-| `initial_base` | 本次运行最初的 base（回滚绝不 reset 早于它） | 必填 |
-| `constraints` | 全局禁改/禁操作清单（forbidden 文件判定基准） | 无 |
-
-## 工作流程
-
-### 阶段 1：加载 references
-
-用 `read` 工具按触发原因加载本技能 `references/` 下对应文件（相对路径基于本 skill 目录）：
-
-- `references/replan.md` → 重规划（触发条件 3 种、规则=复用 session_id/增量调整/不重做已完成、上限 3 轮超限升级用户）
-- `references/budget.md` → 退出条件（5 种）+ 预算与超时（单任务超时 / 等待纪律 / 总预算护栏 4 项）
-- `references/rollback.md` → 中断与回滚（用户中断 / 回滚规则 / forbidden 强制 checkout）+ 防失控护栏 5 条
-
-### 阶段 2：按触发分支执行
-
-- **重规划**：按 `references/replan.md` 复用同一 `session_id`/`doc_dir`/Ledger，只重走第二步对未完成目标重新拆分并更新 `plan.md`，已完成任务保留标记 done 不重派发；Ledger 记 `replan round <R>/3`；最多 3 轮，超限升级用户。
-- **退出判定**：按 `references/budget.md` 退出条件 5 种逐项检查，命中即停止派发并如实报告。
-- **预算与超时**：派发 subagent 时优先用平台 `timeout`/`cancel`/后台执行；不支持则用 prompt 软上限（implementer ≤50 / fix ≤20 / reviewer ≤15）+ `maxSteps` 硬兜底；等待期有界等待不静默阻塞；总预算护栏 4 项超限即停派发记 Ledger 报告用户。
-- **中断与回滚**：用户中断立即停派发 + cancel 在途 + 记 Ledger + 保留现场；回滚限本任务 `BASE..HEAD`（BASE 从 Ledger `T<N>: base=` 读取），工作树脏禁 `--hard` 改用 `git revert` 或 `git reset --soft` + 手动 checkout，forbidden 文件强制 `git checkout -- <file>`，绝不 reset 早于 `initial_base`。
-- **防失控自检**：按 `references/rollback.md` 护栏 5 条周期自检（并发分型 / task 预算 / scoped re-review / Round 5 后裁决 / 外部信息用 general+webfetch）。
-
-## 输出
-
-- Ledger 条目（`replan round <R>/3` / `T<N>: timeout` / `T<N>: interrupted by user ...` / `T<N>: reverted to <sha>` / `T<N>: reverted forbidden <file>` / 总预算超限记录）
-- 更新后的 `plan.md`（重规划时）
-- 本技能**不派发新 subagent**（重规划后的派发由 work agent 主流程按新 plan.md 进行）；**不 push / 不 merge / 不 reset 早于 initial_base**
-
-## 约束
-
-- 重规划复用同一 `session_id`/`doc_dir`/Ledger，是针对失败与未完成部分的增量调整，不重做已完成任务；最多 3 轮，超限升级用户不再自动继续。
-- 退出条件 5 种：target 验收通过 / 重规划 ≤3 轮 / 阻塞无法解除（含与 `constraints` 不可调和）/ 总预算超限 / subagent ESCALATE 且无法通过拆分任务/换模型解决。
-- 单任务超时：平台 `timeout`/`cancel` 优先（硬兜底），否则 prompt 软上限 + `maxSteps` 硬兜底叠加；超时立即记 Ledger `T<N>: timeout` 标 BLOCKED/ESCALATE，不无限同步等待。
-- 等待纪律：有界等待，不轮询短超时也不长时间静默；间隔（如 5 分钟）列一次在途 subagent 追查「已结束但仍未上报」的 child。
-- 总预算护栏 4 项：总任务数 ≤20 / 总运行时长 ≤30 分钟 / 总工具调用或 token 平台可观测时设上限 / 最大并行 explore ≤5；每项超限如实写进 Ledger 并报告，不静默续跑。
-- 用户中断保留现场，不删除产物目录。
-- 回滚仅限本任务 `BASE..HEAD`；工作树脏禁 `--hard`；forbidden 文件强制 `git checkout -- <file>` 恢复；**绝不 `reset` 到早于 `initial_base`**。
-- 防失控护栏 5 条：只读 explore 可并行 ≤5 / 可写 general 必须串行；每个 task ≤10 分钟，失败先换模型/拆任务再重规划；每轮 fix 后必须 scoped re-review；Round 5 后才裁决，每条裁决都是 Ledger 条目禁止静默丢弃；需要外部信息用 `general` + `webfetch` 调研不嵌套再派发。
-
-## 资源目录
-
-```
-references/
-├── replan.md     # 重规划（触发 3 种/规则/上限 3 轮）
-├── budget.md     # 退出条件 5 种 + 预算与超时（单任务超时/等待纪律/总预算护栏 4 项）
-└── rollback.md   # 中断与回滚（用户中断/回滚规则/forbidden 强制 checkout）+ 防失控护栏 5 条
-```

package/skills/work-recovery/references/budget.md

@@ -1,40 +0,0 @@
-# 退出条件
-
-- 对照 `target` 验收标准，所有任务 `done`、review 通过 **且整体验收通过**
-- 重规划 ≤3 轮（整体步骤用平台最大步数配置兜底，如 `maxSteps`）
-- 阻塞无法解除（含与 `constraints` 不可调和）
-- 总预算超限（见「预算与超时」）
-- subagent 返回 ESCALATE 且无法通过拆分任务/换模型解决 → 如实向用户报告
-
-# 预算与超时（总预算 + 单任务超时）
-
-## 单任务超时（技术强制优先）
-
-- 派发 subagent 时，若 `task` 工具支持 `timeout` / `cancel` / 后台执行，必须显式带超时；超时后主 agent 立即记 Ledger `T<N>: timeout` 并标记 `BLOCKED`/`ESCALATE`，**不无限同步等待**（避免主 agent TUI 卡死）。
-- 若平台不支持超时/取消，仍以 prompt 级硬约束（implementer ≤50 / fix ≤20 / reviewer ≤15 次工具调用）为软上限，并在派发后主动推进，不静默阻塞。
-- 二者关系：prompt 中的工具调用上限是**软约束**，平台能力（timeout / maxSteps）是**硬兜底**，叠加使用。
-
-## subagent 强制退出配置（实施细节）
-
-1. **`steps` 配置位置**：应配在 **subagent 定义**上（`agent.general.steps=50` / `agent.explore.steps=30`），不是 work agent 上——"卡住"的是 subagent（foreground 下 work 被 block），steps 达限强制结束的是被配置方。work 自身可加 `steps`（如 200）防 runaway，但次要。
-2. **background 模式启用**：在 opencode 配置中设 `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true`，task 工具的 `background=true` 参数才生效——subagent 异步运行，主 agent 不 block，完成时自动通知注入结果。
-3. **escape 中断语义**：TUI `session_interrupt`（escape）中断的是**整个 session**（含所有子 session），不是只中断子 session。中断后可通过 `git log` + Ledger 恢复续跑。
-
-## 等待纪律（不静默阻塞）
-
-- 派发后不停摆：等待期间继续做本地工作（写 Ledger、准备下一个 review package、读已返回的报告）。
-- 空闲等待用**有界等待**：不轮询短超时，也不长时间静默；间隔一段（如 5 分钟，若平台允许）列一次在途 subagent，追查「已结束但仍未上报」的——child 的结果可能丢失，而 timeout 抓不到这种「结果丢了」的失败。
-- 发现 child 卡死/丢失：按单任务超时处理，记 Ledger `T<N>: timeout` 并标 BLOCKED/ESCALATE。
-
-## 总预算护栏（防失控）
-
-主 agent 侧维护一份总预算，超限即停止派发、记 Ledger、报告用户：
-
-| 预算项 | 建议值 | 超限动作 |
-|--------|--------|---------|
-| 总任务数 | ≤ 20 | 规划期由 2.3 范围闸门拦截；运行时超限停止拆分，评估重规划或升级用户 |
-| 总运行时长 | ≤ 30 分钟 | 停止派发，记 Ledger，报告用户 |
-| 总工具调用 / token | 平台可观测时设上限 | 同上 |
-| 最大并行 explore | ≤ 5（见 2.4） | 等待，不超额派发 |
-
-每项超限都**如实写进 Ledger** 并报告，不静默续跑。

package/skills/work-recovery/references/replan.md

@@ -1,21 +0,0 @@
-# 重规划（计划级失败恢复）
-
-计划级失败时主 agent **自主重新规划**，只针对失败/未完成的目标，不打断用户、不重做已完成任务。
-
-## 触发
-
-单任务失败先走第四步的「换模型 / 拆任务」；当以下任一成立，进入重规划：
-
-- 一轮计划中多个任务失败，暴露计划本身的问题（任务边界 / 依赖 / 验收标准定义错误）；
-- 某任务反复失败，且「换模型 / 拆任务」均无效；
-- 计划自审（2.3）发现的结构性冲突在实现后成真。
-
-## 规则
-
-- 复用同一 `session_id` / `doc_dir` / Ledger：历史与已完成提交不丢；重规划是**针对失败与未完成部分的增量调整**。
-- 只重走第二步：重读 `target`，对未完成目标重新拆分，更新 `plan.md`；已完成任务条目保留并标记 done，不重新派发。
-- Ledger 记 `replan round <R>/3`（`<R>` = 第几轮）；重规划后照常走派发 → review → fix 循环。
-
-## 上限
-
-- 最多 3 轮重规划；超限 → 升级用户，如实报告，不再自动继续（见「退出条件」）。

package/skills/work-recovery/references/rollback.md

@@ -1,20 +0,0 @@
-# 中断与回滚
-
-## 用户中断
-
-- 收到用户中断后：立即停止派发新 subagent；对在途 subagent 发送 cancel（若平台支持 `cancel`）；记 Ledger `T<N>: interrupted by user (commits <base7>..<head7>, uncommitted: <files>)`。
-- **保留现场**：不删除产物目录，便于续跑或复盘。
-
-## 回滚
-
-- implementer 提交有误：回滚限定在本任务 `BASE..HEAD`（BASE 从 Ledger `T<N>: base=` 读取）。**若工作树干净**可用 `git reset --hard <BASE>`；**若工作树脏**（含起始检查中用户选择保留的脏文件），禁止 `--hard`（会连同脏文件一起丢弃），改用 `git revert <task commits>` 或 `git reset --soft <BASE>` + 手动 checkout 目标文件。回滚后在 Ledger 记 `T<N>: reverted to <sha>`。
-- **forbidden 文件被改**：reviewer 检测到 `writable` 白名单外的变更（含 `constraints` 禁改文件）→ 记 Critical finding，强制 `git checkout -- <file>` 恢复，并在 Ledger 记 `T<N>: reverted forbidden <file>`。
-- 回滚仅限本运行产生的提交，**绝不 `reset` 到早于 `initial_base`**。
-
-# 防失控护栏
-
-1. 并发分型：只读 `explore` 可并行 ≤5；可写 `general` 必须串行（同一轮最多 1 个），杜绝并发写冲突与 review diff 污染。
-2. 每个 task 预算 ≤10 分钟；worker 失败先换模型/拆任务重试，仍失败则重规划失败部分（见「重规划」）。
-3. 每轮 fix 后必须 scoped re-review，未审查的 fix 是回归的来源。
-4. Round 5 后才裁决，每条裁决都是 Ledger 条目，禁止静默丢弃。
-5. 需要外部信息时用 `general` + `webfetch` 调研，不在子代理里嵌套再派发。