@iceinvein/agent-skills 0.2.0 → 0.4.0

package/skills/migrate/scripts/coverage.ts

@@ -0,0 +1,151 @@
+import { isCalendarDate } from './dates.ts'
+import type { HandoffFile } from './handoff.ts'
+import type { Requirement, Throughput } from './types.ts'
+
+export type CapCoverage = {
+  slug: string
+  title: string
+  confirmedTotal: number
+  covered: number
+  coveredIds: string[]
+  uncoveredIds: string[]
+}
+
+export type CoverageReport = {
+  caps: CapCoverage[]
+  built: number
+  confirmed: number
+  // Completions that were counted as built but carry no date. They contribute
+  // to coverage and contribute nothing to forecast's measured rate, so the
+  // count is printed rather than folded away.
+  undated: number
+  // Completions naming a requirement the store does not have. Not a
+  // degradation: it means the emitted work and the store have diverged, so the
+  // caller treats it as a failure.
+  unknown: string[]
+  nonConfirmed: { slug: string; count: number }[]
+  // Capabilities the store has requirements in that the emitted order does not
+  // name: the handoff predates them, so the emitted work is out of date.
+  stale: string[]
+  basis: string
+}
+
+// The denominator is confirmed requirements only.
+//
+// This is the method's position rather than a choice made here: flow's own
+// computeParity divides by `conf === "Confirmed"`, and reports the excluded
+// count separately. Parity is a promise about behaviour the run confirmed, and
+// holding a build team to an inferred requirement would assert a confidence
+// the extract phase explicitly declined to claim. Handoff still emits every
+// requirement, so nothing is hidden; it is only the denominator that narrows,
+// and the exclusions are printed underneath.
+export function computeCoverage(input: {
+  requirements: Requirement[]
+  handoff: HandoffFile
+  throughput: Throughput
+}): CoverageReport {
+  const { requirements, handoff, throughput } = input
+  const known = new Set(requirements.map((r) => r.id))
+  const byId = new Map(requirements.map((r) => [r.id, r]))
+
+  const unknown: string[] = []
+  const builtIds = new Set<string>()
+  let undated = 0
+  for (const c of throughput.completions) {
+    if (!known.has(c.fr)) {
+      unknown.push(c.fr)
+      continue
+    }
+    builtIds.add(c.fr)
+    // A date that is not a real calendar day cannot date anything, so it is
+    // reported the same way a missing one is rather than counted as dated.
+    if (c.doneAt === null || !isCalendarDate(c.doneAt)) undated++
+  }
+
+  const titleOf = new Map(handoff.items.map((i) => [i.key, i.title]))
+  const caps: CapCoverage[] = []
+  const nonConfirmed: { slug: string; count: number }[] = []
+
+  // Every capability the STORE has requirements in, not only those the emitted
+  // order happens to name. Walking `basis.order` alone let a stale handoff.json
+  // narrow both numerator and denominator silently: a store with three
+  // confirmed requirements in a capability absent from `order` reported
+  // "built 7/7 confirmed requirements (100%)" while three were unbuilt and the
+  // capability appeared nowhere in the output. The order still decides the
+  // display sequence; anything it omits is appended and named as stale.
+  const inStore = [...new Set(requirements.map((r) => r.cap))]
+  const stale = inStore.filter((slug) => !handoff.basis.order.includes(slug)).sort()
+  for (const slug of [...handoff.basis.order, ...stale]) {
+    const own = requirements.filter((r) => r.cap === slug)
+    const confirmed = own.filter((r) => r.confidence.kind === 'confirmed')
+    const coveredIds = confirmed.filter((r) => builtIds.has(r.id)).map((r) => r.id)
+    const uncoveredIds = confirmed.filter((r) => !builtIds.has(r.id)).map((r) => r.id)
+    caps.push({
+      slug,
+      title: titleOf.get(slug) ?? slug,
+      confirmedTotal: confirmed.length,
+      covered: coveredIds.length,
+      coveredIds,
+      uncoveredIds,
+    })
+    const excluded = own.length - confirmed.length
+    if (excluded > 0) nonConfirmed.push({ slug, count: excluded })
+  }
+
+  // Counted off the per-capability rows rather than off builtIds, so a
+  // completion for a non-confirmed requirement cannot inflate the figure that
+  // sits above a breakdown which excludes it.
+  const built = caps.reduce((n, c) => n + c.covered, 0)
+  const confirmed = caps.reduce((n, c) => n + c.confirmedTotal, 0)
+
+  // A requirement whose capability never reached a work item is invisible to
+  // the loop above, which walks the emitted order. Gate 12 names it, so this
+  // does not report it again; it only avoids counting it.
+  void byId
+
+  return { caps, built, confirmed, undated, unknown, stale, nonConfirmed, basis: throughput.basis }
+}
+
+function pad(text: string, width: number): string {
+  return text.length >= width ? text : text + ' '.repeat(width - text.length)
+}
+
+export function renderCoverage(r: CoverageReport): string {
+  // Never round to a number the fraction beside it contradicts. Math.round
+  // printed 199/200 as 100% and 1/250 as 0%, and the percentage is the figure
+  // that gets quoted onward while the fraction stays behind.
+  const pct =
+    r.confirmed === 0
+      ? 0
+      : r.built === r.confirmed
+        ? 100
+        : r.built === 0
+          ? 0
+          : Math.min(99, Math.max(1, Math.round((r.built / r.confirmed) * 100)))
+  const lines = [
+    `built ${r.built}/${r.confirmed} confirmed requirements (${pct}%)`,
+    `evidence: ${r.basis}`,
+  ]
+  if (r.undated > 0) {
+    lines.push(
+      `undated: ${r.undated} completion(s) carry no date; they count as built and contribute nothing to forecast's measured rate`,
+    )
+  }
+  if (r.nonConfirmed.length > 0) {
+    const total = r.nonConfirmed.reduce((n, e) => n + e.count, 0)
+    const detail = r.nonConfirmed.map((e) => `${e.slug} ${e.count}`).join(', ')
+    lines.push(`excluded: ${total} non-confirmed (${detail})`)
+  }
+  if (r.stale.length > 0) {
+    lines.push(
+      `stale: ${r.stale.length} capability(ies) not in the emitted work (${r.stale.join(', ')}); re-run migrate handoff`,
+    )
+  }
+  lines.push('')
+  const width = Math.max(4, ...r.caps.map((c) => c.slug.length))
+  for (const c of r.caps) {
+    const done = c.confirmedTotal > 0 && c.covered === c.confirmedTotal ? '  done' : ''
+    lines.push(`${pad(c.slug, width)}  ${c.covered}/${c.confirmedTotal}${done}`)
+  }
+  return lines.join('\n')
+}

