llms.txt

# inkcheck

> Mechanical QA for ink interactive-fiction stories. Compile checks, bounded systematic branch exploration, runtime-error repro paths, and dead-content review. A standalone CLI with optional CI and MCP integrations. It writes no prose.

inkcheck exists because compiling an ink story only proves the syntax is valid. It does not exercise choice paths or reproduce runtime failures. inkcheck systematically walks the choice graph within explicit limits, reports terminal states and possible dead content, and exits non-zero on failures so it drops into CI.

## AI / ethics boundary

inkcheck itself does not use AI, machine learning, LLMs, or generative models. It does not train on story source, infer prose changes, rewrite text, or send story content to an AI service. Humans, CI systems, and optional AI coding agents can drive inkcheck, but the checking remains deterministic mechanical QA.

The CLI uses a bounded, adaptive exploration portfolio rather than a single traversal order. Complementary passes — DFS in three orderings, a frontier-capped diversity beam, and seeded random walks — run interleaved in deterministic rounds; each round's budget shifts toward passes still producing new findings (with a per-pass floor), and the whole portfolio stops early the moment a systematic pass proves every reachable state visited. Local CLI and one-shot MCP portfolio checks default to `--concurrency auto`: a live 1,024-state systematic pilot stays sequential for cheap, depth-bound, or saturated work and activates up to four bounded lanes only for an open sustained frontier. Pilot work is never replayed, explicit `--concurrency 1` opts out, and reports expose the versioned decision. `--profile` prints a static shape profile with suggested settings; `--auto` applies them (raising depth for statically deep stories, tuning pass weights — explicit flags always win). The random search slice uses `--seed` (default 1), Ink's initial runtime RNG independently uses `--story-seed` (default 1), and the beam is deterministic without a seed, so fixed-source/config/version runs are reproducible; each finding's `foundBy` names the pass that discovered it, and JSON output carries the executed round schedule plus lifetime per-pass telemetry (`passes`: states explored vs granted, marginal first discoveries, dedupe hits, max depth reached, `lastDiscoveryAtState`, beam frontier stats) — the facts needed to judge which pass earned its budget and whether more budget would help. A long gap since a pass's last discovery does not prove it is finished; late discoveries after long dry spells are real. Coverage remains partial whenever the report says traversal was truncated. The default CLI/MCP state budget is 10,000,000 and the maximum accepted budget is 100,000,000; the memory guard (default 85% of the V8 heap) is what makes an ambitious budget safe, since it stops cleanly before an out-of-memory crash rather than the ceiling being the practical limiter. The hosted web checker defaults to and caps at 1,000,000 and passes an explicit one-lane ceiling — larger jobs (up to 100M states) belong on the local CLI.

`--search=shared` opts into an experimental deterministic multi-frontier engine. Deep, novelty, and seeded views share one deduplicated state graph, expand each state at most once, and retain compact parent links for repro paths. JSON pass telemetry includes unique states, peak pending states/bytes, and observed variable-state/rare-transition counts. Portfolio remains the default; variable rarity is measured but does not steer search yet.

`--search=shared-variable` gives 12.5% of shared-frontier selections to uncommon observed variable snapshots and transitions. It is deterministic, mechanical, bounded, and experimental; it does not interpret variable meaning. Benchmark evidence is mixed, so neither shared mode is the default.

## Install / run

