v1.8.2

v1.8.2 is a patch release with two small mechanism changes, both loosening a gate that read honest work as failure. The evidence for both came from this repository's own first self-convergence, one release ago.

• An iteration that honestly records blocked no longer counts toward the stall stop, under the same cap of three consecutive exempt iterations that already bounds the convergence sequence. The stall gate exists to end dead runs; a run that did the work and refused to claim an unverified checkpoint is not dead - the run that proved it was ended three minutes before its own verify returned green. A run that types blocked forever burns the cap and stalls exactly as before.

• The verify-gate timeout is measured, not guessed. PLAN.md may record a Verify duration: <N>s line from a real timed run; the Stop hook derives its converged-stop bound from it at 3x headroom, floored at the old 240-second default so the gate can never become twitchier than it was. An explicit verify_timeout_seconds in the loop state still wins, the launcher inherits the bound across relaunches and asks when nothing is recorded, and the timeout refusal now names both remedies. The engine's own repository needed a hand-set override to declare its first convergence; no project should meet that refusal twice.

• The validator grew from 197 to 202 checks (the figure a clone derives; the maintainer tree runs two more). The five new scenarios cover both changes, and each was proven able to fail by a sabotage that discriminates it alone - the blocked exemption, its cap, the derived bound, its floor, and the precedence between the state key and the recorded duration.

Mechanism files changed: stop-hook.sh, SKILL.md, iteration-prompt.txt, plan-default.md. Both changes are strictly more permissive; no previously green run turns red. Upgrade: git pull or re-run the installer, which also refreshes the installed skill copies.

v1.8.1

v1.8.1 is a patch release. The engine's mechanisms are byte-identical to v1.8.0 - the Stop hook, the /jeffy and /cancel-jeffy skill commands, both installers, and the iteration prompt carry not one changed byte between the tags. One sentence was added to the method text, and it is the point of the release.

This repository now converges under its own engine, and the receipts are in the tree. A 15-iteration run declared convergence at 9e55f68 with the adversarial evaluator's artifacts published at .jeffy/evaluator/ - invocation 1 a REJECT whose findings were fixed and countersigned by invocation 2's PASS. Evaluator artifacts are product from this release on: a convergence claim ships with the gate's own command-by-command record, every command with its real exit status, committed and unmodified.

The new method sentence backs that up: an evaluator artifact names any location outside the repository by a placeholder it defines once, and never contains a machine-absolute path - the record a repository keeps should read on any clone. A validator check enforces it over every tracked artifact and was proven able to fail, against real artifact text that leaked an absolute path, before it shipped.

The validator grew from 189 to 197 checks (the figure a clone derives; the maintainer tree runs two more). The new checks pin claims that were previously prose: the language-pie alt text, three README/ATTEMPTS agreement surfaces, enumeration boundaries, the refused-truncator and timeout-fallback lists, and that every receipt names the convergence standard its run met - the four pre-evaluator receipts now say so explicitly. One honesty note: the first push of this release went red on the Linux leg's shellcheck pass, on two of the new checks' own lines - a defect invisible on the host that wrote them, where shellcheck is absent and the check skips. Fixed before this tag; the failure and fix are in the history.

The receipts table grew since v1.8.0: rust-url and PHP-Parser joined at 21 converged targets across 10 languages, now drawn as a language pie whose chart and alt text are both derived from the table itself. evals/ATTEMPTS.md gained six published non-convergences - goldmark, image-rs twice, BurntSushi/toml, and mruby twice (5 runs/50 iterations and 5 runs/63) - because a method that only publishes the runs that worked is not being measured.

Also: SECURITY.md now names all five refused verify-command truncators, and the ATTEMPTS pre-registration paragraphs read in ordinal order.

Upgrade: git pull (or re-run the installer). Nothing to reconfigure.

Jeffy Loop 1.8.0

Eight backlog items, and every one of them is a rule the engine stated but did not enforce. Two came from the first production arc run under 1.7.0, one from the first brownfield target picked for an oracle the loop could not rewrite, and the rest from auditing the hook against its own corpus.

Breaking

