dsh-tower 2.0.2 → 2.0.4

package/docs/guide/scenarios-and-philosophy.md

@@ -3,14 +3,15 @@
 [简体中文](../zh/guide/scenarios-and-philosophy.md)
 
 Tower is not a replacement for every multi-agent pattern. It is a **delivery protocol for changes to a
-Git repository**: a small number of bounded missions, isolated writers, independent review, evidence,
-and a merge gate. This page explains the design choices behind it, the situations where it pays off,
-and when Agent Teams, Ralph loops, Workflow orchestration, or ordinary parallel subagents are a better
-fit.
+Git repository**: a small number of bounded missions, isolated writers, optional independent review,
+evidence, and a merge gate. This page explains the design choices behind it, the situations where it
+pays off, and when Agent Teams, Ralph loops, Workflow orchestration, or ordinary parallel subagents are
+a better fit.
 
-If you only remember one sentence: **use Tower when the output is a reviewed, integrated repository
-change; use the other patterns when the output is exploration, repeated attempts, or programmatic
-fan-out.**
+If you only remember one sentence: **use Tower when the output is an integrated repository change that
+must land through a controlled merge; use the other patterns when the output is exploration, repeated
+attempts, or programmatic fan-out.** Enable `review.requireReview` when the change also needs an
+independent reviewer.
 
 ## 1. The design philosophy
 
@@ -19,8 +20,8 @@ Tower makes several deliberate trade-offs. They explain both its strengths and i
 ### 1.1 The repository is the unit of accountability
 
 A mission is not a chat thread or a task card. It is a contract attached to a branch and a worktree,
-with a declared write scope, dependencies, completion evidence, and a review record. The question
-"what changed, who changed it, and what proved it?" has a durable answer in
+with a declared write scope, dependencies, completion evidence, and an optional review record. The
+question "what changed, who changed it, and what proved it?" has a durable answer in
 `<git-common-dir>/dsh-tower/state.json` and the Git history, not only in a conversation.
 
 ### 1.2 One writer per mission
@@ -38,10 +39,17 @@ requirements are still being discovered.
 
 ### 1.4 Integration is a separate, privileged step
 
-Workers never merge. A reviewer inspects a specific branch tip; the tower runs preflight; only then
-does `tower_merge` perform a `--no-ff` merge. The gate re-checks scope, base freshness, tasks, review
-binding, worktree ownership, worker state, tests, and evidence. Separation of duties is the point:
-the agent that wrote the code is not the agent that approves it, and neither is the agent that merges.
+Workers never merge. The tower runs preflight; only then does `tower_merge` perform a `--no-ff` merge.
+The gate re-checks scope, base freshness, tasks, worktree ownership, worker state, tests, and evidence.
+When review is enabled, a reviewer also inspects a specific branch tip and the gate checks the review
+binding. Separation of duties is the point when review is on: the agent that wrote the code is not the
+agent that approves it, and neither is the agent that merges.
+
+Independent review is optional by default: `review.requireReview:true` enforces it (and then a complete
+mission must carry a clean, merge-approved review from a reviewer bound to the branch tip). Set the flag
+to `true` for sensitive repositories; `reviewPolicy:"none"` + a reason + `gates.allowReviewExemption:true`
+remains available as a per-mission exemption when the global gate is on. Reviews can be submitted and
+recorded either way.
 
 ### 1.5 Evidence over assertion
 
@@ -53,18 +61,20 @@ close a finite set of missions only when their required evidence exists.
 ### 1.6 Fail closed, recover explicitly
 
 Tower prefers a visible blocker over a silent repair. A stale worker is marked, not assumed dead; a
-dirty base blocks a merge; a moved review tip blocks a merge; a crash during merge leaves a persistent
-intent that the next `tower_merge` reconciles. The cost is occasional manual cleanup; the benefit is
-that state never lies about what was integrated.
+dirty base blocks a merge; with the review gate on, a moved review tip blocks a merge; a crash during
+merge leaves a persistent intent that the next `tower_merge` reconciles. The cost is occasional manual
+cleanup; the benefit is that state never lies about what was integrated.
 
-### 1.7 The human owns the mode
+### 1.7 Mode control is explicit and attributable
 
 Tower mode changes the session's stance: it narrows the tool surface and injects the mission protocol.
-The shipped patch allows the model to toggle it with a stated reason, but the mode exists because a
-human asked for delivery discipline. Entering pauses an active goal and clears plan mode; leaving does
-not silently resume either. Tower intentionally refuses `goal`, `todo`, Team task-board, Workflow,
-Ralph, and ordinary subagent tools while it is active, so two orchestration protocols do not fight over
-one session.
+The user can always change it with `/tower`; by default the model can also enter or leave with
+`tower_control`, provided it states a concrete reason. Every change records the actor and reason. The
+design point is not that one side owns the switch, but that toggling is deliberate and visible; set
+`mode.allowAgentControl:false` if a deployment wants human-only control. Entering pauses an active goal
+and clears plan mode; leaving does not silently resume either. Tower intentionally refuses `goal`,
+`todo`, Team task-board, Workflow, Ralph, and ordinary subagent tools while it is active, so two
+orchestration protocols do not fight over one session.
 
 ### 1.8 Local-first, no hidden service
 
@@ -74,6 +84,18 @@ Git metadata, so it survives restarts and is visible to a human with ordinary Gi
 
 ## 2. Situations where Tower is a good fit
 
