@iceinvein/agent-skills 0.2.0 → 0.4.0

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

@@ -0,0 +1,186 @@
+import { flow } from './adapters/flow.ts'
+import { github } from './adapters/github.ts'
+import { markdown } from './adapters/markdown.ts'
+import { runCheck } from './check.ts'
+import { loadConfig } from './config.ts'
+import {
+  type Adapter,
+  blockedRequirements,
+  type HandoffFile,
+  type HandoffInput,
+  saveHandoff,
+} from './handoff.ts'
+import { LockError, withStoreLock } from './lock.ts'
+import { storePaths } from './paths.ts'
+import { recordBatch } from './phases.ts'
+import { loadQueue } from './queue.ts'
+import { readRows } from './store.ts'
+import type { Capability, Delta, Requirement, WorkItem } from './types.ts'
+
+const ADAPTERS: Record<string, Adapter> = { markdown, github, flow }
+
+export function adapterNames(): string[] {
+  return Object.keys(ADAPTERS).sort()
+}
+
+// Everything that must be true before any work item is emitted. Three sources,
+// reported together so an operator sees the whole list rather than fixing one
+// blocker at a time.
+//
+// The gate run is deliberately bounded at `adjudicate`. Citations and leaks are
+// both mandatory before handoff, so they are switched on here rather than left
+// to whatever the caller last used, but an unbounded run would also fire gate
+// 12, which requires the handoff.json this command has not written yet. That
+// would refuse every first handoff, permanently.
+export async function preflight(root: string, opts: { gitBin?: string } = {}): Promise<string[]> {
+  const blockers: string[] = []
+
+  const check = await runCheck({
+    root,
+    citations: true,
+    leaks: true,
+    phase: 'adjudicate',
+    ...(opts.gitBin ? { gitBin: opts.gitBin } : {}),
+  })
+  for (const v of check.violations) blockers.push(`[${v.gate}] ${v.message}`)
+
+  // The open items themselves are not listed again here. The adjudication
+  // gate above already names each one, and bounding the gate run at
+  // `adjudicate` is what guarantees it ran. Repeating them made the refusal
+  // report one fact twice and read as more blockers than there were.
+  const paths = storePaths(root)
+  const { items } = await loadQueue(paths.queueDir)
+  const open = items.filter((i) => i.status === 'open')
+
+  const requirements = await readRows<Requirement>(paths.requirements)
+  for (const { fr, queue } of blockedRequirements(requirements, new Set(open.map((i) => i.id)))) {
+    blockers.push(`${fr} blocked by ${queue}`)
+  }
+
+  return blockers
+}
+
+function renderPlan(items: WorkItem[]): string {
+  const lines = ['plan:']
+  for (const item of items) {
+    const deps = item.dependsOn.length > 0 ? ` after ${item.dependsOn.join(', ')}` : ''
+    lines.push(`  ${item.key} (${item.frs.length} requirement(s))${deps}`)
+  }
+  return lines.join('\n')
+}
+
+export async function runHandoff(opts: {
+  root: string
+  adapter?: string
+  dryRun?: boolean
+  gitBin?: string
+  ghBin?: string
+  forceUnlock?: boolean
+}): Promise<number> {
+  const cfg = await loadConfig(opts.root)
+  const name = opts.adapter ?? cfg.handoff.adapter
+  const adapter = ADAPTERS[name]
+  if (!adapter) {
+    process.stderr.write(
+      `handoff: unknown adapter ${name}; want one of ${adapterNames().join(', ')}\n`,
+    )
+    return 2
+  }
+
+  const blockers = await preflight(opts.root, {
+    ...(opts.gitBin ? { gitBin: opts.gitBin } : {}),
+  })
+  if (blockers.length > 0) {
+    // Named individually rather than counted, because each one is a separate
+    // thing somebody has to go and do.
+    for (const b of blockers) process.stderr.write(`handoff: ${b}\n`)
+    process.stderr.write(`handoff: refusing to emit with ${blockers.length} blocker(s)\n`)
+    return 1
+  }
+
+  const paths = storePaths(opts.root)
+  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 items: WorkItem[]
+  try {
+    items = await adapter.plan(input)
+  } catch (e) {
+    // An adapter refuses in plan() precisely so nothing is half-written; the
+    // flow adapter's namespace check is the one that reaches here in practice.
+    process.stderr.write(`handoff: ${(e as Error).message}\n`)
+    return 1
+  }
+
+  if (opts.dryRun) {
+    // Nothing is written, not even handoff.json. A dry run that wrote the
+    // basis would satisfy gate 12 with nothing actually emitted.
+    process.stdout.write(`${renderPlan(items)}\n`)
+    process.stdout.write(`handoff: dry run, ${items.length} work item(s), nothing written\n`)
+    return 0
+  }
+
+  let result: Awaited<ReturnType<Adapter['apply']>>
+  try {
+    result = await adapter.apply(items, input)
+  } catch (e) {
+    process.stderr.write(`handoff: ${(e as Error).message}\n`)
+    return 1
+  }
+
+  const emitted = items.reduce((n, i) => n + i.frs.length, 0)
+  const confirmed = input.requirements.filter((r) => r.confidence.kind === 'confirmed').length
+  const file: HandoffFile = {
+    version: 1,
+    adapter: name,
+    items: items.map(({ key, title, frs, dependsOn, weight }) => ({
+      key,
+      title,
+      frs,
+      dependsOn,
+      weight,
+    })),
+    refs: result.refs,
+    basis: { confirmed, emitted, order: items.map((i) => i.key) },
+  }
+
+  try {
+    await withStoreLock(
+      opts.root,
+      async () => {
+        await saveHandoff(opts.root, file, cfg.source.path)
+        await recordBatch(
+          opts.root,
+          'handoff',
+          { id: `b-handoff-${name}`, count: items.length },
+          cfg.source.path,
+        )
+      },
+      { cmd: 'handoff', ...(opts.forceUnlock ? { force: true } : {}) },
+    )
+  } catch (e) {
+    // Same class as every other writer: exit 3, which a caller can branch on
+    // to retry, rather than the generic guard's 2, which means "do not".
+    if (e instanceof LockError) {
+      process.stderr.write(`handoff: ${e.message}\n`)
+      return 3
+    }
+    throw e
+  }
+
+  process.stdout.write(
+    `handoff: adapter ${name}, ${items.length} work item(s), ${emitted} requirement(s)\n` +
+      `  created   ${result.created.length}\n` +
+      `  updated   ${result.updated.length}\n` +
+      `  unchanged ${result.unchanged.length}\n` +
+      `next: mark the phase done with \`migrate phase handoff --status done\`, then read progress back with \`migrate coverage\`\n`,
+  )
+  return 0
+}

