dsh-tower 2.1.0 → 2.4.0

package/app/tower.js

@@ -1,12 +1,14 @@
 // Tower domain: repo-scoped mission state machine, validation, and gates.
+//
+// #69: the app layer depends on the ports in ports/ and receives their
+// implementations through the deps object assembled by the composition root.
+// It imports no adapter and no infrastructure module.
 import path from 'node:path'
-import { fsp } from '../adapters/store-fs.js'
-import { defaultDeps } from '../adapters/default.js'
+import { assertPorts } from '../ports/index.js'
 import { validateCreate as validateBatchCreate, validateClose as validateBatchClose, summarize as summarizeBatch } from '../domain/batch.js'
-import { assertOwnership } from '../lib/worktreeOwnership.js'
 
-import { runtimeConfig, resolveRepoConfig } from '../lib/config.js'
 import { rebaseWaived } from '../domain/gate.js'
+import { DEFAULT_MERGE_TIMEOUT_MS, gitLockTimeoutMs } from '../domain/lockBudget.js'
 export { ROSTER_INACTIVE_STATES } from '../domain/roster.js'
 
 export { fileInScope, scopesOverlap, validateTitle, normalizeScope } from '../domain/scope.js'
@@ -14,6 +16,8 @@ export { missionSummary } from '../domain/summary.js'
 
 export { MISSION_STATUSES, SCHEMA_VERSION, MERGE_VERDICTS, FINDING_TYPES, FINDING_SEVERITIES, FINDING_STATUSES, FINDING_TRANSITIONS } from '../domain/mission.js'
 import { TowerToolError } from '../domain/errors.js'
+import { buildMissionEvent } from '../domain/events.js'
+import { applyLandedMerge } from '../domain/integration/merge.js'
 import { plan } from './plan.js'
 import { updateMission } from './mission.js'
 import { checkCompletion, complete } from './checkCompletion.js'
@@ -26,12 +30,11 @@ import { recordTestRun, recordLegacySnapshot, recordLegacyMap } from './recordin
 
 export const ROLES = ['worker', 'reviewer']
 const MAX_REVIEW_ROUNDS = 5