+The table is the quick version; the subsections below explain each row.
+
+| Situation | Concrete example | Why Tower |
+|---|---|---|
+| A feature with independent slices | Add OAuth: `token model` → `callback route` → `UI button` + a migration, four missions with mostly separate scopes | Isolated writers, scope reservation, one final review/merge |
+| Ordered refactor/migration | Rename `oldApi` across a monorepo: codemod → import cleanup → snapshots → docs, each depending on the previous merge | `deps`, branch freshness, serialized merges |
+| Investigation then change | A survey mission maps every caller of a deprecated crypto API; two build missions migrate and test | Survey cannot mutate; findings feed build missions |
+| Sensitive or release-bound change | A payments service change or a public library release needing test evidence and an auditable merge (enable review for an independent verdict) | Checks/runs, optional review binding, human-readable audit |
+| Long-running work | A multi-day dependency upgrade interrupted by restarts and context resets | Durable mission/roster/review/worktree state |
+| Hard integration boundary | Four services in one monorepo, each with an owner, then one release review | Parallel missions with a single merge gate |
+| Checkable definition of done | A task list plus required tests plus an optional independent review verdict | Completion/review evidence is visible to another agent |
+
 ### 2.1 A feature that naturally splits into independent slices
 
 Example: add OAuth login, split into "token model", "callback route", "UI button", and "migration +
@@ -105,11 +127,13 @@ silently widening it.
 
 ### 2.4 A sensitive repository or a release-bound change
 
-Example: a payments service, a library with external users, or a release branch. You want an
-independent reviewer, a specific reviewed commit, test evidence, and a human-visible audit trail.
+Example: a payments service, a library with external users, or a release branch. You want test
+evidence and a human-visible audit trail; when review is enabled, you also get an independent reviewer
+and a verdict bound to a specific reviewed commit.
 
-**Why Tower:** review binding, evidence gates, `MISSIONS.md`, activity log, and optional test discovery
-give you a defensible record. The reviewer is a separate read-only agent, not the author.
+**Why Tower:** evidence gates, `MISSIONS.md`, and the activity log give you a defensible record;
+when review is enabled, the reviewer is a separate read-only agent, not the author, and the verdict is
+bound to the tip.
 
 ### 2.5 Long-running work that spans context compaction or restarts
 
@@ -138,11 +162,11 @@ the chat", Tower is overhead.
 
 | Situation | Better fit | Why |
 |---|---|---|
-| One-file edit, typo, small hotfix | Ordinary agent in a single session | Worktree, review, and merge overhead dominate. |
+| One-file edit, typo, small hotfix | Ordinary agent in a single session | Worktree and merge overhead (plus review when enabled) dominate. |
 | Requirements are still being discovered | Ordinary agent, Plan mode, or Agent Teams | Tower asks for scope/tasks before work; a wrong contract causes re-planning. |
 | Open-ended research or brainstorming | Agent Teams, Workflow, or plain subagents | There is no repository change to isolate or merge. |
-| Many tiny independent tasks | Workflow or plain parallel subagents | Per-mission review/merge cost is too high. |
-| Interactive UI pairing / exploratory debugging | Ordinary agent (or a single worker) | Tight feedback loops and frequent human steering; the review gate adds latency. |
+| Many tiny independent tasks | Workflow or plain parallel subagents | Per-mission merge cost (and review when enabled) is too high. |
+| Interactive UI pairing / exploratory debugging | Ordinary agent (or a single worker) | Tight feedback loops and frequent human steering; an enabled review gate adds latency. |
 | A one-shot generation with no integration | Plain subagent/Workflow | No branch, no review, no merge decision. |
 | Cross-repository product work | Agent Teams + ordinary tools | Tower is scoped to one Git repository. |
 
@@ -155,12 +179,12 @@ integration, and what "done" means.**
 
 | Dimension | Tower | Agent Teams | Ralph loop | Workflow orchestration | Ordinary parallel subagents |
 |---|---|---|---|---|---|
-| Primary goal | Deliver reviewed repository changes | Collaborate across people/agents on a shared goal | Repeated fresh attempts at one objective | Programmatic fan-out/pipeline of agent work | Explore or implement in parallel |
+| Primary goal | Deliver integrated repository changes (optional independent review) | Collaborate across people/agents on a shared goal | Repeated fresh attempts at one objective | Programmatic fan-out/pipeline of agent work | Explore or implement in parallel |
 | Unit of work | Mission (branch + worktree + scope + tasks + review) | Task/teammate on a shared board | Round/attempt | Scripted step/stage | Prompt/task per child |
 | Isolation | Git worktree + branch per mission; one writer per mission | Shared workspace; coordination by task ownership | Fresh child per round; no built-in branch/merge contract | Per-step child; no Git isolation | Child sessions; may share workspace |
 | Durable state | Git metadata + JSON state + activity + board | Team task board + sessions | Minimal; each round starts fresh | Run record/results; not a merge ledger | Session/subagent records |
