dsh-tower 1.2.0 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,101 @@
 # Changelog
 
+> 自 2.0.0 起，每个版本按 **新增 / 变更 / 修复** 三类组织；更早的版本保留原始流水式记录。
+
+## 2.0.0（2026-10-18）
+
+### 新增
+
+- **仓库级配置层**：`Tower.open()` 读取 `<git-common-dir>/dsh-tower/config.json`，优先级为
+  代码默认 < profile 配置 < 仓库配置 < 工具参数；`review`/`merge`/`worktrees`/`spawn` 分组生效。
+- **稳定工具错误码**：新增 `lib/errors.js`，工具失败统一 `[tower:<code>]` 前缀，覆盖 17 个 code；
+  新增 `docs/reference/errors.md` 并由 `npm run docs:check` 校验。
+- **finding 生命周期**：新增 `tower_findings`（列表/读取/状态流转/备注），状态为
+  `open → triaged → fixed` / `wontfix` 且可重新打开；只有 tower 或 worker 能改状态，reviewer 只读。
+- **中文文档**：新增 `docs/zh/`（文档索引、quickstart、工具/配置/blocker/错误码参考），
+  与英文参考页保持同一套工具名、blocker 与错误码。
+- **测试与门禁**：新增仓库配置、finding 生命周期、工具别名/错误码/输出 schema、spawn mock
+  与全流程 schema 校验用例；`docs:check` 同时校验中英文参考页、工具名、blocker 与错误码。
+- **协议硬化**：`tower_interrupt`（停止 running agent）、`tower_send(interrupt:true)`；
+  `tower_init` 支持 `autoGitInit`/`snapshotDirty`/`reanchor`；worker 不能直接完成/放弃/扩界，
+  completed 必须经 `tower_complete`；单 mission 单活 worker + `takeover` 接管 + generation。
+- **治理与可观测**：可选 `mode.workspaceLock` 仓库互斥；`spawn.maxLiveWorkers`、`send.maxPerMinute`
+  与 roster stale 标记；`tower_status` 分页/单 mission 明细/gate digest/markdown；`MISSIONS.md`
+  人类可读门板；`tower/*` 进程内事件；`tower_complete.checks` + `gates.requireChecks`。
+- **热重载**：`/tower reload` 与 `tower_reload` 调用 DSH HMR `reconcileProfile`；新增
+  `npm run dev:hmr` 脚本把 linked 仓库加入 profile HMR watch root；`docs/guide/hot-reload.md`。
+- **2.1 测试准入**：读取 worktree `package.json` 的 `tower.testDiscovery`（TAP/json-array），支持
+  `tests.admission:spawn|complete`、16 MiB/60s 预算、minCount/required；`tower_test` 与
+  `tower_complete` 自动生成 `tests` check；`gates.requireTests` / `tests-missing` / `tests-failed`。
+- **2.1 批次与运营**：`tower_batch`（create/status/close，冻结成员、requiredChecks、receiptPaths）、
+  `tower_resource`（advisory lease，token/过期显式 force）、`tower_doctor`（只读健康契约）、
+  `tower_import_legacy` / `tower_legacy_map`（只读快照 + 审计映射）。
+- **2.1 治理**：per-repo roster watchdog（`spawn.staleMs` 15s 标记 stale 并阻断合并）、
+  `spawn.maxWaitMs` 90s、`mode.workspaceLockScope`、plan/tower 互斥（默认清除 plan）、
+  `/tower base <branch>`、`docs.boardLocation`、delivery ack、merge intent 持久化。
+- **2.1 UI**：ui-bundle 增加 12 个 tower tool 卡片、composer dock 最新摘要与 shell.overlay 瞬时状态条；
+  纯会话派生，无 Host RPC/iframe。
+- **2.1 文档**：`docs/reference/testing.md`、`operations.md`、`doctor.md` 与中文同步；工具面 28。
+
+### 变更
+
+- **结构化输出 schema**：全部工具声明 output schema（spawn/status/diff/merge/review/preflight
+  等核心工具含字段结构），并按 DSH 的输出校验规则保证可空字段可空。
+- **命名统一（兼容别名）**：mission 级工具同时接受 `id` 与 `missionId`；`task_done`/`taskDone`、
+  `task_drop`/`taskDrop`、`clear_blockers`/`clearBlockers`、`include_read`/`includeRead`、
+  `dry_run`/`dryRun`、`timeoutMs`/`timeout_ms`、`waitMs`/`wait_ms` 等写法均可，并在参数 schema
+  中显式声明；输出保持既有规范。
+- **诊断信息**：`tower_status` 增加 `config.path`、`config.repoConfigPresent` 与
+  `findingsByStatus`；worker/reviewer preset 允许 `tower_findings`。
+- **配置解析**：兼容别名只用于补缺——同时设置 `section` 与 `mode.promptSection` 时规范键优先；
+  仓库配置增加 1 MiB 大小上限与 `__proto__`/`constructor`/`prototype` 等危险键拒绝。
+- **配置默认值**：`mode.denyTools` 追加 workflow/ralph/subagent/subagent_fork/wait_agent/team_task_list
+  （Tower 模式与其它编排互斥）；新增 `spawn.maxLiveWorkers:4`、`spawn.staleMs:15000`、
+  `spawn.maxWaitMs:90000`、`send.maxPerMinute:120`、`gates.requireChecks:false`、
+  `gates.requireTests:false`、`docs.board:true`、`leases.ttlMs:900000`、`dev.hotReload:true`；
+  随包 patch 打开 `workspaceLock`/`interruptDefault`/`autoGitInit`。
+- **briefing**：worker/reviewer 生成历史审查、上一轮 findings/decision、completion checks 与
+  related findings，长文本截断；reviewer 必须核对 completion checks。
+- **输出/工具面**：`tower_status` 增加 total/offset/nextOffset/detail/markdown，并**默认只返回前 20 个 mission**（旧版返回全部；旧调用需要更多时用 `limit`/`offset`）；`tower_adopt`
+  支持 `retireMissing:false`；`tower_mode` 返回 pluginVersion/HMR/workspace lock；`tower_roster`
+  增加 `stale`。工具总数最多 28（含 doctor/test/batch/resource/import/legacy_map 与可选的 control/reload）。
+- **离线套件**：测试增至 206 项（含 2.1 discovery/batch/leases/legacy/doctor/UI/plan-mode/integration 用例）。
+- 除 `tower_status` 默认分页与 `mode.denyTools` 默认扩充外，既有工具参数与输出保持兼容。
+
+### 修复
+
+- **模式工具 schema 与返回值不一致**：`tower_mode`/`tower_control` 的 `lastChange`、`pausedGoal`、
+  `goalNote` 在正常路径返回 `null`，原 schema 会触发 DSH 强制输出校验失败；已改为可空并补回归测试。
+- **错误码分类补全**：state 校验失败统一归为 `state-corrupt`；`tower_complete` 的未完成任务、
+  blocker、无提交、未读消息等前置条件归为 `invalid-transition`，不再落到 `tool-internal`。
+- **findings 更新后的计数**：状态流转后返回的 `counts` 之前是旧值，现在按变更后重新统计。
+- **findings 只读路径**：列表/读取不再获取写锁，与工具描述一致，长合并或 hook 期间也能读取。
+- **mission id 规范化**：`tower_mission` 对首尾空白的 `id` 先 trim 再查找，不再误报
+  `mission-not-found`。
+- **角色绕过**：worker 之前可经 `tower_mission` 直接 completed/abandoned/扩界或清 blocker，
+  绕过 `tower_complete` 的未读/提交证据；现由服务端角色强制。
+- **并发与接管**：同一 mission 不再允许出现第二个 live worker；stale/interrupted/failed 的
+  worker 可显式 takeover，running worker 必须先中断，否则 `takeover-refused`。
+
+## 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 (206 tests today, including protocol end-to-end against a real temporary Git repository and mock spawn coverage) 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