package/skills/migrate/scripts/dates.ts

@@ -0,0 +1,17 @@
+// A completion date arrives from an adapter's medium: a hand-written date on a
+// roadmap line, a `closedAt` from an API. Nothing upstream guarantees it names
+// a real day, and `Date.parse` answers NaN rather than throwing, so an
+// unvalidated date propagates silently into arithmetic and comes back out as
+// a rate of NaN printed where a number belongs.
+//
+// Checked against the round-trip rather than by a regex on the parts, because
+// the shapes that matter are the ones a regex accepts and a calendar does not:
+// 2026-08-32 is well-formed and does not exist, and 2026-02-31 quietly rolls
+// forward to 3 March, which would stretch an era by a month with nothing
+// visibly wrong.
+export function isCalendarDate(value: string): boolean {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) return false
+  const parsed = new Date(`${value}T00:00:00Z`)
+  if (Number.isNaN(parsed.getTime())) return false
+  return parsed.toISOString().slice(0, 10) === value
+}

package/skills/migrate/scripts/forecast-cmd.ts

@@ -0,0 +1,124 @@
+import { existsSync } from 'node:fs'
+import { flow } from './adapters/flow.ts'
+import { github } from './adapters/github.ts'
+import { markdown } from './adapters/markdown.ts'
+import { parseAssumptions, validateAssumptions } from './assumptions.ts'
+import { loadConfig } from './config.ts'
+import { computeCoverage } from './coverage.ts'
+import { demandOf, project, renderForecast, velocities } from './forecast.ts'
+import { type Adapter, type HandoffInput, loadHandoff } from './handoff.ts'
+import { storePaths } from './paths.ts'
+import { readRows, readTextFile } from './store.ts'
+import type { Capability, Delta, Requirement } from './types.ts'
+
+const ADAPTERS: Record<string, Adapter> = { markdown, github, flow }
+
+function today(): string {
+  return new Date().toISOString().slice(0, 10)
+}
+
+export async function runForecast(opts: {
+  root: string
+  adapter?: string
+  gitBin?: string
+  ghBin?: string
+  now?: () => string
+}): Promise<number> {
+  const cfg = await loadConfig(opts.root)
+  const paths = storePaths(opts.root)
+
+  const loaded = await loadHandoff(opts.root)
+  if (loaded.kind === 'invalid') {
+    for (const e of loaded.errors) process.stderr.write(`forecast: handoff.json ${e}\n`)
+    return 1
+  }
+  const handoff = loaded.kind === 'ok' ? loaded.value : null
+  if (!handoff) {
+    process.stderr.write(
+      'forecast: no handoff.json in the store; run `migrate handoff` before projecting anything\n',
+    )
+    return 1
+  }
+
+  if (!existsSync(paths.forecastAssumptions)) {
+    // Required, not optional. A projection nobody signed is exactly the
+    // asserted number this method exists to refuse, so the file's absence is a
+    // refusal rather than a set of defaults.
+    process.stderr.write(
+      `forecast: no ${paths.forecastAssumptions}; copy templates/forecast-assumptions.md there and attest it\n`,
+    )
+    return 1
+  }
+
+  let assumptions: ReturnType<typeof parseAssumptions>
+  try {
+    assumptions = parseAssumptions(
+      await readTextFile(paths.forecastAssumptions),
+      paths.forecastAssumptions,
+    )
+  } catch (e) {
+    process.stderr.write(`forecast: ${(e as Error).message}\n`)
+    return 1
+  }
+
+  const name = opts.adapter ?? cfg.handoff.adapter
+  const adapter = ADAPTERS[name]
+  if (!adapter) {
+    process.stderr.write(
+      `forecast: unknown adapter ${name}; want one of ${Object.keys(ADAPTERS).sort().join(', ')}\n`,
+    )
+    return 2
+  }
+  if (!adapter.throughput) {
+    process.stderr.write(
+      `forecast: adapter ${name} reports no throughput, so there is nothing measured to project from\n`,
+    )
+    return 1
+  }
+
+  const input: HandoffInput = {
+    requirements: await readRows<Requirement>(paths.requirements),
+    capabilities: await readRows<Capability>(paths.capabilities),
+    deltas: await readRows<Delta>(paths.deltas),
+    config: cfg,
+    root: opts.root,
+    gitBin: opts.gitBin ?? 'git',
+    ghBin: opts.ghBin ?? 'gh',
+  }
+
+  let throughput: Awaited<ReturnType<NonNullable<Adapter['throughput']>>>
+  try {
+    throughput = await adapter.throughput(input)
+  } catch (e) {
+    process.stderr.write(`forecast: ${(e as Error).message}\n`)
+    return 1
+  }
+
+  const coverage = computeCoverage({ requirements: input.requirements, handoff, throughput })
+
+  // Validated against measured coverage rather than against itself: the file
+  // has to account for the capabilities the store actually has confirmed
+  // requirements in, not for whatever it happened to list.
+  const errors = validateAssumptions(assumptions, coverage.caps)
+  if (errors.length > 0) {
+    for (const e of errors) process.stderr.write(`forecast: ${e}\n`)
+    return 1
+  }
+
+  const now = (opts.now ?? today)()
+  const demand = demandOf(assumptions, coverage.caps)
+  const velocity = velocities(throughput.completions, now)
+  const projections = project({ assumptions, demand, velocity, today: now })
+
+  process.stdout.write(
+    `${renderForecast({
+      assumptions,
+      demand,
+      velocity,
+      projections,
+      today: now,
+      undated: coverage.undated,
+    })}\n`,
+  )
+  return 0
+}