• A terminal REJECT is one with no invocation left, not the second one as such - and it no longer forfeits the budget. A second rejection holding an invocation files its findings and the run continues, which is the only way a run whose first verdict was a rejection reaches the third review it earned. A terminal rejection now enters gate salvage: it works only the findings the gate filed, never re-invokes, never declares, and ends blocked with the declaration deferred to the next run's fresh gate. Three blocked runs previously sat on 13 budgeted iterations they were forbidden to use.
• The evaluator artifact is keyed by invocation ordinal, .jeffy/evaluator/<run-id>-<n>.md. Keyed by run id alone, every re-invocation overwrote its predecessor, so a squash, rebase or shallow clone reduced a run's verdicts to whichever came last.
• A missing BACKLOG.md at the promise is a violation, not a pass. It was the broadest fail-open left in the engine, and it sat in front of every gate rather than beside one: deleting one file was the whole price of an unchecked convergence.

Added

• The Converged hash must be reachable from HEAD, and a history rewrite that preserves the tree is answered by appending Converged: <new hash> - <date> (repoints <old hash>, tree unchanged) rather than by editing the line it orphaned. Accepted only when the two commits carry the same tree, the superseded line still stands, and the old commit can still be read.
• The Verify command declares what it grades and what the platform excludes. The evidence is a convergence in which the command exited 0 for 29 iterations across three runs while the repository's 402-case conformance corpus never executed once, and the journal asserted twice that it was green.
• A convergence refused at budget exhaustion gets one corrective re-feed, so the run is told to close honestly instead of the refusal reaching stderr alone.

Fixed

• The hook and the prompt share one definition of ledger progress. The hook checksummed the whole ledger while the prompt's stall rule spoke of items changing state, and the laxer definition decided whether a run kept going.
• The absolute invocation bound is enforced in shell, and only the absolute one. The prompt still owns the cap arithmetic, and that boundary is stated in the hook rather than left to be inferred.

Found in review and in CI, before release

Three defects in this release's own work, each caught by driving the shape through the hook rather than reasoning about it:

• the corrective re-feed now outranks the stall gate's second strike, which had been ending the same turn and putting the refusal back on stderr;
• the invocation bound counts gate verdicts rather than the word REJECT, which had turned it into a false refusal of legal convergences on the precise path this release opened;
• the artifact-ordinal scan parses on bash 3.2, which stock macOS ships and which the first cut of it killed outright.

Known gaps are recorded rather than papered over: the corrective re-feed is not reached when a closing-extension gate has already ended the run, and the docs state that bound instead of an absolute.

Numbers

Validator: 189 behavioural checks on each CI leg - Linux, Windows and macOS - with a shellcheck lint pass riding the Linux leg. Receipts: 19 converged public targets across 9 languages.

Upgrade with git pull and re-run the installer.

Jeffy Loop 1.7.0

Three gates that were prose, or were shell that could not fire, become shell that can. Every item here was found by auditing the engine against its own eval corpus rather than by using it.

Breaking. Evaluator: unavailable no longer converges a run. A session that cannot spawn the adversarial sub-agent records the reason and ends blocked; the declaration waits for a session where the gate can actually run. One receipt in the corpus converged under the old fallback and says so - that receipt is why the escape is closed.

The evaluator gate leaves an artifact. Before returning any verdict the sub-agent writes .jeffy/evaluator/<run-id>.md - every command it ran, each command's real exit status - and the Stop hook refuses a PASS whose artifact is missing, empty, uncommitted, or older than the commit the Converged line certifies. Who wrote the file cannot be proven in shell and the docs say so plainly; what changes is the price of a false PASS, from eleven typed characters to a fabricated forensic record the repository keeps.

The stall gate can actually fire now. It used to ask whether HEAD had moved - but the engine commits every iteration, so a gate that watched HEAD watched itself, and both strikes were unreachable in every git project. Progress is now a path moved outside the loop's own memory, with the convergence-sequence iterations exempt and that exemption capped. Both tree gates also now work in a project below the repository root.

