dsh-tower 2.0.3 → 2.1.0-beta.1

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,15 +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 remains available as a per-mission
-exemption when the global gate is on. Reviews can be submitted and recorded either way.
+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
 
@@ -58,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
 
@@ -86,7 +91,7 @@ The table is the quick version; the subsections below explain each row.
 | 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 a reviewed commit and test evidence | Review binding, checks/runs, human-readable audit |
+| 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 |
@@ -122,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
 
@@ -155,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. |
 
@@ -172,11 +179,11 @@ 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 |
+| 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 |
@@ -187,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
 
@@ -199,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
 
@@ -211,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
@@ -225,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
 
@@ -241,12 +251,12 @@ Tower to discover the plan for you.
 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, prefer `reviewPolicy:"none"` + a
-reason while the global gate is on.
+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.6 Concrete examples by workflow
+### 4.7 Concrete examples by workflow
 
-**Tower** — output is a repository change that must land through isolation and review:
+**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.
@@ -286,7 +296,7 @@ reason while the global gate is on.
 
 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 review and merge.
+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
@@ -299,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
 
@@ -332,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
 
@@ -341,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
@@ -350,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
@@ -369,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,10 @@ 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
@@ -22,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.
@@ -43,8 +44,56 @@ Tower's guarantees are **coordination guarantees**, not a sandbox. Understand wh
 - **Legacy import is read-only.** Imported snapshots live under the canonical state directory and are never
   activated, adopted, or resumed; an operator must explicitly re-plan/migrate work.
 
