dsh-tower 2.5.0 → 2.7.0

package/domain/integration/review.js

@@ -1,11 +1,197 @@
-// Pure review-selection and exemption decisions shared by the merge/gate/read
-// projections. No repository I/O.
+// Pure review-selection, review-policy resolution and exemption decisions
+// shared by the merge/gate/read projections and the config layer. No repository
+// I/O and no process state.
+//
+// REVIEW POLICY (#M39)
+// --------------------
+// `review.mode` is the single policy with exactly three independent values:
+//
+//   off       review is intentionally unavailable: recording a review is
+//             refused, `tower_spawn` refuses the reviewer role, and the merge
+//             gate ignores review blockers. Registration is profile-time: a
+//             profile-level off does not mount `tower_review`, while a
+//             repository-level off over a profile that mounted it refuses the
+//             submission with `review-disabled`;
+//   optional  review is available but never blocks a merge (the default, and the
+//             2.0.3+ behavior of `review.requireReview:false`);
+//   required  a clean review bound to the branch tip is a merge blocker (the
+//             old `review.requireReview:true` behavior).
+//
+// `review.requireReview` stays accepted for one release as a normalized alias:
+// true -> required, false -> optional. Precedence for one raw config object is
+// deterministic:
+//
+//   * only the alias set: the alias decides;
+//   * only the mode set: the mode decides;
+//   * both set: an alias of `true` next to any mode other than `required` is a
+//     contradiction and is rejected naming both keys. An alias of `false` stays
+//     compatible with `off` because both mean "not required by merge" and the
+//     mode is the more specific policy. That asymmetry is also what keeps the
+//     resolver idempotent: it materializes the alias from the mode it resolved,
+//     and `required` is the only mode that mirrors back to `true`.
 // @ts-check
+import { TowerToolError } from '../errors.js'
 
 /** @typedef {import('../../types/index.js').Mission} Mission */
 /** @typedef {import('../../types/index.js').Review} Review */
 /** @typedef {import('../../types/index.js').TowerConfig} TowerConfig */
 
