dsh-tower 2.5.0 → 2.7.0

package/domain/missions/plan.js

@@ -6,6 +6,7 @@
 import { TowerToolError } from '../errors.js'
 import { plannedEvents } from '../events.js'
 import { normalizeScope, validateTitle } from '../scope.js'
+import { SHAPE_KINDS, shapeFor } from '../shapes/index.js'
 
 /** @typedef {import('../../types/index.js').Mission} Mission */
 /** @typedef {import('../../types/index.js').TowerState} TowerState */
@@ -28,15 +29,30 @@ function isPlainObject(value) {
 
 /**
  * Validate and normalize one `tower_plan` mission entry.
+ *
+ * The shape owns the kind-specific plan fields: a build normalizes its scope, a
+ * survey records the commit it reads (`read.commit`, resolved by app/plan from
+ * `state.base`) plus the tracked-status fingerprint captured at the same moment.
  * @param {any} input
  * @param {number} index
+ * @param {{ commit?: string, dirty?: string[] }} [read]
  * @returns {any}
  */
-export function normalizeMissionInput(input, index) {
+export function normalizeMissionInput(input, index, read = {}) {
   if (!isPlainObject(input)) fail(`missions[${index}] must be an object`)
   const title = validateTitle(input.title)
-  const kind = input.kind === 'survey' ? 'survey' : 'build'
-  const scope = normalizeScope(input.scope ?? [], { allowEmpty: kind === 'survey' })
+  const kind = input.kind === undefined ? 'build' : input.kind
+  if (typeof kind !== 'string' || !SHAPE_KINDS.includes(kind)) {
+    fail(`missions[${index}].kind must be one of ${SHAPE_KINDS.join('|')}`)
+  }
+  const shape = shapeFor(kind)
+  /** @type {string[]} */
+  const scopeInput = input.scope ?? []
+  if (!Array.isArray(scopeInput)) fail(`missions[${index}].scope must be an array of globs`)
+  if (!shape.reach.ownsPaths && scopeInput.length > 0) {
+    fail(`missions[${index}] is a ${shape.kind}: it reads a commit and does not own a write scope`)
+  }
+  const scope = shape.reach.ownsPaths ? normalizeScope(scopeInput) : []
   /** @type {Array<{ text: string, status: string }>} */
   const tasks = []
   if (input.tasks !== undefined) {
@@ -80,19 +96,25 @@ export function normalizeMissionInput(input, index) {
   if (reviewPolicy === 'none' && reviewExemptionReason.length === 0) {
     fail(`missions[${index}].reviewPolicy "none" requires a non-empty reviewExemptionReason`)
   }
-  return { title, kind, scope, tasks, deps, context, references, reviewPolicy, reviewExemptionReason }
+  const fields = /** @type {any} */ (/** @type {any} */ (shape).planFields)({
+    scope,
+    readCommit: read.commit,
+    readDirty: read.dirty,
+  })
+  return { title, kind, ...fields, tasks, deps, context, references, reviewPolicy, reviewExemptionReason }
 }
 
 /**
  * Validate the plan envelope and normalize every mission entry.
  * @param {any} input
+ * @param {{ commit?: string, dirty?: string[] }} [read]
  * @returns {any[]}
  */
-export function normalizePlanMissions(input) {
+export function normalizePlanMissions(input, read = {}) {
   if (!Array.isArray(input.missions) || input.missions.length === 0) {
     fail('tower_plan needs at least one mission')
   }
-  return input.missions.map((mission, index) => normalizeMissionInput(mission, index))
+  return input.missions.map((mission, index) => normalizeMissionInput(mission, index, read))
 }
 
 /**
@@ -147,6 +169,8 @@ export function newMission(id, input, now) {
     scopeGeneration: 1,
     createdAt: now,
     updatedAt: now,
+    ...(input.readCommit === undefined ? {} : { readCommit: input.readCommit }),
+    ...(input.readDirty === undefined ? {} : { readDirty: input.readDirty }),
   }))
 }
 

package/domain/missions/review.js

@@ -7,6 +7,7 @@
 import { TowerToolError } from '../errors.js'
 import { reviewedEvent } from '../events.js'
 import { MERGE_VERDICTS, REVIEW_STATUS_RE } from '../mission.js'
+import { isReviewerRole } from '../roles.js'
 
 /** @typedef {import('../../types/index.js').Mission} Mission */
 /** @typedef {import('../../types/index.js').RosterEntry} RosterEntry */
@@ -47,7 +48,7 @@ export function resolveReviewActor({ mission, caller, actorRole, agentId, breakG
     return { reviewerName: 'tower', reviewerRole: 'tower' }
   }
   if (caller) {
-    if (caller.role !== 'reviewer') {
+    if (!isReviewerRole(caller.role)) {
       fail(`agent ${caller.name} is a ${caller.role}; only an assigned reviewer or the tower (break-glass) may review`)
     }
     if (caller.missionId !== mission.id) {
@@ -92,23 +93,6 @@ export function normalizeReviewVerdict(input) {
   return { status: input.status, merge: input.merge, findings, decision, checks }
 }
 
-/**
- * A reviewer may only review the tip it was spawned on.
- * @param {RosterEntry | undefined} caller
- * @param {string} tip
- * @returns {void}
- */
-export function assertReviewerSpawnTip(caller, tip) {
-  if (caller && caller.role === 'reviewer' && !String(caller.spawnTip ?? '').trim()) {
-    fail(`reviewer ${caller.name} has no recorded spawn tip; re-spawn the reviewer before reviewing`)
-  }
-  if (caller && caller.role === 'reviewer' && caller.spawnTip !== tip) {
-    fail(
-      `reviewer ${caller.name} modified the mission branch after it was spawned (${String(caller.spawnTip).slice(0, 7)} -> ${tip.slice(0, 7)}); reviewers must be read-only — spawn a fresh reviewer`,
-    )
-  }
-}
-
 /**
  * The latest review of one branch. Higher rounds win; routes that share a round
  * are ordered by submission sequence, so "latest" is the most recently recorded

package/domain/planning.js

@@ -2,7 +2,7 @@
 // @ts-check
 import { TowerToolError } from './errors.js'
 import { scopesOverlap } from './scope.js'
-import { isTerminal } from './mission.js'
+import { shapeFor } from './shapes/index.js'
 
 /** @typedef {import('../types/index.js').Mission} Mission */
 
@@ -93,7 +93,7 @@ function assertAcyclic(missions) {
  * @returns {void}
  */
 function addAutoDeps(newMissions, existingMissions, { caseInsensitive = false } = {}) {
-  const openExisting = existingMissions.filter((mission) => !isTerminal(mission.status))
+  const openExisting = existingMissions.filter((mission) => !shapeFor(mission.kind).isTerminal(mission.status))
   const all = [...existingMissions, ...newMissions]
   /** @type {Map<string, Mission>} */
   const byId = new Map(all.map((mission) => [mission.id, mission]))
@@ -102,15 +102,15 @@ function addAutoDeps(newMissions, existingMissions, { caseInsensitive = false }
     for (let j = i + 1; j < newMissions.length; j += 1) {
       const earlier = newMissions[i]
       const later = newMissions[j]
-      if (earlier.kind === 'survey' || later.kind === 'survey') continue
+      if (!shapeFor(earlier.kind).reach.ownsPaths || !shapeFor(later.kind).reach.ownsPaths) continue
       if (!scopesOverlap(earlier.scope, later.scope, { caseInsensitive })) continue
       if (hasDependencyPath(byId, later.id, earlier.id)) continue
       addDependency(later, earlier.id)
     }
     const mission = newMissions[i]
-    if (mission.kind === 'survey') continue
+    if (!shapeFor(mission.kind).reach.ownsPaths) continue
     for (const other of openExisting) {
-      if (other.kind === 'survey') continue
+      if (!shapeFor(other.kind).reach.ownsPaths) continue
       if (!scopesOverlap(mission.scope, other.scope, { caseInsensitive })) continue
       if (hasDependencyPath(byId, mission.id, other.id)) continue
       addDependency(mission, other.id)

package/domain/read/missionContext.js

@@ -10,10 +10,13 @@ import { fullMission, findingSummary } from '../summary.js'
  * @param {object} input
  * @param {TowerState} input.state
  * @param {Mission} input.mission
+ * @param {Array<Record<string, any>> | Map<string, Record<string, any>>} [input.archived] archive index entries (or a by-id map) so a dependency that has already been archived keeps its evidence
  * @returns {object}
  */
-export function missionContextView({ state, mission }) {
+export function missionContextView({ state, mission, archived = [] }) {
   const byId = new Map(state.missions.map((entry) => [entry.id, entry]))
+  const archivedById =
+    archived instanceof Map ? archived : new Map(archived.map((entry) => [entry.id, entry]))
   const branch = mission.worktree ? mission.worktree.branch : null
   const reviews = branch
     ? (state.reviews ?? [])
@@ -46,8 +49,19 @@ export function missionContextView({ state, mission }) {
     })),
     findings: findings.map((finding) => findingSummary(finding)),
     deps: (mission.deps ?? []).map((id) => {
-      const dep = byId.get(id)
-      return dep ? { id, title: dep.title, status: dep.status } : { id, title: null, status: 'unknown' }
+      const dep = byId.get(id) ?? archivedById.get(id)
+      if (!dep) return { id, title: null, status: 'unknown' }
+      return {
+        id,
+        title: dep.title,
+        kind: dep.kind,
+        status: dep.status,
+        readCommit: dep.readCommit ?? null,
+        // #148 D6: a survey's completion evidence travels with the dependency
+        // context so a dependent build worker sees what was found, not only that
+        // the survey finished. Formatting/clipping is the briefing's job.
+        result: dep.result ?? null,
+      }
     }),
   }
 }

package/domain/read/views.js

@@ -125,16 +125,20 @@ export function patchLimit(maxBytes) {
  * @param {string[]} input.files
  * @param {string[]} input.commits
  * @param {string} input.fullPatch
+ * @param {string|null} [input.reviewedCommit]
  * @param {number} [input.maxBytes]
  * @returns {object}
  */
-export function diffView({ mission, baseTip, branchTip, mergeBase, files, commits, fullPatch, maxBytes }) {
+export function diffView({ mission, baseTip, branchTip, mergeBase, files, commits, fullPatch, maxBytes, reviewedCommit = null }) {
   const limit = patchLimit(maxBytes)
   return {
     missionId: mission.id,
     branch: mission.worktree ? mission.worktree.branch : null,
     baseTip,
     branchTip,
+    // #149 W3: a reviewer sees (and is stamped with) one recorded commit; the
+    // field is null for every other caller reading the live branch.
+    reviewedCommit,
     mergeBase,
     files,
     commits,

package/domain/roles.js

@@ -0,0 +1,222 @@
+// Role vocabulary (#149). Roles are decided from one place so generic layers do
+// not compare against role strings: the shape audit refuses `role === 'worker'`
+// outside this module. `domain/vocabulary.js` re-exports these constants for the
+// public vocabulary surface; `domain/roster.js` imports them directly so the
+// roster/vocabulary cycle does not exist.
+//
+// #149 W4: a role is not a shape kind. This module owns the role contract; a
+// shape supplies facts (can it merge? does it own a worktree? which model slot?)
+// and this contract decides what a role requires, where it runs, which preset
+// row and model route it resolves, and whether it consumes a worker slot. Spawn,
+// presets, roster and gates resolve role orthogonally to shape through these
+// functions instead of combining `isReviewerRole` with `shape.*` at each site.
+export const ROLE = Object.freeze({
+  tower: 'tower',
+  worker: 'worker',
+  reviewer: 'reviewer',
+  unknown: 'unknown',
+})
+
+/** Roles a spawned child may have. */
+export const ROLES = Object.freeze([ROLE.worker, ROLE.reviewer])
+
+/** Every actor role a tool may see. */
+export const ACTOR_ROLES = Object.freeze([ROLE.tower, ROLE.worker, ROLE.reviewer, ROLE.unknown])
+
+export const DEFAULT_ROLE = ROLE.worker
+
+/** @param {unknown} role */
+export function isTowerRole(role) {
+  return role === ROLE.tower
+}
+
+/** @param {unknown} role */
+export function isWorkerRole(role) {
+  return role === ROLE.worker
+}
+
+/** @param {unknown} role */
+export function isReviewerRole(role) {
+  return role === ROLE.reviewer
+}
+
+/** @param {unknown} role */
+export function isUnknownRole(role) {
+  return role === ROLE.unknown
+}
+
+/**
+ * The one role contract. Every field is a role fact, never a shape fact:
+ *
+ *   preset: 'shape' uses the shape's resolved default preset, otherwise the
+ *           reviewer preset row; `model` names the config.spawn.<slot>Model
+ *           route (a shape supplies its own slot through shape.spawn.model);
+ *   placement: 'mission' provisions the mission placement (branch worktree,
+ *              shared checkout or detached sandbox), 'review-checkout' creates
+ *              the disposable detached review checkout;
+ * `tracksMission`/`countsTowardBudget` answer ownership and resource questions;
+ * `requires` lists what the mission must satisfy (`statuses: 'shape'` defers the
+ * status set to the shape's spawn contract).
+ * @type {Readonly<Record<string, {
+ *   preset: 'shape' | 'reviewer',
+ *   model: 'shape' | 'reviewer',
+ *   placement: 'mission' | 'review-checkout',
+ *   briefing: 'worker' | 'reviewer',
+ *   tracksMission: boolean,
+ *   countsTowardBudget: 'shape' | boolean,
+ *   spawnDiscovery: 'worktree' | 'never',
+ *   requires: { review: boolean, canMerge: boolean, worktree: boolean, statuses: 'shape' | readonly string[] },
+ * }>>}
+ */
+export const ROLE_CONTRACT = Object.freeze({
+  [ROLE.worker]: Object.freeze({
+    preset: 'shape',
+    model: 'shape',
+    placement: 'mission',
+    briefing: 'worker',
+    tracksMission: true,
+    countsTowardBudget: 'shape',
+    spawnDiscovery: 'worktree',
+    requires: Object.freeze({ review: false, canMerge: false, worktree: false, statuses: 'shape' }),
+  }),
+  [ROLE.reviewer]: Object.freeze({
+    preset: 'reviewer',
+    model: 'reviewer',
+    placement: 'review-checkout',
+    briefing: 'reviewer',
+    tracksMission: false,
+    countsTowardBudget: false,
+    spawnDiscovery: 'never',
+    requires: Object.freeze({ review: true, canMerge: true, worktree: true, statuses: Object.freeze(['completed']) }),
+  }),
+})
+
+/** @param {unknown} role */
+export function roleContract(role) {
+  return typeof role === 'string' && Object.prototype.hasOwnProperty.call(ROLE_CONTRACT, role)
+    ? ROLE_CONTRACT[role]
+    : null
+}
+
+/** @param {unknown} role */
+export function roleTracksMission(role) {
+  return roleContract(role)?.tracksMission === true
+}
+
+/** @param {unknown} role */
+export function roleBriefingKind(role) {
+  return roleContract(role)?.briefing ?? null
+}
+
+/** @param {unknown} role */
+export function rolePlacement(role) {
+  return roleContract(role)?.placement ?? null
+}
+
+/** @param {unknown} role */
+export function rolePresetSlot(role) {
+  return roleContract(role)?.preset ?? null
+}
+
+/**
+ * Which config key supplies a role's preset, and the schema fallback. A role
+ * whose `preset` is `shape` takes the shape-resolved preset when one exists and
+ * falls back to `spawn.workerPreset`; the reviewer uses its own row.
+ * @param {unknown} role
+ * @returns {{ slot: 'workerPreset' | 'reviewerPreset', fallback: string } | null}
+ */
+export function rolePresetConfig(role) {
+  const spec = roleContract(role)
+  if (!spec) return null
+  return spec.preset === 'shape'
+    ? { slot: 'workerPreset', fallback: 'tower-worker' }
+    : { slot: 'reviewerPreset', fallback: 'tower-reviewer' }
+}
+
+/**
+ * Does this role consume a worker slot for a mission of this shape?
+ * @param {unknown} role
+ * @param {{ spawn?: { countsTowardWorkerBudget?: boolean } } | null | undefined} shape
+ */
+export function roleCountsTowardBudget(role, shape) {
+  const spec = roleContract(role)
+  if (!spec) return false
+  if (spec.countsTowardBudget === 'shape') return shape?.spawn?.countsTowardWorkerBudget !== false
+  return spec.countsTowardBudget === true
+}
+
+/**
+ * Should this spawn run test discovery before activation? A worker on a shape
+ * with a worktree can; a reviewer never runs repository code.
+ * @param {unknown} role
+ * @param {{ fields?: { worktree?: boolean } } | null | undefined} shape
+ */
+export function roleSpawnDiscovery(role, shape) {
+  const spec = roleContract(role)
+  if (!spec) return false
+  return spec.spawnDiscovery === 'worktree' && shape?.fields?.worktree === true
+}
+
+/**
+ * Resolve the role-controlled spawn facts: preset, model route, placement and
+ * briefing. The shape supplies `canMerge`/`worktree`/`spawn.model`; the role
+ * decides how they are used.
+ * @param {string} role
+ * @param {{ config: any, shape: any, shapePreset?: string | null }} input
+ */
+export function resolveRoleSpawn(role, { config, shape, shapePreset = null }) {
+  const spec = roleContract(role)
+  const spawnConfig = config?.spawn ?? {}
+  if (!spec) return null
+  const preset = spec.preset === 'shape' ? (shapePreset ?? spawnConfig.workerPreset) : spawnConfig.reviewerPreset
+  const modelSlot = spec.model === 'shape' ? (shape?.spawn?.model ?? 'worker') : 'reviewer'
+  const model = spawnConfig[`${modelSlot}Model`]
+  return { preset, model, placement: spec.placement, briefing: spec.briefing }
+}
+
+/**
+ * Role prerequisites for one mission. The caller checks service-level facts
+ * (`reviewAvailable`); shape facts arrive on `shape`/`mission`. Returns
+ * blockers in the order a human would fix them; the caller throws the first.
+ * @param {string} role
+ * @param {{ shape: any, mission: any, reviewAvailable?: boolean }} input
+ * @returns {Array<{ code: string, message: string }>}
+ */
+export function roleMissionBlockers(role, { shape, mission, reviewAvailable = true }) {
+  const spec = roleContract(role)
+  if (!spec) return [{ code: 'invalid-argument', message: `role must be one of ${ROLES.join('|')}` }]
+  const blockers = []
+  if (spec.requires.review && !reviewAvailable) {
+    blockers.push({
+      code: 'review-disabled',
+      message: 'review.mode is off, so review is unavailable and a reviewer cannot be spawned',
+    })
+  }
+  if (spec.requires.canMerge && !shape?.canMerge) {
+    blockers.push({
+      code: 'invalid-transition',
+      message: `mission ${mission?.id} is a ${shape?.kind}: it has no branch to review and is never reviewed`,
+    })
+  }
+  if (spec.requires.worktree && !mission?.worktree) {
+    blockers.push({
+      code: 'reviewer-prerequisite',
+      message: 'reviewer needs an existing mission worktree; spawn a worker first',
+    })
+  }
+  const statuses = spec.requires.statuses === 'shape' ? (shape?.spawn?.missionStatuses ?? []) : spec.requires.statuses
+  if (!statuses.includes(mission?.status)) {
+    blockers.push(
+      spec.requires.statuses === 'shape'
+        ? {
+            code: 'invalid-transition',
+            message: `mission ${mission?.id} is ${mission?.status}; a ${role} can only be spawned for a planned or active mission`,
+          }
+        : {
+            code: 'reviewer-prerequisite',
+            message: `reviewer requires a completed mission; ${mission?.id} is ${mission?.status}`,
+          },
+    )
+  }
+  return blockers
+}

package/domain/roster.js

@@ -1,5 +1,7 @@
 // Pure roster predicates.
 // @ts-check
+import { isWorkerRole, roleCountsTowardBudget } from './roles.js'
+import { shapeFor } from './shapes/index.js'
 
 /** @typedef {import('../types/index.js').RosterEntry} RosterEntry */
 /** @typedef {import('../types/index.js').TowerState} TowerState */
@@ -16,7 +18,7 @@ export const ROSTER_INACTIVE = new Set(ROSTER_INACTIVE_STATES)
  */
 export function liveWorkerEntry(state, missionId) {
   return (state.roster ?? []).find(
-    (entry) => entry.missionId === missionId && entry.role === 'worker' && !ROSTER_INACTIVE.has(entry.state),
+    (entry) => entry.missionId === missionId && isWorkerRole(entry.role) && !ROSTER_INACTIVE.has(entry.state),
   )
 }
 
@@ -26,7 +28,7 @@ export function liveWorkerEntry(state, missionId) {
  * @returns {RosterEntry[]}
  */
 export function workerEntries(state, missionId) {
-  return (state.roster ?? []).filter((entry) => entry.missionId === missionId && entry.role === 'worker')
+  return (state.roster ?? []).filter((entry) => entry.missionId === missionId && isWorkerRole(entry.role))
 }
 
 /**
@@ -34,7 +36,11 @@ export function workerEntries(state, missionId) {
  * @returns {number}
  */
 export function countLiveWorkers(state) {
+  const kinds = new Map((state.missions ?? []).map((mission) => [mission.id, mission.kind]))
   return (state.roster ?? []).filter(
-    (entry) => entry.role === 'worker' && !ROSTER_INACTIVE.has(entry.state) && entry.state !== 'reserved',
+    (entry) =>
+      roleCountsTowardBudget(entry.role, shapeFor(kinds.get(entry.missionId ?? ''))) &&
+      !ROSTER_INACTIVE.has(entry.state) &&
+      entry.state !== 'reserved',
   ).length
 }

package/domain/scope.js

@@ -85,6 +85,57 @@ export function comparisonMode(caseInsensitive) {
   return caseInsensitive === true ? 'case-insensitive' : 'case-sensitive'
 }
 
+/** @typedef {{ code: string, detail: string }} ScopeBlocker */
+/** @typedef {{ ownsPaths: boolean, fence: 'scope' | 'read-only' }} Reach */
+
+/**
+ * The one path-permission fence (#149 W4). A shape's `reach` is the single
+ * definition of whether a mission may change paths at all:
+ *
+ *   - `ownsPaths: true` + `fence: 'scope'`: every changed file must match the
+ *     mission scope (case folding is a checkout fact, not a scope rewrite);
+ *   - anything else (`fence: 'read-only'`): the mission permits no file change,
+ *     so any changed path is a fence violation.
+ *
+ * The merge gate, the planning/lifecycle rules and the spawn briefing derive
+ * from the same declaration; none of them re-reads `mission.scope` to decide
+ * permission on its own.
+ *
+ * @param {{ mission: { id?: string, scope?: string[] | null }, reach: Reach | null | undefined, changedFiles?: string[], caseInsensitive?: boolean }} input
+ * @returns {ScopeBlocker | null}
+ */
+export function scopeFenceBlocker({ mission, reach, changedFiles = [], caseInsensitive = false }) {
+  const files = Array.isArray(changedFiles) ? changedFiles : []
+  const ownsPaths = reach?.ownsPaths === true && reach?.fence !== 'read-only'
+  if (!ownsPaths) {
+    if (files.length === 0) return null
+    return {
+      code: 'out-of-scope',
+      detail: `mission ${mission?.id ?? '(unknown)'} is read-only and changed ${files.length} tracked path(s): ${files.slice(0, 8).join(', ')}`,
+    }
+  }
+  const scope = mission?.scope ?? []
+  const outOfScope = files.filter((file) => !fileInScope(scope, file, { caseInsensitive }))
+  if (outOfScope.length === 0) return null
+  const parts = [`changed files outside scope (${scope.join(', ')}): ${outOfScope.slice(0, 8).join(', ')}`]
+  // On a case-sensitive checkout a case-only mismatch is a human error worth
+  // naming, but it stays a rejection: folding here would make src/Api and
+  // src/api the same directory on a filesystem where they are not (#90).
+  if (!caseInsensitive) {
+    const hints = outOfScope
+      .map((file) => {
+        const pattern = caseInsensitiveScopeMatch(scope, file)
+        return pattern
+          ? `${file} matches "${pattern}" only when case is folded; this checkout is case-sensitive`
+          : null
+      })
+      .filter(Boolean)
+      .slice(0, 3)
+    if (hints.length > 0) parts.push(`case mismatch: ${hints.join('; ')}`)
+  }
+  return { code: 'out-of-scope', detail: parts.join('. ') }
+}
+
 // Mission titles are printable Unicode, not printable ASCII (#88). The hazards
 // the old ASCII range stood in for are made explicit: control/format/surrogate
 // code points, bidi overrides, zero-width characters, and unbounded length.