dsh-tower 2.1.0-beta.1 → 2.1.0

package/app/mission.js

@@ -4,6 +4,7 @@ import { applyMissionUpdate } from '../domain/missions/lifecycle.js'
 import { validateState } from '../domain/state.js'
 import { fullMission } from '../domain/summary.js'
 import { withLock, writeJsonAtomic, appendJsonl } from '../lib/store.js'
+import { sweepArchive } from './archive.js'
 
 function fail(message, code = 'invalid-argument') {
   throw new TowerToolError(code, message)
@@ -19,6 +20,7 @@ export async function updateMission(tower, input = {}) {
     const { changes } = applyMissionUpdate({ mission, state, input, config: tower.config })
     const now = Date.now()
     mission.updatedAt = now
+    await sweepArchive(tower, state, { now })
     state.revision += 1
     state.updatedAt = now
 

package/app/plan.js

@@ -9,21 +9,27 @@ import {
 import { validateState } from '../domain/state.js'
 import { fullMission } from '../domain/summary.js'
 import { withLock, writeJsonAtomic, appendJsonl } from '../lib/store.js'
+import { sweepArchive } from './archive.js'
 
 export async function plan(tower, input = {}) {
   const prepared = normalizePlanMissions(input)
   return withLock(tower.paths, async () => {
     const state = await tower.load()
     const now = Date.now()
-    const assigned = assignMissionIds(prepared, nextMissionNumber(state.missions))
+    // Archived ids stay in the known set: a new mission must not reuse an id
+    // and a merged dependency may live in the archive index (#73).
+    const archive = await tower.archiveIndex()
+    const known = [...state.missions, ...(archive.ok ? archive.missions : [])]
+    const assigned = assignMissionIds(prepared, nextMissionNumber(known))
 
-    assertKnownDependencies(assigned, state.missions)
+    assertKnownDependencies(assigned, known)
 
-    addAutoDeps(assigned, state.missions)
-    assertAcyclic([...state.missions, ...assigned])
+    addAutoDeps(assigned, known, { caseInsensitive: state.caseInsensitive === true })
+    assertAcyclic([...known, ...assigned])
 
     const created = assigned.map((mission) => newMission(mission.id, mission, now))
     state.missions.push(...created)
+    const swept = await sweepArchive(tower, state, { now })
     state.revision += 1
     state.updatedAt = now
 
@@ -37,6 +43,8 @@ export async function plan(tower, input = {}) {
     return {
       revision: state.revision,
       missions: created.map((mission) => fullMission(mission)),
+      ...(swept.archived.length > 0 ? { archived: swept.archived } : {}),
+      ...(swept.error ? { archiveError: swept.error } : {}),
     }
   })
 }

package/app/read.js

@@ -2,29 +2,85 @@
 import { TowerToolError } from '../domain/errors.js'
 import { diffView, missionDetailView, statusView } from '../domain/read/views.js'
 import { readActivityTail } from '../lib/store.js'
+import { archiveView, archivedSummary } from './archive.js'
 
 function fail(message, code = 'invalid-argument') {
   throw new TowerToolError(code, message)
 }
 
+/**
+ * Full detail for one mission. A mission that was archived is reconstructed
+ * from its year file, including the reviews, findings and activity that left
+ * state.json with it. An unreadable archive is a diagnostic, never a throw:
+ * `tower_status` must keep rendering the hot state.
+ */
 export async function missionDetail(tower, missionId) {
   const state = await tower.load()
   const mission = state.missions.find((entry) => entry.id === missionId)
-  if (!mission) fail(`unknown mission "${missionId}"`, 'mission-not-found')
   const activity = await readActivityTail(tower.paths.activity, 200)
-  return missionDetailView({ state, mission, activity })
+  if (mission) return missionDetailView({ state, mission, activity })
+
+  const archived = await tower.archivedMission(missionId)
+  if (archived.ok && archived.entry) {
+    const entry = archived.entry
+    const hotFindings = (state.findings ?? []).filter((finding) => finding.missionId === missionId)
+    const byId = new Map()
+    for (const finding of [...(entry.findings ?? []), ...hotFindings]) {
+      if (finding && typeof finding.id === 'string') byId.set(finding.id, finding)
+    }
+    return {
+      ...missionDetailView({
+        state: /** @type {any} */ ({ reviews: entry.reviews ?? [], findings: [...byId.values()] }),
+        mission: /** @type {any} */ (entry.mission),
+        activity,
+      }),
+      archived: true,
+      archivedAt: entry.archivedAt,
+      archivedYear: entry.archivedYear,
+      branch: entry.branch ?? null,
+    }
+  }
+  if (archived.unreadable) {
+    return {
+      archived: true,
+      archivedAt: null,
+      branch: null,
+      mission: null,
+      reviews: [],
+      findings: [],
+      activity: [],
+      error: archived.error ?? `tower archive is unreadable; mission ${missionId} cannot be loaded`,
+    }
+  }
+  return fail(`unknown mission "${missionId}"`, 'mission-not-found')
 }
 
 export async function status(tower, input = {}) {
   const state = await tower.load()
   const activity = await readActivityTail(tower.paths.activity, 12)
+  const index = await tower.archiveIndex()
+  const activeIds = new Set(state.missions.map((mission) => mission.id))
+  const wanted = Array.isArray(input.missionIds) ? new Set(input.missionIds) : null
+  // An explicit missionId lookup includes its archived summary; the dashboard
+  // includes them only on demand. Archived summaries never carry report bodies.
+  const includeArchived = input.includeArchived === true || wanted !== null
+  const missions = await tower.enrichedMissions(state, input.missionIds)
+  if (includeArchived && index.ok) {
+    for (const entry of index.missions) {
+      if (activeIds.has(entry.id)) continue
+      if (wanted !== null && !wanted.has(entry.id)) continue
+      missions.push(archivedSummary(entry))
+    }
+  }
   return statusView({
     state,
     statePath: tower.paths.state,
     activity,
     unreadTower: tower.unreadFor(state, 'tower').length,
     config: tower.config,
-    missions: await tower.enrichedMissions(state, input.missionIds),
+    missions,
+    archivedMissions: index.ok ? index.missions.length : null,
+    archive: archiveView(index),
   })
 }
 

package/app/review.js

@@ -1,5 +1,6 @@
 // Independent review submission use case.
 import { withLock, writeJsonAtomic, appendJsonl } from '../lib/store.js'
+import { sweepArchive } from './archive.js'
 import { validateState } from '../domain/state.js'
 import { TowerToolError } from '../domain/errors.js'
 import {
@@ -117,6 +118,7 @@ export async function submitReview(tower, input) {
     if (outcome.returnToActive) mission.status = 'active'
     mission.notes.push(outcome.note)
     mission.updatedAt = now
+    await sweepArchive(tower, state, { now })
     state.revision += 1
     state.updatedAt = now
 

package/app/teardown.js

@@ -21,6 +21,7 @@ import {
   teardownRemoveDecision,
   teardownRemovedDecision,
 } from '../domain/integration/teardown.js'
+import { sweepArchive } from './archive.js'
 
 /**
  * Phase 1 (#51): decide every keep/remove outcome without holding the state
@@ -180,5 +181,25 @@ export async function teardown(tower, input) {
     setDecision(candidate.decision, teardownRemovedDecision(outcome))
   }
 
-  return { ok: true, dryRun: false, removed, decisions: prepared.decisions }
+  // Archival runs under one final short lock. It is policy-driven (age or the
+  // hot-terminal cap), so a mission torn down a moment ago stays hot until it
+  // is old enough; `archive.afterDays: 0` archives it on this call.
+  const archive = await withLock(tower.paths, async () => {
+    const state = await tower.load()
+    const swept = await sweepArchive(tower, state, { now: Date.now(), activity: input.activity ?? {} })
+    if (swept.written) {
+      validateState(state, tower.paths.state)
+      await writeJsonAtomic(tower.paths.state, state)
+    }
+    return swept
+  })
+
+  return {
+    ok: true,
+    dryRun: false,
+    removed,
+    decisions: prepared.decisions,
+    archived: archive.archived,
+    ...(archive.error ? { archiveError: archive.error } : {}),
+  }
 }

package/app/tower.js

@@ -20,6 +20,7 @@ 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'
 
@@ -85,6 +86,7 @@ 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'
@@ -142,12 +144,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 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`. */
@@ -316,9 +330,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) {

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…_

package/docs/agents/issue-tracker.md

@@ -0,0 +1,46 @@
+# Issue tracker: GitHub
+
+Issues and specs for this repo live as GitHub issues. Use the `gh` CLI for all operations.
+
+## Conventions
+
+- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies.
+- **Read an issue**: `gh issue view <number> --comments`, filtering comments by `jq` and also fetching labels.
+- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters.
+- **Make an issue a sub-issue of a parent**: `gh issue create --parent <parent> ...`, or `gh issue edit <parent> --add-sub-issue <child>` afterwards (`gh` 2.94+). Older `gh`: `gh api --method POST repos/<owner>/<repo>/issues/<parent>/sub_issues -F sub_issue_id=<child-db-id>` (database id, as in **Blocking** below). Without sub-issues, put `Part of #<parent>` at the top of the child body.
+- **Comment on an issue**: `gh issue comment <number> --body "..."`
+- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
+- **Close**: `gh issue close <number> --comment "..."`
+
+Infer the repo from `git remote -v`; `gh` does this automatically when run inside a clone. For this repo the remote is `louifinn/dsh-tower`.
+
+## Pull requests as a triage surface
+
+**PRs as a request surface: no.** _(Set to `yes` if this repo treats external PRs as feature requests; `/triage` reads this flag.)_
+
+When set to `yes`, PRs run through the same labels and states as issues, using the `gh pr` equivalents:
+
+- **Read a PR**: `gh pr view <number> --comments` and `gh pr diff <number>` for the diff.
+- **List external PRs for triage**: `gh api --paginate 'repos/{owner}/{repo}/pulls?state=open' --jq '.[] | select(.author_association | IN("OWNER","MEMBER","COLLABORATOR") | not) | {number, title, author: .user.login, author_association, labels: [.labels[].name]}'`.
+- **Comment / label / close**: `gh pr comment`, `gh pr edit --add-label`/`--remove-label`, `gh pr close`.
+
+GitHub shares one number space across issues and PRs, so a bare `#42` may be either: resolve with `gh pr view 42` and fall back to `gh issue view 42`.
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitHub issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `gh issue view <number> --comments`.
+
+## Wayfinding operations
+
+Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets.
+
+- **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `gh issue create --label wayfinder:map`.
+- **Child ticket**: an issue linked to the map as a GitHub sub-issue (see **Make an issue a sub-issue of a parent**). Where sub-issues aren't enabled, add the child to a task list in the map body and put `Part of #<map>` at the top of the child body. Labels: `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
+- **Blocking**: GitHub's **native issue dependencies**, the canonical, UI-visible representation. Add an edge with `gh api --method POST repos/<owner>/<repo>/issues/<child>/dependencies/blocked_by -F issue_id=<blocker-db-id>`, where `<blocker-db-id>` is the blocker's numeric **database id** (`gh api repos/<owner>/<repo>/issues/<n> --jq .id`, _not_ the `#number` or `node_id`). GitHub reports `issue_dependencies_summary.blocked_by` (open blockers only, the live gate). Where dependencies aren't available, fall back to a `Blocked by: #<n>, #<n>` line at the top of the child body. A ticket is unblocked when every blocker is closed.
+- **Frontier query**: list the map's open children (`gh issue list --state open`, scoped to the map's sub-issues / task list), drop any with an open blocker (`issue_dependencies_summary.blocked_by > 0`, or an open issue in the `Blocked by` line) or an assignee; first in map order wins.
+- **Claim**: `gh issue edit <n> --add-assignee @me`, the session's first write.
+- **Resolve**: `gh issue comment <n> --body "<answer>"`, then `gh issue close <n>`, then append a context pointer (gist + link) to the map's Decisions-so-far.

package/docs/agents/triage-labels.md

@@ -0,0 +1,15 @@
+# Triage Labels
+
+The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
+
+| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
+| -------------------------- | -------------------- | ---------------------------------------- |
+| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
+| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
+| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
+| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
+| `wontfix`                  | `wontfix`            | Will not be actioned                     |
+
+When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
+
+Edit the right-hand column to match whatever vocabulary you actually use. The right column currently equals the role name, so these are the defaults — `wontfix` already exists on the GitHub repo, while `needs-triage`, `needs-info`, `ready-for-agent`, and `ready-for-human` will be created by `/triage` on first use (or add them upfront with `gh label create`).

package/docs/architecture/overview.md

@@ -101,7 +101,9 @@ After the command, regardless of exit status, it inspects `HEAD`:
 
 | Path | Contents |
 |---|---|
-| `<git-common-dir>/dsh-tower/state.json` | missions, roster, reviews, findings, messages, reviews sequence |
+| `<git-common-dir>/dsh-tower/state.json` | active missions, roster, reviews, findings, messages, reviews sequence |
+| `<git-common-dir>/dsh-tower/archive/index.json` | compact terminal-mission index (ids, status, branch, timestamps) |
+| `<git-common-dir>/dsh-tower/archive/<year>.json` | full archived missions plus their linked reviews/findings |
 | `<git-common-dir>/dsh-tower/activity.jsonl` | append-only activity |
 | `<git-common-dir>/dsh-tower/state.lock` | single-writer state lock (dead-PID reclaimed, live lock reported) |
 | `<git-common-dir>/dsh-tower/git.lock` | repo-scoped serialization for git mutations outside the state lock |

package/docs/guide/install-upgrade-migration.md

@@ -29,7 +29,24 @@ The Host plugin loads at DSH startup: **restart DSH after install or update**.
 
 ## Migration notes
 
-- **2.0.4 → 2.1.0-beta.1**: no state/config migration. This is a **pre-release** published on the
+- **state schema v1 → v2 (unreleased)**: `state.json` migrates automatically. The first **write** after
+  upgrading keeps a `state.json.v1.bak` backup, advances `revision` once, and appends
+  `state.migrated {from,to}` to `activity.jsonl`; read-only tools keep reading a v1 file without
+  rewriting it. `tower_doctor` reports the on-disk version and the pending migration. A file written by
+  a newer plugin is refused with `[tower:state-version-unsupported]` and is never rewritten or
+  downgraded; a migration that throws reports `[tower:state-migration-failed]` and leaves the original
+  file byte-identical.
+
+- **state schema v2 → v3 (unreleased, #90)**: scope matching follows the checkout's filesystem. The
+  migration backfills `caseInsensitive: null` ("not detected"); a migration never reads the filesystem,
+  so the first `tower_init` after upgrading probes the checkout once and records `true`/`false`. Until
+  then the safe `case-sensitive` comparison applies, and `tower_doctor` reports the unknown mode as a
+  `warn` (`case-mode`). On a case-insensitive checkout, `src/Api/**` and `src/api/**` then count as
+  overlapping and case-only mismatches are no longer refused by the out-of-scope gate. Stored scope
+  strings are never rewritten: the board keeps showing what the operator typed.
+
+- **2.0.4 → 2.1.0-beta.1**: no config migration; the state file migrates automatically (v1/v2 → v3) as
+  described above. This is a **pre-release** published on the
   `next` dist-tag, so `latest` still resolves to 2.0.4 — install it with
   `dsh plugin --profile web add dsh-tower@next` (or the exact version). The runtime behavior is
   unchanged; the release carries the delivery gate (mount smoke in CI, `npm run release:check`, the

package/docs/reference/blockers.md

@@ -16,7 +16,7 @@ tables below define 32 stable blocker/failure codes.
 | `branch-missing` | No worktree/branch yet: spawn a worker first. |
 | `stale-base` | The branch does not contain the base tip: run `tower_rebase`. |
 | `read-only-survey` | Survey mission changed files; survey missions must be read-only. |
-| `out-of-scope` | Changed files outside the mission scope; widen scope deliberately or revert. |
+| `out-of-scope` | Changed files outside the mission scope; widen scope deliberately or revert. On a case-sensitive checkout a case-only mismatch is still rejected and the detail names the scope entry it would match if case were folded. |
 | `base-dirty` | The main checkout has uncommitted changes the merge would overwrite. |
 | `deps-unmerged` | A dependency mission is not merged/abandoned. |
 | `no-review` | `review.requireReview:true` and no review exists on the branch: spawn a reviewer (or disable the review gate). |

package/docs/reference/config.generated.md

@@ -51,8 +51,12 @@
 | `gates.requireChecks` | `false` | Require at least one completion check (tower_complete.checks) before a mission can merge. |
 | `gates.requireTests` | `false` | Require a passing test-discovery receipt for the reviewed worktree tip before merge. |
 | `gates.allowReviewExemption` | `false` | Allow reviewPolicy:none missions with a non-empty reviewExemptionReason to skip review blockers. |
+| `gates.maxReportBytes` | `32768` | Hard cap, in UTF-8 bytes, for tower_complete.report; a larger report is rejected with an actionable nextAction, never truncated. |
 | `docs.board` | `true` | Write a human-readable MISSIONS.md after mission changes. |
 | `docs.boardLocation` | `"common"` | common = <git-common-dir>/dsh-tower/MISSIONS.md; repo = <repoRoot>/MISSIONS.md. |
+| `archive.enabled` | `true` | Move terminal (merged/abandoned) missions whose worktree is gone into <git-common-dir>/dsh-tower/archive/ at the next mutation, so state.json stops carrying their full history. |
+| `archive.afterDays` | `30` | Terminal missions untouched for at least this many days are archived on the next mutation (0 archives them immediately). |
+| `archive.maxMissions` | `100` | Maximum terminal missions kept hot; once exceeded, the oldest eligible terminal missions are archived until the cap holds (0 archives every eligible terminal mission). |
 | `tools.exposeOperational` | `true` | Master switch for batch/resource/import/legacy/recover/test/doctor tools. |
 | `tools.exposeBatch` | `true` | Register tower_batch. |
 | `tools.exposeImport` | `true` | Register tower_import_legacy/tower_legacy_map. |

package/docs/reference/config.md

@@ -83,8 +83,12 @@ violates the declared schema (for example `merge.timeoutMs` below 1000) fail wit
 | `gates.requireChecks` | `false` | Require at least one `tower_complete.checks` entry before merge (`no-check-evidence`). |
 | `gates.requireTests` | `false` | Require a passing discovery receipt for the current mission branch tip (`tests-missing`); independent of the review gate. |
 | `gates.allowReviewExemption` | `false` | With `review.requireReview:true`, allow `reviewPolicy:"none"` + a non-empty reason to skip review blockers. Off deliberately; irrelevant while the global review gate is off. |
+| `gates.maxReportBytes` | `32768` (32 KiB) | Hard cap in UTF-8 bytes for `tower_complete.report`. A larger report is rejected with `invalid-argument` and an actionable `nextAction` (file the full text in the mission worktree and reference its path); it is never truncated. Existing larger reports still load. |
 | `docs.board` | `true` | Write `MISSIONS.md` after mutations. |
 | `docs.boardLocation` | `common` | `common` = `<git-common-dir>/dsh-tower/MISSIONS.md`; `repo` = `<repoRoot>/MISSIONS.md`. |
+| `archive.enabled` | `true` | Move terminal (`merged`/`abandoned`) missions whose worktree is gone into `<git-common-dir>/dsh-tower/archive/` at a mutation boundary. Archived missions keep tasks, reviews, findings and the completion report; they are moved, never deleted. |
+| `archive.afterDays` | `30` | Age trigger: a terminal mission untouched for at least this many days is archived on the next mutation (`0` archives immediately). |
+| `archive.maxMissions` | `100` | Cap trigger: once more than this many terminal missions are hot, the oldest eligible ones are archived until the cap holds (`0` archives every eligible terminal mission). A mission with a live worktree is never archived. |
 | `tools.exposeOperational` | `true` | Register batch/resource/import/legacy/recover/test/doctor tools; `false` shrinks the fixed tool-schema context. |
 | `leases.ttlMs` | `900000` | Default advisory lease lifetime; expiry never auto-releases. |
 | `dev.hotReload` | `true` | Register `tower_reload`; `/tower reload` is disabled when off. It returns `reload-unavailable` when the profile has no HMR service. |

package/docs/reference/doctor.md

@@ -8,26 +8,76 @@ It returns:
   "ok": true,
   "checks": [
     { "id": "git", "status": "pass", "detail": "git version 2.55.0" },
-    { "id": "state", "status": "pass", "detail": ".../state.json revision 7" }
+    { "id": "state", "status": "pass", "detail": ".../state.json revision 7" },
+    { "id": "state-schema", "status": "pass", "detail": "schemaVersion 3 is current" },
+    { "id": "case-mode", "status": "pass", "detail": "caseInsensitive: true; scope matching uses case-insensitive comparison" }
   ],
+  "stateSchema": {
+    "currentVersion": 3,
+    "supportedVersion": 3,
+    "migrations": [],
+    "status": "current"
+  },
+  "archive": {
+    "missions": 3,
+    "archivedMissions": 12,
+    "stateBytes": 48211,
+    "archiveBytes": 190244,
+    "years": [2026],
+    "files": 2,
+    "unreadable": [],
+    "policy": { "enabled": true, "afterDays": 30, "maxMissions": 100 }
+  },
   "environmentContract": {
     "platform": "win32",
     "gitVersion": "git version 2.55.0",
     "repoRoot": "D:/repo",
     "commonDir": "D:/repo/.git",
-    "stateDir": "D:/repo/.git/dsh-tower"
+    "stateDir": "D:/repo/.git/dsh-tower",
+    "caseInsensitive": true,
+    "comparisonMode": "case-insensitive"
   }
 }
 ```
 
+`stateSchema` describes the file **on disk**, not the in-memory document: `currentVersion` is the
+`schemaVersion` doctor read, `supportedVersion` is the build's `SCHEMA_VERSION`, and `migrations` is
+the ordered v→v path a write would apply (`[]` when current). `status` is one of `current`,
+`migratable`, `newer`, `unmigratable`, `invalid`. Doctor never migrates, so a `migratable` file stays
+byte-identical and the `state-schema` check is a `warn` (the next locked write applies the migration
+and keeps a `state.json.v<N>.bak` backup). A file written by a newer plugin reports `newer` and a
+`fail`: this build refuses to downgrade it. A state-load failure is reported as a failed check rather
+than thrown so doctor remains useful on a broken repository.
+
+`archive` reports the terminal-mission archive: active `missions`, `archivedMissions` and `stateBytes`,
+the archive directory's `archiveBytes`/`years`/`files`, every `unreadable` diagnostic, and the configured
+`policy` (`enabled`, `afterDays`, `maxMissions`). A missing archive directory is a healthy empty archive
+(`archive` check `pass`); a truncated index or year file is a `warn` with the diagnostic, and archiving is
+paused until it is repaired rather than overwriting it. Nothing is lost while the archive is unreadable:
+the eligible missions stay in `state.json`.
+
 Checks cover: git availability, repository identity, state schema/load, repo config presence,
 worker/reviewer preset names, subagents and HMR services, workspace lock holder/staleness, live roster,
-worktree existence/ownership/dirtiness, test-discovery policy, legacy snapshots, batches and leases.
-Missions intentionally cleaned up by `tower_teardown` are skipped (the check notes the removed count)
-instead of being reported as missing.
-`warn` is advisory; `fail` means the repository needs attention before spawning/merging. A state-load
-failure is reported as a failed check rather than thrown so doctor remains useful on a broken
-repository.
+worktree existence/ownership/dirtiness, test-discovery policy, completion-report sizes, archive health, legacy`nsnapshots, batches and leases. Missions intentionally cleaned up by `tower_teardown` are skipped (the check`nnotes the removed count) instead of being reported as missing.
+
+`caseInsensitive` is the mode `tower_init` detected once on the checkout's filesystem; `null` means
+"not detected yet" and the `case-mode` check is a `warn`. `comparisonMode` is the comparison scope
+matching actually uses: `case-insensitive` folds both sides, `case-sensitive` stays byte-exact. Doctor
+never probes — a probe creates a temporary file, and a read-only call must not write. Run
+`tower_init` on a writable checkout to record the mode; until then the safe `case-sensitive` default
+applies.
+
+Checks cover: git availability, repository identity, state schema/load, the detected case mode, repo
+config presence, worker/reviewer preset names, subagents and HMR services, workspace lock
+holder/staleness, live roster, worktree existence/ownership/dirtiness, test-discovery policy, legacy
+snapshots, batches and leases. Missions intentionally cleaned up by `tower_teardown` are skipped (the
+check notes the removed count) instead of being reported as missing.
+`warn` is advisory; `fail` means the repository needs attention before spawning/merging.
+
+The `reports` check names the largest completion report in the repository (`<bytes> B on <mission>`,
+against the `gates.maxReportBytes` cap); the same numbers are returned as
+`reports: { count, largest: { missionId, bytes } | null, capBytes }`. Reports written before the cap
+only produce a `warn`; doctor never rewrites them.
 
 The environment contract is informational; it is not an identity or authorization proof. `tower_init`
 still requires the tower role, and `tower_spawn` still checks the live subagent catalog.

package/docs/reference/errors.generated.md

@@ -13,6 +13,8 @@
 | `stale-base` | The repository state changed while the operation was being prepared; retry. |
 | `state-locked` | Another Tower writer holds the state lock. |
 | `state-corrupt` | The Tower state file is unreadable or invalid. |
+| `state-version-unsupported` | The Tower state file uses a schema version this build cannot read or downgrade. |
+| `state-migration-failed` | A Tower state migration failed; the original state file was not modified. |
 | `config-invalid` | Tower configuration is invalid. |
 | `config-unknown-key` | Tower configuration has an unknown top-level key. |
 | `git-failed` | A git command failed. |

package/docs/reference/errors.md

@@ -2,7 +2,7 @@
 
 Tool failures are thrown errors, not `{ok:false}` results (gate outcomes are the exception: see
 [blockers.md](blockers.md)). Every thrown error carries a stable code as a message prefix. This
-release defines 33 tool error codes.
+release defines 35 tool error codes.
 
 Every `TowerToolError` also carries `retryable` (boolean), `nextAction` (string or `null`) and `details`
 (structured context or `null`) for programmatic callers; the message prefix remains the stable contract
@@ -26,7 +26,9 @@ plain `Error` without a structured code is reported as `tool-internal`.
 | `stale-base` | The repository state changed while the operation was being prepared; retry. | two-phase mutation revalidation |
 | `worktree-dirty` | The mission worktree has uncommitted changes and cannot complete. | staged, modified, or untracked files left behind before `tower_complete` |
 | `state-locked` | Another Tower writer holds the state lock. | concurrent mutation after the lock timeout |
-| `state-corrupt` | The Tower state file is unreadable or invalid. | hand-edited `state.json` |
+| `state-corrupt` | The Tower state file is unreadable or invalid. | hand-edited `state.json`; invalid JSON; no usable `schemaVersion` |
+| `state-version-unsupported` | The state file's schema version is newer than this build supports, or cannot be migrated. | opening a repository written by a newer plugin; an unknown older version; this build refuses to downgrade |
+| `state-migration-failed` | A state migration threw; the original file was not modified. | a bug in a migration step; see the pre-migration `state.json.v<N>.bak` |
 | `config-invalid` | Tower configuration is invalid. | malformed repo `config.json`, a value that violates the schema |
 | `config-unknown-key` | Tower configuration has an unknown top-level key. | a typo such as `allowAgentToggle` |
 | `git-failed` | A git command failed for a reason other than the delegated cases. | a rejected merge command, invalid ref |

package/docs/reference/tools.generated.md

@@ -6,19 +6,19 @@
 |---|---|
 | `tower_adopt` | Reconcile the roster with the durable subagent catalog after a restart or new session. Agents that are provably gone are marked retired (records are kept) or missing (retireMissing:false, so the tower can inspect/take over); agents whose parent catalog cannot be read stay unknown and are never changed. Only the tower may adopt. |
 | `tower_batch` | Manage finite evidence batches: create freezes missionIds/requiredChecks/receiptPaths, status summarizes members, close verifies every required check and receipt hash, abandon retires a stale open batch. Membership and exclusions are immutable after create; close/abandon never remove missions. |
-| `tower_complete` | Worker-only: report mission completion. Enforced by the store: every task done or dropped, no blockers, the current owner, the mission branch has at least one commit since its spawn base, and no unread inbox messages. checks records verifiable evidence (name/command/exitCode/evidence); gates.requireChecks can require at least one before merge. Stores the full report; completion means ready for preflight and optional review, not merged. |
+| `tower_complete` | Worker-only: report mission completion. Enforced by the store: every task done or dropped, no blockers, the current owner, the mission branch has at least one commit since its spawn base, and no unread inbox messages. checks records verifiable evidence (name/command/exitCode/evidence); gates.requireChecks can require at least one before merge. Stores the full report, capped at gates.maxReportBytes (default 32768 UTF-8 bytes); a larger report is rejected with invalid-argument and an actionable nextAction, never truncated. Persists reportBytes on the stored report. completion means ready for preflight and optional review, not merged. |
 | `tower_diff` | Read-only view of a mission branch for review: merge base, changed files, commits, and a capped patch against the recorded base. Safe for reviewers; it never modifies the repository. |
-| `tower_doctor` | Read-only environment and repository health check: git, state schema, config, presets/subagents/HMR, workspace lock, roster staleness, worktree ownership, test discovery, leases. Returns checks with pass/warn/fail and an environment contract. Never writes state. |
+| `tower_doctor` | Read-only environment and repository health check: git, state schema, case-sensitivity detection (caseInsensitive and the active scope comparison mode), config, presets/subagents/HMR, workspace lock, roster staleness, worktree ownership, test discovery, leases, and the terminal-mission archive (count, bytes, years, unreadable diagnostics and the configured afterDays/maxMissions policy). Returns checks with pass/warn/fail and an environment contract. Never writes state and never probes the filesystem. |
 | `tower_finding` | File a structured finding (bug / improve / vuln / idea) for the tower to route. Use this for anything notable OUTSIDE your mission scope instead of editing out-of-scope files. Severity is one of low|medium|high|critical. Use tower_findings to list, read, or close findings later. |
 | `tower_findings` | List, read, or update findings for a repository. Without id it lists findings newest-first with counts by status (filters: status, type, severity, missionId, open, limit). With id it returns that finding; with id plus status and/or note it records a lifecycle transition. Statuses are open -> triaged -> fixed|wontfix, and fixed/wontfix can be reopened to open. Only the tower or a worker may change a finding; reviewers may only list and read. Read-only when no id is given. |
 | `tower_import_legacy` | Read-only import of a Tower Codex (schemaVersion 1) or DSH legacy state file. Stores the full payload under <common>/dsh-tower/legacy/<sha256>.json and records only a summary in state.legacySnapshots; never activates, adopts, or resumes paused missions. |
 | `tower_inbox` | Read your tower inbox: messages addressed to you plus broadcasts, newest first. Only returned messages are acknowledged; the result reports unreadRemaining, so keep reading until it reaches 0. Set include_read for history. Unread messages block tower_complete. |
-| `tower_init` | Initialize Tower mission state for a repository (absolute repoRoot). Creates <git-common-dir>/dsh-tower/state.json and an activity log; idempotent on an existing workspace. Options: autoGitInit (git init + empty initial commit when the directory is not a repository), snapshotDirty (snapshot uncommitted work into a dangling commit used as the mission baseline), reanchor (change base when every mission is merged/abandoned). Only the tower may initialize. |
+| `tower_init` | Initialize Tower mission state for a repository (absolute repoRoot). Creates <git-common-dir>/dsh-tower/state.json and an activity log; idempotent on an existing workspace. Probes whether the checkout filesystem folds case and records caseInsensitive once, so scope matching follows the real filesystem (a skipped probe records null and keeps the safe case-sensitive comparison). Options: autoGitInit (git init + empty initial commit when the directory is not a repository), snapshotDirty (snapshot uncommitted work into a dangling commit used as the mission baseline), reanchor (change base when every mission is merged/abandoned). Only the tower may initialize. |
 | `tower_interrupt` | Interrupt one running tower roster agent (worker or reviewer) and record it as interrupted in the roster. Only the tower may interrupt. Idempotent: an agent that is not running returns interrupted:false. Use it before takeover after a runaway worker, or to stop work that is no longer wanted. |
 | `tower_legacy_map` | Audit-only mapping between a legacy snapshot id and a current mission. map records sourceHash/oldId/newMissionId; status lists mappings. Mapping never adopts or resumes a legacy mission. |
 | `tower_merge` | Merge a mission branch into the recorded base branch with --no-ff, after the hard gate passes. Verifies the two merge parents and records the mission as merged. If the merge commit already landed (manual merge, crashed or slow pre-merge hook), it detects the merge commit and records it as reconciled instead of merging again. A failed gate returns stable blocker codes without merging; a hook failure aborts cleanly and returns "merge-hook-failed" while a real content conflict returns "merge-conflict". |
 | `tower_mission` | Update one mission: lifecycle status, decision note, blocker, clear blockers, mark a task done, drop a task with a reason, or widen the scope (tower only). "merged" is never set here; only a future tower_merge records it. Merged and abandoned are terminal. |
-| `tower_plan` | Plan one or more missions in an initialized repository. Each mission has a printable-ASCII title, relative scope globs, optional task checklist, optional mission-id dependencies, and kind build|survey. Assigns M1.. ids and auto-adds a dependency when build scopes overlap (serializes merges); rejects dependency cycles. |
+| `tower_plan` | Plan one or more missions in an initialized repository. Each mission has a printable-Unicode title (NFC-normalized, at most 120 characters), relative scope globs, optional task checklist, optional mission-id dependencies, and kind build|survey. Assigns M1.. ids and auto-adds a dependency when build scopes overlap (serializes merges); rejects dependency cycles. |
 | `tower_preflight` | Read-only merge gate for one mission: returns ok plus stable blocker codes (branch-missing, deps-unmerged, read-only-survey, stale-base, out-of-scope, base-dirty, branch-owned-by-closed-missions, and mission/worker guards). Review blockers (no-review, review-hold, not-clean, review-not-approved, tip-moved, review-mission-mismatch) apply only when review.requireReview is on. Never changes anything. |
 | `tower_rebase` | Rebase a mission branch onto the current base tip inside its own worktree. Refuses while its worker is running or the worktree is dirty. A clean conflict-free rebase waives re-review for the old review; a conflict is aborted and the mission is marked blocked. If the branch is already contained in the base, it returns alreadyMerged and leaves the branch untouched so tower_merge can record the landed merge. |
 | `tower_recover` | Read-only recovery diagnostics and an explicit stale-state-lock repair. status reports the state lock owner; clear-stale-lock requires confirm:"CLEAR_STALE_LOCK" and only moves a lock whose PID is provably dead to a backup file. It never resets Tower state or worktrees. |
@@ -28,6 +28,6 @@
 | `tower_roster` | List tower roster agents with authoritative live activity from the subagent catalog (running/inactive/missing/unknown). Read-only; never resumes children. Use before completion or merge decisions. |
 | `tower_send` | Send a durable inbox message to a tower participant: a roster agent name, "tower", or "all" (broadcast). The message is persisted first; when the recipient is a currently running roster agent the tower also steers it into that child's current turn. Returns delivery results. |
 | `tower_spawn` | Spawn a worker or reviewer for a mission. Workers use the tower-worker preset; reviewers require a completed mission and use the read-only tower-reviewer preset. Provisions (or reuses) the mission git worktree and branch, generates a self-contained briefing, and starts a background subagent in that worktree. The child final report is delivered back to this session; tower_roster shows authoritative activity. Records the agent in the roster; reviewer spawns record the branch tip so a reviewer that modifies the branch cannot submit a review. Returns immediately unless wait=true. |
-| `tower_status` | Read the Tower dashboard for a repository: state path, base branch, revision, mission status counts, paged mission summaries (scope/deps/tasks/worktree/owner), roster size, findings, config path and the activity tail. Pass missionId for one full mission (tasks, notes, reviews, findings, completion report); offset/limit page the mission list (default 20, max 100); includeGate adds preflight gate digests for the page; format:"markdown" returns the human-readable mission board. Read-only. |
-| `tower_teardown` | Tear down eligible mission worktrees after their missions are merged or abandoned. A worktree whose roster agent is running is always kept (force cannot override); dirty worktrees need force; exclude keeps named missions. dry_run previews the remove/keep decisions without changing anything. |
+| `tower_status` | Read the Tower dashboard for a repository: state path, base branch, revision, mission status counts, paged mission summaries (scope/deps/tasks/worktree/owner), roster size, findings, archive count, config path and the activity tail. Pass missionId for one full mission (tasks, notes, reviews, findings, completion report; archived missions are loaded from their year file); offset/limit page the mission list (default 20, max 100); includeGate adds preflight gate digests for the page; includeArchived appends compact archived summaries after the active page; format:"markdown" returns the human-readable mission board (active missions plus an archived count). Read-only. |
+| `tower_teardown` | Tear down eligible mission worktrees after their missions are merged or abandoned. A worktree whose roster agent is running is always kept (force cannot override); dirty worktrees need force; exclude keeps named missions. dry_run previews the remove/keep decisions without changing anything. Terminal missions whose worktree is gone and whose configured archive policy is due (archive.afterDays / archive.maxMissions) are moved to <git-common-dir>/dsh-tower/archive/ so state.json stops rewriting them; nothing is deleted. |
 | `tower_test` | Run the mission worktree's declared tower.testDiscovery (package.json) and record the receipt. Returns ok:false with diagnostics when discovery fails; does not change mission status. Use tower_complete for automatic admission checks. |