-| Integration authority | Tower only, after review + gate | Humans/teammates merge or edit manually | Usually the parent/worker applies results | Script applies results | Parent applies results |
-| Review / gate | Mandatory independent review + preflight/merge gate | Review is a collaboration convention, not a hard gate | No built-in review gate | No built-in review gate | No built-in review gate |
+| Integration authority | Tower only, after preflight/gate (plus review when enabled) | Humans/teammates merge or edit manually | Usually the parent/worker applies results | Script applies results | Parent applies results |
+| Review / gate | Optional independent review (enable `review.requireReview`) + preflight/merge gate | Review is a collaboration convention, not a hard gate | No built-in review gate | No built-in review gate | No built-in review gate |
 | Parallelism | Multiple missions, disjoint scopes, serialized merges | Many teammates, shared board | Sequential rounds (or external fan-out) | High fan-out, script-controlled | High fan-out |
 | Human role | Owns the mode; can inspect evidence and release | Collaborator/coordinator | Author of the repeated objective | Author of the orchestration script | Delegator |
 | Best for | Feature delivery, migrations, release-bound changes | Design, research, cross-cutting collaboration | Iterative search/repair with fresh context | Large audits, batch analysis, deterministic pipelines | Quick exploration or independent subtasks |
@@ -170,11 +194,13 @@ integration, and what "done" means.**
 
 Ordinary `subagent`/`subagent_fork` calls are cheap and flexible. They are the right tool for "read
 these five files in parallel" or "try three approaches". They do not provide a write scope, a
-dedicated worktree, a durable mission, an independent review, or a merge gate. Tower wraps the same
-subagent primitive in those contracts; it also costs more per child.
+dedicated worktree, a durable mission, independent review, or a merge gate. Tower wraps the same
+subagent primitive in those contracts; it also costs more per child. (Review is optional: enable
+`review.requireReview` when you need the reviewer role.)
 
 Choose subagents when the work is read-mostly, short-lived, or you will integrate the result
-yourself. Choose Tower when the result must land on a branch and survive a review.
+yourself. Choose Tower when the result must land on a branch under a controlled merge; enable review
+when it must also survive independent review.
 
 ### 4.2 Tower vs Agent Teams
 
@@ -182,11 +208,11 @@ Agent Teams is a **collaboration** pattern: a shared task board, durable teammat
 and interrupt, and a human/Lead coordinating work. It is excellent when the work is cross-cutting,
 exploratory, or needs several perspectives, and when the integration decision is human.
 
-Tower is a **delivery** pattern: mission contracts, Git isolation, review, and a hard merge gate. It
-has less flexible peer-to-peer coordination and more structure. Agent Teams can decide *what* to
-build and *whether* to proceed; Tower can then execute that decision as missions. They are sequential
-or complementary, not concurrent: Tower mode refuses the Team task-board tools so the two protocols do
-not compete for the same session.
+Tower is a **delivery** pattern: mission contracts, Git isolation, an optional review gate, and a hard
+merge gate. It has less flexible peer-to-peer coordination and more structure. Agent Teams can decide
+*what* to build and *whether* to proceed; Tower can then execute that decision as missions. They are
+sequential or complementary, not concurrent: Tower mode refuses the Team task-board tools so the two
+protocols do not compete for the same session.
 
 ### 4.3 Tower vs Ralph loop
 
@@ -194,9 +220,10 @@ Ralph runs the **same objective** through fresh agents, round after round, with
 memory. It is useful for iterative search, flaky repair, or "try again with fresh context". It has no
 mission contract, no independent review, and no merge gate.
 
-Tower is incremental: each mission has a bounded deliverable and lands through review. If the problem
-is "I do not know whether this can be done, and repeated fresh attempts may find a way", Ralph is
-often better. If the problem is "I know the slices; build and integrate them safely", Tower is better.
+Tower is incremental: each mission has a bounded deliverable and lands through the merge gate (with
+review when enabled). If the problem is "I do not know whether this can be done, and repeated fresh
+attempts may find a way", Ralph is often better. If the problem is "I know the slices; build and
+integrate them safely", Tower is better.
 You can use Ralph outside Tower mode to find an approach, then encode the result as Tower missions.
 
 ### 4.4 Tower vs Workflow orchestration
@@ -208,8 +235,8 @@ Git worktree, a review verdict, or a merge gate.
 
 Tower is a **repository delivery protocol** with a small number of missions, not a high-fan-out data
 plane. Use Workflow for "analyze 200 files in parallel"; use Tower for "make the 6 changes those
-analyses justify, with review and a merge". Tower mode refuses Workflow so a script cannot spawn
-competing writers under the Tower contract.
+analyses justify, with an optional review and a merge gate". Tower mode refuses Workflow so a script
+cannot spawn competing writers under the Tower contract.
 
 ### 4.5 Tower vs Plan mode
 
