factoidal

Run and interpret every test suite in the Factoidal project — W3C conformance (SPARQL 1.1, RDF 1.1/1.2 syntax, rdf-mt, RDF canonicalization, OWL 2), local regression scripts, cross-runtime parity (native/JS/wasm), Apache Jena ARQ comparison probes, running only the suites a diff touches (`tools/affected-tests.sh`), regression-pinning discipline (write the failing test before the fix, confirm it fails for the right reason), and the policy for importing external suites. Use when the user asks to "run the tests", "check conformance", "compare against Jena", to investigate a score change, when landing a bug fix and deciding which regression to write, or before claiming any change is done. Testing (with perf measured separately — see perf-benchmarking) drives everything in this project.

Markdown formatting + prose register for Claude-generated text in this repository — chat replies, design docs, READMEs, PR bodies, commit messages. Two load-bearing rules. (1) Links must be unambiguously clickable — bold/italic emphasis around URLs and link syntax frequently breaks the click target. (2) No sycophantic adjectives — drop "honest", "genuine", "important", "critical", "big picture", "key insight", "headline", and similar candor-performance words. Use whenever generating user-facing markdown that may be rendered in different clients (CLI, web, mobile chat, GitHub).

How Factoidal stores RDF data on disk — the COTTAS/Parquet base file, its 11 sidecars, the durable-UPDATE delta log, the compacted-epoch marker, and the symlink-current versioning layout. Use when asked how data is stored on disk, when adding a new on-disk companion file, when a magic-number/framing question comes up (DLE1/DLB1/DLOG/CEP1/COTD/COTP/COTO/COPO/COTS), when running import/query/compact/serve against a COTTAS store, or when auditing rule

How to write subagent prompts for the Factoidal repo so the agent's work actually lands cleanly. Use whenever you dispatch a subagent with the Agent tool, especially with `isolation: "worktree"`. Two load-bearing rules. (1) Path discipline — agents must use only paths under their worktree, not absolute paths from your prompt context. (2) Post-condition checks — agent must verify its main-worktree footprint is zero before reporting back. Also carries MANDATORY brief inclusions for build-list edits (only while `.build-running` is absent), the F*/OCaml comment-nesting trap, and iron rule #11 (no hand-editing extracted `.ml`) — plus the one-agent-one-commit and ship-code-sketches rules. Pairs with workflow-gotchas-debugging (which catalogues recovery steps when these rules are violated).

Set up or repair the F* / opam / z3 toolchain for the Factoidal project. Use when the user asks to install or set up F*, when `fstar.exe` is missing from PATH, when z3 has the wrong version (must be 4.13.3), when `make verify` or `build-ocaml.sh` fails with toolchain errors, when starting on a fresh clone that hasn't been bootstrapped, or when an agent has been "burning time on partial builds" because the opam switch isn't activated.

Restore a fresh or recycled VM/container/session to full working state in minutes, not hours — the cache inventory (toolchain-cache branch, .checked verification cache, pycottas venv, skill symlinks), what the bootstrap hook restores automatically vs what needs a command, the wasm_of_ocaml/binaryen ≥116 install path (proxy-blocked release binaries, conda-forge fallback), and the never-again rules from the 2026-07-03 session that burned ~90 minutes compiling F* from source twice. Use on any fresh clone, restored VM, new sandbox, when fstar.exe or test data is missing, when a wasm build fails on a missing `wasm-merge`, when a session is about to do something expensive that a previous session already did, or when adding a new cache-worthy artifact.

Post-feature-landing sweep for statements the landing just made false — stale "not yet / out of scope / parked / later stage" claims in docs, hub notebooks, skills, .fst header comments, test-suite yamls, the ledger, and dashboard prose. Use IMMEDIATELY AFTER landing any feature, capability, or score change; when writing any "we don't have X / can't do X" sentence (verify against the tree first — negative claims rot fastest); or when a reader reports prose contradicting behavior. Ships tools/obsolescence-sweep.sh, the stale-claim lexicon, the target-surface list, and the 2026-07-10 war stories (VC "crypto is a later stage", "Protocol/GSP parked", ShExC "out of scope indefinitely" — all asserted from stale text while the features sat in the tree).

How Factoidal's F* source is organized and written — the semantic-core vs implementation-pragmatics split, module naming, the planned stratification of RDF.Graph.Executable and SPARQL11.Algebra, interface-file (.fsti) policy, verification requirements (no --lax, no --admit_smt_queries, z3 4.13.3), F* syntax traps (comment nesting, reserved words), extraction-semantics traps (F*-verified totality is NOT OCaml totality — List.Tot.splitAt, split-brained string primitives, fixed fuel constants, accumulator order), and KaRaMeL-compatible style. Use when creating or reorganizing .fst modules, when an F* "Syntax error" makes no sense, when a function that verifies as Tot crashes at runtime after extraction, when deciding where a definition belongs, or when writing F* that should later extract to C.