-const DEFAULT_MERGE_TIMEOUT_MS = 15 * 60 * 1000
 const MERGE_MAX_BUFFER = 64 * 1024 * 1024
 
 function mergeTimeoutMs(value, config) {
   if (value === undefined || value === null) {
-    const configured = (config ?? runtimeConfig()).merge.timeoutMs
+    const configured = (config ?? {}).merge?.timeoutMs
     return Number.isInteger(configured) && configured >= 1000 ? configured : DEFAULT_MERGE_TIMEOUT_MS
   }
   const ms = Number(value)
@@ -39,8 +42,8 @@ function mergeTimeoutMs(value, config) {
   return ms
 }
 
-async function commitParents(cwd, sha) {
-  const line = await defaultDeps.vcs.tryGit(cwd, ['rev-list', '--parents', '-n', '1', sha])
+async function commitParents(tower, cwd, sha) {
+  const line = await tower.deps.vcs.tryGit(cwd, ['rev-list', '--parents', '-n', '1', sha])
   return line ? line.trim().split(/\s+/).slice(1) : []
 }
 
@@ -49,10 +52,10 @@ async function commitParents(cwd, sha) {
  * `--no-ff` merges put the integrated branch on the second parent, so this is
  * the concrete evidence that a mission's work already landed in the base.
  */
-async function findLandedMerge(cwd, baseTip, tips) {
-  const revs = (await defaultDeps.vcs.tryGit(cwd, ['rev-list', '--merges', baseTip])) ?? ''
+async function findLandedMerge(tower, cwd, baseTip, tips) {
+  const revs = (await tower.deps.vcs.tryGit(cwd, ['rev-list', '--merges', baseTip])) ?? ''
   for (const sha of revs.split('\n').filter(Boolean)) {
-    const parents = await commitParents(cwd, sha)
+    const parents = await commitParents(tower, cwd, sha)
     if (parents.length >= 2 && tips.has(parents[1])) return { commit: sha, parents }
   }
   return null
@@ -65,14 +68,14 @@ function describeGitFailure(error) {
 
 /** Remove only lock files that are provably old. A fresh lock may belong to a
  * concurrent Git process; deleting it would let two writers into the index. */
-async function removeStaleGitLocks(commonDir, maxAgeMs = 60000) {
+async function removeStaleGitLocks(tower, commonDir, maxAgeMs = 60000) {
   const removed = []
   for (const name of ['index.lock', 'HEAD.lock', 'MERGE_HEAD.lock', 'ORIG_HEAD.lock']) {
     const file = path.join(commonDir, name)
     try {
-      const stat = await fsp.stat(file)
+      const stat = await tower.deps.store.stat(file)
       if (Date.now() - stat.mtimeMs < maxAgeMs) continue
-      await fsp.unlink(file)
+      await tower.deps.store.unlink(file)
       removed.push(name)
     } catch {
       // absent or in use; never force it
@@ -86,7 +89,6 @@ function fail(message, code = 'invalid-argument') {
 }
 
 import { validateState } from '../domain/state.js'
-import { loadStateFile } from '../lib/stateFile.js'
 import { boardMarkdown } from '../domain/report.js'
 import { diff, missionDetail, status } from './read.js'
 import { evaluateGate } from './gate.js'
@@ -106,28 +108,59 @@ export class Tower {
   /**
    * @param {{ root: string, commonDir: string, branch?: string | null }} repo
    * @param {import('../types/index.js').TowerConfig} [config]
+   * @param {Record<string, any>} [deps] ports assembled by the composition root
+   *   (the host entry); required.
    */
-  constructor(repo, config, deps = defaultDeps) {
+  constructor(repo, config, deps) {
+    assertPorts(deps)
     this.root = repo.root
     this.commonDir = repo.commonDir
     this.branch = repo.branch
-    this.deps = deps
+    this.deps = /** @type {Record<string, any>} */ (deps)
     this.paths = this.deps.store.pathsFor(repo.commonDir)
     // Effective config for this repository: code defaults < profile config <
     // repo config file. Per-call tool arguments are applied by the caller.
-    this.config = /** @type {import('../types/index.js').TowerConfig} */ (config ?? { ...runtimeConfig(), configPath: null, repoConfigPresent: false })
+    this.config = /** @type {import('../types/index.js').TowerConfig} */ (
+      config ?? { ...this.deps.config.runtimeConfig(), configPath: null, repoConfigPresent: false }
+    )
   }
 
-  static async open(repoRoot) {
-    const repo = await defaultDeps.vcs.resolveRepo(repoRoot)
-    const config = await resolveRepoConfig(repo)
-    return new Tower(repo, config)
+  /**
+   * Resolve the repository and config through the injected ports.
+   * @param {string} repoRoot
+   * @param {Record<string, any>} deps
+   */
+  static async open(repoRoot, deps) {
+    assertPorts(deps)
+    const repo = await deps.vcs.resolveRepo(repoRoot)
+    const config = await deps.config.resolveRepoConfig(repo)
+    return new Tower(repo, config, deps)
   }
 
   git(cwd, args, options = {}) {
     return this.deps.vcs.git(cwd, args, { timeoutMs: this.config.git?.timeoutMs, ...options })
   }
 
+  /**
+   * Options for one git-mutex section: the phase, the wait budget derived from
+   * the merge timeout, and the injected clock so waiting is testable in virtual
+   * time. The budget itself is the pure domain policy in ../domain/lockBudget.js
+   * (#93); this method only adds the Tower config and the injected clock.
+   * @param {{ phase?: string, mergeTimeoutMs?: number, timeoutMs?: number, now?: Function }} [options]
+   * @returns {Record<string, any>}
+   */
+  gitMutexOptions(options = {}) {
+    const { phase, mergeTimeoutMs, timeoutMs, ...rest } = options
+    const clock = this.deps.clock
+    const clockNow = clock && typeof clock.now === 'function' ? clock.now.bind(clock) : null
+    return {
+      ...rest,
+      ...(phase ? { phase } : {}),
+      timeoutMs: timeoutMs ?? gitLockTimeoutMs(this.config, mergeTimeoutMs),
+      ...(clockNow ? { now: clockNow } : {}),
+    }
+  }
+
   tryGit(cwd, args, options = {}) {
     return this.deps.vcs.tryGit(cwd, args, { timeoutMs: this.config.git?.timeoutMs, ...options })
   }
@@ -154,7 +187,7 @@ export class Tower {
     if (!(await this.deps.store.exists(this.paths.state))) {
       fail(`tower is not initialized for ${this.root} — run tower_init first`, 'not-initialized')
     }
-    const loaded = await loadStateFile({
+    const loaded = await this.deps.state.loadStateFile({
       store: this.deps.store,
       paths: this.paths,
       now: this.deps.clock?.now ? this.deps.clock.now() : Date.now(),
@@ -169,6 +202,27 @@ export class Tower {
     return init(this, input)
   }
 
+  /**
+   * Persist-then-emit (#75): the caller has already written `state.json` and the
+   * activity log, so each domain transition descriptor is finalised with the
+   * persisted revision and emitted through the event port. The event channel is
+   * best effort — a listener (or an embedder without one) never fails the tool.
+   * @param {Array<{ type: string, missionId: string, commit?: string }>} descriptors
+   * @param {{ revision: number, at: number }} context
+   */
+  emitEvents(descriptors, context) {
+    const events = this.deps.events
+    if (!events || typeof events.emit !== 'function') return
+    for (const descriptor of descriptors ?? []) {
+      try {
+        const event = buildMissionEvent(/** @type {any} */ (descriptor), context)
+        events.emit(event.name, event.payload)
+      } catch {
+        // events describe a fact that is already durable; never fail the tool
+      }
+    }
+  }
+
   async plan(input = {}) {
     return plan(this, input)
   }
@@ -194,7 +248,7 @@ export class Tower {
 
   async assertWorktree(worktree) {
     if (!worktree || typeof worktree.path !== 'string') fail('mission has no worktree')
-    const owned = await assertOwnership({
+    const owned = await this.deps.ownership.assertOwnership({
       storedPath: worktree.path,
       storedRealPath: worktree.realPath,
       branch: worktree.branch,
@@ -361,14 +415,14 @@ export class Tower {
     await this.deps.store.ensureDir(path.dirname(file))
     let text = ''
     try {
-      text = await fsp.readFile(file, 'utf8')
+      text = await this.deps.store.readText(file)
     } catch {
       text = ''
     }
     const lines = text.split(/\r?\n/)
     if (lines.includes(pattern) || lines.includes(`${pattern}/`)) return { inside: true, excluded: true, pattern }
     const suffix = text === '' || text.endsWith('\n') ? '' : '\n'
-    await fsp.appendFile(file, `${suffix}${pattern}\n`, 'utf8')
+    await this.deps.store.appendText(file, `${suffix}${pattern}\n`)
     return { inside: true, excluded: true, pattern }
   }
 
@@ -426,6 +480,7 @@ export class Tower {
       landed = null // no merge commit was created; the intent is safe to drop
     } else {
       landed = await findLandedMerge(
+        this,
         this.root,
         head,
         new Set([intent.branchTip, intent.baseTip].filter(Boolean)),
@@ -489,20 +544,18 @@ export class Tower {
       return null
     }
     const tips = new Set([branchTip, reviewedTip].filter(Boolean))
-    const found = await findLandedMerge(this.root, baseTip, tips)
+    const found = await findLandedMerge(this, this.root, baseTip, tips)
     const mergedCommit = found ? found.commit : branchTip
     const now = Date.now()
     if (state.mergeIntent?.missionId === mission.id) delete state.mergeIntent
-    mission.status = 'merged'
-    mission.mergedAt = now
-    mission.mergedCommit = mergedCommit
-    mission.blockers = []
-    mission.notes.push(
-      found
+    const applied = applyLandedMerge({
+      mission,
+      mergedCommit,
+      note: found
         ? `reconciled already-landed merge ${mergedCommit.slice(0, 7)} with parents [${found.parents.map((parent) => parent.slice(0, 7)).join(', ')}]`
         : `reconciled already-landed merge: ${mergedCommit.slice(0, 7)} is contained in ${state.base} (no merge commit found)`,
-    )
-    mission.updatedAt = now
+      now,
+    })
     state.revision += 1
     state.updatedAt = now
     validateState(state, this.paths.state)
@@ -513,6 +566,7 @@ export class Tower {
       missionId: mission.id,
       text: `reconciled already-landed ${mergedCommit.slice(0, 7)} on ${state.base}`,
     })
+    this.emitEvents(applied.events, { revision: state.revision, at: now })
     return {
       ok: true,
       reconciled: true,

package/cordis.patch.yml

@@ -1,13 +1,25 @@
-# dsh-tower is an all-or-nothing bundle. The single group row is the only
-# user-visible component: disabling it disables every internal section (host,
-# skills, worker/reviewer presets) together, so no orphan preset or skill can
-# point at missing tower_* tools. See docs/architecture/overview.md.
+# dsh-tower component rows (#121).
+#
+# The first top-level row is the mandatory host group: the Host plugin and its
+# worker-preset dependency. Turning it off equals uninstalling Tower (no tools,
+# no presets, no skills), which is the accepted all-off boundary; every other
+# top-level row is an individually switchable optional capability whose off
+# state leaves the rest of Tower working.
+#
+# Policy: principle 11 in PRINCIPLES.md + docs/adr/0005-component-surface.md.
+# The per-key answer is docs/reference/component-surface.md, generated from
+# scripts/component-surface.json. `npm run docs:check:components` refuses a new
+# switch, a missing locale label, or a moved component count without a written
+# decision. `tower_doctor` and `tower_recover` are part of the host and are never
+# switches (#122); a capability row owns exactly one optional capability, and
+# `tower_status` / `tower_doctor` name any row that is off.
 - insert:
-    - id: tower-bundle
+    # Mandatory host anchor. Not an optional capability: off == uninstall.
+    - id: tower
       name: cordis:group
       group: true
       config:
-        - id: tower
+        - id: tower-host
           name: 'dsh-tower'
           config:
             mode:
@@ -21,8 +33,6 @@
               interruptDefault: true
             spawn:
               staleMs: 15000
-        - id: tower-skills
-          name: 'dsh-tower/skills'
         - id: preset-tower-worker
           name: '@deepseek-ai/dsh-agent-preset'
           config:
@@ -41,23 +51,41 @@
                   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
+    # Optional capabilities: each row is the switch for exactly one capability.
+    - id: tower-skills
+      name: 'dsh-tower/skills'
+    - id: tower-batch
+      name: 'dsh-tower/batch'
+    - id: tower-import
+      name: 'dsh-tower/import'
+    - id: tower-leases
+      name: 'dsh-tower/leases'
+    - id: tower-tests
+      name: 'dsh-tower/tests'
+    # dev hot reload: shipped off. Enable the row for a linked dev profile.
+    - id: tower-hmr
+      name: 'dsh-tower/hmr'
+      disabled: true
+    # Conditional optional component: off is supported only while
+    # review.requireReview is false; with the gate on planning/mode entry refuse
+    # the combination with an explanatory error.
+    - 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

@@ -8,8 +8,8 @@ Choose a path:
 |---|---|
 | New user | [When to use Tower](guide/scenarios-and-philosophy.md) → [Quick start](guide/quickstart.md) → [Tools](reference/tools.md) → [Example](examples/first-mission.md) |
 | Choosing a workflow | [When to use Tower, and how it differs from Agent Teams, Ralph, Workflow and parallel subagents](guide/scenarios-and-philosophy.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) → [Release checklist](guide/release.md) → [Tracker board](board.md) → [Contributing](../CONTRIBUTING.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) → [Incidents and regressions](operations/incident.md) |
+| Maintainer | [Engineering principles](../PRINCIPLES.md) → [ADRs](adr/README.md) → [Architecture](architecture/overview.md) → [Surface budget](reference/surface-budget.md) → [Component surface](reference/component-surface.md) → [Config](reference/config.md) → [Hot reload](guide/hot-reload.md) → [Release checklist](guide/release.md) → [Tracker board](board.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
@@ -36,13 +36,18 @@ Other useful pages: [When to use Tower](guide/scenarios-and-philosophy.md), [Ins
 - [Testing and evidence](reference/testing.md)
 - [Batches, leases and legacy import](reference/operations.md)
 - [Doctor](reference/doctor.md)
+- [Surface budget and classification](reference/surface-budget.md)
+- [Component surface: who may be switched off](reference/component-surface.md)
 
 **Operations and background**
 
 - [Operations runbook](operations/runbook.md)
+- [Incidents and regressions](operations/incident.md)
 - [Security model](operations/security.md)
 - [Release checklist](guide/release.md)
 - [Tracker board](board.md)
+- [Engineering principles](../PRINCIPLES.md)
+- [Architecture decision records](adr/README.md)
 - [Architecture and state machine](architecture/overview.md)
 - [First mission example](examples/first-mission.md)
 - [FAQ](faq.md)

package/docs/adr/0001-ports-adapters-as-data.md

@@ -0,0 +1,49 @@
+# 0001 — Ports and adapters are data, not a DI container
+
+- Date: 2026-10-23
+- Status: Accepted
+- Deciders: maintainer
+- Supersedes: none
+
+## Context
+
+Tower needs a real seam between the pure app/domain logic and the effectful
+world (filesystem, Git, clocks, ids). The seam has to survive a test that replaces
+every adapter with an in-memory double, and it has to be obvious to a reader why
+a tool can run without touching a repository. A conventional dependency-injection
+container would add a framework, decorators, and reflection to a plugin that must
+load inside an arbitrary DSH host version.
+
+## Decision
+
+`ports/` declares a frozen `{ name, methods }` runtime contract per capability and
+an `assert*Port` helper; `ports/index.js` exports the `PORTS` table and
+`assertPorts(deps)`. The composition root builds one plain object of adapter
+implementations (`createDefaultDeps`) and passes it explicitly. `app/**` imports
+only app siblings, `domain/**`, `ports/**` and `node:path`. There is no service
+locator and no runtime reflection; a missing method fails at the seam with a
+readable error.
+
+## Consequences
+
+- Every effectful call is visible as `deps.<port>.<method>`, so the contract test
+  can walk the source and assert each method is declared.
+- Tests substitute the same plain object; the in-memory lifecycle is a real test
+  rather than a mock framework feature.
+- Adding a capability means adding a port and an implementation, not registering
+  a class with a container.
+- A downstream embedder that wants a different implementation passes a new
+  object to `registerTowerTools`; it cannot monkey-patch module state.
+
+## Rejected alternatives
+
+- **A dependency-injection container** (`reflect-metadata`, decorators, a
+  string-keyed registry) — adds a load-time framework dependency, hides the
+  dependency graph behind reflection, and fails indistinguishably when a host
+  bundle is mounted twice.
+- **Direct adapter imports from `app/**`** — simpler at first, but it makes the
+  pure app test need a filesystem and a Git binary, and the architecture rule
+  `app-ports-only` would have nothing to enforce.
+- **Module-level singletons** — one adapter instance would be shared across
+  repositories and test cases, which is the ambient-state problem the host-scope
+  rule exists to prevent.

package/docs/adr/0002-single-state-json.md

@@ -0,0 +1,50 @@
+# 0002 — One state.json is the mission persistence contract
+
+- Date: 2026-10-23
+- Status: Accepted
+- Deciders: maintainer
+- Supersedes: none
+
+## Context
+
+Mission state carries active missions, roster entries, reviews, findings, messages
+and batches. The obvious alternative is one file per mission (or one directory
+per mission), which would make every mission a small git-diffable record. Tower is
+not a git-backed issue tracker: it mutates state from several tools on every
+operation, under one process, and a crash between two file writes must not leave
+missions half-valid.
+
+## Decision
+
+One `<git-common-dir>/dsh-tower/state.json` holds the active document. It is
+read/written through one token-checked lock and one atomic temp+rename write with
+a heartbeat-based stale window. Terminal missions whose worktree is gone are moved
+out to `archive/<year>.json` files under the archive policy; that keeps `state.json`
+bounded without changing the live contract. `modes.json` is a separate per-agent
+mode store and follows the same atomic-write primitives.
+
+## Consequences
+
+- A mutation is one lock acquisition and one atomic write, so a reader never sees a
+  half-applied mission graph.
+- Cross-mission invariants (unique mission ids, dependencies, roster ownership,
+  review binding) are checked in one place before the write.
+- `state.json` is not line-diffable per mission. The board (`MISSIONS.md`), the
+  read tools and the archive year files are the human- and diff-facing views.
+- Archiving is a move, never a delete: an unreadable archive pauses archiving
+  rather than losing the entries.
+- Two writers are prevented by the lock, not by "please run one tower".
+
+## Rejected alternatives
+
+- **One JSON file per mission** — makes each mission diffable, but every command
+  that touches several missions (plan, roster, batch, gate) must coordinate N
+  files with no cross-file atomicity; a crash leaves a partial graph.
+- **A database (SQLite or a bundled store)** — adds a native dependency to a plugin
+  that must mount inside arbitrary host builds, and moves the schema migration
+  problem out of a file that a user can inspect and back up.
+- **Append-only event log as the source of truth** — good for audit, bad for the
+  read path this plugin actually has: every status call would replay history, and
+  compaction would become a second correctness problem.
+- **Git-committed mission records** — would make Tower write to the user's history
+  on every tool call, which the "never modify the main checkout" boundary refuses.

package/docs/adr/0003-allow-agent-control-default-true.md

@@ -0,0 +1,48 @@
+# 0003 — allowAgentControl defaults to true
+
+- Date: 2026-10-23
+- Status: Accepted
+- Deciders: maintainer
+- Supersedes: none
+
+## Context
+
+Tower's product claim is a human-owned orchestration mode: the user decides when
+to enter it, and the merge gate is the final authority. The config key
+`mode.allowAgentControl` decides whether the model may call `tower_control` to
+enter or leave the mode. Making it `false` by default would sound safer, but it
+would also mean the feature does not work until the user discovers and flips a
+key, and the model would have no way to leave a mode the user asked it to enter.
+
+## Decision
+
+`mode.allowAgentControl` defaults to `true`, and the legacy top-level
+`allowAgentControl` alias keeps the shipped patch behavior. The default is paired
+with independent checks rather than with trust: entering records a reason, a
+user-paused goal is never auto-resumed without an authorization reference, the
+first entry can require a human `/tower ack`, one Tower session per repository can
+hold the workspace lock, and `tower_merge` still runs the preflight gate.
+
+## Consequences
+
+- The default profile works: a user can say "use Tower" and the model can comply.
+- Human ownership is enforced by refusal paths (ack, authorization, workspace
+  lock, preflight) instead of by a disabled-by-default switch that users would
+  turn on anyway.
+- A deployment that wants human-only mode control pins
+  `mode.allowAgentControl:false`; doctor warns when a profile still relies on a
+  reversed default instead of pinning it.
+- The default is a product decision with a written rationale, so it can be
+  revisited on evidence rather than by citing "secure by default".
+
+## Rejected alternatives
+
+- **Default `false`** — the plugin would appear broken on first use, and the
+  existing reversal would be dropped only to look conservative.
+- **No config key at all** — the model could always toggle the mode, with no way
+  for a human-only deployment to refuse it.
+- **Require an approval prompt for every entry** — the prompt is an environment
+  behavior, not a plugin guarantee; the ack and authorization fields are the
+  guarantees this plugin can actually enforce.
+- **Let the model resume a paused goal on exit** — exit is not consent; resuming
+  stays a human decision.

package/docs/adr/0004-surface-budget.md

@@ -0,0 +1,70 @@
+# 0004 — The concept surface is frozen by a committed baseline
+
+- Date: 2026-10-23
+- Status: Accepted
+- Deciders: maintainer
+- Supersedes: none
+
+## Context
+
+Four days after the first publish the plugin carried 60+ config keys and 28 tools.
+The fitness suite measures file shape (line ceilings, pure-domain share) but not
+how many concepts a user has to hold. Line counts can stay green while the real
+surface grows, and every config key is four promises: a reference row, a validator
+branch, a default that must keep working, and an answer to "why did this change my
+behaviour". The same is true of every tool.
+
+## Decision
+
+Count three surfaces — config leaf keys, config sections and registered tools — in
+one pure module (`domain/surface.js`). Commit the counts in
+`scripts/surface-baseline.json` with a date. `npm run surface:check` fails when a
+live count differs from the baseline; a decision that raises a count must name an
+existing ADR under `docs/adr/` or deletions that are provably absent from the live
+surface. `tower_doctor` prints the counts, the generated config/tools references
+print the same counts plus the baseline date, and every key/tool is classified
+`core`, `tuning` or `niche` in `docs/reference/surface-budget.md`, with a removal
+note for each niche key.
+
+## Consequences
+
+- Growth is visible in a diff instead of arriving one reasonable-looking key at a
+  time.
+- A reduction is cheap: the baseline can be ratcheted down with no ADR.
+- The classification table is auditable, not decorative: the check fails when a
+  live key or tool is missing from it.
+- The numbers are three lines in `tower_doctor` output, not a new dashboard.
+- This does not remove any key in this release; it is a brake, not a clean-up.
+
+## Measurement correction (2026-10-23)
+
+The first baseline counted 27 tools because it recorded only the `define()`
+registration path. `tower_mode` and `tower_control` are registered directly by
+`index.js`, so the shipped surface was always 29 (#118). The baseline now carries
+an explicit correction decision (27 → 29) with a reason, a date and a reference
+to this ADR, and the recorder in `host/tool-registry.js` covers both registration
+paths. This is a measurement correction, not surface growth: a later count change
+still needs its own ADR or a provably matching deletion.
+
+## Amended by ADR 0005 (2026-10-23)
+
+The decision above counts three surfaces. [ADR 0005](0005-component-surface.md)
+extends the budget with a fourth — the number of user-visible component rows in
+`cordis.patch.yml` — and records it as its own `components` baseline entry with a
+two-way decision rule (a contraction needs a decision just like growth). The
+three original counts are still measured by `npm run surface:check`; the
+component count is validated by `npm run docs:check:components`. The historical
+decision above is unchanged: "three surfaces" describes the 2.3.0 rule.
+
+## Rejected alternatives
+
+- **A line-count or file-size rule** — the project already has those and the
+  surface grew while they stayed green; they measure the wrong thing.
+- **A hard cap with no escape hatch** — a real capability would be blocked, and the
+  first exception would be added as an unexplained waiver.
+- **A per-key count in each generated reference** — two references can disagree;
+  one shared baseline plus one check keeps the counts equal.
+- **Only an ADR requirement** — a pure deletion would need paperwork even though it
+  shrinks the surface; the matching-deletion path keeps reductions cheap.
+- **A GitHub issue label instead of a repo file** — the brake must run offline in
+  `npm test` and in CI without a token.