@iceinvein/agent-skills 0.2.0 → 0.4.0

package/skills/migrate/scripts/gates/census.ts

@@ -0,0 +1,107 @@
+import { balanceOf, boundsOf, censusKey } from '../census.ts'
+import type { Census, Violation } from '../types.ts'
+import { isRecord } from '../validate.ts'
+import type { Gate } from './context.ts'
+
+// A hand-edited census.jsonl never passes through census-cmd.ts's
+// validateCensus call, so this is the only label available for a row that
+// fails the check below: its 1-based position in the file, plus (when kind
+// and the field censusKey needs both parse as strings) the same key
+// census-cmd.ts uses to identify a record, so the message points at
+// something the reader can find rather than an opaque line number alone.
+function censusRowLabel(raw: unknown, line: number): string {
+  const base = `census.jsonl line ${line}`
+  if (!isRecord(raw)) return base
+  const kind = raw.kind
+  if (kind === 'lens' && typeof raw.surface === 'string')
+    return `${base} (${censusKey(raw as Census)})`
+  if (kind === 'attribute' && typeof raw.subject === 'string')
+    return `${base} (${censusKey(raw as Census)})`
+  if (kind === 'rule-sweep' && typeof raw.subject === 'string')
+    return `${base} (${censusKey(raw as Census)})`
+  if (kind === 'closer' && typeof raw.closer === 'string')
+    return `${base} (${censusKey(raw as Census)})`
+  return base
+}
+
+// Gate 2: census shape, balance and presence. Rows are validated in runCheck,
+// not here, because gate 10 needs the same partition; this gate reports the
+// shape failures and does the arithmetic. A row that failed validation is
+// excluded from balanceOf, boundsOf, and the in_ledger + added reconciliation:
+// all three assume a well-formed record, so running them on one that already
+// failed shape validation would add confusing noise on top of the real defect
+// rather than a second independent fact.
+export const gate: Gate = (ctx): Violation[] => {
+  const violations: Violation[] = []
+  const surfacesWithCensus = new Set<string>()
+  const closersWithCensus = new Set<string>()
+
+  for (const row of ctx.censusRows) {
+    if (!row.ok) {
+      const label = censusRowLabel(row.raw, row.line)
+      for (const error of row.errors) {
+        violations.push({ gate: 'census', message: `${label}: ${error}` })
+      }
+      // A row that fails validation still ran and still named a surface or
+      // closer it claims to cover; only its shape is defective, not its
+      // existence. Registered defensively here (guarded the same way
+      // censusRowLabel is, since the row is not a trustworthy Census) so
+      // gate 2 does not also claim that surface or closer has no census
+      // record at all, which is a different and wrong accusation: that
+      // message means the lens never ran or never closed, not that it ran
+      // and produced something malformed. A row whose kind or identity
+      // field does not even parse as a string cannot make this claim, so it
+      // falls through to the genuinely-missing check below unregistered.
+      if (isRecord(row.raw)) {
+        if (row.raw.kind === 'lens' && typeof row.raw.surface === 'string') {
+          surfacesWithCensus.add(row.raw.surface)
+        } else if (row.raw.kind === 'closer' && typeof row.raw.closer === 'string') {
+          closersWithCensus.add(row.raw.closer)
+        }
+      }
+      continue
+    }
+    const record = row.record
+    const imbalance = balanceOf(record)
+    if (imbalance) violations.push({ gate: 'census', message: imbalance })
+    const outOfBounds = boundsOf(record)
+    if (outOfBounds) violations.push({ gate: 'census', message: outOfBounds })
+    if (record.kind === 'lens') {
+      surfacesWithCensus.add(record.surface)
+      // balanceOf only checks that the record's own numbers add up
+      // internally; nothing before this ties in_ledger + added to anything
+      // outside the record itself, so a lens census can balance perfectly
+      // while claiming a headcount elements.jsonl never received (total is
+      // self-reported and cannot be checked against anything, but in_ledger
+      // + added claims a specific number of rows now exist in the ledger
+      // for this surface, and that claim is directly countable).
+      const claimed = record.in_ledger + record.added
+      const actual = ctx.elements.filter((e) => e.surface === record.surface).length
+      if (actual !== claimed) {
+        violations.push({
+          gate: 'census',
+          message: `lens census for ${record.surface} claims in_ledger ${record.in_ledger} + added ${record.added} = ${claimed} element(s) in the ledger, but elements.jsonl has ${actual}`,
+        })
+      }
+    }
+    if (record.kind === 'closer') closersWithCensus.add(record.closer)
+  }
+
+  for (const surface of ctx.cfg.surfaces) {
+    if (!surfacesWithCensus.has(surface)) {
+      violations.push({
+        gate: 'census',
+        message: `declared surface ${surface} has no lens census record; the lens did not run or did not close`,
+      })
+    }
+  }
+  for (const closer of ctx.cfg.closers) {
+    if (!closersWithCensus.has(closer)) {
+      violations.push({
+        gate: 'census',
+        message: `declared closer ${closer} has no census record`,
+      })
+    }
+  }
+  return violations
+}

