dsh-tower 2.0.4 → 2.1.0

package/domain/missions/plan.js

@@ -0,0 +1,149 @@
+// Pure mission planning input normalization and projections.
+//
+// The use case in app/plan.js owns the state lock, load, persistence, and the
+// activity entry; everything here is deterministic and repository-free.
+// @ts-check
+import { TowerToolError } from '../errors.js'
+import { normalizeScope, validateTitle } from '../scope.js'
+
+/** @typedef {import('../../types/index.js').Mission} Mission */
+
+/**
+ * @param {string} message
+ * @returns {never}
+ */
+function fail(message) {
+  throw new TowerToolError('invalid-argument', message)
+}
+
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+/**
+ * Validate and normalize one `tower_plan` mission entry.
+ * @param {any} input
+ * @param {number} index
+ * @returns {any}
+ */
+export function normalizeMissionInput(input, index) {
+  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' })
+  /** @type {Array<{ text: string, status: string }>} */
+  const tasks = []
+  if (input.tasks !== undefined) {
+    if (!Array.isArray(input.tasks)) fail(`missions[${index}].tasks must be an array of strings`)
+    for (const task of input.tasks) {
+      if (typeof task !== 'string' || task.trim().length === 0) {
+        fail(`missions[${index}].tasks entries must be non-empty strings`)
+      }
+      tasks.push({ text: task.trim(), status: 'open' })
+    }
+  }
+  /** @type {string[]} */
+  const deps = []
+  if (input.deps !== undefined) {
+    if (!Array.isArray(input.deps)) fail(`missions[${index}].deps must be an array of mission ids`)
+    for (const dep of input.deps) {
+      if (typeof dep !== 'string' || dep.trim().length === 0) {
+        fail(`missions[${index}].deps entries must be non-empty mission ids`)
+      }
+      if (!deps.includes(dep.trim())) deps.push(dep.trim())
+    }
+  }
+  const context = typeof input.context === 'string' ? input.context.slice(0, 4096) : ''
+  /** @type {string[]} */
+  const references = []
+  if (input.references !== undefined) {
+    if (!Array.isArray(input.references)) fail(`missions[${index}].references must be an array of pointers`)
+    if (input.references.length > 20) fail(`missions[${index}].references supports at most 20 pointers`)
+    for (const reference of input.references) {
+      if (typeof reference !== 'string' || reference.trim().length === 0) {
+        fail(`missions[${index}].references entries must be non-empty strings`)
+      }
+      if (!references.includes(reference.trim())) references.push(reference.trim())
+    }
+  }
+  const reviewPolicy = input.reviewPolicy === undefined ? 'required-clean' : input.reviewPolicy
+  if (!['required-clean', 'none'].includes(reviewPolicy)) {
+    fail(`missions[${index}].reviewPolicy must be "required-clean" or "none"`)
+  }
+  const reviewExemptionReason = typeof input.reviewExemptionReason === 'string' ? input.reviewExemptionReason.trim() : ''
+  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 }
+}
+
+/**
+ * Validate the plan envelope and normalize every mission entry.
+ * @param {any} input
+ * @returns {any[]}
+ */
+export function normalizePlanMissions(input) {
+  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))
+}
+
+/**
+ * Assign the next contiguous mission ids without mutating the input.
+ * @param {any[]} prepared
+ * @param {number} start
+ * @returns {any[]}
+ */
+export function assignMissionIds(prepared, start) {
+  return prepared.map((mission, index) => ({ ...mission, id: `M${start + index}` }))
+}
+
+/**
+ * Every explicit dependency must name an existing or newly assigned mission.
+ * @param {any[]} assigned
+ * @param {Mission[]} existingMissions
+ * @returns {void}
+ */
+export function assertKnownDependencies(assigned, existingMissions) {
+  const known = new Set([...existingMissions.map((mission) => mission.id), ...assigned.map((mission) => mission.id)])
+  for (const mission of assigned) {
+    for (const dep of mission.deps) {
+      if (!known.has(dep)) fail(`mission ${mission.id} depends on unknown mission "${dep}"`)
+    }
+  }
+}
+
+/**
+ * Project a normalized, id-assigned input into a fresh mission record.
+ * @param {string} id
+ * @param {any} input
+ * @param {number} now
+ * @returns {Mission}
+ */
+export function newMission(id, input, now) {
+  return /** @type {Mission} */ (/** @type {any} */ ({
+    id,
+    title: input.title,
+    kind: input.kind,
+    scope: input.scope,
+    tasks: input.tasks,
+    deps: input.deps,
+    context: input.context,
+    references: input.references ?? [],
+    reviewPolicy: input.reviewPolicy ?? 'required-clean',
+    reviewExemptionReason: input.reviewExemptionReason ?? '',
+    status: 'planned',
+    owner: null,
+    blockers: [],
+    notes: [],
+    reviews: [],
+    scopeGeneration: 1,
+    createdAt: now,
+    updatedAt: now,
+  }))
+}