@@ -18,6 +18,14 @@ The repository root **is** the DSH bundle: `package.json` declares `dsh.bundle.p
 - **Review-gated merges.** A reviewer bound to the current branch tip must submit a `clean` / `merge` verdict; the merge gate re-checks scope, staleness, task completion, review history, and worktree ownership before a `--no-ff` merge.
 - **Durable coordination.** Roster, inbox, findings, reviews, and mission state are persisted under `.git/dsh-tower/`, so a restart does not lose the plan.
 - **Safe by default.** While Tower mode is active, `create_goal`, `update_goal(resume)`, `todo_write`, the Team task board, and `spawn_teammate` are refused; a paused goal is never resumed automatically.
+- **Traceable finding lifecycle.** `tower_findings` lists, reads, and moves findings through `open → triaged → fixed` / `wontfix` (and can reopen); only the tower or a worker may change state, while reviewers can only read.
+- **Repository-level config.** Any repository can override review/merge/worktree/spawn policy in `<git-common-dir>/dsh-tower/config.json`; tool arguments override the repository layer, so no profile edit is needed per repository.
+- **Stable error codes.** Tool failures carry a `[tower:<code>]` prefix (for example `mission-not-found`, `preset-missing`, `config-invalid`) so callers can branch deterministically.
+- **Role enforcement and control.** Workers cannot complete/abandon a mission or widen its scope directly (completion goes through the `tower_complete` evidence gate); the tower can stop a runaway agent with `tower_interrupt`, and `tower_send(interrupt:true)` interrupts a running turn.
+- **Workspace exclusivity and limits.** Optional `mode.workspaceLock` allows one Tower session per repository; `spawn.maxLiveWorkers`, `send.maxPerMinute` and roster stale flags bound concurrency and message bursts.
+- **2.1 verification and operations.** `tower_test` runs the worktree's `tower.testDiscovery` (TAP/json-array, admission at spawn or complete), `tower_doctor` is a read-only health contract, `tower_batch` closes finite evidence batches, `tower_resource` manages advisory leases, and `tower_import_legacy`/`tower_legacy_map` import old snapshots and audit-map ids. Adds `worker-stale`, test gates, plan/Tower mutual exclusion, `workspaceLockScope`, `docs.boardLocation` and delivery acknowledgements.
+- **Hot reload.** In a profile with DSH HMR, `/tower reload`, `tower_reload` and `npm run dev:hmr` apply linked plugin changes without a restart; `plugin_manager` install/update already applies live.
+- **Evidence gate and events.** Workers can record `checks` in `tower_complete` and `gates.requireChecks` can require them; every mutation emits `tower/*` events and refreshes `MISSIONS.md`.
 
 ## Requirements
 
@@ -50,24 +58,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 +95,44 @@ 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. The bundled patch also enables `mode.workspaceLock` (single-active tower), `send.interruptDefault`, `init.autoGitInit`, and sets `spawn.staleMs` to 15s.
+- `/tower base <branch>` records a session-level init base preference; `/tower on` clears an active plan mode (`mode.planModePolicy:"refuse"` instead refuses entry), keeping plan and Tower mutually exclusive.
+- Repository-level config: put the same JSON shape in `<git-common-dir>/dsh-tower/config.json` (usually `.git/dsh-tower/config.json`) to override `review`/`merge`/`worktrees`/`spawn`. Precedence is code defaults < profile config < repository config < tool arguments. `mode.*` is session-scoped and only the profile layer controls it.
+- Every key and default is in [docs/reference/config.md](docs/reference/config.md); unknown top-level keys are rejected so typos cannot silently disable security-relevant settings, while unknown keys inside a group are ignored. Tool error codes are in [docs/reference/errors.md](docs/reference/errors.md).
 
-## Tools (17)
+## Tools (26 core)
 
-`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_interrupt` · `tower_finding` · `tower_findings` · `tower_review` · `tower_preflight` · `tower_merge` · `tower_rebase` · `tower_teardown` · `tower_mode` · `tower_doctor` · `tower_test` · `tower_batch` · `tower_resource` · `tower_import_legacy` · `tower_legacy_map`
 
-`tower_control` exists only when `allowAgentControl: true`.
+`tower_control` exists only when `allowAgentControl: true`; `tower_reload` is registered while `dev.hotReload` is on (default true) and returns `reload-unavailable` without an HMR service (so up to 28 tools). Mission-scoped tools also accept `id` as an alias for `missionId`; snake/camel spellings such as `task_done`/`taskDone` are both accepted.
 
 ## 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).
+32 stable blocker/failure codes (including gate guards, `no-check-evidence`, `worker-stale`, test gates, and merge/rebase operation failures) — the complete list with triggers and fixes is in [docs/reference/blockers.md](docs/reference/blockers.md). Tool-level error codes are in [docs/reference/errors.md](docs/reference/errors.md); events are in [docs/reference/events.md](docs/reference/events.md).
 
 ## How it works
 
@@ -122,14 +145,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 |
@@ -141,8 +166,20 @@ Workers and reviewers are ordinary DSH subagents started with the bundled `tower
 npm test        # node --test tests/*.test.mjs
 ```
 
+Hot-reload development: `npm run dev:hmr` adds this checkout to the current profile's HMR watch roots
+(one DSH restart); afterwards `/tower reload` or the automatic watcher applies `lib/` edits. See
+[docs/guide/hot-reload.md](docs/guide/hot-reload.md).
+
 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)
+- [Chinese docs](docs/zh/README.md) · [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) · [Error codes](docs/reference/errors.md) · [Events](docs/reference/events.md) · [Testing](docs/reference/testing.md) · [Batches/leases/legacy](docs/reference/operations.md) · [Doctor](docs/reference/doctor.md) · [Hot reload](docs/guide/hot-reload.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

@@ -18,6 +18,14 @@ Tower 模式与 mission/审查工作流的灵感来自 Moonshot AI 的 **Kimi Co
 - **审查门禁合并。** 审查者必须针对当前分支 tip 给出 `clean` / `merge` 结论；合并门禁重新校验 scope、分支新鲜度、任务完成度、审查记录与 worktree 归属，通过后才执行 `--no-ff` 合并。
 - **可恢复的协作状态。** roster、inbox、findings、reviews 与 mission 状态持久化在 `.git/dsh-tower/` 下，重启不会丢计划。
 - **默认安全。** Tower 模式开启期间拒绝 `create_goal`、`update_goal(resume)`、`todo_write`、Team 任务板与 `spawn_teammate`；被暂停的 goal 不会被自动恢复。
+- **可追溯的 finding 生命周期。** `tower_findings` 列表、读取并按 `open → triaged → fixed` / `wontfix` 流转，也可重新打开；只有 tower 或 worker 能改状态，reviewer 只能读。
+- **仓库级配置。** 每个仓库可用 `<git-common-dir>/dsh-tower/config.json` 覆盖 review/merge/worktree/spawn 策略，工具参数再覆盖仓库配置；无需为不同仓库改 profile。
+- **稳定错误码。** 工具失败统一带 `[tower:<code>]` 前缀（如 `mission-not-found`、`preset-missing`、`config-invalid`），调用方可稳定分支处理。
+- **角色强制与可控中断。** worker 不能直接完成/放弃 mission 或扩界（完成必须走 `tower_complete` 证据门），tower 可随时用 `tower_interrupt` 停止跑偏的 agent；`tower_send(interrupt:true)` 可中止运行中的 turn。
+- **仓库互斥与限流。** 可选 `mode.workspaceLock` 让同一仓库只有一个 Tower 会话；`spawn.maxLiveWorkers`、`send.maxPerMinute`、roster stale 标记约束并发与消息风暴。
+- **可热重载。** 在带 DSH HMR 的 profile 中，`/tower reload`、`tower_reload` 与 `npm run dev:hmr` 让 linked 插件代码改动无需重启即生效；`plugin_manager` 安装/更新本身即时生效。
+- **测试证据门与事件。** worker 可在 `tower_complete` 记录 `checks`，`gates.requireChecks` 可强制；每次 mutation 后发射 `tower/*` 事件并刷新 `MISSIONS.md`。
+- **2.1 验证与运营。** `tower_test` 执行 worktree 声明的 `tower.testDiscovery`（TAP/json-array，准入可设 spawn/complete），`tower_doctor` 只读健康契约，`tower_batch` 批次证据收口，`tower_resource` advisory lease，`tower_import_legacy` / `tower_legacy_map` 只读旧版导入与审计映射；新增 `worker-stale`、tests 门禁、plan/tower 互斥、`workspaceLockScope`、`docs.boardLocation` 与交付 ack。
 
 ## 环境要求
 
@@ -50,24 +58,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 +95,44 @@ 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` 时只有人类能切换。随包 patch 还默认开启 `mode.workspaceLock`（单活塔）、`send.interruptDefault`、`init.autoGitInit`，并把 `spawn.staleMs` 设为 15s。
+- `/tower base <branch>` 可设置会话级 init base 偏好；`/tower on` 会清除活跃 plan mode（`mode.planModePolicy:"refuse"` 则拒绝进入），保证 plan/tower 互斥。
+- 仓库级配置：在 `<git-common-dir>/dsh-tower/config.json`（通常是 `.git/dsh-tower/config.json`）放入同样的 JSON 结构，可覆盖 `review`/`merge`/`worktrees`/`spawn`；优先级为代码默认 < profile < 仓库配置 < 工具参数。`mode.*` 属于会话级，只在 profile 生效。
+- 所有键与默认值见 [docs/reference/config.md](docs/reference/config.md)；未知顶层键会被拒绝（防止拼写错误静默失效），嵌套分组内的未知键会被忽略。工具错误码见 [docs/reference/errors.md](docs/reference/errors.md)。
 
-## 工具（17 个）
+## 工具（26 个核心）
 
-`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_interrupt` · `tower_finding` · `tower_findings` · `tower_review` · `tower_preflight` · `tower_merge` · `tower_rebase` · `tower_teardown` · `tower_mode` · `tower_doctor` · `tower_test` · `tower_batch` · `tower_resource` · `tower_import_legacy` · `tower_legacy_map`
 
-`tower_control` 仅在 `allowAgentControl: true` 时存在。
+`tower_control` 仅在 `allowAgentControl: true` 时注册；`tower_reload` 在 `dev.hotReload`（默认 true）时注册，无 HMR 服务调用会返回 `reload-unavailable`（因此最多 28 个工具）。mission 级工具同时接受 `id` 作为 `missionId` 的别名；`task_done`/`taskDone` 等 snake/camel 写法均可。
 
 ## 安全与约束
 
 - **门禁不全绿不合并。** `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 守卫）。
+32 个稳定 blocker/failure code（含 gate 守卫、`no-check-evidence`、worker-stale、tests 门禁与 merge/rebase 操作失败码）——完整清单、触发条件与修复动作见 [docs/reference/blockers.md](docs/reference/blockers.md)。工具本身抛出的错误码见 [docs/reference/errors.md](docs/reference/errors.md)，事件见 [docs/reference/events.md](docs/reference/events.md)。
 
 ## 工作原理
 
@@ -141,8 +164,18 @@ worker 与 reviewer 是使用内置 `tower-worker` preset 的普通 DSH 子代
 npm test        # node --test tests/*.test.mjs
 ```
 
+热重载开发：`npm run dev:hmr` 把本仓库加入当前 profile 的 HMR watch root（需重启 DSH 一次），之后编辑 `lib/` 代码可用 `/tower reload` 或自动 watch 生效；详见 [docs/guide/hot-reload.md](docs/guide/hot-reload.md)。
+
 离线套件不需要 DSH 进程，只在系统临时目录创建一次性 Git 仓库。隔离 Web 运行时检查、模型驱动验收和会话诊断脚本见 `tests/README.md`。
 
+## 文档
+
+- [docs/README.md](docs/README.md) — 文档索引（新用户 / 运维 / 维护者三条阅读路径）
+- [中文文档](docs/zh/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/reference/errors.md) · [事件](docs/reference/events.md) · [测试准入](docs/reference/testing.md) · [批次/租约/旧版](docs/reference/operations.md) · [Doctor](docs/reference/doctor.md) · [热重载](docs/guide/hot-reload.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,18 @@
       name: 'dsh-tower'
       config:
         allowAgentControl: true
+        init:
+          autoGitInit: true
+        mode:
+          workspaceLock: true
+          workspaceLockScope: all
+          planModePolicy: clear
+        send:
+          interruptDefault: true
+        spawn:
+          staleMs: 15000
+    - id: tower-skills
+      name: 'dsh-tower/skills'
     - id: preset-tower-worker
       name: '@deepseek-ai/dsh-agent-preset'
       config:
@@ -21,3 +33,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,17 @@
+# dsh-tower documentation
+
+English is the source of truth; a Chinese translation lives in [zh/README.md](zh/README.md).
+
+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) → [Error codes](reference/errors.md) → [Events](reference/events.md) → [Doctor](reference/doctor.md) → [Testing](reference/testing.md) → [Batches/leases/legacy](reference/operations.md) → [Security](operations/security.md) |
+| Maintainer | [Architecture](architecture/overview.md) → [Config](reference/config.md) → [Hot reload](guide/hot-reload.md) → [Contributing](../CONTRIBUTING.md) |
+
+Reference pages are the source of truth for the current release; the [tools reference](reference/tools.md),
+[blocker list](reference/blockers.md) and [error codes](reference/errors.md) are checked against the
+implementation by `npm run docs:check` in CI (including the Chinese pages).
+
+Other useful pages: [Install, upgrade and migration](guide/install-upgrade-migration.md), [Hot reload](guide/hot-reload.md), [FAQ](faq.md), [CHANGELOG](../CHANGELOG.md).

package/docs/architecture/overview.md

@@ -0,0 +1,70 @@
+# Architecture and state machine
+
+## Components
+
+```
+Host plugin (index.js)
+ ├─ /tower command + Tower mode (guard, prompt section, tower_mode/tower_control, /tower reload)
+ ├─ lib/tools.js  -> 19 repository tools incl. tower_diff, tower_findings and tower_interrupt
+ │                   (+ tower_reload while dev.hotReload is on; fails reload-unavailable without HMR)
+ └─ lib/tower.js  -> Tower domain: missions, gates, worktrees, roster, review, findings, 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 + profile/repo layers + runtime snapshot
+       ├─ lib/errors.js       stable tool error codes and classification
+       ├─ lib/workspaceLock.js  optional one-Tower-session-per-repository advisory lock
+       ├─ lib/hmr.js          optional DSH HMR bridge (tower_reload / /tower reload)
+       └─ lib/modeStore.js    per-agent Tower mode persistence
+Subagents
+ ├─ tower-worker   (dsh-tower/worker)   read/write/edit/pwsh + mission tools + findings
+ └─ tower-reviewer (dsh-tower/reviewer) read/glob/grep + tower_diff + review/finding (read-only)
+```
+
+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 |