dsh-tower 2.6.0 → 2.7.0

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.

package/domain/shapes/build.js

@@ -0,0 +1,254 @@
+// The build shape (#148/#149): a mission that owns a private branch and
+// worktree, writes code, and terminates by being merged or abandoned.
+//
+// This module is the *only* place build-specific policy lives. Generic layers
+// resolve a shape through `./index.js` and never compare `mission.kind`.
+// @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 BUILD_STATUSES = Object.freeze(['planned', 'active', 'completed', 'blocked', 'paused', 'merged', 'abandoned'])
+
+/**
+ * The evidence this shape accepts (#149 W4). A build's discovery receipt is
+ * evidence only for the tip it ran on; a completion check is the caller's
+ * assertion. Both are read through `domain/evidence.js`, never here.
+ * @type {import('../evidence.js').EvidenceContract}
+ */
+export const EVIDENCE = Object.freeze({
+  completionChecks: true,
+  testReceipts: /** @type {const} */ ('tip-bound'),
+})
+
+/**
+ * The build shape's path reach (#149 W4): a build owns the scope it declared,
+ * so every changed path must match it. This is the only place the permission
+ * question is answered; gates and lifecycle rules call domain/scope.js with it.
+ * @type {{ ownsPaths: boolean, fence: 'scope' | 'read-only' }}
+ */
+export const REACH = Object.freeze({
+  ownsPaths: true,
+  fence: /** @type {const} */ ('scope'),
+})
+
+/** @type {Readonly<Record<string, readonly string[]>>} */
+export const BUILD_TRANSITIONS = Object.freeze({
+  planned: Object.freeze(['active', 'blocked', 'abandoned']),
+  active: Object.freeze(['completed', 'blocked', 'paused', 'abandoned']),
+  // `blocked` is derived from open blockers (W3): a blocked mission resumes
+  // only by clearing them, never by pausing or completing through the state.
+  blocked: Object.freeze(['active', 'abandoned']),
+  // A blocker always wins over a pause, which is why paused -> blocked exists.
+  paused: Object.freeze(['active', 'blocked', 'abandoned']),
+  completed: Object.freeze(['active', 'blocked', 'abandoned']),
+  merged: Object.freeze([]),
+  abandoned: Object.freeze([]),
+})
+
+/**
+ * @param {string} status
+ * @returns {boolean}
+ */
+export function isTerminal(status) {
+  return status === 'merged' || status === 'abandoned'
+}
+
+/**
+ * @param {string} from
+ * @param {string} to
+ * @returns {boolean}
+ */
+export function canTransition(from, to) {
+  return (BUILD_TRANSITIONS[from] ?? []).includes(to)
+}
+
+/**
+ * @param {Record<string, any>} context
+ * @returns {Record<string, any>}
+ */
+export function planFields(context) {
+  return { scope: context.scope }
+}
+
+/**
+ * Completion invariants for a build mission: at least one commit on the mission
+ * branch since its base and a clean worktree. The app layer has already resolved
+ * the worktree and collected the primitives.
+ * @param {{ mission: Mission, commits: number, clean: boolean, dirtyPaths: string[] }} context
+ * @returns {{ commits: number }}
+ */
+export function checkCompletion({ mission, commits, clean, dirtyPaths }) {
+  const base = mission.worktree?.baseCommit ?? ''
+  if (commits < 1) {
+    throw new TowerToolError('invalid-argument', `mission branch has no commits since ${String(base).slice(0, 12)}`)
+  }
+  if (!clean) {
+    const shown = dirtyPaths.slice(0, 8).join(', ')
+    const more = dirtyPaths.length > 8 ? ', …' : ''
+    throw new TowerToolError(
+      'worktree-dirty',
+      `mission ${mission.id} worktree has uncommitted changes (${shown}${more}); commit, remove, or record them before tower_complete`,
+    )
+  }
+  return { commits }
+}
+
+/**
+ * Pre-merge completion blockers (the merge gate half of completion).
+ * @param {Mission} mission
+ * @param {TowerConfig} [config]
+ * @returns {Blocker[]}
+ */
+export function completionBlockers(mission, config = /** @type {TowerConfig} */ ({})) {
+  /** @type {Blocker[]} */
+  const blockers = []
+  if (isTerminal(mission.status)) {
+    blockers.push({
+      code: 'branch-owned-by-closed-missions',
+      detail: `mission ${mission.id} is ${mission.status}; a merge never flips a closed mission — re-plan the work under a new title`,
+    })
+  }
+  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 build mission's dependency is satisfied once it has landed or been dropped.
+ * @param {Pick<Mission, 'status'>} dep
+ * @returns {boolean}
+ */
+export function dependencySatisfied(dep) {
+  return dep.status === 'merged' || dep.status === 'abandoned'
+}
+
+/**
+ * Worker spawn constraints: a build worker gets its own branch and worktree.
+ * @type {{ provisioning: 'branch-worktree', missionStatuses: readonly string[], worktree: true, countsTowardWorkerBudget: boolean, model: string }}
+ */
+export const spawn = Object.freeze({
+  provisioning: /** @type {const} */ ('branch-worktree'),
+  missionStatuses: Object.freeze(['planned', 'active', 'completed', 'blocked', 'paused']),
+  worktree: /** @type {const} */ (true),
+  countsTowardWorkerBudget: true,
+  // Optional model route slot: config.spawn.<model>Model. The shape supplies the
+  // fact; the role contract decides whether it is used.
+  model: 'worker',
+})
+
+/**
+ * Mission briefing lines that are specific to the build shape.
+ * @param {Mission} mission
+ * @param {{ worktree?: { path: string, branch: string, baseCommit?: string } | null, base: string, repoRoot?: string, readCommit?: string, readDirty?: string[] }} context
+ * @returns {string[]}
+ */
+export function briefing(mission, context) {
+  const worktree = context.worktree
+  if (!worktree) return []
+  return [
+    `Work ONLY in this git worktree: ${worktree.path}`,
+    `Branch: ${worktree.branch} (based on ${context.base} @ ${String(worktree.baseCommit ?? '').slice(0, 12)})`,
+  ]
+}
+
+/**
+ * Projection of the build-specific mission fields for summaries/board rows.
+ * @param {Mission} mission
+ * @returns {Record<string, any>}
+ */
+export function summary(mission) {
+  return {
+    worktree: mission.worktree ? { path: mission.worktree.path, branch: mission.worktree.branch, baseCommit: mission.worktree.baseCommit } : null,
+    mergedCommit: mission.mergedCommit ?? null,
+    mergedAt: mission.mergedAt ?? null,
+  }
+}
+
+/**
+ * One-line human description of where the mission reads/writes, used by reports.
+ * @param {Mission} mission
+ * @returns {string | null}
+ */
+export function describe(mission) {
+  return mission.worktree?.branch ? `branch ${mission.worktree.branch}` : null
+}
+
+/**
+ * v3 -> v4 migration hook (#148). A build mission's document keeps its shape;
+ * only the kind discriminant is stamped. Documents written before `kind` existed
+ * are builds.
+ * @param {Record<string, any>} mission
+ * @returns {boolean}
+ */
+export function isLegacy(mission) {
+  return mission.kind === undefined || mission.kind === null || mission.kind === '' || mission.kind === 'build'
+}
+
+/**
+ * @param {Record<string, any>} mission
+ * @param {Record<string, any>} [_options] shared migration context; a build needs none
+ * @returns {Record<string, any>}
+ */
+export function migrateLegacy(mission, _options = {}) {
+  return { ...mission, kind: 'build' }
+}
+
+export const buildShape = Object.freeze({
+  kind: /** @type {const} */ ('build'),
+  statuses: BUILD_STATUSES,
+  transitions: BUILD_TRANSITIONS,
+  isTerminal,
+  canTransition,
+  isLegacy,
+  needsLegacyRead: () => false,
+  migrateLegacy,
+  canMerge: true,
+  canRebase: true,
+  provisioning: /** @type {const} */ ('branch-worktree'),
+  reach: REACH,
+  // Document dimensions this shape owns; the state validator reads these.
+  fields: Object.freeze({ worktree: true, readCommit: false, merge: true, sandbox: false }),
+  requiredComponent: null,
+  acceptsResult: false,
+  evidence: EVIDENCE,
+  planFields,
+  completion: Object.freeze({
+    requiresWorktree: true,
+    requiresCommits: true,
+    requiresClean: true,
+    requiresHeadMatch: false,
+    requiresTrackedStatus: false,
+    check: /** @type {(ctx: any) => { commits: number }} */ (checkCompletion),
+  }),
+  completionBlockers,
+  dependencySatisfied,
+  spawn,
+  briefing,
+  summary,
+  describe,
+})