@iceinvein/agent-skills 0.1.39 → 0.2.0

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

@@ -0,0 +1,52 @@
+import { runCheck } from './check.ts'
+import { loadConfig } from './config.ts'
+import { storePaths } from './paths.ts'
+import { loadPhases, PHASES } from './phases.ts'
+import { loadQueue } from './queue.ts'
+import { readRows } from './store.ts'
+import type { Element, Requirement } from './types.ts'
+
+export async function runStatus(opts: { root: string }): Promise<number> {
+  const cfg = await loadConfig(opts.root)
+  const p = storePaths(opts.root)
+  const phases = await loadPhases(opts.root)
+  const elements = await readRows<Element>(p.elements)
+  const requirements = await readRows<Requirement>(p.requirements)
+  const { items, errors } = await loadQueue(p.queueDir)
+  // A malformed queue item on disk must not be invisible here: `check`
+  // flags it and exits 1, `queue list` flags it and exits 1, and status
+  // reporting the same store at exit 0 with no mention of it would read as
+  // "nothing else to look at" when there is.
+  for (const e of errors) process.stderr.write(`status: ${e}\n`)
+  const open = items.filter((i) => i.status === 'open')
+
+  process.stdout.write(`source: ${cfg.source.path} (${cfg.source.stack}, ${cfg.source.basis})\n`)
+  process.stdout.write(`scope:  ${cfg.source.scope}\n\n`)
+
+  for (const phase of PHASES) {
+    const state = phases[phase]
+    const batches = state.batches.length > 0 ? ` (${state.batches.length} batch(es))` : ''
+    process.stdout.write(`  ${phase.padEnd(11)} ${state.status}${batches}\n`)
+  }
+
+  const { summary } = await runCheck({ root: opts.root })
+  process.stdout.write(`\n${summary}\n`)
+  process.stdout.write(`${requirements.length} requirement(s), ${elements.length} element(s)\n`)
+  process.stdout.write(`${open.length} open queue item(s) of ${items.length}\n`)
+
+  const active = PHASES.find((ph) => phases[ph].status !== 'done')
+  if (active) {
+    const last = phases[active].batches.at(-1)
+    const from = last ? `last batch ${last.id} (${last.count} row(s))` : 'no batches yet'
+    process.stdout.write(`\nresume: ${active}, ${from}\n`)
+    if (phases[active].pending.length > 0) {
+      process.stdout.write(`pending: ${phases[active].pending.join(', ')}\n`)
+    }
+  } else {
+    process.stdout.write('\nresume: all phases done\n')
+  }
+  // Same class and exit code as `queue list` for the identical condition: a
+  // content failure on an otherwise well-formed request, not a usage error
+  // (2) and not success (0) while part of the queue could not be read.
+  return errors.length > 0 ? 1 : 0
+}

package/skills/migrate/scripts/store.ts