+export const REVIEW_MODES = Object.freeze(['off', 'optional', 'required'])
+export const DEFAULT_REVIEW_MODE = 'optional'
+
+// Cordis materializes a `.volatile()` schema field as a live reference object
+// (`{ get() }` plus a non-enumerable `Symbol.for('cosmokit.volatile.write')`).
+// Settings forms hand the runtime these references, not plain values, so every
+// consumer below unwraps them before validating or comparing. Keeping the
+// helpers here (instead of a new config module) lets the schema import them
+// without a cycle: review.js has no dependency on schema.js.
+const VOLATILE_WRITE = Symbol.for('cosmokit.volatile.write')
+
+/**
+ * True for the live reference Cordis/Schemastery creates for a volatile field.
+ * @param {unknown} value
+ * @returns {value is { get: () => unknown }}
+ */
+export function isVolatileRef(value) {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    typeof /** @type {{ get?: unknown }} */ (value).get === 'function' &&
+    Object.getOwnPropertySymbols(value).includes(VOLATILE_WRITE)
+  )
+}
+
+/**
+ * Read a volatile reference once; other values pass through unchanged.
+ * @template T
+ * @param {T | { get: () => T }} value
+ * @returns {T}
+ */
+export function unwrapVolatile(value) {
+  return /** @type {any} */ (isVolatileRef(value) ? value.get() : value)
+}
+
+/**
+ * Deep-copy a raw config object, replacing every volatile reference with its
+ * current value. Non-plain objects (for example a class instance) are returned
+ * as-is; Tower config is JSON-shaped plain data.
+ * @param {unknown} value
+ * @returns {any}
+ */
+export function materializeVolatile(value) {
+  const plain = unwrapVolatile(value)
+  if (Array.isArray(plain)) return plain.map((entry) => materializeVolatile(entry))
+  if (plain === null || typeof plain !== 'object') return plain
+  const proto = Object.getPrototypeOf(plain)
+  if (proto !== Object.prototype && proto !== null) return plain
+  /** @type {Record<string, unknown>} */
+  const copy = {}
+  for (const [key, entry] of Object.entries(plain)) copy[key] = materializeVolatile(entry)
+  return copy
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is 'off' | 'optional' | 'required'}
+ */
+export function isReviewMode(value) {
+  return typeof value === 'string' && REVIEW_MODES.includes(value)
+}
+
+/**
+ * The mode the deprecated boolean alias means.
+ * @param {boolean} requireReview
+ */
+export function legacyReviewMode(requireReview) {
+  return requireReview === true ? 'required' : DEFAULT_REVIEW_MODE
+}
+
+/**
+ * The resolved mode for any config object the runtime may hold: a resolved
+ * config, a raw profile/repo layer, or a hand-built test fixture. An explicit
+ * `mode` always wins; otherwise the deprecated alias decides; otherwise the
+ * documented default applies.
+ * @param {{ review?: any } | null | undefined} [config]
+ * @returns {'off' | 'optional' | 'required'}
+ */
+export function reviewModeOf(config) {
+  const review = config?.review ?? {}
+  const mode = unwrapVolatile(review.mode)
+  if (isReviewMode(mode)) return mode
+  const alias = unwrapVolatile(review.requireReview)
+  if (typeof alias === 'boolean') return legacyReviewMode(alias)
+  return DEFAULT_REVIEW_MODE
+}
+
+/**
+ * The review gate is enforced only in `required`. `off` and `optional` both
+ * ignore review at the merge gate; they differ in availability, not strictness.
+ * @param {{ review?: any } | null | undefined} [config]
+ */
+export function reviewRequired(config) {
+  return reviewModeOf(config) === 'required'
+}
+
+/**
+ * True when review is intentionally switched off (`tower_review` absent,
+ * reviewer spawn refused, merge gate ignores review).
+ * @param {{ review?: any } | null | undefined} [config]
+ */
+export function reviewUnavailable(config) {
+  return reviewModeOf(config) === 'off'
+}
+
+/**
+ * Resolve one raw `review` object (a profile, a repository layer, or a single
+ * written config) into its mode. Rejects contradictory explicit values and an
+ * unknown mode with an actionable `config-invalid` error.
+ *
+ * @param {any} rawReview
+ * @returns {{ mode: 'off' | 'optional' | 'required', explicit: boolean, legacy: boolean }}
+ */
+export function resolveReviewPolicy(rawReview) {
+  const review = rawReview && typeof rawReview === 'object' && !Array.isArray(rawReview) ? rawReview : {}
+  const mode = unwrapVolatile(review.mode)
+  const alias = unwrapVolatile(review.requireReview)
+  if (mode !== undefined && !isReviewMode(mode)) {
+    throw new TowerToolError(
+      'config-invalid',
+      `review.mode must be one of ${REVIEW_MODES.join('|')}, got ${JSON.stringify(mode)}`,
+    )
+  }
+  if (alias !== undefined && typeof alias !== 'boolean') {
+    throw new TowerToolError(
+      'config-invalid',
+      'review.requireReview must be a boolean (deprecated alias: true -> required, false -> optional)',
+    )
+  }
+  if (mode !== undefined && alias === true && mode !== 'required') {
+    throw new TowerToolError(
+      'config-invalid',
+      `review.mode is ${JSON.stringify(mode)} but review.requireReview is true; set only review.mode (off|optional|required) — review.requireReview is a deprecated alias (true -> required, false -> optional) and may not contradict it`,
+    )
+  }
+  if (mode !== undefined) return { mode, explicit: true, legacy: alias !== undefined }
+  if (alias !== undefined) return { mode: legacyReviewMode(alias), explicit: true, legacy: true }
+  return { mode: DEFAULT_REVIEW_MODE, explicit: false, legacy: false }
+}
+
+/**
+ * The small read-only projection reported by `tower_status` and the doctor's
+ * `review` check. `detail` is the one sentence both surfaces share.
+ * @param {{ review?: any } | null | undefined} [config]
+ */
+export function reviewPolicyView(config) {
+  const mode = reviewModeOf(config)
+  const detail =
+    mode === 'off'
+      ? 'review.mode:off — review is intentionally unavailable: recording a review is refused, reviewer spawn is refused, and the merge gate ignores review; a profile-level off does not register tower_review'
+      : mode === 'required'
+        ? 'review.mode:required — a clean review bound to the branch tip is a merge blocker'
+        : 'review.mode:optional — review is available but never blocks a merge'
+  return { mode, available: mode !== 'off', required: mode === 'required', detail }
+}
+
 /**
  * Reviews are branch-scoped; a missing branch has no reviews.
  * @param {Review[] | null | undefined} reviews
@@ -26,27 +212,35 @@ export function latestReview(reviews) {
 }
 
 /**
- * A mission may skip review only with both the exemption gate and a reason.
+ * A mission skips the review gate unless `review.mode` is `required`. In
+ * `required`, it may still skip with both the exemption gate and a reason.
+ * `off` and `optional` both bypass the gate; they differ only in whether the
+ * review tools/spawn role exist.
  * @param {Mission} mission
  * @param {TowerConfig} [config]
  * @returns {boolean}
  */
 export function isReviewExempt(mission, config = {}) {
+  if (!reviewRequired(config)) return true
   return (
-    config.review?.requireReview === false ||
-    (mission.reviewPolicy === 'none' &&
-      config.gates?.allowReviewExemption === true &&
-      String(mission.reviewExemptionReason ?? '').trim().length > 0)
+    mission.reviewPolicy === 'none' &&
+    config.gates?.allowReviewExemption === true &&
+    String(mission.reviewExemptionReason ?? '').trim().length > 0
   )
 }
 
 /**
  * `reviewPolicy: none` is invalid when the reviewer gate does not allow it.
+ * Only `review.mode:required` can make the request invalid; with review off or
+ * optional no review blocker is produced at all.
  * @param {Mission} mission
  * @param {TowerConfig} [config]
  * @returns {boolean}
  */
 export function reviewExemptionInvalid(mission, config = {}) {
-  const requireReview = config.review?.requireReview !== false
-  return requireReview && mission.reviewPolicy === 'none' && config.gates?.allowReviewExemption !== true
+  return (
+    reviewRequired(config) &&
+    mission.reviewPolicy === 'none' &&
+    config.gates?.allowReviewExemption !== true
+  )
 }

