The cross-harness skill shipped (PR #17/#19) with README/CLAUDE.md/AGENTS.md
coverage, but the mdBook — the public disclosure surface — had zero mention
of it. By this project's own standard that is a parity defect: the flagship
consumable feature was undocumented where it is disclosed.
- New chapter "Consume it: the peltier skill" (docs/src/skill.md): install
paths and the harness matrix, the ZeroClaw script-blocking variant, the
gate order verify mode enforces, the refusal doctrine, and exactly which
of these claims CI asserts. Numbers carry their CI and workload.
- SUMMARY.md, architecture.md (layout now lists the skill + mirror),
reproduce.md, introduction.md: cross-links to the chapter.
- docs.yml: pull requests now BUILD the book (never deploy) — a broken
chapter or dangling include is a red PR check, not a post-merge surprise.
Also closes an audit finding: the book rebuilds when results/** changes,
since case-study chapters {{#include}} evidence files from there.
Book build verified locally with mdbook 0.4.x (skill.html renders).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The SKILL.md Agent Skills standard (agentskills.io) is now read natively by
Codex, Copilot, VS Code, Cursor, Gemini CLI, opencode, Goose, Amp, Zed,
Factory, and ZeroClaw — so the portable move is not per-harness adapter
files (forked content that drifts) but one canonical skill placed where
each harness actually looks.
- Spec-compliant frontmatter: license, compatibility (the Linux-only
measurement story, stated up front), version/author/tags top-level
(ZeroClaw's runtime reads those; the spec ignores unknown fields).
reference/ renamed to references/ per the spec's conventional layout.
- .agents/skills/peltier/ mirror: the cross-tool convergence path (Codex,
Zed, Cursor, Gemini CLI, Copilot, opencode, Goose, Amp). Byte-identical
to the .claude canonical, enforced by CI — drift between the two copies
is a red build, not a footnote.
- AGENTS.md at the repo root for the ~20 harnesses that read it (Claude
Code does not; CLAUDE.md remains its file). Deliberately thin: it points
at CLAUDE.md and the skill instead of restating rules.
- scripts/install-skill.sh: stamps a consumer repo at both discovery paths
(--layout claude|agents|both), or emits a script-less --zeroclaw-variant.
ZeroClaw's skill security policy blocks script files by default
(skills.allow_scripts off) — its audit rejected the full skill and passes
the variant, verified against the real zeroclaw binary. The variant loses
nothing: preflight.sh still exists exactly once, in the peltier checkout
the skill already requires, and SKILL.md now documents running it from
there. Re-implementing preflight inline is named as a refusal condition.
- CI (skill-preflight): frontmatter upgraded to a full Agent Skills spec
conformance check on BOTH copies (name rules, dir match, description and
body limits, metadata string-map), plus mirror equality and a functional
installer test (both layouts identical to canonical, variant carries no
scripts/, nonexistent target refused).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The description was an unquoted YAML scalar containing "trust layer:
equivalence" — a colon-space inside a plain scalar makes YAML parse it as a
nested mapping, so the frontmatter raised "mapping values are not allowed in
this context" and the skill would not load at all.
Quoted the scalar and replaced the colon with an em dash.
The real defect is that CI asserted the preflight script's behavior but never
checked that the skill it ships is loadable. Added a step that parses the
frontmatter, requires name/description to be non-empty strings, and requires
name to match the directory — so an unloadable skill fails the build instead
of failing the user.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The reusable artifact here was never the vendored targets — it is the
discipline: prove equivalence, prove significance, or claim nothing. This
packages it as a Claude Code skill usable from any repo.
Two modes. `verify` works anywhere, on any two shell commands in any
language: equivalence before timing -> A/A calibration -> interleaved A/B
with a bootstrap CI -> a verdict decided by the CI lower bound, never the
median. `attempt` drives the full in-repo loop (gates, pristine-baseline
verdict, ledger row, ROI report).
It drives the real bench-runner binary and refuses rather than degrade: on
an unsupported host, or with no trust layer reachable, preflight stops and
says so instead of falling back to a hand-rolled timing loop. A second copy
of the statistics is a second thing that can lie. A refusal ends the claim,
not the work.
An adversarial review of the skill caught six high-severity defects, all
fixed here — several of them the very errors the skill exists to prevent:
- verify mode had no risk classification at all. bench-runner emits only
accepted/rejected-bench; needs-human-review is minted by the in-repo
verdict path, which verify does not run. A concurrency change with
byte-identical output would have sailed through as "accepted". The skill
now makes the agent the classifier and says so explicitly.
- the accept template exposed `pin_prefix`, which is inert for
compare/aa/calibrate (only `verdict` reads it) — an agent would have set
it and reported pinning that never happened. Now documents wrapping both
sides in taskset instead.
- the equivalence gate compared stdout only, so two commands that write to
stderr and a dist/ tree would "GOLDEN PASS" on two empty files. Now hashes
stdout + stderr + exit code + artifact tree, and an empty diff over empty
output is a failed gate, not a passed one.
- nothing told the agent to build two coexisting immutable artifacts, so a
`cargo run` baseline could rebuild from the patched tree mid-bench — the
exact trap phase1-verdict-smoke-001 recorded.
- service mode was documented as generic HTTP. It is not: the server must
take <port> <doc> <iters>, print READY, and close the connection. A stock
Express app hangs the harness forever. Contract now stated.
- the CI refusal test could not pass: preflight also walks up from its own
location, so running it in-place found this very repo. The test now copies
the skill out of the tree first.
CI job `skill-preflight` asserts the contract that matters — resolve when a
trust layer is reachable, REFUSE when it is not, and work when consumed from
another repo via PELTIER_HOME. It deliberately does not assert a statistical
outcome: a shared runner is too noisy for that, which is precisely why the
skill calibrates before it claims.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- docs/: an mdBook documentation site — thesis, architecture, measurement
discipline, equivalence gates, agent loop, isolation/anti-reward-hacking,
playbook, ROI, reproduce, roadmap, and the five case studies (pulled from
their single source in results/ via {{#include}}). Builds clean (21
pages).
- .github/workflows/docs.yml: builds mdBook and deploys to GitHub Pages on
push to main (one-time setup: Settings → Pages → Source = GitHub Actions).
- README.md: rewritten as the project front page — the thesis, the verified
results table, layout, quick start, how it stays honest, links to the
book. Replaces the stale Phase-0-era text.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EcKPWQ3MQD4NdEHwar96u2
diff-test standalone (just gates / CI target-gates) passed the now-
templated build.binary into golden replay verbatim — literal {out}.
It now builds the current tree to targets/<t>/gates-build and tests
that, with a --binary override. CI's target-gates-no-net job gains
clang/cmake, fetches+gates the cjson C target (clang build -> Unity/
CTest -> golden replay) alongside tokei.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EcKPWQ3MQD4NdEHwar96u2
The 8-session probe passed cleanly (0 false positives, 8/8 detection,
A/A CIs ~±0.6%); run the same 20-session protocol used for the local
trust anchor so GH-runner evidence is directly comparable.
Closes the CI-reachable slice of the Phase 1 infra gaps:
- trust-layer job: cargo test + clippy -D warnings + fmt
- target-gates-no-net: fetches pinned targets (new targets/fetch.sh),
regenerates + verifies corpora, runs 'just gates tokei'
mechanically, and executes the bench workload inside a
--network=none container (SPEC 3.1/10 no-net requirement)
- runner-calibration (informational): A/A + injection harness measures
the shared runner's noise floor per run, evidence uploaded as an
artifact — environments are judged empirically, not assumed
- perf-probe (informational): reports which perf event sources work
docs/infra.md maps each remaining hardware requirement (pinned cores,
governor/SMT control, separate-uid trust layer) to the bench-metal
self-hosted runner setup a human can complete in ~15 min.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EcKPWQ3MQD4NdEHwar96u2
benbrownandClaude Fable 5
copilot-swe-agent[bot]andGitHub