dsh-tower 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 1.3.0 — 2026-10-18
+
+- **独立的只读 reviewer preset**：新增 `reviewer.js` / `tower-reviewer`，去掉 `write`/`edit`/`pwsh`/
+  `tower_mission`/`tower_complete`，只保留读、`tower_diff`、消息、finding、review；`tower_spawn`
+  按 role 映射 preset，reviewer 必须等待 mission `completed`。`tower_review` 会记录 reviewer spawn
+  时的 tip，审查期间改动分支将被拒绝（修复自审风险）。
+- **新增 `tower_diff`**：只读 merge-base diff（files/commits/patch），供 reviewer 使用。
+- **声明 `Config` schema**：`section`/`allowAgentControl` 兼容别名 + `mode`/`review`/`merge`/
+  `worktrees`/`spawn` 分组；评审轮数、合并超时/缓冲、worktree 根、spawn preset/model 等可配置；
+  `mode.storePath`/`maxEntries`/`autoPauseGoal`/`denyTools`/`sectionAppend` 生效。
+- **spawn 健壮性**：preset 存在性预检、按 role 选择 preset/model、失败/空闲状态写回 roster。
+- **内置 Agent Skills**：`skills/tower-worker-protocol`、`skills/tower-review`、`skills/tower-recovery`，
+  通过 `dsh-tower/skills` provider 注册；worker/reviewer preset 允许 `skill`。
+- **文档**：新增 `docs/`（quickstart、安装升级迁移、工具/配置/blocker 参考、架构、运维、安全、FAQ、
+  示例）；README quick start 修正为“先 reviewer 后 preflight 全绿”，工具数/测试数/blocker 数修正；
+  `npm run docs:check` 与 CI 校验文档与代码一致。
+- `package.json` 增加 `@deepseek-ai/schemastery` 依赖、`files` 补充 reviewer/skills/docs/贡献与安全文档。
+- 测试 26 项（新增 preset/skills/config 四个用例）。
+
 ## 1.2.0 — 2026-10-18
 
 - **`tower_merge` 对“提交已落地但调用报错”的恢复**：合并命令失败/超时后检查 `HEAD`，若已是

package/CONTRIBUTING.md

@@ -0,0 +1,36 @@
+# Contributing
+
+Thanks for your interest in `dsh-tower`. This is a DeepSeek Harness plugin; the repository root is the bundle itself (`package.json` + `cordis.patch.yml`).
+
+## Development setup
+
+```bash
+git clone https://github.com/louifinn/dsh-tower.git
+cd dsh-tower
+npm test        # no dependencies to install; Node's built-in test runner only
+```
+
+Requirements: Node.js 22+, Git. No package installation is needed for the offline suite.
+
+## What to change
+
+- `index.js` — Host entry: `/tower` command, mode guard, dynamic prompt section, `tower_control`.
+- `lib/` — the Tower domain (`tower.js`), tool definitions (`tools.js`), persistence (`store.js`, `modeStore.js`), Git helpers (`git.js`).
+- `worker.js` — the `tower-worker` preset policy (tool surface + protocol text).
+- `tests/` — add a regression test for every behavior change. The offline suite is `tests/*.test.mjs`; live-runtime scripts are documented in `tests/README.md`.
+
+## Pull request checklist
+
+1. `npm test` passes locally (26 tests today, including protocol end-to-end against a real temporary Git repository) and `npm run docs:check` passes.
+2. New behavior has a test. Bug fixes should add a test that fails before the fix.
+3. No secrets, tokens, personal paths, session logs, or generated artifacts are added. `.gitignore` covers local acceptance output; do not force-add it.
+4. Keep the public API and state-file formats compatible; if a change is breaking, call it out in `CHANGELOG.md` and bump the version.
+5. Update `README.md` / `README.en.md` when the user-visible behavior changes.
+
+## Commit style
+
+Conventional-commit prefixes are preferred: `feat:`, `fix:`, `docs:`, `test:`, `refactor:`, `chore:`. Keep the subject line in the imperative mood.
+
+## Reporting issues
+
+Include the DSH version, Node.js version, the exact `/tower` or tool input, and the relevant error text. Redact paths, tokens, session ids, and any personal data from logs before posting. For security issues, see [SECURITY.md](SECURITY.md).

package/README.en.md

@@ -50,24 +50,23 @@ The Host plugin is loaded when the DSH process starts, so **restart DSH after in
 
 ## Quick start
 
-```
+```text
 /tower on
 