package/domain/mission.js

@@ -1,4 +1,8 @@
-// Pure mission vocabulary and transition rules (#49). No fs, git, or config.
+// Pure mission vocabulary (#49). No fs, git, or config.
+//
+// Per-kind status policy lives in `./shapes/` (#149): this module keeps only the
+// vocabulary every kind shares. `isTerminal(kind, status)` and
+// `canTransition(kind, from, to)` are exported from `./shapes/index.js`.
 // @ts-check
 
 /** @typedef {import('../types/index.js').FindingSeverity} FindingSeverity */
@@ -7,9 +11,17 @@
 /** @typedef {import('../types/index.js').MergeVerdict} MergeVerdict */
 /** @typedef {import('../types/index.js').MissionStatus} MissionStatus */
 
-/** @type {readonly MissionStatus[]} */
-export const MISSION_STATUSES = ['planned', 'active', 'completed', 'blocked', 'paused', 'merged', 'abandoned']
-export const SCHEMA_VERSION = 3
+import { SHAPE_KINDS, shapeFor } from './shapes/index.js'
+
+/**
+ * The union of every shape's status vocabulary, in registry order. A build
+ * mission can be `merged`; a survey cannot, but the union names the word.
+ * @type {readonly MissionStatus[]}
+ */
+export const MISSION_STATUSES = /** @type {import('../types/index.js').MissionStatus[]} */ (
+  [...new Set(SHAPE_KINDS.flatMap((kind) => shapeFor(kind).statuses))]
+)
+export const SCHEMA_VERSION = 5
 /** @type {readonly MergeVerdict[]} */
 export const MERGE_VERDICTS = ['merge', 'fix-then-merge', 'hold']
 // #115: the review status vocabulary is one runtime source. The validator
