dsh-tower 2.6.0 → 2.7.0

package/domain/shapes/index.js

@@ -0,0 +1,171 @@
+// The one shape registry (#149). A *shape* is the contract a mission kind
+// carries: its status vocabulary and transitions, what it provisions, how it
+// completes, how dependencies are satisfied, and what its briefing and summary
+// say. Generic layers resolve a shape once through `shapeFor()` and never
+// compare `mission.kind`.
+//
+// `isTerminal(kind, status)` and `canTransition(kind, from, to)` are the only
+// entry points for status policy; the old global `TERMINAL_STATUSES` and
+// `TRANSITIONS` tables are gone.
+// @ts-check
+import { TowerToolError } from '../errors.js'
+import { buildShape } from './build.js'
+import { surveyShape } from './survey.js'
+
+/** @typedef {import('../../types/index.js').Mission} Mission */
+
+/** @type {Readonly<Record<string, typeof buildShape | typeof surveyShape>>} */
+export const SHAPES = Object.freeze({
+  build: buildShape,
+  survey: surveyShape,
+})
+
+/** Ordered kind vocabulary; the first kind is the default for absent kinds. */
+/** @type {readonly string[]} */
+export const SHAPE_KINDS = Object.freeze(Object.keys(SHAPES))
+
+/**
+ * Resolve a mission kind to its shape.
+ *
+ * A document written before schema v4 may omit `kind`; the v3 -> v4 migration
+ * stamps `build`, and pure helpers that tolerate partial mission snapshots still
+ * resolve an absent kind as the build shape. An unknown non-empty kind is never
+ * guessed.
+ * @param {string | null | undefined} kind
+ * @returns {typeof buildShape | typeof surveyShape}
+ */
+export function shapeFor(kind) {
+  if (kind === undefined || kind === null || kind === '') return SHAPES.build
+  const shape = SHAPES[kind]
+  if (!shape) {
+    throw new TowerToolError('invalid-argument', `unknown mission kind "${kind}"; expected one of ${SHAPE_KINDS.join('|')}`)
+  }
+  return shape
+}
+
+/**
+ * @param {unknown} kind
+ * @returns {boolean}
+ */
+export function isShapeKind(kind) {
+  return typeof kind === 'string' && Object.hasOwn(SHAPES, kind)
+}
+
+/**
+ * The only terminality entry point.
+ * @param {string | null | undefined} kind
+ * @param {string} status
+ * @returns {boolean}
+ */
+export function isTerminal(kind, status) {
+  return shapeFor(kind).isTerminal(status)
+}
+
+/**
+ * The only transition entry point.
+ * @param {string | null | undefined} kind
+ * @param {string} from
+ * @param {string} to
+ * @returns {boolean}
+ */
+export function canTransition(kind, from, to) {
+  return shapeFor(kind).canTransition(from, to)
+}
+
+/**
+ * @param {string | null | undefined} kind
+ * @returns {boolean}
+ */
+export function canMerge(kind) {
+  return shapeFor(kind).canMerge
+}
+
+/**
+ * @param {string | null | undefined} kind
+ * @returns {boolean}
+ */
+export function canRebase(kind) {
+  return shapeFor(kind).canRebase
+}
+
+/**
+ * Resolve how a mission of this kind is provisioned. A shape may resolve the
+ * placement from tuning config (#148 W2: a survey is `shared` by default and
+ * `detached` with `survey.sandbox: 'detached'`); a shape without a resolver keeps
+ * its static placement. When a mission is supplied, a placement already recorded
+ * on it (a provisioned detached sandbox) wins over config.
+ * @param {string | null | undefined} kind
+ * @param {import('../../types/index.js').TowerConfig} [config]
+ * @param {import('../../types/index.js').Mission | null | undefined} [mission]
+ * @returns {'branch-worktree' | 'shared' | 'detached'}
+ */
+export function provisioningFor(kind, config = {}, mission = null) {
+  const shape = shapeFor(kind)
+  if ('resolveProvisioning' in shape && typeof shape.resolveProvisioning === 'function') {
+    return shape.resolveProvisioning(mission, config)
+  }
+  return shape.provisioning
+}
+
+/**
+ * Resolve the agent preset that executes this kind in the configured placement.
+ * A build keeps its `spawn.defaultPreset`; a survey switches between the
+ * read-only preset and the sandbox preset so the allow-list follows the
+ * resolved placement rather than a hard-coded kind.
+ * @param {string | null | undefined} kind
+ * @param {import('../../types/index.js').TowerConfig} [config]
+ * @param {import('../../types/index.js').Mission | null | undefined} [mission]
+ * @returns {string | null}
+ */
+export function defaultPresetFor(kind, config = {}, mission = null) {
+  const shape = shapeFor(kind)
+  if ('resolvePreset' in shape && typeof shape.resolvePreset === 'function') {
+    return shape.resolvePreset(mission, config)
+  }
+  return 'defaultPreset' in shape.spawn ? shape.spawn.defaultPreset : null
+}
+
+/**
+ * Refuse branch-shaped actions for a shape that has no branch. The message tells
+ * the caller what to do instead, so the refusal is actionable rather than a bare
+ * "invalid transition".
+ * @param {Mission} mission
+ * @param {'merge' | 'rebase' | 'preflight' | 'diff'} action
+ * @returns {void}
+ */
+export function assertActionSupported(mission, action) {
+  const shape = shapeFor(mission.kind)
+  // Derived from the shape, never from a hard-coded kind: a new shape that has
+  // no branch gets the same refusals without touching this function.
+  const evidence = shape.fields.readCommit
+    ? `readCommit ${String(mission.readCommit ?? '').slice(0, 12)}`
+    : 'recorded evidence'
+  if (action === 'merge' && !shape.canMerge) {
+    throw new TowerToolError(
+      'invalid-transition',
+      `mission ${mission.id} is a ${shape.kind}: it has no branch to merge and is never merged; a completed ${shape.kind} already satisfies its dependents`,
+      { nextAction: `use tower_complete to finish the ${shape.kind}; its ${evidence} is the evidence` },
+    )
+  }
+  if (action === 'rebase' && !shape.canRebase) {
+    throw new TowerToolError(
+      'invalid-transition',
+      `mission ${mission.id} is a ${shape.kind}: it has no branch to rebase; a ${shape.kind} does not move`,
+      { nextAction: `re-plan the ${shape.kind} if the base moved; the recorded ${evidence} is immutable` },
+    )
+  }
+  if (action === 'preflight' && !shape.canMerge) {
+    throw new TowerToolError(
+      'invalid-transition',
+      `mission ${mission.id} is a ${shape.kind}: it has no merge gate; tower_complete checks HEAD, tracked files and zero commits`,
+      { nextAction: `use tower_complete to finish the ${shape.kind}; ${shape.kind}s are not preflighted or merged` },
+    )
+  }
+  if (action === 'diff' && !shape.canMerge) {
+    throw new TowerToolError(
+      'invalid-transition',
+      `mission ${mission.id} is a ${shape.kind}: it has no branch diff; its ${evidence} is the evidence`,
+      { nextAction: `inspect the recorded ${evidence} directly, or the ${shape.kind} result recorded at completion` },
+    )
+  }
+}

