@cr1992/agentkit 1.0.0

package/docs/verify/verification-protocol.md

@@ -0,0 +1,76 @@
+# 一次性独立 verifier 协议
+
+本文件是 reviewer 行为、输入隔离、证伪步骤和三态 verdict 语义的唯一真源。runtime 校验结构与
+绑定；L1 的语义判断仍由新上下文 reviewer 完成。
+
+## 输入
+
+只给 reviewer 四类信息：
+
+1. 冻结 Task Contract；
+2. 冻结 Artifact Ref 与只读产物；
+3. Verification Profile 中的 L0 入口和 L1 lenses；
+4. runtime 生成的 reviewer view：逐条 acceptance、稳定 ID 与必要证据指针。
+
+禁止提供实现者对话、思考过程、自述、上一轮完整报告或“预期通过”的暗示。允许为复核修复提供
+上一轮 finding 的结构化事实，但不提供其方法论与叙事。
+
+## 证伪任务
+
+```text
+你是独立验收者。任务不是确认实现已完成，而是寻找冻结 Artifact 不满足 Task Contract 的证据。
+
+1. 只审查给定 Artifact，不修改业务产物、合同、Profile 或验证定义。
+2. 对照 reviewer view 的每个 contract_item_id 和 lenses 主动构造边界情况。
+3. 不采信实现者提供的测试结论；L0 由 runtime 负责，L1 只引用可复核产物或复现证据。
+4. protected_verifier_paths 有变化时，逐项确认是否被 allowed_validation_changes 精确授权；
+   弱化验收或越权修改属于 verification_definition finding。
+5. 输出 fail、no_defect_found、undecidable 三态之一。无法获得会改变结论的真源或证据时必须
+   undecidable，不用低保证结果替代。
+6. safety finding 不能被其他通过项抵消。
+```
+
+视觉与主观结果仍须从设计稿、协议、计划等裁决真源独立推导。涉及图层合成时核对整组图层，按
+“参数 < 导出渲染 < 原生渲染”逐级提高证据；最高必要证据不可得且影响结论时输出 `undecidable`。
+
+## Review Result v1
+
+```json
+{
+  "schema_version": 1,
+  "review_result_id": "uuid",
+  "contract_digest": "sha256:...",
+  "verification_profile_digest": "sha256:...",
+  "artifact_ref": {},
+  "challenge_nonce": "controller-issued-nonce",
+  "verdict": "fail | no_defect_found | undecidable",
+  "findings": [
+    {
+      "contract_item_id": "stable-id",
+      "class": "functional | scope | verification_definition | safety",
+      "evidence": "artifact or reproduction evidence",
+      "expected": "contract requirement",
+      "actual": "observed result"
+    }
+  ],
+  "forensics": ["实际读取、构造或比对的证据"],
+  "review_result_digest": "sha256:..."
+}
+```
+
+约束：
+
+- `contract_digest`、`verification_profile_digest`、`artifact_ref` 和 `challenge_nonce` 必须从当前
+  `review-input` 原样复制，不得由 controller 在 reviewer 输出后补写，也不得复用其他 run 的 Review Result；
+
+- `fail` 的 findings 非空，每条字段完整且引用已冻结 acceptance ID；
+- `no_defect_found` 的 findings 为空、forensics 非空；它只表示在取证范围内未发现缺陷；
+- `undecidable` 至少包含一条 finding，说明缺失证据及其对应 acceptance；
+- 任何 safety finding 都使最终 outcome 至少为 `blocked_safety`；
+- reviewer 不填写 L0 exit code，不生成 Evidence，不宣布 Goal 或全局任务完成。
+
+## 回传
+
+一次性模式将 Review Result 交还 runtime 后停止。若上层 Loop 决定继续，只把 findings 的
+`contract_item_id / class / evidence / expected / actual` 回传 implementer，不回传 reviewer 的隐藏
+推理或完整取证方法论。

package/docs/worktree/batch-integration.md

