Repository navigation
Releases
v9.21.0 — integration manifest and the summary-schema versioning fix
Minor release: an integration manifest, and the summary-schema versioning fix. A tool that
runs beside the plugin (first consumer: agent-router) now reads the plugin's identity from
references/integration.json instead of hard-coding it, and structured-summary blocks written
before conclusion.rests_on existed (9.16–9.17 reports) validate as schema_version 1 again.
No agent-body, rubric, template or skill wording change.
Fixed — summary-schema versioning
e5d670e4addedconclusion.rests_onas a required nested key without a version bump, so every
pre-field v1 block (9.16-9.17 agent reports) failed validation. The schema gains anoptional
keyword;conclusion.rests_oncarries it and an absent key reads as null. Theversioningrule now
distinguishes adding an optional field (keeps the version) from adding a required one (increments
it);schema_versionstays 1. SUMM-BLOCK still enforcesrests_onthrough the section 6
Pre-check: cross-check and gains three controls.
Added — integration manifest
first-principles/references/integration.json(sourceshared/spine/references/integration.json,
emitted verbatim as a second JSON spine reference): the plugin's public identity for tools that run
next to it — plugin and agent name, command prefix, launcher, output directory and glob, the
summary block's schema path, heading and version, the examples directory. Data only: nothing in
this plugin reads it, and no consumer is required. Add-only evolution under its own
manifest_version(1); it carries no plugin version stamp. First consumer: agent-router's
first-principles integration, which falls back to a pinned copy when the file is absent.
GENERATED_TARGET_COUNT58 → 59. No agent-body, rubric, template or skill change.
v9.20.0 — one-page executive summary
Minor release: every analysis now opens with a one-page executive summary. The reader report
was accurate but dense — the summary above it was three lines of chain ids over a report of several
thousand words. The new summary follows the shape of a business executive summary (problem,
recommendation, findings, value and risk, next steps) and is written for a reader who will read
nothing else.
Changed — the Answer block becomes the executive summary (shipped)
- Seven lead-ins, in order: The question, Recommendation, Key findings (3–5 bullets), Value and
risks, Band (from §6), Would change it, Next steps (3–5 numbered actions). At most 400 words (was
120). The reader report still heads it Executive Summary; the working file still heads it
## Answer, so the delivery guard and the persona skill, which read the three original lead-ins,
are unchanged. - It adds nothing. Every line, bullet and step restates §6 and cites the chain §6 cites (The
question restates §1); every number appears in §1 or §6; a line that does not is cut before
assembly. It is written for an outsider: things named by what they are, ids only in citations. - One page in the PDF. The page template sets the Executive Summary on a page of its own and
starts §1 on the next. - The output template carries a worked example of the shape; the reading guide, the report layout
description and both READMEs describe it.
Added — gate controls
- FIG-GATE L04/L05. L04 typesets a worst-case summary (every lead-in, five findings, five steps,
425 words, a title that wraps) through the shipped template and requires, from typst's own heading
locations, that the next section starts exactly one page after it; L05 removes the page break and
must fail. This proves one fixture fits one page, not that every live summary will.
Falsifier:python3 scripts/check-report-figures.py --self-test.
Not in this release
- Backlog 999.199 (correct by appending replacement blocks) was measured and reverted; see
Measured — backlog 999.199 above. The shipped tree apart from this change is 9.19.4's.
🤖 Generated with Claude Code
v9.19.4 — the agent's turn budget rises from 60 to 90
Patch release: the agent's turn budget rises from 60 to 90. Measured, not guessed: the
skip-rate measurement and a turn-by-turn reading of 99 captured agent transcripts
(docs/skip-rate-reading.md).
Changed — agent frontmatter (shipped; backlog 999.197)
maxTurns: 90(was 60). Delivery completes at a median of turn 40 but a 90th percentile of
59, and 16 of 99 runs hit the 60 cap. Every one of those runs had rewritten its own analysis file
in place six or more times after its self-audit found something to correct. At the cap, the main
session resumed the agent and told it to cut the delivery short ("plain text only, no files").
Raising the cap is headroom; backlog 999.198 (audit before writing) addresses the cause. GATE-01
pins the new value.
Measured
- Skip rate, 9.19.2 vs 9.19.3 (
docs/skip-rate-preregistration.md,docs/skip-rate-reading.md,
tests/skip-rate/): 5 of 28 runs finished without delivering on 9.19.2, 0 of 27 on 9.19.3
(Fisher one-sided p = 0.028); the pre-registered verdict is shown effective. 9.19.3's agent
still tried to stop early in 3 of 27 runs; the guard blocked all 3 and all 3 delivered.Skill
was called in no run on either version. The transcripts show four distinct failures behind
"skip": an early skip, the turn cap followed by the main session cutting the delivery, a
delivery written to the wrong directory, and a main session that never dispatches the agent.
🤖 Generated with Claude Code
v9.19.3 — the delivery guard sends a skipping agent back to its procedure
Patch release: an agent that tries to finish without delivering its analysis file is sent back to
its procedure — up to twice per run — by a SubagentStop delivery guard, the plugin's first
executable code, and Skill joins the agent's disallowedTools. Closes the 9.19.2 known issue's
mechanism; the skip rate itself is measured separately.
Fixed — the agent skipping its procedure (shipped; backlog 999.196)
- A delivery guard now refuses the agent's stop until it has delivered. The plugin ships
its first executable code:first-principles/hooks/hooks.jsonruns
first-principles/hooks/delivery-guard.pyonSubagentStopfor
first-principles:first-principles. The guard reads the agent's own transcript for the
analysis file it created and blocks the stop — telling the agent what is missing — until
that file is assembled (first##heading## Answer) and the reader report beside it
exists. It blocks at most twice per run, then lets the stop through, and it fails open on
any error or whenpython3is absent. On the recorded current-body captures it blocks all
7 recorded skips and both partial deliveries and passes every delivered run (DELIVERY-GUARD).
This retires "the entire deliverable is pure Markdown"; the claim is registered under
RETRACT-01. Skillis added to the agent'sdisallowedTools. In 5 of 28 worked-example runs the
agent's first tool call wasSkill— the slash-only launcher, an unrelated user-level skill,
or one that does not exist — and 3 of those 5 abandoned the procedure. GATE-01 pins the
widened list and gains fixture-o, a list missingSkill, which must fail.
Changed — checks
- New gate DELIVERY-GUARD (
scripts/check-delivery-guard.py --self-test, CI and battery):
the guard's wiring (oneSubagentStopentry, matcher derived from the plugin and agent
names, the shipped command) and its verdicts on 44 current-body captures against an
independently transcribed table, with must-fail controls for a renamed matcher, a missing
guard file, a duplicated entry, and an always-allow and an always-block stub.
🤖 Generated with Claude Code
v9.19.2 — the delivery pointer's paths come from the shell
Patch release: the final message's file paths now come from the shell, and every worked
example is corrected where a re-run on the current agent found a verified defect.
Fixed — delivery pointer (shipped agent body)
- The final message's file paths now come from the shell. The final pointer could name
the reports at a location the shell never wrote: the agent rewrote the relative
.first-principles/…paths its delivery commands printed into absolute paths it built
itself, taking the directory from the working directory's name when that name encoded
another path. It happened in 3 of 9 runs on 9.19.1's body and 0 of 9 on 9.13.0's
(docs/skip-paired-reading.md); one run then abandoned the file handoff. Step 9 of Deliver
the analysis as a file now has one Bash call print"$(pwd -P)/<path>"for every path the
steps printed, requires the message to copy those lines verbatim, and forbids writing a path
no command printed. Verified on all 14 worked examples, run in the same scratch directory
whose name triggered the defect: 0 of 14 file-delivering runs named a wrong location
(4 of 23 before the fix), and 13 of 14 gave every path absolute and correct
(docs/pointer-fix-preregistration.md,docs/pointer-fix-reading.md).
Fixed — worked examples (shipped)
- Every worked example re-run on the current agent and corrected where the re-run found a
verified defect (docs/example-rerun-2-reading.md). 13 examples change; no recommendation
reverses. Seven carried an error in their own text:estimate-fermistill argued the
pre-ceb16c52framing in six places;composed-inversion-second-order's estimate did not
cover what it recommended and it was the last example on the old assumptions-table header;
ishikawa-fishbonerated C1 HIGH on an unsupported tier link and called 11 of 23 "the
majority";personal-general-2compared a real return with a nominal rate;
science-engineering's binding-constraint claim failed at its own winter figure;
science-engineering-2cited a gear and a ball standard for a roller bearing;
software-systemswas rated HIGH without meeting the HIGH rule and credited schema
decomposition with independent deploys. Four catches left open since the v9.13.0 re-run are
closed: the equity vesting cliff (personal-general), free-tier cannibalisation
(product-business), the backwards cold-oil premise (science-engineering-2) and
worst-month sizing (science-engineering, now 600 W). Bands lowered to MEDIUM:
software-systemsC2/C3/§6,ishikawa-fishboneC1,software-systems-2C3,
science-engineering-2C2.
Changed — checks
- SUMM-BLOCK control C31 re-pinned to
ishikawa-fishbone's new section 6 pre-check line. - RETRACT-01 registers seven literals the example corrections retracted.
tests/example-rerun-2/,tests/skip-paired/andtests/pointer-fix/registered under
FROZEN-EVIDENCE.
Known issue
- The agent sometimes skips its procedure — about 3 to 4 runs in 14 on the worked
examples, on 9.19.1's body and this one alike. Two modes recur: it invokes a skill (the
slash-only launcher, an unrelated user-level skill, or one that does not exist) and loses
the procedure, or it answers with no tool call at all. A re-run delivers. Not fixed in this
release (docs/pointer-fix-reading.md).
v9.19.1 — reader-report PDFs render again
Patch release: reader-report PDFs render again, and a gate now compiles the page
template. It closes backlog 999.195. It also ships the worked-example and output-template
corrections from 999.178, 999.186, 999.189, 999.190, 999.191 and 999.192, listed below.
Fixed — PDF page template (shipped)
- The PDF page template compiles under typst 0.15 again (backlog 999.195). The cover page
and table of contents added in45f6244a(shipped in 9.19.0) passed a content value to
document(author:)and built the two page styles aspage(...)values with no body, which
#set page(content-page)then tried to apply. typst rejects both, so every reader-report,
memo, reading-guide and index PDF failed from 9.19.0 on: pandoc exited 43 withexpected string or array, found content. The agent disclosed each failure in its final message, as
its contract requires, but the delivered folder looked complete. The template now sets the
author as a string, uses one#set page(...)for content pages, and draws the cover with a
#page(...)[...]call of its own. The design is unchanged: cover page, contents page, and a
running header from page 3.
Added — checks
- FIG-GATE compiles the PDF page template (999.195). Three new controls: L01 renders a worked
example and the reading guide through the shipped template with the agent's own pandoc and
typst invocation, and requires a real PDF from each. L02 must fail on the template frozen from
45f6244a(tests/report-layout-v9.20/). L03 must fail when a content-valued
document(author:)is injected into the shipped template. New finding codeFIG-LAYOUT. With
the 9.19.0 template, FIG-GATE fails at L01. The gate proves the template compiles, not that the
page looks right. pandoc absent means BLOCKED, never PASS; the battery's prerequisite branch
now checks for pandoc too. - The
check-report-figures (FIG-GATE)CI job installs pandoc 3.10.2 from the pinned,
sha256-verified release tarball.
Changed — output template and worked examples (shipped)
- The provenance roll-up's read-at-source clause now covers every load-bearing chain, not
only HIGH ones (backlog 999.191). The output template now names the same population as the
agent body's Phase 3 exit criterion: every unsuffixed ground truth feeding a chain a conclusion
rests on, whatever its band. Every worked example now names aRead-at-source:location for
each such ground truth (26 lines added), and the "none — no chain is rated HIGH" lines are gone.
Where an entry names only a kind of source, the line says so. - Ground truths that were never read at source now carry the
?(backlog 999.190 and
91-REVIEW IN-01). theoretical-limit-carnot GT-4 and estimate-fermi GT-4/GT-5/GT-6 are unquoted
hand-offs from the five-whys example. personal-general GT-2/GT-3 and science-engineering GT-1
are illustrative figures. theoretical-limit-carnot C1 and personal-general C1 drop from HIGH to
MEDIUM, and both examples' §6 drop with them. Each confidence line now names the read that
would remove the?. - software-systems-2 C1 is re-derived (backlog 999.186). On its own numbers the buy path is
cheaper at every FTE level in GT-4's range, and no cost line favours building. The title, the
third hop, the confidence line, §6 and the §2 hinge row now say so. The team-capability
assumption is re-typeduntested belief — capability-hinge. - decompose-irreducibility C1 no longer rests on the unverified ~99% storage figure (backlog
999.189). The refutation now uses the bound (≤ ~62% even at zero storage loss and the Carnot
limit), so C1 stays HIGH without consuming GT-7?. - self-application §6 no longer calls C3 HIGH (backlog 999.192). It names C1 and C3 as the
below-HIGH contributors.
Fixed — documentation and apparatus
docs/ARCHITECTURE.mdno longer says the companion procedures are not inlined. They are, by
generate_agent()(backlog 999.178).- PROV-ROLLUP's exemplar floor now requires the read-at-source half of the roll-up, with two
must-fail injections (91-REVIEW WR-05).
v9.18.4 — First Principles Thinking
Patch release: the check runners read source, never a stale bytecode cache. The shipped
plugin is unchanged apart from its version stamps: no agent or skill body was edited.
Fixed
- CPython reuses a
__pycache__entry when the source's whole-second mtime and size match
the ones the entry recorded. A same-size mutate-run-restore edit made within the second
could therefore be served stale bytecode in either direction: the mutation never ran, or a
restored file ran as still mutated. Reproduced onscripts/_battery_core.py: mutated to
MIN_HEADER_HITS = 3over a cache of the original, the battery reported
FIREWALL: GREEN (32/32)without executing the mutation. Turning off bytecode writes alone
does not fix it, because an existing stale entry is still read. scripts/check-firewall-battery.sh, both pre-commit hooks (.githooks/pre-commit,
scripts/git-hooks/pre-commit) and a newtests/conftest.pynow point
PYTHONPYCACHEPREFIXat a per-run directory. The directory begins empty and is removed on
exit, and every child process inherits it, so no cache entry from an earlier run is ever
read. Rerun on the same planted state, the battery reportsFIREWALL: RED (30/32)with BATT-06 failing. Under pytest, a
planted stale cache was read before the fix, both in-process and in a child process. After
the fix, both read the source.- Both pre-commit hooks no longer
exectheir final gate.execreplaced the shell before its
EXIT trap could remove the cache directory, which leaked one directory per commit. As the
last command, the gate's exit status is still the hook's. docs/TESTING.mddocuments the hazard. A single script run by hand outside these runners
is not covered unless it exports a freshPYTHONPYCACHEPREFIX.
Cost
Bytecode writes stay on inside the per-run directory, so processes within a run still share
compiled modules. A first cut that also turned writes off measured 212s -> 450s for a full
battery. With writes on, a full battery takes 238s, against 212s before.
FIREWALL: GREEN (32/32); tests/: 132 passed; VERSION-01 green on every stamp.
v9.18.3 — First Principles Thinking
Patch release: the tests/ suite is green again. At 9.18.2, uv run pytest tests/ failed
2 of 132 tests. Both failures were stale pins, not product defects. The shipped plugin is
unchanged apart from its version stamps: no agent or skill body was edited.
Changed
tests/test_65_doc_invariants.pyno longer requiresCLAUDE.mdto spell out
--focused-p-threshold 4/--focused-n-threshold 1. That prose was removed when
CLAUDE.mdwas condensed, and its presence never proved the value the battery applies. A new
test_battery_focused_thresholds_default_4_1reads the defaults directly from
scripts/check-routing-battery.py, from both its--helptext andbuild_parser(). The
thresholds stay documented indocs/MEASUREMENT-MAP.md.- The battery-defaults tests load the script from a fresh compile of its source in a
-B
child process. An in-process import could reuse a stalescripts/__pycache__entry, and a
mutation check read a 4 -> 3 edit back as the old value. test_battery_boundary_p_threshold_default_is_2now reads its own flag's default. Before,
it matched a baredefault: 2, which--boundary-n-thresholdalso prints, so a 2 -> 3
change to the boundary-p default still passed.
Fixed
tests/test_70_step0_emulator_invariants.pypinsKNOWN_TECHNIQUESby its parsed value.
The 9.18.2 Ruff format pass wrapped the tuple one name per line, so the one-line text match
failed while the eight techniques were unchanged.
Each pin was checked by mutation: changing any pinned default or technique name fails its own
assertion. tests/: 132 passed. tests/ is still run by hand only. It is not registered in
CI or the battery.
v9.18.2 — First Principles Thinking
Patch release: Ruff for the Python tooling. The validation scripts now share one pinned
linter and formatter. The shipped plugin is unchanged apart from its version stamps: it is pure
Markdown, and no agent or skill body was edited.
Added
- Ruff
0.16.10, pinned inpyproject.toml'sdevgroup and locked inuv.lock, with
Ruff's full default rule set (noselect).scripts/*.pyandtests/test_*.pyare in
scope; every recordedtests/<run-dir>/runner is excluded, including the frozen
tests/confidence-transitivity-v9.4, so frozen evidence stays byte-identical. .git-blame-ignore-revs, listing the mass-reformat commit
(git config blame.ignoreRevsFile .git-blame-ignore-revs).- A "Lint and format (Ruff)" section in
docs/DEVELOPMENT.md, with pointers from
CLAUDE.md,CONTRIBUTING.mdanddocs/TESTING.md. Ruff is a local convention. It is
not registered as a gate in CI or the battery.
Changed
uv run ruff checkanduv run ruff format --checknow both pass. Every implicit string
concatenation inside a collection (ISC004) was read in context: none was a missing comma,
and each is now parenthesised so the wrap is explicit. Deliberate blind excepts in gate and
self-test code carry a per-site# noqa: BLE001with its reason. Scripts with a__main__
guard are executable, and importable helpers lost their shebang.- Functions whose source text is sha256-pinned or sliced by a gate are fenced with
# fmt: off/# fmt: onoutside the pinned span, so their bytes are unchanged.
Fixed
- FIG-GATE: control B01 still expected the typst-absent exit code
2after it moved to1. - CONF-SURFACE: the gate page's deferred-ledger narrative chain is extended to its current
terminus after theCLAUDE.mdcondensation shrank the ledger. CLAUDE.mdagain names the FU-21 gate on the routing-battery row, which the condensation
dropped (tests/test_65_doc_invariants.py).- The Check 5 description in
scripts/check-agent.pywas missing a space.
FIREWALL: GREEN (32/32); sync-content.py --check clean; VERSION-01 green on every stamp.
v9.18.1 — First Principles Thinking
Tagged 2026-10-02; release page created retroactively on 2026-10-04. CHANGELOG.md has no 9.18.1 section; these notes are the annotated tag message.
-
trackb-comparative.py: Fixed init_check() to use relative paths for plugin validation instead of absolute paths, improving portability and reliability (#3000025d)
-
quality-harness.py: Registered report-layout-eisvogel.md in reference exclusion list to prevent false positive detections (#67a839e5)
-
Firewall Battery: All 32/32 gates passing (FIREWALL: GREEN)
-
Version Stamps: All 18 hand-maintained version stamps synchronized to 9.18.1
-
Pre-commit Gates: sync-drift, conformance-baseline, and claim-surface gates all pass
-
Eisvogel LaTeX template integration complete with professional PDF output
-
All changes committed and verified against gate battery before tagging
-
34 files modified (regenerated from shared/ source)
-
2 critical bug fixes in measurement harness and quality tools
-
No breaking changes
-
Fully backward compatible
Tagged: 2026-10-03T03:43:40Z