@iceinvein/agent-skills 0.1.39 → 0.2.0

package/skills/migrate/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: migrate
+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.
+---
+
+# migrate
+
+## Prerequisites
+
+- `migrate` on `PATH`, put there by this skill's `install.sh`.
+- A read-only checkout of the legacy source. `migrate check`'s `citations` and
+  `source` gates read it; nothing here writes to it, and every writer in the CLI
+  refuses a path that resolves inside it.
+- A target repo that is a git working copy. The store lives inside it and
+  commits alongside your own work; there is no separate run directory.
+
+## Phase walkthrough
+
+Work phases 0 through 7 in order. Do not skip ahead: the run-state gate fails a
+phase marked `done` while its predecessor is still `pending`, so working out of
+order just produces a violation you undo later.
+
+### 0. Probe
+
+Produces `.migrate/config.toml` (detected source stack, `runnable` or
+`source-only` basis, the target profile), written by `migrate init`, plus
+`.migrate/parity-basis.md`: hand-written prose carrying the detection
+evidence, since no command writes it either.
+
+Read `references/phases/probe.md` before dispatching anything.
+
+```
+migrate init --source <path> --scope "<text>" --name <target> \
+  [--source-stack <s>] [--target-stack <s>] [--basis <runnable|source-only>]
+migrate phase probe --status done
+```
+
+### 1. Enumerate
+
+Produces `elements.jsonl`, every row `unaccounted`, and one `lens` census
+record per declared surface type.
+
+Read `references/phases/enumerate.md` before dispatching anything.
+
+Fanout unit: one agent per (surface, lens) pair.
+
+```
+migrate import elements <batch.json>
+migrate census <lens-record.json>
+migrate phase enumerate --status done
+```
+
+### 2. Seam
+
+Produces `capabilities.jsonl` (the seam partition), `seam.json` (run-level
+seam metadata), and `seam.md` (the validators' raw evidence). All three are
+hand-written: there is no `seam` verb, so nothing in the CLI authors their
+content. (`migrate reset --phase seam` does write to these paths, clearing
+`capabilities.jsonl` and deleting the other two, but that undoes the phase
+rather than authoring it.)
+
+Read `references/phases/seam.md` before dispatching anything.
+
+```
+migrate phase seam --status done
+```
+
+### 3. Extract
+
+Produces `requirements.jsonl`, the attribute/rule-sweep/closer census records,
+and a terminal disposition on every element.
+
+Read `references/phases/extract.md` before dispatching anything.
+
+Fanout unit: one agent per capability.
+
+```
+migrate import reqs <batch.json>
+migrate import elements <batch.json>
+migrate census <record.json>
+migrate queue add <item.md>
+migrate phase extract --status done
+```
+
+`queue add` is not optional here. An `out-of-scope` disposition's queue id
+and a `queued` confidence's queue id are both checked by the `refs` gate, and
+a queue id with no file behind it is a violation the moment anything checks,
+not a future one. File each item in the same pass that names it.
+
+The second import carries the resolved `disposition` (`mapped` or
+`out-of-scope`); it is the only writer of a *resolved* value there, so this
+line is the ledger write-back itself, not something the phase-status flip
+does for you. `migrate reset --phase extract` also writes this field, but
+only back to `unaccounted`; it clears, it does not resolve.
+
+### 4. Parity
+
+Produces `deltas.jsonl` and a parity plan on every requirement whose
+confidence is not `queued`.
+
+Read `references/phases/parity.md` before dispatching anything.
+
+```
+migrate import deltas <batch.json>
+migrate import reqs <batch.json>
+migrate queue add <item.md>
+migrate phase parity --status done
+```
+
+Same rule as phase 3: a `rubric` plan below `high` must carry a queue id, and
+the `refs` gate checks it resolves, so file the item in this pass.
+
+The second import carries the resolved `parity` value; as in extract, it is
+the only writer of a *resolved* value, and this line is the write-back
+itself. `migrate reset --phase parity` also writes this field, but only
+back to `null`; it clears, it does not resolve.
+
+### 5. Queue
+
+Produces the queue items carrying forward anything ambiguous: evidence,
+options, and a recommendation, filed for an owner to adjudicate.
+
+Read `references/phases/queue.md` before dispatching anything.
+
+```
+migrate queue add <item.md>
+migrate phase queue --status done
+```
+
+### 6. Adjudicate
+
+A run stops at the queue in this version of the tool: `adjudicate` has no verb
+yet, so nothing here can move a queue item's status past `open`. `migrate
+status` and `migrate queue list` are the terminus; adjudication arrives with
+its verb in the next milestone.
+
+### 7. Handoff
+
+`handoff` has no verb yet either, for the same reason. `migrate status` and
+`migrate queue list` remain the terminus; handoff arrives with its verb in the
+next milestone.
+
+## Checking as you go
+
+Run `migrate check --phase <current>` after every batch. It bounds the
+run-state gate at that phase; the other nine gates always read the whole
+store, so a coverage or census gap past your current phase still fails on its
+own gate regardless of `--phase`.
+
+Run plain `migrate check` only when claiming the whole migration is complete:
+with no `--phase`, it gates every phase through `handoff`. In this version
+that cannot pass, because `adjudicate` and `handoff` have no verbs to complete
+them. `migrate check --phase queue` is the practical terminus for this
+milestone; its exit 0 is what "done, for now" means.
+
+```
+migrate check --phase queue
+migrate check
+```
+
+## Resuming a crashed run
+
+```
+migrate status
+migrate phase
+```
+
+`migrate status` prints the last committed batch and the outstanding work;
+`migrate phase` (no name) prints every phase's status and batch count, one
+line each, so you can see exactly where the run stopped. To re-enter one
+phase, clear its derived rows and re-run it:
+
+```
+migrate reset --phase <phase>
+```
+
+Re-importing a batch upserts rows by id rather than duplicating them, so
+progress from before the crash is not lost by retrying it.
+
+## Aborting
+
+There is no run directory to delete: the store lives at `.migrate/` inside the
+target repo. `references/run-ops.md` holds the batch-checkpoint discipline (a
+git commit after every `migrate import`); if it was followed, an aborted run
+leaves behind exactly whatever the last commit captured. Leave `.migrate/` in
+place either way. Discard only uncommitted scratch files, such as a
+`batch.json` you built but never imported. `.migrate/.env`, if a runtime lens
+created one, must never be committed regardless of how the run ends. `init`
+takes care of the ignore entry in all three cases, and says on stdout when it
+changed something: `init: created <path> with .migrate/.env` when the target
+had no `.gitignore`, `init: appended .migrate/.env to <path>` when it had one
+without the entry, and **nothing at all** when the entry was already there,
+since there was nothing to change. Silence from `init` on this is the
+already-correct case, not a skipped one. If you edited `.gitignore` after
+`init` ran, check the entry is still there before committing anything, because
+nothing re-checks it: the `leaks` gate that would catch a committed value is
+opt-in (`migrate check --leaks`).

package/skills/migrate/bin/migrate

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Resolve symlinks so we find the real migrate.ts even when invoked via
+# a /usr/local/bin or ~/.local/bin symlink.
+SCRIPT="${BASH_SOURCE[0]}"
+while [ -L "$SCRIPT" ]; do
+  DIR="$(cd -P "$(dirname "$SCRIPT")" && pwd)"
+  TARGET="$(readlink "$SCRIPT")"
+  if [[ "$TARGET" = /* ]]; then
+    SCRIPT="$TARGET"
+  else
+    SCRIPT="$DIR/$TARGET"
+  fi
+done
+DIR="$(cd -P "$(dirname "$SCRIPT")" && pwd)"
+exec bun "$DIR/migrate.ts" "$@"

package/skills/migrate/bin/migrate.ts

@@ -0,0 +1,309 @@
+#!/usr/bin/env bun
+
+import pkg from '../package.json' with { type: 'json' }
+
+const VERSION = (pkg as { version: string }).version
+
+const USAGE = `Usage: migrate <subcommand> [args]
+
+Subcommands:
+  init --source <path> --scope <text> --name <target>
+                                  Write .migrate/config.toml
+  import <elements|reqs|deltas> <batch.json> [--force-unlock]
+                                  Validated bulk append to the store
+  census <record.json> [--force-unlock]
+                                  Record a lens accounting record
+  phase [<name>] [--status <s>] [--force-unlock]
+                                  Print phase state, or set one phase's status
+  queue add <file.md>             Add a queue item
+  queue list [--open]             List queue items, severity first
+  queue show <id>                 Print one queue item
+  check [--phase <p>] [--no-citations] [--leaks]
+                                  Run the gates; without --phase, exit 0 means
+                                  the whole migration is complete
+  status                          Phase state, counts, resume pointer
+  reset --phase <phase> [--force-unlock]
+                                  Clear one phase's derived rows
+  report [--out <dir>]            Render markdown views
+  --version                       Print the migrate version
+  --help                          Show this message`
+
+type Handler = (args: string[]) => Promise<number> | number
+
+// A flag's value is missing, or the value slot is occupied by another flag
+// (`init --scope --name newapp` used to read scope as the literal string
+// "--name" and carry on), in both cases the request is malformed, not a
+// value the command can act on. Every `--flag <value>` parser in this file
+// shares this one check so the three no longer disagree about which of
+// those two shapes is a usage error and which is silently tolerated.
+function readFlag(args: string[], name: string): { value?: string; error?: string } {
+  const at = args.indexOf(name)
+  if (at === -1) return {}
+  const value = args[at + 1]
+  if (value === undefined || value.startsWith('--')) {
+    return { error: `${name} needs a value` }
+  }
+  return { value }
+}
+
+const HANDLERS: Record<string, Handler> = {
+  init: async (args) => {
+    const names = ['--source', '--scope', '--name', '--source-stack', '--target-stack', '--basis']
+    const values: Record<string, string | undefined> = {}
+    for (const name of names) {
+      const result = readFlag(args, name)
+      if (result.error) {
+        process.stderr.write(`init: ${result.error}\n`)
+        return 2
+      }
+      values[name] = result.value
+    }
+    const sourcePath = values['--source']
+    const scope = values['--scope']
+    const targetName = values['--name']
+    if (!sourcePath || !scope || !targetName) {
+      process.stderr.write(
+        'init: want --source <path> --scope <text> --name <target> [--source-stack <s>] [--target-stack <s>] [--basis <runnable|source-only>]\n',
+      )
+      return 2
+    }
+    const { runInit } = await import('../scripts/init-cmd.ts')
+    return runInit({
+      root: process.cwd(),
+      sourcePath,
+      scope,
+      targetName,
+      ...(values['--source-stack'] ? { sourceStack: values['--source-stack'] } : {}),
+      ...(values['--target-stack'] ? { targetStack: values['--target-stack'] } : {}),
+      ...(values['--basis'] ? { basis: values['--basis'] } : {}),
+    })
+  },
+  import: async (args) => {
+    const kind = args[0]
+    const file = args[1]
+    if (kind !== 'elements' && kind !== 'reqs' && kind !== 'deltas') {
+      process.stderr.write('import: want <elements|reqs|deltas> <batch.json>\n')
+      return 2
+    }
+    if (!file) {
+      process.stderr.write('import: missing <batch.json>\n')
+      return 2
+    }
+    const { findStoreRoot } = await import('../scripts/paths.ts')
+    const root = await findStoreRoot(process.cwd())
+    if (!root) {
+      process.stderr.write('import: no .migrate store found above the cwd\n')
+      return 2
+    }
+    const forceUnlock = args.includes('--force-unlock')
+    const { runImport } = await import('../scripts/import-cmd.ts')
+    return runImport({
+      root,
+      kind,
+      batchFile: file,
+      ...(forceUnlock ? { forceUnlock: true } : {}),
+    })
+  },
+  census: async (args) => {
+    const file = args[0]
+    if (!file) {
+      process.stderr.write('census: missing <record.json>\n')
+      return 2
+    }
+    const { findStoreRoot } = await import('../scripts/paths.ts')
+    const root = await findStoreRoot(process.cwd())
+    if (!root) {
+      process.stderr.write('census: no .migrate store found above the cwd\n')
+      return 2
+    }
+    const forceUnlock = args.includes('--force-unlock')
+    const { runCensus } = await import('../scripts/census-cmd.ts')
+    return runCensus({ root, file, ...(forceUnlock ? { forceUnlock: true } : {}) })
+  },
+  phase: async (args) => {
+    const status = readFlag(args, '--status')
+    if (status.error) {
+      process.stderr.write(`phase: ${status.error}\n`)
+      return 2
+    }
+    // args[0] is the phase name only when it is a positional. A flag sitting
+    // in that slot (`phase --force-unlock enumerate --status done`) leaves the
+    // name undefined, which used to silently downgrade a write to a read:
+    // every phase's line printed, exit 0, nothing moved. `import` and `census`
+    // both reject the identical flag-ordering mistake at 2, because their
+    // first positional is load-bearing too. Any write-intent flag with no
+    // phase name to apply it to is that same mistake, so it is refused here
+    // rather than serviced as a listing nobody asked for.
+    const name = args[0]?.startsWith('--') ? undefined : args[0]
+    if (!name && (status.value !== undefined || args.includes('--force-unlock'))) {
+      process.stderr.write(
+        'phase: want <name> before --status/--force-unlock, as in `phase enumerate --status done`\n',
+      )
+      return 2
+    }
+    const { findStoreRoot } = await import('../scripts/paths.ts')
+    const root = await findStoreRoot(process.cwd())
+    if (!root) {
+      process.stderr.write('phase: no .migrate store found above the cwd\n')
+      return 2
+    }
+    const forceUnlock = args.includes('--force-unlock')
+    const { runPhase } = await import('../scripts/phase-cmd.ts')
+    return runPhase({
+      root,
+      ...(name ? { name } : {}),
+      ...(status.value ? { status: status.value } : {}),
+      ...(forceUnlock ? { forceUnlock: true } : {}),
+    })
+  },
+  queue: async (args) => {
+    const { findStoreRoot } = await import('../scripts/paths.ts')
+    const root = await findStoreRoot(process.cwd())
+    if (!root) {
+      process.stderr.write('queue: no .migrate store found above the cwd\n')
+      return 2
+    }
+    const { runQueue } = await import('../scripts/queue-cmd.ts')
+    return runQueue({ root, args })
+  },
+  check: async (args) => {
+    const phase = readFlag(args, '--phase')
+    if (phase.error) {
+      process.stderr.write(`check: ${phase.error}\n`)
+      return 2
+    }
+    const { isPhase, PHASES } = await import('../scripts/phases.ts')
+    if (phase.value && !isPhase(phase.value)) {
+      process.stderr.write(
+        `check: unknown phase ${phase.value}; want one of ${PHASES.join(', ')}\n`,
+      )
+      return 2
+    }
+    const { findStoreRoot } = await import('../scripts/paths.ts')
+    const root = await findStoreRoot(process.cwd())
+    if (!root) {
+      process.stderr.write('check: no .migrate store found above the cwd\n')
+      return 2
+    }
+    const { runCheckCmd } = await import('../scripts/check-cmd.ts')
+    return runCheckCmd({
+      root,
+      // --citations is accepted and ignored: citations are on by default now,
+      // and silently rejecting the old flag would break every invocation
+      // written against Milestone 1.
+      citations: !args.includes('--no-citations'),
+      leaks: args.includes('--leaks'),
+      ...(phase.value && isPhase(phase.value) ? { phase: phase.value } : {}),
+    })
+  },
+  status: async () => {
+    const { findStoreRoot } = await import('../scripts/paths.ts')
+    const root = await findStoreRoot(process.cwd())
+    if (!root) {
+      process.stderr.write('status: no .migrate store found above the cwd\n')
+      return 2
+    }
+    const { runStatus } = await import('../scripts/status-cmd.ts')
+    return runStatus({ root })
+  },
+  reset: async (args) => {
+    const result = readFlag(args, '--phase')
+    if (result.error) {
+      process.stderr.write(`reset: ${result.error}\n`)
+      return 2
+    }
+    const phase = result.value
+    if (!phase) {
+      process.stderr.write('reset: missing --phase <phase>\n')
+      return 2
+    }
+    const { findStoreRoot } = await import('../scripts/paths.ts')
+    const root = await findStoreRoot(process.cwd())
+    if (!root) {
+      process.stderr.write('reset: no .migrate store found above the cwd\n')
+      return 2
+    }
+    const forceUnlock = args.includes('--force-unlock')
+    const { runReset } = await import('../scripts/reset-cmd.ts')
+    return runReset({ root, phase, ...(forceUnlock ? { forceUnlock: true } : {}) })
+  },
+  report: async (args) => {
+    const result = readFlag(args, '--out')
+    if (result.error) {
+      process.stderr.write(`report: ${result.error}\n`)
+      return 2
+    }
+    const outDir = result.value
+    const { findStoreRoot } = await import('../scripts/paths.ts')
+    const root = await findStoreRoot(process.cwd())
+    if (!root) {
+      process.stderr.write('report: no .migrate store found above the cwd\n')
+      return 2
+    }
+    const { runReport } = await import('../scripts/report-cmd.ts')
+    return runReport({ root, ...(outDir ? { outDir } : {}) })
+  },
+}
+
+// A handler's rejection reaching the guard below is not guaranteed to be an
+// Error: `(e as Error).message` on a non-Error rejection prints the useless
+// "sub: undefined", and on a rejected `null` or `undefined` it throws inside
+// the catch itself -- the one shape that would otherwise still escape this
+// guard uncaught. Every other value (a string, a plain object, an Error)
+// converts to a message without throwing.
+export function errorMessage(e: unknown): string {
+  return e instanceof Error ? e.message : String(e)
+}
+
+export async function main(argv: string[]): Promise<number> {
+  const [sub, ...rest] = argv
+  if (sub === '--help' || sub === '-h') {
+    process.stdout.write(`${USAGE}\n`)
+    return 0
+  }
+  if (sub === '--version' || sub === '-V') {
+    process.stdout.write(`migrate ${VERSION}\n`)
+    return 0
+  }
+  if (!sub) {
+    process.stderr.write(`${USAGE}\n`)
+    return 2
+  }
+  const handler = HANDLERS[sub]
+  if (!handler) {
+    process.stderr.write(`Unknown subcommand: ${sub}\n${USAGE}\n`)
+    return 2
+  }
+  try {
+    return await handler(rest)
+  } catch (e) {
+    // Every failure a handler recognizes already returns its own exit code
+    // without throwing (see import-cmd.ts, census-cmd.ts, queue-cmd.ts,
+    // check-cmd.ts). An Error reaching here is one none of them classified,
+    // and in this codebase that is dominated by one shape: loadConfig
+    // throwing because config.toml is missing or malformed, unguarded at
+    // its import-cmd.ts, census-cmd.ts, queue-cmd.ts and check.ts call
+    // sites, or an equivalent case where the store itself cannot be read
+    // (a corrupt phases.json, a malformed row in an existing store file).
+    // Every one of those means the request could never have been serviced
+    // as posed, not that a well-formed request turned up a bad answer, so
+    // it takes the same code already used a few lines up for "no .migrate
+    // store found above the cwd" and, in every handler, for the
+    // assertNotUnderSource containment refusal: 2, not 1. The message
+    // printed is the Error's own message (never a generic replacement, so a
+    // genuine bug is still visible), prefixed the way every handler prefixes
+    // its own diagnostics, and nothing else: no stack trace.
+    process.stderr.write(`${sub}: ${errorMessage(e)}\n`)
+    return 2
+  }
+}
+
+// Guarded so this module can be imported (e.g. by tests, to exercise `main`
+// and `errorMessage` directly) without re-running the CLI against the
+// importing process's own argv and calling process.exit out from under it.
+// Running `bun bin/migrate.ts ...` directly still takes this branch exactly
+// as before.
+if (import.meta.main) {
+  const code = await main(process.argv.slice(2))
+  process.exit(code)
+}

package/skills/migrate/biome.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.4.6/schema.json",
+  "assist": {
+    "enabled": true,
+    "actions": {
+      "source": {
+        "organizeImports": "on"
+      }
+    }
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "suspicious": {
+        "noArrayIndexKey": "off"
+      }
+    }
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 100
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "single",
+      "semicolons": "asNeeded"
+    }
+  },
+  "files": {
+    "includes": ["bin/**", "scripts/**"]
+  }
+}

package/skills/migrate/bun.lock

@@ -0,0 +1,24 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "migrate",
+      "devDependencies": {
+        "@types/bun": "^1.2.0",
+        "typescript": "^5.9.0",
+      },
+    },
+  },
+  "packages": {
+    "@types/bun": ["@types/bun@1.3.14", "", { "dependencies": { "bun-types": "1.3.14" } }, "sha512-h1hFqFVcvAvD9j9K7ZW7vd82aSA+rTdznZa+5bwvCwqSB1jmmfLcbIWhOLx1/+boy/xmjgCs/OMUL8hRJSmnPw=="],
+
+    "@types/node": ["@types/node@26.1.2", "", { "dependencies": { "undici-types": "~8.3.0" } }, "sha512-Vu4a5UFA9rIIFJ7rB/Vaafh9lrCQszopTCx6KjFboXTGQbPNasehVR5TEiithSDGyd1DEiUByggTZsg8jukeIg=="],
+
+    "bun-types": ["bun-types@1.3.14", "", { "dependencies": { "@types/node": "*" } }, "sha512-4N0ig0fEomHt5R0KCFWjovxow98rIoRwKolrYdCcknNwMekCXRnWEUvgu5soYV8QXtVsrUD8B95MBOZGPvr6KQ=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@8.3.0", "", {}, "sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ=="],
+  }
+}