@@ -24,8 +36,6 @@ export const REVIEW_STATUSES = [
   ...REVIEW_STATUS_PRIORITIES.flatMap((priority) => REVIEW_STATUS_ITEMS.map((count) => `${priority}-${count}items`)),
 ]
 export const REVIEW_STATUS_RE = new RegExp(`^(?:clean|(?:${REVIEW_STATUS_PRIORITIES.join('|')})-\\d+items)$`)
-/** @type {ReadonlySet<string>} */
-export const TERMINAL_STATUSES = new Set(['merged', 'abandoned'])
 /** @type {readonly FindingType[]} */
 export const FINDING_TYPES = ['bug', 'improve', 'vuln', 'idea']
 /** @type {readonly FindingSeverity[]} */
@@ -41,33 +51,6 @@ export const FINDING_TRANSITIONS = {
 }
 /** @type {readonly string[]} */
 export const PAUSE_CAUSES = ['user', 'failure', 'resource', 'dependency']
-/** @type {Record<string, readonly string[] | undefined>} */
-export const TRANSITIONS = {
-  planned: ['active', 'abandoned'],
-  active: ['completed', 'blocked', 'paused', 'abandoned'],
-  blocked: ['active', 'paused', 'completed', 'abandoned'],
-  paused: ['active', 'abandoned'],
-  completed: ['active', 'abandoned'],
-  merged: [],
-  abandoned: [],
-}
-
-/**
- * @param {string} status
- * @returns {boolean}
- */
-export function isTerminal(status) {
-  return TERMINAL_STATUSES.has(status)
-}
-
-/**
- * @param {string} from
- * @param {string} to
- * @returns {boolean}
- */
-export function canTransition(from, to) {
-  return (TRANSITIONS[from] ?? []).includes(to)
-}
 
 /**
  * @param {string | null | undefined} [value]

package/domain/missions/completion.js

@@ -5,6 +5,8 @@
 // @ts-check
 import { TowerToolError } from '../errors.js'
 import { completedEvent } from '../events.js'
+import { shapeFor } from '../shapes/index.js'
+import { isWorkerRole } from '../vocabulary.js'
 
 /** @typedef {import('../../types/index.js').Mission} Mission */
 /** @typedef {import('../../types/index.js').RosterEntry} RosterEntry */