@@ -0,0 +1,176 @@
+# 批量集成验收契约
+
+## 选择模式
+
+- **分支矩阵**：各 feature 相互独立，只需批量跑检查。固定每个 SHA 后分别验收，不建集成树。
+- **合成候选**：需验证交叉文件、编译、运行时或用户链路兼容性。每批、每仓创建一棵一次性候选树。
+
+选哪个由 SKILL.md 第 8 节的口径决定：同一仓库、同一目标分支的并行输入 ≥3 时默认走合成候选——此时
+"互不触碰"的人工评估视为不可信，不得据它豁免；=2 时按三条判据走，交叉面成立即合成。跨仓或目标
+分支不同的输入不计入同批。
+
+不维护长期共享 integration 分支。长期分支会混入旧 feature，无法证明报告对应哪组输入。
+
+集成候选也**不作为 change request 载体**。它的产出是一份"这组输入合成后兼容"的验收结论；合入仍按
+可独立评审、合入和回退的交付单元分别进行。用聚合载体代替各自载体会同时失去评审独立性、回退
+粒度，以及各输入自己的合入监听。
+
+## 输入契约
+
+`plan-batch` 的 selector 只能指向当前 repository identity 的 tracked record。调用者先按项目规则 fetch target，工具本身保持离线只读。
+
+计划只接受：
+
+1. `task_status` 为 `ready_for_review` 或 `integrating`。
+2. worktree 存在且干净，没有 merge/rebase/cherry-pick/revert 中间态。
+3. live HEAD 等于 trace `last_head`。
+4. upstream 存在且指向同一 HEAD，证明精确产物已推送。
+
+工具会先排除 target 已包含的 HEAD，再按 Git 祖先关系折叠重复/父分支。`included` 保留用户给定顺序；顺序参与 fingerprint，不得在合成时重排。
+
+fingerprint 只绑定 target SHA 和有序输入 SHA，不纳入本机路径、repository UUID 或平台默认目录，因此同一组 Git 对象在不同宿主上保持一致。验收契约与环境指纹另外记录；它们变化时即使 Git fingerprint 未变，报告也必须标记 `stale`。
+
+## 冻结前的冲突预测
+
+冲突对和冲突文件如果只在真的合到一半时才暴露，合并排序和"这两支是不是该并成一支"就都成了事后
+补救。`plan-batch --scan-conflicts` 把这份信息提前到规划期。
+
+**形态是 `plan-batch` 的附加输出，不是独立子命令。** 理由：矩阵要针对的恰好是这份计划**冻结下来的
+那一组输入**——同一批 selector、同一个 target、同一套折叠与准入规则（dirty / HEAD 漂移 / 未推送的
+输入根本不该进矩阵，否则读到的是不可复现的现场）。独立子命令得把选择器解析、准入和折叠再实现
+一遍，两套口径迟早漂移。因此扫描只挂在 `cmdPlanBatch` 上，**不进 `computeBatchPlan`**：后者同时是
+`batch-integrate` 的新鲜度重算口径，把扫描塞进去会让每次合成都白跑一遍 `merge-tree`，也会把决策
+辅助信息混进"必须逐项比对"的冻结契约。指纹只绑 SHA，加不加 flag 都一样。
+
+干跑用 `git merge-tree --write-tree`：合并在**对象库**里算完，只产生未被任何 ref 引用的临时
+tree/blob（随 gc 回收），不动工作区、index、HEAD 和任何 ref，因此可以在 `plan-batch` 的只读语义下
+跑，也不需要先建候选树。
+
+**冲突判定只认退出码，不认文件条目数。** git-merge-tree(1) 的 EXIT STATUS 是 0=可自动合并、
+1=有冲突、其他=Git 自身失败；同一页的 MISTAKES TO AVOID 明确写着不得把空的 Conflicted file info
+当成干净合并——有几类目录重命名冲突就是退出码 1 却没有任何 unmerged 文件条目。按条目数判 clean
+会把真冲突报成"没事"，这是最坏的一种错。这类格子的信息全在 `conflict_notes` 里，人读输出用
+`[NOTE]` 单独打出来。
+
+**Git ≥ 2.39。** `merge-tree --write-tree` 2.38 就有，但本扫描依赖 `-z` 信息段里的结构化 NUL 记录
+（`<路径数>NUL<路径>...NUL<conflict-type>NUL<message>NUL`，其中 `<conflict-type>` 是 man page 明说的
+stable string）；2.38 的 `-z` 信息段还是自由文本，按结构化格式去解会把消息当类型，冲突类型粗分
+随之错判。与其写一段本机无法实测的 2.38 兼容分支，不如把线抬到 2.39 并 fail-closed 降级：低版本
+整段回报 `supported: false` 并说明原因，计划本身照常冻结——**宁可没有矩阵，不要一份可能错的矩阵。**
+
+输出结构（`conflict_scan`）：
+
+- `pairs[]`：两两干跑。每对给 `merge_base`、`conflict_files`、`adjacent_files`、`state`、
+  `files[]`、`files_total`、`conflict_notes[]`。
+- `state` 五态：`conflict`（退出码 1）、`adjacent`（可自动合但有同文件相邻）、`clean`、
+  `incomplete`（能自动合，但相邻面没算出来）、`error`（merge-tree 自身失败）。
+- `adjacent_files` 允许为 `null`，表示相邻面**未知**（merge base 解析不了、`git diff` 失败或超时）。
+  未知一律显式标注，绝不退化成 `0`——空集会被读成"确认没有相邻文件"，那是静默降级。汇总里
+  `incomplete_pairs`、`unknown_adjacency_rows`、`pathless_conflict_pairs` 分别计数，人读输出在存在
+  未完成格子时打 `[WARN]`：矩阵不完整就不能据它断言"没有冲突"。
+- `against_target[]`：每个输入各自对 target 干跑一次。它常常全是 `clean`——这恰好说明冲突只在
+  "合到一起"时出现，正是矩阵要提前暴露的东西。
+- `files[].class` 三分：`overlapping`（Git 报的内容冲突，同 hunk）、`structural`（改/删、重命名、
+  distinct types 这类非内容重叠冲突，处置方式和挑 hunk 完全不同）、`adjacent`（两支相对
+  merge base 都改了同一文件，但能自动合）。`adjacent` 单独成类是因为语义冲突只会藏在这一格，
+  机器判不了，必须交给人看清单。
+- **截断只发生在展示层。** `files[]` 每对上限 50 项并置 `files_truncated`，但 `files_total`、
+  `conflict_files` 和 `summary.regenerated_paths` 都跑在**未截断的全量清单**上——先截断再统计会让
+  排在 50 项之后的 lock/golden 从产物类汇总里凭空消失，而那恰恰是最需要被看见的一类。
+- `files[].regenerated`：命中 lock / golden / codegen / dist 这类"只能在合成态重新生成"的产物
+  （见 Profile 的 `post_integrate_steps`）。命中只是提示，portable core 不猜也不代跑生成命令。
+- `summary.inputs[]`：按冲突面降序，直接支撑"冲突面大的压轴"这条排序口径。排序主键是
+  `conflicting_peers` 而不是 `conflict_files`——没有文件条目的目录重命名类冲突同样是真冲突，
+  不能因为 `conflict_files=0` 被排到干净输入后面。
+
+**已知边界**：两两干跑预测的是**成对**冲突，实际合成是顺序累积的三方合并，两两干净不等于合成一定
+干净。矩阵是决策输入，不是通过证明，替代不了 `batch-integrate` 的实合与门禁。
+
+## 候选树状态
+
+```text
+collecting -> planned -> composing -> verifying -> passed / failed / stale -> reclaimed
+```
+
+- `planned`：保存 fingerprint、target SHA、有序输入 SHA。
+- `composing`：只有一个 controller/integrator 写候选树。
+- `verifying`：候选树已干净，验收器只读候选 SHA。
+- `failed`：区分 composition conflict 和 test failure，不把冲突修复混入候选树。
+- `stale`：target、输入、顺序或验收契约任一变化。
+
+## 合成执行
+
+`batch-integrate` 负责 `planned -> composing` 这一段，并只负责这一段：
+
+- **新鲜度**：按**原始 selector 全集**（计划中的 `requested_selectors`）重算，与冻结计划逐项比对
+  repository identity、target ref/SHA、有序输入、被折叠/已合入输入集合和 fingerprint；任一漂移或
+  重算出现 blocker 即拒绝，要求重新 `plan-batch`。只回算 `included` 是不够的：被折叠的父分支后来
+  前进时，指纹不变的假象会让那部分改动被静默漏出合成结果。不存在"就地放行"的旁路。
+- **候选身份**：同 fingerprint 幂等复用；fingerprint 变化视为新的一次性候选，另起 semantic task
+  并双向登记替代关系，旧候选先冻结为 `abandoned`。一次性候选不复用交付身份。跨会话只能读取
+  已完成候选的 `already_composed` 结果；任何续合、重置或台账改写前必须先 `handoff` 给当前 controller。
+- **已合成候选不重置**：合成后候选树通常会因执行 `post_integrate_steps` 而前进，HEAD 不再等于
+  `composed_sha`。此时同指纹重跑只做幂等回报，不重置候选、不重置步骤状态；HEAD 既不等于也不是
+  `composed_sha` 后继时 fail-closed 要求人工核对。只有当前 owner 同时提供 `--recompose` 与
+  `--recompose-head <候选当前完整 HEAD>` 才可重合成：工具先记录包含 discarded/authorized HEAD 的
+  `batch_candidate_recompose_authorized` event，并在 reset 前再次做 HEAD CAS，防止陈旧授权丢弃新提交。
+- **冲突**：fail-closed 停在冲突处，报告冲突文件、双方来源 SHA 和候选树路径；不自动解、不自动
+  abort。人工裁决属于 controller 的职责，工具只保证现场可读、可复现。
+- **rerere**：候选树默认启用 `rerere.enabled` + `rerere.autoUpdate`（worktree 级配置，不写全局）。
+  两项必须同时生效：只有 `enabled` 时 rerere 会把已录解法写回工作区却不更新 index，合成循环仍会
+  把它判成真冲突，重放形同失效。因此仓库已继承 `rerere.enabled=true` 也不会跳过补齐 `autoUpdate`。
+  自动启用共享 `extensions.worktreeConfig` 时会写一条独立审计事件
+  （`repository_config_extension_enabled`），如实记录覆盖前值，并可区分"本轮写入"与"原本已启用"；
+  Git boolean 通过 `git config --bool` 归一化，`yes/on/1` 不会被误判成未启用。
+  人工裁决并提交一次后，重跑合成会自动重放同一冲突的解法——多轮候选之间不再重复手解。
+  解法缓存位于共享 common dir 的 `rr-cache/`，因此同仓任何 worktree 录下的解法都会被复用；
+  一个错误解法同样会跨候选扩散，需要时用 `git rerere forget <path>` 清除。
+  worktree 级配置依赖仓库 `extensions.worktreeConfig`；`core.bare` / `core.worktree` 非默认值时
+  工具拒绝自动启用并回报原因，不擅自搬动这两个键。
+- **门禁**：`batch-integrate` 不执行任何验收命令。`post_integrate_steps` 只回显、不代跑，执行结果
+  由 `batch-step` 登记。这条边界与"portable core 不执行 Profile 中的任意 shell command"是同一条。
+
+## 验收报告
+
+报告至少记录：
+
+- repository identity、target ref/SHA、plan fingerprint。
+- 有序输入的 task、worktree ID、branch、HEAD、upstream。
+- 候选分支与最终 candidate SHA。
+- 验收契约/环境指纹、每项命令、退出码、证据地址。
+- 结论 `passed` / `failed` / `stale` 及失败归因。
+
+完成门禁后，用 runtime 冻结终态，而不是只把 task 标成 `done`：
+
+```bash
+agentkit worktree batch-result <candidate> \
+  --state passed \
+  --candidate <exact-live-head> \
+  --evidence <evidence.json>
+```
+
+`passed` / `failed` 必须提供结构化 Evidence，且 `contract_digest` 必须非空；`stale` 必须提供
+`--reason`，Evidence 可选，缺少独立合同文件时其 digest 可以为 null。这里的 null 只表达“候选在形成
+可判定验收结论前已失效”，不能用于通过/失败证明。结果一旦写入
+不可覆盖：target、输入、顺序、候选 SHA 或验收合同变化都另起候选。`passed` 还要求 Profile 声明的
+`post_integrate_steps` 已全部 `done` 或 `skipped`；任何 `pending` / `failed` 都 fail-closed。
+
+[`Batch Result schema v1`](../../schemas/batch-result-v1.schema.json) 的 Evidence manifest 只保存有界摘要：
+顶层 `contract_digest` 与 `checks[]`；每项 check 保存稳定 `name`、
+结构化 `environment`、argv 数组、`outcome`、`exit_code` 和带 SHA-256 digest 的 `evidence_refs[]`。不要把
+原始日志、环境变量值、凭证或大块设备输出放入 trace；把它们放在项目认可的证据存储，只登记稳定 ref
+和 digest。environment 键必须是 lowercase 标识符并拒绝 secret/token/password/credential/key 类名称，
+值只接受最长 500 字符的无换行字符串、有限数字或布尔值；这些限制同时写入 schema 与 runtime。
+runtime 绑定 live candidate HEAD、batch fingerprint、target SHA、有序输入 SHA、Evidence
+manifest digest，并把工作完成态收敛为 `task_status=done`；真实验收语义仍只由 `batch_result.outcome`
+表达，`done` 本身不代表通过。
+
+已冻结 `passed` / `failed` / `stale` 的候选如不作为 MR 载体，可按
+[reclaim-and-watch.md](reclaim-and-watch.md) 的证据归档通道回收。归档 ref 只保护当前仓库免受 Git GC，
+不提供跨机器、跨 clone 或远端灾备保证；需要长期/跨机保留时再按项目政策推送专用 ref 或保存 bundle。
+
+Git worktree 只隔离工作目录和 index，不隔离端口、模拟器/设备、Docker 名、外部数据库、用户级 cache 或凭证。项目 wrapper/Profile 必须为并行候选分配独立运行时资源，或显式串行。
+
+## 多仓项目
+
+项目目录可能只是包含多个 Git 仓库的容器。先按 repository identity 分组，每仓独立规划/合成/验收；上层批次台账再绑定各仓 candidate SHA 和跨仓环境测试。不得把一个仓的 worktree 冒充整个项目的集成边界。