package/skills/migrate/scripts/gates/citations.ts

@@ -0,0 +1,11 @@
+import { resolveCitations } from '../citations.ts'
+import type { Violation } from '../types.ts'
+import type { Gate } from './context.ts'
+
+// Gate 7: citations. On unless explicitly disabled. An FR citing a path that
+// does not exist is the never-fabricate rule's only mechanical expression, so
+// it should not be something a run has to remember to ask for.
+export const gate: Gate = async (ctx): Promise<Violation[]> => {
+  if (!ctx.citations) return []
+  return resolveCitations(ctx.requirements, ctx.cfg.source.path)
+}

package/skills/migrate/scripts/gates/context.ts

@@ -0,0 +1,76 @@
+import type { Config } from '../config.ts'
+import type { LoadedHandoff } from '../handoff.ts'
+import type { StorePaths } from '../paths.ts'
+import type { Phase, PhaseState } from '../phases.ts'
+import type {
+  Capability,
+  Census,
+  Delta,
+  Element,
+  QueueItem,
+  Requirement,
+  Violation,
+} from '../types.ts'
+
+// One census.jsonl row, validated, in file order. A failed row keeps its raw
+// value and 1-based line: the line is the only label a hand-edited row has,
+// and the raw value still names the surface or closer the row claims to
+// cover, which gate 2 registers so it does not also report that surface as
+// having no census record at all.
+//
+// Kept as one ordered list rather than split into valid and invalid halves,
+// because gate 2 reports both kinds and its message order follows the file.
+// Splitting them would group every shape error ahead of every arithmetic
+// error, which reorders the output for any store holding both.
+export type CensusRow =
+  | { ok: true; line: number; record: Census }
+  | { ok: false; line: number; raw: unknown; errors: string[] }
+
+export function validCensus(rows: CensusRow[]): Census[] {
+  const out: Census[] = []
+  for (const row of rows) {
+    if (row.ok) out.push(row.record)
+  }
+  return out
+}
+
+// Everything the gates read, loaded once by runCheck and handed to each gate
+// unchanged. A gate is a pure function of this record: it may not read the
+// filesystem for store content, so the store is parsed exactly once per run
+// no matter how many gates consult it.
+//
+// `censusRows` is the one field this record does work for rather than merely
+// carrying. validateCensus runs once, in runCheck, because two gates need the
+// result and neither should re-derive it: gate 2 reports the shape failures
+// and does the balance arithmetic, and gate 10 cross-checks the valid records'
+// batch fields against phases.json. Before the split those two shared a local
+// variable inside one function; this is what replaces that sharing without
+// making one gate depend on another having run first.
+export type GateContext = {
+  root: string
+  cfg: Config
+  paths: StorePaths
+  elements: Element[]
+  requirements: Requirement[]
+  capabilities: Capability[]
+  deltas: Delta[]
+  censusRows: CensusRow[]
+  // Loaded lazily, immediately before the handoff gate runs, because it is the
+  // only gate that reads it and a corrupt file must not break the others.
+  // `undefined` means "not loaded yet"; every other state is a LoadedHandoff.
+  handoff: LoadedHandoff | undefined
+  queueItems: QueueItem[]
+  queueErrors: string[]
+  phases: Record<Phase, PhaseState>
+  // The index in PHASES of the last phase this invocation gates. Only the
+  // run-state gate reads it today; every other gate reads the whole store
+  // regardless, because a coverage or census gap is a real failure whenever it
+  // is found rather than only once the run claims to have reached that phase.
+  // An index rather than a name, because both consumers compare positions.
+  terminusIndex: number
+  citations: boolean
+  leaks: boolean
+  gitBin: string
+}
+
+export type Gate = (ctx: GateContext) => Violation[] | Promise<Violation[]>