- Discover installed schemas/features: `npx -y inkcheck capabilities --json`
- Put approved mechanical story invariants in `inkcheck.yml` assertions; violations include stable IDs and exact indexed replay witnesses. A bounded non-finding is not proof, while `exhaustively_verified` is.
- Inspect a project without compiling/exploring: `npx -y inkcheck inspect story/main.ink --json`
- Machine reports: schema v1 with stable finding IDs, normalized kinds, story fingerprint, effective configuration, binding limit, and indexed replay witnesses
- CLI: `npx -y inkcheck <story.ink>`
- CLI machine output: `npx -y inkcheck <story.ink> --json`
- Save a source-bound local report: `npx -y inkcheck <story.ink> --save-report --json`
- Reopen saved evidence by stable ID: `npx -y inkcheck artifacts show <report-id> --json` and require `artifact.freshness == "current"` before treating it as current evidence
- Page privacy-minimal saved findings: `npx -y inkcheck artifacts findings <report-id> --limit 20 --json`; follow `page.nextCursor` without loading the full report
- Fetch or replay one stable finding: `npx -y inkcheck artifacts finding <report-id> <finding-id> --json` or `npx -y inkcheck artifacts replay <report-id> <finding-id> --json`; replay fails unless source freshness is current
- Report storage is capped at 256 MiB per report and 1 GiB per project. Preview cleanup with `artifacts delete <id> --json` or `artifacts prune --keep N --json`; add `--apply` only after reviewing the deterministic, at-most-100-report selection.
- Save an unfinished exact local frontier: `npx -y inkcheck story.ink --search=shared --no-min-repro --max-states 100000 --save-checkpoint --json`
- Resume it to a larger total grant: `npx -y inkcheck resume <checkpoint-id> --max-states 1000000 --json`; require current freshness and treat checkpoint files as sensitive story data.
- MCP long jobs use `start_search` then `inspect_search` / `continue_search` with the returned bearer capability and revision. Each synchronous window adds at most 5M states; `cancel_search` acts between windows and retains exact recoverability unless `discard: true`.
- Policy-bound MCP jobs use `start_campaign` then `inspect_search` / `continue_campaign`. Prefer `mode: balanced` for a fresh agent; quick/deep/overnight/campaign/fixed modes and bounded overrides are versioned and replayable. `campaign.decision` exposes policy attribution, preferred-yield forecast, uncertainty, constraints, and a report ID for drill-down. Jobs persist aggregate state/time/deadline/memory/disk limits over one shared frontier; they do not yet run concurrent or independent strategy children, and knee estimates never imply coverage proof.
- `add_goal` spends up to 5M explicit additional states on one safe typed goal from the story root. It leaves the exact base report/checkpoint untouched and reports base, directed, and total campaign budgets separately; it is not resumed-frontier reprioritization.
- Human fix list: `npx -y inkcheck <story.ink> --human`
- Human-readable CI output: `npx -y inkcheck <story.ink> --markdown`
- CI: `npx -y inkcheck story/main.ink --strict`
- Broader bounded check: `npx -y inkcheck story/main.ink --max-states 100000000` (paired with the memory guard; raise --max-old-space-size for headroom)
- Skip BFS repro shortening: `npx -y inkcheck story/main.ink --no-min-repro`
- Different random sample: `npx -y inkcheck story/main.ink --seed 2`
- Experimental shared-state search: `npx -y inkcheck story/main.ink --search=shared`
- Experimental variable-aware search: `npx -y inkcheck story/main.ink --search=shared-variable`
- Show story shape + suggested settings: `npx -y inkcheck story/main.ink --profile`
- Apply the shape profile (depth + pass weights): `npx -y inkcheck story/main.ink --auto`
- Auto-escalate limits until nothing new is found: `npx -y inkcheck story/main.ink --next`
- Cap memory (default 85% of V8 heap limit): `npx -y inkcheck story/main.ink --max-memory 2048`
- Cap wall-clock time, return a partial report at the deadline: `npx -y inkcheck story/main.ink --max-time 60`
- MCP (Claude Code): `claude mcp add inkcheck -- npx -y inkcheck mcp`
- MCP config: `{ "mcpServers": { "inkcheck": { "command": "npx", "args": ["-y", "inkcheck", "mcp"] } } }`
- Self-hosted web service: `inkcheck-web` or `npm run web` (temporary upload; local CLI remains private by default)

## Exit codes

- 0: clean
- 1: compile errors, runtime errors, or (under --strict) warnings, unvisited knots, truncation, or external stubs
- 2: usage error

## MCP tools

- `inkcheck_capabilities`: versioned schemas, limits, modes, and explicit feature availability
- `inspect_story`: bounded source-only project map; recommended first call in an unfamiliar repository

