Add production-readiness execution pack (work orders + fleet runner) (#36)

Adds `.claude/tasks/prod-readiness/` — 15 self-contained work orders
from the 2026-07-10 ten-dimension audit, each runnable by a fresh Claude
session with **per-task Opus/Sonnet/Haiku routing** — plus
`.claude/workflows/prod-readiness.js`, a fleet runner that routes each
task to its model and runs implement → adversarial-verify → open-PR.

### Contents
- **Wave 1** (basic functioning): W1-1 neural-boundary guardrail
(**P0**), W1-2 degenerate-input guards, W1-3 router coverage, W1-6 zig
FFI, W1-7 agda proofs. *(W1-4/#34, W1-5/#35, hygiene/#33 already merged
— marked done.)*
- **Wave 2** (beyond): release (Registrator+TagBot+SBOM), buildable
guix, runnable containers, experimental reframe, extended reference
validation, structured logging, prompt-injection delimiting, polish
sweep.

### Why
The wave-1 fleet completed setup (Julia 1.10.11 / Zig 0.16 / Agda
2.6.4.3 in WSL, baseline 4404 tests green) and landed 3 PRs, but hit a
monthly spend limit before the other 5 packages pushed. This pack
captures every remaining item as durable, context-free briefs so any
session (or a re-run of the fleet) can execute them — carrying the
user's decisions of record and verified toolchain facts.

Docs/config only; no code or CI behavior changes.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

.claude/tasks/prod-readiness/README.md

@@ -0,0 +1,110 @@
+<!--
+SPDX-License-Identifier: MPL-2.0
+Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+-->
+# Production-Readiness — Execution Pack
+
+Self-contained work orders from the 2026-07-10 ten-dimension production-readiness
+audit of statistikles. Each file is a standalone brief runnable by a fresh Claude
+session with **no dependency on the originating conversation**, with a recommended
+model (**Opus / Sonnet / Haiku**) for implementation and for adversarial verification.
+
+- **Wave 1** = "basically running & functioning acceptably" (the P0 guarantee + the
+  crash/robustness/coverage/install fixes). Do these **first**.
+- **Wave 2** = everything beyond that (release engineering, packaging, honesty
+  reframes, deeper test coverage, observability, polish).
+
+Package 8 of wave 1 (hygiene/security-templates) is **already merged** (PR #33).
+Everything else below is open work.
+
+## How to run
+
+**One task, any session:**
+> "Execute the work order in `.claude/tasks/prod-readiness/w1-1-neural-guardrail.md`.
+>  Use the model it names; follow the execution contract in the README."
+
+**A whole wave as a fleet (Claude Code, budget permitting):**
+> `Workflow({ name: "prod-readiness" })` — the runner reads this folder, routes each
+>  task to its model, and does implement → adversarial-verify → open-PR. See
+>  `.claude/workflows/prod-readiness.js`.
+
+## Model routing
+
+### Wave 1 — basic functioning (do first, in order)
+
+**Status (2026-07-11):** packages 4, 5, and 8 are **MERGED** (PRs #34, #35, #33). The
+five below with a status of OPEN are the remainder — their fleet agents died on a spend
+limit before pushing. Do them next, **W1-1 (P0) first**.
+
+| # | Task | Branch | Impl | Verify | Status |
+|---|------|--------|------|--------|--------|
+| 1 | [Neural boundary guardrail (**P0**)](w1-1-neural-guardrail.md) | `fix/neural-boundary-guardrail` | **opus** | **opus** | **OPEN** |
+| 2 | [Degenerate-input guards + `@assert`→`ArgumentError`](w1-2-stats-degenerate-inputs.md) | `fix/stats-degenerate-inputs` | sonnet | opus | **OPEN** |
+| 3 | [Table-driven router tests + CI coverage](w1-3-executor-router-coverage.md) | `test/executor-router-coverage` | sonnet | sonnet | **OPEN** |
+| 4 | [Real install path (Justfile, quickstarts, smoke CI)](w1-4-documented-install-path.md) | `fix/documented-install-path` | sonnet | haiku | ✅ #34 |
+| 5 | [Pin compute half + prune Dependabot + threat model](w1-5-supply-chain-pinning.md) | `fix/supply-chain-pinning` | sonnet | sonnet | ✅ #35 |
+| 6 | [Make Zig FFI compile + `zig build test` CI](w1-6-zig-ffi-compiles.md) | `fix/zig-ffi-compiles` | **opus** | sonnet | **OPEN** |
+| 7 | [Type-checking Agda proofs + `agda --safe` CI](w1-7-agda-proofs-ci.md) | `fix/agda-proofs-ci` | **opus** | sonnet | **OPEN** |
+| 8 | Hygiene / security-templates | `chore/hygiene-security-templates` | haiku | haiku | ✅ #33 |
+
+### Wave 2 — beyond basic functioning
+
+| # | Task | Branch | Impl | Verify |
+|---|------|--------|------|--------|
+| 1 | [Release: JuliaRegistrator + TagBot + SBOM](w2-1-release-pipeline.md) | `feat/release-registrator-tagbot` | **opus** | **opus** |
+| 2 | [Buildable guix.scm](w2-2-guix-package.md) | `feat/guix-real-package` | **opus** | sonnet |
+| 3 | [Runnable Containerfile + devcontainer](w2-3-containers.md) | `feat/containers-runnable` | sonnet | sonnet |
+| 4 | [Experimental reframe: FFI + proofs docs](w2-4-experimental-reframe.md) | `docs/experimental-reframe` | sonnet | sonnet |
+| 5 | [Extend ground-truth reference validation](w2-5-reference-validation.md) | `test/reference-validation-extension` | sonnet | **opus** |
+| 6 | [Structured logging + audit trail](w2-6-observability.md) | `feat/structured-observability` | sonnet | sonnet |
+| 7 | [Prompt-injection delimiting](w2-7-prompt-injection.md) | `fix/prompt-injection-delimiting` | sonnet | haiku |
+| 8 | [Polish sweep](w2-8-polish-sweep.md) | `chore/polish-sweep` | haiku | haiku |
+
+**Routing rationale.** Opus for design-sensitive, safety-critical, or niche-toolchain
+work (the guarantee guardrail, release engineering, Guix, Zig/Agda, statistical
+ground-truth). Sonnet for well-specified implementation. Haiku for mechanical sweeps.
+Verification is adversarial — the verifier tries to *refute* the implementation against
+the work order's acceptance criteria — and is deliberately assigned the model that
+should be able to follow the spec: if the verify-model can't confirm it, the spec or
+the code isn't done.
+
+## Decisions of record (user-approved 2026-07-10 — do not relitigate)
+
+1. **Release = JuliaRegistrator + TagBot** (General registry), not artifact-only.
+2. **FFI (Zig/C-ABI) and Agda proofs are EXPERIMENTAL** — make them compile & CI-check
+   (wave 1), reframe docs (wave 2); do NOT invest in the Idris2 ABI or proofs-over-ℝ yet.
+3. **guix.scm gets made real** (buildable), not deleted — governance has a "Guix primary"
+   policy check.
+4. **Merge gate is active**: the Base ruleset requires the "E2E — Julia Test Suite"
+   status check. A PR cannot merge red.
+
+## Verified toolchain facts (WSL Debian, set up 2026-07-10)
+
+- **Julia 1.10.11** via juliaup; on PATH only in a **login shell** (`bash -lc`).
+  Baseline `Pkg.test()` = **4404 tests green** (Full 424 / E2E 145 / Property 3800 /
+  Reference 35). ALWAYS serialize Julia runs: `flock /tmp/statistikles-julia.lock -c '…'`
+  (16 GB RAM ceiling). Warm depot exists; `instantiate+precompile` ≈ 1m46s, test ≈ 36s
+  after precompile.
+- **Zig 0.16.0** tarball at `/home/hyperpolymath/zig/zig-x86_64-linux-0.16.0/zig`
+  (also `~/.local/bin/zig` in login shells). ⚠ 0.15+/0.16 has breaking std changes
+  (Io writer/reader redesign) — if the repo's Zig targets ≤0.14, fetch an older
+  tarball into the same dir.
+- **Agda 2.6.4.3 + agda-stdlib 2.1** (apt); stdlib wired via `~/.agda/libraries` +
+  `~/.agda/defaults`. ⚠ stdlib 2.1 renamed some modules vs 1.x — expect import tweaks.
+
+## Execution contract (every task)
+
+- Branch from up-to-date `origin/main` using the named branch. If a wave-1 prerequisite
+  is unmerged and you touch the same files, branch from that branch and say so in the PR.
+- Commits SSH-signed (environment is pre-configured). End messages with the
+  `Co-Authored-By` trailer for your model.
+- Run the work order's **Local verification** before pushing; on 16 GB RAM, wrap Julia
+  in `flock /tmp/statistikles-julia.lock`. Never claim verification you didn't run.
+- Diffs surgical; match surrounding style. GitHub Actions **SHA-pinned** with a version
+  comment. Never job-level `hashFiles()`/`secrets` conditionals (silent startup_failure)
+  — step-level only.
+- **Do not open GitHub issues** and **do not merge/delete/force-push.** Open exactly one
+  PR to `main` per task, titled per the work order; body = what changed & why (file
+  refs) + verification run & result + anything skipped. Stop there.
+- Python is banned in repo code (governance-enforced). Deriving test constants with
+  Python/R locally is fine; only the constants + a derivation note enter the repo.

.claude/tasks/prod-readiness/w1-1-neural-guardrail.md

@@ -0,0 +1,79 @@
+# W1-1 · Neural boundary guardrail (P0) + hardening
+
+**Model:** impl=opus · verify=opus · **Branch:** `fix/neural-boundary-guardrail`
+**Priority: P0 — this is the product's raison d'être made real.**
+
+## Context
+
+The flagship guarantee — "no number is ever produced by the LLM" — is currently
+**prompt-only** (`src/tools/chat.jl` SYSTEM_PROMPT ~lines 29-66) with zero output
+validation. `chat.jl` (~114-119) prints assistant content verbatim; nothing checks
+that numerals in the reply came from a tool result. Surrounding this are crash/robustness
+gaps: unguarded tool-call JSON parsing, no HTTP timeout, silent-null unknown sub-types,
+dropped `tools` on follow-up calls (no multi-step chaining), and `@assert`-based
+resource assumptions.
+
+## Requirements (implement in `src/tools/`)
+
+**(a) NEW `src/tools/guardrail.jl`:**
+- `collect_numbers(x)` — recursively harvest every numeric value from tool-result
+  Dicts/Vectors/nested structures.
+- `extract_numeric_tokens(text::String)` — find numeric literals in assistant prose
+  (ints, decimals, scientific notation, percentages).
+- `validate_numeric_provenance(text, tool_results, user_numbers; rtol=1e-6) -> (ok::Bool, orphans::Vector{String})`.
+  A token is legitimate if it approx-matches (rtol) any harvested tool-result number,
+  OR its ÷100 / ×100 variant matches (percent phrasing), OR it appears in the user's own
+  input numbers, OR it is a small structural integer 0..12.
+
+**(b) `chat.jl`:** record all tool results for the turn; after the final assistant
+content, run the guardrail (parse user-message numbers as `user_numbers`). If orphans
+exist AND tool calls happened: ONE retry asking the model to restate using only
+tool-result numbers; if orphans persist, print the reply with a clear warning block
+listing the unverified numbers. If the reply has numeric tokens but NO tool call was
+made: same retry-once-then-warn with a "no symbolic computation was performed" message.
+**Never silently rewrite model text — flag, never fabricate.**
+
+**(c) `lmstudio.jl` `process_tool_calls`:** wrap the per-tool-call body (nested key
+access + `JSON3.read` of arguments, ~lines 88-101) in try/catch; on failure push a
+`role:"tool"` message with a clean `Dict("error"=>...)` so the model recovers. **Pass
+the `tools` parameter on the follow-up call** (currently dropped ~line 104) and iterate
+tool-call rounds in a bounded loop (max 5) until a reply has no tool_calls. Add HTTP
+timeouts to `call_lm_studio` and the `chat.jl` HTTP call: `connect_timeout=10`,
+`readtimeout=120`, `retry=false` (see `echidna_adapter.jl` for the existing pattern);
+timeout → return the existing error-Dict shape.
+
+**(d) `chat.jl` REPL while-loop:** try/catch around the turn body — print a concise
+error and continue; one bad turn must never kill the session.
+
+**(e) `executor.jl`:** clamp caller-supplied `n_reps`/`n_permutations` to ≤100_000 and
+component counts `k` to ≤20 (return `Dict("error"=>...)` when exceeded); add a trailing
+`else return Dict("error"=>"Unknown type '…' for <tool>")` to EVERY inner sub-type
+dispatch (grep every inner if/elseif chain: t_test, time_series, information_theory,
+survival_analysis, robust_stats, causal_inference, spatial_stats, advanced_modeling,
+algebraic_stats, nonparametric_test, and any others); gate the `trace` backtrace field
+in the catch-all behind ENV `STATISTIKLES_DEBUG` (default off), keeping a concise stable
+error string.
+
+**(f) tests — NEW `test/guardrail_test.jl`:** unit tests for the three guardrail
+functions incl. a **clean fixture** (all numbers from tool results, with rounding/percent
+variants) that passes and an **injected-fabrication fixture** that MUST be flagged; tests
+for `process_tool_calls` recovery with malformed tool_call dicts (missing keys, non-JSON
+arguments) — construct response Dicts directly, no HTTP; tests for clamps and
+unknown-sub-type else-errors via `execute_tool`. Wire into `test/runtests.jl`.
+
+## Acceptance criteria
+
+- [ ] Guardrail flags an injected fabricated number and passes a clean reply (both tested).
+- [ ] Malformed tool-call dicts recover instead of crashing (tested).
+- [ ] Every inner sub-type dispatch has an `else`-error; clamps enforced (tested).
+- [ ] HTTP calls have timeouts; follow-up call passes `tools`; loop is bounded.
+- [ ] Full suite green locally (was 4404 tests) + the new tests.
+
+## Local verification
+
+`flock /tmp/statistikles-julia.lock -c 'cd <repo> && julia --project=. -e "using Pkg; Pkg.test()"'`
+in a WSL login shell (`wsl.exe -d Debian -u hyperpolymath -- bash -lc '…'`).
+
+## Out of scope
+
+Prompt-injection input delimiting (that is W2-7, which builds on this guardrail).

.claude/tasks/prod-readiness/w1-2-stats-degenerate-inputs.md

@@ -0,0 +1,54 @@
+# W1-2 · Degenerate-input guards + `@assert`→`ArgumentError`
+
+**Model:** impl=sonnet · verify=opus · **Branch:** `fix/stats-degenerate-inputs`
+
+## Context
+
+The compute core is correct on the happy path and reference-validated, but degenerate
+inputs leak `NaN`/`Inf` verbatim to the user — violating the finiteness + JSON-
+serialisability contract and the "nothing fabricated" guarantee. Separately, ~26
+validation `@assert` sites across ~13 modules are the sole guard on user/LLM data;
+Julia documents `@assert` as disable-able, so mismatched-length/out-of-range inputs
+could proceed to `BoundsError` or silently-wrong numbers.
+
+## Requirements
+
+**(a) Degenerate guards** (`src/stats/*.jl`): skewness requires n≥3; kurtosis n≥4;
+pearson/regression guard zero denominators (`den>0`, `ss_tot>0`, `(1-r^2)>0`); t-tests
+guard `se==0` and `n<2`; zero-variance groups. Follow the guard patterns already in
+`spearman`/`one_way_anova`. On a degenerate case return `nothing` (JSON null) for that
+field plus, where the Dict shape allows, a short `"note"` explaining why — never
+NaN/Inf. Also convert misleading sentinels `harmonic_mean=0.0`, `cv=Inf`,
+`geometric_mean=NaN` to `nothing`+note.
+
+**(b) Replace validation `@assert`s** that guard user/LLM data with
+`throw(ArgumentError("…"))` carrying a precise message (grep `@assert` under `src/`;
+known sites include `correlation_regression.jl:17,54,206`, `descriptive.jl:132`,
+`information_theory.jl:26`, `representations.jl:15`, `bridge/typell_levels.jl:59`). Add
+NEW `src/stats/validation.jl` with small helpers (`require_equal_length`,
+`require_nonempty`, `require_positive`, `require_probability`, …) and use them. Keep
+`@assert` only for true internal invariants.
+
+**(c) tests — NEW `test/degenerate_input_test.jl`:** n=1/2/3 vectors, constant vectors,
+zero-variance two-group cases; assert no `NaN`/`Inf` anywhere in returned Dicts (reuse
+the serialisability walk from `e2e_test.jl`); `@test_throws ArgumentError` for the
+converted validations. Wire into `runtests.jl`.
+
+**NOTE:** `descriptive_stats`' `outlier_fences` was already fixed to a `Vector` (PR #31,
+merged). Do not touch it.
+
+## Acceptance criteria
+
+- [ ] No core stat function returns NaN/Inf on degenerate input (tested).
+- [ ] Converted validations throw `ArgumentError` (tested).
+- [ ] Full suite green + new tests.
+
+## Local verification
+
+`flock /tmp/statistikles-julia.lock -c 'cd <repo> && julia --project=. -e "using Pkg; Pkg.test()"'`
+(WSL login shell). Sibling W1-1 also adds guards; if both are unmerged and overlap on a
+file, note it — do not duplicate.
+
+## Out of scope
+
+The guardrail/provenance layer (W1-1); reference-value coverage (W2-5).

.claude/tasks/prod-readiness/w1-3-executor-router-coverage.md

@@ -0,0 +1,51 @@
+# W1-3 · Table-driven router tests + CI coverage
+
+**Model:** impl=sonnet · verify=sonnet · **Branch:** `test/executor-router-coverage`
+
+## Context
+
+`src/tools/executor.jl` has ~75 dispatch arms but `execute_tool` is tested exactly once
+(anova, `reference_validation_test.jl:103`). The string→function mapping and argument
+coercion — the precise layer the LLM drives — is unverified for 74/75 tools; `lmstudio.jl`
+has zero test references. Coverage is entirely unmeasured (no flag, no reporter, no gate)
+across ~90 source files.
+
+## Requirements
+
+**(a) NEW `test/executor_router_test.jl`:** programmatically enumerate every registered
+tool name from `src/tools/definitions.jl` (parse the definitions structure — do NOT
+hand-copy the list); maintain a table of minimal valid arguments per tool; for each,
+call `execute_tool(name, args)` and assert the result is a `Dict` NOT containing
+`"error"`. Maintain an explicit skip-list with a reason string for tools genuinely
+needing external services/files, and assert the skip-list stays small. For ≥5
+high-traffic tools (t_test, descriptive_stats, correlation, regression, mann_whitney)
+cross-check key numbers against the direct Julia function call (the anova pattern). **The
+test must FAIL if a new tool is registered without a table entry or skip reason** — that
+is the point. Wire into `runtests.jl`.
+
+**(b) `.github/workflows/e2e.yml`:** switch to `Pkg.test(coverage=true)`; add a
+SHA-pinned `julia-actions/julia-processcoverage` step; compute total % and echo to
+`GITHUB_STEP_SUMMARY`; upload an lcov artifact. **INFORMATIONAL only** (no threshold
+gate yet). Match existing SHA-pinning style (every action pinned by full commit SHA +
+version comment).
+
+**Sibling caution:** W1-1 adds `else`-error branches for unknown sub-types and clamps —
+do NOT assert unknown sub-types return `nothing`, and use argument values within clamp
+bounds.
+
+## Acceptance criteria
+
+- [ ] Every registered tool is exercised or explicitly skipped-with-reason (tested).
+- [ ] ≥5 tools cross-checked vs direct calls.
+- [ ] e2e.yml runs with coverage and reports a %; actions SHA-pinned.
+- [ ] Full suite green + new test.
+
+## Local verification
+
+`flock /tmp/statistikles-julia.lock -c 'cd <repo> && julia --project=. -e "using Pkg; Pkg.test()"'`
+(WSL login shell). YAML: actionlint if available, else careful review.
+
+## Out of scope
+
+Enforcing a coverage threshold (informational first); extending ground-truth reference
+values (W2-5).

.claude/tasks/prod-readiness/w1-4-documented-install-path.md

@@ -0,0 +1,57 @@
+# W1-4 · Make the documented install path real
+
+**Model:** impl=sonnet · verify=haiku · **Branch:** `fix/documented-install-path`
+
+## Context
+
+`QUICKSTART-USER.adoc` drives `just setup`/`just run`/`just deps`, but `setup` doesn't
+exist, `run` prints "Run not configured yet" (`Justfile:347-349`), `deps`/`build` are
+no-op echoes with TODOs. A new user following the documented quickstart cannot install
+or run. Only the raw README `julia --project=.` path works. Four quickstarts diverge;
+`docs/QUICKSTART.md` even clones a different repo.
+
+## Requirements
+
+**(a) Justfile** — real recipes wrapping the working commands:
+`setup: julia --project=. -e 'using Pkg; Pkg.instantiate()'`; `deps:` alias/dependency
+of setup; `build: julia --project=. -e 'using Pkg; Pkg.precompile()'`;
+`run: julia --project=. -e 'using Statistikles; main()'`. Keep the test recipe correct.
+If docs reference `stapeln-run`, either alias it to `run` or drop the reference — be
+consistent.
+
+**(b) Quickstarts** — replace remaining template placeholder content in
+`QUICKSTART-USER.adoc` (token list ~line 4, "See README.adoc" body) with a real minimal
+quickstart matching the new recipes; correct expected-output claims (check what
+`src/Statistikles.jl` `main()` actually prints — don't promise unprinted strings).
+`QUICKSTART-DEV.adoc`: replace `{{BUILD_CMD}}`/`{{TEST_CMD}}`/`{{LANG_STACK}}` with real
+Julia commands; fix references to nonexistent `just setup-dev`/`panic-scan`/`flake.nix`/
+`tests/` (tests live in `test/`). `QUICKSTART-MAINTAINER.adoc`: trim references to
+missing recipes. `docs/QUICKSTART.md`: reconcile to statistikles or reduce to a pointer.
+**One canonical, tested command story.**
+
+**(c) `.tool-versions`:** add `julia` pinned to the CI minor (check `e2e.yml` — 1.10.x).
+
+**(d) `README.adoc`:** fix the module-count claim (says 17; count `src/stats/*.jl` and
+state the real number — audit found ~40).
+
+**(e) NEW `.github/workflows/install-smoke.yml`:** ubuntu-latest; SHA-pinned
+`actions/checkout` + `julia-actions/setup-julia` (1.10) matching repo pinning style;
+install `just` (SHA-pinned action or apt); run `just setup && julia --project=. -e 'using Statistikles' && just --list`.
+NO job-level `hashFiles()`/`secrets` conditionals — step-level only.
+
+## Acceptance criteria
+
+- [ ] Every recipe referenced by any quickstart exists in the Justfile (grep-verified).
+- [ ] No `{{placeholders}}` remain in touched docs.
+- [ ] install-smoke.yml is schema-valid and SHA-pinned.
+- [ ] README module count matches reality.
+
+## Local verification
+
+In WSL: `sudo apt-get install -y just` (NOPASSWD sudo), then `just --list` in the repo
+parses; grep that every quickstart-referenced recipe exists. Optionally `just setup`
+under the Julia lock.
+
+## Out of scope
+
+Container/devcontainer install (W2-3); release (W2-1).