@iceinvein/agent-skills 0.1.39 → 0.2.0

package/skills/migrate/scripts/__tests__/queue.test.ts

@@ -0,0 +1,475 @@
+import { afterEach, beforeEach, expect, test } from 'bun:test'
+import { existsSync } from 'node:fs'
+import { chmod, mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { writeConfig } from '../config.ts'
+import { isMissingFrontmatter, loadQueue, parseQueueItem } from '../queue.ts'
+import { runQueue } from '../queue-cmd.ts'
+
+let root: string
+let queueDir: string
+
+beforeEach(async () => {
+  root = await mkdtemp(join(tmpdir(), 'migrate-queue-'))
+  queueDir = join(root, '.migrate', 'queue')
+  await mkdir(queueDir, { recursive: true })
+  await writeConfig(root, { sourcePath: join(root, 'legacy'), scope: 'all', targetName: 'newapp' })
+})
+
+afterEach(async () => {
+  await rm(root, { recursive: true, force: true })
+})
+
+const GOOD = `---
+id: q-invoice-batch-scope
+severity: moderate
+status: open
+---
+
+## Evidence
+
+Route POST /api/invoice/batch found in InvoiceController.cs:215-240.
+
+## Options
+
+(a) Replicate as-is. (b) Harden it. (c) Mark out of scope.
+
+## Recommendation
+
+Recommend (c); three invocations in six months.
+`
+
+test('a well-formed item parses', () => {
+  const result = parseQueueItem(GOOD, join(queueDir, 'q-invoice-batch-scope.md'))
+  expect(result.ok).toBe(true)
+  if (result.ok) {
+    expect(result.value.severity).toBe('moderate')
+    expect(result.value.status).toBe('open')
+    expect(result.value.evidence).toContain('InvoiceController.cs')
+  }
+})
+
+test('a filename that does not match the id is rejected', () => {
+  const result = parseQueueItem(GOOD, join(queueDir, 'other.md'))
+  expect(result.ok).toBe(false)
+  if (!result.ok) expect(result.errors.join(' ')).toContain('filename')
+})
+
+test('an empty section is rejected', () => {
+  const text = GOOD.replace('Recommend (c); three invocations in six months.', '')
+  const result = parseQueueItem(text, join(queueDir, 'q-invoice-batch-scope.md'))
+  expect(result.ok).toBe(false)
+  if (!result.ok) expect(result.errors.join(' ')).toContain('Recommendation')
+})
+
+test('a missing section is rejected', () => {
+  const text = GOOD.replace(/## Options[\s\S]*?(?=## Recommendation)/, '')
+  const result = parseQueueItem(text, join(queueDir, 'q-invoice-batch-scope.md'))
+  expect(result.ok).toBe(false)
+  if (!result.ok) expect(result.errors.join(' ')).toContain('Options')
+})
+
+test('an unknown severity is rejected', () => {
+  const text = GOOD.replace('severity: moderate', 'severity: urgent')
+  const result = parseQueueItem(text, join(queueDir, 'q-invoice-batch-scope.md'))
+  expect(result.ok).toBe(false)
+  if (!result.ok) expect(result.errors.join(' ')).toContain('severity')
+})
+
+test('loadQueue sorts critical first and reports per-file errors', async () => {
+  await writeFile(join(queueDir, 'q-invoice-batch-scope.md'), GOOD)
+  await writeFile(
+    join(queueDir, 'q-zulu.md'),
+    GOOD.replace('q-invoice-batch-scope', 'q-zulu').replace(
+      'severity: moderate',
+      'severity: critical',
+    ),
+  )
+  await writeFile(join(queueDir, 'q-broken.md'), '---\nid: q-broken\n---\n')
+  const { items, errors } = await loadQueue(queueDir)
+  expect(items.map((i) => i.id)).toEqual(['q-zulu', 'q-invoice-batch-scope'])
+  expect(errors.join(' ')).toContain('q-broken')
+})
+
+// An adjudicated item requires a ruling: status alone is not enough to
+// close out a decision, since 'adjudicated' with no ruling text records
+// that a call was made without recording what it was.
+
+test('an adjudicated item with no ruling is rejected', () => {
+  const text = GOOD.replace('status: open', 'status: adjudicated')
+  const result = parseQueueItem(text, join(queueDir, 'q-invoice-batch-scope.md'))
+  expect(result.ok).toBe(false)
+  if (!result.ok) expect(result.errors.join(' ')).toContain('ruling')
+})
+
+test('an adjudicated item with a ruling parses', () => {
+  const text = GOOD.replace('status: open', 'status: adjudicated\nruling: out of scope, delta-003')
+  const result = parseQueueItem(text, join(queueDir, 'q-invoice-batch-scope.md'))
+  expect(result.ok).toBe(true)
+  if (result.ok) {
+    expect(result.value.status).toBe('adjudicated')
+    expect(result.value.ruling).toBe('out of scope, delta-003')
+  }
+})
+
+// Correction 1: no uncaught throws from the CLI, ever. runQueue reads files
+// with readFile; a missing file, a directory passed as a file, or an
+// unreadable file must all produce a clean diagnostic and a deliberate exit
+// code instead of a raw stack trace escaping the process.
+
+test('queue add reports a missing file as a clean diagnostic, not a thrown stack trace', async () => {
+  const code = await runQueue({ root, args: ['add', join(root, 'does-not-exist.md')] })
+  expect(code).toBe(2)
+})
+
+test('queue add reports a directory passed as a file as a clean diagnostic', async () => {
+  const dir = join(root, 'a-directory.md')
+  await mkdir(dir)
+  const code = await runQueue({ root, args: ['add', dir] })
+  expect(code).toBe(2)
+})
+
+test('queue add reports an unreadable file as a clean diagnostic', async () => {
+  const path = join(root, 'no-access.md')
+  await writeFile(path, GOOD)
+  await chmod(path, 0o000)
+  try {
+    const code = await runQueue({ root, args: ['add', path] })
+    expect(code).toBe(2)
+  } finally {
+    await chmod(path, 0o644)
+  }
+})
+
+test('loadQueue reports a directory named *.md without abandoning the rest of the directory', async () => {
+  await writeFile(join(queueDir, 'q-invoice-batch-scope.md'), GOOD)
+  await mkdir(join(queueDir, 'q-oops.md'))
+  const { items, errors } = await loadQueue(queueDir)
+  expect(items.map((i) => i.id)).toEqual(['q-invoice-batch-scope'])
+  expect(errors.join(' ')).toContain('q-oops.md')
+})
+
+test('loadQueue reports an unreadable file without abandoning the rest of the directory', async () => {
+  await writeFile(join(queueDir, 'q-invoice-batch-scope.md'), GOOD)
+  const lockedPath = join(queueDir, 'q-locked.md')
+  await writeFile(
+    lockedPath,
+    GOOD.replace('q-invoice-batch-scope', 'q-locked').replace(
+      'severity: moderate',
+      'severity: critical',
+    ),
+  )
+  await chmod(lockedPath, 0o000)
+  try {
+    const { items, errors } = await loadQueue(queueDir)
+    expect(items.map((i) => i.id)).toEqual(['q-invoice-batch-scope'])
+    expect(errors.join(' ')).toContain('q-locked.md')
+  } finally {
+    await chmod(lockedPath, 0o644)
+  }
+})
+
+test('loadQueue reports a queue path that is a file, not a directory, without throwing', async () => {
+  const notADir = join(root, '.migrate', 'not-a-dir')
+  await writeFile(notADir, 'oops')
+  const { items, errors } = await loadQueue(notADir)
+  expect(items).toEqual([])
+  expect(errors.join(' ')).toContain(notADir)
+})
+
+// Correction 2: exit-code convention. A queue file that cannot be read or
+// has no frontmatter at all is a usage error (2); a queue file that parses
+// but violates the grammar is a content failure (1).
+
+test('isMissingFrontmatter is true only for the no-frontmatter case', () => {
+  const noFm = parseQueueItem('not frontmatter at all\n', join(queueDir, 'x.md'))
+  const badSeverity = parseQueueItem(
+    GOOD.replace('severity: moderate', 'severity: urgent'),
+    join(queueDir, 'q-invoice-batch-scope.md'),
+  )
+  if (!noFm.ok) expect(isMissingFrontmatter(noFm.errors)).toBe(true)
+  if (!badSeverity.ok) expect(isMissingFrontmatter(badSeverity.errors)).toBe(false)
+})
+
+test('queue add rejects a file with no frontmatter at all as a usage error (2)', async () => {
+  const path = join(root, 'no-frontmatter.md')
+  await writeFile(path, '# Just some markdown\n\nNo frontmatter here.\n')
+  const code = await runQueue({ root, args: ['add', path] })
+  expect(code).toBe(2)
+})
+
+test('queue add rejects a well-formed-but-invalid item as a content failure (1)', async () => {
+  const path = join(root, 'q-invoice-batch-scope.md')
+  await writeFile(path, GOOD.replace('severity: moderate', 'severity: urgent'))
+  const code = await runQueue({ root, args: ['add', path] })
+  expect(code).toBe(1)
+})
+
+test('queue add rejects an empty section as a content failure (1)', async () => {
+  const path = join(root, 'q-invoice-batch-scope.md')
+  await writeFile(path, GOOD.replace('Recommend (c); three invocations in six months.', ''))
+  const code = await runQueue({ root, args: ['add', path] })
+  expect(code).toBe(1)
+})
+
+test('queue add accepts a well-formed item and copies it into the store (0)', async () => {
+  const path = join(root, 'q-invoice-batch-scope.md')
+  await writeFile(path, GOOD)
+  const code = await runQueue({ root, args: ['add', path] })
+  expect(code).toBe(0)
+  expect(existsSync(join(queueDir, 'q-invoice-batch-scope.md'))).toBe(true)
+})
+
+test('queue add with no file argument is a usage error (2)', async () => {
+  const code = await runQueue({ root, args: ['add'] })
+  expect(code).toBe(2)
+})
+
+test('queue list reports items and returns 0 when the queue is clean', async () => {
+  const path = join(root, 'q-invoice-batch-scope.md')
+  await writeFile(path, GOOD)
+  await runQueue({ root, args: ['add', path] })
+  const code = await runQueue({ root, args: ['list'] })
+  expect(code).toBe(0)
+})
+
+test('queue list returns 1 when a queue file is broken, without abandoning the listing', async () => {
+  await writeFile(join(queueDir, 'q-broken.md'), '---\nid: q-broken\n---\n')
+  const code = await runQueue({ root, args: ['list'] })
+  expect(code).toBe(1)
+})
+
+test('queue show prints the raw file for a known id', async () => {
+  await writeFile(join(queueDir, 'q-invoice-batch-scope.md'), GOOD)
+  const code = await runQueue({ root, args: ['show', 'q-invoice-batch-scope'] })
+  expect(code).toBe(0)
+})
+
+test('queue show reports an unknown id as a content failure (1)', async () => {
+  const code = await runQueue({ root, args: ['show', 'q-does-not-exist'] })
+  expect(code).toBe(1)
+})
+
+test('queue show with no id is a usage error (2)', async () => {
+  const code = await runQueue({ root, args: ['show'] })
+  expect(code).toBe(2)
+})
+
+test('queue with an unknown verb is a usage error (2)', async () => {
+  const code = await runQueue({ root, args: ['frobnicate'] })
+  expect(code).toBe(2)
+})
+
+// Critical finding 1: a store configured so its own path resolves inside
+// its configured source tree (e.g. source.path pointing at the project
+// root itself, which the store also lives under) must not crash.
+// assertNotUnderSource throws by design (writeRows's own contract, see
+// store.test.ts); queue-cmd.ts must catch that throw and report a clean
+// diagnostic with a deliberate exit code instead of letting it escape as
+// an uncaught stack trace. Chosen exit code: 2 -- a malformed/unusable
+// setup that fails identically no matter what valid file content is
+// supplied, not a property of this file's own data (see the report for
+// the full argument against exit code 1).
+
+test('queue add refuses to write when the store sits inside its own configured source tree, as a clean usage error (2), not a crash', async () => {
+  await writeConfig(root, { sourcePath: root, scope: 'all', targetName: 'newapp' })
+  const path = join(root, 'q-invoice-batch-scope.md')
+  await writeFile(path, GOOD)
+  const code = await runQueue({ root, args: ['add', path] })
+  expect(code).toBe(2)
+  expect(existsSync(join(queueDir, 'q-invoice-batch-scope.md'))).toBe(false)
+})
+
+// Critical finding 2: sectionBody must match headings at a line boundary
+// and at exactly level two. Before the fix, '### Options' (one hash too
+// many) was invisible to the next-boundary search but still matched by a
+// plain indexOf('## Options') substring lookup, so Evidence silently
+// absorbed the whole mislabeled Options block (including its own heading)
+// while Options was separately (mis)populated from that same text --
+// ok:true, corrupted and duplicated, no diagnostic. A duplicated
+// '## Evidence' heading similarly truncated Evidence to its first block
+// and dropped the second entirely, again ok:true with no diagnostic.
+
+test('a heading one level too deep (### Options) is reported as a missing section, not silently accepted with corrupted content', () => {
+  const text = GOOD.replace('## Options', '### Options')
+  const result = parseQueueItem(text, join(queueDir, 'q-invoice-batch-scope.md'))
+  expect(result.ok).toBe(false)
+  if (!result.ok) expect(result.errors.join(' ')).toContain('Options')
+})
+
+test('a duplicated ## Evidence heading is rejected as a duplicate section, not silently truncated to the first block', () => {
+  const text = GOOD.replace(
+    '## Evidence\n\nRoute POST /api/invoice/batch found in InvoiceController.cs:215-240.\n',
+    '## Evidence\n\nFirst evidence block.\n\n## Evidence\n\nSecond evidence block, silently dropped by the pre-fix code.\n',
+  )
+  const result = parseQueueItem(text, join(queueDir, 'q-invoice-batch-scope.md'))
+  expect(result.ok).toBe(false)
+  if (!result.ok) {
+    const msg = result.errors.join(' ')
+    expect(msg).toContain('Evidence')
+    expect(msg.toLowerCase()).toContain('duplicate')
+  }
+})
+
+test('a level-three sub-heading inside a section is kept as ordinary content, not treated as a boundary', () => {
+  const text = GOOD.replace(
+    'Route POST /api/invoice/batch found in InvoiceController.cs:215-240.',
+    'Route POST /api/invoice/batch found in InvoiceController.cs:215-240.\n\n### Extra detail\n\nAlso seen in the audit log.',
+  )
+  const result = parseQueueItem(text, join(queueDir, 'q-invoice-batch-scope.md'))
+  expect(result.ok).toBe(true)
+  if (result.ok) {
+    expect(result.value.evidence).toContain('### Extra detail')
+    expect(result.value.evidence).toContain('Also seen in the audit log.')
+    expect(result.value.options).not.toContain('Extra detail')
+  }
+})
+
+// Important finding 3: a leading BOM and/or CRLF line endings must not
+// reject an otherwise well-formed item wholesale. Both are common
+// byproducts of authoring on Windows; neither changes the file's actual
+// content, so both are stripped/normalized before any grammar check runs.
+
+test('a leading BOM does not cause a well-formed item to be rejected', () => {
+  const result = parseQueueItem(`\uFEFF${GOOD}`, join(queueDir, 'q-invoice-batch-scope.md'))
+  expect(result.ok).toBe(true)
+})
+
+test('CRLF line endings do not cause a well-formed item to be rejected', () => {
+  const crlf = GOOD.replace(/\n/g, '\r\n')
+  const result = parseQueueItem(crlf, join(queueDir, 'q-invoice-batch-scope.md'))
+  expect(result.ok).toBe(true)
+  if (result.ok) {
+    expect(result.value.evidence).toContain('InvoiceController.cs')
+    expect(result.value.evidence).not.toContain('\r')
+  }
+})
+
+test('a BOM plus CRLF together do not cause a well-formed item to be rejected', () => {
+  const text = `\uFEFF${GOOD.replace(/\n/g, '\r\n')}`
+  const result = parseQueueItem(text, join(queueDir, 'q-invoice-batch-scope.md'))
+  expect(result.ok).toBe(true)
+})
+
+// Minor finding 4: a wrong-case heading (e.g. '## options') reports
+// "missing ## Options section" with no hint that case is the problem,
+// identical to the message for a heading that's absent entirely. State
+// the grammar so the author can tell the two apart.
+
+test('a wrong-case heading names the exact grammar required, not just "missing"', () => {
+  const text = GOOD.replace('## Options', '## options')
+  const result = parseQueueItem(text, join(queueDir, 'q-invoice-batch-scope.md'))
+  expect(result.ok).toBe(false)
+  if (!result.ok) {
+    const msg = result.errors.join(' ')
+    expect(msg).toContain('Options')
+    expect(msg).toContain('case-sensitive')
+  }
+})
+
+// Round-1 confirmation: an indented, tab-indented, blockquoted, or
+// starts-with heading must still be treated as ordinary body text (not a
+// section boundary), exactly as before the fence fix. These are
+// regression checks, not fail-before/pass-after tests for this round --
+// the fence-scanning rewrite only changed how a line is classified while
+// inside a fence; the underlying line-anchored, exact-name heading test
+// applied to a non-fenced line is unchanged.
+
+test('an indented ## Options heading is not recognized (still missing)', () => {
+  const text = GOOD.replace('## Options', '  ## Options')
+  const result = parseQueueItem(text, join(queueDir, 'q-invoice-batch-scope.md'))
+  expect(result.ok).toBe(false)
+  if (!result.ok) expect(result.errors.join(' ')).toContain('missing ## Options')
+})
+
+test('a tab-indented ## Options heading is not recognized (still missing)', () => {
+  const text = GOOD.replace('## Options', '\t## Options')
+  const result = parseQueueItem(text, join(queueDir, 'q-invoice-batch-scope.md'))
+  expect(result.ok).toBe(false)
+  if (!result.ok) expect(result.errors.join(' ')).toContain('missing ## Options')
+})
+
+test('a blockquoted ## Options heading is not recognized (still missing)', () => {
+  const text = GOOD.replace('## Options', '> ## Options')
+  const result = parseQueueItem(text, join(queueDir, 'q-invoice-batch-scope.md'))
+  expect(result.ok).toBe(false)
+  if (!result.ok) expect(result.errors.join(' ')).toContain('missing ## Options')
+})
+
+test('a heading whose name only starts with the required text (## Options considered) does not match Options', () => {
+  const text = GOOD.replace('## Options', '## Options considered')
+  const result = parseQueueItem(text, join(queueDir, 'q-invoice-batch-scope.md'))
+  expect(result.ok).toBe(false)
+  if (!result.ok) expect(result.errors.join(' ')).toContain('missing ## Options')
+})
+
+// Critical finding (round 2): a fenced code block quoting a '##'-prefixed
+// line (a shell script's own comments, a quoted markdown file, a diff)
+// must not be mistaken for real document structure. Before this fix, a
+// fenced '## Options' inside Evidence was rejected as "duplicate ##
+// Options" (colliding with the real Options heading later in the
+// document) -- a false rejection of well-formed input pointing the author
+// at entirely the wrong problem.
+
+const FENCE = '```'
+
+test('a fenced code block in Evidence containing ## Options parses cleanly, with the fence content preserved verbatim', () => {
+  const text = GOOD.replace(
+    'Route POST /api/invoice/batch found in InvoiceController.cs:215-240.',
+    [
+      'Route POST /api/invoice/batch found in InvoiceController.cs:215-240.',
+      '',
+      FENCE,
+      '## Options',
+      'echo "quoted shell output, not a real heading"',
+      FENCE,
+    ].join('\n'),
+  )
+  const result = parseQueueItem(text, join(queueDir, 'q-invoice-batch-scope.md'))
+  expect(result.ok).toBe(true)
+  if (result.ok) {
+    expect(result.value.evidence).toContain('## Options')
+    expect(result.value.evidence).toContain('echo "quoted shell output, not a real heading"')
+    expect(result.value.options).not.toContain('echo')
+  }
+})
+
+test('a fenced code block containing ## Evidence does not trigger duplicate-section detection', () => {
+  const text = GOOD.replace(
+    'Route POST /api/invoice/batch found in InvoiceController.cs:215-240.',
+    [
+      'Route POST /api/invoice/batch found in InvoiceController.cs:215-240.',
+      '',
+      FENCE,
+      '## Evidence',
+      'quoted from another document, not a real heading',
+      FENCE,
+    ].join('\n'),
+  )
+  const result = parseQueueItem(text, join(queueDir, 'q-invoice-batch-scope.md'))
+  expect(result.ok).toBe(true)
+  if (result.ok) {
+    expect(result.value.evidence).toContain('## Evidence')
+    expect(result.value.evidence).toContain('quoted from another document, not a real heading')
+  }
+})
+
+test('an unclosed fence produces one clear, loud error naming the fence, not a silently truncated or corrupted document', () => {
+  const text = GOOD.replace(
+    'Route POST /api/invoice/batch found in InvoiceController.cs:215-240.',
+    [
+      'Route POST /api/invoice/batch found in InvoiceController.cs:215-240.',
+      '',
+      FENCE,
+      'echo "this fence is never closed"',
+    ].join('\n'),
+  )
+  const result = parseQueueItem(text, join(queueDir, 'q-invoice-batch-scope.md'))
+  expect(result.ok).toBe(false)
+  if (!result.ok) {
+    const msg = result.errors.join(' ')
+    expect(msg).toContain('unclosed')
+    expect(msg).toContain('fence')
+  }
+})

package/skills/migrate/scripts/__tests__/report.test.ts

@@ -0,0 +1,150 @@
+import { afterEach, beforeEach, expect, test } from 'bun:test'
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { writeConfig } from '../config.ts'
+import { storePaths } from '../paths.ts'
+import { renderLedger, renderRequirements } from '../report.ts'
+import { runReport } from '../report-cmd.ts'
+import type { Element, Requirement } from '../types.ts'
+
+let root: string
+
+beforeEach(async () => {
+  root = await mkdtemp(join(tmpdir(), 'migrate-report-'))
+  await mkdir(join(root, '.migrate'), { recursive: true })
+})
+
+afterEach(async () => {
+  await rm(root, { recursive: true, force: true })
+})
+
+const ELEMENT: Element = {
+  id: 'route-get-api-users',
+  surface: 'routes',
+  element: 'GET /api/users',
+  found_by: ['code', 'nav'],
+  disposition: { kind: 'mapped', fr: 'UM-001' },
+  refs: [{ kind: 'src', path: 'Controllers/Users.cs', lines: [42, 58] }],
+  lens: 'code',
+  batch: 'b-1',
+  notes: 'first',
+}
+
+const REQUIREMENT: Requirement = {
+  id: 'UM-001',
+  cap: 'user-management',
+  requirement: 'List users | paginated',
+  actors: 'User',
+  objects: 'User',
+  rules: '-',
+  origin: 'intended',
+  confidence: { kind: 'confirmed' },
+  citations: [{ kind: 'ledger', id: 'route-get-api-users' }],
+  parity: { kind: 'rubric', level: 'high' },
+  batch: 'b-1',
+}
+
+test('the ledger renders one section per surface with a header banner', () => {
+  const md = renderLedger([ELEMENT])
+  expect(md).toContain('generated by `migrate report`')
+  expect(md).toContain('## routes')
+  expect(md).toContain('route-get-api-users')
+  expect(md).toContain('mapped:UM-001')
+  expect(md).toContain('code,nav')
+})
+
+test('a pipe inside a cell is escaped so the table survives', () => {
+  const md = renderRequirements([REQUIREMENT])
+  expect(md).toContain('List users \\| paginated')
+  // Split on unescaped pipes only: a plain split('|') would also split on the
+  // \| this test exists to verify, and would always agree with itself.
+  const columns = (line: string): number => line.split(/(?<!\\)\|/).length
+  const header = md.split('\n').find((l) => l.startsWith('| id '))
+  const row = md.split('\n').find((l) => l.includes('UM-001'))
+  expect(header).toBeDefined()
+  expect(row).toBeDefined()
+  expect(columns(row as string)).toBe(columns(header as string))
+})
+
+// The assertion above is only worth having if it can actually fail. This
+// reproduces, by hand, exactly what renderRequirements would emit if `cell()`
+// regressed to not escaping '|' at all: the requirement cell's literal pipe
+// stays raw instead of becoming '\|'. A plain line.split('|') would count
+// that raw pipe as a column break in BOTH the correctly-escaped and the
+// broken case identically (it does not look at the preceding character),
+// so it can never distinguish them -- which is why the brief's original
+// `line.split('|')` version always agreed with itself regardless of what
+// the code did. The unescaped-pipe split used above does not have that
+// blind spot: it must report the broken row as having one more column than
+// the header, which is exactly what a bug caught by this test looks like.
+test('the corrected column-count assertion genuinely fails when pipe-escaping is missing', () => {
+  const header =
+    '| id | requirement | actors | objects | rules | confidence | origin | citations | parity |'
+  const brokenRow =
+    '| UM-001 | List users | paginated | User | User | - | confirmed | intended | route-get-api-users | rubric:high |'
+  const columns = (line: string): number => line.split(/(?<!\\)\|/).length
+  expect(columns(brokenRow)).not.toBe(columns(header))
+})
+
+test('confidence and parity render in their grammar form', () => {
+  const md = renderRequirements([
+    {
+      ...REQUIREMENT,
+      confidence: { kind: 'queued', queue: 'q-a' },
+      parity: { kind: 'rubric', level: 'moderate', queue: 'q-a' },
+    },
+  ])
+  expect(md).toContain('queued:q-a')
+  expect(md).toContain('rubric:moderate:q-a')
+})
+
+test('an empty store still renders a valid document', () => {
+  const md = renderLedger([])
+  expect(md).toContain('No surface elements recorded')
+})
+
+// report writes generated views next to the store by default, never inside
+// the read-only source checkout. assertNotUnderSource throws by design (see
+// paths.test.ts and store.test.ts); report-cmd.ts deliberately does not
+// catch that throw itself (unlike census-cmd.ts, import-cmd.ts and
+// queue-cmd.ts), relying instead on bin/migrate.ts's central error guard to
+// turn it into a clean exit-2 diagnostic -- so at this layer the contract
+// under test is that runReport rejects, not that it returns 2.
+test('report refuses to write when the output directory sits inside the configured source tree', async () => {
+  await writeConfig(root, { sourcePath: root, scope: 'all', targetName: 'newapp' })
+  await expect(runReport({ root })).rejects.toThrow(/source/)
+})
+
+async function captureStderr(fn: () => Promise<number>): Promise<{ code: number; text: string }> {
+  const out: string[] = []
+  const original = process.stderr.write.bind(process.stderr)
+  process.stderr.write = ((s: string) => {
+    out.push(s)
+    return true
+  }) as typeof process.stderr.write
+  try {
+    const code = await fn()
+    return { code, text: out.join('') }
+  } finally {
+    process.stderr.write = original
+  }
+}
+
+// Important finding 3: a malformed queue item used to be dropped from
+// queue.md with no trace at all -- the file still carried its "generated by
+// `migrate report`" banner, exit was 0, and an owner handed queue.md alone
+// had no way to learn a queue item existed that this run could not read.
+// `check` and `queue list` already flag the identical condition and exit 1;
+// report must not be the one command in the CLI that hides it.
+test('report surfaces a malformed queue item on stderr and exits 1, not silently 0', async () => {
+  await writeConfig(root, { sourcePath: join(root, 'legacy'), scope: 'all', targetName: 'newapp' })
+  const p = storePaths(root)
+  await mkdir(p.queueDir, { recursive: true })
+  await writeFile(join(p.queueDir, 'q-broken.md'), 'not a queue item at all')
+
+  const { code, text } = await captureStderr(() => runReport({ root }))
+
+  expect(code).toBe(1)
+  expect(text).toContain('q-broken.md')
+})