@iceinvein/agent-skills 0.1.39 → 0.2.0

package/skills/migrate/scripts/queue-cmd.ts

@@ -0,0 +1,98 @@
+import { copyFile, mkdir } from 'node:fs/promises'
+import { basename, join } from 'node:path'
+import { loadConfig } from './config.ts'
+import { assertNotUnderSource, storePaths } from './paths.ts'
+import { isMissingFrontmatter, loadQueue, parseQueueItem } from './queue.ts'
+import { readTextFile } from './store.ts'
+
+export async function runQueue(opts: { root: string; args: string[] }): Promise<number> {
+  const [verb, ...rest] = opts.args
+  const cfg = await loadConfig(opts.root)
+  const queueDir = storePaths(opts.root).queueDir
+
+  if (verb === 'add') {
+    const file = rest[0]
+    if (!file) {
+      process.stderr.write('queue add: missing <file.md>\n')
+      return 2
+    }
+    let text: string
+    try {
+      text = await readTextFile(file)
+    } catch (e) {
+      // Missing file, a directory passed as a file, or an unreadable file:
+      // the request can never be serviced, the same usage-error class as
+      // import-cmd.ts's and census-cmd.ts's readJsonFile catch.
+      process.stderr.write(`queue add: ${(e as Error).message}\n`)
+      return 2
+    }
+    const dest = join(queueDir, basename(file))
+    const parsed = parseQueueItem(text, dest)
+    if (!parsed.ok) {
+      for (const e of parsed.errors) process.stderr.write(`queue add: ${e}\n`)
+      // No frontmatter at all belongs to the same usage-error class as the
+      // read failure above; every other grammar violation (bad severity, a
+      // missing or empty section, a filename/id mismatch, an adjudicated
+      // item with no ruling) is a well-formed file with bad content -- a
+      // content failure instead.
+      return isMissingFrontmatter(parsed.errors) ? 2 : 1
+    }
+    try {
+      await assertNotUnderSource(dest, cfg.source.path)
+    } catch (e) {
+      // A store whose configured source.path resolves to include its own
+      // queue directory (e.g. source.path: '.') can never be written to,
+      // for any well-formed item whatsoever: an environment/config
+      // problem, invariant across every possible file, not a property of
+      // this item's own content, so it is a usage error (2), not the
+      // content failure (1) returned just above for a bad grammar.
+      process.stderr.write(`queue add: ${(e as Error).message}\n`)
+      return 2
+    }
+    await mkdir(queueDir, { recursive: true })
+    await copyFile(file, dest)
+    process.stdout.write(`queue add: ${parsed.value.id} [${parsed.value.severity}]\n`)
+    return 0
+  }
+
+  if (verb === 'list') {
+    const openOnly = rest.includes('--open')
+    const { items, errors } = await loadQueue(queueDir)
+    for (const e of errors) process.stderr.write(`queue: ${e}\n`)
+    const shown = openOnly ? items.filter((i) => i.status === 'open') : items
+    for (const item of shown) {
+      process.stdout.write(`${item.id}\t${item.severity}\t${item.status}\n`)
+    }
+    process.stdout.write(`${shown.length} item(s)\n`)
+    return errors.length > 0 ? 1 : 0
+  }
+
+  if (verb === 'show') {
+    const id = rest[0]
+    if (!id) {
+      process.stderr.write('queue show: missing <id>\n')
+      return 2
+    }
+    const { items } = await loadQueue(queueDir)
+    const item = items.find((i) => i.id === id)
+    if (!item) {
+      process.stderr.write(`queue show: no item ${id}\n`)
+      return 1
+    }
+    let text: string
+    try {
+      text = await readTextFile(item.path)
+    } catch (e) {
+      // The item was in the index a moment ago; its file vanishing or
+      // becoming unreadable between load and show is a domain failure on an
+      // otherwise well-formed request, not a malformed one.
+      process.stderr.write(`queue show: ${(e as Error).message}\n`)
+      return 1
+    }
+    process.stdout.write(text)
+    return 0
+  }
+
+  process.stderr.write('queue: want add <file.md> | list [--open] | show <id>\n')
+  return 2
+}

