@iceinvein/agent-skills 0.3.0 → 0.4.0

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

@@ -0,0 +1,332 @@
+import { afterEach, beforeEach, expect, test } from 'bun:test'
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { applyRuling, renderReviewSheet } from '../adjudicate-cmd.ts'
+import { parseQueueItem } from '../queue.ts'
+import type { QueueItem } from '../types.ts'
+
+const CLI = join(import.meta.dir, '..', '..', 'bin', 'migrate.ts')
+
+let target: string
+let source: string
+
+async function migrate(args: string[]): Promise<{ code: number; out: string; err: string }> {
+  const proc = Bun.spawn(['bun', CLI, ...args], { cwd: target, stdout: 'pipe', stderr: 'pipe' })
+  const [out, err] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ])
+  await proc.exited
+  return { code: proc.exitCode ?? -1, out, err }
+}
+
+function item(id: string, severity: string, extra = ''): string {
+  return `---
+id: ${id}
+severity: ${severity}
+status: open
+${extra}---
+
+## Evidence
+
+Two tables both look like they own the join.
+
+## Options
+
+1. Give it to billing.
+2. Give it to scheduling.
+
+## Recommendation
+
+Billing owns it, on the strength of the write sites.
+`
+}
+
+async function addItem(id: string, severity: string, extra = ''): Promise<void> {
+  const path = join(target, `${id}.md`)
+  await writeFile(path, item(id, severity, extra))
+  const added = await migrate(['queue', 'add', path])
+  expect(added.code).toBe(0)
+}
+
+beforeEach(async () => {
+  target = await mkdtemp(join(tmpdir(), 'migrate-adjudicate-'))
+  source = join(target, 'legacy')
+  await Bun.write(join(source, 'app.js'), '// legacy\n')
+  const init = await migrate(['init', '--source', source, '--scope', 'x', '--name', 'target'])
+  expect(init.code).toBe(0)
+})
+
+afterEach(async () => {
+  await rm(target, { recursive: true, force: true })
+})
+
+// --- applyRuling, pure ---
+
+test('applyRuling keeps unowned keys in place and the body byte-identical', () => {
+  const body = `
+## Evidence
+
+A body with a --- line inside it:
+
+---
+
+and a fenced block:
+
+\`\`\`
+status: open
+ruling: not a real key
+\`\`\`
+
+## Options
+
+Only one.
+
+## Recommendation
+
+Take it.
+`
+  // `severity` deliberately sits AFTER `status`, the one owned key already
+  // present. With the owned key last, an implementation that simply dropped
+  // owned keys and appended them would produce the same output as one that
+  // replaces in place, and this test would assert nothing about position.
+  const before = `---
+id: q-table-ownership
+owner: dik
+status: open
+severity: critical
+---${body}`
+
+  const after = applyRuling(before, 'billing owns it', '2026-08-13')
+
+  // Body preserved byte for byte, including the --- line and the fence.
+  expect(after.slice(after.indexOf('\n---', 3) + 4)).toBe(body)
+  const fm = after.slice(4, after.indexOf('\n---', 3))
+  expect(fm.split('\n')).toEqual([
+    'id: q-table-ownership',
+    'owner: dik',
+    'status: adjudicated',
+    'severity: critical',
+    'ruling: billing owns it',
+    'adjudicated: 2026-08-13',
+  ])
+})
+
+test('applyRuling rewrites an existing ruling in place rather than appending a second', () => {
+  const before = `---
+id: q-x
+severity: minor
+status: adjudicated
+ruling: an earlier call
+adjudicated: 2026-08-01
+---
+
+## Evidence
+
+e
+
+## Options
+
+o
+
+## Recommendation
+
+r
+`
+  const after = applyRuling(before, 'the revised call', '2026-08-13')
+  const fm = after.slice(4, after.indexOf('\n---', 3))
+  expect(fm.split('\n')).toEqual([
+    'id: q-x',
+    'severity: minor',
+    'status: adjudicated',
+    'ruling: the revised call',
+    'adjudicated: 2026-08-13',
+  ])
+  expect(after.match(/^ruling:/gm)).toHaveLength(1)
+})
+
+test('applyRuling refuses a ruling that would break the frontmatter it writes into', () => {
+  const before = item('q-x', 'minor')
+  // A line break is the whole hazard: it lets the value inject further
+  // frontmatter keys, or a closing fence. A value of '---' is not a hazard,
+  // because it is written as `ruling: ---` and so never sits at line start.
+  expect(() => applyRuling(before, 'line one\nline two', '2026-08-13')).toThrow(/newline/)
+  expect(() => applyRuling(before, 'line one\rline two', '2026-08-13')).toThrow(/newline/)
+  expect(() => applyRuling(before, '   ', '2026-08-13')).toThrow(/empty/)
+  expect(applyRuling(before, '---', '2026-08-13')).toContain('ruling: ---')
+})
+
+// --- renderReviewSheet, pure ---
+
+test('renderReviewSheet is severity-ordered, carries each recommendation, and counts open', () => {
+  const items: QueueItem[] = [
+    {
+      id: 'q-minor-thing',
+      severity: 'minor',
+      status: 'open',
+      evidence: 'e',
+      options: 'o',
+      recommendation: 'Leave it alone.\nA second line nobody needs here.',
+      path: 'p',
+    },
+    {
+      id: 'q-big-thing',
+      severity: 'critical',
+      status: 'adjudicated',
+      ruling: 'done already',
+      evidence: 'e',
+      options: 'o',
+      recommendation: 'Split the table.',
+      path: 'p',
+    },
+  ]
+  expect(renderReviewSheet(items)).toBe(
+    [
+      'q-big-thing [critical] adjudicated - Split the table.',
+      'q-minor-thing [minor] open - Leave it alone.',
+      '',
+      '1 open',
+    ].join('\n'),
+  )
+})
+
+// --- the verb ---
+
+test('adjudicate with no id prints the review sheet', async () => {
+  await addItem('q-alpha', 'critical')
+  await addItem('q-beta', 'minor')
+
+  const sheet = await migrate(['adjudicate'])
+  expect(sheet.code).toBe(0)
+  expect(sheet.out).toContain('q-alpha [critical] open - Billing owns it')
+  expect(sheet.out).toContain('q-beta [minor] open')
+  expect(sheet.out).toContain('2 open')
+})
+
+test('adjudicate records a ruling, flips status, and records a batch', async () => {
+  await addItem('q-alpha', 'critical')
+
+  const ruled = await migrate(['adjudicate', 'q-alpha', '--ruling', 'billing owns it'])
+  expect(ruled.code).toBe(0)
+  expect(ruled.out).toContain('q-alpha')
+  expect(ruled.out).toContain('open -> adjudicated')
+  // The verb points at the writer that applies the consequence, since it does
+  // not touch the row files itself.
+  expect(ruled.out).toContain('migrate import')
+
+  const text = await readFile(join(target, '.migrate', 'queue', 'q-alpha.md'), 'utf8')
+  expect(text).toContain('status: adjudicated')
+  expect(text).toContain('ruling: billing owns it')
+  expect(text).toMatch(/adjudicated: \d{4}-\d{2}-\d{2}/)
+  // The body survived.
+  expect(text).toContain('Two tables both look like they own the join.')
+
+  const phases = JSON.parse(await readFile(join(target, '.migrate', 'phases.json'), 'utf8'))
+  expect(phases.phases.adjudicate.batches).toHaveLength(1)
+  expect(phases.phases.adjudicate.batches[0].id).toBe('b-adjudicate-q-alpha')
+})
+
+test('adjudicate refuses an unknown id as a usage error', async () => {
+  await addItem('q-alpha', 'critical')
+  const missing = await migrate(['adjudicate', 'q-nope', '--ruling', 'x'])
+  expect(missing.code).toBe(2)
+  expect(missing.err).toContain('q-nope')
+})
+
+test('adjudicate refuses to overwrite an existing ruling without --force', async () => {
+  await addItem('q-alpha', 'critical')
+  await migrate(['adjudicate', 'q-alpha', '--ruling', 'the first call'])
+
+  const again = await migrate(['adjudicate', 'q-alpha', '--ruling', 'a different call'])
+  expect(again.code).toBe(1)
+  // The existing ruling is printed, so the caller sees what they would have lost.
+  expect(again.err).toContain('the first call')
+  expect(again.err).toContain('--force')
+
+  const forced = await migrate(['adjudicate', 'q-alpha', '--ruling', 'a different call', '--force'])
+  expect(forced.code).toBe(0)
+  const text = await readFile(join(target, '.migrate', 'queue', 'q-alpha.md'), 'utf8')
+  expect(text).toContain('ruling: a different call')
+})
+
+test('adjudicate refuses a ruling containing a newline', async () => {
+  await addItem('q-alpha', 'critical')
+  const bad = await migrate(['adjudicate', 'q-alpha', '--ruling', 'one\ntwo'])
+  expect(bad.code).toBe(2)
+  expect(bad.err).toContain('newline')
+})
+
+test('adjudicate reports a queue file that will not parse as a content failure', async () => {
+  await addItem('q-alpha', 'critical')
+  // Break the file after it is in the store: an empty Options section.
+  const path = join(target, '.migrate', 'queue', 'q-alpha.md')
+  const text = await readFile(path, 'utf8')
+  await writeFile(path, text.replace('1. Give it to billing.\n2. Give it to scheduling.\n', ''))
+
+  const broken = await migrate(['adjudicate', 'q-alpha', '--ruling', 'x'])
+  expect(broken.code).toBe(1)
+  expect(broken.err).toContain('q-alpha')
+})
+
+test('an indented --- inside the frontmatter is refused, not silently mis-fenced', () => {
+  // queue.ts closes the block at any line STARTING with ---, so a line that
+  // only looks like a fence after trimming is body to the parser and was a
+  // fence here. The owned keys landed above the real fence, the parser's
+  // last-key-wins read still saw `status: open`, and the command reported
+  // success over an item that stayed open forever.
+  const before = `---
+id: q-x
+  ---
+severity: minor
+status: open
+---
+
+## Evidence
+
+e
+
+## Options
+
+o
+
+## Recommendation
+
+r
+`
+  const after = applyRuling(before, 'settled', '2026-08-13')
+  // Whatever this produces, it must read back as adjudicated through the
+  // parser every other command uses.
+  const reparsed = parseQueueItem(after, 'q-x.md')
+  expect(reparsed.ok && reparsed.value.status).toBe('adjudicated')
+})
+
+test('a nested key named status is left alone', () => {
+  const before = `---
+id: q-x
+severity: minor
+status: open
+meta:
+  status: draft
+  ruling: none yet
+---
+
+## Evidence
+
+e
+
+## Options
+
+o
+
+## Recommendation
+
+r
+`
+  const after = applyRuling(before, 'settled', '2026-08-13')
+  const fm = after.slice(4, after.indexOf('\n---', 3))
+  expect(fm).toContain('  status: draft')
+  expect(fm).toContain('  ruling: none yet')
+  expect(fm.match(/^status:/gm)).toHaveLength(1)
+  expect(fm.match(/^ruling:/gm)).toHaveLength(1)
+})

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