package/docs/worktree/delivery-identity.md

@@ -0,0 +1,41 @@
+# Worktree 交付身份
+
+仅在同一 Agent 已有未回收树、需要第二棵树、替代旧树，或发现未登记的并存关系时读取。
+
+## 三种关系
+
+- **复用**：验收结果、目标 ref、写入归属相同且改动面实质重叠。目录或提交历史不够整洁不构成新交付。
+- **并存**：成果能独立评审、合入和回退，依赖确需单独落地，或多个写入者必须物理隔离。不同 MR、
+  branch 或命名只是线索，不能单独证明独立。
+- **替代**：旧树因基线、历史、环境、权限或 owner 问题不能继续。先冻结旧写入，记录旧树到新树、
+  独有改动保存位置和退出条件；迁移结束立即停止旧 watcher、处理旧 change request 并回收。
+
+manager 用真实 `agent-id` 做最小门禁。同一会话已有未回收树时，普通 `spawn` 返回
+`DELIVERY_WORKTREE_EXISTS`。同一交付直接进入旧路径；确属独立并行时说明可独立交付的理由：
+
+```bash
+agentkit worktree spawn independent-release-audit \
+  --agent codex --agent-id <real-thread-id> \
+  --purpose "独立发布审计" \
+  --parallel-reason "与现有改动可独立评审、合入和回退"
+```
+
+替代旧树前先使旧树 clean，并用 `touch ... --status abandoned --note <迁移边界>` 冻结：
+
+```bash
+agentkit worktree spawn current-ios-validation \
+  --agent codex --agent-id <real-thread-id> \
+  --purpose "迁移到新基线" \
+  --supersedes old-ios-validation \
+  --replacement-reason "旧基线不可继续，独有提交已保存"
+```
+
+`--parallel-reason` 与 `--supersedes/--replacement-reason` 互斥，都是人工裁决后的审计出口。
+存量替代树用 `supersede` 补双向关系，不伪造新树或手改 trace：
+
+```bash
+agentkit worktree supersede old-ios-validation \
+  --by current-ios-validation --reason "旧树已被完整替代"
+```
+
+该命令只接受同一会话、owner 一致且新树不早于旧树的组合，幂等写入双方关系；冲突关系 fail-closed。