package/skills/migrate/scripts/queue.ts

@@ -0,0 +1,258 @@
+import { existsSync } from 'node:fs'
+import { readdir } from 'node:fs/promises'
+import { basename, join } from 'node:path'
+import { isValidSlug } from './ids.ts'
+import { readTextFile } from './store.ts'
+import type { QueueItem, Severity } from './types.ts'
+
+const SEVERITIES: Severity[] = ['critical', 'moderate', 'minor']
+const SECTIONS = ['Evidence', 'Options', 'Recommendation'] as const
+
+// A file with no --- frontmatter block at all never gets far enough to be
+// treated as a queue item; the message below is the sole diagnostic on that
+// path (see parseQueueItem). isMissingFrontmatter lets callers tell that
+// case apart from every other grammar violation.
+const NO_FRONTMATTER = 'missing --- frontmatter block'
+
+export type ParsedQueue = { ok: true; value: QueueItem } | { ok: false; errors: string[] }
+
+// Files authored on Windows commonly carry a leading byte-order mark and/or
+// CRLF line endings; neither changes the file's actual content, so both are
+// normalized away before any grammar check runs. Nothing further: no other
+// encoding normalization is in scope.
+function normalizeText(text: string): string {
+  const noBom = text.startsWith('\uFEFF') ? text.slice(1) : text
+  return noBom.replace(/\r\n/g, '\n')
+}
+
+function splitFrontmatter(text: string): { fm: Record<string, string>; body: string } | null {
+  if (!text.startsWith('---\n')) return null
+  const end = text.indexOf('\n---', 3)
+  if (end === -1) return null
+  const fmText = text.slice(4, end)
+  const body = text.slice(end + 4).replace(/^\n/, '')
+  const fm: Record<string, string> = {}
+  for (const line of fmText.split('\n')) {
+    const at = line.indexOf(':')
+    if (at === -1) continue
+    fm[line.slice(0, at).trim()] = line.slice(at + 1).trim()
+  }
+  return { fm, body }
+}
+
+type Heading = { name: string; start: number; end: number }
+
+// Only a line that starts with exactly '## ' (two hashes, one space, at the
+// very start of a line) counts as a section heading. Requiring exactly two
+// hashes at the true start of the line means '### Options' (one hash too
+// many) or '#Options' (too few), or an indented/blockquoted/tab-indented
+// '##' line, are ordinary body text, not headings: a level typo can no
+// longer be mistaken for a real heading, corrupt a neighboring section's
+// content, or silently stand in for a missing one.
+const HEADING_LINE = /^## (.+)$/
+
+// A fenced code block (three or more backticks, or three or more tildes, at
+// the start of a line once surrounding whitespace is trimmed) hides
+// everything inside it from heading detection: a pasted shell script's
+// '## Section' comments, a quoted markdown file, or a diff are Evidence
+// content, not document structure, and must not be mistaken for one. This
+// is deliberately not a conforming CommonMark fence parser -- no info
+// string handling, no requirement that a closing fence be at least as long
+// as the one that opened it -- it only needs to stop quoted code from
+// reading as a heading, which a same-character open/close toggle already
+// does; a fence line of the other character (e.g. a '~~~' divider inside a
+// backtick-fenced block) does not close it.
+const FENCE_LINE = /^(`{3,}|~{3,})/
+
+type HeadingScan = {
+  headings: Heading[]
+  // The 1-indexed body line where an opening fence was never matched by a
+  // closing one, or null if every fence (if any) closed. A null-vs-number
+  // result, not a boolean, so the error message can point at exactly where
+  // the unterminated fence began.
+  unclosedFenceAt: number | null
+}
+
+function findHeadings(body: string): HeadingScan {
+  const headings: Heading[] = []
+  const lines = body.split('\n')
+  let fenceChar: string | null = null
+  let fenceStartLine: number | null = null
+  let offset = 0
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] ?? ''
+    const fenceMatch = FENCE_LINE.exec(line.trim())
+    if (fenceMatch) {
+      const ch = fenceMatch[1]?.[0] ?? ''
+      if (fenceChar === null) {
+        fenceChar = ch
+        fenceStartLine = i + 1
+      } else if (ch === fenceChar) {
+        fenceChar = null
+        fenceStartLine = null
+      }
+      // A fence line of the other character while already inside a fence
+      // is just content (e.g. a '~~~' rule inside a backtick block): no
+      // state change, and it can never look like a heading anyway.
+    } else if (fenceChar === null) {
+      const m = HEADING_LINE.exec(line)
+      if (m) {
+        headings.push({ name: (m[1] ?? '').trim(), start: offset, end: offset + line.length })
+      }
+    }
+    offset += line.length + 1
+  }
+  return { headings, unclosedFenceAt: fenceChar === null ? null : fenceStartLine }
+}
+
+type SectionResult = { kind: 'ok'; text: string } | { kind: 'missing' } | { kind: 'duplicate' }
+
+// A section is identified by an exact, case-sensitive, line-anchored
+// '## <name>' heading. Zero matches is a missing section; more than one is
+// a duplicate, reported as an error rather than silently taking the first
+// (which used to truncate the section and drop everything after the
+// second heading with no diagnostic). Content runs from the end of the
+// matched heading's line to the start of the next heading of any name, or
+// to the end of the document if there is none.
+function sectionBody(headings: Heading[], body: string, name: string): SectionResult {
+  const matches = headings.filter((h) => h.name === name)
+  if (matches.length === 0) return { kind: 'missing' }
+  if (matches.length > 1) return { kind: 'duplicate' }
+  const match = matches[0]
+  if (!match) return { kind: 'missing' }
+  const at = headings.indexOf(match)
+  const next = headings[at + 1]
+  const contentEnd = next ? next.start : body.length
+  return { kind: 'ok', text: body.slice(match.end, contentEnd).trim() }
+}
+
+// A queue file that cannot be parsed at all (no --- frontmatter block found)
+// is a usage error: the request never resolved to a queue item in the first
+// place. Every other error below comes from a file that did parse, so it is
+// a well-formed file with invalid content -- a content failure instead.
+// Callers (queue-cmd.ts) use this to pick the right exit code without
+// re-parsing the file themselves.
+export function isMissingFrontmatter(errors: string[]): boolean {
+  return errors.length === 1 && (errors[0]?.includes(NO_FRONTMATTER) ?? false)
+}
+
+export function parseQueueItem(rawText: string, path: string): ParsedQueue {
+  const errors: string[] = []
+  const text = normalizeText(rawText)
+  const split = splitFrontmatter(text)
+  if (!split) return { ok: false, errors: [`${path}: ${NO_FRONTMATTER}`] }
+  const { fm, body } = split
+
+  const id = fm.id ?? ''
+  if (!id) errors.push(`${path}: frontmatter is missing id`)
+  const stem = basename(path).replace(/\.md$/, '')
+  if (id && stem !== id) errors.push(`${path}: filename ${stem} does not match id ${id}`)
+  if (id && !(id.startsWith('q-') && isValidSlug(id.slice(2)))) {
+    errors.push(`${path}: id ${id} must be q- followed by a lowercase kebab-case slug`)
+  }
+
+  const severity = fm.severity ?? ''
+  if (!SEVERITIES.includes(severity as Severity)) {
+    errors.push(
+      `${path}: severity must be one of ${SEVERITIES.join(', ')}, got ${severity || '<none>'}`,
+    )
+  }
+  const status = fm.status ?? ''
+  if (status !== 'open' && status !== 'adjudicated') {
+    errors.push(`${path}: status must be open or adjudicated, got ${status || '<none>'}`)
+  }
+  if (status === 'adjudicated' && !fm.ruling) {
+    errors.push(`${path}: an adjudicated item needs a ruling`)
+  }
+
+  const { headings, unclosedFenceAt } = findHeadings(body)
+  const found: Record<string, string> = {}
+  if (unclosedFenceAt !== null) {
+    // The document's structure past an unterminated fence cannot be
+    // trusted -- any '##' line after it might belong inside the fence or
+    // outside it, and there is no reliable way to tell. Rather than guess
+    // (which risks exactly the silent corruption Finding 2 fixed) or pile
+    // on confusing per-section "missing"/"duplicate" noise that would
+    // misdirect the author toward the wrong section entirely, this is one
+    // clear, specific, loud error naming the real problem, and every
+    // per-section check below is skipped.
+    errors.push(
+      `${path}: unclosed code fence starting at body line ${unclosedFenceAt} (add a matching closing fence; headings after this point cannot be recognized)`,
+    )
+  } else {
+    for (const name of SECTIONS) {
+      const section = sectionBody(headings, body, name)
+      if (section.kind === 'missing') {
+        // States the grammar explicitly (line-anchored, exactly two hashes,
+        // case-sensitive) so a level typo or a wrong-case heading (which also
+        // lands here, since neither is recognized as this heading) reads as
+        // a grammar mismatch rather than "you forgot this entirely".
+        errors.push(
+          `${path}: missing ## ${name} section (a line reading exactly "## ${name}", case-sensitive)`,
+        )
+      } else if (section.kind === 'duplicate') {
+        errors.push(
+          `${path}: duplicate ## ${name} section (the heading "## ${name}" appears more than once)`,
+        )
+      } else if (section.text.length === 0) {
+        errors.push(`${path}: ## ${name} section is empty`)
+      } else {
+        found[name] = section.text
+      }
+    }
+  }
+
+  if (errors.length > 0) return { ok: false, errors }
+  return {
+    ok: true,
+    value: {
+      id,
+      severity: severity as Severity,
+      status: status as QueueItem['status'],
+      ...(fm.ruling ? { ruling: fm.ruling } : {}),
+      ...(fm.adjudicated ? { adjudicated: fm.adjudicated } : {}),
+      evidence: found.Evidence ?? '',
+      options: found.Options ?? '',
+      recommendation: found.Recommendation ?? '',
+      path,
+    },
+  }
+}
+
+export async function loadQueue(
+  queueDir: string,
+): Promise<{ items: QueueItem[]; errors: string[] }> {
+  if (!existsSync(queueDir)) return { items: [], errors: [] }
+  let names: string[]
+  try {
+    names = (await readdir(queueDir)).filter((n) => n.endsWith('.md')).sort()
+  } catch {
+    // existsSync just confirmed the path exists, so a readdir failure here
+    // means it is not a readable directory (e.g. a file sits at the queue
+    // path). One clean diagnostic naming the path, not an uncaught throw.
+    return { items: [], errors: [`${queueDir}: cannot be read as a directory`] }
+  }
+  const items: QueueItem[] = []
+  const errors: string[] = []
+  for (const name of names) {
+    const path = join(queueDir, name)
+    let text: string
+    try {
+      text = await readTextFile(path)
+    } catch (e) {
+      // One unreadable entry (permission denied, a directory named *.md, or
+      // a file removed between readdir and read) must not hide the rest of
+      // the directory: report it and keep going.
+      errors.push((e as Error).message)
+      continue
+    }
+    const parsed = parseQueueItem(text, path)
+    if (parsed.ok) items.push(parsed.value)
+    else errors.push(...parsed.errors)
+  }
+  items.sort((a, b) => {
+    const bySeverity = SEVERITIES.indexOf(a.severity) - SEVERITIES.indexOf(b.severity)
+    return bySeverity !== 0 ? bySeverity : a.id.localeCompare(b.id)
+  })
+  return { items, errors }
+}

