@iceinvein/agent-skills 0.2.0 → 0.4.0

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%)')
+})

package/skills/migrate/scripts/__tests__/e2e-express.test.ts

@@ -755,7 +755,7 @@ function readTomlString(text: string, key: string): string {
   return match[1]
 }
 
-test('contract-only run driven probe through queue, ending green at check --phase queue', async () => {
+test('contract-only run driven probe through handoff, ending green at a plain check', async () => {
   const groundTruthPath = join(source, 'GROUND-TRUTH.md')
   const rows = await parseGroundTruth(groundTruthPath)
   expect(rows.length).toBeGreaterThan(0)
@@ -1012,8 +1012,8 @@ test('contract-only run driven probe through queue, ending green at check --phas
 
   // 10. Phase 5, queue. Every item this run owed was filed in the pass that
   // named it, so this phase closes on the status flip, exactly as queue.md
-  // says: closing is not "the queue is empty", since nothing in this milestone
-  // adjudicates an item.
+  // says: closing is not "the queue is empty", since phase 5 itself never
+  // adjudicates an item. Phase 6, below, is where they get decided.
   const listed = await migrate(['queue', 'list', '--open'])
   expect(listed.code).toBe(0)
   expect(listed.out).toContain(`${Object.keys(QUEUE_ITEMS).length + 1} item(s)`)
@@ -1025,12 +1025,13 @@ test('contract-only run driven probe through queue, ending green at check --phas
   expect(green.out).not.toContain('Violations')
   expect(green.code).toBe(0)
 
-  // 12. Plain `migrate check` gates every phase through handoff, and fails on
-  // exactly the two that have no verb in this milestone. The violation count
-  // is what makes "exactly" an assertion rather than a hope.
+  // 12. Plain `migrate check` gates every phase through handoff. A run that
+  // stops at the queue fails it on three distinct fronts, and naming each one
+  // is what makes this an assertion rather than a hope: the two phases still
+  // pending, every queue item nobody has ruled on, and the handoff that never
+  // emitted anything.
   const full = await migrate(['check'])
   expect(full.code).toBe(1)
-  expect(full.out).toContain('Violations (2):')
   expect(full.out).toContain('  run-state:')
   expect(full.out).toContain(
     '    phase adjudicate is pending; every phase through handoff must be done',
@@ -1038,6 +1039,10 @@ test('contract-only run driven probe through queue, ending green at check --phas
   expect(full.out).toContain(
     '    phase handoff is pending; every phase through handoff must be done',
   )
+  expect(full.out).toContain('  adjudication:')
+  expect(full.out).toContain('is still open; every queue item needs a ruling before handoff')
+  expect(full.out).toContain('  handoff:')
+  expect(full.out).toContain('no handoff.json in the store')
 
   // 13. The terminus assertion in step 11 is load-bearing, shown by mutation
   // rather than asserted: nulling every requirement's parity plan is a phase-4
@@ -1090,4 +1095,159 @@ test('contract-only run driven probe through queue, ending green at check --phas
   expect(afterRemoval.out).toContain(
     `lens census for ${mutatedSurface} claims in_ledger 0 + added ${claimed} = ${claimed} element(s) in the ledger, but elements.jsonl has ${actual}`,
   )
+  await writeFile(elementsPath, elementsText)
+  expect((await migrate(['check', '--phase', 'queue'])).code).toBe(0)
+
+  // 15. Phase 6, adjudicate. The review sheet first, because that is how the
+  // phase is meant to be worked: one pass over every open item with its
+  // recommendation in view, rather than opening four files.
+  const sheet = await migrate(['adjudicate'])
+  expect(sheet.code).toBe(0)
+  expect(sheet.out).toContain(`${Object.keys(QUEUE_ITEMS).length + 1} open`)
+  for (const id of [...Object.keys(QUEUE_ITEMS), QUEUE_ID]) {
+    expect(sheet.out).toContain(`${id} [`)
+  }
+
+  const RULINGS: Record<string, string> = {
+    'q-express-user-list-source':
+      'the empty list is the real behaviour; the table stays unread and unmapped',
+    'q-express-mailer-delivery-unobservable':
+      'accept the rubric at moderate; delivery is unobservable from the source alone',
+    'q-express-users-table-unwired': 'the table is in scope and stays mapped to UD-002',
+    [QUEUE_ID]: 'the scaffold row is enumeration noise and is skipped by name',
+  }
+  for (const [id, ruling] of Object.entries(RULINGS)) {
+    const ruled = await migrate(['adjudicate', id, '--ruling', ruling])
+    expect(ruled.code).toBe(0)
+    expect(ruled.out).toContain('open -> adjudicated')
+  }
+  // Re-ruling one of them refuses without --force, so an owner's recorded
+  // decision cannot be replaced by a re-run that meant no harm.
+  const reruled = await migrate(['adjudicate', QUEUE_ID, '--ruling', 'something else'])
+  expect(reruled.code).toBe(1)
+  expect(reruled.err).toContain('--force')
+
+  expect((await migrate(['adjudicate'])).out).toContain('0 open')
+  expect((await migrate(['phase', 'adjudicate', '--status', 'done'])).code).toBe(0)
+
+  // 16. Phase 7, handoff. UD-006 still carries a `queued` confidence, and its
+  // queue item is now adjudicated, so it no longer blocks: that is the whole
+  // point of measuring blockers against open items rather than against the
+  // confidence field.
+  const dry = await migrate(['handoff', '--dry-run'])
+  expect(dry.code).toBe(0)
+  expect(dry.out).toContain('plan:')
+  expect(dry.out).toContain('nothing written')
+  expect(await Bun.file(join(storeDir, 'handoff.json')).exists()).toBe(false)
+
+  const emitted = await migrate(['handoff'])
+  expect(emitted.code).toBe(0)
+  expect(emitted.out).toContain('adapter markdown')
+
+  const handoffFile = JSON.parse(await readFile(join(storeDir, 'handoff.json'), 'utf8'))
+  expect(handoffFile.basis.emitted).toBe(REQUIREMENTS.length)
+  // Every capability the seam declared reached a work item.
+  expect(handoffFile.items).toHaveLength(CAPABILITIES.length)
+  const roadmapPath = join(target, 'docs', 'migrate', 'roadmap.md')
+  const roadmap = await readFile(roadmapPath, 'utf8')
+  for (const r of REQUIREMENTS) expect(roadmap).toContain(`- [ ] ${r.id} `)
+
+  expect((await migrate(['phase', 'handoff', '--status', 'done'])).code).toBe(0)
+
+  // 17. The milestone's acceptance proof. Plain `migrate check`, with no
+  // --phase, gating every phase through handoff, exits 0. This is the first
+  // time in the project's history that the unbounded gate can pass at all.
+  const complete = await migrate(['check'])
+  expect(complete.out).not.toContain('Violations')
+  expect(complete.code).toBe(0)
+
+  // 18. Coverage, read back through the adapter that emitted the work. Two
+  // boxes ticked by hand, one dated and one not, which is what an owner
+  // actually does to a roadmap.
+  const built = ['UD-001', 'UD-002']
+  let ticked = roadmap
+  ticked = ticked.replace(`- [ ] ${built[0]} `, `- [x] ${built[0]} <!-- done:2026-08-10 --> `)
+  ticked = ticked.replace(`- [ ] ${built[1]} `, `- [x] ${built[1]} <!-- done:2026-08-12 --> `)
+  await writeFile(roadmapPath, ticked)
+
+  const coverage = await migrate(['coverage'])
+  expect(coverage.code).toBe(0)
+  expect(coverage.out).toContain('evidence: markdown roadmap checkboxes, dated in file')
+  // The fixture carries two non-confirmed requirements, UD-006 (`queued`) and
+  // one inferred. Both sit outside the confirmed denominator and are reported
+  // as exclusions rather than counted against delivery: parity is a promise
+  // about behaviour the run confirmed.
+  expect(coverage.out).toContain(
+    'excluded: 2 non-confirmed (user-directory 1, welcome-notification 1)',
+  )
+  expect(coverage.out).toMatch(/built 2\/\d+ confirmed requirements/)
+
+  // Re-running handoff after the boxes were ticked must not erase them. This
+  // is the data-loss regression the markdown adapter exists to avoid, checked
+  // here against a real store rather than a unit fixture.
+  expect((await migrate(['handoff'])).code).toBe(0)
+  const afterRerun = await readFile(roadmapPath, 'utf8')
+  expect(afterRerun).toContain(`- [x] ${built[0]} <!-- done:2026-08-10 --> `)
+  expect(afterRerun).toContain(`- [x] ${built[1]} <!-- done:2026-08-12 --> `)
+
+  // 19. Forecast. It refuses before the owner has attested anything, which is
+  // the difference between a projection and a guess.
+  const unattested = await migrate(['forecast'])
+  expect(unattested.code).toBe(1)
+  expect(unattested.err).toContain('forecast-assumptions.md')
+
+  await writeFile(
+    join(storeDir, 'forecast-assumptions.md'),
+    [
+      '---',
+      'attestedBy: e2e',
+      'attestedDate: 2026-08-13',
+      '---',
+      '',
+      '## Territories',
+      '',
+      '| capability | territory |',
+      '| --- | --- |',
+      ...CAPABILITIES.map((c) => `| ${c.slug} | established |`),
+      '',
+      '## Multipliers',
+      '',
+      '| territory | multiplier |',
+      '| --- | --- |',
+      '| established | 1.0 |',
+      '',
+      '## Scenarios',
+      '',
+      '| label | rate | streams | tax | note |',
+      '| --- | --- | --- | --- | --- |',
+      '| steady | as-is | 1 | 0 | measured |',
+      '| target | 2 | 1 | 0 | owner target |',
+      '',
+      '## Caveats',
+      '',
+      '- The fixture is not a real campaign.',
+      '',
+    ].join('\n'),
+  )
+
+  const forecast = await migrate(['forecast'])
+  expect(forecast.code).toBe(0)
+  expect(forecast.out).toContain('attested by e2e on 2026-08-13')
+  // Two dated completions is exactly the minimum, so the measured rows
+  // project; the target row is labelled as owner-attested either way.
+  expect(forecast.out).toContain('target (owner-attested, nothing measures this)')
+  expect(forecast.out).toContain('The fixture is not a real campaign.')
+
+  // 20. The acceptance proof is load-bearing, shown by mutation: reopening one
+  // queue item must break the plain check that step 17 asserted, and only on
+  // the adjudication gate.
+  const reopenPath = join(storeDir, 'queue', `${QUEUE_ID}.md`)
+  const ruledText = await readFile(reopenPath, 'utf8')
+  await writeFile(reopenPath, ruledText.replace('status: adjudicated', 'status: open'))
+  const reopened = await migrate(['check'])
+  expect(reopened.code).toBe(1)
+  expect(reopened.out).toContain('  adjudication:')
+  expect(reopened.out).toContain(QUEUE_ID)
+  await writeFile(reopenPath, ruledText)
+  expect((await migrate(['check'])).code).toBe(0)
 })

package/skills/migrate/scripts/__tests__/e2e-webforms.test.ts

@@ -1208,12 +1208,13 @@ test('aspnet recipe run driven probe through queue, ending green at check --phas
   expect(green.out).not.toContain('Violations')
   expect(green.code).toBe(0)
 
-  // 13. Plain `migrate check` gates every phase through handoff, and fails on
-  // exactly the two that have no verb in this milestone. The violation count
-  // is what makes "exactly" an assertion rather than a hope.
+  // 13. Plain `migrate check` gates every phase through handoff. A run that
+  // stops at the queue fails it on three distinct fronts, and naming each one
+  // is what makes this an assertion rather than a hope: the two phases still
+  // pending, every queue item nobody has ruled on, and the handoff that never
+  // emitted anything.
   const full = await migrate(['check'])
   expect(full.code).toBe(1)
-  expect(full.out).toContain('Violations (2):')
   expect(full.out).toContain('  run-state:')
   expect(full.out).toContain(
     '    phase adjudicate is pending; every phase through handoff must be done',
@@ -1221,6 +1222,10 @@ test('aspnet recipe run driven probe through queue, ending green at check --phas
   expect(full.out).toContain(
     '    phase handoff is pending; every phase through handoff must be done',
   )
+  expect(full.out).toContain('  adjudication:')
+  expect(full.out).toContain('is still open; every queue item needs a ruling before handoff')
+  expect(full.out).toContain('  handoff:')
+  expect(full.out).toContain('no handoff.json in the store')
 
   // 14. The terminus assertion in step 12 is load-bearing, shown by mutation
   // rather than asserted: nulling every requirement's parity plan is a phase-4