@iceinvein/agent-skills 0.3.0 → 0.4.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

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

@@ -0,0 +1,280 @@
+import { expect, test } from 'bun:test'
+import { parseAssumptions } from '../assumptions.ts'
+import type { CapCoverage } from '../coverage.ts'
+import { addDays, demandOf, project, renderForecast, velocities } from '../forecast.ts'
+import type { Completion } from '../types.ts'
+
+const ASSUMPTIONS = parseAssumptions(
+  `---
+attestedBy: Dik Rana
+attestedDate: 2026-08-13
+---
+
+## 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 |
+| --- | --- | --- | --- | --- |
+| steady | as-is | 1 | 0 | one stream at the measured pace |
+| target | 2 | 1 | 0 | owner target, nothing measures this |
+
+## Caveats
+
+- Billing has no precedent here.
+`,
+  'f.md',
+)
+
+// billing: 3 confirmed, 1 covered, 2 remaining. user-management: 2 confirmed,
+// 0 covered, 2 remaining. Raw demand 4; weighted 2*2.5 + 2*1.0 = 7.
+const COVERAGE: CapCoverage[] = [
+  {
+    slug: 'billing',
+    title: 'Billing',
+    confirmedTotal: 3,
+    covered: 1,
+    coveredIds: ['BI-001'],
+    uncoveredIds: ['BI-002', 'BI-003'],
+  },
+  {
+    slug: 'user-management',
+    title: 'User management',
+    confirmedTotal: 2,
+    covered: 0,
+    coveredIds: [],
+    uncoveredIds: ['UM-001', 'UM-002'],
+  },
+]
+
+const TODAY = '2026-08-11'
+const DATED: Completion[] = [
+  { fr: 'BI-001', doneAt: '2026-08-01' },
+  { fr: 'BI-004', doneAt: '2026-08-03' },
+  { fr: 'BI-005', doneAt: '2026-08-05' },
+]
+
+test('addDays crosses a month boundary', () => {
+  expect(addDays('2026-08-11', 24)).toBe('2026-09-04')
+})
+
+test('demand is reported both raw and weighted by attested multiplier', () => {
+  const d = demandOf(ASSUMPTIONS, COVERAGE)
+  expect(d.remainingRaw).toBe(4)
+  expect(d.remainingWeighted).toBe(7)
+  // Territories come out in Multipliers-table order, which is what the
+  // milestone sequence walks.
+  expect(d.territories.map((t) => t.territory)).toEqual(['established', 'unknown-ground'])
+  expect(d.territories[1]?.frEquivalents).toBe(5)
+})
+
+test('two measured velocities: calendar days and active days', () => {
+  const v = velocities(DATED, TODAY)
+  // Three completions over eleven calendar days, 2026-08-01 to 2026-08-11
+  // counted inclusively.
+  expect(v.asIs.value).toBeCloseTo(3 / 11, 10)
+  expect(v.asIs.basis).toContain('quiet days included')
+  // Three completions over three days on which something completed.
+  expect(v.active.value).toBe(1)
+  expect(v.active.basis).toContain('something completed')
+})
+
+test('as-is is never faster than active, which is what keeps the band the right way round', () => {
+  // asIs is the pessimistic floor and active the optimistic ceiling. If asIs
+  // can exceed active the band prints its optimistic bound later than its
+  // pessimistic one, which is worse than not printing a band at all. The
+  // dense-cadence case is where an exclusive era made that happen: one
+  // completion per day, ending today.
+  const dense: Completion[] = Array.from({ length: 10 }, (_, i) => ({
+    fr: `X-${i}`,
+    doneAt: `2026-08-${String(i + 1).padStart(2, '0')}`,
+  }))
+  const v = velocities(dense, '2026-08-10')
+  expect(v.asIs.value).toBeLessThanOrEqual(v.active.value ?? 0)
+
+  // And a completion dated ahead of today extends the era rather than being
+  // clamped to a single day, which used to turn a typo into a huge velocity.
+  const future = velocities(
+    [
+      { fr: 'A', doneAt: '2026-08-20' },
+      { fr: 'B', doneAt: '2026-08-22' },
+    ],
+    '2026-08-11',
+  )
+  expect(future.asIs.value).toBeCloseTo(2 / 3, 10)
+  expect(future.asIs.value).toBeLessThanOrEqual(future.active.value ?? 0)
+})
+
+test('a date that is not a real calendar day is dropped rather than parsed as NaN', () => {
+  const v = velocities(
+    [
+      { fr: 'A', doneAt: '2026-08-32' },
+      { fr: 'B', doneAt: '2026-09-01' },
+      { fr: 'C', doneAt: '2026-09-03' },
+    ],
+    '2026-09-05',
+  )
+  // Two usable dates remain, so a rate is still measurable and is not NaN.
+  expect(Number.isNaN(v.asIs.value ?? 0)).toBe(false)
+  expect(v.asIs.value).toBeCloseTo(2 / 5, 10)
+})
+
+test('fewer than two dated completions leaves both velocities unmeasured', () => {
+  const one = velocities([{ fr: 'BI-001', doneAt: '2026-08-01' }], TODAY)
+  expect(one.asIs.value).toBeNull()
+  expect(one.active.value).toBeNull()
+  expect(one.asIs.basis).toContain('one point is not a rate')
+
+  // Undated completions never contribute to a rate, so three of them are still
+  // nothing to measure from.
+  const undated = velocities(
+    [
+      { fr: 'A', doneAt: null },
+      { fr: 'B', doneAt: null },
+      { fr: 'C', doneAt: null },
+    ],
+    TODAY,
+  )
+  expect(undated.asIs.value).toBeNull()
+})
+
+test('a measured scenario projects raw and weighted finishes and carries a band', () => {
+  const projections = project({
+    assumptions: ASSUMPTIONS,
+    demand: demandOf(ASSUMPTIONS, COVERAGE),
+    velocity: velocities(DATED, TODAY),
+    today: TODAY,
+  })
+  const steady = projections[0]
+  expect(steady?.basis).toBe('as-is')
+  expect(steady?.perDay).toBeCloseTo(3 / 11, 10)
+  // 4 raw at 3/11 per day is 15 days; 7 weighted is 26.
+  expect(steady?.daysRaw).toBe(15)
+  expect(steady?.finishRaw).toBe('2026-08-26')
+  expect(steady?.daysWeighted).toBe(26)
+  expect(steady?.finishWeighted).toBe('2026-09-06')
+  // The band applies the same streams and tax to both measured bases, and its
+  // optimistic end is never later than its pessimistic one.
+  expect(steady?.band).toEqual({ optimistic: '2026-08-18', pessimistic: '2026-09-06' })
+  // Milestones accumulate weighted demand in Multipliers order.
+  expect(steady?.milestones).toEqual([
+    { territory: 'established', finish: '2026-08-19' },
+    { territory: 'unknown-ground', finish: '2026-09-06' },
+  ])
+})
+
+test('an owner target projects but carries no band, and is labelled as a target', () => {
+  const projections = project({
+    assumptions: ASSUMPTIONS,
+    demand: demandOf(ASSUMPTIONS, COVERAGE),
+    velocity: velocities(DATED, TODAY),
+    today: TODAY,
+  })
+  const target = projections[1]
+  expect(target?.basis).toBe('target')
+  expect(target?.perDay).toBe(2)
+  expect(target?.daysWeighted).toBe(4)
+  expect(target?.finishWeighted).toBe('2026-08-15')
+  // No measured spread backs an attested rate, so no band is offered.
+  expect(target?.band).toBeNull()
+})
+
+test('with no measured velocity a target still projects and a measured row does not', () => {
+  // This is the flow adapter's situation exactly: coverage but no dates.
+  const projections = project({
+    assumptions: ASSUMPTIONS,
+    demand: demandOf(ASSUMPTIONS, COVERAGE),
+    velocity: velocities([], TODAY),
+    today: TODAY,
+  })
+  expect(projections[0]?.perDay).toBeNull()
+  expect(projections[0]?.finishWeighted).toBeNull()
+  // Still a band, with both ends unmeasurable. An absent band means a target
+  // row, which is a different claim from a measured row nothing can date yet.
+  expect(projections[0]?.band).toEqual({ optimistic: null, pessimistic: null })
+  expect(projections[1]?.finishWeighted).toBe('2026-08-15')
+})
+
+test('the rendered forecast separates measured rows from targets and prints caveats', () => {
+  const out = renderForecast({
+    assumptions: ASSUMPTIONS,
+    demand: demandOf(ASSUMPTIONS, COVERAGE),
+    velocity: velocities(DATED, TODAY),
+    projections: project({
+      assumptions: ASSUMPTIONS,
+      demand: demandOf(ASSUMPTIONS, COVERAGE),
+      velocity: velocities(DATED, TODAY),
+      today: TODAY,
+    }),
+    today: TODAY,
+    undated: 2,
+  })
+  expect(out).toContain('attested by Dik Rana on 2026-08-13')
+  expect(out).toContain('remaining 4 requirement(s), 7 weighted')
+  expect(out).toContain('steady')
+  expect(out).toContain('measured')
+  expect(out).toContain('target (owner-attested, nothing measures this)')
+  expect(out).toContain('Billing has no precedent here.')
+  expect(out).toContain('2 completion(s) carry no date')
+})
+
+test('an unprojectable measured row says so rather than printing nothing', () => {
+  const out = renderForecast({
+    assumptions: ASSUMPTIONS,
+    demand: demandOf(ASSUMPTIONS, COVERAGE),
+    velocity: velocities([], TODAY),
+    projections: project({
+      assumptions: ASSUMPTIONS,
+      demand: demandOf(ASSUMPTIONS, COVERAGE),
+      velocity: velocities([], TODAY),
+      today: TODAY,
+    }),
+    today: TODAY,
+    undated: 0,
+  })
+  expect(out).toContain('not projected')
+})
+
+test('a finished campaign says nothing remains rather than omitting every date', () => {
+  // Zero remaining and no measured rate both leave every date null, but they
+  // are opposite pieces of news and must not print the same way.
+  const done: CapCoverage[] = [
+    {
+      slug: 'billing',
+      title: 'Billing',
+      confirmedTotal: 3,
+      covered: 3,
+      coveredIds: ['BI-001', 'BI-002', 'BI-003'],
+      uncoveredIds: [],
+    },
+  ]
+  const demand = demandOf(ASSUMPTIONS, done)
+  expect(demand.remainingWeighted).toBe(0)
+  const out = renderForecast({
+    assumptions: ASSUMPTIONS,
+    demand,
+    velocity: velocities(DATED, TODAY),
+    projections: project({
+      assumptions: ASSUMPTIONS,
+      demand,
+      velocity: velocities(DATED, TODAY),
+      today: TODAY,
+    }),
+    today: TODAY,
+    undated: 0,
+  })
+  expect(out).toContain('nothing remaining: every confirmed requirement is already built')
+  expect(out).not.toContain('not projected')
+})