package/skills/migrate/scripts/handoff.ts

@@ -0,0 +1,330 @@
+import { existsSync } from 'node:fs'
+import type { Config } from './config.ts'
+import { storePaths } from './paths.ts'
+import { readJsonFile, writeAtomically } from './store.ts'
+import type { ApplyResult, Capability, Delta, Requirement, Throughput, WorkItem } from './types.ts'
+import { isRecord } from './validate.ts'
+
+export type HandoffInput = {
+  requirements: Requirement[]
+  capabilities: Capability[]
+  deltas: Delta[]
+  config: Config
+  // What an adapter needs to reach the world. The two binary paths are the
+  // same injection seams the rest of the CLI uses, and without them the github
+  // adapter cannot be tested against a fake `gh` and the flow adapter cannot
+  // run the target's own checker.
+  root: string
+  gitBin: string
+  ghBin: string
+}
+
+export type Adapter = {
+  name: string
+  plan(input: HandoffInput): Promise<WorkItem[]>
+  apply(items: WorkItem[], input: HandoffInput): Promise<ApplyResult>
+  // Optional in the contract, but only one adapter is expected to decline: an
+  // adapter whose medium has no completion signal at all. `coverage` names an
+  // adapter that declines rather than reporting zero built, because those are
+  // very different claims.
+  throughput?(input: HandoffInput): Promise<Throughput>
+}
+
+// The body is prose, and it is regenerated on every plan(), so storing it
+// would make handoff.json churn on wording changes that emitted nothing new.
+// Everything gate 12 checks lives in the fields that remain.
+export type StoredItem = Omit<WorkItem, 'body'>
+
+export type HandoffFile = {
+  version: 1
+  adapter: string
+  items: StoredItem[]
+  refs: Record<string, string>
+  // The forecast basis. `confirmed` is coverage's denominator, `emitted` is
+  // every requirement that reached a work item, and the two differ by exactly
+  // the non-confirmed requirements that handoff still emits but parity does
+  // not hold the build to.
+  basis: { confirmed: number; emitted: number; order: string[] }
+}
+
+// Capability A depends on capability B when a requirement in A carries a
+// ledger citation to an element the partition assigns to B. Directional, which
+// is what plain citation overlap is not: overlap alone gives clusters, and a
+// build team needs an order.
+function dependencyEdges(caps: Capability[], reqs: Requirement[]): Map<string, Set<string>> {
+  const owner = new Map<string, string>()
+  for (const c of caps) {
+    for (const el of c.elements) owner.set(el, c.slug)
+  }
+  const deps = new Map<string, Set<string>>()
+  for (const c of caps) deps.set(c.slug, new Set())
+  for (const r of reqs) {
+    const from = deps.get(r.cap)
+    // A requirement naming a capability the partition does not have is a real
+    // defect, and the refs gate names it. Skipped rather than reported again
+    // here, because a dependency sort is not where that failure belongs.
+    if (!from) continue
+    for (const cite of r.citations) {
+      if (cite.kind !== 'ledger') continue
+      const to = owner.get(cite.id)
+      // A capability citing an element it owns itself is the normal case, not
+      // a self-dependency; an unowned element is one the refs gate names.
+      if (!to || to === r.cap) continue
+      from.add(to)
+    }
+  }
+  return deps
+}
+
+// Whether `from` can reach `to` following dependency edges within `scope`.
+// Used to tell a genuine cycle member (it reaches itself) from a capability
+// that is merely blocked by one.
+function reaches(
+  from: string,
+  to: string,
+  deps: Map<string, Set<string>>,
+  scope: Set<string>,
+): boolean {
+  const seen = new Set<string>()
+  const stack = [...(deps.get(from) ?? [])].filter((d) => scope.has(d))
+  while (stack.length > 0) {
+    const next = stack.pop() as string
+    if (next === to) return true
+    if (seen.has(next)) continue
+    seen.add(next)
+    for (const d of deps.get(next) ?? []) {
+      if (scope.has(d)) stack.push(d)
+    }
+  }
+  return false
+}
+
+// Kahn's algorithm over slug-sorted candidates. When a pass emits nothing,
+// every remaining capability is in a cycle: they are emitted in slug order and
+// returned in `cycle` so the caller can report it. Deterministic in both
+// branches, and independent of the order rows happen to sit in the store.
+export function dependencyOrder(
+  caps: Capability[],
+  reqs: Requirement[],
+): { ordered: Capability[]; cycle: string[] } {
+  const deps = dependencyEdges(caps, reqs)
+  const bySlug = new Map(caps.map((c) => [c.slug, c]))
+  const ordered: Capability[] = []
+  const remaining = new Set(caps.map((c) => c.slug))
+  const cycle: string[] = []
+
+  while (remaining.size > 0) {
+    let progress = false
+    for (const slug of [...remaining].sort()) {
+      const blocked = [...(deps.get(slug) ?? [])].some((dep) => remaining.has(dep))
+      if (blocked) continue
+      const capability = bySlug.get(slug)
+      if (!capability) {
+        remaining.delete(slug)
+        continue
+      }
+      ordered.push(capability)
+      remaining.delete(slug)
+      progress = true
+    }
+    if (progress) continue
+    // Nothing could be emitted, so at least one cycle blocks the rest. Only the
+    // members of a cycle are broken out, and only one pass' worth, after which
+    // the loop resumes: dumping everything remaining reported capabilities that
+    // were merely downstream of a cycle as cycle members, and threw away a
+    // perfectly satisfiable order for them. A capability that depends on a
+    // cycle should still be emitted after it, not alongside it.
+    const stuck = [...remaining].sort()
+    const inCycle = stuck.filter((slug) => reaches(slug, slug, deps, remaining))
+    const release = inCycle.length > 0 ? inCycle : stuck
+    for (const slug of release) {
+      const capability = bySlug.get(slug)
+      if (capability) {
+        ordered.push(capability)
+        cycle.push(slug)
+      }
+      remaining.delete(slug)
+    }
+  }
+  return { ordered, cycle }
+}
+
+function renderBody(capability: Capability, reqs: Requirement[]): string {
+  const lines = [`${capability.title}`, '']
+  if (reqs.length === 0) {
+    lines.push('No requirements were extracted for this capability.')
+  } else {
+    for (const r of reqs) lines.push(`- ${r.id}: ${r.requirement}`)
+  }
+  return lines.join('\n')
+}
+
+// One work item per capability, in dependency order. `weight` is the plain
+// requirement count; the territory multipliers that turn counts into effort
+// live in the owner-attested assumptions file, not in the emitted basis,
+// because a weighting the tool invents is the kind of number this method
+// refuses to assert.
+export function buildWorkItems(caps: Capability[], reqs: Requirement[]): WorkItem[] {
+  const { ordered } = dependencyOrder(caps, reqs)
+  const deps = dependencyEdges(caps, reqs)
+  const known = new Set(caps.map((c) => c.slug))
+  return ordered.map((capability) => {
+    const own = reqs.filter((r) => r.cap === capability.slug)
+    return {
+      key: capability.slug,
+      title: capability.title,
+      body: renderBody(capability, own),
+      frs: own.map((r) => r.id),
+      dependsOn: [...(deps.get(capability.slug) ?? [])].filter((d) => known.has(d)).sort(),
+      weight: own.length,
+    }
+  })
+}
+
+// A requirement is blocked when a decision it is waiting on has not been made
+// yet. Two independent paths reach that state, and both are relative to an
+// item that is still OPEN:
+//
+//   - a `queued` confidence, meaning the extract phase could not settle what
+//     the requirement is, and
+//   - a sub-high `rubric` parity, meaning the parity phase could not settle
+//     how it will be proven.
+//
+// Relative to open items specifically, which is the whole subtlety. A queued
+// confidence pointing at an item that has since been adjudicated is settled:
+// the owner ruled, and the requirement must stop blocking handoff even though
+// its confidence field still reads `queued`. Treating every queued confidence
+// as a blocker would refuse handoff forever unless each one were re-imported
+// with a new confidence first, which is work the ruling did not ask for.
+//
+// One requirement can be blocked from both directions at once and is reported
+// once per path, because they are two different decisions to go and make.
+export function blockedRequirements(
+  reqs: Requirement[],
+  openQueueIds: Set<string>,
+): { fr: string; queue: string }[] {
+  const blocked: { fr: string; queue: string }[] = []
+  for (const r of reqs) {
+    if (r.confidence.kind === 'queued' && openQueueIds.has(r.confidence.queue)) {
+      blocked.push({ fr: r.id, queue: r.confidence.queue })
+    }
+    if (r.parity?.kind === 'rubric' && r.parity.level !== 'high') {
+      if (openQueueIds.has(r.parity.queue)) blocked.push({ fr: r.id, queue: r.parity.queue })
+    }
+  }
+  return blocked
+}
+
+// handoff.json was the only store file in this codebase read through an
+// unchecked cast, and this milestone gave it three consumers (the gate,
+// coverage, forecast). `readRows` carries the same warning and every census row
+// goes through `validateCensus` for exactly this reason: nothing stops a hand
+// edit, a merge-conflict resolution, or a half-written file. Without this, `{}`
+// or a truncated write reached `handoff.items.map` and crashed `migrate check`
+// with an internal TypeError at exit 2, which claims the request was malformed
+// when in fact a well-formed request found a bad store file.
+export function validateHandoff(
+  raw: unknown,
+): { ok: true; value: HandoffFile } | { ok: false; errors: string[] } {
+  const errors: string[] = []
+  if (!isRecord(raw)) return { ok: false, errors: ['is not a JSON object'] }
+  const rec: Record<string, unknown> = raw
+  if (typeof rec.adapter !== 'string' || (rec.adapter as string).length === 0) {
+    errors.push('adapter must be a non-empty string')
+  }
+  if (!Array.isArray(rec.items)) errors.push('items must be an array')
+  else {
+    ;(rec.items as unknown[]).forEach((item: unknown, i: number) => {
+      if (!isRecord(item)) {
+        errors.push(`items[${i}] is not an object`)
+        return
+      }
+      if (typeof item.key !== 'string' || item.key.length === 0) {
+        errors.push(`items[${i}].key must be a non-empty string`)
+      }
+      if (typeof item.title !== 'string') errors.push(`items[${i}].title must be a string`)
+      if (!Array.isArray(item.frs) || (item.frs as unknown[]).some((f) => typeof f !== 'string')) {
+        errors.push(`items[${i}].frs must be an array of strings`)
+      }
+      if (
+        !Array.isArray(item.dependsOn) ||
+        (item.dependsOn as unknown[]).some((d) => typeof d !== 'string')
+      ) {
+        errors.push(`items[${i}].dependsOn must be an array of strings`)
+      }
+      if (typeof item.weight !== 'number' || !Number.isFinite(item.weight)) {
+        errors.push(`items[${i}].weight must be a number`)
+      }
+    })
+  }
+  if (!isRecord(rec.refs)) errors.push('refs must be an object')
+  else if (Object.values(rec.refs as Record<string, unknown>).some((v) => typeof v !== 'string')) {
+    errors.push('every refs value must be a string')
+  }
+  if (!isRecord(rec.basis)) errors.push('basis must be an object')
+  else {
+    for (const k of ['confirmed', 'emitted']) {
+      const v = (rec.basis as Record<string, unknown>)[k]
+      if (typeof v !== 'number' || !Number.isFinite(v)) {
+        errors.push(`basis.${k} must be a number`)
+      }
+    }
+    const order = (rec.basis as Record<string, unknown>).order
+    if (!Array.isArray(order) || order.some((o) => typeof o !== 'string')) {
+      errors.push('basis.order must be an array of strings')
+    }
+  }
+  if (errors.length > 0) return { ok: false, errors }
+  return { ok: true, value: rec as unknown as HandoffFile }
+}
+
+export type LoadedHandoff =
+  | { kind: 'absent' }
+  | { kind: 'ok'; value: HandoffFile }
+  | { kind: 'invalid'; errors: string[] }
+
+// Never throws. A file that cannot be read, parsed or validated comes back as
+// `invalid` with the reason, so a caller can report it as a violation instead
+// of dying on it.
+export async function loadHandoff(root: string): Promise<LoadedHandoff> {
+  const path = storePaths(root).handoff
+  if (!existsSync(path)) return { kind: 'absent' }
+  let raw: unknown
+  try {
+    raw = await readJsonFile(path)
+  } catch (e) {
+    return { kind: 'invalid', errors: [(e as Error).message] }
+  }
+  const result = validateHandoff(raw)
+  return result.ok
+    ? { kind: 'ok', value: result.value }
+    : { kind: 'invalid', errors: result.errors }
+}
+
+// Written with sorted `refs` keys and a fixed field order, so two apply() runs
+// over one store produce identical bytes. There are deliberately no timestamps
+// anywhere in this file: every date this tool reports is read at read time,
+// from the adapter's medium, which is also what keeps the file testable
+// against a golden.
+export async function saveHandoff(
+  root: string,
+  file: HandoffFile,
+  sourcePath: string,
+): Promise<void> {
+  const refs: Record<string, string> = {}
+  for (const key of Object.keys(file.refs).sort()) {
+    refs[key] = file.refs[key] ?? ''
+  }
+  const stable: HandoffFile = {
+    version: 1,
+    adapter: file.adapter,
+    items: file.items,
+    refs,
+    basis: file.basis,
+  }
+  await writeAtomically(
+    storePaths(root).handoff,
+    `${JSON.stringify(stable, null, 2)}\n`,
+    sourcePath,
+  )
+}