package/domain/shapes/survey.js

@@ -0,0 +1,445 @@
+// The survey shape (#148/#149): a read of one commit, not a write of a branch.
+//
+// A survey has no worktree, no branch and no commit of its own. By default it
+// runs in the shared checkout with a read-only preset allow-list. With
+// `survey.sandbox: 'detached'` the read moves into a disposable detached git
+// worktree at the recorded commit (#148 W2): the sandbox preset may write and
+// run commands there, but the sandbox has no branch, never merges, is removed
+// when the mission completes or is abandoned, and must still end at the
+// recorded commit with zero commits. Both placements record the commit read
+// plus the tracked-status fingerprint captured at plan time; only the shared
+// placement enforces the fingerprint as a completion invariant.
+// @ts-check
+import { TowerToolError } from '../errors.js'
+import { hasCheckEvidence } from '../evidence.js'
+
+/** @typedef {import('../../types/index.js').Mission} Mission */
+/** @typedef {import('../../types/index.js').Blocker} Blocker */
+/** @typedef {import('../../types/index.js').TowerConfig} TowerConfig */
+
+/** @type {readonly string[]} */
+export const SURVEY_STATUSES = Object.freeze(['planned', 'active', 'completed', 'blocked', 'paused', 'abandoned'])
+
+/**
+ * The evidence this shape accepts (#149 W4). A survey has no branch and no
+ * tree tip, so a discovery receipt cannot appertain; its completion checks are
+ * still accepted through the same one reader.
+ * @type {import('../evidence.js').EvidenceContract}
+ */
+export const EVIDENCE = Object.freeze({
+  completionChecks: true,
+  testReceipts: /** @type {const} */ (false),
+})
+
+/**
+ * The survey shape's path reach (#149 W4): a survey owns no paths. Its scope is
+ * empty by construction and any changed path is a fence violation; the
+ * placement (shared read-only checkout or detached disposable sandbox) changes
+ * where it runs, not what it may change.
+ * @type {{ ownsPaths: boolean, fence: 'scope' | 'read-only' }}
+ */
+export const REACH = Object.freeze({
+  ownsPaths: false,
+  fence: /** @type {const} */ ('read-only'),
+})
+
+/**
+ * A survey has no `merged` row or column: it is never merged, only completed.
+ * @type {Readonly<Record<string, readonly string[]>>}
+ */
+export const SURVEY_TRANSITIONS = Object.freeze({
+  planned: Object.freeze(['active', 'blocked', 'abandoned']),
+  active: Object.freeze(['completed', 'blocked', 'paused', 'abandoned']),
+  // W3: `blocked` is derived from open blockers; clearing them is the only way
+  // out, and a blocker always wins over a pause (hence paused -> blocked).
+  blocked: Object.freeze(['active', 'abandoned']),
+  paused: Object.freeze(['active', 'blocked', 'abandoned']),
+  completed: Object.freeze([]),
+  abandoned: Object.freeze([]),
+})
+
+/**
+ * @param {string} status
+ * @returns {boolean}
+ */
+export function isTerminal(status) {
+  return status === 'completed' || status === 'abandoned'
+}
+
+/**
+ * @param {string} from
+ * @param {string} to
+ * @returns {boolean}
+ */
+export function canTransition(from, to) {
+  return (SURVEY_TRANSITIONS[from] ?? []).includes(to)
+}
+
+/**
+ * Survey planning records what is being read, not what will be written: the
+ * commit and the tracked-status fingerprint at plan time. Scope is empty.
+ * @param {{ readCommit?: unknown, readDirty?: unknown }} context
+ * @returns {{ scope: string[], readCommit: string, readDirty: string[] }}
+ */
+export function planFields(context) {
+  const readCommit = context.readCommit
+  if (typeof readCommit !== 'string' || readCommit.length === 0) {
+    throw new TowerToolError('invalid-argument', 'a survey needs the commit it reads (state.base did not resolve)', {
+      nextAction: 'run tower_init so the base branch resolves to a commit, then plan the survey again',
+    })
+  }
+  const readDirty = Array.isArray(context.readDirty)
+    ? context.readDirty.filter((entry) => typeof entry === 'string')
+    : []
+  return { scope: [], readCommit, readDirty }
+}
+
+/**
+ * Completion invariants for a survey that reads the shared checkout: zero
+ * commits, same HEAD, same tracked files. The app layer supplies the observed
+ * primitives.
+ * @param {{ mission: Mission, head: string, readCommit: string, trackedChanged: string[] }} context
+ * @returns {{ commits: number }}
+ */
+export function checkCompletion({ mission, head, readCommit, trackedChanged }) {
+  if (head !== readCommit) {
+    throw new TowerToolError(
+      'invalid-argument',
+      `survey ${mission.id} moved HEAD from ${String(readCommit).slice(0, 12)} to ${String(head).slice(0, 12)}; a survey reads one commit and makes no commits`,
+      { nextAction: 'reset the shared checkout to the recorded readCommit; do not commit survey work' },
+    )
+  }
+  if (trackedChanged.length > 0) {
+    throw new TowerToolError(
+      'invalid-argument',
+      `survey ${mission.id} changed tracked files: ${trackedChanged.join(', ')}; a survey is read-only`,
+      { nextAction: 'restore the shared checkout tracked files to the status captured at plan time' },
+    )
+  }
+  return { commits: 0 }
+}
+
+/**
+ * Completion invariants for a detached survey sandbox: the disposable checkout
+ * is allowed to contain write/shell side effects, but it may not commit and it
+ * must still be at the recorded commit. The sandbox itself is removed after a
+ * successful completion.
+ * @param {{ mission: Mission, head: string, readCommit: string, commits: number, sandbox: string }} context
+ * @returns {{ commits: number }}
+ */
+export function checkSandboxCompletion({ mission, head, readCommit, commits, sandbox }) {
+  if (!sandbox || sandbox !== mission.sandbox) {
+    throw new TowerToolError(
+      'invalid-argument',
+      `detached survey ${mission.id} has no recorded sandbox; re-provision the survey or abandon it`,
+      { nextAction: 'run tower_spawn to create the detached sandbox again, then complete' },
+    )
+  }
+  if (commits !== 0) {
+    throw new TowerToolError(
+      'invalid-argument',
+      `survey ${mission.id} made ${commits} commit(s) in its detached sandbox; a survey reads one commit and records no commit of its own`,
+      { nextAction: `reset --hard ${String(readCommit).slice(0, 12)} in ${sandbox}; the sandbox is disposable but its HEAD must stay at the recorded commit` },
+    )
+  }
+  if (head !== readCommit) {
+    throw new TowerToolError(
+      'invalid-argument',
+      `survey ${mission.id} moved the detached sandbox HEAD from ${String(readCommit).slice(0, 12)} to ${String(head).slice(0, 12)}; a survey reads one commit and makes no commits`,
+      { nextAction: `reset --hard ${String(readCommit).slice(0, 12)} in ${sandbox}; the sandbox is removed on completion` },
+    )
+  }
+  return { commits: 0 }
+}
+
+/**
+ * Resolve the survey placement (#148 W2). The shape owns the decision so
+ * generic layers never compare `mission.kind` or read the raw key.
+ *
+ * A sandbox already recorded on the mission is authoritative: provisioned
+ * state must win over current config, otherwise flipping `survey.sandbox`
+ * between provision and completion would silently move the mission to the
+ * shared checkout (or make the completion invariants disagree with the
+ * checkout that actually exists). Config only decides initial provisioning.
+ * @param {Mission | null | undefined} [mission]
+ * @param {TowerConfig} [config]
+ * @returns {'shared' | 'detached'}
+ */
+export function resolveProvisioning(mission, config = /** @type {TowerConfig} */ ({})) {
+  const recorded = mission && typeof mission.sandbox === 'string' ? mission.sandbox.trim() : ''
+  if (recorded.length > 0) return 'detached'
+  return config.survey?.sandbox === 'detached' ? 'detached' : 'shared'
+}
+
+/**
+ * The preset that executes a survey in the resolved placement. Shared surveys
+ * stay strictly read-only; a detached sandbox gets a preset that may write and
+ * run commands inside the disposable checkout.
+ * @param {Mission | null | undefined} [mission]
+ * @param {TowerConfig} [config]
+ * @returns {'tower-survey' | 'tower-survey-sandbox'}
+ */
+export function resolvePreset(mission, config = /** @type {TowerConfig} */ ({})) {
+  return resolveProvisioning(mission, config) === 'detached' ? 'tower-survey-sandbox' : 'tower-survey'
+}
+
+/** Shared-checkout completion invariants (the default placement). */
+const SHARED_COMPLETION = Object.freeze({
+  requiresWorktree: false,
+  requiresSandbox: false,
+  requiresCommits: false,
+  requiresClean: false,
+  requiresHeadMatch: true,
+  requiresTrackedStatus: true,
+  check: /** @type {(ctx: any) => { commits: number }} */ (checkCompletion),
+})
+
+/** Detached-sandbox completion invariants. */
+const SANDBOX_COMPLETION = Object.freeze({
+  requiresWorktree: false,
+  requiresSandbox: true,
+  requiresCommits: true,
+  requiresClean: false,
+  requiresHeadMatch: true,
+  requiresTrackedStatus: false,
+  check: /** @type {(ctx: any) => { commits: number }} */ (checkSandboxCompletion),
+})
+
+/**
+ * The completion invariants for the checkout the mission was provisioned in.
+ * Placement is read from the recorded `mission.sandbox`, never from current
+ * config: a detached sandbox still enforces its HEAD/zero-commit invariants and
+ * is removed after a config flip to `none`, and a survey that never got a
+ * sandbox keeps the shared invariants even if config now asks for `detached`.
+ * The config parameter stays in the shape contract for symmetry with other
+ * hooks, but is intentionally not consulted here.
+ * @param {Mission} mission
+ * @param {TowerConfig} [_config]
+ * @returns {typeof SHARED_COMPLETION | typeof SANDBOX_COMPLETION}
+ */
+export function resolveCompletion(mission, _config = /** @type {TowerConfig} */ ({})) {
+  return resolveProvisioning(mission) === 'detached' ? SANDBOX_COMPLETION : SHARED_COMPLETION
+}
+
+/**
+ * Completion blockers for a survey. A survey is never merged, so the build-only
+ * "closed mission owns a branch" blocker does not exist for it.
+ * @param {Mission} mission
+ * @param {TowerConfig} [config]
+ * @returns {Blocker[]}
+ */
+export function completionBlockers(mission, config = /** @type {TowerConfig} */ ({})) {
+  /** @type {Blocker[]} */
+  const blockers = []
+  if (mission.status !== 'completed') {
+    blockers.push({
+      code: 'mission-not-completed',
+      detail:
+        mission.status === 'blocked'
+          ? `mission ${mission.id} is blocked: ${(mission.blockers ?? []).join('; ')}; clear the blockers to resume it`
+          : `mission ${mission.id} is ${mission.status}; completion is required`,
+    })
+  }
+  const open = (mission.tasks ?? []).filter((task) => task.status === 'open')
+  if (open.length > 0) {
+    blockers.push({ code: 'tasks-open', detail: `${open.length} open task(s): ${open.map((task) => task.text).join('; ')}` })
+  }
+  if ((mission.blockers ?? []).length > 0) {
+    blockers.push({ code: 'blockers-present', detail: (mission.blockers ?? []).join('; ') })
+  }
+  if (config.gates?.requireChecks && !hasCheckEvidence(EVIDENCE, mission)) {
+    blockers.push({
+      code: 'no-check-evidence',
+      detail: `mission ${mission.id} has no completion checks; gates.requireChecks is enabled`,
+    })
+  }
+  return blockers
+}
+
+/**
+ * A completed survey satisfies its dependents; its read commit is part of the
+ * evidence, but the shape contract only needs the terminal status.
+ * @param {Pick<Mission, 'status'>} dep
+ * @returns {boolean}
+ */
+export function dependencySatisfied(dep) {
+  return dep.status === 'completed' || dep.status === 'abandoned'
+}
+
+/**
+ * Worker spawn constraints: a survey worker runs in the shared checkout (or,
+ * with `survey.sandbox: 'detached'`, in a disposable detached worktree) and
+ * never provisions a branch. The concrete placement/preset is resolved by
+ * `resolveProvisioning`/`resolvePreset`.
+ * @type {{ provisioning: 'shared', missionStatuses: readonly string[], worktree: false, defaultPreset: string, countsTowardWorkerBudget: boolean, model: string }}
+ */
+export const spawn = Object.freeze({
+  provisioning: /** @type {const} */ ('shared'),
+  missionStatuses: Object.freeze(['planned', 'active', 'blocked', 'paused']),
+  worktree: /** @type {const} */ (false),
+  defaultPreset: 'tower-survey',
+  countsTowardWorkerBudget: false,
+  model: 'survey',
+})
+
+/**
+ * Mission briefing lines that are specific to the survey shape. A detached
+ * sandbox is named explicitly so the worker never edits the main checkout and
+ * knows the checkout is disposable but the recorded commit is pinned.
+ * @param {Mission} mission
+ * @param {{ repoRoot: string, worktree?: unknown }} context
+ * @returns {string[]}
+ */
+export function briefing(mission, context) {
+  const short = String(mission.readCommit ?? '').slice(0, 12)
+  const fingerprint = (mission.readDirty ?? []).length
+  if (mission.sandbox) {
+    return [
+      `Read and work in the disposable detached sandbox: ${mission.sandbox} (no branch, no commit of your own; the sandbox is removed when the mission completes)`,
+      `The sandbox HEAD is pinned to ${short}. Write and shell side effects stay inside the sandbox; completion requires HEAD to still be ${short} and zero new commits.`,
+      `Pass workdir="${mission.sandbox}" on every shell command; never modify the main checkout ${context.repoRoot}.`,
+    ]
+  }
+  return [
+    `Read only: commit ${short} in the shared checkout ${context.repoRoot} (no branch, no worktree, no commits)`,
+    `Completion invariants: HEAD must still be ${short} and the tracked-status set captured at plan time (${fingerprint} path(s)) must be unchanged. Complete with zero commits.`,
+  ]
+}
+
+/**
+ * Projection of the survey-specific mission fields for summaries/board rows.
+ * @param {Mission} mission
+ * @returns {Record<string, any>}
+ */
+export function summary(mission) {
+  return {
+    worktree: null,
+    sandbox: mission.sandbox ?? null,
+    readCommit: mission.readCommit ?? null,
+    readDirty: [...(mission.readDirty ?? [])],
+    mergedCommit: null,
+    mergedAt: null,
+  }
+}
+
+/**
+ * One-line human description of where the mission reads, used by reports.
+ * @param {Mission} mission
+ * @returns {string | null}
+ */
+export function describe(mission) {
+  return mission.readCommit ? `read at ${String(mission.readCommit).slice(0, 12)}` : null
+}
+
+/**
+ * v3 -> v4 migration hook (#148). A legacy survey reads the commit its
+ * branch-shaped worktree was based on, keeps its completion report, and loses
+ * the worktree/branch/merge projection. A legacy survey that was merged becomes
+ * completed: a survey is never merged in v4.
+ * @param {Record<string, any>} mission
+ * @returns {boolean}
+ */
+export function isLegacy(mission) {
+  return mission.kind === 'survey'
+}
+
+/**
+ * The commit a legacy (v3, branch-shaped) survey recorded, in fallback order:
+ * the v4 field, the worktree it was based on, then the mission-level base
+ * commit. A survey planned and never provisioned (or whose spawn failed before
+ * provisioning) has none of the three.
+ * @param {Record<string, any>} mission
+ * @returns {string | null}
+ */
+export function legacyReadCommit(mission) {
+  const recorded = mission.readCommit ?? mission.worktree?.baseCommit ?? mission.baseCommit
+  return typeof recorded === 'string' && recorded.length > 0 ? recorded : null
+}
+
+/**
+ * True when a legacy survey has no base of its own: the state loader must
+ * resolve one from the repository before migration can anchor the survey.
+ * @param {Record<string, any>} mission
+ * @returns {boolean}
+ */
+export function needsLegacyRead(mission) {
+  return legacyReadCommit(mission) === null
+}
+
+/**
+ * @param {Record<string, any>} mission
+ * @param {{ legacySurveyRead?: { readCommit?: unknown, readDirty?: unknown } | null }} [options]
+ * @returns {Record<string, any>}
+ */
+export function migrateLegacy(mission, options = {}) {
+  const recorded = legacyReadCommit(mission)
+  // The loader resolves the state base once for the whole document; only a
+  // survey that recorded no base of its own may consume that resolution. A
+  // recorded commit always wins, so re-running the step is a fixed point.
+  const resolved = recorded === null ? options.legacySurveyRead : null
+  const readCommit = recorded ?? resolved?.readCommit
+  if (typeof readCommit !== 'string' || readCommit.length === 0) {
+    throw new Error(
+      `survey ${String(mission.id)} has no recorded base commit to read; the state loader must resolve the base ref for a planned-but-never-provisioned survey`,
+    )
+  }
+  const readDirty =
+    recorded === null
+      ? Array.isArray(resolved?.readDirty)
+        ? resolved.readDirty.filter((entry) => typeof entry === 'string')
+        : []
+      : Array.isArray(mission.readDirty)
+        ? [...mission.readDirty]
+        : []
+  const next = /** @type {Record<string, any>} */ ({
+    ...mission,
+    kind: 'survey',
+    scope: [],
+    readCommit,
+    readDirty,
+  })
+  if (next.status === 'merged') next.status = 'completed'
+  delete next.worktree
+  delete next.worktreeRemovedAt
+  delete next.sandbox
+  delete next.sandboxCleanupError
+  delete next.sandboxRemovedAt
+  delete next.branch
+  delete next.baseCommit
+  delete next.mergedCommit
+  delete next.mergedAt
+  return next
+}
+
+export const surveyShape = Object.freeze({
+  kind: /** @type {const} */ ('survey'),
+  statuses: SURVEY_STATUSES,
+  transitions: SURVEY_TRANSITIONS,
+  isTerminal,
+  canTransition,
+  isLegacy,
+  migrateLegacy,
+  needsLegacyRead,
+  canMerge: false,
+  canRebase: false,
+  provisioning: /** @type {const} */ ('shared'),
+  reach: REACH,
+  // Document dimensions this shape owns; the state validator reads these.
+  fields: Object.freeze({ worktree: false, readCommit: true, merge: false, sandbox: true }),
+  // A survey needs its optional component row; a build does not.
+  requiredComponent: 'tower-survey',
+  // Only a survey records `result` evidence on completion.
+  acceptsResult: true,
+  evidence: EVIDENCE,
+  planFields,
+  resolveProvisioning,
+  resolvePreset,
+  resolveCompletion,
+  completion: SHARED_COMPLETION,
+  completionBlockers,
+  dependencySatisfied,
+  spawn,
+  briefing,
+  summary,
+  describe,
+})

