dsh-tower 2.5.0 → 2.7.0

package/domain/evidence.js

@@ -0,0 +1,283 @@
+// One evidence contract (#149 W4). "Did the work pass checks?" has exactly one
+// answer shape and one reader:
+//
+//   * a completion report's `checks` (an assertion the caller recorded), and
+//   * a test-discovery receipt in `mission.testRuns` (machine evidence bound to
+//     the tree tip the discovery ran on).
+//
+// Every consumer — the merge gate's test blocker, batch close/status, the
+// shape completion invariants and the tools that record evidence — calls this
+// module. The shape declares which sources appertain (`shape.evidence`); the
+// generic layers never read `completionReport.checks` or `mission.testRuns`
+// themselves, and no layer copies a receipt into a completion report.
+//
+// A normalized record is the unit both kinds of evidence share:
+//   { names, name, source, ok, command, exitCode, evidence, treeTip, entry }
+//
+// @ts-check
+
+/** @typedef {'completionReport' | 'testRuns' | 'input'} EvidenceSource */
+/**
+ * @typedef {{
+ *   completionChecks: boolean,
+ *   testReceipts: false | 'tip-bound',
+ * }} EvidenceContract
+ */
+/**
+ * @typedef {{
+ *   names: string[],
+ *   name: string,
+ *   source: EvidenceSource,
+ *   ok: boolean | null,
+ *   command: string | null,
+ *   exitCode: number | null,
+ *   evidence: string | null,
+ *   treeTip: string | null,
+ *   entry: Record<string, any>,
+ * }} EvidenceEntry
+ */
+
+/** Provenance labels reported by every reader. */
+export const EVIDENCE_SOURCE = Object.freeze({
+  COMPLETION: /** @type {const} */ ('completionReport'),
+  DISCOVERY: /** @type {const} */ ('testRuns'),
+  INPUT: /** @type {const} */ ('input'),
+})
+
+/**
+ * A nameless discovery receipt answers to both names: `tests` is the name the
+ * built-in test tool has always used, `tower_test` the synthetic name older
+ * integrations attached to the same receipt.
+ */
+export const TEST_EVIDENCE_NAMES = Object.freeze(['tests', 'tower_test'])
+
+/** @param {unknown} value */
+function nonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0
+}
+
+/** @param {unknown} value */
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+/**
+ * @param {Record<string, any>} entry
+ * @returns {boolean}
+ */
+function isDiscoveryReceipt(entry) {
+  return Array.isArray(entry.commands) && Array.isArray(entry.tests)
+}
+
+/**
+ * @param {Record<string, any>} entry
+ * @returns {string[]}
+ */
+function namesOf(entry) {
+  if (isDiscoveryReceipt(entry)) return [...TEST_EVIDENCE_NAMES]
+  for (const candidate of [entry.name, entry.id, entry.check]) {
+    if (nonEmptyString(candidate)) return [String(candidate).trim()]
+  }
+  return []
+}
+
+/**
+ * @param {Record<string, any>} entry
+ * @returns {boolean | null}
+ */
+function outcomeOf(entry) {
+  if (typeof entry.status === 'string') {
+    const status = entry.status.trim().toLowerCase()
+    if (['pass', 'passed', 'ok', 'success', 'succeeded', 'green', 'clean'].includes(status)) return true
+    if (['fail', 'failed', 'error', 'failure', 'red', 'not-clean'].includes(status)) return false
+  }
+  if (typeof entry.ok === 'boolean') return entry.ok
+  if (typeof entry.pass === 'boolean') return entry.pass
+  if (typeof entry.success === 'boolean') return entry.success
+  if (entry.exitCode !== undefined && entry.exitCode !== null) {
+    const exitCode = typeof entry.exitCode === 'number' ? entry.exitCode : Number(entry.exitCode)
+    if (Number.isFinite(exitCode)) return exitCode === 0
+  }
+  if (entry.error !== undefined && entry.error !== null && entry.error !== '') return false
+  return null
+}
+
+/**
+ * @param {Record<string, any>} entry
+ * @returns {string | null}
+ */
+function receiptCommand(entry) {
+  const commands = Array.isArray(entry.commands) ? entry.commands : []
+  const rendered = commands
+    .filter((command) => isPlainObject(command))
+    .map((command) => `${command.id ?? '?'}: ${command.command ?? '?'}`)
+    .join('; ')
+  return rendered || null
+}
+
+/**
+ * @param {Record<string, any>} entry
+ * @returns {number | null}
+ */
+function receiptExitCode(entry) {
+  const commands = Array.isArray(entry.commands) ? entry.commands : []
+  if (commands.length === 0) return null
+  const failed = commands.find((command) => isPlainObject(command) && command.exitCode !== 0)
+  if (!failed) return 0
+  return typeof failed.exitCode === 'number' ? failed.exitCode : 1
+}
+
+/**
+ * @param {Record<string, any>} entry
+ * @returns {string | null}
+ */
+function receiptEvidence(entry) {
+  if (entry.ok === true) {
+    const count = Array.isArray(entry.tests) ? entry.tests.length : 0
+    const tip = String(entry.treeTip ?? '').slice(0, 12)
+    return `${count} test(s) passed${tip ? ` at ${tip}` : ''}; receipt ${entry.receiptPath ?? entry.diagnosticsPath ?? '(none)'}`
+  }
+  return `test discovery failed: ${String(entry.error ?? 'unknown').slice(0, 300)}`
+}
+
+/**
+ * Normalize one evidence source entry. Returns null for an entry that names no
+ * check and for a non-object, so a reader never silently invents evidence.
+ * @param {unknown} raw
+ * @param {EvidenceSource} source
+ * @returns {EvidenceEntry | null}
+ */
+export function normalizeEvidence(raw, source) {
+  if (!isPlainObject(raw)) return null
+  const entry = /** @type {Record<string, any>} */ (raw)
+  const names = namesOf(entry)
+  if (names.length === 0) return null
+  const receipt = isDiscoveryReceipt(entry)
+  return {
+    names,
+    name: names[0],
+    source,
+    ok: outcomeOf(entry),
+    command: receipt ? receiptCommand(entry) : nonEmptyString(entry.command) ? String(entry.command) : null,
+    exitCode: receipt
+      ? receiptExitCode(entry)
+      : typeof entry.exitCode === 'number'
+        ? entry.exitCode
+        : null,
+    evidence: receipt
+      ? receiptEvidence(entry)
+      : nonEmptyString(entry.evidence)
+        ? String(entry.evidence)
+        : null,
+    treeTip: nonEmptyString(entry.treeTip) ? String(entry.treeTip) : null,
+    entry,
+  }
+}
+
+/**
+ * Every evidence record for one mission, newest first within a source:
+ * completion checks, then discovery receipts (when the shape accepts them),
+ * then caller-supplied close-time checks.
+ * @param {EvidenceContract} contract
+ * @param {Record<string, any> | null | undefined} mission
+ * @param {{ extraChecks?: any[], missionId?: string }} [options]
+ * @returns {EvidenceEntry[]}
+ */
+export function evidenceEntries(contract, mission, { extraChecks = [], missionId = mission?.id } = {}) {
+  /** @type {EvidenceEntry[]} */
+  const records = []
+  if (contract?.completionChecks !== false) {
+    const checks = Array.isArray(mission?.completionReport?.checks) ? mission.completionReport.checks : []
+    for (let index = checks.length - 1; index >= 0; index -= 1) {
+      const record = normalizeEvidence(checks[index], EVIDENCE_SOURCE.COMPLETION)
+      if (record) records.push(record)
+    }
+  }
+  if (contract?.testReceipts) {
+    const runs = Array.isArray(mission?.testRuns) ? mission.testRuns : []
+    for (let index = runs.length - 1; index >= 0; index -= 1) {
+      const run = runs[index]
+      if (!isPlainObject(run)) continue
+      const nested = Array.isArray(run.checks) && run.checks.length > 0
+      if (nested) {
+        for (let inner = run.checks.length - 1; inner >= 0; inner -= 1) {
+          const record = normalizeEvidence(run.checks[inner], EVIDENCE_SOURCE.DISCOVERY)
+          if (record) records.push(record)
+        }
+      } else {
+        const record = normalizeEvidence(run, EVIDENCE_SOURCE.DISCOVERY)
+        if (record) records.push(record)
+      }
+    }
+  }
+  for (let index = extraChecks.length - 1; index >= 0; index -= 1) {
+    const entry = extraChecks[index]
+    if (!isPlainObject(entry)) continue
+    const scope = entry.missionId ?? entry.mission_id
+    if (scope !== undefined && scope !== null && String(scope) !== missionId) continue
+    const record = normalizeEvidence(entry, EVIDENCE_SOURCE.INPUT)
+    if (record) records.push(record)
+  }
+  return records
+}
+
+/**
+ * The most authoritative recorded outcome for one check name. Completion
+ * checks win over discovery receipts, which win over caller-supplied checks;
+ * within a source the newest entry wins.
+ * @param {EvidenceContract} contract
+ * @param {Record<string, any> | null | undefined} mission
+ * @param {string} name
+ * @param {{ extraChecks?: any[], missionId?: string }} [options]
+ * @returns {EvidenceEntry | null}
+ */
+export function findEvidence(contract, mission, name, options = {}) {
+  for (const record of evidenceEntries(contract, mission, options)) {
+    if (!record.names.includes(name)) continue
+    if (record.ok === null) continue
+    return record
+  }
+  return null
+}
+
+/**
+ * The passing discovery receipt bound to `branchTip`, or null. A receipt is
+ * evidence only for the tree it ran on, so a receipt recorded at another tip
+ * (or no tip) never satisfies the merge gate.
+ * @param {EvidenceContract} contract
+ * @param {Record<string, any> | null | undefined} mission
+ * @param {string | null | undefined} branchTip
+ * @returns {EvidenceEntry | null}
+ */
+export function passingDiscovery(contract, mission, branchTip) {
+  if (contract?.testReceipts !== 'tip-bound') return null
+  if (!nonEmptyString(branchTip)) return null
+  const tip = String(branchTip)
+  return (
+    evidenceEntries(contract, mission).find(
+      (record) => record.source === EVIDENCE_SOURCE.DISCOVERY && record.ok === true && record.treeTip === tip,
+    ) ?? null
+  )
+}
+
+/**
+ * Whether a mission has any recorded check evidence. `gates.requireChecks`
+ * asks this question; a discovery receipt answers it because a receipt is
+ * stronger evidence than a hand-written check line.
+ * @param {EvidenceContract} contract
+ * @param {Record<string, any> | null | undefined} mission
+ * @returns {boolean}
+ */
+export function hasCheckEvidence(contract, mission) {
+  return evidenceEntries(contract, mission).length > 0
+}
+
+/**
+ * Whether the mission has recorded test-discovery receipts. Diagnostics use
+ * this instead of reading `mission.testRuns` themselves.
+ * @param {Record<string, any> | null | undefined} mission
+ * @returns {boolean}
+ */
+export function hasTestReceipts(mission) {
+  return Array.isArray(mission?.testRuns) && mission.testRuns.length > 0
+}