package/skills/migrate/scripts/paths.ts

@@ -17,6 +17,8 @@ export type StorePaths = {
   seamJson: string
   seamMd: string
   parityBasis: string
+  handoff: string
+  forecastAssumptions: string
   env: string
 }
 
@@ -35,6 +37,8 @@ export function storePaths(root: string): StorePaths {
     seamJson: join(dir, 'seam.json'),
     seamMd: join(dir, 'seam.md'),
     parityBasis: join(dir, 'parity-basis.md'),
+    handoff: join(dir, 'handoff.json'),
+    forecastAssumptions: join(dir, 'forecast-assumptions.md'),
     env: join(dir, '.env'),
   }
 }

package/skills/migrate/scripts/types.ts

@@ -135,3 +135,46 @@ export type QueueItem = {
 }
 
 export type Violation = { gate: string; message: string }
+
+// A unit of dependency-ordered work handed to a delivery medium. One work item
+// is one capability, uniformly across every adapter, because `dependsOn` is
+// only meaningful at that granularity: the store holds no per-requirement
+// edges of any kind. An adapter is free to expand one item into several
+// artifacts, and the github adapter deliberately does, into a milestone plus
+// an issue per requirement.
+export type WorkItem = {
+  // Stable across runs, so apply() is idempotent. The capability slug.
+  key: string
+  title: string
+  body: string
+  frs: string[]
+  dependsOn: string[]
+  weight: number
+}
+
+// What apply() did, keyed by work-item key. `refs` maps a key to whatever
+// external identity the adapter minted (an issue number, a file path), and it
+// is what makes a second apply() an update rather than a duplicate.
+export type ApplyResult = {
+  created: string[]
+  updated: string[]
+  unchanged: string[]
+  refs: Record<string, string>
+}
+
+// `doneAt` is nullable because not every medium dates a completion. The github
+// adapter reads closedAt and always has one; the flow adapter reads coverage
+// from the target's own parity command, which reports which requirements are
+// covered and not when. Coverage counts an undated completion as built and
+// says how many were undated; forecast excludes them from its rate.
+export type Completion = { fr: string; doneAt: string | null }
+
+// The completions plus a sentence naming where they came from. The basis
+// travels with the data rather than being reconstructed by the caller, so a
+// figure derived from it can always print its own provenance.
+export type Throughput = { completions: Completion[]; basis: string }
+
+// A measured or attested number that may not exist. A null value propagates
+// through every figure derived from it, and those figures print as omitted
+// rather than as a guess.
+export type Rate = { value: number | null; basis: string }