@@ -0,0 +1,159 @@
+import { randomBytes } from 'node:crypto'
+import { existsSync } from 'node:fs'
+import { readFile, rename, unlink, writeFile } from 'node:fs/promises'
+import { assertNotUnderSource } from './paths.ts'
+
+// Reads one JSON file and parses it, or throws a clean diagnostic naming the
+// path and the reason (missing file, or content that isn't valid JSON)
+// instead of letting readFile/JSON.parse's raw error escape. Shared by every
+// command that takes a single JSON file as an argument, so each one only has
+// to decide what its own exit code means, not how to report a bad file.
+export async function readJsonFile(path: string): Promise<unknown> {
+  let text: string
+  try {
+    text = await readFile(path, 'utf8')
+  } catch {
+    throw new Error(`${path}: not found`)
+  }
+  try {
+    return JSON.parse(text)
+  } catch {
+    throw new Error(`${path}: not valid JSON`)
+  }
+}
+
+// Reads one markdown file as text, or throws a clean diagnostic naming the
+// path first (missing file, a directory where a file was expected, or an
+// unreadable file) instead of letting readFile's raw error escape. Queue
+// items are markdown, not JSON, so this is readJsonFile's sibling: same
+// message convention, no JSON parsing.
+export async function readTextFile(path: string): Promise<string> {
+  try {
+    return await readFile(path, 'utf8')
+  } catch (e) {
+    const code = (e as { code?: string }).code
+    if (code === 'EISDIR') throw new Error(`${path}: is a directory, not a file`)
+    if (code === 'EACCES') throw new Error(`${path}: permission denied`)
+    throw new Error(`${path}: not found`)
+  }
+}
+
+// Parses each line without asserting a type onto it, and keeps the 1-based
+// line number each value came from. readRows below is the common case (a
+// caller that trusts its own writer), but a gate checking a file that could
+// have been hand-edited needs both: the unknown value, so it can run real
+// validation instead of a cast that only satisfies the compiler; and the
+// line number, so a violation can point at something the reader can find in
+// the file rather than just naming the record's own fields.
+export async function readRawRows(path: string): Promise<{ line: number; raw: unknown }[]> {
+  if (!existsSync(path)) return []
+  const text = await readFile(path, 'utf8')
+  const rows: { line: number; raw: unknown }[] = []
+  const lines = text.split('\n')
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]?.trim()
+    if (!line) continue
+    try {
+      rows.push({ line: i + 1, raw: JSON.parse(line) })
+    } catch {
+      throw new Error(`${path}: malformed JSON at line ${i + 1}`)
+    }
+  }
+  return rows
+}
+
+export async function readRows<T>(path: string): Promise<T[]> {
+  return (await readRawRows(path)).map((r) => r.raw as T)
+}
+
+// Temp-plus-rename so a crash mid-write cannot truncate the store. The temp
+// file is a sibling, which keeps the rename on one filesystem and therefore
+// atomic. Cleanup on failure ignores unlink errors to let the original error
+// propagate unchanged.
+export async function writeAtomically(
+  path: string,
+  content: string,
+  sourcePath: string,
+): Promise<void> {
+  await assertNotUnderSource(path, sourcePath)
+  const random = randomBytes(8).toString('hex')
+  const tmp = `${path}.${random}.tmp`
+  try {
+    await writeFile(tmp, content)
+    await rename(tmp, path)
+  } finally {
+    try {
+      await unlink(tmp)
+    } catch {
+      // Ignore cleanup errors, let original error propagate
+    }
+  }
+}
+
+// Temp-plus-rename so a crash mid-write cannot truncate the store. The temp
+// file is a sibling, which keeps the rename on one filesystem and therefore
+// atomic.
+export async function writeRows<T>(path: string, rows: T[], sourcePath: string): Promise<void> {
+  const body = rows.map((r) => JSON.stringify(r)).join('\n')
+  const text = rows.length > 0 ? `${body}\n` : ''
+  await writeAtomically(path, text, sourcePath)
+}
+
+function stableStringify(obj: unknown): string {
+  if (obj === null) return 'null'
+  if (typeof obj !== 'object') return JSON.stringify(obj)
+  if (Array.isArray(obj)) {
+    return `[${obj.map(stableStringify).join(',')}]`
+  }
+  const pairs: string[] = []
+  const keys = Object.keys(obj as Record<string, unknown>).sort()
+  for (const key of keys) {
+    const val = (obj as Record<string, unknown>)[key]
+    pairs.push(`${JSON.stringify(key)}:${stableStringify(val)}`)
+  }
+  return `{${pairs.join(',')}}`
+}
+
+export function upsertRows<T extends { id: string }>(
+  existing: T[],
+  incoming: T[],
+): { rows: T[]; added: number; updated: number } {
+  const snapshot = new Map<string, string>()
+  for (let i = 0; i < existing.length; i++) {
+    const row = existing[i]
+    if (row) snapshot.set(row.id, stableStringify(row))
+  }
+  const rows = [...existing]
+  const index = new Map<string, number>()
+  for (let i = 0; i < rows.length; i++) {
+    const row = rows[i]
+    if (row) index.set(row.id, i)
+  }
+  for (const row of incoming) {
+    const at = index.get(row.id)
+    if (at === undefined) {
+      index.set(row.id, rows.length)
+      rows.push(row)
+    } else {
+      rows[at] = row
+    }
+  }
+  let added = 0
+  let updated = 0
+  const finalIndex = new Map<string, string>()
+  for (let i = 0; i < rows.length; i++) {
+    const row = rows[i]
+    if (row) {
+      const id = row.id
+      const newStr = stableStringify(row)
+      finalIndex.set(id, newStr)
+      const oldStr = snapshot.get(id)
+      if (oldStr === undefined) {
+        added++
+      } else if (oldStr !== newStr) {
+        updated++
+      }
+    }
+  }
+  return { rows, added, updated }
+}

