Skip to content

Releases

v9.21.0 — integration manifest and the summary-schema versioning fix

Choose a tag to compare

@chrisdavidson chrisdavidson released this 16 Oct 02:03

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

  • e5d670e4 added conclusion.rests_on as 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 an optional
    keyword; conclusion.rests_on carries it and an absent key reads as null. The versioning rule now
    distinguishes adding an optional field (keeps the version) from adding a required one (increments
    it); schema_version stays 1. SUMM-BLOCK still enforces rests_on through the section 6
    Pre-check: cross-check and gains three controls.

Added — integration manifest

  • first-principles/references/integration.json (source shared/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_COUNT 58 → 59. No agent-body, rubric, template or skill change.

v9.20.0 — one-page executive summary

Choose a tag to compare

@chrisdavidson chrisdavidson released this 15 Oct 11:20

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

Choose a tag to compare

@chrisdavidson chrisdavidson released this 15 Oct 11:51

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

Choose a tag to compare

@chrisdavidson chrisdavidson released this 15 Oct 11:51

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.json runs
    first-principles/hooks/delivery-guard.py on SubagentStop for
    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 when python3 is 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.
  • Skill is added to the agent's disallowedTools. In 5 of 28 worked-example runs the
    agent's first tool call was Skill — 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 missing Skill, which must fail.

Changed — checks

  • New gate DELIVERY-GUARD (scripts/check-delivery-guard.py --self-test, CI and battery):
    the guard's wiring (one SubagentStop entry, 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

Choose a tag to compare

@chrisdavidson chrisdavidson released this 09 Oct 08:57

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-fermi still argued the
    pre-ceb16c52 framing 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-fishbone rated C1 HIGH on an unsupported tier link and called 11 of 23 "the
    majority"; personal-general-2 compared a real return with a nominal rate;
    science-engineering's binding-constraint claim failed at its own winter figure;
    science-engineering-2 cited a gear and a ball standard for a roller bearing;
    software-systems was 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-systems C2/C3/§6, ishikawa-fishbone C1, software-systems-2 C3,
    science-engineering-2 C2.

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/ and tests/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

Choose a tag to compare

@chrisdavidson chrisdavidson released this 06 Oct 04:09

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 in 45f6244a (shipped in 9.19.0) passed a content value to
    document(author:) and built the two page styles as page(...) 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 with expected 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 code FIG-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 a Read-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-typed untested 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.md no 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

Choose a tag to compare

@chrisdavidson chrisdavidson released this 05 Oct 04:06

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 on scripts/_battery_core.py: mutated to
    MIN_HEADER_HITS = 3 over 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 new tests/conftest.py now point
    PYTHONPYCACHEPREFIX at 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 reports FIREWALL: 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 exec their final gate. exec replaced 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.md documents the hazard. A single script run by hand outside these runners
    is not covered unless it exports a fresh PYTHONPYCACHEPREFIX.

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

Choose a tag to compare

@chrisdavidson chrisdavidson released this 05 Oct 01:22

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.py no longer requires CLAUDE.md to spell out
    --focused-p-threshold 4 / --focused-n-threshold 1. That prose was removed when
    CLAUDE.md was condensed, and its presence never proved the value the battery applies. A new
    test_battery_focused_thresholds_default_4_1 reads the defaults directly from
    scripts/check-routing-battery.py, from both its --help text and build_parser(). The
    thresholds stay documented in docs/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 stale scripts/__pycache__ entry, and a
    mutation check read a 4 -> 3 edit back as the old value.
  • test_battery_boundary_p_threshold_default_is_2 now reads its own flag's default. Before,
    it matched a bare default: 2, which --boundary-n-threshold also prints, so a 2 -> 3
    change to the boundary-p default still passed.

Fixed

  • tests/test_70_step0_emulator_invariants.py pins KNOWN_TECHNIQUES by 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

Choose a tag to compare

@chrisdavidson chrisdavidson released this 05 Oct 00:18

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 in pyproject.toml's dev group and locked in uv.lock, with
    Ruff's full default rule set (no select). scripts/*.py and tests/test_*.py are in
    scope; every recorded tests/<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.md and docs/TESTING.md. Ruff is a local convention. It is
    not registered as a gate in CI or the battery.

Changed

  • uv run ruff check and uv run ruff format --check now 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: BLE001 with 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: on outside the pinned span, so their bytes are unchanged.

Fixed

  • FIG-GATE: control B01 still expected the typst-absent exit code 2 after it moved to 1.
  • CONF-SURFACE: the gate page's deferred-ledger narrative chain is extended to its current
    terminus after the CLAUDE.md condensation shrank the ledger.
  • CLAUDE.md again 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.py was missing a space.

FIREWALL: GREEN (32/32); sync-content.py --check clean; VERSION-01 green on every stamp.

v9.18.1 — First Principles Thinking

Choose a tag to compare

@chrisdavidson chrisdavidson released this 05 Oct 01:26

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