-tower_init        <repoRoot>
-tower_plan        <repoRoot> missions=[...]
-tower_spawn       <repoRoot> missionId=M1 role=worker
-# worker implements and reports completion
-tower_preflight   <repoRoot> missionId=M1    # must be green before merging
-tower_spawn       <repoRoot> missionId=M1 role=reviewer
-tower_review      ...                        # reviewer submits verdict
-tower_preflight   <repoRoot> missionId=M1
-tower_merge       <repoRoot> missionId=M1
-tower_teardown    <repoRoot>
+tower_init      repoRoot=D:\work\repo            # records the base (current branch by default)
+tower_plan      repoRoot=D:\work\repo missions=[{"title":"Feature A","scope":["src/a/**"],"tasks":["implement","commit"],"kind":"build"}]
+tower_spawn     repoRoot=D:\work\repo missionId=M1 role=worker
+# the worker implements and commits in its worktree, calls tower_complete; its final report returns here
+tower_spawn     repoRoot=D:\work\repo missionId=M1 role=reviewer
+# the reviewer inspects read-only and calls tower_review (clean+merge, or p1-Nitems/p2-Nitems)
+tower_preflight repoRoot=D:\work\repo missionId=M1    # expect no-review before review; ok:true after it
+tower_merge     repoRoot=D:\work\repo missionId=M1
+tower_teardown  repoRoot=D:\work\repo
 
 /tower off
 ```
 
-A typical run takes one worker mission and one reviewer round for a small change.
+A small change usually takes one worker mission and one reviewer round. A full copy-paste example is in [docs/examples/first-mission.md](docs/examples/first-mission.md); per-tool parameters are in [docs/reference/tools.md](docs/reference/tools.md).
 
 ## Commands
 
@@ -88,28 +87,42 @@ Image and file attachments are forwarded together with the instruction as one co
 - id: tower
   name: 'dsh-tower'
   config:
-    section: 'Optional replacement for the Tower-mode system prompt text'
-    allowAgentControl: true   # true registers tower_control; false makes the mode human-only
+    section: 'Optional legacy alias replacing the Tower-mode prompt text'
+    allowAgentControl: true   # legacy alias for mode.allowAgentControl
+    mode:
+      allowAgentControl: true
+      autoPauseGoal: true
+      denyTools: [create_goal, todo_write, team_task_create, team_task_update, team_task_reopen, spawn_teammate]
+    review:
+      maxRoundsPerReviewer: 5
+    merge:
+      timeoutMs: 900000
+    worktrees:
+      root: ''                 # empty = <checkout parent>/.dsh-tower-worktrees/<hash>
+    spawn:
+      workerPreset: tower-worker
+      reviewerPreset: tower-reviewer
+      maxDepth: 1
 ```
 
-- `allowAgentControl` defaults to `false` in code. The bundled `cordis.patch.yml` enables it (`true`) so the model may enter/leave Tower mode when the user intent or task state clearly warrants it, always stating a reason.
-- When disabled, only the human can change the mode.
+- `mode.allowAgentControl` defaults to `false` in code; the bundled `cordis.patch.yml` enables it (`true`) so the model may enter/leave when the user intent or task state warrants it, always stating a reason.
+- Every key and default is in [docs/reference/config.md](docs/reference/config.md); unknown keys are rejected so typos cannot silently disable security-relevant settings.
 
-## Tools (17)
+## Tools (18)
 
-`tower_init` · `tower_plan` · `tower_mission` · `tower_status` · `tower_spawn` · `tower_roster` · `tower_adopt` · `tower_send` · `tower_inbox` · `tower_complete` · `tower_finding` · `tower_review` · `tower_preflight` · `tower_merge` · `tower_rebase` · `tower_teardown` · `tower_mode`
+`tower_init` · `tower_plan` · `tower_mission` · `tower_status` · `tower_spawn` · `tower_roster` · `tower_adopt` · `tower_diff` · `tower_send` · `tower_inbox` · `tower_complete` · `tower_finding` · `tower_review` · `tower_preflight` · `tower_merge` · `tower_rebase` · `tower_teardown` · `tower_mode`
 
-`tower_control` exists only when `allowAgentControl: true`.
+`tower_control` exists only when `allowAgentControl: true` (the bundled patch enables it, so an installed build exposes 19 tools).
 
 ## Safety and guardrails
 
 - **No merge without a green gate.** `tower_preflight` is read-only and reports stable blocker codes; `tower_merge` refuses when any blocker remains.