@@ -113,7 +115,7 @@ export function assertCompletionRequest({ mission, roster, input, maxReportBytes
   if (!worker || worker.missionId !== mission.id) {
     fail(`agent ${input.agentId} is not assigned to mission ${mission.id}`)
   }
-  if (worker.role !== 'worker') fail(`agent ${worker.name} is a ${worker.role}, not a worker`)
+  if (!isWorkerRole(worker.role)) fail(`agent ${worker.name} is a ${worker.role}, not a worker`)
   if (['retired', 'failed', 'interrupted', 'missing', 'stale'].includes(worker.state)) {
     fail(`agent ${worker.name} is ${worker.state}; a stopped worker cannot report completion`)
   }
@@ -121,6 +123,12 @@ export function assertCompletionRequest({ mission, roster, input, maxReportBytes
     fail(`agent ${worker.name} is not the current owner of mission ${mission.id} (owner: ${mission.owner})`)
   }
   if (mission.status === 'completed') fail(`mission ${mission.id} is already completed`)
+  // `blocked` is derived from open blockers, so name them instead of a generic
+  // status error: clearing them is the one recovery path (#149 W3).
+  const blockers = mission.blockers ?? []
+  if (blockers.length > 0) {
+    fail(`mission ${mission.id} has unresolved blockers: ${blockers.join('; ')}; clear the blockers to resume it`)
+  }
   if (!['active', 'planned'].includes(mission.status)) {
     fail(`mission ${mission.id} is ${mission.status}; it cannot be completed from that state`)
   }
@@ -136,11 +144,6 @@ export function assertCompletionRequest({ mission, roster, input, maxReportBytes
         .join('; ')}`,
     )
   }
-  const blockers = mission.blockers ?? []
-  if (blockers.length > 0) {
-    fail(`mission ${mission.id} has unresolved blockers: ${blockers.join('; ')}`)
-  }
-  if (!mission.worktree) fail(`mission ${mission.id} has no worktree`)
   return worker
 }
 
@@ -167,13 +170,48 @@ export function completionReport({ report, worker, checks, now, maxReportBytes }
   return { report: text, reportBytes: assertReportSize(text, maxReportBytes), by: worker.name, at: now, checks }
 }
 
+/**
+ * Normalize the optional survey result (#148 D6). Only a shape that accepts a
+ * result may carry one; the value stays small so the state document does not
+ * become an evidence dump.
+ * @param {unknown} result
+ * @returns {any}
+ */
+export function normalizeResult(result) {
+  if (result === undefined || result === null) return null
+  if (!isPlainObject(result)) fail('result must be an object')
+  const value = /** @type {Record<string, any>} */ (result)
+  /** @type {Record<string, any>} */
+  const normalized = {}
+  for (const key of ['paths', 'symbols', 'plan']) {
+    if (value[key] === undefined) continue
+    if (!Array.isArray(value[key])) fail(`result.${key} must be an array of strings`)
+    if (value[key].length > 200) fail(`result.${key} supports at most 200 entries`)
+    normalized[key] = value[key].map((entry) => {
+      if (typeof entry !== 'string' || entry.trim().length === 0) fail(`result.${key} entries must be non-empty strings`)
+      return entry.trim()
+    })
+  }
+  if (value.notes !== undefined) {
+    if (typeof value.notes !== 'string') fail('result.notes must be a string')
+    normalized.notes = value.notes.trim().slice(0, 4000)
+  }
+  return normalized
+}
+
 /**
  * Apply the completion transition to the mission draft and describe the domain
  * fact. Persistence stays in app/checkCompletion.js.
- * @param {{ mission: Mission, report: any, now: number }} params
+ * @param {{ mission: Mission, report: any, now: number, result?: any }} params
  * @returns {{ state: Mission, events: Array<{ type: string, missionId: string }> }}
  */
-export function applyCompletion({ mission, report, now }) {
+export function applyCompletion({ mission, report, now, result }) {
+  const shape = shapeFor(mission.kind)
+  const normalized = normalizeResult(result)
+  if (normalized !== null) {
+    if (!shape.acceptsResult) fail(`mission ${mission.id} is a ${shape.kind}; a completion result is survey evidence only`)
+    mission.result = normalized
+  }
   mission.status = 'completed'
   mission.completionReport = report
   mission.updatedAt = now

package/domain/missions/findings.js

@@ -5,6 +5,7 @@
 // @ts-check
 import { TowerToolError } from '../errors.js'
 import { FINDING_SEVERITIES, FINDING_STATUSES, FINDING_TRANSITIONS, FINDING_TYPES } from '../mission.js'
+import { isReviewerRole } from '../roles.js'
 import { countFindings, findingSummary } from '../summary.js'
 
 /** @typedef {import('../../types/index.js').Finding} Finding */
@@ -158,7 +159,7 @@ export function readFindingsView(findings, input) {
  * @returns {{ noteAdded: boolean }}
  */
 export function applyFindingUpdate({ finding, input, actor, now }) {
-  if (actor.role === 'reviewer') {
+  if (isReviewerRole(actor.role)) {
     fail('reviewers may list and read findings, but only the tower or a worker may change finding status', 'not-authorized')
   }
   let noteAdded = false

package/domain/missions/lifecycle.js

@@ -6,14 +6,14 @@
 // @ts-check
 import { TowerToolError } from '../errors.js'
 import { abandonedEvent, completedEvent } from '../events.js'
-import { MISSION_STATUSES, TERMINAL_STATUSES, canTransition, pauseCauseError } from '../mission.js'
+import { pauseCauseError } from '../mission.js'
 import { normalizeScope, scopesOverlap } from '../scope.js'
+import { shapeFor } from '../shapes/index.js'
+import { isReviewerRole, isWorkerRole } from '../vocabulary.js'
 
 /** @typedef {import('../../types/index.js').Mission} Mission */
 /** @typedef {import('../../types/index.js').TowerState} TowerState */
 
-const TERMINAL = TERMINAL_STATUSES
-
 /**
  * @param {string} message
  * @param {string} [code]
@@ -42,8 +42,8 @@ export function normalizePauseCause(value) {
  * @returns {void}
  */
 export function assertMissionActor(mission, actor, input) {
-  const workerRequest = actor.role === 'worker'
-  if (actor.role === 'reviewer') {
+  const workerRequest = isWorkerRole(actor.role)
+  if (isReviewerRole(actor.role)) {
     fail('only the tower or a worker may update a mission; reviewers submit tower_review', 'not-authorized')
   }
   if (workerRequest && mission.owner && mission.owner !== actor.name) {
@@ -61,6 +61,48 @@ export function assertMissionActor(mission, actor, input) {
   }
 }
 
+/**
+ * Mark a mission blocked from a machine-derived failure (a merge or rebase
+ * conflict). `blocked` is derived from open blockers, so the blocker is recorded
+ * with the status in one write path; no caller assigns the status directly
+ * (#149 W3). Repeating the same failure does not duplicate the blocker.
+ * @param {Mission} mission
+ * @param {string} blocker
+ * @param {number} [now]
+ * @returns {Mission}
+ */
+export function markBlocked(mission, blocker, now = Date.now()) {
+  if (typeof blocker !== 'string' || blocker.trim().length === 0) fail('a blocker must be a non-empty string')
+  const text = blocker.trim()
+  const blockers = /** @type {string[]} */ (mission.blockers)
+  if (!blockers.includes(text)) blockers.push(text)
+  mission.status = 'blocked'
+  // A blocker wins over a pause: the human cause is superseded by the failure.
+  delete mission.pauseCause
+  mission.updatedAt = now
+  return mission
+}
+
+/**
+ * Resolve blockers that a successful machine operation has cleared (a rebase
+ * conflict that the retried rebase resolved). Blockers that do not match stay,
+ * and the mission stays blocked while any remain — recovery is always "the
+ * recorded blockers are gone", never a status assignment.
+ * @param {Mission} mission
+ * @param {(blocker: string) => boolean} matches
+ * @param {number} [now]
+ * @returns {boolean} whether any blocker was removed
+ */
+export function resolveBlockers(mission, matches, now = Date.now()) {
+  const blockers = /** @type {string[]} */ (mission.blockers ?? [])
+  const kept = blockers.filter((blocker) => !matches(blocker))
+  if (kept.length === blockers.length) return false
+  mission.blockers = kept
+  if (kept.length === 0 && mission.status === 'blocked') mission.status = 'active'
+  mission.updatedAt = now
+  return true
+}
+
 /**
  * Apply one validated `tower_mission` patch to the mission draft and return
  * the human-readable change list used by the activity log plus the domain
@@ -82,34 +124,80 @@ export function applyMissionUpdate({ mission, state, input, config }) {
   /** @type {Array<{ type: string, missionId: string }>} */
   const events = []
 
+  const shape = shapeFor(mission.kind)
+  // W3: `blocked` is derived state, `paused` is a deliberate stop. Clearing the
+  // blockers is what resumes a blocked mission, so it is applied before any
+  // status patch: `{clear_blockers:true,status:"active"}` and
+  // `{clear_blockers:true,status:"completed"}` both describe one coherent step.
+  if (input.clear_blockers === true) {
+    if ((mission.blockers ?? []).length > 0) {
+      mission.blockers = []
+      changes.push('blockers cleared')
+    }
+    if (mission.status === 'blocked') {
+      mission.status = 'active'
+      changes.push('status=active (blocked until the blockers were cleared)')
+    }
+  }
   if (input.status !== undefined) {
-    if (typeof input.status !== 'string' || !MISSION_STATUSES.includes(input.status)) {
-      fail(`unknown mission status "${input.status}"`)
+    if (typeof input.status !== 'string' || !shape.statuses.includes(input.status)) {
+      fail(`unknown mission status "${input.status}" for a ${shape.kind} mission`)
     }
     if (input.status === 'merged') {
       fail('merged is recorded only by tower_merge, not by a generic mission patch', 'invalid-transition')
     }
-    if (!canTransition(mission.status, input.status)) {
-      fail(`mission ${mission.id} cannot move from ${mission.status} to ${input.status}`, 'invalid-transition')
+    if (input.status === 'blocked') {
+      fail(
+        'blocked is derived from open blockers: record blocker:"..." instead of setting status "blocked"',
+        'invalid-transition',
+      )
     }
-    if (input.status === 'paused') {
-      mission.pauseCause = normalizePauseCause(input.pause_cause)
+    const openBlockers = mission.blockers ?? []
+    if (mission.status === 'blocked' && input.status !== 'abandoned') {
+      // A blocked mission is resumed by clearing its blockers, never by a
+      // status patch that skips the blocker record (#149 W3).
+      fail(
+        `mission ${mission.id} is blocked (${openBlockers.join('; ')}); clear_blockers resumes it — it cannot move to ${input.status} directly`,
+        'invalid-transition',
+      )
     }
-    if (mission.status === 'paused' && input.status === 'active') {
-      const requireAuthorization = config.mode.requireResumeAuthorization === true
-      if (requireAuthorization && (mission.pauseCause ?? 'user') === 'user') {
-        if (typeof input.authorization !== 'string' || input.authorization.trim().length === 0) {
-          fail('resuming a user-paused mission requires a non-empty authorization reference')
-        }
+    if (openBlockers.length > 0 && ['active', 'completed', 'paused'].includes(input.status)) {
+      fail(
+        `mission ${mission.id} has open blockers (${openBlockers.join('; ')}); clear_blockers resumes it — do not move it to ${input.status}`,
+        'invalid-transition',
+      )
+    }
+    // A status patch is a real move: the target must differ and be a legal edge.
+    // `paused` is re-entered only from a different status (a pause cause is
+    // meaningful when the pause begins, not as an in-place metadata edit).
+    // `{clear_blockers:true,status:"active"}` is one coherent resume step: the
+    // clear already moved the mission, so the redundant patch is not a second
+    // transition.
+    const redundantResume =
+      input.clear_blockers === true && input.status === 'active' && mission.status === 'active'
+    if (!redundantResume) {
+      if (!shape.canTransition(mission.status, input.status)) {
+        fail(`mission ${mission.id} cannot move from ${mission.status} to ${input.status}`, 'invalid-transition')
       }
-      if (typeof input.authorization === 'string' && input.authorization.trim()) {
-        mission.authorizationRef = input.authorization.trim()
+      if (input.status === 'paused') {
+        mission.pauseCause = normalizePauseCause(input.pause_cause)
       }
+      if (mission.status === 'paused' && input.status === 'active') {
+        const requireAuthorization = config.mode.requireResumeAuthorization === true
+        if (requireAuthorization && (mission.pauseCause ?? 'user') === 'user') {
+          if (typeof input.authorization !== 'string' || input.authorization.trim().length === 0) {
+            fail('resuming a user-paused mission requires a non-empty authorization reference')
+          }
+        }
+        if (typeof input.authorization === 'string' && input.authorization.trim()) {
+          mission.authorizationRef = input.authorization.trim()
+        }
+      }
+      mission.status = input.status
+      changes.push(`status=${input.status}`)
+      if (input.status === 'completed') events.push(completedEvent(mission))
+      if (input.status === 'abandoned') events.push(abandonedEvent(mission))
     }
-    mission.status = input.status
-    changes.push(`status=${input.status}`)
-    if (input.status === 'completed') events.push(completedEvent(mission))
-    if (input.status === 'abandoned') events.push(abandonedEvent(mission))
   }
 
   if (input.task_done !== undefined) {
@@ -144,20 +232,23 @@ export function applyMissionUpdate({ mission, state, input, config }) {
     if (typeof input.blocker !== 'string' || input.blocker.trim().length === 0) {
       fail('blocker must be a non-empty string')
     }
-    if (TERMINAL.has(mission.status)) {
+    if (shape.isTerminal(mission.status)) {
       fail(`mission ${mission.id} is ${mission.status}; a blocker cannot reopen a terminal mission`)
     }
     const blockers = /** @type {string[]} */ (mission.blockers)
     blockers.push(input.blocker.trim())
-    mission.status = 'blocked'
+    // W3: a blocker always wins over a pause; the paused cause is superseded and
+    // the mission is blocked until the blockers are cleared.
+    if (mission.status !== 'blocked') {
+      if (!shape.canTransition(mission.status, 'blocked')) {
+        fail(`mission ${mission.id} cannot move from ${mission.status} to blocked`, 'invalid-transition')
+      }
+      if (mission.status === 'paused') delete mission.pauseCause
+      mission.status = 'blocked'
+    }
     changes.push('blocker added')
   }
 
-  if (input.clear_blockers === true) {
-    mission.blockers = []
-    changes.push('blockers cleared')
-  }
-
   if (input.note !== undefined) {
     if (typeof input.note !== 'string' || input.note.trim().length === 0) {
       fail('note must be a non-empty string')
@@ -168,16 +259,21 @@ export function applyMissionUpdate({ mission, state, input, config }) {
   }
 
   if (input.scope !== undefined) {
+    if (!shape.reach.ownsPaths) {
+      fail(`mission ${mission.id} is a ${shape.kind}: it reads a commit and does not own scope`)
+    }
     if (!['active', 'completed'].includes(mission.status)) {
       fail(`scope can only be widened for active or completed missions, not ${mission.status}`)
     }
-    const scope = normalizeScope(input.scope, { allowEmpty: mission.kind === 'survey' })
-    const others = state.missions.filter(
-      (entry) => entry.id !== mission.id && !TERMINAL.has(entry.status) && entry.kind !== 'survey',
-    )
+    const scope = normalizeScope(input.scope)
+    const others = state.missions.filter((entry) => {
+      if (entry.id === mission.id) return false
+      const other = shapeFor(entry.kind)
+      return other.reach.ownsPaths && !other.isTerminal(entry.status)
+    })
     const caseInsensitive = state.caseInsensitive === true
     for (const other of others) {
-      if (mission.kind !== 'survey' && scopesOverlap(scope, other.scope, { caseInsensitive })) {
+      if (scopesOverlap(scope, other.scope, { caseInsensitive })) {
         fail(`widened scope overlaps mission ${other.id}; retire it or add an explicit ordering`)
       }
     }