Work efficiently in a fresh Factoidal session — what the bootstrap hook already set up, token prudence (targeted reads and suite runs instead of shotguns), model and effort selection for subagents, context minimalism, and how to pick the next piece of work toward the project goal. Use at the start of an autonomous session, when planning subagent fan-outs, when a session is burning tokens re-deriving known state, or when deciding what to work on next.

Update and publish the Factoidal website, test-results dashboard, demo pages, and the Fly.io SPARQL endpoint — and keep every progress/score table in the repo in sync with measured reality. Use when the user asks to "update the site", "refresh the dashboard", "publish the demo", "deploy", or when README/current-state/scorecard numbers have drifted from docs/test-results/latest.json. Stale public numbers are treated as bugs.

How Factoidal's Verifiable-Credentials crypto (VC Data Integrity, eddsa-rdfc-2022) runs OFF the native binary — in Node and the browser — by realising VC.DataIntegrity.fst's four crypto assume vals with HACL*'s official WebAssembly build. Use when VC verify/sign must work without a native binary, when a js_of_ocaml/wasm_of_ocaml build crashes inside a digest/signature primitive, when wiring or landing the hacl-wasm stubs, when adding a new crypto assume val that must reach the browser, or when auditing the crypto provenance/licence chain. Pairs with crypto-policy (the sourcing rule) — this is the concrete build.

The verified-library boundary — what OCaml is allowed to exist, the assume-val glue taxonomy, patch directories and their lifecycle, companion-file byte-layout rules, third-party vendoring policy, and the extraction targets (OCaml native, js_of_ocaml, wasm_of_ocaml, KaRaMeL C). Use when adding or reviewing any hand-written OCaml, when a patch in experimental_ocaml_glue or minimal_regrettable_glue is involved, when realising a new assume val, when writing a companion-file writer, or when someone proposes "just do it in OCaml for now". That proposal is how the project nearly lost its verification story once.

Measure, record, and gate Factoidal performance — parser throughput benchmarks, UK Parliament query bench, query observability (Server-Timing, /admin/recent.json, --explain), profiling policy, and the history of why things were slow. Use when the user asks "is it faster", "benchmark the parser", "why is this query slow", before claiming any speed win, or when a perf number in docs looks stale. Speed is measured separately from correctness; never claim a perf improvement inside a compliance change without its own measurement.

The project's cryptography sourcing policy — never write our own crypto primitives; adopt HACL* (the F*/Low*-verified library Mozilla ships inside NSS) to realize the hash/signature assume vals, in a fixed adoption order with a hard wasm compatibility gate. Use when touching any hash/signature/UUID assume val, when implementing VC Data Integrity proofs, when a wasm build crashes inside a digest function, or when someone proposes adding a crypto dependency.

Diagnostic playbook for the dev-loop hazards that recur in this repo. Use when a build mysteriously fails, a fresh clone breaks where local works, an agent's work doesn't appear on its branch, the same uncommitted file keeps coming back after `git checkout`, a secondary compile script poisons shared `.cmi`/`.cmx` files, a `set -e` + cleanup trap eats a failing build's log, or "stop hook fires every turn but I'm not done." Twelve hazards total (see "Lessons from 2026-05-07" below): subagent worktree-leakage, concurrent F* extract races, source-without-build-wiring, stale doc numbers, the build-aware stop-hook gap, the `(* *)` comment trap, worktree garbage, secondary-script `.cmx` poisoning, editing build inputs mid-build, cleanup traps eating diagnostics, old-base cherry-picks silently dropping build-list/consumer entries, and stale js/npm bundles failing hub cells — plus their detection + recovery steps.

Check a SKOS vocabulary against the SKOS Reference (W3C Rec. 18 Aug 2009) integrity conditions using this project's own engines — the SHACL validator (98 pass, 0 fail on the W3C core suite), SPARQL 1.1 with property paths (631 pass, 0 fail), and the generic OWL 2 RL closure. Use when asked to validate a SKOS taxonomy or thesaurus, when auditing skos:prefLabel/altLabel/hiddenLabel usage, skos:broader/narrower/related consistency, or mapping-property (exactMatch/broadMatch/narrowMatch/relatedMatch) clashes, or when the user references SKOS "integrity conditions" / S-numbers from the Reference. A prose skill rather than an F* module by design — the checks mix shapes, SPARQL, and axiom data rather than new engine logic.

Calculate the token cost of an agent session INCLUDING all its subagent children, using agentsview (uvx agentsview). Use when the owner asks "what has this session cost", "how much did last night cost", when planning subagent fan-outs against a budget, or when writing a retrospective that should carry real spend numbers. The one-liner is tools/session-cost.sh; this doc records the working recipe and the traps (main-only usage under-counts by ~40%, sync first, JSON key names).