The +2 closing extension has exactly one legal convergence shape, enforced. The clean audit a declaration cites must predate the window; an audit run inside it ends the run out of budget before any promise is read. Prompt prose alone had failed twice.

Validator grew from 125 to 165 behavioural checks per CI leg. Two independent adversarial review passes over the new gates found 27 defects between them before anything shipped; the eleven worth reading are in the commit messages. First production arc (a four-run convergence on a private repo) exercised every new gate live - including one lesson promoted straight into the prompt: a PASS with observations declares, and the observations travel to the next run.

Full details in the commit history. Upgrade: git pull, then re-run the installer.

v1.6.0 - Enhance mode

Enhance mode, plus ten mechanical guards. The v1.5.0 loop could only find what was wrong; this release lets the same discipline be pointed at what could be better, and hardens the places the eval corpus showed a run could still mislead itself.

Added

• Enhance mode: /jeffy [N] enhance <topic> runs the loop against a stated topic instead of the defect rubric. Iteration 1 is an opportunity audit of the topic's surface; tasks are ranked by impact in the severity slot, worked one per iteration, each with an acceptance check observed to fail against the unimproved tree first. A new plan template, references/enhance-plan-default.md, carries the mode - the topic bounds the run the way the Operating envelope bounds a defect run, and an opportunity exists only if you can point at it. A defect found mid-run is recorded to Proposed and never filed at severity unless it blocks the task in flight, so an Enhance run cannot widen into an uninvited audit. The Stop hook, verify gate, checkpoints, journal, and evaluator gate are untouched and identical in both modes.
• Mode guard: an Enhance launch over a standard PLAN.md, and a standard launch over an Enhance one, are both refused - the two rank work differently and their ledgers must never mix in one set of state files. A PLAN.md with no ## Mode section is a user-authored plan and reads as standard. enhance with no topic is refused with usage text; an unbounded make-it-better run is the invented work the envelope exists to prevent.
• Closing-extension backstop: the +2 window buys the convergence sequence, not another round of work. When non-evaluator work refills the ledger inside the extension, the hook ends the run instead of re-feeding it; evaluator-filed tasks proceed under the one-transaction endgame. The finding rides the run report as the next run's first task.
• Truncator refusal: a Verify command whose last pipeline stage is head or tail is refused, at launch by pre-flight check 6 and again at the converged stop. Such a pipeline reports the truncator's exit status, so a red suite reads as green - the one shape that could have let a broken project converge.
• JEFFY_VERSION in the engine: stated in every RUN STATE line, announced at launch from the installed hook rather than the repo copy, and asked for in the bug-report template.
• Four launch pre-flight guards, all zero-iteration cost: core.autocrlf set to true on Windows (checkpoint diffs would show every line changed), a project that is a subdirectory of a larger git repo (checkpoints would commit the parent's tree), a nested project inside another Jeffy project, and a dirty tree whose modified paths are all symlinks (a cross-filesystem tree, not real changes).
• macOS CI leg: validate-macos on macos-latest. BSD sed, grep, and stat differ from GNU and nothing exercised them before. It found a real defect on its first run, below.
• The verify gate no longer needs GNU coreutils. The hook enforces the timeout with timeout, else gtimeout, else a shell watchdog, so the converged stop re-runs the project's verify command on a stock macOS exactly as it does everywhere else. The three validator scenario groups that used to skip without a timeout binary now run on every leg, and all three legs report the same 125 checks.

Fixed

• The static verify gates were disarmed on every Mac. Parsing the Command: line, the bash -n runnability check, and the truncator refusal all sat behind command -v timeout, so on a host without GNU coreutils none of them ran and the gate was skipped outright. A macOS user whose gate was pytest | tail -1 could converge over a red suite with no diagnostic - the exact failure the truncator refusal was written to stop. Only the run needs a timeout binary; the static checks now always execute. Found by the new macOS CI leg on its first run.

Changed

• Persistent probe batteries declare their paths. A battery under .jeffy/probes/ names the paths it owns; an iteration that touches one of those paths runs that battery in the same iteration, and a battery failure counts as a Verify failure. A battery that pins behaviour a fix changes is updated in that same iteration.
• A clean Testing score costs one isolated run. Scoring Testing None requires at least one test module executed on its own first - a suite green only as a whole hides order dependence and shared-fixture leakage.
• Generalising prose claims ship with their enumeration. A claim over a set of sites - the error names X, no temporary is left behind, reachable only when Y - ships in the same iteration with the enumeration of that set, and its executing check drives every enumerated site. For a claim about failures the enumeration is built by provoking a failure at every step of the operation, never by grepping the source for the calls it makes. If the enumeration cannot be produced that iteration, the sentence narrows to the single site actually verified.
• A fix re-executes the claims it invalidates. Before the checkpoint, the checks behind every prose claim and stated number in the state files, in the modules the diff touches, and in their direct siblings are re-run. A line number is never written into a state file - state the shape the enumerating command returns.
• README counts are derived, never transcribed. The validator computes the eval-receipt numbers from the evals table and fails on a mismatch, closing the class where a hand-typed number quietly goes stale.
• media/flowchart.mmd and both rendered PNGs redrawn for the extension backstop branch, with the REFILL edge on the re-feed path where the backstop actually fires. README gains a first-class Enhance mode section; README and SECURITY.md enumerate the new gates and the third CI leg; the validator grew to 125 behavioural checks on each CI leg.

Upgrading

Re-run the installer. It overwrites the skill folders in ~/.claude/skills and leaves the hook registration alone if it is already correct. Existing PLAN.md, BACKLOG.md, and JOURNAL.md files keep working; the loop-state schema is additive.

Every run now opens by naming its engine version. If you file a bug, include that line.

Jeffy Loop 1.5.0

Every change in this release traces to a failure recorded in the public eval journals in evals/. Twelve projects were run to convergence and their append-only journals read in full; the patterns that cost the most iterations became this engine.

The engine (Stop hook)

• The hook does the budget arithmetic. Every re-feed now carries a RUN STATE line the engine counts itself: the iteration and how many remain, open tasks per section, unswept inventory rows, and, once only the convergence sequence remains, what that sequence still costs. Runs used to discover the arithmetic at the last iteration; the journals record one confessing "the budget arithmetic should have been done at iteration 7, not felt at iteration 9."
• A one-time +2 closing extension. When the budget expires with the ledger empty and the surface swept, the run gets exactly two more iterations to finish the ceremony instead of dying with the work done. Granted once, at exact exhaustion only, on both the plain and rejected-declaration paths.
• The verdict must be on the record. The hook refuses a convergence declaration whose closing journal entry carries no evaluator verdict, PASS or a stated unavailable. The ratchet is exempt; missing journals fail open.
• Machine-read lines stopped eating declarations. Six of twelve projects lost a first declaration to markdown on a machine-read line: backticks became command substitution (exit 127), a trailing annotation became a shell error (exit 2), a list-marker Converged line became invisible. The parsers now tolerate the marker and the backticks, check the command with bash -n before running anything, and name the exact fix instead of a mystery exit code. The fallback that executed section prose as shell is deleted.
• Rotation and archive counters anchor on real entry headings, with a one-shot migration for legacy baselines that counted the grammar template; an interrupt-desynced iteration counter now draws a hygiene note.

The method (templates)

• The adversarial evaluator fires the iteration the ledger first empties, given a clean audit on record and three or more iterations left, so a rejection lands while it can still be answered; up to three reviews when the first lands before the midpoint. The declaring iteration may close up to two gate-filed fixes, re-invoke, and declare as one transaction.
• Declining is priced: a non-runtime Low whose fix plus test exceeds one iteration is declined as cost: exceeds one iteration and named in the run report, never downgraded.
• Backlog lines carry a class (runtime, test, build-ci, docs, dev-tooling), runtime ordered first. Surface a host cannot reach is disclosed as - [~] with its reason instead of blocking convergence. Known-answer probe batteries are kept under .jeffy/probes/ and re-run instead of rebuilt. Working rules the corpus paid for are now binding, from "copy fixed files aside before a red-proof run" to "never pipe the verify through head or tail."

The launcher lints the plan's Verify command at /jeffy launch, so a malformed line costs one message at the start of a run instead of a rejected declaration at its end.

Validation. The behavioural suite grew from 75 to 116 checks. Three corpus failure scenarios were replayed against both engines: red on v1.4.1, green on v1.5.0. One limit stated plainly: the extension never fires over an occupied ledger, by design; a rejection that files tasks at the final iteration is answered by the earlier gate, not by more budget.

Upgrade: git pull and re-run the installer.

Jeffy Loop 1.4.1

The adversarial evaluator, named everywhere it acts

A naming and receipts release. No gate, check, or contract changed behavior; what changed is that the loop's independent convergence judge now carries one canonical name - the adversarial evaluator - across every surface that invokes it: the iteration prompt, the plan template, the validator's governance marker (flipped red-green, still 75 checks), the flowchart, and the README. One concept, one name, no synonyms to reconcile.

Ten converged loop runs

The receipts section now lists ten converged /jeffy loop runs, four of them new since 1.4.0:

• PyPortfolioOpt - six runs, 58 iterations, from a CI-red baseline to 356 passing; the adversarial evaluator rejected five convergence attempts before countersigning the sixth.
• dayjs - eight runs, 74 iterations, 45 findings with 10 High in a 63M-downloads-a-week library; names the third boundary class, host-environment defects.
• yfinance - one run, nine iterations; closed a High that upstream's own failing contract test was advertising; names the fourth boundary class, fixture-corpus defects.
• bat - one run, ten iterations, the first target chosen fresh with no prior audit and the first Rust target: a just-merged, unreleased security flag was silently inert whenever output is piped, and the run caught and owned a regression of its own making along the way.

Upstream, the wave continued: fixes are open as PyPortfolioOpt#751, dayjs#3167, and bat#3862 - the last filed before the affected feature's first release - each carrying a regression test proven to fail on the target's own unpatched branch.

A README that tells the story

The README was redesigned end to end: a theme-aware banner, a story-ordered structure, the receipts as a table (stars, iterations to convergence, run status, headline) with one collapsible entry per receipt, the rules grouped by when they bind, and Quickstart now covering git installation for first-time setups.

Upgrading

git pull
./install.sh        # Windows PowerShell: .\install.ps1

The installer copies the skill into ~/.claude/, which is what actually runs; pulling alone does not update it.

Jeffy Loop 1.4.0

The documented-parameter contract, proven by a convergence

The sweep contract gains its third rule, and this release ships the first machine-checked convergence earned under all three.

Every documented parameter must move. A sweep of value-computing surface now exercises every documented parameter at two or more values that must change the output, boundary and negative sides included. A documented parameter whose value changes nothing is a finding, never a pass. The rule closes a class observed four times in one library - an inert flag, a rate applied only when positive, an aggregation token falling through to no-op, a caller-name skip list silently voiding an argument - the same defect wearing four names, every one invisible to a probe that only checks where the parameter works.

The proof is a converged run. ranaroussi/quantstats (7,489 stars), green at 125 tests at upstream HEAD, converged after four budgeted runs and 40 iterations: 29 findings filed and closed, suite at 393 passing, the library smaller than it started, every fix red-green proven, and the convergence countersigned by an adversarial evaluator that reverted the source and counted 65 of the run's tests fail. The first fresh audit under this release's rule immediately found what five previous audits could not: a risk-free rate silently voided for cagr by a caller-name skip list, and an index builder whose .resample existed only in its docstring.

The receipt states the boundary as plainly as the wins. A parallel manual audit of the same commit found six convention defects - internally consistent numbers wrong in context - that the loop did not find and that remain at the converged tree, named in the receipt. A known-answer probe verifies a formula; it cannot adjudicate which formula the context demands. Convergence is a claim about a contract, and the receipt says exactly which one.

The quantstats receipt carries the full four-run record, the two-way comparison, and the independent re-verification from pristine upstream.

Upgrading

git pull
./install.sh        # Windows PowerShell: .\install.ps1

The installer copies the skill into ~/.claude/, which is what actually runs; pulling alone does not update it.

Jeffy Loop 1.3.1

Correctness probes, not liveness probes

The first run under the v1.3.0 surface inventory (ten iterations on ranaroussi/quantstats) proved the mechanism and exposed its one bias: every High the run filed was a crash or a type error, while independently re-verified value defects at the same upstream commit - a Kelly criterion returning the growth-optimal fraction multiplied by the average loss, an aggregation argument silently ignored - sat untouched behind 160 probes, because a run-without-crashing probe cannot see a wrong number.

Three rules close it, each proven red in the validator before its fix:

• Sweeping value-computing surface requires a known-answer or invariant check per function family. Run-without-crashing flips no inventory row: the costliest defects return wrong numbers without complaint, and a crash-biased sweep files every type error while certifying wrong arithmetic as clean.
• Inventory rows enumerate from the code, including underscore-private modules - independent review found one dead function in a module no row named, demonstrably outside every sweep - and are sized so one checkbox certifies a comparable amount of surface, not eighty functions in one row and two in another.
• The verify gate's revert rule gains its one principled exception, observed working in the field: a newly red test proven green-because-of-the-bug may be fixed forward within the iteration, but only with differential evidence that the change altered no previously-passing output. Without the evidence, revert.

Validator at 75 behavioural checks.

Upgrading

git pull
./install.sh        # Windows PowerShell: .\install.ps1

The installer copies the skill into ~/.claude/, which is what actually runs; pulling alone does not update it. Existing projects inherit the new sweep rules from the iteration prompt automatically; refresh the Surface inventory prose in an existing PLAN.md from skills/jeffy/references/plan-default.md if you want the project-local text to match.

Jeffy Loop 1.3.0

The surface inventory: bound the audit, not just the run

Real third-party runs kept exposing the same design gap. On bukosabino/ta the loop took 64 iterations and was still landing genuine Highs at iteration 62. On ranaroussi/quantstats, 50 iterations across 6 runs scored correctness: None in audit after audit while an entire module - the montecarlo simulator - had never been examined once. Dimension scores claimed the whole project but measured only where the audit had wandered, so a clean score could mean unexamined rather than clean, and nothing bounded or even measured the remaining surface. Convergence was empirical, not structural.

The surface inventory closes that.

• The first audit enumerates the project's whole public surface as a checkbox table in PLAN.md before filing any finding, and probes it breadth-first - every row shallowly before any row deeply - so the worst defect appears in the first filing, not the sixth.
• A row flips to swept only with the commit an executed probe certified, and flips back when its implementing code changes.
• Audits sweep unswept and stale rows first and never wander; a dimension scored None claims only the rows actually swept, and an audit that leaves rows unswept must say so.
• The Stop hook refuses convergence while any row is unswept, alongside its existing ledger, Converged-line and verify-command checks. A PLAN.md from before this release has no inventory section and fails open.
• The run report states progress as rows swept of rows total - a real denominator, so the remaining work is always the visible remainder of a finite list.

Change discipline, aimed at the self-inflicted regressions long runs surfaced: before changing shared or public code the loop reads its callers and the tests that pin it and states the contract the change preserves; a change that alters behavior, signature, or accepted inputs updates the documentation and reopens the affected inventory rows in the same iteration.

Publication rule: code that leaves the project - an issue body, a PR description, a report - must be run in exactly the form it is published, and its stated output must be that run's real output. A reduction of a verified script is new, unverified code.

Also in this release: the ta eval is now a full loop-run receipt (6 runs, 64 iterations, machine-checked convergence, 134 red tests to 211 green), and the README's evals, rules, and contributing sections are brought fully current.

Validator: 66 to 75 behavioural checks across these releases, every new check proven red before its fix.

Upgrading

git pull
./install.sh        # Windows PowerShell: .\install.ps1

The installer copies the skill into ~/.claude/, which is what actually runs; pulling alone does not update it. Existing projects keep converging under their old PLAN.md until you add a Surface inventory section (copy it from skills/jeffy/references/plan-default.md); new projects get it automatically at bootstrap.