package/skills/migrate/scripts/gates/coverage.ts

@@ -0,0 +1,22 @@
+import type { Violation } from '../types.ts'
+import type { Gate } from './context.ts'
+
+// Gate 1: coverage. Every element must carry a terminal disposition.
+//
+// The summary line runCheck returns ("612/612 mapped, ...") counts the same
+// three dispositions this gate walks, but it is built in check.ts rather than
+// here, because report-cmd.ts reads it out of CheckResult on a store that is
+// expected to have violations. A gate returns violations; the summary is a
+// property of the run.
+export const gate: Gate = (ctx): Violation[] => {
+  const violations: Violation[] = []
+  for (const el of ctx.elements) {
+    if (el.disposition.kind === 'mapped') continue
+    if (el.disposition.kind === 'out-of-scope') continue
+    violations.push({
+      gate: 'coverage',
+      message: `${el.id} (${el.surface}) is still unaccounted`,
+    })
+  }
+  return violations
+}

package/skills/migrate/scripts/gates/deltas.ts

@@ -0,0 +1,15 @@
+import type { Violation } from '../types.ts'
+import type { Gate } from './context.ts'
+
+// Gate 5: deltas. A sanctioned delta is only sanctioned once an owner has
+// signed it; an unsigned row at gate time is a difference from the source
+// nobody agreed to.
+export const gate: Gate = (ctx): Violation[] => {
+  const violations: Violation[] = []
+  for (const delta of ctx.deltas) {
+    if (!delta.owner_signed) {
+      violations.push({ gate: 'deltas', message: `${delta.id} is not owner-signed` })
+    }
+  }
+  return violations
+}

package/skills/migrate/scripts/gates/handoff.ts