Use the GitHub CLI (gh) for the Factoidal repository's PR / issue / branch workflow. Use when the user asks to create / view / merge a PR, list branches, audit stale branches, comment on an issue, or anything involving gh commands. The Factoidal repo's git remote uses a local proxy that confuses gh's repo inference, so all commands need an explicit --repo flag.

Commit-message attribution policy for this repository — do NOT list Claude's role in GitHub commits. No Co-Authored-By Claude trailers, no "Generated with Claude Code" lines, no Claude-Session links, no prose crediting Claude in commit messages. Use whenever writing a git commit in this repo, and when configuring or reviewing any tool/harness that appends attribution trailers automatically.

Make the F* verify + OCaml extract + compile + test loop fast via .checked caching, targeted single-module rebuilds, and safe parallelism. Use when an edit-verify-extract cycle feels slow, when deciding whether to run a full ./build-ocaml.sh vs a targeted rebuild, when wiring caches into CI or the session container, or before dispatching parallel verification work. Every claim below is marked CONFIRMED (seen in --help output, script source, or measured here) or PROPOSED (not yet verified in this repo).

Discipline for long-running autonomous work — always make use of wall-clock time. Use when running multi-hour sessions, kicking long builds in the background, waiting on system notifications, or when you suspect a background job has stalled. Codifies the silent-stall failure mode (background job dies, no notification arrives, you sit waiting) and the timers/loops/monitors/callbacks toolkit that prevents it.

Build, extract, compile, and test the Factoidal F* project. Use when the user asks to "run the tests", "verify F*", "build the binary", "extract OCaml", "build for JS/WASM", or wants to know how to invoke the W3C test runner. Also use when troubleshooting build-ocaml.sh, ocaml-patches.sh, or test-runner output.

How to pick the model AND the effort dial (low/medium/high/xhigh/max) for every subagent you spawn — especially when the orchestrating session runs on a Fable-class (top-tier) model. Covers when a deliberate Fable-class subagent (not accidental inheritance) is the right call. Core rule, from the owner: "For all coding tasks use your judgement to decide an appropriate lower power model and run that in a subagent." Use whenever dispatching an Agent, planning a fan-out, writing a Workflow, or when a session is burning top-tier tokens on work a cheaper model executes reliably.

Build a source-mapped, pretty-printed js_of_ocaml bundle and wire it into the public demo so a browser-only crash gives a real OCaml stack trace. Use when a query works under the native binary or under Node but crashes only in the browser (e.g. `BatUChar.Out_of_range`, "use-js-string=true" UTF-16 mismatches), when a minified `factoidal.js` stack trace shows opaque single-letter function names like `aw`/`bb`/`cd`, or when the user asks to "build a debug bundle / get sourcemaps for the JS demo / step through the browser bundle". Pairs with build-and-test (which covers the production js_of_ocaml step) and workflow-gotchas-debugging.

Get oriented in the Factoidal repository layout. Use when starting work on a fresh clone, when asked "where does X live?", or when a doc references a path that's unfamiliar. Maps the dual nature of the project (verified F* spec is the product; everything else is plumbing or build artifacts).

Reference for how MCP servers are wired in the Factoidal repo (today: `fstar-mcp` from FStarLang/fstar-mcp, served over HTTP on http://127.0.0.1:3700). Use when configuring, debugging, restarting, or adding to the project's MCP setup. Covers `.mcp.json`, the session-start bootstrap (`tools/sandbox-bootstrap.sh`), the daemon manager (`tools/fstar-mcp-server.sh`), port assignment via `FSTAR_MCP_PORT`, and why we run HTTP transport instead of stdio. Pairs with the `fstar-mcp` skill (which covers USING the F* MCP for proof / typecheck queries during development).

Use the F* MCP server (FStarLang/fstar-mcp) — a stdio bridge to F*'s --ide protocol — to query proof context, type-check expressions, and tune fuel/ifuel without re-running fstar.exe in batch mode. Use whenever you'd otherwise reach for `fstar.exe X.fst` or `make verify` to chase a single error message; whenever you need the typing context, the assumed hypotheses, or the goal that SMT couldn't discharge at a failure point; whenever you'd guess at fuel/ifuel before re-running. Also use when the user asks "is the F* MCP available", "use fstar-mcp for this", or "interactively check this".

Keep GitHub issues + their checklists / comments in sync with PR landings as work progresses (live tracking) AND run periodic sweeps for drift. Use AS PRs MERGE to tick checklist boxes and post short progress comments — don't batch this until Friday. Run a fuller sweep on Fridays, after a merge cluster, or when user types /issue-hygiene. Tracker is danbri/factoidal#198; migration epic is