-- **Review is bound to a commit.** If the branch tip moves after a review, the gate reports `tip-moved`; re-review is required (a clean rebase waiver is the only exception).
+- **Review is bound to a commit.** A moved tip reports `tip-moved` and requires a fresh review; reviewers use a read-only preset, and a branch change during review is rejected.
 - **Scope enforcement.** A mission may only change files matched by its declared scope globs; `out-of-scope` blocks the merge.
 - **Worktree ownership.** Dirty worktrees, a running worker, or a branch owned by a closed mission block teardown/merge.
 - **Goal isolation.** Entering Tower mode pauses the active goal and records it; leaving does not resume it. Use `/tower off` and resume the goal yourself.
 
-The 13 stable blocker codes are: `branch-missing`, `deps-unmerged`, `read-only-survey`, `stale-base`, `no-review`, `review-hold`, `not-clean`, `review-not-approved`, `tip-moved`, `review-mission-mismatch`, `out-of-scope`, `base-dirty`, `branch-owned-by-closed-missions` (plus mission/worker guards).
+13 stable blocker codes (plus 6 additional gate guards and 6 merge/rebase failure codes) — the complete list with triggers and fixes is in [docs/reference/blockers.md](docs/reference/blockers.md).
 
 ## How it works
 
@@ -122,14 +135,16 @@ A mission moves through `planned → active → completed → merged` (or `block
 | `<checkout parent>/.dsh-tower-worktrees/<hash>/<missionId>` | per-mission worktree |
 | `$DSH_HOME/tower-mode/modes.json` | Tower mode state per agent/session |
 
-Workers and reviewers are ordinary DSH subagents started with the bundled `tower-worker` preset; their tools are restricted to the mission surface (filesystem, shell, and Tower protocol tools), never merge/spawn.
+Workers use the bundled `tower-worker` preset (writable worktree surface); reviewers use the separate read-only `tower-reviewer` preset and can only inspect (`tower_diff`) and submit `tower_review`. The reviewer records the branch tip at spawn; if the branch moves, the review is rejected. Neither preset can merge or spawn.
 
 ## Project layout
 
 | Path | Contents |
 |---|---|
 | `package.json`, `cordis.patch.yml` | bundle manifest and loader patch (inserts the Host plugin and the `tower-worker` preset) |
-| `index.js`, `lib/`, `worker.js` | Host entry, protocol implementation, worker preset policy |
+| `index.js`, `lib/`, `worker.js`, `reviewer.js` | Host entry, protocol/config implementation, worker and reviewer preset policies |
+| `skills.js`, `skills/` | bundled agent skills (worker protocol, review checklist, recovery playbook) |
+| `docs/` | guides, reference, architecture, operations, FAQ and examples |
 | `locale/`, `icon.svg` | localization and icon |
 | `tests/` | pure-function, protocol end-to-end, and plugin-level tests; optional isolated Web-runtime scripts |
 | `ui-bundle/` | optional Client widget (static `/tower` hint), not installed by default |
@@ -143,6 +158,14 @@ npm test        # node --test tests/*.test.mjs
 
 The offline suite needs no DSH process and creates throwaway Git repositories in the OS temp directory. `tests/README.md` documents the isolated Web-runtime checks, model-driven acceptance, and the session-diagnostic scripts used while hardening the plugin.
 
+## Documentation
+
+- [docs/README.md](docs/README.md) — documentation index (new user / operator / maintainer paths)
+- [Quick start](docs/guide/quickstart.md) · [Install, upgrade and migration](docs/guide/install-upgrade-migration.md)
+- [Tools reference](docs/reference/tools.md) · [Config reference](docs/reference/config.md) · [Blockers and failure codes](docs/reference/blockers.md)
+- [Architecture and state machine](docs/architecture/overview.md) · [Operations runbook](docs/operations/runbook.md) · [Security model](docs/operations/security.md)
+- [FAQ](docs/faq.md) · [Examples](docs/examples/first-mission.md)
+
 ## Troubleshooting
 
 - **The plugin does not appear after install/update.** Host plugins load at DSH startup; restart DSH. Confirm the entry point targets this repository root (the folder with `package.json` and `cordis.patch.yml`), not a subdirectory.

package/README.md

@@ -50,24 +50,23 @@ Host 插件在 DSH 进程启动时加载，**安装或更新后需重启 DSH**
 
 ## 快速开始
 
-```
+```text
 /tower on
 
-tower_init        <repoRoot>
-tower_plan        <repoRoot> missions=[...]
-tower_spawn       <repoRoot> missionId=M1 role=worker
-# worker 实现并汇报完成
-tower_preflight   <repoRoot> missionId=M1    # 必须全绿才能合并
-tower_spawn       <repoRoot> missionId=M1 role=reviewer
-tower_review      ...                        # 审查者提交结论
-tower_preflight   <repoRoot> missionId=M1
-tower_merge       <repoRoot> missionId=M1
-tower_teardown    <repoRoot>
+tower_init      repoRoot=D:\work\repo            # 首次初始化，记录 base（默认当前分支）
+tower_plan      repoRoot=D:\work\repo missions=[{"title":"Feature A","scope":["src/a/**"],"tasks":["implement","commit"],"kind":"build"}]
+tower_spawn     repoRoot=D:\work\repo missionId=M1 role=worker
+# worker 在 worktree 内实现并提交，调用 tower_complete；最终报告会返回本会话
+tower_spawn     repoRoot=D:\work\repo missionId=M1 role=reviewer
+# reviewer 只读审查并调用 tower_review（clean+merge 或 p1-Nitems/p2-Nitems）
+tower_preflight repoRoot=D:\work\repo missionId=M1    # 审查前 预期 no-review；审查后应为 ok:true
+tower_merge     repoRoot=D:\work\repo missionId=M1
+tower_teardown  repoRoot=D:\work\repo
 
 /tower off
 ```
 
-小改动通常一轮 worker + 一轮 reviewer 即可完成。
+小改动通常一轮 worker + 一轮 reviewer 即可完成。完整可复制示例见 [docs/examples/first-mission.md](docs/examples/first-mission.md)，逐工具参数见 [docs/reference/tools.md](docs/reference/tools.md)。
 
 ## 命令
 
@@ -88,28 +87,42 @@ tower_teardown    <repoRoot>
 - id: tower
   name: 'dsh-tower'
   config:
-    section: '（可选）覆盖 Tower 模式系统提示文案'
-    allowAgentControl: true   # true 时注册 tower_control；false 时只有人类能切换
+    section: '（可选，兼容别名）覆盖 Tower 模式系统提示文案'
+    allowAgentControl: true   # 兼容别名；等价于 mode.allowAgentControl
+    mode:
+      allowAgentControl: true
+      autoPauseGoal: true
+      denyTools: [create_goal, todo_write, team_task_create, team_task_update, team_task_reopen, spawn_teammate]
+    review:
+      maxRoundsPerReviewer: 5
+    merge:
+      timeoutMs: 900000
+    worktrees:
+      root: ''                 # 空 = <主检出父目录>/.dsh-tower-worktrees/<hash>
+    spawn:
+      workerPreset: tower-worker
+      reviewerPreset: tower-reviewer
+      maxDepth: 1
 ```
 
-- 代码中 `allowAgentControl` 默认 `false`；仓库自带的 `cordis.patch.yml` 把它设为 `true`：当用户意图或任务状态明确时，模型可以自行进出 Tower 模式，但必须给出理由。
-- 设为 `false` 时只有人类能切换模式。
+- 代码中 `mode.allowAgentControl` 默认 `false`；随包 `cordis.patch.yml` 设为 `true`：模型可在用户意图/任务状态明确时自行进出，但必须给出理由；设为 `false` 时只有人类能切换。
+- 所有键与默认值见 [docs/reference/config.md](docs/reference/config.md)；未知键会被拒绝（防止拼写错误静默失效）。
 
-## 工具（17 个）
+## 工具（18 个）
 
-`tower_init` · `tower_plan` · `tower_mission` · `tower_status` · `tower_spawn` · `tower_roster` · `tower_adopt` · `tower_send` · `tower_inbox` · `tower_complete` · `tower_finding` · `tower_review` · `tower_preflight` · `tower_merge` · `tower_rebase` · `tower_teardown` · `tower_mode`
+`tower_init` · `tower_plan` · `tower_mission` · `tower_status` · `tower_spawn` · `tower_roster` · `tower_adopt` · `tower_diff` · `tower_send` · `tower_inbox` · `tower_complete` · `tower_finding` · `tower_review` · `tower_preflight` · `tower_merge` · `tower_rebase` · `tower_teardown` · `tower_mode`
 
-`tower_control` 仅在 `allowAgentControl: true` 时存在。
+`tower_control` 仅在 `allowAgentControl: true` 时存在（随包 patch 默认开启，因此安装后共 19 个工具）。
 
 ## 安全与约束
 
 - **门禁不全绿不合并。** `tower_preflight` 是只读检查，返回稳定的 blocker code；存在 blocker 时 `tower_merge` 拒绝合并。
-- **审查绑定提交。** 审查后分支 tip 变化会报 `tip-moved`，必须重新审查；唯一的例外是干净 rebase 的免审豁免。
+- **审查绑定提交。** 审查后分支 tip 变化会报 `tip-moved`，必须重新审查；reviewer 使用只读 preset，若在审查期间改动分支，提交审查会被拒绝。
 - **scope 强制。** mission 只能修改其 scope glob 匹配的文件，越界会以 `out-of-scope` 阻止合并。
 - **worktree 归属。** 脏工作树、运行中的 worker、已关闭 mission 的分支都会阻止合并或 teardown。
 - **goal 隔离。** 进入 Tower 模式会暂停活跃 goal 并记录；退出不会自动恢复，需要你自行恢复。
 
-13 个稳定 blocker code：`branch-missing`、`deps-unmerged`、`read-only-survey`、`stale-base`、`no-review`、`review-hold`、`not-clean`、`review-not-approved`、`tip-moved`、`review-mission-mismatch`、`out-of-scope`、`base-dirty`、`branch-owned-by-closed-missions`（另有 mission/worker 守卫）。
+13 个稳定 blocker code（另有 6 个 gate 守卫与 6 个 merge/rebase 操作失败码）——完整清单、触发条件与修复动作见 [docs/reference/blockers.md](docs/reference/blockers.md)。
 
 ## 工作原理
 
@@ -143,6 +156,14 @@ npm test        # node --test tests/*.test.mjs
 
 离线套件不需要 DSH 进程，只在系统临时目录创建一次性 Git 仓库。隔离 Web 运行时检查、模型驱动验收和会话诊断脚本见 `tests/README.md`。
 
+## 文档
+
+- [docs/README.md](docs/README.md) — 文档索引（新用户 / 运维 / 维护者三条阅读路径）
+- [快速开始](docs/guide/quickstart.md) · [安装、升级与迁移](docs/guide/install-upgrade-migration.md)
+- [工具参考](docs/reference/tools.md) · [配置参考](docs/reference/config.md) · [blocker 与失败码](docs/reference/blockers.md)
+- [架构与状态机](docs/architecture/overview.md) · [运维 runbook](docs/operations/runbook.md) · [安全模型](docs/operations/security.md)
+- [FAQ](docs/faq.md) · [示例](docs/examples/first-mission.md)
+
 ## 常见问题
 
 - **安装/更新后插件不出现。** Host 插件在 DSH 启动时加载，请重启 DSH；并确认安装目标指向本仓库根目录（含 `package.json` 与 `cordis.patch.yml` 的那一层），而不是子目录。

package/SECURITY.md

@@ -0,0 +1,20 @@
+# Security policy
+
+## Scope
+
+`dsh-tower` runs inside a local DeepSeek Harness process. It does not send data to any network service of its own: mission state is written under the target repository's `.git/dsh-tower/`, and Tower-mode state is written under `$DSH_HOME/tower-mode/`.
+
+Areas that matter for security reports:
+
+- The merge gate (`tower_preflight` / `tower_merge`): bypassing scope, review, staleness, or ownership checks.
+- The mode guard: reaching a denied tool (`create_goal`, `todo_write`, Team task tools, `spawn_teammate`, `update_goal(resume)`) while Tower mode is active.
+- Command forwarding: injecting content into the model history that the user did not send.
+- Writes outside the declared scope, the mission worktree, or the DSH home directory.
+
+## Reporting
+
+Please do **not** publish exploit details in a public issue. Open a minimal issue titled `security: request private contact` describing only the impact category (for example “merge gate bypass”), and a maintainer will arrange a private channel. Include the affected version and, if possible, a minimal reproduction in the private follow-up.
+
+## Supported versions
+
+Security fixes target the latest released version (`1.x`). Older pre-release snapshots are not maintained.

package/cordis.patch.yml

@@ -3,6 +3,8 @@
       name: 'dsh-tower'
       config:
         allowAgentControl: true
+    - id: tower-skills
+      name: 'dsh-tower/skills'
     - id: preset-tower-worker
       name: '@deepseek-ai/dsh-agent-preset'
       config:
@@ -21,3 +23,23 @@
               sampleOverCapGlobResults: false
           - id: tower-worker-pwsh
             name: '@deepseek-ai/dsh-tool-pwsh'
+    - id: preset-tower-reviewer
+      name: '@deepseek-ai/dsh-agent-preset'
+      config:
+        id: tower-reviewer
+        name: Tower Reviewer
+        description: Read-only independent reviewer for a completed Tower mission.
+        order: 61
+        plugins:
+          - id: tower-reviewer-policy
+            name: 'dsh-tower/reviewer'
+          - id: tower-reviewer-fs
+            name: '@deepseek-ai/dsh-tool-fs'
+            config:
+              write: false
+              edit: false
+              readImage: false
+          - id: tower-reviewer-fs-search
+            name: '@deepseek-ai/dsh-tool-fs-search'
+            config:
+              sampleOverCapGlobResults: false

package/docs/README.md

@@ -0,0 +1,13 @@
+# dsh-tower documentation
+
+Choose a path:
+
+| You are | Start here |
+|---|---|
+| New user | [Quick start](guide/quickstart.md) → [Tools](reference/tools.md) → [Example](examples/first-mission.md) |
+| Operator | [Runbook](operations/runbook.md) → [Blockers](reference/blockers.md) → [Security](operations/security.md) |
+| Maintainer | [Architecture](architecture/overview.md) → [Config](reference/config.md) → [Contributing](../CONTRIBUTING.md) |
+
+Reference pages are the source of truth for the current release; the [tools reference](reference/tools.md) and [blocker list](reference/blockers.md) are checked by `npm run docs:check` in CI.
+
+Other useful pages: [Install, upgrade and migration](guide/install-upgrade-migration.md), [FAQ](faq.md), [CHANGELOG](../CHANGELOG.md).

package/docs/architecture/overview.md

@@ -0,0 +1,66 @@
+# Architecture and state machine
+
+## Components
+
+```
+Host plugin (index.js)
+ ├─ /tower command + Tower mode (guard, prompt section, tower_control)
+ ├─ lib/tools.js  -> 17 tools (+ tower_diff) registered on ctx.tools
+ └─ lib/tower.js  -> Tower domain: missions, gates, worktrees, roster, review, merge
+       ├─ lib/git.js     minimal git port (execFile, bounded output, timeout classification)
+       ├─ lib/store.js   repo-scoped lock + atomic JSON + activity.jsonl
+       ├─ lib/config.js  Config schema + runtime snapshot
+       └─ lib/modeStore.js  per-agent Tower mode persistence
+Subagents
+ ├─ tower-worker   (dsh-tower/worker)   read/write/edit/pwsh + mission tools
+ └─ tower-reviewer (dsh-tower/reviewer) read/glob/grep + tower_diff + review/finding
+```
+
+The main checkout is the control-tower repo; each mission has a branch `tower/<id>-<slug>` and a
+worktree in `.dsh-tower-worktrees/<hash>/<missionId>`. The plugin never operates on the main checkout's
+working tree except merge and the read-only diff.
+
+## Mission state machine
+
+```
+planned ──spawn worker──▶ active ──tower_complete──▶ completed ──tower_merge──▶ merged
+   │                        │  ▲                         │
+   │                        │  └──── review round not clean ────┐
+   └── abandon ──▶ abandoned│                                   │
+                            ├── blocker ──▶ blocked ──active/completed──▶ ...
+                            └── pause ─────▶ paused ──active──▶ ...
+```
+
+`merged` and `abandoned` are terminal. `tower_mission` may set `blocked → completed`; `merged` is only
+set by `tower_merge`/reconciliation.
+
+## Gate pipeline (`tower_preflight`)
+
+1. Mission status must be `completed`; tasks and blockers are checked.
+2. The worktree exists; the base tip is an ancestor of the branch tip; changed files are computed
+   against the merge base.
+3. Survey missions must not change files; build missions must stay inside `scope`.
+4. The main checkout must be clean for the files this merge would overwrite and on the base branch.
+5. Dependency missions must be merged/abandoned.
+6. A review must exist, belong to this mission, be clean, approve merge, and be bound to the tip
+   (unless a clean rebase waived it). No worker may be running.
+
+## Merge
+
+`tower_merge` runs `git merge --no-ff` with a configurable timeout (default 15 min) and 64 MB buffer.
+After the command, regardless of exit status, it inspects `HEAD`:
+
+- merge commit with parents `[baseTip, branchTip]` → record merged (including `recoveredFromFailure`);
+- otherwise classify the failure: unmerged index → `merge-conflict` (mission blocked); no unmerged
+  entries → `merge-hook-failed` (mission retryable), with abort/reset cleanup.
+- If the branch or its reviewed commit is already contained in the base, reconcile instead of merging.
+
+## State files
+
+| Path | Contents |
+|---|---|
+| `<git-common-dir>/dsh-tower/state.json` | missions, roster, reviews, findings, messages, reviews sequence |
+| `<git-common-dir>/dsh-tower/activity.jsonl` | append-only activity |
+| `<git-common-dir>/dsh-tower/state.lock` | single-writer lock (stale locks are reported, never stolen) |
+| `<checkout parent>/.dsh-tower-worktrees/<hash>/<missionId>` | mission worktree |
+| `$DSH_HOME/tower-mode/modes.json` | Tower mode per agent/session |

package/docs/examples/first-mission.md

@@ -0,0 +1,58 @@
+# Example: first mission, end to end
+
+Assume a repository at `D:\work\demo` with a clean `main` branch and one file `README.md`.
+
+```
+/tower on
+tower_init repoRoot=D:\work\demo
+```
+
+`s` is a placeholder for tool JSON arguments; DSH accepts the object form:
+
+```json
+{"repoRoot":"D:\\work\\demo","missions":[{"title":"Add greeting","scope":["src/**"],"tasks":["write src/greet.txt","commit the change"],"kind":"build"}]}
+```
+
+`tower_plan` returns `M1`. Spawn the worker:
+
+```json
+{"repoRoot":"D:\\work\\demo","missionId":"M1","role":"worker"}
+```
+
+Wait for the worker's final report (delivered to this session) or check `tower_roster`. The worker
+creates `src/greet.txt`, commits on `tower/m1-add-greeting`, marks both tasks done, and calls
+`tower_complete`.
+
+Spawn the reviewer:
+
+```json
+{"repoRoot":"D:\\work\\demo","missionId":"M1","role":"reviewer"}
+```
+
+The read-only reviewer inspects `tower_diff`, then calls `tower_review` with:
+
+```json
+{"repoRoot":"D:\\work\\demo","missionId":"M1","status":"clean","merge":"merge","findings":"none","decision":"single in-scope file; content correct"}
+```
+
+Gate and merge:
+
+```json
+{"repoRoot":"D:\\work\\demo","missionId":"M1"}
+```
+
+Call `tower_preflight` with the same arguments; expect `ok: true`. Then `tower_merge`, and finally
+`tower_teardown` with `{"repoRoot":"D:\\work\\demo"}`.
+
+```
+/tower off
+```
+
+Typical expected output after merge:
+
+```json
+{"ok":true,"mergedCommit":"<sha>","baseTip":"<old>","branchTip":"<sha>","parents":["<old>","<sha>"]}
+```
+
+If the merge hook is slow, add `"timeoutMs": 1800000` to `tower_merge`; if a merge commit landed but the
+call failed, re-run `tower_merge` and it records the existing commit instead of merging again.

package/docs/faq.md

@@ -0,0 +1,43 @@
+# FAQ
+
+**Why did `tower_preflight` fail with `no-review` right after the worker finished?**
+That is expected: a completed mission awaits review. Spawn a reviewer; after a clean review the gate
+turns green.
+
+**Do I need to poll the worker?**
+No. The worker's final report is delivered to this session; `tower_roster` shows live activity. Polling
+wastes turns.
+
+**`/tower` says the mode is on but `tower_control` is missing.**
+`mode.allowAgentControl` is off. Set it to `true` in the profile patch and restart DSH.
+
+**The merge hook takes minutes and `tower_merge` failed.**
+Retry with a larger `timeoutMs`: `tower_merge({ missionId, timeoutMs: 1800000 })`. The default is 15
+minutes and merge output is buffered up to 64 MB. A hook failure returns `merge-hook-failed` and leaves
+the repo clean for a retry.
+
+**A merge commit exists but Tower says the mission is not merged.**
+Call `tower_merge` again. It detects the landed merge commit (`reconciled`) or recovers a failed call
+whose commit exists (`recoveredFromFailure`) and records it.
+
+**`tower_rebase` returned `alreadyMerged` and changed nothing.**
+Correct: the branch is already contained in the base. Call `tower_merge` to record the landed merge
+instead of rebasing.
+
+**Can a reviewer edit files?**
+No. Reviewers use the read-only `tower-reviewer` preset (no write/edit/pwsh); a branch changed after the
+reviewer spawned is rejected. Reviewers file `tower_finding` for issues outside the mission.
+
+**Can workers use Tower tools to merge or spawn?**
+No. The worker preset contains mission/progress tools only; merge and spawn live in the parent tower.
+
+**Where does Tower store state?**
+`<git-common-dir>/dsh-tower/state.json` and `activity.jsonl` in the target repo; mode state in
+`$DSH_HOME/tower-mode/modes.json`. Worktrees live next to the checkout in `.dsh-tower-worktrees/`.
+
+**How do I change the review round cap or presets?**
+Use `review.maxRoundsPerReviewer` and `spawn.workerPreset`/`spawn.reviewerPreset`; see
+[config](reference/config.md). Restart DSH after a profile config change.
+
+**Does Tower send data anywhere?**
+No. It has no telemetry and no network service; all state is local.

package/docs/guide/install-upgrade-migration.md

@@ -0,0 +1,48 @@
+# Install, upgrade and migration
+
+## Requirements
+
+- DSH `0.2.1-rc.2` or newer
+- Node.js 22+
+- Git (local worktrees; no network access is required)
+
+## Install
+
+```bash
+dsh plugin --profile web add dsh-tower
+```
+
+Or inside DSH: `plugin_manager({ action: "install_bundle", target: "dsh-tower" })`. From a checkout:
+
+```bash
+dsh plugin --profile web add github:louifinn/dsh-tower
+```
+
+The Host plugin loads at DSH startup: **restart DSH after install or update**.
+
+## Upgrade
+
+1. Read [CHANGELOG.md](../../CHANGELOG.md) for behavior changes.
+2. Update the dependency (`dsh plugin --profile web add dsh-tower@latest` or your pinned version).
+3. Restart DSH; check `tower_mode` reports `allowAgentControl` as expected.
+4. Existing mission state stays compatible: the state schema did not change in 1.2/1.3.
+
+## Migration notes
+
+- **1.2 → 1.3**: reviewers moved from the shared `tower-worker` preset to the new read-only
+  `tower-reviewer` preset. Reinstall/restart so both preset rows exist. `tower_spawn role=reviewer`
+  now requires the mission to be `completed`.
+- **1.1 → 1.2**: merge failures gained `merge-hook-failed`, `cleanup` and reconciliation behavior; no
+  state migration is needed.
+- **1.0 → 1.1**: package name changed from `@local/dsh-tower` to `dsh-tower`. Remove the old bundle
+  (`remove_bundle` with `@local/dsh-tower`) and install `dsh-tower`.
+
+## Uninstall
+
+```text
+plugin_manager({ action: "remove_bundle", target: "dsh-tower" })
+```
+
+Restart DSH. Mission state under `<git-common-dir>/dsh-tower/` and worktrees under
+`<checkout parent>/.dsh-tower-worktrees/` are left in place; remove them manually only after no mission
+is active.

package/docs/guide/quickstart.md

@@ -0,0 +1,65 @@
+# Quick start
+
+Prerequisites: DSH `0.2.1-rc.2`+, Node.js 22+, Git. Install `dsh-tower` and restart DSH (see
+[install](install-upgrade-migration.md)).
+
+## 1. Enter Tower mode
+
+```
+/tower
+```
+
+The session reports `Tower mode ON`. You are now the control tower; goal/todo/team delegation tools are
+reserved for normal mode.
+
+## 2. Initialize and plan
+
+```
+tower_init repoRoot=D:\work\repo
+tower_plan repoRoot=D:\work\repo missions=[{"title":"Feature A","scope":["src/a/**"],"tasks":["implement the feature","commit the change"],"kind":"build"}]
+```
+
+`tower_plan` returns mission ids (`M1`). Each mission gets a branch and a worktree when spawned.
+
+## 3. Run the worker
+
+```
+tower_spawn repoRoot=D:\work\repo missionId=M1 role=worker
+```
+
+The call returns immediately with the child agent id. The worker works inside the mission worktree,
+commits, marks tasks done, and calls `tower_complete`; its final report is delivered back to this
+session. Use `tower_roster` to observe activity; do not poll in a loop.
+
+## 4. Review
+
+```
+tower_spawn repoRoot=D:\work\repo missionId=M1 role=reviewer
+```
+
+Reviewers use the read-only `tower-reviewer` preset. They inspect `tower_diff` and submit
+`tower_review`. A `clean` + `merge` verdict is required to merge.
+
+## 5. Gate, merge, clean up
+
+```
+tower_preflight repoRoot=D:\work\repo missionId=M1
+tower_merge     repoRoot=D:\work\repo missionId=M1
+tower_teardown  repoRoot=D:\work\repo
+```
+
+`tower_preflight` before review is expected to report `no-review`; after a clean review it should be
+`ok:true`. `tower_merge` refuses while blockers remain. `tower_teardown` removes merged/abandoned
+worktrees and branches.
+
+```
+/tower off
+```
+
+## If something fails
+
+Read the blocker code and use [the blocker reference](reference/blockers.md). The most common cases:
+`stale-base` (run `tower_rebase`), `no-review` (spawn a reviewer), `merge-hook-failed` (retry, or raise
+`timeoutMs`), `tip-moved` (the branch changed after review; review again).
+
+A complete copy-paste example: [examples/first-mission.md](../examples/first-mission.md).