dsh-tower 2.1.0 → 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,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/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/workflow.md

@@ -0,0 +1,51 @@
+# Execution workflow: Matt Pocock skills × Tower
+
+This repository uses two workflows together. They are not alternatives: the **Matt Pocock skills** own thinking, planning, review discipline and retros; **Tower** owns delivery — isolated worktrees, scope fences, review gates, merges and durable mission state. **GitHub Issues** is the single source of truth for what is planned, in progress, blocked and shipped.
+
+## Who owns what
+
+| Stage | Owner | Artifact |
+|---|---|---|
+| Intake | Matt Pocock `/triage` for raw external reports; milestones + `P*`/`area/*` labels for self-authored findings | issue with owner-facing state |
+| Plan | `/to-spec` → `/to-tickets` (or an existing issue whose acceptance criteria are already ticket-shaped) | spec issue, tickets with native `blocked_by` edges |
+| Execute | `/implement-spec` subagents for one-session waves; **Tower missions** for parallel or long-lived work | integration branch + PRs, or mission worktrees + merge gate |
+| Build each unit | `/tdd` inside the ticket/mission | failing test first, then green |
+| Verify | gates + required CI checks + `/code-review` (Standards + Spec) | green PR with two-axis review |
+| Land | protected `main`, four-line PR body, `verified-by:`/`commit:` closure | merged PR, closed issues |
+| Release | `release:check`, CHANGELOG, COMPATIBILITY, tag; publish only when planned | tag-only or published release |
+| Learn | `/retro`; mechanical findings become checks, judgement becomes standards | CONTRIBUTING/AGENTS/scanner updates |
+
+## The flow
+
+1. **Intake.** Raw external bug reports and feature requests go through `/triage` (they are not ours). Findings we file ourselves (audits, retros) skip triage and get a priority, an area and a milestone; they are already acceptance-criteria-shaped.
+2. **Plan.** Multi-session work goes `/to-spec` → `/to-tickets`. Tickets are tracer bullets with native blocking edges; the frontier is whatever has no open blockers. Small work may skip the spec when the issue already states acceptance criteria (e.g. a patch ticket).
+3. **Choose the orchestrator.**
+   - **One-session wave (≤3 tickets, mostly independent):** `/implement-spec`-style: an integration branch, one implementer subagent per ticket in its own worktree, merger merges to the integration branch, one PR to `main`.
+   - **Parallel or long-lived wave (architecture epics, >3 tickets, review needed):** **Tower**. `tower_init` → `tower_plan` with one mission per ticket, `scope` = the ticket's write fence, `deps` = the ticket's blocking edges → `tower_spawn` a worker per mission → optional reviewer (`tower-reviewer`) → `tower_merge` (gate checks scope, branch freshness, review, tasks) → `tower_teardown`. Tower's persistent state makes the wave resumable after a restart.
+   - Never run both orchestrators over the same files at once.
+4. **Build.** Each unit starts with `/tdd`: one failing test, then the implementation, then the next slice. Commit messages carry `Refs #n`; the completing commit uses `Fixes #n`. Workers do not merge; they hand off a branch.
+5. **Verify before landing.** Run `npm test`, `npm run docs:check`, all four `docs:check:generated*`, `npm run pack:check`, `npm run architecture:check`, `npm run types:check`, `npm run domain:check`. Bundle changes also run `npm run smoke:mount`. CI must be green on the required checks (`test (22)`, `test (24)`, `test (22, windows)`, `mount`). Then `/code-review` runs both axes on the diff (Standards against CONTRIBUTING/architecture docs, Spec against the ticket); every finding is fixed in the same PR or explicitly deferred with a reason.
+6. **Land.** PR body follows the four-line contract (failure mode → change → test that fails without it → blast radius). `main` is protected: PR + required checks, admins included, no force-push. A closure comment carries `verified-by: <test file>` and `commit: <sha>`; `npm run audit:issues` flags closures whose evidence is missing.
+7. **Release.** `release:check` compares the version, the previous tag and the CHANGELOG; a tag push fails when the version did not move or the tag does not match. Releases are either **tag-only** (version + changelog + compatibility row + annotated tag; no npm publish, no GitHub Release) or **published** (adds the human `npm publish --tag latest` with 2FA, `dist-tags` verification, then the GitHub Release). The mode is recorded in the milestone/plan.
+8. **Learn.** After a release (or a wave that went sideways) run `/retro`: mechanical mistakes become deterministic checks (scripts, CI jobs, preflight), judgement calls become written standards. Periodically run `/improve-codebase-architecture` for deepening opportunities and `/domain-modeling` to keep the vocabulary and ADRs (2.3.0) honest.
+
+## Decision table
+
+| Situation | Flow |
+|---|---|
+| Raw external issue | `/triage` → then plan |
+| Design question you cannot settle on paper | `/grill-with-docs`, detour through `/prototype` if it needs a runnable answer |
+| Multi-session feature | `/to-spec` → `/to-tickets` → `/implement-spec` |
+| Small fix with acceptance criteria | ticket → `/implement` (+ `/tdd`) |
+| Architecture epic / parallel missions | Tower plan → missions → review gate → merge |
+| Something broken, cause unknown | `/diagnosing-bugs` (tight red loop first) |
+| Repeated mistakes | `/retro` → checks/standards |
+| Release | release plan: tag-only or publish |
+
+## Invariants
+
+- One ticket per PR series; a branch never touches two tickets.
+- Tracked blocking edges, not prose: work only the frontier.
+- Tower missions: `scope` is the write fence, a mission that outgrows it is re-scoped, not silently widened; the workspace lock keeps one Tower session per repository.
+- Human-only gates: npm publish/2FA, branch-protection changes, anything behind a third-party credential. Stop and hand over rather than inventing a credential path.
+- Context hygiene: keep planning in one window until tickets exist; start each implementation unit from the ticket, not from the previous unit's context.