package/skills/migrate/scripts/types.ts

@@ -0,0 +1,137 @@
+export type Lens = 'code' | 'nav' | 'docs' | 'runtime'
+
+export type Ref =
+  | { kind: 'src'; path: string; lines?: [number, number] }
+  | { kind: 'ledger'; id: string }
+  | { kind: 'doc'; path: string; note?: string }
+  | { kind: 'observed'; host: string; path: string; behavior: string }
+
+export type Disposition =
+  | { kind: 'unaccounted' }
+  | { kind: 'mapped'; fr: string }
+  | { kind: 'out-of-scope'; queue: string }
+
+export type Element = {
+  id: string
+  surface: string
+  element: string
+  found_by: Lens[]
+  disposition: Disposition
+  refs: Ref[]
+  lens: Lens
+  batch: string
+  notes: string
+}
+
+export type Confidence =
+  | { kind: 'confirmed' }
+  | { kind: 'inferred' }
+  | { kind: 'queued'; queue: string }
+
+export type Parity =
+  | { kind: 'golden-master'; ref: string }
+  | { kind: 'differential'; ref: string }
+  | { kind: 'rubric'; level: 'high' }
+  | { kind: 'rubric'; level: 'moderate' | 'low' | 'unknown'; queue: string }
+
+export type Requirement = {
+  id: string
+  cap: string
+  requirement: string
+  actors: string
+  objects: string
+  rules: string
+  origin: 'intended' | 'accidental-candidate'
+  confidence: Confidence
+  citations: Ref[]
+  parity: Parity | null
+  batch: string
+}
+
+export type Capability = {
+  slug: string
+  title: string
+  ns: string
+  elements: string[]
+}
+
+export type Delta = {
+  id: string
+  scope: string
+  rationale: string
+  parity_exclusion: string
+  validation: string
+  owner_signed: string | null
+  batch: string
+}
+
+export type Skipped = { element: string; reason: string }
+
+// A direction records both how many findings it produced and how that count
+// was produced. The evidence is free text because some directions are
+// judgment walks rather than commands, so the gate is presence, not
+// executability; the field exists so a reviewer can retrace a count, and so a
+// later re-run verb has somewhere to read the command from.
+export type Direction = { count: number; evidence: string }
+
+export type Census =
+  | {
+      kind: 'lens'
+      surface: string
+      phase: string
+      directions: Record<string, Direction>
+      total: number
+      in_ledger: number
+      added: number
+      skipped: Skipped[]
+      queued: string[]
+      batch: string
+    }
+  | {
+      kind: 'attribute'
+      surface: string
+      subject: string
+      phase: string
+      directions: Record<string, Direction>
+      total: number
+      behavioral: number
+      explained: number
+      queued: string[]
+      batch: string
+    }
+  | {
+      kind: 'rule-sweep'
+      subject: string
+      phase: string
+      probes: number
+      found: number
+      as_requirements: number
+      queued: string[]
+      batch: string
+    }
+  | {
+      kind: 'closer'
+      closer: string
+      phase: string
+      checked: number
+      findings: number
+      fixed: number
+      queued: string[]
+      batch: string
+    }
+
+export type Severity = 'critical' | 'moderate' | 'minor'
+
+export type QueueItem = {
+  id: string
+  severity: Severity
+  status: 'open' | 'adjudicated'
+  ruling?: string
+  adjudicated?: string
+  evidence: string
+  options: string
+  recommendation: string
+  path: string
+}
+
+export type Violation = { gate: string; message: string }

