@iceinvein/agent-skills 0.1.39 → 0.2.0

package/skills/magpie/scripts/shard.ts

@@ -0,0 +1,171 @@
+import { mkdir, readdir, rm, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { type FileChunk, splitFileChunks } from './diff-chunks.ts'
+
+export const DEFAULT_SHARD_BUDGET = 6000
+export const DEFAULT_SHARD_MAX_FILES = 80
+
+export type ShardEntry = { id: number; path: string; files: string[]; lines: number }
+export type ShardManifest = {
+  budget: number
+  maxFiles: number
+  totalFiles: number
+  totalLines: number
+  shards: ShardEntry[]
+}
+
+/**
+ * The directory a file is grouped under, capped at two segments. Cohesion is
+ * not cosmetic: the architecture and code-smells focuses look for duplication,
+ * boundary violations, and shotgun surgery, and splitting a module across
+ * shards hides exactly those.
+ */
+export function groupKey(path: string): string {
+  const parts = path.split('/')
+  if (parts.length <= 1) return '.'
+  return parts.slice(0, Math.min(2, parts.length - 1)).join('/')
+}
+
+export function planShards(chunks: FileChunk[], budget: number, maxFiles: number): FileChunk[][] {
+  const groups = new Map<string, FileChunk[]>()
+  for (const c of chunks) {
+    const key = groupKey(c.path)
+    const existing = groups.get(key)
+    if (existing) existing.push(c)
+    else groups.set(key, [c])
+  }
+
+  const shards: FileChunk[][] = []
+  let current: FileChunk[] = []
+  let currentLines = 0
+  const flush = () => {
+    if (current.length > 0) {
+      shards.push(current)
+      current = []
+      currentLines = 0
+    }
+  }
+
+  for (const members of groups.values()) {
+    const groupLines = members.reduce((n, c) => n + c.lines, 0)
+    // Start a fresh shard rather than straddle a group across a boundary, when
+    // the whole group could fit on its own.
+    if (
+      current.length > 0 &&
+      (currentLines + groupLines > budget || current.length + members.length > maxFiles)
+    ) {
+      flush()
+    }
+    for (const c of members) {
+      if (
+        current.length > 0 &&
+        (currentLines + c.lines > budget || current.length + 1 > maxFiles)
+      ) {
+        flush()
+      }
+      current.push(c)
+      currentLines += c.lines
+    }
+  }
+  flush()
+  return shards
+}
+
+/** Read `$RUN_DIR/diff.patch`, tolerating only its absence. A missing
+ *  diff.patch means "nothing to shard"; anything else (permission error,
+ *  disk error, EISDIR, ...) is a genuine failure and must propagate rather
+ *  than silently turn into an empty manifest. */
+async function readDiffPatch(runDir: string): Promise<string> {
+  try {
+    return await Bun.file(join(runDir, 'diff.patch')).text()
+  } catch (err) {
+    const code = err && typeof err === 'object' && 'code' in err ? err.code : undefined
+    if (code === 'ENOENT') return ''
+    throw err
+  }
+}
+
+/** Delete `shard-<n>.patch` files left by an earlier split. Re-splitting 7 shards
+ *  into 4 would otherwise leave `shard-5.patch` .. `shard-7.patch` on disk: the
+ *  manifest is authoritative for dispatch, but a stale patch makes the directory
+ *  claim coverage the manifest does not have, and a resume that reads shard ids
+ *  off disk would review a file set that no longer matches its id. Only the shard
+ *  patches are touched: `manifest.json` stays in place until it is overwritten at
+ *  the end (so there is never a window with no manifest), and `diff.patch` lives
+ *  outside this directory and is what a single-shard manifest points at. */
+async function clearStaleShardPatches(shardsDir: string): Promise<void> {
+  let entries: string[]
+  try {
+    entries = await readdir(shardsDir)
+  } catch {
+    return
+  }
+  for (const name of entries) {
+    if (/^shard-\d+\.patch$/.test(name)) await rm(join(shardsDir, name), { force: true })
+  }
+}
+
+/**
+ * Split `$RUN_DIR/diff.patch` into budgeted shards. `diff.patch` is never
+ * modified: shards are views over it, which is what keeps the critic's diff
+ * excerpts, dedupe's evidence check, and the report's rendering working
+ * unchanged.
+ *
+ * Re-splitting an already-sharded run invalidates any
+ * `findings/<focus>.shard-<n>.json` from the previous split: the same shard id
+ * now names a different file set. Stage 4's resume rule keys on those files, so
+ * the caller must delete them before re-dispatching.
+ */
+export async function shardDiff(
+  runDir: string,
+  opts: { budget?: number; maxFiles?: number } = {},
+): Promise<ShardManifest> {
+  const budget = opts.budget ?? DEFAULT_SHARD_BUDGET
+  const maxFiles = opts.maxFiles ?? DEFAULT_SHARD_MAX_FILES
+  const diff = await readDiffPatch(runDir)
+  const chunks = splitFileChunks(diff)
+  const totalLines = chunks.reduce((n, c) => n + c.lines, 0)
+  const shardsDir = join(runDir, 'shards')
+  await clearStaleShardPatches(shardsDir)
+  await mkdir(shardsDir, { recursive: true })
+
+  const planned = planShards(chunks, budget, maxFiles)
+  let shards: ShardEntry[]
+  if (planned.length === 0) {
+    shards = []
+  } else if (planned.length === 1) {
+    // Single-shard passthrough: stage 4 takes the same path it took on 0.9.0.
+    const only = planned[0] ?? []
+    shards = [
+      {
+        id: 1,
+        path: 'diff.patch',
+        files: only.map((c) => c.path),
+        lines: only.reduce((n, c) => n + c.lines, 0),
+      },
+    ]
+  } else {
+    shards = []
+    for (const [i, members] of planned.entries()) {
+      const id = i + 1
+      const rel = `shards/shard-${id}.patch`
+      await writeFile(join(runDir, rel), members.map((c) => c.text).join(''))
+      shards.push({
+        id,
+        path: rel,
+        files: members.map((c) => c.path),
+        lines: members.reduce((n, c) => n + c.lines, 0),
+      })
+    }
+  }
+
+  const manifest: ShardManifest = {
+    budget,
+    maxFiles,
+    totalFiles: chunks.length,
+    totalLines,
+    shards,
+  }
+  await writeFile(join(shardsDir, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`)
+  return manifest
+}

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

@@ -1,7 +1,10 @@
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 
-const ORDER = [
+/** The resume ladder. Exported so `skill-lint` can assert that the diagnostic
+ *  stage names SKILL.md logs (`filter`, `tests-check`, `shard-coverage`, ...) stay
+ *  out of it: a diagnostic entry that lands on this list would move `next`. */
+export const ORDER = [
   'setup',
   'context',
   'specialists',
@@ -15,9 +18,9 @@ const ORDER = [
 export type StatusResult = {
   /**
    * Highest stage the log says is behind us. A stage logged `skipped` counts:
-   * `context` has no work in the pipeline and is always logged that way, so
-   * treating it as unfinished would send a resume back to a stage that has no
-   * step to run.
+   * `context` logs `skipped` when the scout produced no brief, and the pipeline
+   * has nothing to go back for, so treating it as unfinished would send a resume
+   * to a stage with no remaining work.
    */
   lastCompleted: (typeof ORDER)[number] | null
   next: (typeof ORDER)[number] | 'cleanup'

package/skills/magpie/scripts/types.ts

@@ -332,3 +332,53 @@ export type PrFileEntry = {
 export function isSuggestion(f: ReviewFinding): boolean {
   return f.risk.action === 'consider' || f.risk.action === 'optional'
 }
+
+export type BriefSubsystem = {
+  name: string
+  role: string
+}
+
+/** Scout-produced PR summary. Written to `$RUN_DIR/brief.json` by the context stage. */
+export type PrBrief = {
+  purpose: string
+  changes: string[]
+  subsystems: BriefSubsystem[]
+  watchItems: string[]
+  unclear: string[]
+}
+
+function briefStrings(raw: unknown): string[] {
+  if (!Array.isArray(raw)) return []
+  return raw
+    .filter((v): v is string => typeof v === 'string')
+    .map((v) => v.trim())
+    .filter((v) => v.length > 0)
+}
+
+/**
+ * Lenient by design, unlike `parseFinding`. A subagent-authored brief that came
+ * back malformed must degrade the report header to absent, not throw away an
+ * otherwise-complete review at render time.
+ */
+export function parseBrief(raw: unknown): PrBrief | null {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null
+  const r = raw as Record<string, unknown>
+  const purpose = typeof r.purpose === 'string' ? r.purpose.trim() : ''
+  if (purpose.length === 0) return null
+  const subsystems: BriefSubsystem[] = Array.isArray(r.subsystems)
+    ? (r.subsystems as unknown[]).flatMap((entry) => {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) return []
+        const e = entry as Record<string, unknown>
+        const name = typeof e.name === 'string' ? e.name.trim() : ''
+        if (name.length === 0) return []
+        return [{ name, role: typeof e.role === 'string' ? e.role.trim() : '' }]
+      })
+    : []
+  return {
+    purpose,
+    changes: briefStrings(r.changes),
+    subsystems,
+    watchItems: briefStrings(r.watchItems),
+    unclear: briefStrings(r.unclear),
+  }
+}

package/skills/magpie/skill.json

@@ -1,7 +1,7 @@
 {
   "name": "magpie",
-  "version": "0.8.0",
-  "description": "Interactive PR review pipeline. Runs five parallel specialist subagents (security, bugs, performance, code-smells, architecture), dedupes findings, applies a critic rubric, peer-reviews via codex exec (falling back to a Claude second opinion when codex is unavailable), and serves an interactive HTML report for selecting findings to post via gh. Bundles a Bun CLI installed onto PATH via the skill's postinstall step. Use when the user asks to review a GitHub pull request.",
+  "version": "0.10.0",
+  "description": "Interactive PR review pipeline. Runs five parallel specialist subagents (security, bugs, performance, code-smells, architecture), dedupes findings, applies a critic rubric, peer-reviews via codex exec (falling back to a Claude second opinion when codex is unavailable), and serves an interactive HTML report for selecting findings to post via gh. Bundles a Bun CLI installed onto PATH via the skill's postinstall step. Use when the user asks to review a GitHub pull request. Splits oversized diffs into budgeted shards and rebuilds the diff from the local clone when gh pr diff refuses it.",
   "author": "iceinvein",
   "type": "prompt",
   "tools": [

package/skills/magpie/templates/styles.css

@@ -183,6 +183,11 @@ button {
   color: var(--ink);
 }
 
+.diff-source {
+  font-size: 0.78rem;
+  opacity: 0.7;
+}
+
 .header-spacer {
   flex: 1;
 }
@@ -1638,3 +1643,64 @@ code.inline-code {
     border-color: var(--line);
   }
 }
+
+/* ---- PR brief header ---- */
+.pr-brief {
+  margin: 0;
+  padding: 10px 16px 12px;
+  background: var(--card);
+  border-bottom: 1px solid var(--line);
+  color: var(--ink);
+}
+
+.brief-summary {
+  cursor: pointer;
+  font-size: 12px;
+  font-weight: 600;
+  letter-spacing: 0.02em;
+  text-transform: uppercase;
+  color: var(--ink-muted);
+}
+
+.brief-body {
+  padding-top: 8px;
+  max-width: 92ch;
+}
+
+.brief-purpose {
+  margin: 0;
+  font-size: 14px;
+  line-height: 1.5;
+}
+
+.brief-changes {
+  margin: 8px 0 0;
+  padding-left: 18px;
+  font-size: 13px;
+  line-height: 1.5;
+  color: var(--ink-muted);
+}
+
+.brief-subsystems,
+.brief-issues {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  margin-top: 10px;
+}
+
+.brief-chip,
+.brief-issue {
+  padding: 2px 8px;
+  border: 1px solid var(--line);
+  border-radius: var(--radius-sm);
+  font-family: var(--font-mono);
+  font-size: 11px;
+  color: var(--ink-muted);
+}
+
+.brief-issue {
+  border-color: var(--accent);
+  color: var(--accent);
+  text-decoration: none;
+}

package/skills/migrate/README.md

@@ -0,0 +1,194 @@
+# migrate
+
+Source-agnostic legacy migration mapping. `migrate` walks a legacy codebase
+through probe, enumerate, seam, extract, parity, and queue, building an
+auditable requirements ledger with mandatory citations instead of a
+self-reported one. It enumerates the legacy surface from two independent
+directions per lens, derives a capability seam empirically rather than by
+guesswork, extracts cited functional requirements, plans parity against the
+source, and routes every ambiguity to a batch decision queue for a human to
+adjudicate. The coverage arithmetic, citation resolution, and phase ordering
+are enforced by a bundled Bun CLI instead of being self-reported. Two more
+phases, adjudicate and handoff, complete the walkthrough but ship no CLI verb
+yet; see the phases table below.
+
+## Using it
+
+Invoke `/migrate` in a target repo that is a git working copy, pointed at a
+read-only checkout of the legacy source. The skill (`SKILL.md`) is the
+walkthrough: it names, phase by phase, what to read, what to dispatch, and
+what `migrate` command closes that phase out. Each phase's manual under
+`references/phases/` carries the actual judgment calls, loaded only when
+that phase is current so a run never pays for prose it does not need yet.
+
+### The phases
+
+| # | Phase | Manual | What it produces |
+|---|---|---|---|
+| 0 | Probe | `references/phases/probe.md` | `.migrate/config.toml` (detected source stack, basis, target profile) and `.migrate/parity-basis.md` (the detection evidence, hand-written) |
+| 1 | Enumerate | `references/phases/enumerate.md` | `elements.jsonl` and a lens census record per surface |
+| 2 | Seam | `references/phases/seam.md` | `capabilities.jsonl`, `seam.json`, `seam.md`: the capability partition and its evidence |
+| 3 | Extract | `references/phases/extract.md` | `requirements.jsonl`, attribute/rule-sweep/closer census records, terminal element dispositions |
+| 4 | Parity | `references/phases/parity.md` | `deltas.jsonl` and a parity plan on every non-queued requirement |
+| 5 | Queue | `references/phases/queue.md` | Queue items carrying evidence, options and a recommendation for anything ambiguous |
+| 6 | Adjudicate | none yet | No verb ships in this version; `migrate status` and `migrate queue list` are the terminus |
+| 7 | Handoff | none yet | Same as adjudicate: no verb yet |
+
+A run in this version stops at the queue. `adjudicate` and `handoff` have no
+CLI verbs to complete them, so `migrate check --phase queue` is the
+practical terminus: its exit 0 is what "done, for now" means. Plain `migrate
+check` gates every phase through `handoff` and cannot pass yet for the same
+reason. `references/run-ops.md` covers what applies across every phase
+rather than any one of them: subagent dispatch, the batch-checkpoint
+discipline, and what happens when two agents contend for the store lock.
+
+### Recipes
+
+Enumerate reads the source stack `probe` detected and looks for a matching
+file in `references/recipes/`, one file per stack family
+(`references/recipes/aspnet.md` covers `aspnet-webforms`, `aspnet-mvc`, and
+`aspnet-webapi`). A recipe answers one narrow question: for each declared
+surface type, at least two independent directions for enumerating it and the
+probe command that realises each one. Nothing else; the lens contract itself
+lives once in `enumerate.md`, and a recipe does not restate it, carry
+classification rules, or gate anything.
+
+If no file matches the detected stack, that is contract-only mode: a
+supported path, not a degraded one. The enumerating agent derives its own two
+directions per surface, and the census gates them exactly as it would a
+recipe's.
+
+**Adding a stack is one new file in `references/recipes/` and no edit
+anywhere else.** `SKILL.md`, the phase manuals, and the CLI never name an
+individual stack; they only read `[source].stack` and look in that
+directory. See `references/recipes/README.md` for the exact file shape.
+
+## Checking as you go
+
+```
+migrate check --phase <current-phase>
+```
+
+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`. Citations are checked by
+default; pass `--no-citations` to skip that gate.
+
+## Fixtures
+
+Two fixtures, each with a committed `GROUND-TRUTH.md`, drive the skill end to
+end:
+
+- **`fixtures/tiny-express/`**: a small Express/Node app, twelve elements
+  across all eight default surfaces. Its stack (`express`) matches no file
+  in `references/recipes/`, so it proves the contract-only path: enumerate
+  deriving its own two directions per surface with no recipe to lean on, and
+  the census gating them exactly the same as it would a recipe's.
+- **`fixtures/tiny-webforms/`**: a small ASP.NET Web Forms app, sixteen
+  elements across the same eight surfaces. Its stack (`aspnet-webforms`)
+  matches `references/recipes/aspnet.md`, so it is that recipe's first run
+  against committed code, not just the throwaway trees it was written
+  against.
+
+`scripts/__tests__/e2e-express.test.ts` and
+`scripts/__tests__/e2e-webforms.test.ts` copy the respective fixture to a
+temp directory and drive the real CLI as a subprocess, probe through queue,
+through `init`, `import`, `census`, `phase`, `queue add`, `queue list`, and
+`check`, reconciling every row against the fixture's ground truth. Both end at
+`migrate check --phase queue` on exit 0, and then show plain `migrate check`
+failing on exactly `adjudicate` and `handoff`, the two phases with no verb in
+this version.
+
+Both show gates in both directions. Failing before they pass: the mid-run check
+after enumerate names the three closer records extract has not written yet, and
+the `deltas` gate names the sanctioned difference each run files unsigned
+before an owner signs it. Failing after they pass: each run closes green, then
+mutates the store (nulling every parity plan, then removing an element row) and
+asserts the gate that should catch it does.
+
+## Documentation
+
+- **[docs/reference.md](docs/reference.md)** is what you need to drive the CLI:
+  the batch-file and census formats with worked examples, the row schemas and
+  their grammars, what each of the ten gates enforces, and the exit-code
+  convention. Ships with the installed skill.
+- **[docs/architecture.md](docs/architecture.md)** is for working on the skill
+  itself: the module map, the rule that decides what belongs in the CLI rather
+  than the prompt, how to add a gate or a surface type, the testing
+  conventions, and the known limits.
+
+## Store layout
+
+The store lives at `.migrate/` in the target repo and is committed.
+
+| Path | Shape | Holds |
+|---|---|---|
+| `.migrate/config.toml` | declarative | source pointer and scope, detected source stack, target profile, surface-type set, closer set, handoff adapter |
+| `.migrate/elements.jsonl` | rows | surface ledger |
+| `.migrate/requirements.jsonl` | rows | functional requirements and their dispositions |
+| `.migrate/capabilities.jsonl` | rows | the seam partition |
+| `.migrate/seam.json` | object | run-level seam metadata: validators run, modularity, status |
+| `.migrate/deltas.jsonl` | rows | sanctioned delta catalog |
+| `.migrate/census.jsonl` | rows | one accounting record per lens run |
+| `.migrate/phases.json` | object | per-phase status, batches, resume pointers |
+| `.migrate/seam.md` | prose | validator scripts and their raw output |
+| `.migrate/parity-basis.md` | prose | runnable-versus-source-only detection evidence |
+| `.migrate/queue/q-<slug>.md` | prose | evidence, options, recommendation |
+| `.migrate/.env` | secrets | runtime-lens credentials, gitignored |
+| `docs/migrate/*.md` | generated | human-readable views, written by `migrate report` |
+
+## CLI
+
+| Command | Does |
+|---|---|
+| `migrate init --source <path> --scope <text> --name <target>` | Writes `.migrate/config.toml` |
+| `migrate import <elements\|reqs\|deltas> <batch.json>` | Validated bulk append to the store |
+| `migrate census <record.json>` | Records a lens accounting record |
+| `migrate phase [<name>] [--status <s>]` | Prints phase state, or sets one phase's status to any value you name |
+| `migrate queue add <file.md>` | Adds a queue item |
+| `migrate queue list [--open]` | Lists queue items, severity first |
+| `migrate queue show <id>` | Prints one queue item |
+| `migrate check [--phase <p>] [--no-citations] [--leaks]` | Runs the gates |
+| `migrate status` | Phase state, counts, resume pointer |
+| `migrate reset --phase <phase>` | Clears one phase's derived rows and returns it to `pending` |
+| `migrate report [--out <dir>]` | Renders markdown views |
+
+Run `migrate --help` for the same list from the CLI itself.
+
+**Four commands write a phase's status, each to a different extent.** `phase
+--status <s>` is the only one that writes any value you ask for, and the only
+one whose whole purpose is that write. `reset --phase <p>` also writes it
+directly, but only ever to `pending`, and it empties that phase's `batches`
+list at the same time. `import` and `census` touch `phases.json` incidentally,
+each moving a phase to `running` (unless it is already `done`) when they record
+a batch. Nothing else writes it at all.
+
+A lock failure on `import`, `census`, `phase --status`, or `reset` exits `3`;
+pass `--force-unlock` once you have confirmed no other agent is actually
+writing.
+
+## Install
+
+```
+bunx @iceinvein/agent-skills install migrate -g
+```
+
+This skill ships in two parts: the prompt (`SKILL.md`) and a companion Bun
+CLI (`bin` + `scripts`). The agent-skills installer writes both into
+`~/.claude/skills/migrate/` and then runs the bundled `install.sh` as a
+postinstall step, which symlinks `bin/migrate` onto your PATH (preferring
+`/usr/local/bin`, falling back to `~/.local/bin`). Removing the skill with
+`agent-skills remove migrate -g` runs `uninstall.sh` first to undo the PATH
+symlink.
+
+If you cloned this repo and want to run from source, you can also invoke
+`./install.sh` directly: it does the PATH-link step against the local source
+tree.
+
+## Development
+
+```
+bun test              # Run all tests
+bun run lint          # Biome check
+bun run typecheck     # tsc --noEmit
+```