Rebuild mod-builder for Claude Code 2.1.287 and later

[karanb192]

Summary

• Rewrites the mod-builder skill (plugin version 1.0.0) for Claude Code 2.1.287 and later: SKILL.md (159 lines) runs a gate, a plan, a shape check against the generated types, a footprint diff, a test seen failing, an isolated proof, a threat model and a fixed handoff; every early-access instruction (the CLAUDE_CODE_ENABLE_FUNCTION_HOOKS flag, /plugin-types, .claude/types) is gone.
• Adds four scripts under skills/mod-builder/scripts/: lib.mjs (find claude, harness home, run, parse validate --json, extract the API map from the types, locate or generate the types with a headless load), gate.mjs (step 0 block; lines that need attention start with !; --json lists them), api-check.mjs (diff the references' fenced api-* blocks and backticked names against the running build's types; --mod lists early-access spellings under eight M.* ids; --write-baseline), prove.mjs (copies the mod, drives a child claude under its own CLAUDE_CONFIG_DIR, stages validate, load, typecheck, test, command, opt-in interactive and install-smoke, isolation; one evidence file per stage, status.txt, run.json, three strikes). footprint.mjs is rewritten: rules move to data/reach-rules.json, env and state lines are parsed and diffed, an unknown method prints ungraded: and exits 1. list-mods.mjs uses process.exitCode so piped JSON is not cut short.
• Adds data/api-map.json (baseline extracted from the 2.1.287 declarations), data/api-assertions.json (13 value-level regexes), data/reach-rules.json, and assets/probe-mod/ (the mod the gate loads to make the engine write the types).
• Rewrites the references (plan, build, events, nouns, ui-and-state, limits, testing, proof, threat-model, composing, workflows, migrate, sources, invitation) with a stamp on each restated fact; deletes gotchas.md, official-sources.md, reading.md, templates.md. The star invitation moves from SKILL.md to references/invitation.md; scripts/star-invitation.mjs is unchanged.
• Adds tests/scripts.test.mjs and tests/helpers.mjs (a config-driven stub claude): 74 tests, offline plus a live section that skips with a printed line when no claude at or above 2.1.287 is on PATH; new .github/workflows/mod-builder.yml runs them.
• Repo: plugins/fable-pin/tsconfig.json becomes { "extends": "./.claude-plugin/types/tsconfig.json" }; root .gitignore and plugins/image-peek/.gitignore ignore .claude-plugin/types/; root README.md, .claude-plugin/marketplace.json and the site/index.html mod-builder card describe the new pipeline.

Details

Why the rewrite. An audit against the 2.1.287 docs found 19 verified errors in the previous skill text, all from the early-access build it was written on (the flag, /plugin-types, "nothing draws on Desktop", stale result shapes). The new text restates only decision facts, process facts and limits, each with [src | checked <build> | recheck: <trigger>]; shapes are never restated, the references give the grep into <types>/claude-code/index.d.ts.

Staying correct across releases. No patch version is pinned in prose (the floor 2.1.287 appears in lib.mjs and once in SKILL.md). api-check.mjs extracts events, methods, nouns, components, surfaces, elements, invalidatable events, tiers, budget and tools from the live types, diffs them against data/api-map.json, and reports STALE names in the references, SHAPE DRIFT on the assertions, and +/- names since the baseline. On the installed 2.1.288 it reports + ui.selection (op event), + $.ui.selection (method), 0 stale, 2 uncovered, 0 shape drift.

Proof. prove.mjs writes the status block (ran and passed, ran and FAILED (...), not applicable (...), unverified (...)); the skill pastes it and may add nothing. The load stage passes only on the documented hooks module <name>@inline loaded line; the observed lines (settled in, $.<noun>.<verb> (<name>), [<name>] $.ui.log, type root of) are extra evidence and sit in one table with the build they were seen on. The isolation stage checks the loaded lines' provenance, the real ~/.claude.json and settings.json, the ~/.claude/projects listing and the source hashes. references/proof.md ends with the block from a real run on assets/probe-mod.

Review before this PR was finalised. Three fact-checkers read 486 claims against the 2.1.288 types and the docs; 45 confirmed errors (none high after a skeptic pass) are fixed in the second commit. Three fresh agents built branch-guard, turn-meter and read-log from the skill text alone; each passed validate, load, typecheck and test with tests seen failing, and their friction notes drove the routing and wording changes (one plan block, references per step, the ! markers on the gate, the login hint naming only the interactive stage).

Measured on this machine (2.1.288). claude -p loads a --plugin-dir mod, fires session.start, writes the types and answers a registered /command before the login check, so only the interactive stage needs a login. The debug log records loads and most $ calls, but not $.state or $.env.get calls. claude plugin init scaffolds a classic-hook plugin, not a mod. Bare npx tsc installs an unrelated package. A /** @jsx h */ pragma is harmless; a foreign factory silently retargets JSX and hides <Client> modules from validate.

Listing surfaces touched: README.md, .claude-plugin/marketplace.json, site/index.html (mod-builder card and nothing else), plugins/mod-builder/README.md.

Test plan

• node --test 'plugins/mod-builder/skills/mod-builder/tests/*.test.mjs' from the repo root: 74 pass (71 pass, 3 skipped without MOD_BUILDER_SNAPSHOT=<path to the 2.1.287 d.ts>).
• node plugins/mod-builder/skills/mod-builder/scripts/gate.mjs prints verdict: proceed (exit 0), references: usable (0 stale, 2 uncovered: ui.selection, $.ui.selection) on 2.1.288, and a ! only on the harness line when not logged in.
• node plugins/mod-builder/skills/mod-builder/scripts/prove.mjs plugins/mod-builder/skills/mod-builder/assets/probe-mod --plan '$.command.register,$.env.get,$.state.get,$.state.set,$.ui.log' --env MOD_BUILDER_PROBE --state probe-mod.runs: validate, load, typecheck, test, command and isolation read ran and passed; the source tree is unchanged after the run.
• node .../scripts/prove.mjs plugins/fable-pin: typecheck passes against the new extends tsconfig.
• claude plugin validate --strict plugins/mod-builder passes.
• CI: the mod-builder scripts job passes on the PR; Invitation tests still passes.
• After merge: the Pages deploy publishes site/index.html; check the mod-builder card on https://claude-code-mods.karanbansal.in/ reads "proves the result in an isolated run".