@@ -218,6 +245,60 @@ Tower entry clears an active plan (or refuses entry under `mode.planModePolicy:"
 Tower session cannot use the goal/todo/team/workflow tools. Plan first, then execute; do not expect
 Tower to discover the plan for you.
 
+### 4.6 Review is optional by default
+
+`review.requireReview:false` is the default, so a completed mission can merge without a reviewer for
+low-risk repositories, scratch work, or human-supervised sessions. Set it to `true` to enforce the
+independent review gate; the gate then re-checks `no-review`, `not-clean`, `review-hold`,
+`review-not-approved`, `tip-moved`, and `review-mission-mismatch`. `tower_review` is always available
+and records verdicts even when the gate is off. For one mission only, with the global gate on, set
+`reviewPolicy:"none"` + a reason and `gates.allowReviewExemption:true`.
+
+### 4.7 Concrete examples by workflow
+
+**Tower** — output is a repository change that must land through isolation and a merge gate:
+
+- **OAuth login**: four missions (`token model`, `callback route`, `accept/decline API`, `UI`); the API depends on tokens and email.
+- **Node 18 → 22 upgrade**: survey breaking API usages, then codemod, test updates, CI config, release notes as separate missions.
+- **Deprecated crypto migration**: a read-only survey mission maps call sites; build missions replace them package by package.
+- **Release hardening**: three missions for the change, migration guide, and release notes; close a `tower_batch` with required tests before tagging.
+- **Monorepo service split**: one mission per package with disjoint scopes; a final review mission checks integration.
+
+**Agent Teams** — output is a decision, design, or cross-cutting collaboration, not a single mergeable branch:
+
+- Architecture review with a backend, frontend, and security teammate, each contributing findings to a shared board.
+- Incident postmortem: one teammate reconstructs the timeline, another checks logs, a third drafts actions.
+- Product requirements discovery: several perspectives converge on a spec; the human decides what to build.
+- Cross-repository investigation where there is no single repo to isolate or merge.
+
+**Ralph loop** — output is a better attempt at the *same* objective, with fresh context:
+
+- A flaky test that needs several independent attempts to reproduce and fix.
+- Performance optimization where each round tries a different hypothesis against an eval.
+- "Find any working approach" exploration where the parent does not know the path.
+- Repeated prompt/skill tuning until an eval threshold is met.
+
+**Workflow orchestration** — output is a large, programmatic fan-out or pipeline:
+
+- Audit 200 files for unsafe API usage and produce a structured report.
+- Run a dependency upgrade matrix across many packages/versions in parallel.
+- Multi-angle research or adversarial verification of a proposal.
+- Generate/translate/test many independent artifacts and aggregate the results.
+
+**Ordinary parallel subagents** — output is quick parallel read-mostly work or independent explorations:
+
+- Read five candidate files in parallel and summarize each.
+- Try three implementations of the same function and compare.
+- Scan a repo for a risky pattern without changing it.
+- Run independent document lookups before the parent writes the answer.
+
+**Mixed phases (recommended)** — analyze with Workflow/Teams, then deliver with Tower:
+
+1. Workflow audits 200 files → structured findings.
+2. Agent Teams reviews the findings and decides the top six changes.
+3. Tower missions implement those six changes with optional review and a merge gate.
+4. Ralph is used after merge only for a stubborn flaky test that does not need a new mission contract.
+
 ## 5. Worked scenarios
 
 ### Scenario A: four-slice feature
@@ -228,29 +309,31 @@ A team wants "organization invitations": token model, email delivery, accept/dec
    `src/ui/invites/**`; make the API depend on tokens and email.
 2. Spawn workers for the independent missions; the API waits for its deps.
 3. Each worker commits on its branch, completes with checks.
-4. Spawn reviewers; a clean+merge review is required.
+4. With `review.requireReview:true`, spawn reviewers and require a clean+merge verdict; otherwise
+   review is optional.
 5. `tower_preflight` and `tower_merge` each mission; resolve scope/base/review blockers.
 6. `tower_teardown`; `MISSIONS.md` is the human-readable record.
 
 **Why not Team/Workflow?** The work is a known set of repository changes that must land in a specific
-order with independent review. Team tasks would not isolate writes; Workflow would analyze but not
-gate the merge.
+order under a merge gate (and optional independent review). Team tasks would not isolate writes;
+Workflow would analyze but not gate the merge.
 
 ### Scenario B: migration with a survey
 
 1. Survey mission: "map all callers of `oldApi`"; scope empty, read-only.
 2. Build missions: codemod, test updates, docs; depend on the survey's findings.
-3. Reviewers check the diff against the survey; tests must pass for the reviewed tip.
+3. With review enabled, reviewers check the diff against the survey; the tests gate still validates the
+   current branch tip. With the default optional review, skip the reviewer and rely on the same gate/tests.
 4. Merge in dependency order.
 
 **Why not plain subagents?** The survey must not accidentally mutate; the codemod must not touch
-out-of-scope files; the review must bind to the exact commit.
+out-of-scope files; with review enabled, the review must bind to the exact commit.
 
 ### Scenario C: incident hotfix
 
 A one-line fix in production. Use an ordinary agent, commit and push through your normal process.
-Tower would add a worktree, a reviewer, a gate, and a merge step; for a one-line urgent fix that is
-mostly latency. If the "hotfix" is actually several coordinated changes, Tower becomes reasonable.
+Tower would add a worktree, a merge gate, and (if enabled) a reviewer; for a one-line urgent fix that
+is mostly latency. If the "hotfix" is actually several coordinated changes, Tower becomes reasonable.
 
 ### Scenario D: broad codebase audit
 
@@ -261,8 +344,9 @@ Tower missions from those findings.
 ### Scenario E: sensitive release
 
 A library release with external consumers. Plan missions for the change, migration guide, and
-release notes; require tests and review; use `tower_batch` to close the release evidence only when
-all required checks are present; merge and tag outside Tower as your release process requires.
+release notes; enable `review.requireReview:true` if the release requires independent review, require
+tests, and use `tower_batch` to close the release evidence only when all required checks are present;
+merge and tag outside Tower as your release process requires.
 
 ## 6. Choosing in practice: a short decision path
 
@@ -270,8 +354,9 @@ all required checks are present; merge and tag outside Tower as your release pro
 2. **Would you open a PR for it?** No → Tower is too heavy; use a normal agent.
 3. **Do the slices have stable scopes and a known definition of done?** No → plan/explore first; then
    return to Tower.
-4. **Do you need independent review and a merge gate?** Yes → Tower. If no, plain subagents may be
-   enough.
+4. **Do you need a merge gate?** Repository changes with integration risk → Tower. Enable
+   `review.requireReview:true` if you also need independent review. If neither isolation nor evidence
+   is needed, plain subagents may be enough.
 5. **Do you need many parallel analyses or repeated fresh attempts?** Use Workflow/Ralph for that
    phase; encode the resulting changes as Tower missions.
 6. **Do you need cross-cutting human collaboration?** Use Agent Teams to decide; execute the decided
@@ -279,12 +364,13 @@ all required checks are present; merge and tag outside Tower as your release pro
 
 ## 7. Cost, limits, and anti-patterns
 
-- **Per-mission overhead is real**: worktree creation, spawn, completion checks, review round, gate,
-  merge. Keep missions meaningful (roughly a PR-sized slice), not one task per function.
+- **Per-mission overhead is real**: worktree creation, spawn, completion checks, an optional review
+  round, gate, merge. Keep missions meaningful (roughly a PR-sized slice), not one task per function.
 - **Merges serialize**: overlapping scopes auto-add dependencies; independent missions still merge
   one at a time onto the base. Do not expect linear speedup for merge-heavy work.
-- **Review is not free**: every mission needs a reviewer and a clean verdict. Exemptions are opt-in
-  and require a reason; they are not the default.
+- **Review is not free when enabled**: each mission then needs a reviewer and a clean verdict.
+  `review.requireReview:false` (the default) makes review optional; when the gate is on, exemptions
+  are opt-in and require a reason.
 - **Too-fine missions** increase coordination and merge cost. **Too-coarse missions** lose the benefit
   of parallel review and make scope conflicts likely.
 - **Tower is not a sandbox**: it is a coordination protocol. Host permissions, repository hooks, and
@@ -298,9 +384,11 @@ all required checks are present; merge and tag outside Tower as your release pro
 
 - [ ] The work produces a repository change that deserves a PR-style review.
 - [ ] I can name 2–8 missions with non-overlapping scopes and a rough dependency order.
-- [ ] Each mission has a testable definition of done (tasks, checks/tests, review).
+- [ ] Each mission has a testable definition of done (tasks, checks/tests, optional review).
+- [ ] If this change needs independent review, `review.requireReview` is on (default is off).
 - [ ] I know which missions can run in parallel and which must wait.
-- [ ] I accept the review/merge overhead and will inspect `MISSIONS.md`/the branch.
+- [ ] I accept the merge-gate overhead (and review overhead if enabled) and will inspect
+      `MISSIONS.md`/the branch.
 - [ ] I am not currently relying on a Team task board, Workflow script, Ralph loop, or plan mode in
       the same session.
 - [ ] I have a recovery path if a worker stalls (interrupt/adopt) or a merge conflicts.

package/docs/operations/security.md

@@ -4,9 +4,15 @@ Tower's guarantees are **coordination guarantees**, not a sandbox. Understand wh
 
 ## Enforced by the plugin
 
-- **Review binding.** `tower_review` records the branch tip it inspected; the gate rejects a moved tip
-  (`tip-moved`) unless a clean conflict-free rebase waived it. A reviewer that modifies the branch after
-  spawning is rejected (`reviewer must not modify the mission branch`).
+- **Review binding (when review is enabled).** `tower_review` records the branch tip it inspected;
+  with `review.requireReview:true`, the gate rejects a moved tip (`tip-moved`) unless a clean
+  conflict-free rebase waived it. A reviewer that modifies the branch after spawning is rejected
+  (`reviewer must not modify the mission branch`).
+- **Review is optional by default, enforceable by config.** `review.requireReview:false` is the
+  default; set it to `true` to enforce the independent-review gate. Mission-level
+  `reviewPolicy:"none"` + reason is the narrower exemption when the global gate is on. With the gate
+  off, separation of duties is not enforced by the plugin; use it only for trusted or human-supervised
+  repositories.
 - **Role enforcement.** The caller is resolved against the roster. Worker mission updates are limited to
   task/blocker/note; `completed`, `abandoned`, scope widening and blocker clearing are tower-only, and
   completion (with its unread-inbox/commit gates) must go through `tower_complete`. Tower-only tools reject
@@ -17,18 +23,18 @@ Tower's guarantees are **coordination guarantees**, not a sandbox. Understand wh
   file findings, and submit a review.
 - **Scope gate.** A mission may only change files matched by its declared scope globs; out-of-scope
   changes block the merge.
-- **Worktree isolation.** Workers operate in a dedicated worktree and branch; the main checkout is only
-  touched by merge/teardown.
-- **Human-owned mode.** `/tower` is user-owned. With `mode.allowAgentControl` the model may toggle it,
-  but must state a reason; the shipped patch enables that by default — set it to `false` to make the
-  mode human-only.
+- **Mode control is explicit and configurable.** `/tower` is always available. With
+  `mode.allowAgentControl:true` (the default), the model may also enter/leave with `tower_control` and
+  a mandatory reason; every change records actor/reason. Set it to `false` for human-only mode control.
+  The point is an attributable change, not a particular owner.
 - **No automatic goal resume.** Entering pauses the active goal; leaving does not resume it.
 - **Advisory workspace lock.** `mode.workspaceLock` prevents two Tower sessions from accidentally driving
   one repository; it is a same-user coordination lock, not authentication between users.
-- **Test discovery is repository code.** `tower_test`/`tower_complete` execute `package.json`
-  `tower.testDiscovery` commands in the mission worktree with the DSH process's OS permissions. Set
-  `tests.allowPackageDiscovery:false` for untrusted repositories; output/time budgets fail closed but are
-  not a sandbox.
+- **Test discovery is repository code.** `tower_test`/`tower_complete` can execute `package.json`
+  `tower.testDiscovery` commands in the mission worktree with the DSH process's OS permissions.
+  `tests.admission` defaults to `off`, so this happens only on an explicit `tower_test`; set
+  `tests.allowPackageDiscovery:false` for untrusted repositories. Output/time budgets fail closed but
+  are not a sandbox.
 - **Review exemption is opt-in.** `reviewPolicy:"none"` requires `gates.allowReviewExemption:true` and a
   non-empty reason. It is off by default because a model-driven tower could otherwise self-exempt; the
   exemption and its reason are recorded in state/events and never granted to workers.
@@ -40,6 +46,11 @@ Tower's guarantees are **coordination guarantees**, not a sandbox. Understand wh
 
 ## Not enforced by the plugin (deployment concerns)
 
+- **Worktree isolation is a protocol convention, not an OS sandbox.** Workers are assigned a dedicated
+  worktree and branch and told to stay there, but the `tower-worker` preset still includes `pwsh`,
+  `write`, and `edit`; those tools can write absolute paths or run Git in the main checkout. The scope
+  gate checks the committed branch diff, not filesystem access. For hard isolation use a container,
+  separate OS user, or a restricted host tool policy.
 - **Sandboxing.** Host plugins run outside the filesystem sandbox; the reviewer's shell ability is
   removed at the tool-surface level, but the underlying process still has whatever OS permissions DSH
   has. Deployments that need hard isolation must restrict the process/user themselves.

package/docs/reference/blockers.md

@@ -1,14 +1,15 @@
 # Blockers and failure codes
 
 `tower_preflight` returns `{ok:false, blockers:[{code, detail}]}`. `tower_merge` and `tower_rebase`
-return the same shape for operation failures. Codes are stable; the detail is human-facing.
+return the same shape for operation failures. Codes are stable; the detail is human-facing. The
+tables below define 32 stable blocker/failure codes.
 
 ## Gate blockers (26)
 
 | Code | Meaning / next action |
 |---|---|
 | `mission-missing` | Unknown mission id. Check `tower_status`. |
-| `mission-not-completed` | Mission is not `completed`; only a completed mission (awaiting review) merges. |
+| `mission-not-completed` | Mission is not `completed`; only a completed mission (ready for preflight/merge) merges. |
 | `tasks-open` | Open tasks remain; the worker must finish or `task_drop` with a reason. |
 | `blockers-present` | The mission has blockers; clear them after resolving. |
 | `no-check-evidence` | `gates.requireChecks` is enabled and the completion report has no `checks`. Return the completed mission to `active`, re-run `tower_complete` with checks, then review again. |
@@ -18,20 +19,20 @@ return the same shape for operation failures. Codes are stable; the detail is hu
 | `out-of-scope` | Changed files outside the mission scope; widen scope deliberately or revert. |
 | `base-dirty` | The main checkout has uncommitted changes the merge would overwrite. |
 | `deps-unmerged` | A dependency mission is not merged/abandoned. |
-| `no-review` | No review on the branch: spawn a reviewer. |
-| `review-mission-mismatch` | The latest review belongs to another mission. |
-| `not-clean` | Latest review is `p1-Nitems`/`p2-Nitems`; another round is required. |
-| `review-hold` | Latest review recommends hold; a later clean review must supersede it. |
-| `review-not-approved` | Latest clean review says `fix-then-merge` or `hold`; only `merge` approves. |
-| `tip-moved` | The branch changed after review; review again (or use a clean rebase waiver). |
+| `no-review` | `review.requireReview:true` and no review exists on the branch: spawn a reviewer (or disable the review gate). |
+| `review-mission-mismatch` | `review.requireReview:true` and the latest review belongs to another mission. |
+| `not-clean` | `review.requireReview:true` and latest review is `p1-Nitems`/`p2-Nitems`; another round is required. |
+| `review-hold` | `review.requireReview:true` and latest review recommends hold; a later clean review must supersede it. |
+| `review-not-approved` | `review.requireReview:true` and latest clean review says `fix-then-merge` or `hold`; only `merge` approves. |
+| `tip-moved` | `review.requireReview:true` and the branch changed after review; review again (or use a clean rebase waiver). |
 | `worker-busy` | A roster agent for this mission is running; wait or retire it. |
 | `worker-status-unknown` | The parent catalog is unavailable, so a live roster agent cannot be proven stopped; retry after the catalog recovers or adopt it. |
 | `base-wrong-branch` | The main checkout is not on the recorded base branch. |
 | `branch-owned-by-closed-missions` | The mission is already merged/abandoned; re-plan under a new title. |
 | `worker-stale` | A roster worker for this mission has no catalog activity beyond `spawn.staleMs`; adopt it (or interrupt it only if it is actually running) before merge. |
-| `tests-missing` | `gates.requireTests` is enabled and there is no passing discovery receipt for the reviewed tip; run `tower_test` or `tower_complete`. |
+| `tests-missing` | `gates.requireTests` is enabled and there is no passing discovery receipt for the current branch tip; run `tower_test` or `tower_complete`. |
 | `tests-failed` | The latest discovery receipt failed or did not meet minCount/required checks. Fix the tests and re-run. |
-| `review-exemption-invalid` | The mission requests `reviewPolicy:"none"` but `gates.allowReviewExemption` is off (or the reason is missing). |
+| `review-exemption-invalid` | `review.requireReview:true` and the mission requests `reviewPolicy:"none"` while `gates.allowReviewExemption` is off (or the reason is missing). |
 | `merge-intent-pending` | A merge intent was recorded before a crash/failure; run `tower_merge` to reconcile before another gate. |
 
 ## Merge failures (4)

package/docs/reference/config.md

@@ -22,7 +22,7 @@ win, profile keys survive when the repo does not set them. `tower_status` report
 
 ```json
 {
-  "review": { "maxRoundsPerReviewer": 3 },
+  "review": { "requireReview": true, "maxRoundsPerReviewer": 3 },
   "merge": { "timeoutMs": 1800000 },
   "worktrees": { "root": "D:/tower-worktrees" },
   "spawn": { "reviewerPreset": "tower-reviewer", "maxDepth": 2 }
@@ -38,12 +38,12 @@ violates the declared schema (for example `merge.timeoutMs` below 1000) fail wit
 | Key | Default | Meaning |
 |---|---|---|
 | `section` | `''` | Legacy alias: replace the whole Tower-mode prompt text. Empty keeps the built-in reminder. |
-| `allowAgentControl` | `false` (bundled patch: `true`) | Legacy alias: register `tower_control`. |
+| `allowAgentControl` | `true` (alias of `mode.allowAgentControl`) | Legacy alias: register `tower_control` so the model may toggle the mode. |
 | `init.autoGitInit` | `false` (bundled patch: `true`) | `tower_init` may run `git init` + an empty initial commit when `repoRoot` is an absolute, existing directory that is not a repository. |
 | `init.snapshotDirty` | `false` | `tower_init` may snapshot uncommitted **tracked** changes into a dangling commit used as the mission baseline (untracked files are not included; the commit is kept alive under `refs/tower/snapshot/*`). |
 | `mode.promptSection` | `''` | Replacement prompt text (takes precedence over `section` when both set). |
 | `mode.sectionAppend` | `''` | Extra text appended after the reminder (team conventions). |
-| `mode.allowAgentControl` | `false` | Register `tower_control`; the model may enter/leave with a reason. |
+| `mode.allowAgentControl` | `true` | Register `tower_control`; the model may enter/leave with a reason. Set `false` for human-only mode control. |
 | `mode.autoPauseGoal` | `true` | Pause an active goal on entry; the goal is never auto-resumed on exit. |
 | `mode.requireResumeAuthorization` | `false` | Resuming a mission paused with `pauseCause:user` requires an `authorization` reference. |
 | `mode.workspaceLock` | `false` (bundled patch: `true`) | Allow only one Tower session per repository (`tower.lock`); others get `workspace-busy`. |
@@ -54,9 +54,11 @@ violates the declared schema (for example `merge.timeoutMs` below 1000) fail wit
 | `mode.denyTools` | goal/todo/team/workflow/subagent tools | Tools refused while the mode is active (12 defaults). |
 | `mode.storePath` | `$DSH_HOME/tower-mode` | Directory for `modes.json`. |
 | `mode.maxEntries` | `200` | Maximum persisted mode entries (1–2000). |
+| `review.requireReview` | `false` | Enforce an independent clean review before merge. Default `false` (review optional); set `true` to require `no-review`/`not-clean`/`review-hold`/`review-not-approved`/`tip-moved`/`review-mission-mismatch` checks. `tower_review` remains available either way. |
 | `review.maxRoundsPerReviewer` | `5` | Review-round cap per reviewer per branch. |
 | `merge.timeoutMs` | `900000` (15 min) | Default `tower_merge` timeout, including hooks. A per-call `timeoutMs` wins. |
 | `merge.maxBufferBytes` | `67108864` (64 MB) | Merge output buffer. |
+| `git.timeoutMs` | `15000` | Default timeout for Git commands other than merge; merge uses `merge.timeoutMs`. |
 | `worktrees.root` | `''` | Default worktree parent; empty derives `<checkout parent>/.dsh-tower-worktrees/<hash>`. |
 | `spawn.workerPreset` | `tower-worker` | Preset used for `role=worker`. |
 | `spawn.reviewerPreset` | `tower-reviewer` | Preset used for `role=reviewer`. |
@@ -71,14 +73,14 @@ violates the declared schema (for example `merge.timeoutMs` below 1000) fail wit
 | `send.maxPerMinute` | `120` | Per-repository `tower_send` rate limit (0 disables); exceeding it returns `rate-limited`. |
 | `send.interruptDefault` | `false` (bundled patch: `true`) | Default for `tower_send.interrupt` (interrupt the running turn before delivering). |
 | `tests.enabled` | `true` | Run declared test discovery when the worktree `package.json` configures it. |
-| `tests.admission` | `complete` | `spawn` runs discovery before starting a worker, `complete` at `tower_complete`, `off` only on explicit `tower_test`. |
+| `tests.admission` | `off` | `spawn` runs discovery before starting a worker, `complete` at `tower_complete`, `off` only on explicit `tower_test` (default; repository code is not executed automatically). |
 | `tests.timeoutMs` | `60000` | Per discovery command timeout. |
 | `tests.maxBytes` | `16777216` (16 MiB) | Captured stdout cap per command. |
 | `tests.autoChecks` | `true` | Attach an automatic `tests` check to the completion report. |
 | `tests.allowPackageDiscovery` | `true` | Allow repo-controlled `tower.testDiscovery` commands (executes worktree code; see security). |
 | `gates.requireChecks` | `false` | Require at least one `tower_complete.checks` entry before merge (`no-check-evidence`). |
-| `gates.requireTests` | `false` | Require a passing discovery receipt for the reviewed tip (`tests-missing`). |
-| `gates.allowReviewExemption` | `false` | Allow `reviewPolicy:"none"` + reason to skip review blockers; default off deliberately. |
+| `gates.requireTests` | `false` | Require a passing discovery receipt for the current mission branch tip (`tests-missing`); independent of the review gate. |
+| `gates.allowReviewExemption` | `false` | With `review.requireReview:true`, allow `reviewPolicy:"none"` + a non-empty reason to skip review blockers. Off deliberately; irrelevant while the global review gate is off. |
 | `docs.board` | `true` | Write `MISSIONS.md` after mutations. |
 | `docs.boardLocation` | `common` | `common` = `<git-common-dir>/dsh-tower/MISSIONS.md`; `repo` = `<repoRoot>/MISSIONS.md`. |
 | `leases.ttlMs` | `900000` | Default advisory lease lifetime; expiry never auto-releases. |

package/docs/reference/errors.md

@@ -1,7 +1,12 @@
 # Tool error codes
 
 Tool failures are thrown errors, not `{ok:false}` results (gate outcomes are the exception: see
-[blockers.md](blockers.md)). Every thrown error carries a stable code as a message prefix:
+[blockers.md](blockers.md)). Every thrown error carries a stable code as a message prefix. This
+release defines 31 tool error codes.
+
+Every `TowerToolError` also carries `retryable` (boolean), `nextAction` (string or `null`) and `details`
+(structured context or `null`) for programmatic callers; the message prefix remains the stable contract
+for text-only clients.
 
 ```
 [tower:mission-not-found] unknown mission "M9"
@@ -18,6 +23,7 @@ message without a more specific match is reported as `tool-internal`.
 | `mission-not-found` | No mission with that id exists. | a stale or mistyped `M9` |
 | `finding-not-found` | No finding with that id exists. | `tower_findings({id:"F99"})` |
 | `invalid-transition` | The requested state transition is not allowed. | a blocked→merged attempt; a finding transition not in the graph; a reviewer mutating findings; completing a mission with open tasks, blockers, no commits, or unread inbox messages. |
+| `worktree-dirty` | The mission worktree has uncommitted changes and cannot complete. | staged, modified, or untracked files left behind before `tower_complete` |
 | `state-locked` | Another Tower writer holds the state lock. | concurrent mutation after the lock timeout |
 | `state-corrupt` | The Tower state file is unreadable or invalid. | hand-edited `state.json` |
 | `config-invalid` | Tower configuration is invalid. | malformed repo `config.json`, a value that violates the schema |

package/docs/reference/events.md

@@ -1,8 +1,8 @@
 # Tower events
 
 Tower emits process-local Cordis events after successful tool calls (mutations and read-only tools), so
-other plugins can observe a repository without polling. Events are **not** sent over the network and carry
-no telemetry.
+other plugins can observe a repository without polling. This release emits 29 process-local events.
+Events are **not** sent over the network and carry no telemetry.
 
 ```js
 ctx.on('tower/merge', (payload) => {
@@ -32,14 +32,17 @@ ctx.on('tower/merge', (payload) => {
 | `tower/status` | `tower_status` read the dashboard |
 | `tower/preflight` | `tower_preflight` evaluated the gate |
 | `tower/doctor` | `tower_doctor` completed its read-only checks |
+| `tower/recover` | `tower_recover` inspected or cleared a stale state lock |
 | `tower/test` | `tower_test` ran discovery |
 | `tower/batch` | `tower_batch` created, inspected or closed a batch |
 | `tower/resource` | `tower_resource` acquired/released/inspected leases |
 | `tower/import_legacy` | `tower_import_legacy` stored a legacy snapshot |
 | `tower/legacy_map` | `tower_legacy_map` mapped or listed legacy ids |
+| `tower/mode` | `tower_mode` read/changed the session stance (`value.mode`, `allowAgentControl`, `deniedWhileActive`) |
+| `tower/control` | `tower_control` entered/left the mode (`value.mode`, actor/reason in `value`) |
+| `tower/reload` | `tower_reload` returned a reload schedule/result |
 
-`tower_mode`, `tower_control` and `tower_reload` do not emit Tower events. Payloads are JSON:
-`{tool, repoRoot, value}`. Listener exceptions never affect the tool result.
+Payloads are JSON: `{tool, repoRoot, value}`. Listener exceptions never affect the tool result.
 
 For a durable audit trail use `<git-common-dir>/dsh-tower/activity.jsonl` and `MISSIONS.md` instead;
 events are process-local and are not replayed.

package/docs/reference/testing.md

@@ -50,7 +50,8 @@ discovery fails.
 - `tower_test({repoRoot,missionId})` runs discovery on demand and records a receipt.
 - `tower_complete` adds a `tests` check when `tests.autoChecks` is on.
 - `gates.requireChecks` requires any completion check; `gates.requireTests` requires a passing receipt
-  for the reviewed tip (`tests-missing`).
+  for the current mission branch tip (`tests-missing`). Review is independent of this gate: with
+  `review.requireReview:false` the tests gate still checks the branch tip.
 
 ## Trust boundary