@@ -0,0 +1,145 @@
+import type { Violation } from '../types.ts'
+import type { Gate } from './context.ts'
+
+// Gate 12: handoff. Whether the ratified requirements actually reached the
+// emitted work.
+//
+// This is what stops a plain `migrate check` from meaning no more than "the
+// phases are marked done". Every other gate proves the store is internally
+// consistent about phases 0 through 5, and gate 10 asks whether the run
+// happened; without this one, a store could pass with handoff.json absent and
+// nothing emitted anywhere at all.
+//
+// The honest limit is the same in kind as gate 10's. This proves the emitted
+// work covers the store's requirements. It cannot prove the issues were read
+// or the roadmap was believed.
+export const gate: Gate = (ctx): Violation[] => {
+  const violations: Violation[] = []
+  const loaded = ctx.handoff
+  if (!loaded || loaded.kind === 'absent') {
+    return [
+      {
+        gate: 'handoff',
+        message:
+          'no handoff.json in the store; handoff has not run, so nothing has reached a delivery medium',
+      },
+    ]
+  }
+  if (loaded.kind === 'invalid') {
+    // A present-but-unusable file is a different fact from an absent one, and
+    // saying "handoff has not run" about a file that exists would send an
+    // operator to re-run the command rather than to look at what is in it.
+    return loaded.errors.map((e) => ({
+      gate: 'handoff',
+      message: `handoff.json ${e}`,
+    }))
+  }
+  const handoff = loaded.value
+
+  const known = new Set(ctx.requirements.map((r) => r.id))
+  const keys = new Set(handoff.items.map((i) => i.key))
+  const emittedIds = new Set<string>()
+  const seenKeys = new Set<string>()
+  const seenFrs = new Set<string>()
+
+  for (const item of handoff.items) {
+    // Two work items under one key make `refs`, `dependsOn` and the coverage
+    // order all ambiguous, and a Set of keys hides the collision from every
+    // check below it.
+    if (seenKeys.has(item.key)) {
+      violations.push({
+        gate: 'handoff',
+        message: `work item key ${item.key} appears more than once`,
+      })
+    }
+    seenKeys.add(item.key)
+    if (handoff.refs[item.key] === undefined) {
+      // `refs` is the only evidence in this file that anything actually
+      // reached the medium; every adapter writes one entry per item.
+      violations.push({
+        gate: 'handoff',
+        message: `work item ${item.key} has no entry in refs, so nothing records where it was emitted`,
+      })
+    }
+    for (const fr of item.frs) {
+      if (seenFrs.has(fr)) {
+        // The emitted count is a sum over frs lengths while membership is a
+        // set, so without this one requirement in two work items satisfies
+        // both and is delivered twice.
+        violations.push({
+          gate: 'handoff',
+          message: `requirement ${fr} appears in more than one work item`,
+        })
+      }
+      seenFrs.add(fr)
+      emittedIds.add(fr)
+      if (!known.has(fr)) {
+        violations.push({
+          gate: 'handoff',
+          message: `work item ${item.key} names requirement ${fr}, which is not in the registry`,
+        })
+      }
+    }
+    for (const dep of item.dependsOn) {
+      if (dep === item.key) {
+        violations.push({
+          gate: 'handoff',
+          message: `work item ${item.key} depends on itself`,
+        })
+      } else if (!keys.has(dep)) {
+        violations.push({
+          gate: 'handoff',
+          message: `work item ${item.key} depends on ${dep}, which is not a work item`,
+        })
+      }
+    }
+  }
+
+  // basis.order drives coverage's whole per-capability walk, so an order that
+  // does not match the emitted items makes coverage report a denominator
+  // narrower than the store without saying so.
+  for (const slug of handoff.basis.order) {
+    if (!keys.has(slug)) {
+      violations.push({
+        gate: 'handoff',
+        message: `handoff basis order names ${slug}, which is not a work item`,
+      })
+    }
+  }
+  for (const key of keys) {
+    if (!handoff.basis.order.includes(key)) {
+      violations.push({
+        gate: 'handoff',
+        message: `work item ${key} is missing from the handoff basis order, so coverage would not count it`,
+      })
+    }
+  }
+
+  // Every requirement, not only the confirmed ones. An inferred requirement is
+  // something the build team must see and decide about, so handoff emits it;
+  // confidence starts mattering at the coverage denominator, not here.
+  for (const r of ctx.requirements) {
+    if (!emittedIds.has(r.id)) {
+      violations.push({
+        gate: 'handoff',
+        message: `${r.id} appears in no work item; re-run migrate handoff after the store changed`,
+      })
+    }
+  }
+
+  const confirmed = ctx.requirements.filter((r) => r.confidence.kind === 'confirmed').length
+  if (handoff.basis.confirmed !== confirmed) {
+    violations.push({
+      gate: 'handoff',
+      message: `handoff basis records ${handoff.basis.confirmed} confirmed requirement(s), but the store has ${confirmed}`,
+    })
+  }
+  const emitted = handoff.items.reduce((n, i) => n + i.frs.length, 0)
+  if (handoff.basis.emitted !== emitted) {
+    violations.push({
+      gate: 'handoff',
+      message: `handoff basis records ${handoff.basis.emitted} emitted requirement(s), but its work items carry ${emitted}`,
+    })
+  }
+  return violations
+}

package/skills/migrate/scripts/gates/leaks.ts

@@ -0,0 +1,11 @@
+import { scanLeaks } from '../leaks.ts'
+import type { Violation } from '../types.ts'
+import type { Gate } from './context.ts'
+
+// Gate 8: leaks, opt-in. Unlike citations, the scan shells out to `git log -S`
+// per secret and its cost scales with history depth rather than with store
+// size, which is why it stays behind a flag while citations do not.
+export const gate: Gate = async (ctx): Promise<Violation[]> => {
+  if (!ctx.leaks) return []
+  return scanLeaks({ root: ctx.root, gitBin: ctx.gitBin })
+}

package/skills/migrate/scripts/gates/parity.ts

@@ -0,0 +1,15 @@
+import type { Violation } from '../types.ts'
+import type { Gate } from './context.ts'
+
+// Gate 6: parity coverage. A requirement whose confidence is `queued` is
+// waiting on an owner decision, so it is not yet expected to carry a parity
+// plan; every other requirement is.
+export const gate: Gate = (ctx): Violation[] => {
+  const violations: Violation[] = []
+  for (const req of ctx.requirements) {
+    if (req.confidence.kind !== 'queued' && req.parity === null) {
+      violations.push({ gate: 'parity', message: `${req.id} has no parity plan` })
+    }
+  }
+  return violations
+}

package/skills/migrate/scripts/gates/queue.ts