package/docs/worktree/profile.md

@@ -0,0 +1,107 @@
+# Repository Profile 与项目适配边界
+
+portable runtime 在没有配置时即可运行。仓库若要固定 base、命名模板、任务来源或 change-request provider，可在 Git primary worktree 根放置 `.worktree-trace.json`。
+
+## 推荐最小 Profile
+
+```json
+{
+  "schema_version": 1,
+  "default_base": "origin/main",
+  "branch_template": "{host}/{task}",
+  "path_template": "{host}-{task}",
+  "task_naming": {
+    "mode": "semantic",
+    "example": "ci-gate-hardening"
+  }
+}
+```
+
+semantic naming 是推荐且默认的安全模式：
+
+- task 必须是 lowercase hyphenated semantic slug。
+- task 至少包含两个以字母开头的词。
+- branch/path 模板必须包含完整 `{host}` 和 `{task}`。
+- semantic 模式禁止 `{id8}` 和 `{task_short}`；内部 identity 只进 metadata。
+
+如果仓库需要兼容既有命名，可以显式选择 legacy `slug` mode，但这会降低可读性；不要为新仓库使用它。
+
+从 legacy `slug` 切换到 `semantic` 时，`doctor` 会把仍活跃但不满足新 DoD 的存量 record 报为 error。这是有意的迁移压力：先完成、handoff 或回收存量树；迁移窗口也可以暂留 `slug`，不要静默改名已有 worktree。
+
+## 可配置内容
+
+Profile 可声明：
+
+- `default_base`：默认基线。primary Profile 启用该字段时必须使用可 fetch 的 `remote/branch` 形式，例如 `origin/main`；本地 `main` 或 `feature/foo` 不属于可刷新配置。
+- `worktree_root`：仓库级集中 worktree 根；CLI `--root` 和 `WORKTREE_ROOT` 优先级更高。显式值不可写时 fail-closed；只有零配置默认 root 才允许 manager 使用安全降级根。
+- `task_naming`、`branch_template`、`path_template`：可见命名约定。
+- collision scan adapter：将仓库自己的任务认领信息并入 dirty/recent-commit 扫描。
+- change-request provider：当前 bundled adapter 支持 GitLab push-options；未配置时走仓库自己的 PR/MR 流程。
+- `post_integrate_steps`：声明"合成之后需要重新生成"的动作（见下）。
+- 无秘密的 prerequisite/doctor 提示。
+
+Profile 是数据，不是任意命令执行入口。不要放 shell command、token、cookie、私钥或个人凭证路径。
+
+`default_base` 应表达仓库当前实际采用的默认基线。需要在版本线与 main 间切换的仓库，应由自己的发布
+流程显式更新该值（例如 `origin/dev/x.y.z` → `origin/main`）。portable core 不扫描 `dev/*` 猜活跃分支，
+也不引入一个与 `default_base` 竞争优先级的隐式覆盖项。
+
+## 合成后再生成步骤
+
+golden 基准、代码生成产物、依赖锁文件这类东西被多个分支各自重新生成时，合成必然冲突，且冲突
+无法靠挑一边解决——只有在合成态重新生成一次才是对的。这类动作高度依赖具体仓库，portable core
+不知道该跑什么，也**不允许**替仓库跑任何命令。
+
+因此 Profile 只**声明**清单，`batch-integrate` 合成完成后只回显它，由 controller 逐条执行，再用
+`batch-step` 登记结果：
+
+```json
+{
+  "schema_version": 1,
+  "post_integrate_steps": [
+    { "name": "regenerate-golden", "hint": "在候选树重跑 golden 生成命令后提交" },
+    { "name": "recompute-lock", "hint": "重算依赖锁文件并确认无版本漂移" }
+  ]
+}
+```
+
+- 每项只有 `name` 与 `hint` 两个键，**没有也不会有 `command` / `run` / `script`**；未知键一律
+  fail-closed，防止有人把 shell 塞进声明位，绕过"portable core 不执行 Profile 内容"这条边界。
+- `name` 是 kebab-case slug、同一 Profile 内唯一，它是 `batch-step` 登记结果的键。
+- `hint` 是给人看的单行说明（≤240 字符），不是可执行内容。
+- 最多 20 项。清单过长通常说明这些动作应当收进仓库自己的一条 wrapper 命令。
+
+显式 `--config <path>` 不执行 primary Profile 的 baseline fetch/drift gate，只读取本地 ref；它适合已经人工核对的离线恢复，不等于自动证明配置新鲜。
+
+## 通用层与项目层
+
+放在本 skill：
+
+- worktree 创建、接管、状态机、event/record trace、审计和保守回收。
+- 通用 dirty/recent-commit collision scan。
+- semantic naming DoD 与 fail-closed 校验。
+- provider 协议和 GitLab push-options adapter。
+
+留在目标仓库：
+
+- `.worktree-trace.json` 与任务系统 adapter 的启用配置。
+- 项目测试、lint、commit gate、构建、签名、视觉验收和部署流程。
+- 特定 app/module 的初始化、凭证 doctor 和 finish wrapper。
+- owner、默认目标分支、MR/PR 审批和 source branch 删除策略。
+
+项目 wrapper 可以先调用自己的门禁，再调用 portable manager 的 `submit`、`watch` 或 `reclaim`；不要把项目目录名或业务判断回写进 portable scripts。
+
+## Kiro tasks adapter
+
+bundled scan 保留一个可选 `kiro_tasks` adapter，用来读取 Profile `glob` 命中的任务文件中实施中的任务及“影响文件或目录”。`glob` 必须是仓库内安全相对路径，支持路径段内 `*` / `?` 和跨目录 `**`，禁止绝对路径、空路径段和 `..`。典型值为 `.kiro/specs/*/tasks.md`。只有 Profile 显式启用时才生效；不使用 Kiro 的仓库不会访问该目录。
+
+新增任务系统时应实现独立 adapter，并保持：
+
+1. 只读目标仓库。
+2. 输出规范化的 owner/task/path claims。
+3. 解析失败时报可诊断错误，不假装 `CLEAR`。
+4. 不把平台或业务名写进 portable collision 算法。
+
+## 同步和分发
+
+本目录中的 `scripts/` 是安装后执行的 portable runtime。项目如果 vendoring 一份副本用于 CI 或 clone 后即用，应记录 upstream 版本并做确定性 diff/check；项目专用 wrapper 不参与同步。