+## Repository protection
+
+This section is about **this repository**, not about a repository Tower runs on. Server-side branch
+protection is not a plugin feature — Tower writes to the local base branch and cannot configure a
+remote — but `dsh-tower` enables it for its own `main`, because the code that is the gate is also the
+code an attacker would most want to change:
+
+- `main` requires a pull request for every change, **enforced for admins**, so a direct push is
+  rejected even for the maintainer.
+- Required checks are `test (22)`, `test (24)` and `mount`. The mount job packs the tarball and boots
+  it in a throwaway profile, so "the tests pass" cannot land a bundle that fails to appear after
+  `dsh plugin add`.
+- Force-push and branch deletion are blocked, so history cannot be rewritten under a published tag.
+- There are no mandatory approvals: with one maintainer, a self-approval requirement would be a rubber
+  stamp. The evidence instead is the four-line PR body (failure mode, change, test, blast radius) for
+  the two-key paths, written in [CONTRIBUTING.md](../../CONTRIBUTING.md#landing-changes).
+
+What this buys: no untested change reaches `main`, a red or missing required check cannot be bypassed
+by the owner, and history is append-only. What it does **not** buy: a second reader, protection against
+a compromised maintainer token, or any protection for the repositories Tower itself operates on — those
+remain deployment concerns. The settings, their rationale and a verification command are recorded in
+[SECURITY.md](../../SECURITY.md#repository-protection-on-main).
+
+## Model-initiated mode entry (threat model)
+
+`mode.allowAgentControl:true` means a prompt injection in a repository file, issue text, or fetched
+page can ask the model to “enter tower mode and fix this”. Tower does **not** authenticate the human
+intent behind that entry. What it does provide:
+
+- the entry is recorded with actor, action, reason, and timestamp; `tower_status.mode.history`
+  surfaces the recent transitions without grepping the activity log;
+- the model cannot merge without the preflight gate, review policy, scope checks, tests, and
+  clean-base checks; writing the plan does not bypass them;
+- workers are tool-restricted and instructed to stay in their worktree, but the main-checkout
+  protection is enforced by scope/merge checks and the preset, **not** by an OS sandbox;
+- `mode.workspaceLock` prevents a second Tower session from driving the same repository.
+
+It does **not** defend against: a model that legitimately passes every gate while acting on malicious
+instructions; repository hooks or test commands the repository itself declares; or filesystem/shell
+access outside the worktree by a worker that ignores its instructions. For a higher-assurance team,
+set `mode.allowAgentControl:false`, keep `review.requireReview:true`, review the repository before
+Tower work, and run the host under OS-level isolation.
+
 ## 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.
@@ -59,8 +108,10 @@ Tower's guarantees are **coordination guarantees**, not a sandbox. Understand wh
   from disk. Only enable HMR watch roots for checkouts you trust; a reload executes the current files.
 - **Prompt injection.** The reviewer reads untrusted branch content (diff/comments). The read-only preset
   limits impact, but no model-side protection is absolute.
-- **Base branch protection.** Tower writes to the local base branch; server-side branch protection/push
-  rules are not part of the plugin.
+- **Base branch protection.** Tower writes to the local base branch; server-side branch protection and
+  push rules are not part of the plugin. This repository's own `main` protection is described in
+  [Repository protection](#repository-protection); enabling equivalent protection on the repository you
+  run Tower on remains a deployment concern.
 
 ## Reporting
 

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.generated.md

@@ -0,0 +1,66 @@
+# Config reference (generated)
+
+> Generated by `npm run docs:generate:config` from `domain/config/schema.js`. Values are defaults before repo config.
+
+| Key | Default | Description |
+|---|---|---|
+| `section` | `""` | Legacy alias for mode.promptSection: replaces the whole Tower-mode system prompt text. |
+| `allowAgentControl` | `` | Legacy alias for mode.allowAgentControl: register tower_control so the model may toggle the mode. |
+| `init.autoGitInit` | `false` | tower_init may run git init and create an empty initial commit when the directory is not a repository. |
+| `init.snapshotDirty` | `false` | tower_init may snapshot uncommitted tracked changes into a dangling commit used as the mission baseline. |
+| `init.autoExclude` | `true` | Add in-repo Tower artifacts (MISSIONS.md, in-repo worktree roots) to .git/info/exclude so they do not look like user dirt. |
+| `mode.promptSection` | `` | Replacement Tower-mode system prompt text. Empty keeps the built-in reminder. |
+| `mode.sectionAppend` | `` | Extra text appended to the Tower-mode system prompt section (team conventions). |
+| `mode.allowAgentControl` | `true` | Register tower_control so the model may enter/leave the mode with a reason. |
+| `mode.autoPauseGoal` | `true` | Pause an active goal when entering Tower mode. |
+| `mode.requireResumeAuthorization` | `false` | Require an authorization reference when resuming a mission paused with pauseCause=user. |
+| `mode.requireHumanAckOnFirstEntry` | `false` | Require a human /tower ack before the model may enter Tower mode for the first time in a session. |
+| `mode.workspaceLock` | `false` | Allow only one Tower session per repository (advisory <git-common-dir>/dsh-tower/tower.lock). |
+| `mode.workspaceLockScope` | `"all"` | all = every repo-scoped tool acquires the workspace lock; mutations = only tools that write state/worktrees do. |
+| `mode.planModePolicy` | `"clear"` | On Tower entry: clear an active plan mode, or refuse to enter until the plan is exited. |
+| `mode.workspaceStaleMs` | `300000` | A workspace lock older than this is stale and can be taken over. |
+| `mode.heartbeatMs` | `10000` | Workspace-lock heartbeat interval while Tower mode is on. |
+| `mode.denyTools` | `["create_goal","todo_write","team_task_create","team_task_update","team_task_reopen","team_task_list","spawn_teammate","wait_agent","workflow","ralph","subagent","subagent_fork"]` | Tools refused while Tower mode is active. |
+| `mode.storePath` | `` | Directory for modes.json; defaults to $DSH_HOME/tower-mode. |
+| `mode.maxEntries` | `200` | Maximum persisted mode entries. |
+| `mode.lockTimeoutMs` | `5000` | How long saveModes waits for the cross-process modes.lock before giving up. |
+| `review.requireReview` | `false` | Require an independent clean review before merge. Default false: review is optional; set true to enforce the review gate globally. |
+| `review.maxRoundsPerReviewer` | `5` | Review-round cap per reviewer per mission branch. |
+| `merge.timeoutMs` | `900000` | Default tower_merge timeout, including pre-merge hooks. |
+| `merge.maxBufferBytes` | `67108864` | Captured merge output buffer. |
+| `git.timeoutMs` | `15000` | Default timeout for Git commands other than merge; merge uses merge.timeoutMs. |
+| `worktrees.root` | `` | Default parent directory for mission worktrees; empty derives <main-checkout-parent>/.dsh-tower-worktrees/<hash>. |
+| `spawn.workerPreset` | `"tower-worker"` | Agent preset for worker missions. |
+| `spawn.reviewerPreset` | `"tower-reviewer"` | Agent preset for reviewers. |
+| `spawn.maxDepth` | `1` | Subagent depth requested when spawning tower agents. |
+| `spawn.provider` | `` | Subagent provider id; empty picks spawn, then the first registered provider. |
+| `spawn.workerModel` | `{}` | Model route for workers; omitted inherits the parent session. |
+| `spawn.reviewerModel` | `{}` | Model route for reviewers; omitted inherits the parent session (recommended). |
+| `spawn.maxLiveWorkers` | `4` | Maximum live worker entries allowed per repository at once. |
+| `spawn.staleMs` | `15000` | Roster entries with no catalog activity after this age are marked stale and block merge (0 disables). |
+| `spawn.maxWaitMs` | `90000` | Upper bound for tower_spawn waitMs (default 90s, Kimi-compatible). |
+| `spawn.requireLease` | `` | Optional lease name tower_spawn must hold before starting a worker. |
+| `send.maxPerMinute` | `120` | Per-repository tower_send rate limit per minute (0 disables). |
+| `send.interruptDefault` | `false` | Default value of tower_send.interrupt when the caller omits it. |
+| `tests.enabled` | `true` | Run declared test discovery when a mission configures it. |
+| `tests.admission` | `"off"` | Run discovery before spawning a worker, when completing, or only on explicit tower_test (default off: repository code runs only on an explicit tower_test). |
+| `tests.timeoutMs` | `60000` | Per discovery command timeout. |
+| `tests.maxBytes` | `16777216` | Maximum captured stdout bytes per command. |
+| `tests.autoChecks` | `true` | Attach a tests check to the completion report when discovery runs. |
+| `tests.allowPackageDiscovery` | `true` | Allow package.json tower.testDiscovery commands from the mission worktree (executes repository code; see security docs). |
+| `gates.requireChecks` | `false` | Require at least one completion check (tower_complete.checks) before a mission can merge. |
+| `gates.requireTests` | `false` | Require a passing test-discovery receipt for the reviewed worktree tip before merge. |
+| `gates.allowReviewExemption` | `false` | Allow reviewPolicy:none missions with a non-empty reviewExemptionReason to skip review blockers. |
+| `docs.board` | `true` | Write a human-readable MISSIONS.md after mission changes. |
+| `docs.boardLocation` | `"common"` | common = <git-common-dir>/dsh-tower/MISSIONS.md; repo = <repoRoot>/MISSIONS.md. |
+| `tools.exposeOperational` | `true` | Master switch for batch/resource/import/legacy/recover/test/doctor tools. |
+| `tools.exposeBatch` | `true` | Register tower_batch. |
+| `tools.exposeImport` | `true` | Register tower_import_legacy/tower_legacy_map. |
+| `tools.exposeLeases` | `true` | Register tower_resource advisory leases. |
+| `tools.exposeTests` | `true` | Register tower_test; gates.requireTests requires it. |
+| `tools.exposeRecovery` | `true` | Register tower_recover (stale state-lock escape). |
+| `tools.exposeDoctor` | `true` | Register tower_doctor (read-only health contract). |
+| `leases.ttlMs` | `900000` | Default advisory lease lifetime; expiry never auto-releases. |
+| `dev.hotReload` | `true` | Register tower_reload and /tower reload when the DSH HMR service is available. |
+| `dev.reloadDelayMs` | `50` | Delay before a scheduled reload, so the tool result is delivered first. |
+| `dev.reloadRequiredIds` | `["tower-bundle","tower","tower-skills","preset-tower-worker","preset-tower-reviewer"]` | Loader entry ids passed to reconcileProfile as required. |