@@ -0,0 +1,9 @@
+import type { Violation } from '../types.ts'
+import type { Gate } from './context.ts'
+
+// Gate 4: queue grammar. loadQueue does the parsing and collects one error
+// string per grammar violation; this gate only labels them, because a queue
+// file that will not parse is equally a problem for `queue list`, `report`
+// and `adjudicate`, all of which call loadQueue directly.
+export const gate: Gate = (ctx): Violation[] =>
+  ctx.queueErrors.map((message) => ({ gate: 'queue', message }))

package/skills/migrate/scripts/gates/refs.ts

@@ -0,0 +1,97 @@
+import type { Violation } from '../types.ts'
+import type { Gate } from './context.ts'
+
+// A duplicate id or slug within one store file is a real defect the refs
+// gate must catch on its own, not something it can assume another gate or
+// command already ruled out: `import reqs` upserts by id, but
+// capabilities.jsonl has no import path at all today, so hand-editing is
+// currently the only way a row lands there, and nothing stops two rows
+// from hand-editing into the same identity with different content. A
+// gate whose soundness depends on another gate having run first is not
+// independently a gate. Counted off the raw row arrays, not a `Set`:
+// a `Set` collapses duplicates by construction, which is exactly the
+// evidence (which id, how many rows) this check exists to preserve.
+function duplicatesOf(values: string[]): Map<string, number> {
+  const counts = new Map<string, number>()
+  for (const v of values) counts.set(v, (counts.get(v) ?? 0) + 1)
+  const dups = new Map<string, number>()
+  for (const [v, count] of counts) {
+    if (count > 1) dups.set(v, count)
+  }
+  return dups
+}
+
+// Gate 3: referential integrity.
+export const gate: Gate = (ctx): Violation[] => {
+  const violations: Violation[] = []
+  const reqIds = new Set(ctx.requirements.map((r) => r.id))
+  const elementIds = new Set(ctx.elements.map((e) => e.id))
+  const capSlugs = new Set(ctx.capabilities.map((c) => c.slug))
+  const queueIds = new Set(ctx.queueItems.map((q) => q.id))
+
+  for (const [id, count] of duplicatesOf(ctx.requirements.map((r) => r.id))) {
+    violations.push({
+      gate: 'refs',
+      message: `requirement id ${id} appears ${count} times in requirements.jsonl`,
+    })
+  }
+  for (const [slug, count] of duplicatesOf(ctx.capabilities.map((c) => c.slug))) {
+    violations.push({
+      gate: 'refs',
+      message: `capability slug ${slug} appears ${count} times in capabilities.jsonl`,
+    })
+  }
+  for (const [id, count] of duplicatesOf(ctx.elements.map((e) => e.id))) {
+    violations.push({
+      gate: 'refs',
+      message: `element id ${id} appears ${count} times in elements.jsonl`,
+    })
+  }
+
+  // `field` names where the queue reference came from (`disposition.queue`,
+  // `confidence.queue`, `parity.queue`) so that one requirement citing the
+  // same missing queue id from two different fields produces two
+  // violations that read as two distinct citations to fix, not one
+  // ambiguous duplicate-looking line.
+  const needQueue = (id: string, owner: string, field: string): void => {
+    if (!queueIds.has(id)) {
+      violations.push({
+        gate: 'refs',
+        message: `${owner} references queue item ${id} via ${field}, which does not exist`,
+      })
+    }
+  }
+  for (const el of ctx.elements) {
+    if (el.disposition.kind === 'mapped' && !reqIds.has(el.disposition.fr)) {
+      violations.push({
+        gate: 'refs',
+        message: `${el.id} is mapped to ${el.disposition.fr}, which is not in the registry`,
+      })
+    }
+    if (el.disposition.kind === 'out-of-scope') {
+      needQueue(el.disposition.queue, el.id, 'disposition.queue')
+    }
+  }
+  for (const req of ctx.requirements) {
+    if (!capSlugs.has(req.cap)) {
+      violations.push({
+        gate: 'refs',
+        message: `${req.id} names capability ${req.cap}, which is not in the partition`,
+      })
+    }
+    if (req.confidence.kind === 'queued')
+      needQueue(req.confidence.queue, req.id, 'confidence.queue')
+    if (req.parity?.kind === 'rubric' && req.parity.level !== 'high') {
+      needQueue(req.parity.queue, req.id, 'parity.queue')
+    }
+    for (const ref of req.citations) {
+      if (ref.kind === 'ledger' && !elementIds.has(ref.id)) {
+        violations.push({
+          gate: 'refs',
+          message: `${req.id} cites ledger id ${ref.id}, which is not in the ledger`,
+        })
+      }
+    }
+  }
+  return violations
+}