package/skills/migrate/scripts/report-cmd.ts

@@ -0,0 +1,47 @@
+import { mkdir } from 'node:fs/promises'
+import { join } from 'node:path'
+import { runCheck } from './check.ts'
+import { loadConfig } from './config.ts'
+import { assertNotUnderSource, storePaths } from './paths.ts'
+import { loadQueue } from './queue.ts'
+import { renderLedger, renderQueueReport, renderRequirements } from './report.ts'
+import { readRows, writeAtomically } from './store.ts'
+import type { Element, Requirement } from './types.ts'
+
+export async function runReport(opts: { root: string; outDir?: string }): Promise<number> {
+  const cfg = await loadConfig(opts.root)
+  const p = storePaths(opts.root)
+  const outDir = opts.outDir ?? join(opts.root, 'docs', 'migrate')
+  await assertNotUnderSource(outDir, cfg.source.path)
+  await mkdir(outDir, { recursive: true })
+
+  const elements = await readRows<Element>(p.elements)
+  const requirements = await readRows<Requirement>(p.requirements)
+  const { items, errors } = await loadQueue(p.queueDir)
+  // A queue item the report cannot parse is not represented in queue.md at
+  // all: silently emitting a file that only covers the parseable items,
+  // under a banner claiming it was generated from the store, would let an
+  // owner reading it conclude there is nothing else to adjudicate. Surfaced
+  // the same way every other command in this CLI surfaces a domain problem
+  // on an otherwise well-formed request: named on stderr, non-zero exit.
+  for (const e of errors) process.stderr.write(`report: ${e}\n`)
+  const { summary } = await runCheck({ root: opts.root })
+
+  // Through writeAtomically rather than writeFile, so the three rendered views
+  // get temp-plus-rename like every store file: a report is what a human opens
+  // to read the run, and a truncated one is worse than a stale one. The
+  // explicit assertNotUnderSource on outDir above is still needed regardless,
+  // because the mkdir happens before any of these three run.
+  const src = cfg.source.path
+  await writeAtomically(join(outDir, 'ledger.md'), `${renderLedger(elements)}\n${summary}\n`, src)
+  await writeAtomically(join(outDir, 'requirements.md'), renderRequirements(requirements), src)
+  await writeAtomically(join(outDir, 'queue.md'), renderQueueReport(items), src)
+
+  process.stdout.write(`report: wrote ledger.md, requirements.md, queue.md to ${outDir}\n`)
+  // A malformed queue item is a content failure on an otherwise well-formed
+  // request (the store exists and could be read), the same class `queue
+  // list` already reports as exit 1 for the identical condition -- not a
+  // usage error (2, this request was perfectly serviceable) and not success
+  // (0, the report is incomplete).
+  return errors.length > 0 ? 1 : 0
+}

