dsh-tower 2.1.0-beta.1 → 2.3.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,23 +16,25 @@ 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'
 import { missionContext } from './missionContext.js'
 import { enrichedMissions } from './enrichedMissions.js'
 import { writeBoard, boardFile } from './board.js'
+import { archiveIndex, archivedMission } from './archive.js'
 import { recordSpawnOutcome, recordInterrupt, reserveRoster, recordSpawn, rosterView } from './spawn.js'
 import { recordTestRun, recordLegacySnapshot, recordLegacyMap } from './recording.js'
 
 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)
@@ -38,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) : []
 }
 
@@ -48,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
@@ -64,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
@@ -104,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 })
   }
@@ -142,12 +177,24 @@ export class Tower {
     return (await this.tryGit(cwd, ['merge-base', '--is-ancestor', ancestor, descendant].filter(Boolean))) !== null
   }
 
-  async load() {
+  /**
+   * Read the state document, migrating an older schema in memory and (while the
+   * caller holds the state lock) persisting that migration with one revision
+   * bump and a `state.migrated` activity entry (#72).
+   * @param {{ persist?: boolean }} [options]
+   */
+  async load(options = {}) {
     if (!(await this.deps.store.exists(this.paths.state))) {
       fail(`tower is not initialized for ${this.root} — run tower_init first`, 'not-initialized')
     }
-    const state = await this.deps.store.readJson(this.paths.state)
-    return validateState(state, this.paths.state)
+    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(),
+      persist: options.persist,
+    })
+    this.stateLoad = { ...loaded.version, migration: loaded.migration }
+    return loaded.state
   }
 
   /** #51 two-phase init: see the prepare/act/commit helpers in `./tower/init.js`. */
@@ -155,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)
   }
@@ -180,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,
@@ -316,9 +384,23 @@ export class Tower {
     return missionDetail(this, missionId)
   }
 
-  /** Human-readable mission board (markdown) for the current state. */
-  boardMarkdown(state) {
-    return boardMarkdown(state)
+  /**
+   * Human-readable mission board (markdown) for the current state.
+   * @param {import('../types/index.js').TowerState} state
+   * @param {{ count?: number, unreadable?: boolean, message?: string } | null} [archive]
+   */
+  boardMarkdown(state, archive = null) {
+    return boardMarkdown(state, archive)
+  }
+
+  /** Read `archive/index.json`; `ok:false` carries a diagnostic instead of throwing. */
+  archiveIndex() {
+    return archiveIndex(this)
+  }
+
+  /** Load one archived mission (full record) with its linked reviews and findings. */
+  archivedMission(missionId) {
+    return archivedMission(this, missionId)
   }
 
   async ensureExcluded(target) {
@@ -333,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 }
   }
 
@@ -398,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)),
@@ -461,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)
@@ -485,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/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) → [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,17 @@ 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)
 
 **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,50 @@
+# 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.
+
+## 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.

package/docs/adr/README.md

@@ -0,0 +1,51 @@
+# Architecture decision records
+
+An ADR is a dated record of a decision that is already load-bearing. It is not a
+proposal: the status says whether the decision is accepted, and the rejected
+alternatives exist so a future reader can see what was actually weighed.
+
+The engineering principles that these records serve are in
+[../PRINCIPLES.md](../PRINCIPLES.md). `npm run docs:check:philosophy` requires at
+least three numbered ADRs, each with Context, Decision, Consequences, Rejected
+alternatives, Date and Status.
+
+| ADR | Decision | Date |
+|---|---|---|
+| [0001](0001-ports-adapters-as-data.md) | Ports and adapters are data, not a dependency-injection container | 2026-10-23 |
+| [0002](0002-single-state-json.md) | One `state.json` is the mission persistence contract | 2026-10-23 |
+| [0003](0003-allow-agent-control-default-true.md) | `allowAgentControl` defaults to `true` | 2026-10-23 |
+| [0004](0004-surface-budget.md) | The concept surface is frozen by a committed baseline | 2026-10-23 |
+
+## Template
+
+```markdown
+# NNNN — Decision title
+
+- Date: YYYY-MM-DD
+- Status: Proposed | Accepted | Superseded by NNNN
+- Deciders: <who>
+
+## Context
+
+What forced the decision.
+
+## Decision
+
+What was decided, in one paragraph.
+
+## Consequences
+
+What becomes easier, what becomes harder, and what is now refused.
+
+## Rejected alternatives
+
+- **Alternative** — why it was not chosen.
+```
+
+## Non-goals
+
+These records do not form an RFC queue, an architecture review board, or a
+process for approving ordinary changes.
+
+Unowned. This is a documentation convention, not a gate; nothing in CI blocks a
+new ADR or rewards one.

package/docs/agents/domain.md

@@ -0,0 +1,38 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`GLOSSARY.md`** at the repo root, or
+- **`GLOSSARY-MAP.md`** at the repo root if it exists: it points at one `GLOSSARY.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`**: read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+This repo is **single-context**: one `GLOSSARY.md` and one `docs/adr/` at the repo root.
+
+```
+/
+├── GLOSSARY.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+(If the repo ever grows per-package contexts, switch to the multi-context layout: a root `GLOSSARY-MAP.md` pointing at per-context `GLOSSARY.md` files, with system-wide decisions in `docs/adr/` and context decisions in `src/<context>/docs/adr/`.)
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `GLOSSARY.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal: either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders), but worth reopening because…_