package/docs/worktree/reclaim-and-watch.md

@@ -0,0 +1,96 @@
+# Watch 与保守回收
+
+仅在准备武装、恢复或解除 watcher，以及执行 `reclaim`/`archive` 或诊断 `KEEP/BRANCH_PENDING` 时读取。
+
+## 内容监听
+
+监听绑定“冻结的 head SHA 已成为目标 ref 祖先”这一事实，不绑定 change request 载体。载体改为他人代推、
+聚合 MR 或其他分支时不解除监听。进入 `ready_for_review` 默认武装；`submit` 只是其中一个入口。电脑重启后
+由 `resume-all` 恢复 stale watcher；change request 已关闭且明确不会合入时用 `unwatch`。
+
+## 已推送成果
+
+```bash
+agentkit worktree reclaim <task-or-id> --pushed <sha-or-unique-prefix>
+```
+
+只有无 stash、树干净、branch/HEAD 已进入给定 SHA，才执行：
+
+```text
+final_snapshot -> reclaim_ready -> git worktree remove -> branch cleanup -> reclaimed
+```
+
+终态事件将非 `abandoned` 任务收敛为 `done`，并以最终 source HEAD 闭合 ownership epoch。旧版本若留下
+`reclaimed` 但状态或 epoch 未闭合，重复同一命令会追加 reconciliation event 后再对账。
+
+给定 SHA 还必须由待回收 branch 以外的持久 ref 保护：local/remote branch、tag 或
+`refs/worktree-archive/*` 均可。`--pushed <当前 HEAD>` 但只有候选 branch 自己引用时会被拒绝，因为删掉
+branch 后对象仍会成为 dangling object；这不是“已推送”证据。
+
+`--pushed` 是人体工学例外：接受十六进制唯一短前缀，runtime 用 `rev-parse --verify` 展开后，后续 event、
+可达性和 branch cleanup 全部只使用完整 object ID。`--discard`、Artifact、batch candidate 与 evidence
+archive 仍要求完整 SHA，因为它们承担 CAS 或冻结身份边界。
+
+## 固定 SHA 的批次验收候选
+
+一次性 batch integration candidate 不作为 MR 载体，且正式分支可能用不同 merge topology 合入各输入，
+因此“代码内容已进入目标分支”不等于“设备证据绑定的精确 candidate SHA 已成为目标分支祖先”。先用
+`batch-result` 冻结 `passed` / `failed` / `stale`，再走独立归档回收：
+
+```bash
+agentkit worktree reclaim <candidate> \
+  --archive-evidence <exact-candidate-head> \
+  --reason "固定验收已结束，输入已按正式交付单元处理"
+```
+
+manager 校验终态 `batch_result`、live HEAD CAS、clean/stash/Git 中间态/submodule，并创建
+`refs/worktree-archive/evidence/<worktree-id>`。只有回读 ref 精确等于候选 HEAD 后，才进入通用
+`reclaim_ready -> remove -> branch cleanup -> reclaimed`。trace 保留 fingerprint、target SHA、有序输入、
+结果/Evidence digest 和归档原因；`task_status` 保持 `done`，不把已通过候选伪装成 `abandoned`。
+
+恢复方式：
+
+```bash
+git branch <recovery-branch> refs/worktree-archive/evidence/<worktree-id>
+```
+
+该 ref 是**本地 GC 保护**，不是远端备份。归档 ref 已存在但指向别的提交、用户 SHA 与 live HEAD 不同、
+结果未冻结或 ref 创建后回读失败时均不删除。命令可在 worktree remove 或 branch cleanup 中断后用同一
+参数幂等重跑。`doctor` 用 `DONE_BATCH_CANDIDATE_RESULT_UNRECORDED` 提示只标 done 未冻结结果，用
+`DONE_EVIDENCE_WORKTREE_RECLAIM_PENDING` 提示已冻结但仍占目录的候选。
+
+## 被替代的未推送成果
+
+不得为了清理而推送废弃分支。双向替代关系已经登记后，默认先归档旧 HEAD：
+
+```bash
+agentkit worktree reclaim old-task --superseded-by new-task
+```
+
+默认 ref 是 `refs/worktree-archive/superseded/<old-worktree-id>`。manager 验证旧树为 `abandoned`、会话和
+owner 一致、替代关系双向、替代树干净，并继续执行 stash、dirty、submodule 和目录审计。只有归档创建并
+回读到精确旧 HEAD 后，才删除目录和 local branch；恢复方式为：
+
+```bash
+git branch <recovery-branch> <archive-ref>
+```
+
+人工明确裁定无需恢复时，才允许精确 SHA 授权丢弃：
+
+```bash
+agentkit worktree reclaim old-task \
+  --superseded-by new-task --discard <exact-old-head>
+```
+
+`--discard` 不是布尔开关，SHA 必须与实时旧 HEAD 完全一致；归档和丢弃策略登记后不得互换。
+
+## 故障与不变量
+
+- `abandoned` 只冻结写入，不等于已回收；`doctor` 持续报告残留树和断裂替代关系。
+- 禁止 `rm -rf`、`git worktree remove --force` 和 `branch -D`。
+- branch cleanup 失败时保留 `BRANCH_PENDING`；修复占用后重跑相同 `reclaim`，工具重新验证 branch tip。
+- `git worktree remove` 失败返回非零 `KEEP` 并记录原始错误。即使 Git 登记已解除，物理目录仍在也不能
+  标为 `reclaimed`；先恢复权限或登记关系，不用强删掩盖孤儿目录。
+- 含 submodule 的树逐个验证已初始化工作区干净，再自动 deinit 并清理该树私有元数据。submodule 脏、
+  未初始化目录非空或 `.git` 指针悬空均返回 `KEEP`。
+- worktree 在宿主或沙箱写权限之外时，先取得精确目录的写权限，再重试回收。

