dsh-tower 2.1.0 → 2.3.0

package/domain/integration/gate.js

@@ -123,11 +123,26 @@ export function baseDirtyBlocker(wouldOverwrite) {
     : null
 }
 
+/**
+ * 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.
+ * @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'
+}
+
 /**
  * @param {object} input
  * @param {string[]} input.deps
  * @param {TowerState} input.state
- * @param {Map<string, { status: string }>} [input.archived] compact archived missions (#73)
+ * @param {Map<string, { status: string, kind?: string }>} [input.archived] compact archived missions (#73)
  * @returns {Blocker[]}
  */
 export function dependencyBlockers({ deps = [], state, archived = new Map() }) {
@@ -135,7 +150,7 @@ export function dependencyBlockers({ deps = [], state, archived = new Map() }) {
   const blockers = []
   for (const depId of deps) {
     const dep = state.missions.find((entry) => entry.id === depId) ?? archived.get(depId)
-    if (!dep || !['merged', 'abandoned'].includes(dep.status)) {
+    if (!dependencySatisfied(dep)) {
       blockers.push({ code: 'deps-unmerged', detail: `${depId} is ${dep ? dep.status : 'missing'}` })
     }
   }

package/domain/integration/merge.js

@@ -3,6 +3,7 @@
 // writes, the state lock, and persistence stay in app/merge.js.
 // @ts-check
 import { isReviewExempt, latestReview, reviewsForBranch } from './review.js'
+import { mergedEvent } from '../events.js'
 
 /** @typedef {import('../../types/index.js').Mission} Mission */
 /** @typedef {import('../../types/index.js').Review} Review */
@@ -182,6 +183,40 @@ export function mergeSuccessNote(branchTip, base, newTip) {
   return `merged ${branchTip.slice(0, 7)} into ${base} as ${newTip.slice(0, 7)}`
 }
 
+/**
+ * Apply a successful two-phase merge to the mission draft and describe the
+ * domain fact, including the commit that landed. Persistence stays in
+ * app/merge.js at the commit phase.
+ * @param {{ mission: Mission, branchTip: string, base: string, newTip: string, now: number }} params
+ * @returns {{ state: Mission, events: Array<{ type: string, missionId: string, commit: string }> }}
+ */
+export function applyMergeSuccess({ mission, branchTip, base, newTip, now }) {
+  mission.status = 'merged'
+  mission.mergedAt = now
+  mission.mergedCommit = newTip
+  mission.updatedAt = now
+  mission.notes = mission.notes ?? []
+  mission.notes.push(mergeSuccessNote(branchTip, base, newTip))
+  return { state: mission, events: [mergedEvent(mission, newTip)] }
+}
+
+/**
+ * Apply an already-landed merge reconciliation to the mission draft. `note` is
+ * the evidence line the caller built from the observed commit and parents.
+ * @param {{ mission: Mission, mergedCommit: string, note: string, now: number }} params
+ * @returns {{ state: Mission, events: Array<{ type: string, missionId: string, commit: string }> }}
+ */
+export function applyLandedMerge({ mission, mergedCommit, note, now }) {
+  mission.status = 'merged'
+  mission.mergedAt = now
+  mission.mergedCommit = mergedCommit
+  mission.blockers = []
+  mission.notes = mission.notes ?? []
+  mission.notes.push(note)
+  mission.updatedAt = now
+  return { state: mission, events: [mergedEvent(mission, mergedCommit)] }
+}
+
 /**
  * @param {string} detail
  * @returns {string}

package/domain/lockBudget.js

@@ -0,0 +1,30 @@
+// Git-mutex budget policy (#93), shared by the app layer and the store
+// infrastructure (#69).
+//
+// The waiter behind the repo-scoped git mutex must outlast a merge that is
+// entitled to `mergeTimeoutMs`: a merge legally holds the mutex for its whole
+// plan.timeoutMs and then runs a few cheap evidence/cleanup git calls before
+// releasing it (#93). The budget is pure policy over the resolved Tower config,
+// so it lives in the domain rather than in an adapter; app/tower.js and
+// adapters/store.js both compute it from here.
+export const GIT_LOCK_MARGIN_MS = 60000
+
+/** The default merge timeout when a caller passes a config without `merge`. */
+export const DEFAULT_MERGE_TIMEOUT_MS = 900000
+
+/**
+ * @param {{ merge?: { timeoutMs?: number } } | null | undefined} config
+ * @param {number} [mergeTimeoutMs] the caller's resolved merge timeout
+ * @returns {number}
+ */
+export function gitLockTimeoutMs(config, mergeTimeoutMs) {
+  const explicit = Number(mergeTimeoutMs)
+  const configured = Number(config?.merge?.timeoutMs)
+  const base =
+    Number.isInteger(explicit) && explicit > 0
+      ? explicit
+      : Number.isInteger(configured) && configured > 0
+        ? configured
+        : DEFAULT_MERGE_TIMEOUT_MS
+  return base + GIT_LOCK_MARGIN_MS
+}

package/domain/missions/completion.js

@@ -4,6 +4,7 @@
 // Git, and persists the transition; the rules below are repository-free.
 // @ts-check
 import { TowerToolError } from '../errors.js'
+import { completedEvent } from '../events.js'
 
 /** @typedef {import('../../types/index.js').Mission} Mission */
 /** @typedef {import('../../types/index.js').RosterEntry} RosterEntry */
@@ -165,3 +166,16 @@ export function completionReport({ report, worker, checks, now, maxReportBytes }
   const text = report.trim()
   return { report: text, reportBytes: assertReportSize(text, maxReportBytes), by: worker.name, at: now, checks }
 }
+
+/**
+ * Apply the completion transition to the mission draft and describe the domain
+ * fact. Persistence stays in app/checkCompletion.js.
+ * @param {{ mission: Mission, report: any, now: number }} params
+ * @returns {{ state: Mission, events: Array<{ type: string, missionId: string }> }}
+ */
+export function applyCompletion({ mission, report, now }) {
+  mission.status = 'completed'
+  mission.completionReport = report
+  mission.updatedAt = now
+  return { state: mission, events: [completedEvent(mission)] }
+}

package/domain/missions/lifecycle.js

@@ -5,6 +5,7 @@
 // in-memory mission draft it is given.
 // @ts-check
 import { TowerToolError } from '../errors.js'
+import { abandonedEvent, completedEvent } from '../events.js'
 import { MISSION_STATUSES, TERMINAL_STATUSES, canTransition, pauseCauseError } from '../mission.js'
 import { normalizeScope, scopesOverlap } from '../scope.js'
 
@@ -62,9 +63,10 @@ export function assertMissionActor(mission, actor, input) {
 
 /**
  * Apply one validated `tower_mission` patch to the mission draft and return
- * the human-readable change list used by the activity log.
+ * the human-readable change list used by the activity log plus the domain
+ * events the transition describes.
  * @param {{ mission: Mission, state: TowerState, input: any, config: any }} params
- * @returns {{ changes: string[] }}
+ * @returns {{ state: Mission, changes: string[], events: Array<{ type: string, missionId: string }> }}
  */
 export function applyMissionUpdate({ mission, state, input, config }) {
   const actor = input.actor ?? { name: 'tower', role: 'tower' }
@@ -77,6 +79,8 @@ export function applyMissionUpdate({ mission, state, input, config }) {
   }
   /** @type {string[]} */
   const changes = []
+  /** @type {Array<{ type: string, missionId: string }>} */
+  const events = []
 
   if (input.status !== undefined) {
     if (typeof input.status !== 'string' || !MISSION_STATUSES.includes(input.status)) {
@@ -104,6 +108,8 @@ export function applyMissionUpdate({ mission, state, input, config }) {
     }
     mission.status = input.status
     changes.push(`status=${input.status}`)
+    if (input.status === 'completed') events.push(completedEvent(mission))
+    if (input.status === 'abandoned') events.push(abandonedEvent(mission))
   }
 
   if (input.task_done !== undefined) {
@@ -182,5 +188,5 @@ export function applyMissionUpdate({ mission, state, input, config }) {
   }
 
   if (changes.length === 0) fail('tower_mission requires at least one change')
-  return { changes }
+  return { state: mission, changes, events }
 }

package/domain/missions/plan.js

@@ -4,9 +4,11 @@
 // activity entry; everything here is deterministic and repository-free.
 // @ts-check
 import { TowerToolError } from '../errors.js'
+import { plannedEvents } from '../events.js'
 import { normalizeScope, validateTitle } from '../scope.js'
 
 /** @typedef {import('../../types/index.js').Mission} Mission */
+/** @typedef {import('../../types/index.js').TowerState} TowerState */
 
 /**
  * @param {string} message
@@ -147,3 +149,15 @@ export function newMission(id, input, now) {
     updatedAt: now,
   }))
 }
+
+/**
+ * Append the freshly projected missions to the state document and describe the
+ * resulting domain facts. Persistence and revision accounting stay in app/plan.
+ * @param {TowerState} state
+ * @param {Mission[]} created
+ * @returns {{ state: TowerState, events: Array<{ type: string, missionId: string }> }}
+ */
+export function applyPlan(state, created) {
+  state.missions.push(...created)
+  return { state, events: plannedEvents(created) }
+}

package/domain/missions/review.js

@@ -5,6 +5,7 @@
 // persistence. Everything here is deterministic and repository-free.
 // @ts-check
 import { TowerToolError } from '../errors.js'
+import { reviewedEvent } from '../events.js'
 import { MERGE_VERDICTS, REVIEW_STATUS_RE } from '../mission.js'
 
 /** @typedef {import('../../types/index.js').Mission} Mission */
@@ -109,11 +110,67 @@ export function assertReviewerSpawnTip(caller, tip) {
 }
 
 /**
- * Compute the review round and enforce the per-reviewer cap.
- * @param {{ reviews: Review[] | undefined, branch: string, reviewerName: string, maxRoundsPerReviewer: unknown }} params
+ * 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
+ * verdict (#108).
+ * @param {Review[]} reviews
+ * @returns {Review | null}
+ */
+function latestBranchReview(reviews) {
+  /** @type {Review | null} */
+  let latest = null
+  for (const review of reviews) {
+    if (!latest) {
+      latest = review
+      continue
+    }
+    const round = Number(review.round) || 0
+    const latestRound = Number(latest.round) || 0
+    if (round > latestRound) latest = review
+    else if (round === latestRound && (Number(review.seq) || 0) > (Number(latest.seq) || 0)) latest = review
+  }
+  return latest
+}
+
+/**
+ * Decide whether this submission starts a new review round or appends to the
+ * current one (#108). A completed mission always starts a new round. A mission
+ * that is `active` accepts a later route for the tip that its current round
+ * reviewed: the first non-clean verdict already returned it to `active`, and the
+ * remaining routes spawned against the same tip must still record their
+ * verdicts. A verdict for a tip that moved is rejected with an explanation.
+ * @param {{ mission: Mission, reviews: Review[] | undefined, branch: string, tip: string }} params
+ * @returns {{ appended: boolean, round: number | null }}
+ */
+export function reviewAdmission({ mission, reviews, branch, tip }) {
+  if (mission.status === 'completed') return { appended: false, round: null }
+  if (mission.status !== 'active') {
+    fail(`mission ${mission.id} is ${mission.status}; only a completed mission can be reviewed`)
+  }
+  const latest = latestBranchReview((reviews ?? []).filter((review) => review.branch === branch))
+  if (!latest) {
+    fail(`mission ${mission.id} is active and has no review round to append to; only a completed mission can be reviewed`)
+  }
+  if (latest.reviewedCommit !== tip) {
+    const cause =
+      latest.status === 'clean'
+        ? 'the reviewed tip moved'
+        : `review round ${latest.round} (${latest.status}) returned it to active and the reviewed tip moved`
+    fail(
+      `mission ${mission.id} is active: ${cause} (${String(latest.reviewedCommit).slice(0, 7)} -> ${tip.slice(0, 7)}); only review routes for the same reviewed tip can append to round ${latest.round} — return the mission to completed before starting a new round`,
+    )
+  }
+  return { appended: true, round: latest.round }
+}
+
+/**
+ * Compute the review round and enforce the per-reviewer cap. `round` joins the
+ * round `reviewAdmission` selected for an appended route; omitted, the
+ * submission opens the next round.
+ * @param {{ reviews: Review[] | undefined, branch: string, reviewerName: string, maxRoundsPerReviewer: unknown, round?: number | null }} params
  * @returns {{ reviewerRounds: number, round: number }}
  */
-export function reviewRound({ reviews, branch, reviewerName, maxRoundsPerReviewer }) {
+export function reviewRound({ reviews, branch, reviewerName, maxRoundsPerReviewer, round: sharedRound }) {
   const prior = (reviews ?? []).filter((review) => review.branch === branch)
   const reviewerRounds = prior.filter((review) => review.reviewer === reviewerName).length
   const maxReviewRounds = Number(maxRoundsPerReviewer) || MAX_REVIEW_ROUNDS
@@ -122,17 +179,28 @@ export function reviewRound({ reviews, branch, reviewerName, maxRoundsPerReviewe
       `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
+  const round = Number.isInteger(sharedRound)
+    ? /** @type {number} */ (sharedRound)
+    : 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
+ * clean verdict leaves the status untouched. An appended route records the
+ * verdict without flipping the status again (#108).
+ * @param {{ status: string, merge: string, round: number, reviewerName: string, appended?: boolean }} params
  * @returns {{ returnToActive: boolean, note: string }}
  */
-export function reviewOutcome({ status, merge, round, reviewerName }) {
+export function reviewOutcome({ status, merge, round, reviewerName, appended = false }) {
+  if (appended) {
+    return {
+      returnToActive: false,
+      note: `review round ${round} by ${reviewerName}: ${status} (${merge}) — appended to the same round; the mission stays active until it is re-completed`,
+    }
+  }
   if (status !== 'clean') {
     return {
       returnToActive: true,
@@ -142,6 +210,21 @@ export function reviewOutcome({ status, merge, round, reviewerName }) {
   return { returnToActive: false, note: `review round ${round} by ${reviewerName}: clean (${merge})` }
 }
 
+/**
+ * Apply a recorded review's mission-level effect to the draft and describe the
+ * domain fact. Persistence, the review record and the round accounting stay in
+ * app/review.js.
+ * @param {{ mission: Mission, outcome: { returnToActive: boolean, note: string }, now: number }} params
+ * @returns {{ state: Mission, events: Array<{ type: string, missionId: string }> }}
+ */
+export function applyReviewOutcome({ mission, outcome, now }) {
+  if (outcome.returnToActive) mission.status = 'active'
+  mission.notes = mission.notes ?? []
+  mission.notes.push(outcome.note)
+  mission.updatedAt = now
+  return { state: mission, events: [reviewedEvent(mission)] }
+}
+
 /**
  * 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

package/domain/read/views.js

@@ -40,6 +40,7 @@ export function missionDetailView({ state, mission, activity }) {
  * @param {object[]} input.missions enriched mission views
  * @param {number | null} [input.archivedMissions] archived mission count, or null when unreadable
  * @param {object} [input.archive] archive index view/diagnostic
+ * @param {{ held: boolean, pid?: number | null, phase?: string | null, heldMs?: number | null }} [input.gitLock]
  * @returns {object}
  */
 export function statusView({
@@ -51,6 +52,7 @@ export function statusView({
   missions,
   archivedMissions = 0,
   archive = null,
+  gitLock = { held: false },
 }) {
   /** @type {Record<string, number>} */
   const counts = {}
@@ -100,6 +102,7 @@ export function statusView({
     })),
     missions,
     archivedMissions,
+    gitLock,
     ...(archive ? { archive } : {}),
     activity,
   }

package/domain/state/archive.js

@@ -9,7 +9,7 @@
 // This module is pure: it declares the archive document contract, selects what
 // is eligible under the configured policy, and builds the records. Reading and
 // writing the files, and the lock that makes them atomic with state.json, live
-// in `lib/archive.js` and `app/archive.js`.
+// in `adapters/archive.js` and `app/archive.js`.
 // @ts-check
 import { isTerminal } from '../mission.js'
 

package/domain/state.js

@@ -8,7 +8,7 @@
 // `validateState` proves a document matches the *current* schema.
 // `prepareState` is the load-path decision: it inspects the version, applies the
 // ordered migration registry, then validates the target schema. Both are pure;
-// the side effects (backup, write, activity) live in `lib/stateFile.js`.
+// the side effects (backup, write, activity) live in `adapters/stateFile.js`.
 // @ts-check
 import { TowerToolError } from './errors.js'
 import { SCHEMA_VERSION } from './mission.js'

package/domain/surface.js

@@ -0,0 +1,248 @@
+// Concept budget: surface metrics, the committed baseline and its classifications (#84).
+//
+// The repository does not measure "how many concepts a user has to hold" by
+// counting lines. It measures the surface — config leaf keys, config sections and
+// registered tools — and keeps a committed baseline. Growth is refused by
+// default: a baseline decision that raises a count must name either an ADR (why
+// the surface has to grow) or deletions that are provably gone from the live
+// surface (the added concept replaced a removed one).
+//
+// This module is pure: no fs, no git. `scripts/surface-baseline.mjs` supplies
+// the live counts and the file reads; `scripts/lib/surface.mjs` wraps them.
+export const SURFACE_BASELINE_FILE = 'scripts/surface-baseline.json'
+export const SURFACE_CLASSIFICATION_FILE = 'docs/reference/surface-budget.md'
+export const SURFACE_KEYS = ['configKeys', 'sections', 'tools']
+export const CONFIG_CLASSES = ['core', 'tuning', 'niche']
+export const TOOL_CLASSES = ['core', 'optional']
+export const SURFACE_SCHEMA_VERSION = 1
+
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/
+
+/**
+ * The human-readable count line shared by `tower_doctor` and the generated
+ * references: `config keys: N · sections: N · tools: N`.
+ * @param {{ configKeys?: number, sections?: number, tools?: number }} counts
+ */
+export function surfaceLine(counts = {}) {
+  const value = (key) => (Number.isInteger(counts[key]) ? String(counts[key]) : '?')
+  return `config keys: ${value('configKeys')} · sections: ${value('sections')} · tools: ${value('tools')}`
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function surfaceError(message) {
+  return new Error(message)
+}
+
+/**
+ * Parse and validate `scripts/surface-baseline.json`. Throws with an actionable
+ * message when the file is malformed; returns a normalized copy otherwise.
+ * @param {string | object} source
+ */
+export function parseBaseline(source) {
+  let value
+  if (typeof source === 'string') {
+    try {
+      value = JSON.parse(source)
+    } catch (error) {
+      throw surfaceError(`surface baseline is not valid JSON: ${error?.message ?? error}`)
+    }
+  } else {
+    value = source
+  }
+  if (!isPlainObject(value)) throw surfaceError('surface baseline must be a JSON object')
+  if (value.schema !== undefined && value.schema !== SURFACE_SCHEMA_VERSION) {
+    throw surfaceError(`surface baseline schema ${value.schema} is not supported (expected ${SURFACE_SCHEMA_VERSION})`)
+  }
+  if (typeof value.date !== 'string' || !ISO_DATE.test(value.date)) {
+    throw surfaceError(`surface baseline needs a date (YYYY-MM-DD), got ${JSON.stringify(value.date)}`)
+  }
+  if (!isPlainObject(value.surfaces)) throw surfaceError('surface baseline needs a "surfaces" object')
+  const surfaces = {}
+  for (const key of SURFACE_KEYS) {
+    const entry = value.surfaces[key]
+    if (!isPlainObject(entry)) throw surfaceError(`surface baseline misses the "${key}" entry`)
+    if (!Number.isInteger(entry.seed) || entry.seed < 0) {
+      throw surfaceError(`surface baseline ${key}.seed must be a non-negative integer`)
+    }
+    if (!Number.isInteger(entry.value) || entry.value < 0) {
+      throw surfaceError(`surface baseline ${key}.value must be a non-negative integer`)
+    }
+    if (!Array.isArray(entry.decisions)) throw surfaceError(`surface baseline ${key}.decisions must be an array`)
+    surfaces[key] = {
+      seed: entry.seed,
+      value: entry.value,
+      decisions: entry.decisions.map((decision, index) => {
+        if (!isPlainObject(decision)) {
+          throw surfaceError(`surface baseline ${key}.decisions[${index}] must be an object`)
+        }
+        if (!Number.isInteger(decision.from) || decision.from < 0) {
+          throw surfaceError(`surface baseline ${key}.decisions[${index}].from must be a non-negative integer`)
+        }
+        if (!Number.isInteger(decision.to) || decision.to < 0) {
+          throw surfaceError(`surface baseline ${key}.decisions[${index}].to must be a non-negative integer`)
+        }
+        return { ...decision }
+      }),
+    }
+  }
+  return { schema: SURFACE_SCHEMA_VERSION, date: value.date, surfaces }
+}
+
+/**
+ * The rows of the classification table, already parsed. `kind` is `config` or
+ * `tools`, `name` is the key/tool name, `className` is the declared class.
+ * @param {string} markdown
+ */
+export function parseClassification(markdown) {
+  const text = String(markdown ?? '')
+  const dateMatch = /^\s*(?:[-*]\s*)?Decision date:\s*(\d{4}-\d{2}-\d{2})\s*$/im.exec(text)
+  const entries = []
+  let kind = null
+  for (const rawLine of text.split(/\r?\n/)) {
+    const heading = /^#{1,6}\s+(.+?)\s*$/.exec(rawLine)
+    if (heading) {
+      const title = heading[1].toLowerCase()
+      kind = title.includes('config') ? 'config' : title.includes('tool') ? 'tools' : null
+      continue
+    }
+    if (!kind) continue
+    const match = /^\|\s*`([^`]+)`\s*\|\s*([a-z-]+)\s*\|\s*(.*?)\s*\|\s*$/.exec(rawLine)
+    if (!match) continue
+    entries.push({ kind, name: match[1].trim(), className: match[2].trim().toLowerCase(), note: match[3].trim() })
+  }
+  return { date: dateMatch ? dateMatch[1] : null, entries }
+}
+
+/**
+ * Validate the classification table against the live surface. Every live key and
+ * tool must appear exactly once with a legal class; every `niche` row must carry
+ * a removal note, so "we will remove it later" is a written promise rather than
+ * an implication.
+ * @param {string} markdown
+ * @param {{ configKeys: string[], sections: string[], tools: string[] }} liveNames
+ * @param {{ baselineDate?: string }} [options]
+ * @returns {{ date: string | null, entries: Array<{ kind: string, name: string, className: string, note: string }>, findings: Array<{ code: string, level: string, message: string }> }}
+ */
+export function validateClassification(markdown, liveNames, options = {}) {
+  const parsed = parseClassification(markdown)
+  const findings = []
+  const text = String(markdown ?? '')
+  const record = (code, message) => findings.push({ code, level: 'error', message })
+  if (!parsed.date) {
+    record('classification-date', 'classification table needs a "Decision date: YYYY-MM-DD" line')
+  } else if (options.baselineDate && parsed.date !== options.baselineDate) {
+    record(
+      'classification-date',
+      `classification date ${parsed.date} does not match the baseline date ${options.baselineDate}`,
+    )
+  }
+
+  const checkRows = (kind, expected, legal) => {
+    const rows = parsed.entries.filter((entry) => entry.kind === kind)
+    const seen = new Map()
+    for (const row of rows) {
+      if (seen.has(row.name)) record('classification-duplicate', `${kind === 'config' ? 'config key' : 'tool'} ${row.name} is classified twice`)
+      seen.set(row.name, row)
+      if (!legal.includes(row.className)) {
+        record(
+          'classification-class',
+          `${kind === 'config' ? 'config key' : 'tool'} ${row.name} has class "${row.className}" (expected ${legal.join('/')})`,
+        )
+      }
+    }
+    for (const name of expected) {
+      if (!seen.has(name)) record('classification-missing', `${kind === 'config' ? 'config key' : 'tool'} ${name} is not classified`)
+    }
+    const expectedSet = new Set(expected)
+    for (const name of seen.keys()) {
+      if (!expectedSet.has(name)) record('classification-unknown', `${kind === 'config' ? 'config key' : 'tool'} ${name} is not in the live surface`)
+    }
+    return rows
+  }
+
+  const configRows = checkRows('config', liveNames.configKeys, CONFIG_CLASSES)
+  checkRows('tools', liveNames.tools, TOOL_CLASSES)
+  const nicheRows = configRows.filter((row) => row.className === 'niche')
+  for (const row of nicheRows) {
+    if (!/removal note:/i.test(row.note)) {
+      record('niche-removal-note', `niche config key ${row.name} needs a "Removal note:" in its table row`)
+    }
+  }
+  if (nicheRows.length === 0 && !/no key qualifies as niche/i.test(text)) {
+    record('niche-removal-note', 'no niche config key has a removal note and the table does not say "no key qualifies as niche"')
+  }
+  return { date: parsed.date, entries: parsed.entries, findings }
+}
+
+/**
+ * Validate a committed baseline against the live counts and its own decision
+ * chain. This is the brake: `current[surface] !== entry.value` fails, and every
+ * decision that grows a count must name an existing ADR or deletions that are
+ * provably absent from the live surface.
+ *
+ * @param {ReturnType<typeof parseBaseline>} baseline
+ * @param {{ configKeys: number, sections: number, tools: number, liveNames: { configKeys: string[], sections: string[], tools: string[] } }} current
+ * @param {{ exists?: (relativePath: string) => boolean }} [options]
+ * @returns {Array<{ code: string, level: string, message: string }>}
+ */
+export function validateBaseline(baseline, current, options = {}) {
+  const exists = options.exists ?? (() => false)
+  const findings = []
+  const record = (code, message) => findings.push({ code, level: 'error', message })
+
+  for (const key of SURFACE_KEYS) {
+    const entry = baseline.surfaces[key]
+    const live = current[key]
+    if (!Number.isInteger(live)) {
+      record('surface-missing', `live ${key} count is unavailable`)
+      continue
+    }
+    if (live !== entry.value) {
+      const direction = live > entry.value ? 'grew' : 'shrank'
+      record(
+        'stale-baseline',
+        `${key} ${direction} from the committed baseline ${entry.value} to ${live}; update ${SURFACE_BASELINE_FILE} with an ADR or a deletion record before landing`,
+      )
+    }
+    let running = entry.seed
+    entry.decisions.forEach((decision, index) => {
+      const where = `${key}.decisions[${index}]`
+      if (decision.from !== running) {
+        record('broken-chain', `${where}.from ${decision.from} does not continue from ${running}`)
+      }
+      if (decision.date !== undefined && !ISO_DATE.test(String(decision.date))) {
+        record('broken-chain', `${where}.date is not YYYY-MM-DD`)
+      }
+      const growth = decision.to - decision.from
+      if (growth > 0) {
+        const deletions = Array.isArray(decision.deletions)
+          ? decision.deletions.filter((name) => typeof name === 'string' && name.trim()).map((name) => name.trim())
+          : []
+        const adr = typeof decision.adr === 'string' && decision.adr.trim() ? decision.adr.trim().replace(/\\/g, '/') : null
+        const adrExists = Boolean(adr) && adr.startsWith('docs/adr/') && adr.endsWith('.md') && exists(adr)
+        const liveNames = new Set(current.liveNames?.[key] ?? [])
+        const stillLive = deletions.filter((name) => liveNames.has(name))
+        const deletionEvidence = deletions.length >= growth && stillLive.length === 0
+        if (!adrExists && !deletionEvidence) {
+          const reasons = []
+          if (adr && !adrExists) reasons.push(`ADR ${adr} does not exist under docs/adr/`)
+          if (deletions.length === 0) reasons.push('no deletions recorded')
+          else if (stillLive.length > 0) reasons.push(`deleted name(s) are still in the live surface: ${stillLive.join(', ')}`)
+          else if (deletions.length < growth) reasons.push(`only ${deletions.length} deletion(s) for a growth of ${growth}`)
+          record('growth-without-evidence', `${where} grows ${key} by ${growth} without an ADR or a matching deletion (${reasons.join('; ')})`)
+        }
+      }
+      running = decision.to
+    })
+    if (running !== entry.value && !(entry.decisions.length === 0 && entry.value < running)) {
+      record(
+        'broken-chain',
+        `${key} value ${entry.value} does not match the last decision (${running}); every count change needs a decision record`,
+      )
+    }
+  }
+  return findings
+}