package/skills/migrate/scripts/gates/run-state.ts

@@ -0,0 +1,67 @@
+import { PHASES, type Phase } from '../phases.ts'
+import type { Violation } from '../types.ts'
+import { type Gate, validCensus } from './context.ts'
+
+// Gate 10: run-state. Every other gate proves the store is internally
+// consistent, which an empty store satisfies. This one asks whether the run
+// that was supposed to fill it actually happened, which is the only reason
+// exit 0 can mean "complete" rather than "nothing contradicts anything".
+export const gate: Gate = (ctx): Violation[] => {
+  const violations: Violation[] = []
+  const terminusName = PHASES[ctx.terminusIndex]
+
+  for (let i = 0; i <= ctx.terminusIndex; i++) {
+    const p = PHASES[i]
+    if (!p) continue
+    const status = ctx.phases[p].status
+    if (status !== 'done') {
+      violations.push({
+        gate: 'run-state',
+        message: `phase ${p} is ${status}; every phase through ${terminusName} must be done`,
+      })
+    }
+  }
+
+  // Checked across all eight phases, not just up to the terminus: a later
+  // phase marked done over a pending predecessor is hand-edited state, and it
+  // is worth naming whether or not the caller asked about that phase.
+  for (let i = 1; i < PHASES.length; i++) {
+    const current = PHASES[i]
+    const previous = PHASES[i - 1]
+    if (!current || !previous) continue
+    if (ctx.phases[current].status === 'done' && ctx.phases[previous].status === 'pending') {
+      violations.push({
+        gate: 'run-state',
+        message: `phase ${current} is done while ${previous} is still pending`,
+      })
+    }
+  }
+
+  // A census record naming a batch phases.json never committed means the two
+  // disagree about what happened. Only checked when the record exists, since
+  // gate 2 already names a declared surface or closer that has none.
+  const committedIn = (phase: Phase): Set<string> =>
+    new Set(ctx.phases[phase].batches.map((b) => b.id))
+  const census = validCensus(ctx.censusRows)
+  const enumerateBatches = committedIn('enumerate')
+  for (const surface of ctx.cfg.surfaces) {
+    const record = census.find((r) => r.kind === 'lens' && r.surface === surface)
+    if (record && !enumerateBatches.has(record.batch)) {
+      violations.push({
+        gate: 'run-state',
+        message: `lens census for ${surface} names batch ${record.batch}, which phases.json has no record of committing in enumerate`,
+      })
+    }
+  }
+  const extractBatches = committedIn('extract')
+  for (const closer of ctx.cfg.closers) {
+    const record = census.find((r) => r.kind === 'closer' && r.closer === closer)
+    if (record && !extractBatches.has(record.batch)) {
+      violations.push({
+        gate: 'run-state',
+        message: `closer census for ${closer} names batch ${record.batch}, which phases.json has no record of committing in extract`,
+      })
+    }
+  }
+  return violations
+}

package/skills/migrate/scripts/gates/source.ts

@@ -0,0 +1,28 @@
+import { existsSync } from 'node:fs'
+import type { Violation } from '../types.ts'
+import type { Gate } from './context.ts'
+
+async function sourceIsDirty(sourcePath: string, gitBin: string): Promise<boolean> {
+  if (!existsSync(`${sourcePath}/.git`)) return false
+  const proc = Bun.spawn([gitBin, 'status', '--porcelain'], {
+    cwd: sourcePath,
+    stdout: 'pipe',
+    stderr: 'ignore',
+  })
+  const out = await new Response(proc.stdout).text()
+  await proc.exited
+  return out.trim().length > 0
+}
+
+// Gate 9: source integrity. A source that is not a git checkout cannot be
+// checked this way and is not reported as a violation; the CLI's own refusal
+// to write any path under the source root is what covers that case.
+export const gate: Gate = async (ctx): Promise<Violation[]> => {
+  if (!(await sourceIsDirty(ctx.cfg.source.path, ctx.gitBin))) return []
+  return [
+    {
+      gate: 'source',
+      message: `the source checkout at ${ctx.cfg.source.path} has uncommitted changes; it must stay read-only`,
+    },
+  ]
+}