package/domain/missions/review.js

@@ -0,0 +1,179 @@
+// Pure review submission policy: actor resolution, verdict validation, round
+// accounting, and the resulting mission/record projections.
+//
+// app/review.js owns loading state, the worktree/tip Git reads, the lock, and
+// persistence. Everything here is deterministic and repository-free.
+// @ts-check
+import { TowerToolError } from '../errors.js'
+import { MERGE_VERDICTS, REVIEW_STATUS_RE } from '../mission.js'
+
+/** @typedef {import('../../types/index.js').Mission} Mission */
+/** @typedef {import('../../types/index.js').RosterEntry} RosterEntry */
+/** @typedef {import('../../types/index.js').Review} Review */
+
+export const MAX_REVIEW_ROUNDS = 5
+
+/**
+ * @param {string} message
+ * @param {string} [code]
+ * @returns {never}
+ */
+function fail(message, code = 'invalid-argument') {
+  throw new TowerToolError(code, message)
+}
+
+/**
+ * A mission with a worktree is the only reviewable subject; the caller checks
+ * that its status is `completed`.
+ * @param {Mission} mission
+ * @returns {void}
+ */
+export function assertReviewableMission(mission) {
+  if (!mission.worktree) fail(`mission ${mission.id} has no worktree to review`)
+}
+
+/**
+ * Resolve who is submitting the review. An unregistered caller fails closed;
+ * only an assigned reviewer or the tower (break-glass) may review.
+ * @param {{ mission: Mission, caller: RosterEntry | undefined, actorRole: string | undefined, agentId: string | undefined, breakGlassReason: unknown }} params
+ * @returns {{ reviewerName: string, reviewerRole: string }}
+ */
+export function resolveReviewActor({ mission, caller, actorRole, agentId, breakGlassReason }) {
+  if (actorRole === 'tower') {
+    if (typeof breakGlassReason !== 'string' || breakGlassReason.trim().length === 0) {
+      fail('a tower-submitted review is break-glass and requires a non-empty breakGlassReason', 'not-authorized')
+    }
+    return { reviewerName: 'tower', reviewerRole: 'tower' }
+  }
+  if (caller) {
+    if (caller.role !== 'reviewer') {
+      fail(`agent ${caller.name} is a ${caller.role}; only an assigned reviewer or the tower (break-glass) may review`)
+    }
+    if (caller.missionId !== mission.id) {
+      fail(`reviewer ${caller.name} was not assigned to mission ${mission.id}`)
+    }
+    if (mission.owner && caller.name === mission.owner) fail('the reviewer must differ from the worker', 'not-authorized')
+    return { reviewerName: caller.name, reviewerRole: 'reviewer' }
+  }
+  // Fail closed: an unknown caller is not the tower, and a missing roster row
+  // is not evidence of tower identity.
+  fail(`agent ${agentId ?? '(unknown)'} is not a registered reviewer or the tower`)
+}
+
+/**
+ * Validate the verdict payload fields that are independent of Git.
+ * @param {any} input
+ * @returns {{ status: string, merge: string, findings: string, decision: string, checks: string[] }}
+ */
+export function normalizeReviewVerdict(input) {
+  if (!REVIEW_STATUS_RE.test(String(input.status ?? ''))) {
+    fail('status must be "clean", "p1-Nitems", or "p2-Nitems"')
+  }
+  if (!MERGE_VERDICTS.includes(input.merge)) {
+    fail(`merge verdict must be one of ${MERGE_VERDICTS.join('|')}`)
+  }
+  const findings = String(input.findings ?? '').trim()
+  if (!findings) fail('findings text is required; write "none" for a clean verdict')
+  if (input.status === 'clean' && findings.toLowerCase() !== 'none') {
+    fail('a clean verdict requires findings text "none"')
+  }
+  if (input.status !== 'clean' && findings.toLowerCase() === 'none') {
+    fail('a non-clean verdict must describe its findings')
+  }
+  const decision = String(input.decision ?? '').trim()
+  if (!decision) fail('decision (the reasoning behind the verdict) is required')
+  /** @type {string[]} */
+  let checks = []
+  if (input.checks !== undefined) {
+    if (!Array.isArray(input.checks)) fail('checks must be an array of strings')
+    checks = input.checks.map((entry) => String(entry))
+  }
+  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`,
+    )
+  }
+}
+
+/**
+ * Compute the review round and enforce the per-reviewer cap.
+ * @param {{ reviews: Review[] | undefined, branch: string, reviewerName: string, maxRoundsPerReviewer: unknown }} params
+ * @returns {{ reviewerRounds: number, round: number }}
+ */
+export function reviewRound({ reviews, branch, reviewerName, maxRoundsPerReviewer }) {
+  const prior = (reviews ?? []).filter((review) => review.branch === branch)
+  const reviewerRounds = prior.filter((review) => review.reviewer === reviewerName).length
+  const maxReviewRounds = Number(maxRoundsPerReviewer) || MAX_REVIEW_ROUNDS
+  if (reviewerRounds >= maxReviewRounds) {
+    fail(
+      `reviewer ${reviewerName} reached the ${maxReviewRounds}-round cap for ${branch}; continue with a different reviewer`,
+    )
+  }
+  const round = prior.length === 0 ? 1 : Math.max(...prior.map((review) => review.round)) + 1
+  return { reviewerRounds, round }
+}
+
+/**
+ * A non-clean verdict returns the mission to active and records the note; a
+ * clean verdict leaves the status untouched.
+ * @param {{ status: string, merge: string, round: number, reviewerName: string }} params
+ * @returns {{ returnToActive: boolean, note: string }}
+ */
+export function reviewOutcome({ status, merge, round, reviewerName }) {
+  if (status !== 'clean') {
+    return {
+      returnToActive: true,
+      note: `review round ${round} by ${reviewerName}: ${status} (${merge}) — returned to active`,
+    }
+  }
+  return { returnToActive: false, note: `review round ${round} by ${reviewerName}: clean (${merge})` }
+}
+
+/**
+ * Project the persisted review record.
+ * @param {{ seq: number, missionId: string, branch: string, tip: string, verdict: { status: string, merge: string, findings: string, checks: string[], decision: string }, reviewerName: string, reviewerRole: string, round: number, now: number, breakGlassReason?: string }} params
+ * @returns {Review}
+ */
+export function reviewRecord({
+  seq,
+  missionId,
+  branch,
+  tip,
+  verdict,
+  reviewerName,
+  reviewerRole,
+  round,
+  now,
+  breakGlassReason,
+}) {
+  return {
+    id: `R${seq}`,
+    seq,
+    missionId,
+    branch,
+    reviewedCommit: tip,
+    status: verdict.status,
+    mergeVerdict: /** @type {import('../../types/index.js').MergeVerdict} */ (verdict.merge),
+    findings: verdict.findings,
+    checks: verdict.checks,
+    decision: verdict.decision,
+    reviewer: reviewerName,
+    reviewerRole,
+    round,
+    at: now,
+    ...(reviewerRole === 'tower' ? { breakGlassReason } : {}),
+  }
+}

package/domain/planning.js

@@ -0,0 +1,121 @@
+// Pure mission planning helpers.
+// @ts-check
+import { TowerToolError } from './errors.js'
+import { scopesOverlap } from './scope.js'
+import { isTerminal } from './mission.js'
+
+/** @typedef {import('../types/index.js').Mission} Mission */
+
+/**
+ * @param {string} message
+ * @returns {never}
+ */
+function fail(message) {
+  throw new TowerToolError('invalid-argument', message)
+}
+
+/**
+ * @param {Mission[]} missions
+ * @returns {number}
+ */
+function nextMissionNumber(missions) {
+  let max = 0
+  for (const mission of missions) {
+    const match = /^M(\d+)$/.exec(mission.id)
+    if (match) max = Math.max(max, Number(match[1]))
+  }
+  return max + 1
+}
+
+/**
+ * @param {Mission} mission
+ * @param {string} dep
+ * @returns {void}
+ */
+function addDependency(mission, dep) {
+  if (mission.id === dep) return
+  if (!mission.deps.includes(dep)) mission.deps.push(dep)
+}
+
+/**
+ * @param {Map<string, Mission>} missionsById
+ * @param {string} fromId
+ * @param {string} toId
+ * @returns {boolean}
+ */
+function hasDependencyPath(missionsById, fromId, toId) {
+  /** @type {Set<string>} */
+  const seen = new Set()
+  /** @type {string[]} */
+  const stack = [fromId]
+  while (stack.length > 0) {
+    const current = /** @type {string} */ (stack.pop())
+    if (current === toId) return true
+    if (seen.has(current)) continue
+    seen.add(current)
+    const mission = missionsById.get(current)
+    if (!mission) continue
+    for (const dep of mission.deps) stack.push(dep)
+  }
+  return false
+}
+
+/**
+ * @param {Mission[]} missions
+ * @returns {void}
+ */
+function assertAcyclic(missions) {
+  /** @type {Map<string, Mission>} */
+  const byId = new Map(missions.map((mission) => [mission.id, mission]))
+  /** @type {Map<string, 'visiting' | 'done'>} */
+  const state = new Map()
+  /** @type {(id: string, trail: string[]) => void} */
+  const visit = (id, trail) => {
+    const mark = state.get(id)
+    if (mark === 'done') return
+    if (mark === 'visiting') fail(`mission dependencies have a cycle: ${[...trail, id].join(' -> ')}`)
+    state.set(id, 'visiting')
+    const mission = byId.get(id)
+    if (mission) for (const dep of mission.deps) visit(dep, [...trail, id])
+    state.set(id, 'done')
+  }
+  for (const mission of missions) visit(mission.id, [])
+}
+
+/**
+ * Kimi-style heuristic: overlapping build scopes are serialized by an
+ * auto-added dependency. It is conservative, not a proof of disjointness.
+ * `caseInsensitive` is the checkout's detected mode (#90); on such a filesystem
+ * `src/Api/**` and `src/api/**` are the same real files and must serialise.
+ * @param {Mission[]} newMissions
+ * @param {Mission[]} existingMissions
+ * @param {{ caseInsensitive?: boolean }} [options]
+ * @returns {void}
+ */
+function addAutoDeps(newMissions, existingMissions, { caseInsensitive = false } = {}) {
+  const openExisting = existingMissions.filter((mission) => !isTerminal(mission.status))
+  const all = [...existingMissions, ...newMissions]
+  /** @type {Map<string, Mission>} */
+  const byId = new Map(all.map((mission) => [mission.id, mission]))
+
+  for (let i = 0; i < newMissions.length; i += 1) {
+    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 (!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
+    for (const other of openExisting) {
+      if (other.kind === 'survey') continue
+      if (!scopesOverlap(mission.scope, other.scope, { caseInsensitive })) continue
+      if (hasDependencyPath(byId, mission.id, other.id)) continue
+      addDependency(mission, other.id)
+    }
+  }
+}
+
+export { nextMissionNumber, addDependency, hasDependencyPath, assertAcyclic, addAutoDeps }

package/domain/read/enrichedMissions.js

@@ -0,0 +1,58 @@
+// Pure dashboard mission enrichment: select the latest review, project the
+// review view, and merge it into the mission summary. The worktree existence
+// check and `rev-parse HEAD` that detect a moved tip stay in
+// app/enrichedMissions.js.
+// @ts-check
+import { missionSummary } from '../summary.js'
+import { latestReview, reviewsForBranch } from '../integration/review.js'
+
+/** @typedef {import('../../types/index.js').Mission} Mission */
+/** @typedef {import('../../types/index.js').Review} Review */
+/** @typedef {import('../../types/index.js').TowerState} TowerState */
+
+/**
+ * Filter the missions the caller asked for, preserving state order.
+ * @param {Mission[]} missions
+ * @param {string[] | null | undefined} onlyIds
+ * @returns {Mission[]}
+ */
+export function missionsToEnrich(missions, onlyIds) {
+  const wanted = onlyIds ? new Set(onlyIds) : null
+  return wanted ? missions.filter((mission) => wanted.has(mission.id)) : missions
+}
+
+/**
+ * @param {TowerState} state
+ * @param {Mission} mission
+ * @returns {Review | null}
+ */
+export function latestReviewForMission(state, mission) {
+  const branch = mission.worktree ? mission.worktree.branch : null
+  return latestReview(reviewsForBranch(state.reviews, branch))
+}
+
+/**
+ * @param {object} input
+ * @param {Mission} input.mission
+ * @param {Review | null} input.latest
+ * @param {boolean} input.tipMoved
+ * @returns {object}
+ */
+export function enrichedMissionView({ mission, latest, tipMoved }) {
+  return {
+    ...missionSummary(mission),
+    review: latest
+      ? {
+          id: latest.id,
+          round: latest.round,
+          status: latest.status,
+          mergeVerdict: latest.mergeVerdict,
+          reviewer: latest.reviewer,
+          reviewerRole: latest.reviewerRole,
+          reviewedCommit: latest.reviewedCommit,
+          at: latest.at,
+        }
+      : null,
+    tipMoved,
+  }
+}

package/domain/read/missionContext.js

@@ -0,0 +1,53 @@
+// Pure mission-context projection: reviews, findings, and dependency statuses
+// for one mission. Loading state and activity stays in app/missionContext.js.
+// @ts-check
+import { fullMission, findingSummary } from '../summary.js'
+
+/** @typedef {import('../../types/index.js').Mission} Mission */
+/** @typedef {import('../../types/index.js').TowerState} TowerState */
+
+/**
+ * @param {object} input
+ * @param {TowerState} input.state
+ * @param {Mission} input.mission
+ * @returns {object}
+ */
+export function missionContextView({ state, mission }) {
+  const byId = new Map(state.missions.map((entry) => [entry.id, entry]))
+  const branch = mission.worktree ? mission.worktree.branch : null
+  const reviews = branch
+    ? (state.reviews ?? [])
+        .filter((review) => review.branch === branch)
+        .slice()
+        .sort((left, right) => right.round - left.round)
+        .slice(0, 3)
+    : []
+  const findings = (state.findings ?? [])
+    .filter((finding) => finding.missionId === mission.id)
+    .slice()
+    .sort((left, right) => (right.seq ?? 0) - (left.seq ?? 0))
+    .slice(0, 10)
+  return {
+    base: state.base,
+    mission: fullMission(mission),
+    snapshotCommit: state.snapshotCommit ?? null,
+    completionReport: mission.completionReport ?? null,
+    reviews: reviews.map((review) => ({
+      id: review.id,
+      round: review.round,
+      status: review.status,
+      mergeVerdict: review.mergeVerdict,
+      reviewer: review.reviewer,
+      findings: review.findings,
+      checks: review.checks ?? [],
+      decision: review.decision,
+      reviewedCommit: review.reviewedCommit,
+      at: review.at,
+    })),
+    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' }
+    }),
+  }
+}