package/skills/migrate/scripts/report.ts

@@ -0,0 +1,131 @@
+import type {
+  Confidence,
+  Disposition,
+  Element,
+  Parity,
+  QueueItem,
+  Ref,
+  Requirement,
+} from './types.ts'
+
+const BANNER = '<!-- generated by `migrate report`; edit the store, not this file -->'
+
+// A cell's content is free text an agent wrote while reading a legacy
+// codebase, so it can contain anything. Two things actually break a GFM
+// table's structure (change the column count a row parses to, or split one
+// row into several): an unescaped '|', which reads as a new column
+// boundary, and a line break, which ends the row outright. Both are
+// neutralized here: '|' is escaped to '\|', and every line-break variant
+// (bare '\n', '\r\n', and a lone '\r' from old Mac-authored text) is
+// flattened to a space, not just '\n' alone, so a stray '\r' can't survive
+// as an unflattened character in the middle of a row.
+//
+// A run of backticks is deliberately left alone. It cannot change the
+// column count or split the row: GFM splits a table row into cells by its
+// literal, unescaped '|' characters first, and only afterward parses each
+// cell's inline content (code spans, emphasis, ...) independently, so an
+// unbalanced backtick run is confined to the cell it's in and renders as
+// literal backticks at worst. Wrapping such a cell in a matching fence was
+// considered, but it would have to run after the '|' escaping above, and a
+// backtick code span does not itself interpret backslash escapes, so an
+// escaped pipe inside it would render as the literal two characters '\|'
+// instead of a pipe: a cosmetic regression in exchange for guarding against
+// a break that was never structural in the first place.
+function cell(text: string): string {
+  return text.replaceAll('|', '\\|').replaceAll(/\r\n|\r|\n/g, ' ')
+}
+
+export function refToText(ref: Ref): string {
+  if (ref.kind === 'src')
+    return ref.lines ? `src:${ref.path}:${ref.lines[0]}-${ref.lines[1]}` : `src:${ref.path}`
+  if (ref.kind === 'ledger') return ref.id
+  if (ref.kind === 'doc') return `doc:${ref.path}`
+  return `observed:${ref.host}${ref.path}`
+}
+
+export function dispositionToText(d: Disposition): string {
+  if (d.kind === 'mapped') return `mapped:${d.fr}`
+  if (d.kind === 'out-of-scope') return `out-of-scope:${d.queue}`
+  return 'unaccounted'
+}
+
+export function confidenceToText(c: Confidence): string {
+  return c.kind === 'queued' ? `queued:${c.queue}` : c.kind
+}
+
+export function parityToText(p: Parity | null): string {
+  if (p === null) return '-'
+  if (p.kind === 'rubric')
+    return p.level === 'high' ? 'rubric:high' : `rubric:${p.level}:${p.queue}`
+  return `${p.kind}:${p.ref}`
+}
+
+export function renderLedger(elements: Element[]): string {
+  const lines = [BANNER, '', '# Surface ledger', '']
+  if (elements.length === 0) {
+    lines.push('No surface elements recorded yet.', '')
+    return lines.join('\n')
+  }
+  const bySurface = new Map<string, Element[]>()
+  for (const el of elements) {
+    const list = bySurface.get(el.surface) ?? []
+    list.push(el)
+    bySurface.set(el.surface, list)
+  }
+  for (const surface of [...bySurface.keys()].sort()) {
+    lines.push(`## ${surface}`, '')
+    lines.push('| id | element | found-by | disposition | refs | notes |')
+    lines.push('| --- | --- | --- | --- | --- | --- |')
+    for (const el of bySurface.get(surface) ?? []) {
+      lines.push(
+        `| ${cell(el.id)} | ${cell(el.element)} | ${el.found_by.join(',')} | ${dispositionToText(el.disposition)} | ${cell(el.refs.map(refToText).join(', '))} | ${cell(el.notes)} |`,
+      )
+    }
+    lines.push('')
+  }
+  return lines.join('\n')
+}
+
+export function renderRequirements(reqs: Requirement[]): string {
+  const lines = [BANNER, '', '# Functional requirements', '']
+  if (reqs.length === 0) {
+    lines.push('No requirements recorded yet.', '')
+    return lines.join('\n')
+  }
+  const byCap = new Map<string, Requirement[]>()
+  for (const req of reqs) {
+    const list = byCap.get(req.cap) ?? []
+    list.push(req)
+    byCap.set(req.cap, list)
+  }
+  for (const cap of [...byCap.keys()].sort()) {
+    lines.push(`## ${cap}`, '')
+    lines.push(
+      '| id | requirement | actors | objects | rules | confidence | origin | citations | parity |',
+    )
+    lines.push('| --- | --- | --- | --- | --- | --- | --- | --- | --- |')
+    for (const req of byCap.get(cap) ?? []) {
+      lines.push(
+        `| ${cell(req.id)} | ${cell(req.requirement)} | ${cell(req.actors)} | ${cell(req.objects)} | ${cell(req.rules)} | ${confidenceToText(req.confidence)} | ${req.origin} | ${cell(req.citations.map(refToText).join(', '))} | ${cell(parityToText(req.parity))} |`,
+      )
+    }
+    lines.push('')
+  }
+  return lines.join('\n')
+}
+
+export function renderQueueReport(items: QueueItem[]): string {
+  const lines = [BANNER, '', '# Decision queue', '']
+  if (items.length === 0) {
+    lines.push('No queue items.', '')
+    return lines.join('\n')
+  }
+  lines.push('| id | severity | status | recommendation |')
+  lines.push('| --- | --- | --- | --- |')
+  for (const item of items) {
+    const first = item.recommendation.split('\n')[0] ?? ''
+    lines.push(`| ${cell(item.id)} | ${item.severity} | ${item.status} | ${cell(first)} |`)
+  }
+  lines.push('')
+  return lines.join('\n')
+}