package/skills/migrate/scripts/forecast.ts

@@ -0,0 +1,264 @@
+import type { Assumptions } from './assumptions.ts'
+import type { CapCoverage } from './coverage.ts'
+import { isCalendarDate } from './dates.ts'
+import type { Completion, Rate } from './types.ts'
+
+const DAY_MS = 86_400_000
+
+export function addDays(date: string, days: number): string {
+  return new Date(Date.parse(`${date}T00:00:00Z`) + days * DAY_MS).toISOString().slice(0, 10)
+}
+
+export type TerritoryDemand = {
+  territory: string
+  capabilities: string[]
+  remainingRaw: number
+  multiplier: number
+  frEquivalents: number
+}
+
+export type Demand = {
+  territories: TerritoryDemand[]
+  remainingRaw: number
+  remainingWeighted: number
+}
+
+// Demand is reported both ways on purpose. `raw` is a count anyone can check
+// against the store; `weighted` is that count through the owner's attested
+// multipliers. Printing only the weighted figure would bury a judgment inside
+// something that looks like a measurement.
+//
+// Territories come out in Multipliers-table order, which is the order the
+// milestone sequence walks: the owner decides what gets finished first by
+// deciding how to write that table.
+export function demandOf(assumptions: Assumptions, coverage: CapCoverage[]): Demand {
+  const territories: TerritoryDemand[] = Object.entries(assumptions.multipliers).map(
+    ([territory, multiplier]) => {
+      const caps = coverage.filter((c) => assumptions.territories[c.slug] === territory)
+      const remainingRaw = caps.reduce((n, c) => n + (c.confirmedTotal - c.covered), 0)
+      return {
+        territory,
+        capabilities: caps.map((c) => c.slug),
+        remainingRaw,
+        multiplier,
+        frEquivalents: remainingRaw * multiplier,
+      }
+    },
+  )
+  return {
+    territories,
+    remainingRaw: territories.reduce((n, t) => n + t.remainingRaw, 0),
+    remainingWeighted: territories.reduce((n, t) => n + t.frEquivalents, 0),
+  }
+}
+
+const UNMEASURED = 'not enough dated completions to measure a rate; one point is not a rate'
+
+// Two measured velocities from the same completions, and the difference
+// between them is the honest uncertainty band. `as-is` divides by every
+// calendar day since the first completion, quiet days included, and is the
+// pessimistic base. `active` divides only by the days something completed, and
+// is the optimistic one.
+//
+// The era runs from the earliest completion rather than from an attested
+// baseline, so both stay measured and the assumptions file holds judgment
+// only. Undated completions contribute to neither: they are counted as built
+// by coverage and say nothing about pace.
+export function velocities(completions: Completion[], today: string): { asIs: Rate; active: Rate } {
+  // A date that is not a real calendar day is dropped rather than parsed. Left
+  // in, `Date.parse` returns NaN, `Math.max(1, NaN)` is NaN, and because
+  // `NaN !== null` the whole null-propagation contract disengages and a rate
+  // of NaN gets printed where a number belongs.
+  const dates = completions
+    .map((c) => c.doneAt)
+    .filter((d): d is string => d !== null && isCalendarDate(d))
+    .sort()
+  if (dates.length < 2) {
+    return { asIs: { value: null, basis: UNMEASURED }, active: { value: null, basis: UNMEASURED } }
+  }
+  const first = dates[0] as string
+  const last = dates[dates.length - 1] as string
+  // The era is counted INCLUSIVELY, and runs to the later of today and the
+  // last completion. Both halves matter, and getting either wrong inverts the
+  // uncertainty band rather than merely shifting it.
+  //
+  // Inclusive because `activeDays` counts distinct dates, which is inclusive by
+  // construction: ten completions on ten consecutive days ending today gave an
+  // exclusive era of nine, so `asIs` (10/9) came out FASTER than `active`
+  // (10/10). asIs is the pessimistic floor and active the optimistic ceiling,
+  // so that made the band print its optimistic bound later than its
+  // pessimistic one. Counted inclusively, activeDays <= eraDays always holds,
+  // because every active day falls inside the era.
+  //
+  // Running to `max(today, last)` because a completion dated ahead of today is
+  // otherwise clamped to a one-day era, which turns a typo or a timezone edge
+  // into an enormous measured velocity. Extending the era is the honest
+  // reading: the run demonstrably spans that date.
+  const end = last > today ? last : today
+  const eraDays = (Date.parse(`${end}T00:00:00Z`) - Date.parse(`${first}T00:00:00Z`)) / DAY_MS + 1
+  const activeDays = new Set(dates).size
+  return {
+    asIs: {
+      value: dates.length / eraDays,
+      basis: `${dates.length} dated completion(s) over ${eraDays} calendar day(s) since ${first}, quiet days included`,
+    },
+    active: {
+      value: dates.length / activeDays,
+      basis: `${dates.length} dated completion(s) over ${activeDays} day(s) something completed`,
+    },
+  }
+}
+
+export type Projection = {
+  label: string
+  // The epistemic family. `as-is` and `active` extrapolate something measured;
+  // `target` scales a rate the owner attested and nothing backs. Views keep
+  // the two apart so an aspiration never reads as a fact.
+  basis: 'as-is' | 'active' | 'target'
+  streams: number
+  tax: number
+  note: string
+  ratePerStream: number | null
+  perDay: number | null
+  daysRaw: number | null
+  finishRaw: string | null
+  daysWeighted: number | null
+  finishWeighted: string | null
+  band: { optimistic: string | null; pessimistic: string | null } | null
+  milestones: { territory: string; finish: string | null }[]
+}
+
+// Null propagates. Every figure whose input is unmeasured comes out null and
+// renders as omitted, rather than as a zero or a guess. That is what makes the
+// no-dates case degrade cleanly: the flow adapter supplies coverage without
+// dates, so measured rows project nothing and say why, while target rows still
+// project because they never needed a measurement.
+const daysFor = (remaining: number, rate: number | null): number | null =>
+  rate !== null && rate > 0 && remaining > 0 ? Math.ceil(remaining / rate) : null
+
+export function project(input: {
+  assumptions: Assumptions
+  demand: Demand
+  velocity: { asIs: Rate; active: Rate }
+  today: string
+}): Projection[] {
+  const { assumptions, demand, velocity, today } = input
+  const finishFor = (remaining: number, rate: number | null): string | null => {
+    const d = daysFor(remaining, rate)
+    return d === null ? null : addDays(today, d)
+  }
+
+  return assumptions.scenarios.map((s) => {
+    const scaled = (base: number | null): number | null =>
+      base === null ? null : base * s.streams * (1 - s.tax)
+    const basis =
+      typeof s.rate === 'number'
+        ? ('target' as const)
+        : s.rate === 'as-is'
+          ? ('as-is' as const)
+          : ('active' as const)
+    const ratePerStream =
+      typeof s.rate === 'number'
+        ? s.rate
+        : s.rate === 'as-is'
+          ? velocity.asIs.value
+          : velocity.active.value
+    const perDay = scaled(ratePerStream)
+
+    const milestones: { territory: string; finish: string | null }[] = []
+    let cumulative = 0
+    for (const t of demand.territories) {
+      if (t.remainingRaw <= 0) continue
+      cumulative += t.frEquivalents
+      milestones.push({ territory: t.territory, finish: finishFor(cumulative, perDay) })
+    }
+
+    return {
+      label: s.label,
+      basis,
+      streams: s.streams,
+      tax: s.tax,
+      note: s.note,
+      ratePerStream,
+      perDay,
+      daysRaw: daysFor(demand.remainingRaw, perDay),
+      finishRaw: finishFor(demand.remainingRaw, perDay),
+      daysWeighted: daysFor(demand.remainingWeighted, perDay),
+      finishWeighted: finishFor(demand.remainingWeighted, perDay),
+      // A target row has no measured spread behind it, so offering a band
+      // would dress an attested number as an observed range.
+      band:
+        typeof s.rate === 'number'
+          ? null
+          : {
+              optimistic: finishFor(demand.remainingWeighted, scaled(velocity.active.value)),
+              pessimistic: finishFor(demand.remainingWeighted, scaled(velocity.asIs.value)),
+            },
+      milestones,
+    }
+  })
+}
+
+export function renderForecast(input: {
+  assumptions: Assumptions
+  demand: Demand
+  velocity: { asIs: Rate; active: Rate }
+  projections: Projection[]
+  today: string
+  undated: number
+}): string {
+  const { assumptions, demand, velocity, projections, today, undated } = input
+  const lines = [
+    `forecast from ${today}, attested by ${assumptions.attestedBy} on ${assumptions.attestedDate}`,
+    `remaining ${demand.remainingRaw} requirement(s), ${demand.remainingWeighted} weighted by attested multipliers`,
+    '',
+    'measured velocity',
+    `  as-is   ${velocity.asIs.value === null ? 'unmeasured' : `${velocity.asIs.value.toFixed(2)}/day`}  (${velocity.asIs.basis})`,
+    `  active  ${velocity.active.value === null ? 'unmeasured' : `${velocity.active.value.toFixed(2)}/day`}  (${velocity.active.basis})`,
+  ]
+  if (undated > 0) {
+    lines.push(`  ${undated} completion(s) carry no date and contribute to neither rate`)
+  }
+  lines.push('')
+
+  for (const p of projections) {
+    const kind =
+      p.basis === 'target'
+        ? 'target (owner-attested, nothing measures this)'
+        : `measured (${p.basis})`
+    lines.push(`${p.label}: ${kind}`)
+    lines.push(`  ${p.streams} stream(s), tax ${p.tax}, ${p.note}`)
+    if (demand.remainingWeighted === 0) {
+      // Distinguished from the unmeasured case below on purpose. Both leave
+      // every date null, but "there is nothing left to build" and "there is no
+      // rate to build at" are opposite pieces of news, and printing the same
+      // "omitted" for each would hide which one the reader is looking at.
+      lines.push('  nothing remaining: every confirmed requirement is already built')
+    } else if (p.perDay === null) {
+      lines.push('  not projected: no measured rate to extrapolate from')
+    } else {
+      lines.push(`  ${p.perDay.toFixed(2)} requirement(s)/day`)
+      lines.push(
+        `  raw       ${p.finishRaw === null ? 'omitted' : `${p.finishRaw} (${p.daysRaw} day(s))`}`,
+      )
+      lines.push(
+        `  weighted  ${p.finishWeighted === null ? 'omitted' : `${p.finishWeighted} (${p.daysWeighted} day(s))`}`,
+      )
+      if (p.band) {
+        lines.push(
+          `  band      ${p.band.optimistic ?? 'omitted'} to ${p.band.pessimistic ?? 'omitted'}`,
+        )
+      }
+      for (const m of p.milestones) {
+        lines.push(`  ${m.territory} done by ${m.finish ?? 'omitted'}`)
+      }
+    }
+    lines.push('')
+  }
+
+  if (assumptions.caveats.length > 0) {
+    lines.push('caveats')
+    for (const c of assumptions.caveats) lines.push(`  - ${c}`)
+  }
+  return lines.join('\n')
+}

package/skills/migrate/scripts/gates/adjudication.ts

@@ -0,0 +1,30 @@
+import type { Violation } from '../types.ts'
+import type { Gate } from './context.ts'
+
+// Gate 11: adjudication. Every queue item carries an owner's ruling.
+//
+// The queue gate already refuses an `adjudicated` item with no ruling, and
+// this gate checks the same thing independently rather than leaning on it. A
+// gate whose soundness depends on another gate having run first is not
+// independently a gate, and the two are asking different questions: the queue
+// gate asks whether the file is well formed, this one asks whether the
+// decision was made.
+export const gate: Gate = (ctx): Violation[] => {
+  const violations: Violation[] = []
+  for (const item of ctx.queueItems) {
+    if (item.status !== 'adjudicated') {
+      violations.push({
+        gate: 'adjudication',
+        message: `${item.id} [${item.severity}] is still ${item.status}; every queue item needs a ruling before handoff`,
+      })
+      continue
+    }
+    if (!item.ruling || item.ruling.trim().length === 0) {
+      violations.push({
+        gate: 'adjudication',
+        message: `${item.id} [${item.severity}] is adjudicated with no ruling recorded`,
+      })
+    }
+  }
+  return violations
+}