package/domain/gate.js

@@ -1,7 +1,8 @@
 // Pure completion gate checks (#49). No repository I/O.
 // @ts-check
-import { isTerminal } from './mission.js'
-import { isReviewExempt, reviewExemptionInvalid } from './integration/review.js'
+import { shapeFor } from './shapes/index.js'
+import { passingDiscovery } from './evidence.js'
+import { isReviewExempt, reviewExemptionInvalid, reviewRequired } from './integration/review.js'
 
 /** @typedef {import('../types/index.js').Blocker} Blocker */
 /** @typedef {import('../types/index.js').MergeGateOptions} MergeGateOptions */
@@ -10,39 +11,15 @@ import { isReviewExempt, reviewExemptionInvalid } from './integration/review.js'
 /** @typedef {import('../types/index.js').TowerConfig} TowerConfig */
 
 /**
+ * Pre-merge completion blockers. The shape owns the vocabulary: a survey is
+ * terminal when completed and is never merged, so it has no
+ * "closed mission owns a branch" blocker.
  * @param {Mission} mission
  * @param {TowerConfig} [config]
  * @returns {Blocker[]}
  */
 export function completionBlockers(mission, config = {}) {
-  /** @type {Blocker[]} */
-  const blockers = []
-  /** @type {(code: string, detail: string) => void} */
-  const push = (code, detail) => {
-    blockers.push({ code, detail })
-  }
-  if (isTerminal(mission.status)) {
-    push(
-      'branch-owned-by-closed-missions',
-      `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') {
-    push('mission-not-completed', `mission ${mission.id} is ${mission.status}; completion is required`)
-  }
-  const openTasks = (mission.tasks ?? []).filter((task) => task.status === 'open')
-  if (openTasks.length > 0) {
-    push('tasks-open', `${openTasks.length} open task(s): ${openTasks.map((task) => task.text).join('; ')}`)
-  }
-  const presentBlockers = mission.blockers ?? []
-  if (presentBlockers.length > 0) push('blockers-present', presentBlockers.join('; '))
-  if (config.gates?.requireChecks === true) {
-    const checks = mission.completionReport?.checks ?? []
-    if (checks.length === 0) {
-      push('no-check-evidence', `mission ${mission.id} has no completion checks; gates.requireChecks is enabled`)
-    }
-  }
-  return blockers
+  return shapeFor(mission.kind).completionBlockers(mission, config)
 }
 
 /**
@@ -74,13 +51,16 @@ export function mergeGateBlockers({
     blockers.push({ code, detail })
   }
   const inactive = new Set(inactiveStates)
-  const requireReview = config.review?.requireReview !== false
+  // #M39: only `review.mode:required` produces review blockers. `optional`
+  // records reviews without gating, and `off` disables review entirely (no
+  // tower_review, no reviewer spawn), so both skip this whole block.
+  const requireReview = reviewRequired(config)
   const exempt = isReviewExempt(mission, config)
   if (reviewExemptionInvalid(mission, config)) {
     push('review-exemption-invalid', `mission ${mission.id} requests no review but gates.allowReviewExemption is disabled`)
   }
   if (requireReview && !exempt && !review) {
-    push('no-review', `branch ${branch ?? '(none)'} has no review; assign a reviewer first (or set review.requireReview:false)`)
+    push('no-review', `branch ${branch ?? '(none)'} has no review; assign a reviewer first (or set review.mode:optional)`)
   } else if (requireReview && !exempt) {
     const latest = /** @type {Review} */ (review)
     if (latest.missionId !== mission.id) push('review-mission-mismatch', `latest review belongs to mission ${latest.missionId}`)
@@ -109,8 +89,11 @@ export function mergeGateBlockers({
     push('worker-stale', `stale worker(s) for ${mission.id}: ${staleWorkers.map((row) => row.name).join(', ')}; adopt or interrupt before merge`)
   }
   if (config.gates?.requireTests === true) {
-    const runs = (mission.testRuns ?? []).filter((run) => run.ok === true && run.treeTip && branchTip && run.treeTip === branchTip)
-    if (runs.length === 0) {
+    // #149 W4: the receipt question is answered by the one evidence reader, not
+    // by a second filter here. The shape decides whether a receipt appertains;
+    // a receipt is evidence only for the tip it ran on.
+    const receipt = passingDiscovery(shapeFor(mission.kind).evidence, mission, branchTip)
+    if (!receipt) {
       // #140: name the component cause when the row is off. Without this the
       // blocker reads as a repository mistake ("no passing discovery") when the
       // real cause is a disabled row and no tower_test tool exists to produce a

package/domain/integration/gate.js

@@ -2,7 +2,8 @@
 // facts the app already read (tips, changed files, checkout branch). The app
 // performs every read and owns the result assembly.
 // @ts-check
-import { caseInsensitiveScopeMatch, fileInScope } from '../scope.js'
+import { scopeFenceBlocker } from '../scope.js'
+import { shapeFor } from '../shapes/index.js'
 
 /** @typedef {import('../../types/index.js').Blocker} Blocker */
 /** @typedef {import('../../types/index.js').Mission} Mission */
@@ -58,21 +59,9 @@ export function staleBaseBlocker({ branch, base, baseTip }) {
 }
 
 /**
- * @param {object} input
- * @param {string} input.missionId
- * @param {string[]} input.changedFiles
- * @returns {Blocker | null}
- */
-export function surveyChangedFilesBlocker({ missionId, changedFiles }) {
-  return changedFiles.length > 0
-    ? {
-        code: 'read-only-survey',
-        detail: `survey ${missionId} is read-only but ${changedFiles.length} file(s) changed: ${changedFiles.slice(0, 5).join(', ')}`,
-      }
-    : null
-}
-
-/**
+ * The merge gate's scope fence. The shape (via `reach`) owns the permission
+ * question; this enforcer only supplies the changed files and the checkout's
+ * comparison mode.
  * @param {object} input
  * @param {Mission} input.mission
  * @param {string[]} input.changedFiles
@@ -80,25 +69,12 @@ export function surveyChangedFilesBlocker({ missionId, changedFiles }) {
  * @returns {Blocker | null}
  */
 export function outOfScopeBlocker({ mission, changedFiles, caseInsensitive = false }) {
-  const outOfScope = changedFiles.filter((file) => !fileInScope(mission.scope, file, { caseInsensitive }))
-  if (outOfScope.length === 0) return null
-  const parts = [`changed files outside scope (${mission.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(mission.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('. ') }
+  return scopeFenceBlocker({
+    mission,
+    reach: shapeFor(mission.kind).reach,
+    changedFiles,
+    caseInsensitive,
+  })
 }
 
 /**
@@ -124,18 +100,16 @@ export function baseDirtyBlocker(wouldOverwrite) {
 }
 
 /**
- * Whether a dependency already satisfies the gate. A build mission must be
- * merged (or abandoned), but a survey is terminal-success at `completed`: it is
- * read-only and has no branch to merge, so requiring `merged` would keep the
- * dependent mission blocked forever (#107). Archived entries carry `kind` for
- * the same decision.
+ * Whether a dependency already satisfies the gate. Each shape owns the answer:
+ * a build dependency must be merged (or abandoned), a survey dependency is
+ * terminal-success at `completed` (it has no branch to merge). Archived entries
+ * carry `kind` for the same decision.
  * @param {{ kind?: string, status?: string } | null | undefined} dep
  * @returns {boolean}
  */
 export function dependencySatisfied(dep) {
-  if (!dep) return false
-  if (dep.status === 'merged' || dep.status === 'abandoned') return true
-  return dep.kind === 'survey' && dep.status === 'completed'
+  if (!dep || typeof dep.status !== 'string') return false
+  return shapeFor(dep.kind).dependencySatisfied(/** @type {any} */ (dep))
 }
 
 /**

package/domain/integration/init.js

@@ -2,7 +2,8 @@
 // policy, snapshot decisions, and the initial/existing result projections. All
 // fs/git work and state persistence stay in app/init.js.
 // @ts-check
-import { SCHEMA_VERSION, TERMINAL_STATUSES } from '../mission.js'
+import { SCHEMA_VERSION } from '../mission.js'
+import { shapeFor } from '../shapes/index.js'
 
 /** @typedef {import('../../types/index.js').Mission} Mission */
 /** @typedef {import('../../types/index.js').TowerState} TowerState */
@@ -72,7 +73,7 @@ export function claimCaller(owner, caller) {
  * @returns {string | null} refusal message, or null when reanchor may proceed
  */
 export function reanchorBlockedMessage(missions) {
-  const active = missions.filter((mission) => !TERMINAL_STATUSES.has(mission.status))
+  const active = missions.filter((mission) => !shapeFor(mission.kind).isTerminal(mission.status))
   return active.length > 0 ? `cannot reanchor base while ${active.length} mission(s) are not merged or abandoned` : null
 }
 

package/domain/integration/provision.js

@@ -69,6 +69,18 @@ export function worktreePath(root, missionId) {
   return path.join(root, missionId)
 }
 
+/**
+ * The disposable detached checkout a `survey.sandbox: 'detached'` survey reads
+ * in (#148 W2). The `-sandbox` suffix keeps it distinct from a build worktree
+ * with the same mission id and from the mission branch naming scheme.
+ * @param {string} root
+ * @param {string} missionId
+ * @returns {string}
+ */
+export function sandboxPath(root, missionId) {
+  return path.join(root, `${missionId}-sandbox`)
+}
+
 /**
  * @param {unknown} missionId
  * @returns {boolean}
@@ -114,6 +126,45 @@ export function createdWorktreeResult(mission, worktree) {
   return { mission, worktree, created: true }
 }
 
+/**
+ * A shared-checkout shape (survey) provisions no branch and no worktree: the
+ * agent reads the recorded commit in the main checkout.
+ * @param {Mission} mission
+ * @param {string} cwd
+ * @returns {{ mission: Mission, worktree: null, cwd: string, created: false, provisioning: 'shared' }}
+ */
+export function sharedProvisionResult(mission, cwd) {
+  return { mission, worktree: null, cwd, created: false, provisioning: /** @type {const} */ ('shared') }
+}
+
+/**
+ * A detached survey result (#148 W2). The mission has no worktree projection:
+ * the sandbox path is recorded as `mission.sandbox` and is the agent's cwd.
+ * @param {Mission} mission
+ * @param {string} sandbox
+ * @param {boolean} created
+ * @returns {{ mission: Mission, worktree: null, sandbox: string, cwd: string, created: boolean, provisioning: 'detached' }}
+ */
+export function detachedSandboxResult(mission, sandbox, created) {
+  return {
+    mission,
+    worktree: null,
+    sandbox,
+    cwd: sandbox,
+    created,
+    provisioning: /** @type {const} */ ('detached'),
+  }
+}
+
+/**
+ * @param {string} sandbox
+ * @param {string} readCommit
+ * @returns {string}
+ */
+export function sandboxActivityText(sandbox, readCommit) {
+  return `detached sandbox at ${sandbox} (read ${String(readCommit).slice(0, 12)})`
+}
+
 /**
  * @param {string} branch
  * @param {string} wtPath

package/domain/integration/rebase.js

@@ -155,13 +155,28 @@ export function buildRebaseIntent({ token, missionId, base, oldTip, baseTip, com
   return { token, missionId, base, oldTip, baseTip, commits, startedAt }
 }
 
+/**
+ * Prefix that identifies the blocker a rebase conflict records. A successful
+ * retry resolves exactly that blocker; unrelated blockers keep the mission
+ * blocked.
+ */
+export const REBASE_CONFLICT_PREFIX = 'rebase conflict onto '
+
+/**
+ * @param {string} blocker
+ * @returns {boolean}
+ */
+export function isRebaseConflictBlocker(blocker) {
+  return typeof blocker === 'string' && blocker.startsWith(REBASE_CONFLICT_PREFIX)
+}
+
 /**
  * @param {string} base
  * @param {string} baseTip
  * @returns {string}
  */
 export function rebaseConflictNote(base, baseTip) {
-  return `rebase conflict onto ${base} @ ${baseTip.slice(0, 12)}`
+  return `${REBASE_CONFLICT_PREFIX}${base} @ ${baseTip.slice(0, 12)}`
 }
 
 /**