- compile_story — structured compile issues (severity, file, line)
- story_stats — word/knot/choice counts + full knot list with locations
- playtest_story — play one indexed choice path headlessly; transcript, tags, variables, errors, and replay status (`completed`, `runtime_error`, or `path_changed`)
- explore_story — bounded systematic walk: terminal states, error repro paths, knot coverage, and explicit limitations
- start_search — start one durable exact base-shared result window (1M default) and return a bearer capability
- start_campaign — resolve a named or fixed durable policy and execute its first exact shared result window
- continue_campaign — execute the next exact window with measured spend, preferred yield, forecast uncertainty, decision reason, and provenance
- inspect_search — bounded session status and privacy-minimal saved finding summaries; no full report/frontier
- continue_search — continue the exact frontier to a larger cumulative grant, adding at most 5M per call
- add_goal — run one safe typed or staged goal as an explicit additive root-started probe without mutating the exact base frontier
- cancel_search — cancel between synchronous windows; retained by default, explicitly forget with `discard: true`
- replay_witness — explicitly execute one stable latest-report finding against current source; returns transcript/choices/variables, advances revision, and keeps only opaque audit metadata
- pin_regression — preserve one confirmed current runtime failure as a private idempotent pin; runtime errors only in this first slice
- check_regression — after editing, classify a pin as fixed, still_failing, or path_changed without spending search states

## Intended agent loop

Use the bundled `skills/inkcheck/SKILL.md`. Start with `inkcheck_capabilities`, then call `inspect_story` once, `compile_story`, and `start_search`. Inspect bounded finding summaries, fetch and replay one stable finding, make only an unambiguous mechanical edit, then recompile and verify with the same source/config/seeds. Prefer result-window sessions over loading the full `explore_story` report. Treat inkcheck as deterministic bounded mechanical QA, not a completeness or author-intent oracle.

For coverage escalation, every explore report includes `nextRun`: a deterministic verdict from the closed set stop / deepen / broaden / reseed / investigate, with ready-to-use `flags`, a `rationale` citing the report fields that drove it, and `stop: true` when rerunning has no evidence behind it. Loop on it (rerun with `nextRun.flags` until `stop`), or use CLI `--next` which does the loop itself (max 3 escalations, fixpoint-detected, per-run trail in JSON `runs`).

## What it is not

Not a writing tool, not an authoring aid, and not an AI system. It generates zero prose. It is pure QA for the [ink](https://github.com/inkle/ink) language (inkle's scripting language for interactive fiction).

## Coverage limits

- `--max-states` is the total exploration budget across portfolio passes, not a single DFS count.
- Inkcheck is systematic and reproducible inside its budget when source, limits, versions, and both seeds are fixed. `--seed` controls the random-sampling search slice; `--story-seed` independently controls Ink's initial runtime RNG for RANDOM/shuffle behavior and is included in replay instructions. Change the former to sample different choice walks or the latter to exercise another story-randomness sequence. External random sampling can still be complementary for very large or random-heavy stories.
- The beam pass caps its frontier at a fixed width and marks the run truncated whenever it prunes a reachable state, so bounded memory never turns into a silent completeness claim.
- Truncation means the report is partial; strict mode fails. `truncatedBy` in JSON names the limit that cut coverage (maxDepth, maxStates, the beam frontier cap, or memory) so tooling can raise the right flag.
- A run that would run out of memory stops cleanly before the (uncatchable) V8 OOM and returns a partial report with `truncatedBy.memory`; the cap defaults to 85% of the V8 heap limit and is overridable with `--max-memory <mb>`. On a memory stop, `nextRun` recommends `investigate` (raise --max-old-space-size or lower --max-states), never `broaden`.
- `--max-time <s>` sets a wall-clock budget: the run stops cleanly at the deadline and returns a partial report with `truncatedBy.time` instead of running to the state budget. No default limit on the CLI; the hosted checker sets it automatically just under its hard timeout so a slow story returns a partial report rather than being killed. On a time stop, `nextRun` also recommends `investigate` (raise --max-time or use the local CLI), never `broaden`.
- `exhaustive: true` means a systematic pass visited every reachable state without hitting a limit; sampling-slice budget exhaustion does not count as truncation in that case.
- Unvisited knots carry `inboundDiverts` and `staticOrphanCandidate` triage hints: no authored divert found = possible orphan; inbound diverts present = likely cut off by this run's limits.
- EXTERNAL functions are stubbed to zero and named in the report; strict mode fails.
- Random behavior is detected and replayable for the reported story seed, but every possible story seed is not enumerated.
- Unvisited knots are review prompts, not automatic proof that content should be deleted.
- Hosted checks accept only authorized `.ink` files, validate INCLUDE paths, enforce stricter limits, and delete each temporary job after its response.

## Links

- Repo: https://github.com/chaoz23/inkcheck
- Package: https://www.npmjs.com/package/inkcheck
- ink language: https://github.com/inkle/ink
- License: MIT