package/skills/migrate/scripts/validate.ts

@@ -130,6 +130,18 @@ export function validateRequirement(row: unknown, _cfg: Config): Validated<Requi
   const where = `requirement ${id || '<no id>'}`
 
   if (!id) errors.push('requirement: missing id')
+  // Elements have had an id grammar since Milestone 1; requirements were
+  // checked only for presence, so `migrate import reqs` accepted "BI 001" and
+  // "BI-002 (draft)" at exit 0. A requirement id travels into places that
+  // cannot represent whitespace: the markdown roadmap keys its checkbox lines
+  // on a single whitespace-delimited token, so an id with a space in it
+  // silently reverted the owner's ticked box on the next handoff, and the flow
+  // target rejects anything outside `<ns>-NNN` outright.
+  else if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(id)) {
+    errors.push(
+      `${where}: id must be letters, digits, dot, underscore or hyphen with no whitespace, since it is used as a key in emitted work items`,
+    )
+  }
   if (!str(r.cap) || r.cap.length === 0) errors.push(`${where}: missing cap`)
   if (!str(r.requirement) || r.requirement.length === 0)
     errors.push(`${where}: missing requirement text`)

package/skills/migrate/skill.json

@@ -1,7 +1,7 @@
 {
   "name": "migrate",
-  "version": "0.2.0",
-  "description": "Source-agnostic legacy migration mapping. Walks a legacy codebase through probe, enumerate, seam, extract, parity, and queue, building an auditable requirements ledger with mandatory citations and a `migrate check` gate in place of self-reported completeness. Use when the user asks to migrate, re-specify, replatform, or map a legacy system onto a new stack, or to resume, check, or report on a mapping run already under way.",
+  "version": "0.3.0",
+  "description": "Source-agnostic legacy migration mapping. Walks a legacy codebase through probe, enumerate, seam, extract, parity, queue, adjudicate and handoff, building an auditable requirements ledger with mandatory citations and a `migrate check` gate in place of self-reported completeness. Use when the user asks to migrate, re-specify, replatform, or map a legacy system onto a new stack, to hand mapped requirements to a delivery team, or to resume, check, report, or forecast a mapping run already under way.",
   "author": "iceinvein",
   "type": "prompt",
   "tools": ["claude"],

package/skills/migrate/templates/forecast-assumptions.md

@@ -0,0 +1,59 @@
+---
+attestedBy: <owner-name>
+attestedDate: <YYYY-MM-DD>
+---
+
+# Forecast assumptions
+
+Owner-attested judgment inputs for `migrate forecast`. Everything measured
+lives in the store and in the adapter's throughput; everything here is a
+decision. Re-attest (edit and commit) when a judgment changes.
+
+Copy this file to `.migrate/forecast-assumptions.md` and fill it in. `migrate
+forecast` refuses without it, because a projection nobody signed is exactly the
+asserted number this method exists to refuse.
+
+## Territories
+
+One row per capability that has confirmed requirements. A territory is a name
+for how hard the ground is, and it is the unit of attested difficulty: a
+campaign names a handful of them rather than a weight per requirement. Every
+territory named here needs a multiplier row below.
+
+| capability | territory |
+| --- | --- |
+
+## Multipliers
+
+How much one requirement in that territory costs relative to a baseline of 1.0.
+Positive numbers only.
+
+| territory | multiplier |
+| --- | --- |
+| established | 1.0 |
+
+## Scenarios
+
+`rate` is one of three things, and the projection labels which:
+
+- `as-is`, the measured velocity over calendar days since the first recorded
+  completion, quiet days included. The pessimistic measured base.
+- `active`, the measured velocity over the days something actually completed.
+  The optimistic measured base.
+- a positive number, requirements per day per stream, attested by the owner.
+  Nothing measures this, the projection labels it a target, and it carries no
+  uncertainty band.
+
+`streams` is how many can run in parallel. `tax` is the coordination overhead,
+in `[0, 1)`, taken off the combined rate. `note` says where the figure came
+from; on a target row it is the only record of that.
+
+| label | rate | streams | tax | note |
+| --- | --- | --- | --- | --- |
+| as-is | as-is | 1 | 0 | placeholder: re-attest before relying on projections |
+
+## Caveats
+
+Printed verbatim under every projection.
+
+- Skeleton values: attest real territories, multipliers and scenarios before use.