dsh-tower 2.5.0 → 2.7.0

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,
+})

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` },
+    )
+  }
+}