package/skills/migrate/scripts/validate.ts

@@ -0,0 +1,221 @@
+import type { Config } from './config.ts'
+import { validateElementId } from './ids.ts'
+import type {
+  Confidence,
+  Delta,
+  Disposition,
+  Element,
+  Lens,
+  Parity,
+  Ref,
+  Requirement,
+} from './types.ts'
+
+export type Validated<T> = { ok: true; value: T } | { ok: false; errors: string[] }
+
+const LENSES: Lens[] = ['code', 'nav', 'docs', 'runtime']
+
+function str(v: unknown): v is string {
+  return typeof v === 'string'
+}
+
+// A row must be a JSON object. null, arrays and primitives all fail this, and
+// must be rejected here rather than left to crash on the first property read:
+// `null.id` throws, but a normal validation error is what every validator in
+// this file (and census.ts) expects to return instead.
+export function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v)
+}
+
+function checkRef(ref: unknown, where: string, errors: string[]): void {
+  const r = ref as Record<string, unknown>
+  const kind = r?.kind
+  if (kind === 'src') {
+    if (!str(r.path)) errors.push(`${where}: src ref needs a path`)
+    if (r.lines !== undefined) {
+      const lines = r.lines as unknown[]
+      const ok =
+        Array.isArray(lines) &&
+        lines.length === 2 &&
+        typeof lines[0] === 'number' &&
+        typeof lines[1] === 'number' &&
+        (lines[0] as number) <= (lines[1] as number)
+      if (!ok) errors.push(`${where}: src ref lines must be [start, end] with start <= end`)
+    }
+  } else if (kind === 'ledger') {
+    if (!str(r.id)) errors.push(`${where}: ledger ref needs an id`)
+  } else if (kind === 'doc') {
+    if (!str(r.path)) errors.push(`${where}: doc ref needs a path`)
+  } else if (kind === 'observed') {
+    if (!str(r.host) || !str(r.path) || !str(r.behavior)) {
+      errors.push(`${where}: observed ref needs host, path and behavior`)
+    }
+  } else {
+    errors.push(`${where}: unknown ref kind ${String(kind)}`)
+  }
+}
+
+export function validateElement(row: unknown, cfg: Config): Validated<Element> {
+  if (!isRecord(row)) return { ok: false, errors: ['element: row must be a JSON object'] }
+  const errors: string[] = []
+  const r = row
+  const id = str(r.id) ? r.id : ''
+  const surface = str(r.surface) ? r.surface : ''
+  const where = `element ${id || '<no id>'}`
+
+  if (!id) errors.push('element: missing id')
+  if (!surface) errors.push(`${where}: missing surface`)
+  else if (!cfg.surfaces.includes(surface)) {
+    errors.push(
+      `${where}: surface ${surface} is not in the declared set [${cfg.surfaces.join(', ')}]`,
+    )
+  } else if (id) {
+    const idError = validateElementId(id, surface, cfg.surfaceSingular)
+    if (idError) errors.push(`${where}: ${idError}`)
+  }
+  if (!str(r.element) || r.element.length === 0) errors.push(`${where}: missing element text`)
+
+  const foundBy = r.found_by as unknown[]
+  if (!Array.isArray(foundBy) || foundBy.length === 0) {
+    errors.push(`${where}: found_by must list at least one lens`)
+  } else {
+    for (const l of foundBy) {
+      if (!LENSES.includes(l as Lens))
+        errors.push(`${where}: unknown lens ${String(l)} in found_by`)
+    }
+  }
+  if (!LENSES.includes(r.lens as Lens)) errors.push(`${where}: unknown lens ${String(r.lens)}`)
+
+  const d = r.disposition as Record<string, unknown> | undefined
+  const dk = d?.kind
+  if (dk === 'unaccounted') {
+    // nothing further
+  } else if (dk === 'mapped') {
+    if (!str(d?.fr)) errors.push(`${where}: mapped disposition needs an fr id`)
+  } else if (dk === 'out-of-scope') {
+    if (!str(d?.queue)) errors.push(`${where}: out-of-scope disposition needs a queue id`)
+  } else {
+    errors.push(`${where}: unknown disposition kind ${String(dk)}`)
+  }
+
+  const refs = (r.refs ?? []) as unknown[]
+  if (!Array.isArray(refs)) errors.push(`${where}: refs must be an array`)
+  else
+    refs.forEach((ref, i) => {
+      checkRef(ref, `${where} refs[${i}]`, errors)
+    })
+
+  if (errors.length > 0) return { ok: false, errors }
+  return {
+    ok: true,
+    value: {
+      id,
+      surface,
+      element: r.element as string,
+      found_by: foundBy as Lens[],
+      disposition: r.disposition as Disposition,
+      refs: refs as Ref[],
+      lens: r.lens as Lens,
+      batch: '',
+      notes: str(r.notes) ? r.notes : '',
+    },
+  }
+}
+
+export function validateRequirement(row: unknown, _cfg: Config): Validated<Requirement> {
+  if (!isRecord(row)) return { ok: false, errors: ['requirement: row must be a JSON object'] }
+  const errors: string[] = []
+  const r = row
+  const id = str(r.id) ? r.id : ''
+  const where = `requirement ${id || '<no id>'}`
+
+  if (!id) errors.push('requirement: missing id')
+  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`)
+  if (r.origin !== 'intended' && r.origin !== 'accidental-candidate') {
+    errors.push(`${where}: origin must be intended or accidental-candidate`)
+  }
+
+  const c = r.confidence as Record<string, unknown> | undefined
+  if (c?.kind === 'queued') {
+    if (!str(c.queue)) errors.push(`${where}: queued confidence needs a queue id`)
+  } else if (c?.kind !== 'confirmed' && c?.kind !== 'inferred') {
+    errors.push(`${where}: unknown confidence kind ${String(c?.kind)}`)
+  }
+
+  const citations = (r.citations ?? []) as unknown[]
+  if (!Array.isArray(citations) || citations.length === 0) {
+    errors.push(`${where}: at least one citation is required`)
+  } else {
+    citations.forEach((ref, i) => {
+      checkRef(ref, `${where} citations[${i}]`, errors)
+    })
+  }
+
+  const p = r.parity as Record<string, unknown> | null | undefined
+  if (p !== null && p !== undefined) {
+    if (p.kind === 'golden-master' || p.kind === 'differential') {
+      if (!str(p.ref)) errors.push(`${where}: ${String(p.kind)} parity needs a ref`)
+    } else if (p.kind === 'rubric') {
+      const level = p.level
+      if (level === 'high') {
+        // no queue id needed
+      } else if (level === 'moderate' || level === 'low' || level === 'unknown') {
+        if (!str(p.queue)) errors.push(`${where}: rubric:${level} parity needs a queue id`)
+      } else {
+        errors.push(`${where}: unknown rubric level ${String(level)}`)
+      }
+    } else {
+      errors.push(`${where}: unknown parity kind ${String(p.kind)}`)
+    }
+  }
+
+  if (errors.length > 0) return { ok: false, errors }
+  return {
+    ok: true,
+    value: {
+      id,
+      cap: r.cap as string,
+      requirement: r.requirement as string,
+      actors: str(r.actors) ? r.actors : '-',
+      objects: str(r.objects) ? r.objects : '-',
+      rules: str(r.rules) ? r.rules : '-',
+      origin: r.origin as Requirement['origin'],
+      confidence: r.confidence as Confidence,
+      citations: citations as Ref[],
+      parity: (r.parity ?? null) as Parity | null,
+      batch: '',
+    },
+  }
+}
+
+export function validateDelta(row: unknown, _cfg: Config): Validated<Delta> {
+  if (!isRecord(row)) return { ok: false, errors: ['delta: row must be a JSON object'] }
+  const errors: string[] = []
+  const r = row
+  const id = str(r.id) ? r.id : ''
+  const where = `delta ${id || '<no id>'}`
+  if (!id.startsWith('delta-')) errors.push(`${where}: id must start with delta-`)
+  for (const key of ['scope', 'rationale', 'parity_exclusion', 'validation']) {
+    const v = r[key]
+    if (!str(v) || v.length === 0) errors.push(`${where}: missing ${key}`)
+  }
+  const signed = r.owner_signed
+  if (signed !== null && signed !== undefined && !str(signed)) {
+    errors.push(`${where}: owner_signed must be a date string or null`)
+  }
+  if (errors.length > 0) return { ok: false, errors }
+  return {
+    ok: true,
+    value: {
+      id,
+      scope: r.scope as string,
+      rationale: r.rationale as string,
+      parity_exclusion: r.parity_exclusion as string,
+      validation: r.validation as string,
+      owner_signed: (signed ?? null) as string | null,
+      batch: '',
+    },
+  }
+}

package/skills/migrate/skill.json

@@ -0,0 +1,33 @@
+{
+  "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.",
+  "author": "iceinvein",
+  "type": "prompt",
+  "tools": ["claude"],
+  "files": { "prompt": "SKILL.md" },
+  "bundle": {
+    "include": [
+      "bin",
+      "references",
+      "scripts",
+      "templates",
+      "fixtures/tiny-express",
+      "fixtures/tiny-webforms",
+      "install.sh",
+      "uninstall.sh",
+      "package.json",
+      "README.md",
+      "docs/reference.md"
+    ],
+    "exclude": ["scripts/__tests__/"]
+  },
+  "install": {
+    "claude": {
+      "prompt": ".claude/skills/migrate/SKILL.md",
+      "bundleRoot": ".claude/skills/migrate",
+      "postinstall": "install.sh",
+      "postremove": "uninstall.sh"
+    }
+  }
+}

package/skills/migrate/templates/config.toml

@@ -0,0 +1,27 @@
+[source]
+path  = "{{SOURCE_PATH}}"
+scope = "{{SCOPE}}"
+stack = "{{SOURCE_STACK}}"
+vcs   = "{{VCS}}"
+basis = "{{BASIS}}"
+
+[target]
+name  = "{{TARGET_NAME}}"
+stack = "{{TARGET_STACK}}"
+parity_test_path = "tests/parity/{capability}/{fr_slug}.test.ts"
+
+[target.layout]
+
+[target.commands]
+test  = "echo 'wire the target test command'"
+lint  = "echo 'wire the target lint command'"
+build = "echo 'wire the target build command'"
+
+[surfaces]
+types = ["routes", "tables", "jobs", "reports", "screens", "integrations", "workflows", "settings"]
+
+[closers]
+set = ["cross-capability-workflow", "scope-injection", "read-write-symmetry"]
+
+[handoff]
+adapter = "markdown"

package/skills/migrate/templates/queue-item.md

@@ -0,0 +1,17 @@
+---
+id: q-{{SLUG}}
+severity: {{SEVERITY}}
+status: open
+---
+
+## Evidence
+
+{{EVIDENCE}}
+
+## Options
+
+{{OPTIONS}}
+
+## Recommendation
+
+{{RECOMMENDATION}}

package/skills/migrate/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "types": ["bun"],
+    "lib": ["ESNext"],
+    "jsx": "preserve"
+  },
+  "include": ["bin/**/*.ts", "scripts/**/*.ts"]
+}