package/skills/migrate/scripts/reset-cmd.ts

@@ -0,0 +1,120 @@
+import { rm } from 'node:fs/promises'
+import { loadConfig } from './config.ts'
+import { LockError, withStoreLock } from './lock.ts'
+import { type StorePaths, storePaths } from './paths.ts'
+import { isPhase, loadPhases, type Phase, savePhases } from './phases.ts'
+import { readRows, writeRows } from './store.ts'
+import type { Census, Element, Requirement } from './types.ts'
+
+export async function runReset(opts: {
+  root: string
+  phase: string
+  forceUnlock?: boolean
+}): Promise<number> {
+  if (!isPhase(opts.phase)) {
+    process.stderr.write(`reset: unknown phase ${opts.phase}\n`)
+    return 2
+  }
+  const phase = opts.phase
+  const cfg = await loadConfig(opts.root)
+  const p = storePaths(opts.root)
+  const src = cfg.source.path
+
+  // reset performs the same read-modify-write over whole store files that
+  // import and census do -- it reads census.jsonl and elements.jsonl, filters
+  // or rewrites every row, and writes the file back, then does the same to
+  // phases.json -- and it was the one such command with no lock at all.
+  // Concurrently with an importer that is mid-critical-section, either
+  // rewrite can discard every row the other wrote, which is exactly the loss
+  // the lock exists to stop. Nothing inside this critical section takes the
+  // lock again: writeRows, readRows, loadPhases and savePhases are all
+  // lock-free, and savePhases is deliberately called below instead of
+  // setPhaseStatus, which is the one phases.ts helper that does take it.
+  // withStoreLock is not reentrant, so that distinction is load-bearing
+  // rather than incidental.
+  let cleared: string[]
+  try {
+    cleared = await withStoreLock(opts.root, () => clearPhase(opts.root, phase, p, src), {
+      cmd: 'reset',
+      ...(opts.forceUnlock ? { force: true } : {}),
+      onWait: (m) => process.stderr.write(`reset: ${m}\n`),
+    })
+  } catch (e) {
+    // Same classification import, census and phase --status already use: a
+    // lock failure is neither an unknown phase (2) nor a content failure (1);
+    // the request is fine and would likely succeed on retry.
+    if (e instanceof LockError) {
+      process.stderr.write(`reset: ${e.message}\n`)
+      return 3
+    }
+    throw e
+  }
+
+  const what = cleared.length > 0 ? `: cleared ${cleared.join(', ')}` : ' (state only)'
+  process.stdout.write(`reset ${phase}${what}\n`)
+  return 0
+}
+
+// The whole mutation, extracted so the critical section above is one call and
+// the lock's extent is impossible to misread. Returns what it cleared, which
+// is used only to build the stdout line, after the lock has been released.
+async function clearPhase(
+  root: string,
+  phase: Phase,
+  p: StorePaths,
+  src: string,
+): Promise<string[]> {
+  const cleared: string[] = []
+
+  if (phase === 'enumerate') {
+    await writeRows(p.elements, [], src)
+    const census = await readRows<Census>(p.census)
+    await writeRows(
+      p.census,
+      census.filter((c) => c.kind !== 'lens'),
+      src,
+    )
+    cleared.push('elements', 'lens census')
+  }
+
+  if (phase === 'seam') {
+    await writeRows(p.capabilities, [], src)
+    await rm(p.seamJson, { force: true })
+    await rm(p.seamMd, { force: true })
+    cleared.push('capabilities', 'seam')
+  }
+
+  if (phase === 'extract') {
+    await writeRows(p.requirements, [], src)
+    const census = await readRows<Census>(p.census)
+    await writeRows(
+      p.census,
+      census.filter((c) => c.kind === 'lens'),
+      src,
+    )
+    const elements = await readRows<Element>(p.elements)
+    await writeRows(
+      p.elements,
+      elements.map((e) => ({ ...e, disposition: { kind: 'unaccounted' as const } })),
+      src,
+    )
+    cleared.push('requirements', 'attribute/rule-sweep/closer census', 'element dispositions')
+  }
+
+  if (phase === 'parity') {
+    await writeRows(p.deltas, [], src)
+    const reqs = await readRows<Requirement>(p.requirements)
+    await writeRows(
+      p.requirements,
+      reqs.map((r) => ({ ...r, parity: null })),
+      src,
+    )
+    cleared.push('deltas', 'parity plans')
+  }
+
+  const phases = await loadPhases(root)
+  phases[phase] = { status: 'pending', batches: [], pending: [] }
+  await savePhases(root, phases, src)
+
+  return cleared
+}