package/docs/worktree/review-lifecycle.md

@@ -0,0 +1,92 @@
+# 评审、交接与合入监听
+
+进入 `ready_for_review`、handoff、提交 change request 或处理 watcher 漂移时读取。
+
+## 状态与 watcher
+
+```bash
+agentkit worktree touch <selector> --status blocked --note "等待环境"
+agentkit worktree touch <selector> --status active
+agentkit worktree touch <selector> --status ready_for_review
+```
+
+`ready_for_review` 默认按该树登记的 `base_ref` 武装监听，Profile `default_base` 只在 record 没有 base 时
+兜底；显式 target 与既有人工 target 仍然优先。HEAD 前进时同一 event 使旧 watcher 失效，
+再尝试冻结新 HEAD。worktree dirty、HEAD 未推送或远端主干不可刷新时 fail-soft，状态更新成功但明确
+回报未武装原因。补齐前提后重跑，或用 `--no-watch` 明确接受人工回收。
+
+人工 `watch --target` 可改默认目标；已经显式武装的 target 不被静默改写，换目标先 `unwatch`。陈旧
+watcher 不能覆盖并发 rearm 或 `merge_detected`。旧 SHA 合入不代表新 HEAD 已完成。
+
+### Target 前进与显式评审刷新
+
+watcher 发现 target SHA 偏离本次武装时冻结的 target baseline、且冻结 HEAD 尚未合入时，只读记录一次
+`target_advanced` event，并用 `git merge-tree` 给出三档预判：
+
+- `clean`：`TARGET_ADVANCED_REFRESH_CLEAN`，三方合并干跑无冲突；逐 commit rebase 仍可能不同。
+- `conflict`：`REBASE_NEEDED`，预留人工解冲突时间。
+- `unknown/diverged`：`TARGET_ADVANCED_PREDICTION_UNKNOWN`，不能可靠预判或 target 非快进。
+
+watcher 本身不改写历史、不 push。由人或 controller 显式授权一次刷新：
+
+```bash
+agentkit worktree refresh-review <selector>
+```
+
+命令要求 `ready_for_review`、clean、冻结 HEAD 与远端 upstream 完全一致、target 是登记 base 的快进后继。
+它先登记 `review_refresh` marker，再调用同一 managed rebase 事务；成功后使用绑定旧 upstream SHA 的精确
+`--force-with-lease` 推送，回读新远端 HEAD，更新 change request head 并自动重新武装 watcher。
+
+无项目 wrapper 时，显式调用默认完成 push，后续门禁由远端 CI 和 merge human gate 承担。项目要在
+push 前跑本地门禁时：
+
+```bash
+agentkit worktree refresh-review <selector> --pause-before-push
+# 项目 wrapper 运行 lint/test/sign 等门禁
+agentkit worktree refresh-review <selector> --continue
+```
+
+rebase 冲突时保留 managed intent 与 refresh marker；只编辑冲突并 `git add`，然后运行同一
+`refresh-review <selector> --continue`，它会继续 rebase、push、重冻结和 rearm。仍处于 Git rebase
+冲突态时可用 `--abort` 恢复原 HEAD 与原 watcher。`--pause-before-push` 后项目门禁失败时也可
+`--abort`：manager reset 到 `old_head`，以补偿 event 恢复原 base、ownership 与 change-request 边界，
+重武装原 watcher；已发生的 rebase lineage 保留审计，并追加 rollback 记录。远端 branch 必须仍等于
+冻结旧 HEAD；已经 push、远端被他人更新或分支已删除时拒绝自动回滚。非暂停模式中 rebase 已成功而
+push/凭证/网络失败时用 `--continue` 幂等恢复。远端分支不存在会单独报告，其他 SHA 漂移由精确 lease
+门禁拒绝覆盖。
+
+## Handoff
+
+交接前使树 clean 并 push：
+
+```bash
+agentkit worktree handoff <selector> \
+  --to-agent kiro --to-agent-id <real-task-id> \
+  --note "已完成什么，下一步是什么"
+```
+
+handoff 保存 ownership boundary SHA；脏树拒绝，禁止用 stash 搬运未提交内容。
+
+## Change request
+
+先执行目标仓库自己的测试、commit gate、review 和 push 规则。Profile 已启用 provider 时：
+
+```bash
+agentkit worktree submit <selector> \
+  --title "<title>" --description "<summary>" --notify auto
+```
+
+若 change request 已由 UI/API 创建，用一个 event 原子登记 URL、目标、冻结 HEAD、状态和 watcher：
+
+```bash
+agentkit worktree touch <selector> \
+  --status ready_for_review \
+  --mr "https://gitlab.example/group/project/-/merge_requests/42" \
+  --watch-target origin/main --notify auto
+```
+
+未给 target 时使用 record 的 `base_ref`；远端 MR target 不同时先核对 provider/UI，再显式传
+真实目标。`--mr` 只接受 HTTP(S) URL；纯文本载体使用 `--change-ref`。
+
+watcher 只在冻结 SHA 成为目标 ref 祖先后回收。重启后 `resume-all` 恢复 stale watcher；change request
+关闭且确定不会合入时 `unwatch`。详细回收见 [reclaim-and-watch.md](reclaim-and-watch.md)。