@iceinvein/agent-skills 0.2.0 → 0.4.0

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

package/skills/migrate/scripts/__tests__/gates-handoff.test.ts

@@ -0,0 +1,309 @@
+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 { runCheck } from '../check.ts'
+import type { HandoffFile } from '../handoff.ts'
+import type { Requirement, Violation } from '../types.ts'
+
+let root: string
+let source: string
+
+const PHASES = ['probe', 'enumerate', 'seam', 'extract', 'parity', 'queue', 'adjudicate', 'handoff']
+
+function req(id: string, over: Partial<Requirement> = {}): Requirement {
+  return {
+    id,
+    cap: 'user-management',
+    requirement: `requirement ${id}`,
+    actors: 'User',
+    objects: 'Thing',
+    rules: 'none',
+    origin: 'intended',
+    confidence: { kind: 'confirmed' },
+    citations: [{ kind: 'src', path: 'app.js', lines: [1, 1] }],
+    parity: { kind: 'rubric', level: 'high' },
+    batch: 'b-extract-1',
+    ...over,
+  }
+}
+
+const HANDOFF: HandoffFile = {
+  version: 1,
+  adapter: 'markdown',
+  items: [
+    {
+      key: 'user-management',
+      title: 'User management',
+      frs: ['UM-001', 'UM-002'],
+      dependsOn: [],
+      weight: 2,
+    },
+  ],
+  refs: { 'user-management': 'docs/migrate/capabilities/user-management.md' },
+  basis: { confirmed: 2, emitted: 2, order: ['user-management'] },
+}
+
+async function jsonl(name: string, rows: unknown[]): Promise<void> {
+  await writeFile(join(root, '.migrate', name), rows.map((r) => `${JSON.stringify(r)}\n`).join(''))
+}
+
+async function store(
+  over: {
+    requirements?: Requirement[]
+    handoff?: HandoffFile | null
+    queueStatus?: string
+    ruling?: boolean
+  } = {},
+): Promise<void> {
+  await mkdir(join(root, '.migrate', 'queue'), { recursive: true })
+  await writeFile(
+    join(root, '.migrate', 'config.toml'),
+    [
+      '[source]',
+      `path = "${source}"`,
+      'scope = "gate fixture"',
+      'stack = "unknown"',
+      'vcs = "none"',
+      'basis = "source-only"',
+      '',
+      '[target]',
+      'name = "target"',
+      'stack = "unknown"',
+      'parity_test_path = "tests/parity/{capability}/{fr_slug}.test.ts"',
+      '',
+      '[surfaces]',
+      'types = ["routes"]',
+      '',
+      '[closers]',
+      'set = []',
+      '',
+    ].join('\n'),
+  )
+  const requirements = over.requirements ?? [req('UM-001'), req('UM-002')]
+  await jsonl('elements.jsonl', [
+    {
+      id: 'route-get-users',
+      surface: 'routes',
+      element: 'GET /users',
+      found_by: ['code'],
+      disposition: { kind: 'mapped', fr: 'UM-001' },
+      refs: [],
+      lens: 'code',
+      batch: 'b-routes-1',
+      notes: '',
+    },
+  ])
+  await jsonl('requirements.jsonl', requirements)
+  await jsonl('capabilities.jsonl', [
+    { slug: 'user-management', title: 'User management', ns: 'UM', elements: ['route-get-users'] },
+  ])
+  await jsonl('census.jsonl', [
+    {
+      kind: 'lens',
+      surface: 'routes',
+      phase: 'enumerate',
+      directions: {
+        code: { count: 1, evidence: 'grep app.get' },
+        nav: { count: 1, evidence: 'walked the router' },
+      },
+      total: 1,
+      in_ledger: 0,
+      added: 1,
+      skipped: [],
+      queued: [],
+      batch: 'b-routes-1',
+    },
+  ])
+  const status = over.queueStatus ?? 'adjudicated'
+  await writeFile(
+    join(root, '.migrate', 'queue', 'q-open-question.md'),
+    [
+      '---',
+      'id: q-open-question',
+      'severity: moderate',
+      `status: ${status}`,
+      ...(status === 'adjudicated' && over.ruling !== false ? ['ruling: settled'] : []),
+      '---',
+      '',
+      '## Evidence',
+      '',
+      'e',
+      '',
+      '## Options',
+      '',
+      'o',
+      '',
+      '## Recommendation',
+      '',
+      'r',
+      '',
+    ].join('\n'),
+  )
+  const phases: Record<string, unknown> = {}
+  for (const p of PHASES) {
+    phases[p] = {
+      status: 'done',
+      batches:
+        p === 'enumerate'
+          ? [{ id: 'b-routes-1', count: 1 }]
+          : p === 'extract'
+            ? [{ id: 'b-extract-1', count: requirements.length }]
+            : [],
+      pending: [],
+    }
+  }
+  await writeFile(
+    join(root, '.migrate', 'phases.json'),
+    JSON.stringify({ version: 1, phases }, null, 2),
+  )
+  const handoff = over.handoff === undefined ? HANDOFF : over.handoff
+  if (handoff) {
+    await writeFile(join(root, '.migrate', 'handoff.json'), `${JSON.stringify(handoff, null, 2)}\n`)
+  }
+}
+
+// Marks every phase up to and including `last` as done and the rest pending.
+async function setPhasesThrough(last: string): Promise<void> {
+  const phases: Record<string, unknown> = {}
+  for (const p of PHASES) {
+    phases[p] = {
+      status: PHASES.indexOf(p) <= PHASES.indexOf(last) ? 'done' : 'pending',
+      batches:
+        p === 'enumerate'
+          ? [{ id: 'b-routes-1', count: 1 }]
+          : p === 'extract'
+            ? [{ id: 'b-extract-1', count: 2 }]
+            : [],
+      pending: [],
+    }
+  }
+  await writeFile(
+    join(root, '.migrate', 'phases.json'),
+    JSON.stringify({ version: 1, phases }, null, 2),
+  )
+}
+
+const of = (violations: Violation[], gate: string): string[] =>
+  violations.filter((v) => v.gate === gate).map((v) => v.message)
+
+beforeEach(async () => {
+  root = await mkdtemp(join(tmpdir(), 'migrate-gates-'))
+  source = join(root, 'legacy')
+  await Bun.write(join(source, 'app.js'), '// legacy\n')
+})
+
+afterEach(async () => {
+  await rm(root, { recursive: true, force: true })
+})
+
+test('a complete store passes both new gates', async () => {
+  await store()
+  const { violations } = await runCheck({ root })
+  expect(of(violations, 'adjudication')).toEqual([])
+  expect(of(violations, 'handoff')).toEqual([])
+})
+
+// --- gate 11, adjudication ---
+
+test('gate 11 names each open queue item with its severity', async () => {
+  await store({ queueStatus: 'open' })
+  const { violations } = await runCheck({ root })
+  const messages = of(violations, 'adjudication')
+  expect(messages).toHaveLength(1)
+  expect(messages[0]).toContain('q-open-question')
+  expect(messages[0]).toContain('moderate')
+})
+
+// --- gate 12, handoff ---
+
+test('gate 12 fails when handoff has never run', async () => {
+  await store({ handoff: null })
+  const { violations } = await runCheck({ root })
+  const messages = of(violations, 'handoff')
+  expect(messages).toHaveLength(1)
+  expect(messages[0]).toContain('handoff.json')
+})
+
+test('gate 12 names a requirement that reached no work item', async () => {
+  await store({ requirements: [req('UM-001'), req('UM-002'), req('UM-003')] })
+  const { violations } = await runCheck({ root })
+  const messages = of(violations, 'handoff')
+  expect(messages.some((m) => m.includes('UM-003'))).toBe(true)
+})
+
+test('gate 12 names a work item entry that resolves to no requirement', async () => {
+  await store({
+    handoff: {
+      ...HANDOFF,
+      items: [{ ...HANDOFF.items[0], frs: ['UM-001', 'UM-002', 'UM-999'] } as never],
+    },
+  })
+  const { violations } = await runCheck({ root })
+  expect(of(violations, 'handoff').some((m) => m.includes('UM-999'))).toBe(true)
+})
+
+test('gate 12 names a dependsOn that resolves to no work item', async () => {
+  await store({
+    handoff: {
+      ...HANDOFF,
+      items: [{ ...HANDOFF.items[0], dependsOn: ['nowhere'] } as never],
+    },
+  })
+  const { violations } = await runCheck({ root })
+  expect(of(violations, 'handoff').some((m) => m.includes('nowhere'))).toBe(true)
+})
+
+test('gate 12 names a basis whose counts disagree with the store', async () => {
+  await store({
+    handoff: { ...HANDOFF, basis: { confirmed: 99, emitted: 2, order: ['user-management'] } },
+  })
+  const { violations } = await runCheck({ root })
+  expect(of(violations, 'handoff').some((m) => m.includes('confirmed'))).toBe(true)
+})
+
+test('gate 12 counts only confirmed requirements in the basis denominator', async () => {
+  // One inferred requirement: still emitted, still in a work item, but not part
+  // of the confirmed denominator that coverage divides by.
+  await store({
+    requirements: [req('UM-001'), req('UM-002', { confidence: { kind: 'inferred' } })],
+    handoff: { ...HANDOFF, basis: { confirmed: 1, emitted: 2, order: ['user-management'] } },
+  })
+  const { violations } = await runCheck({ root })
+  expect(of(violations, 'handoff')).toEqual([])
+})
+
+// --- the phase-scope rule ---
+
+test('both gates are skipped below their phase and fire at it', async () => {
+  await store({ handoff: null, queueStatus: 'open' })
+  // The phases past `queue` must be pending for the skip to apply at all: a
+  // store whose own state file claims it reached handoff cannot hide an
+  // unemitted handoff by being checked at an earlier terminus.
+  await setPhasesThrough('queue')
+
+  // At --phase queue neither gate describes work the run claims to have
+  // reached, so neither fires. This is what keeps mid-run checking usable.
+  const mid = await runCheck({ root, phase: 'queue' })
+  expect(of(mid.violations, 'adjudication')).toEqual([])
+  expect(of(mid.violations, 'handoff')).toEqual([])
+
+  // At --phase adjudicate the adjudication gate applies but handoff does not.
+  const late = await runCheck({ root, phase: 'adjudicate' })
+  expect(of(late.violations, 'adjudication')).toHaveLength(1)
+  expect(of(late.violations, 'handoff')).toEqual([])
+
+  // Unbounded, both apply.
+  const full = await runCheck({ root })
+  expect(of(full.violations, 'adjudication')).toHaveLength(1)
+  expect(of(full.violations, 'handoff')).toHaveLength(1)
+})
+
+test('a store that stops at the queue still passes check --phase queue', async () => {
+  // The Milestone 2 posture: no adjudication, no handoff, and the phases after
+  // queue still pending. Adding two gates must not narrow this.
+  await store({ handoff: null, queueStatus: 'open' })
+  await setPhasesThrough('queue')
+  const { violations } = await runCheck({ root, phase: 'queue' })
+  expect(violations).toEqual([])
+})