@@ -0,0 +1,179 @@
+import { expect, test } from 'bun:test'
+import { parseAssumptions, validateAssumptions } from '../assumptions.ts'
+import type { CapCoverage } from '../coverage.ts'
+
+const GOOD = `---
+attestedBy: Dik Rana
+attestedDate: 2026-08-13
+---
+
+# Forecast assumptions
+
+Prose the parser ignores.
+
+## Territories
+
+| capability | territory |
+| --- | --- |
+| user-management | established |
+| billing | unknown-ground |
+
+## Multipliers
+
+| territory | multiplier |
+| --- | --- |
+| established | 1.0 |
+| unknown-ground | 2.5 |
+
+## Scenarios
+
+| label | rate | streams | tax | note |
+| --- | --- | --- | --- | --- |
+| as-is | as-is | 1 | 0 | one stream, measured |
+| pushing | active | 2 | 0.2 | two streams, coordination tax |
+| target | 1.5 | 2 | 0 | owner target, nothing measures this |
+
+## Caveats
+
+- The billing rewrite has no precedent in this codebase.
+`
+
+const cap = (slug: string, confirmedTotal: number): CapCoverage => ({
+  slug,
+  title: slug,
+  confirmedTotal,
+  covered: 0,
+  coveredIds: [],
+  uncoveredIds: [],
+})
+
+test('a complete file parses into territories, multipliers, scenarios and caveats', () => {
+  const a = parseAssumptions(GOOD, 'f.md')
+  expect(a.attestedBy).toBe('Dik Rana')
+  expect(a.attestedDate).toBe('2026-08-13')
+  expect(a.territories).toEqual({ 'user-management': 'established', billing: 'unknown-ground' })
+  expect(a.multipliers).toEqual({ established: 1, 'unknown-ground': 2.5 })
+  expect(a.scenarios).toEqual([
+    { label: 'as-is', rate: 'as-is', streams: 1, tax: 0, note: 'one stream, measured' },
+    {
+      label: 'pushing',
+      rate: 'active',
+      streams: 2,
+      tax: 0.2,
+      note: 'two streams, coordination tax',
+    },
+    { label: 'target', rate: 1.5, streams: 2, tax: 0, note: 'owner target, nothing measures this' },
+  ])
+  expect(a.caveats).toEqual(['The billing rewrite has no precedent in this codebase.'])
+})
+
+test('an unattested file is refused, naming the missing field', () => {
+  expect(() => parseAssumptions(GOOD.replace('attestedBy: Dik Rana\n', ''), 'f.md')).toThrow(
+    /attestedBy/,
+  )
+  expect(() => parseAssumptions(GOOD.replace('attestedDate: 2026-08-13\n', ''), 'f.md')).toThrow(
+    /attestedDate/,
+  )
+})
+
+test('a missing required section is refused by name', () => {
+  const noMultipliers = GOOD.replace(/## Multipliers[\s\S]*?\n\n## Scenarios/, '## Scenarios')
+  expect(() => parseAssumptions(noMultipliers, 'f.md')).toThrow(/Multipliers/)
+})
+
+test('a scenario rate must be as-is, active, or a positive number', () => {
+  const bad = GOOD.replace('| as-is | as-is | 1 | 0 |', '| as-is | sometimes | 1 | 0 |')
+  expect(() => parseAssumptions(bad, 'f.md')).toThrow(/rate/)
+  const zero = GOOD.replace('| target | 1.5 | 2 | 0 |', '| target | 0 | 2 | 0 |')
+  expect(() => parseAssumptions(zero, 'f.md')).toThrow(/rate/)
+})
+
+test('tax must sit in [0, 1)', () => {
+  expect(() =>
+    parseAssumptions(
+      GOOD.replace('| pushing | active | 2 | 0.2 |', '| pushing | active | 2 | 1 |'),
+      'f.md',
+    ),
+  ).toThrow(/tax/)
+  expect(() =>
+    parseAssumptions(
+      GOOD.replace('| pushing | active | 2 | 0.2 |', '| pushing | active | 2 | -0.1 |'),
+      'f.md',
+    ),
+  ).toThrow(/tax/)
+  // 0.9 is legal.
+  expect(
+    parseAssumptions(
+      GOOD.replace('| pushing | active | 2 | 0.2 |', '| pushing | active | 2 | 0.9 |'),
+      'f.md',
+    ).scenarios[1]?.tax,
+  ).toBe(0.9)
+})
+
+test('streams must be positive', () => {
+  expect(() =>
+    parseAssumptions(
+      GOOD.replace('| as-is | as-is | 1 | 0 |', '| as-is | as-is | 0 | 0 |'),
+      'f.md',
+    ),
+  ).toThrow(/streams/)
+})
+
+test('a multiplier must be a positive number', () => {
+  expect(() =>
+    parseAssumptions(GOOD.replace('| established | 1.0 |', '| established | 0 |'), 'f.md'),
+  ).toThrow(/multiplier/)
+})
+
+test('every parse failure names the file', () => {
+  expect(() => parseAssumptions('no frontmatter here', 'docs/x.md')).toThrow(/docs\/x\.md/)
+})
+
+// --- validation against measured coverage ---
+
+test('a capability with confirmed requirements and no territory fails by name', () => {
+  const a = parseAssumptions(GOOD, 'f.md')
+  const errors = validateAssumptions(a, [cap('user-management', 2), cap('notifications', 5)])
+  expect(errors).toHaveLength(1)
+  expect(errors[0]).toContain('notifications')
+})
+
+test('a capability with no confirmed requirements needs no territory', () => {
+  const a = parseAssumptions(GOOD, 'f.md')
+  expect(validateAssumptions(a, [cap('user-management', 2), cap('notifications', 0)])).toEqual([])
+})
+
+test('a territory with no multiplier fails by name', () => {
+  const a = parseAssumptions(GOOD.replace('| unknown-ground | 2.5 |\n', ''), 'f.md')
+  const errors = validateAssumptions(a, [cap('user-management', 1), cap('billing', 1)])
+  expect(errors.some((e) => e.includes('unknown-ground'))).toBe(true)
+})
+
+test('zero scenarios fails', () => {
+  const a = parseAssumptions(
+    GOOD.replace(/\| as-is \| as-is[\s\S]*?nothing measures this \|\n/, ''),
+    'f.md',
+  )
+  expect(a.scenarios).toEqual([])
+  expect(validateAssumptions(a, [cap('user-management', 1)])).toContain('no scenarios defined')
+})
+
+test('a table written without a separator row keeps every data row', () => {
+  // slice(2) dropped two lines positionally, so a missing separator silently
+  // ate the first data row: the owner attested two scenarios and got one, and
+  // the lost row is the as-is baseline the template puts first.
+  const noSeparator = GOOD.replace('| --- | --- | --- | --- | --- |\n', '')
+  const a = parseAssumptions(noSeparator, 'f.md')
+  expect(a.scenarios.map((s) => s.label)).toEqual(['as-is', 'pushing', 'target'])
+})
+
+test('an alignment separator is recognised wherever it sits', () => {
+  const aligned = GOOD.replace(
+    '| --- | --- |\n| user-management',
+    '| :--- | ---: |\n| user-management',
+  )
+  expect(parseAssumptions(aligned, 'f.md').territories).toEqual({
+    'user-management': 'established',
+    billing: 'unknown-ground',
+  })
+})

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

@@ -0,0 +1,192 @@
+import { expect, test } from 'bun:test'
+import { computeCoverage, renderCoverage } from '../coverage.ts'
+import type { HandoffFile } from '../handoff.ts'
+import type { Requirement, Throughput } from '../types.ts'
+
+function req(id: string, cap: string, confidence: Requirement['confidence']): Requirement {
+  return {
+    id,
+    cap,
+    requirement: `requirement ${id}`,
+    actors: 'User',
+    objects: 'Thing',
+    rules: 'none',
+    origin: 'intended',
+    confidence,
+    citations: [],
+    parity: { kind: 'rubric', level: 'high' },
+    batch: 'b-1',
+  }
+}
+
+const CONFIRMED: Requirement['confidence'] = { kind: 'confirmed' }
+const INFERRED: Requirement['confidence'] = { kind: 'inferred' }
+
+const REQS = [
+  req('UM-001', 'user-management', CONFIRMED),
+  req('UM-002', 'user-management', CONFIRMED),
+  req('BI-001', 'billing', CONFIRMED),
+  req('BI-002', 'billing', INFERRED),
+  req('BI-003', 'billing', INFERRED),
+]
+
+const HANDOFF: HandoffFile = {
+  version: 1,
+  adapter: 'markdown',
+  items: [
+    {
+      key: 'billing',
+      title: 'Billing',
+      frs: ['BI-001', 'BI-002', 'BI-003'],
+      dependsOn: [],
+      weight: 3,
+    },
+    {
+      key: 'user-management',
+      title: 'User management',
+      frs: ['UM-001', 'UM-002'],
+      dependsOn: ['billing'],
+      weight: 2,
+    },
+  ],
+  refs: {},
+  basis: { confirmed: 3, emitted: 5, order: ['billing', 'user-management'] },
+}
+
+const through = (completions: Throughput['completions']): Throughput => ({
+  completions,
+  basis: 'markdown roadmap checkboxes, dated in file',
+})
+
+test('the denominator is confirmed requirements only, with exclusions reported', () => {
+  const r = computeCoverage({
+    requirements: REQS,
+    handoff: HANDOFF,
+    throughput: through([
+      { fr: 'UM-001', doneAt: '2026-08-12' },
+      { fr: 'BI-001', doneAt: '2026-08-11' },
+    ]),
+  })
+  // Five requirements exist; three are confirmed; two of those are built.
+  expect(r.confirmed).toBe(3)
+  expect(r.built).toBe(2)
+  expect(r.nonConfirmed).toEqual([{ slug: 'billing', count: 2 }])
+})
+
+test('a completion for a non-confirmed requirement does not inflate the figure', () => {
+  // BI-002 is inferred, so it is outside the denominator. Reporting it as
+  // complete must not push built above the confirmed total it sits over.
+  const r = computeCoverage({
+    requirements: REQS,
+    handoff: HANDOFF,
+    throughput: through([
+      { fr: 'BI-001', doneAt: '2026-08-11' },
+      { fr: 'BI-002', doneAt: '2026-08-11' },
+    ]),
+  })
+  expect(r.built).toBe(1)
+  expect(r.confirmed).toBe(3)
+  expect(r.unknown).toEqual([])
+})
+
+test('capabilities are reported in the emitted dependency order', () => {
+  const r = computeCoverage({ requirements: REQS, handoff: HANDOFF, throughput: through([]) })
+  expect(r.caps.map((c) => c.slug)).toEqual(['billing', 'user-management'])
+})
+
+test('an undated completion counts as built and is reported as undated', () => {
+  const r = computeCoverage({
+    requirements: REQS,
+    handoff: HANDOFF,
+    throughput: through([{ fr: 'UM-001', doneAt: null }]),
+  })
+  expect(r.built).toBe(1)
+  expect(r.undated).toBe(1)
+  expect(renderCoverage(r)).toContain('undated: 1 completion(s)')
+})
+
+test('a completion naming an unknown requirement is collected, not counted', () => {
+  const r = computeCoverage({
+    requirements: REQS,
+    handoff: HANDOFF,
+    throughput: through([
+      { fr: 'UM-001', doneAt: '2026-08-12' },
+      { fr: 'ZZ-999', doneAt: '2026-08-12' },
+    ]),
+  })
+  expect(r.unknown).toEqual(['ZZ-999'])
+  expect(r.built).toBe(1)
+})
+
+test('the rendered report names its evidence and marks a finished capability', () => {
+  const r = computeCoverage({
+    requirements: REQS,
+    handoff: HANDOFF,
+    throughput: through([
+      { fr: 'UM-001', doneAt: '2026-08-12' },
+      { fr: 'UM-002', doneAt: '2026-08-13' },
+    ]),
+  })
+  expect(renderCoverage(r)).toBe(
+    [
+      'built 2/3 confirmed requirements (67%)',
+      'evidence: markdown roadmap checkboxes, dated in file',
+      'excluded: 2 non-confirmed (billing 2)',
+      '',
+      'billing          0/1',
+      'user-management  2/2  done',
+    ].join('\n'),
+  )
+})
+
+test('a store with no confirmed requirements reports zero rather than dividing by zero', () => {
+  const r = computeCoverage({
+    requirements: [req('BI-002', 'billing', INFERRED)],
+    handoff: { ...HANDOFF, basis: { confirmed: 0, emitted: 1, order: ['billing'] } },
+    throughput: through([]),
+  })
+  expect(r.confirmed).toBe(0)
+  expect(renderCoverage(r)).toContain('built 0/0 confirmed requirements (0%)')
+})
+
+test('a capability the emitted order omits is counted and named as stale', () => {
+  // A stale handoff.json used to narrow both numerator and denominator
+  // silently, reporting 100% while confirmed requirements sat unbuilt in a
+  // capability that appeared nowhere in the output.
+  const r = computeCoverage({
+    requirements: REQS,
+    handoff: { ...HANDOFF, basis: { confirmed: 3, emitted: 5, order: ['user-management'] } },
+    throughput: through([
+      { fr: 'UM-001', doneAt: '2026-08-12' },
+      { fr: 'UM-002', doneAt: '2026-08-13' },
+    ]),
+  })
+  expect(r.confirmed).toBe(3)
+  expect(r.built).toBe(2)
+  expect(r.stale).toEqual(['billing'])
+  expect(r.caps.map((c) => c.slug)).toEqual(['user-management', 'billing'])
+  expect(renderCoverage(r)).toContain('stale: 1 capability(ies) not in the emitted work (billing)')
+})
+
+test('the percentage never contradicts the fraction beside it', () => {
+  const at = (built: number, confirmed: number): string => {
+    const reqs = Array.from({ length: confirmed }, (_, i) => req(`X-${i}`, 'billing', CONFIRMED))
+    return renderCoverage(
+      computeCoverage({
+        requirements: reqs,
+        handoff: {
+          ...HANDOFF,
+          items: [],
+          basis: { confirmed, emitted: confirmed, order: ['billing'] },
+        },
+        throughput: through(
+          Array.from({ length: built }, (_, i) => ({ fr: `X-${i}`, doneAt: '2026-08-12' })),
+        ),
+      }),
+    )
+  }
+  expect(at(199, 200)).toContain('built 199/200 confirmed requirements (99%)')
+  expect(at(1, 250)).toContain('built 1/250 confirmed requirements (1%)')
+  expect(at(200, 200)).toContain('(100%)')
+  expect(at(0, 200)).toContain('(0%)')
+})