package/domain/state/archive.js

@@ -11,7 +11,8 @@
 // writing the files, and the lock that makes them atomic with state.json, live
 // in `adapters/archive.js` and `app/archive.js`.
 // @ts-check
-import { isTerminal } from '../mission.js'
+import { normalizeResult } from '../missions/completion.js'
+import { shapeFor } from '../shapes/index.js'
 
 /** @typedef {import('../../types/index.js').Finding} Finding */
 /** @typedef {import('../../types/index.js').Mission} Mission */
@@ -63,7 +64,8 @@ export function terminalTimestamp(mission) {
  * Select the terminal missions the policy wants moved out of state.json.
  *
  * Eligibility:
- *   - status is `merged` or `abandoned` (terminal);
+ *   - the mission's shape reports its status as terminal (`merged`/`abandoned`
+ *     for a build, `completed`/`abandoned` for a survey);
  *   - the worktree is gone (never provisioned, or removed by teardown);
  *   - the caller did not protect it (open batch members, live agents).
  *
@@ -85,7 +87,7 @@ export function selectForArchive(missions, policy = {}, options = {}) {
   const afterDays = Number.isFinite(policy?.afterDays) ? /** @type {number} */ (policy.afterDays) : 30
   const maxMissions = Number.isFinite(policy?.maxMissions) ? /** @type {number} */ (policy.maxMissions) : 100
   const eligible = missions.filter(
-    (mission) => isTerminal(mission.status) && !hasLiveWorktree(mission) && !protectedIds.has(mission.id),
+    (mission) => shapeFor(mission.kind).isTerminal(mission.status) && !hasLiveWorktree(mission) && !protectedIds.has(mission.id),
   )
   if (eligible.length === 0) return []
   if (options.force === true) return eligible
@@ -140,10 +142,30 @@ export function archiveYearFor(now) {
   return new Date(now).getUTCFullYear()
 }
 
+/**
+ * Keep the bounded survey evidence on the index entry. The value was already
+ * normalized when the survey completed, but re-normalizing is cheap and makes
+ * a hand-edited or legacy document safe to archive.
+ * @param {Mission} mission
+ * @returns {Record<string, any> | null}
+ */
+function boundedResult(mission) {
+  const record = /** @type {Record<string, any>} */ (mission)
+  if (record.result === undefined || record.result === null) return null
+  try {
+    return normalizeResult(record.result)
+  } catch {
+    return null
+  }
+}
+
 /**
  * The compact entry written to `archive/index.json` (and referenced by
  * `tower_status`). It carries enough fields to keep ordering, dependency
- * lookups and mission-id allocation working without loading a year file.
+ * lookups, freshness checks and mission-id allocation working without loading a
+ * year file: `readCommit` and the bounded survey `result` stay on the index so
+ * an archived survey dependency keeps its evidence and cannot fail the
+ * `gates.requireFreshSurvey` check open.
  * @param {Mission} mission
  * @param {ArchiveMeta} meta
  * @returns {Record<string, any>}
@@ -158,6 +180,8 @@ export function archiveIndexEntry(mission, meta) {
     kind: record.kind ?? 'build',
     scope: Array.isArray(record.scope) ? record.scope : [],
     deps: Array.isArray(record.deps) ? record.deps : [],
+    readCommit: record.readCommit ?? null,
+    result: boundedResult(mission),
     owner: record.owner ?? null,
     branch,
     mergedCommit: record.mergedCommit ?? null,