Changelog

Unreleased

Breaking Changes

• Track Work's init makes a Schema 5 task folder and needs --cue (when the task matters, starting "read when"); a script that ran init without it gets an error saying so.
• Pi's Task Memory is removed: the task_memory tool and its dialogs, /freeflow task, /freeflow project and /freeflow trash, the record write gate, held records, child records and fan-out, the taskMemory settings, and the task-memory capability skill. Pi keeps tasks in the Freeflow store as Claude Code does: the task menu at session start, the held task in the footer, and Freeflow's compaction after the agent's checkpoint. A config that still sets taskMemory loads, and /freeflow status says those settings are ignored. Setup Freeflow moves Task Memory's records into the store with Track Work's migrate, as a task each (a child record too), leaving the originals in place; store init still refuses the folder that holds them, so the store goes in another one.
• Track Work no longer runs Schema 4 records: only migrate reads one, and every other command refuses it and names migrate. init --schema 4, view resume, Checkpoints and Decisions (checkpoint propose, activate, defer, resume and close, decision add, supersede and retire), slice reopen, the registry's project link, task import, task env and task fanout, and the Schema 4 reference are gone; project and task commands work only in a Freeflow store. Discuss Work's choices.mjs --record reads a Schema 5 record only.
• Evaluate Behavior's skill-eval run --dry-run is now --uncommitted: it always ran subjects and called models, and only allowed uncommitted inputs, so the old name promised a run that spends nothing. --dry-run is refused with a message naming the new flag; stored results keep their dryRun field and still read.
• Review Work's review mode is replaced: review.mode (auto, off, always) is gone, and a configuration that still sets it is refused with a message naming review.unit. An independent review now runs at every review unit, review.unit (pr by default, or push, commit, agreement, manual, which proposes each review and waits for your yes), with review.rounds capping its rounds; review.model defaults to auto.

Added

• Freeflow's settings can be changed on every host, the same way. Setup Freeflow's scripts/settings.mjs lists, reads, sets and unsets any setting in the repository's .freeflow/config.json, your .freeflow/local.json, or for this session only, with the rules of Pi's settings screen, and tells the agent at once which Runtime State line changed; the agent runs it when you ask. On Claude Code, /freeflow settings lists the settings Claude Code acts on and /freeflow settings review.mode always [--session | --personal | --repository] changes one, Personal by default, the agent working under the new line from its next step; it runs with no model call and shows in a cloud session. A Session value outside Pi lives in the Freeflow home and is read again at resume and compaction; a new session starts without it.

• Track Work's delegate open --scratch <folder> keeps a delegation with no task: the same brief from the template under the folder's delegations/, with nothing recorded, and delegate check-return --scratch checks its return. Freeflow's core prompt now names Execute Work's delegation reference whenever work goes to another agent (a subagent, parallel workers, a reviewer or any multi-agent orchestration), with or without a task.

• Setup Freeflow sets up the Freeflow store that keeps task memory, in a reference of its own: it asks local only or local + cloud, local only by default, makes it with Track Work's store init (or store init --remote <url> for your private repository), says what to set in a cloud environment (FREEFLOW_HOME at the store's clone, a setup-script line that clones a Freeflow release, and the store attached to a session when its work needs task memory), and moves older records into the store: Schema 4 records and Pi's Task Memory with migrate --project, which converts a copy, and Schema 5 tasks kept in a repository's .freeflow/tasks/ with the same command, which copies them unchanged; the originals stay. A task always lives in the store: where you want no store, there is no task.

• At session start, Freeflow on Claude Code says what keeps the session from a working store and whether you or the agent fixes it (session status's new missing list): a store FREEFLOW_HOME names that is not there, an empty clone not laid out yet, a cloud session's store with no remote. Where no task names the session's folder, as in a cloud session that starts in the store, the menu lists every open task in the store; and task here --scan <folders> finds where a task's repositories are on this machine, so recovery reads their files in a fresh container.

• Track Work's tasks may belong to no project: task create --no-project, or with no project naming the repository, makes task-NNN in the store's tasks/, the session-start menu lists it under "No project", and task move --id <ID> --project <name> (or --no-project) moves a task's folder into a project or out of it, with the next number there and Git keeping its history. estimate gives the context's use against the window and the point where Freeflow's notice comes, from --used or the session's transcript, and with --done and --left projects whether the rest of the work fits in this cycle; where no window is set and the context is larger than the one it would assume, it asks for --window.

• Freeflow on Claude Code (2.1.287 or later) carries a Schema 5 task through compactions by itself, wherever a Freeflow store exists; elsewhere it does nothing. At session start, /clear and resume it pulls the store and gives the agent the menu of the project's tasks. As the context nears Claude's own compaction it tells the agent to checkpoint, and once the checkpoint is done it compacts the session at the turn's end with the task's bundle in place of the conversation, with no summary request, then starts the next turn so the work goes on. A compaction that comes before the checkpoint is Claude's own, with the bundle as of the last checkpoint and your messages since added after its summary. Reading and editing files inside the store no longer waits on a permission prompt or auto mode's check, as in a working directory where edits are allowed; a deny rule still holds. It also syncs the store when a turn changed it, reminds workers whose prompt names a delegation to keep their progress.md, sends back once a return that is not ready, and releases the task at session end; resuming that session, as a cloud session resumes after its container was reclaimed, takes the task back, unless another session took it meanwhile, and Pi does the same. Track Work's script gains session status (this session's state in the store, as JSON for such a layer) and view bundle --fallback.

• Track Work's script sets up the Freeflow store, one Git repository that holds every task's memory. It is local by default (store init makes it on this device, and nothing leaves the machine), and a cloud store with your private repository: store init --remote <url> clones it into the Freeflow home and, when it is empty, lays the store out (store.json, ignore and merge rules, rules/, projects/) and pushes a first commit authored as you, or joins a store another machine made, and store remote --url <url> moves a local store's whole history into an empty repository; store status says what is not committed or pushed; store sync commits, takes the remote's commits and pushes, or with --pull only takes them. Sync keeps working without a network (it commits here and pushes next time), retries a push the remote refused because it moved, merges history.md and sessions.md by keeping both sides' lines, stops on any other file both machines changed with both copies kept until store sync --resolved, and scans every push for common secrets, naming a found one by path and line and never pushing a commit that held it. A home that holds Pi's Task Memory is left alone, and records inside the store pass Track Work's Git check.

• Track Work's script keeps Schema 5 tasks. init makes a task folder: record.md (Current Context, Current Work with the open agreement, the Slice, delegations, Space and what to read, and Future Work), history.md and decisions.md. agreement open, update and close keep what the user agreed, in their words; the slice commands and task set-state work on it; closing a Slice or an agreement appends its one History entry (with the Slice's updates, or the agreement's lines, updates and decision list) and commits and pushes the store; a close that stopped halfway finishes when run again. checkpoint checks the folder's structure and the recovery budget, writes where the work repository stands and pushes the store. view recover says the record is memory and your direction decides the work, then prints the rules, the record, the decisions within their budget, the History index, the project's other tasks and the checks; view entry and view index read History. In a Freeflow store, project new, remove, list and show and task create, take, release, switch, here, search and remove work on its folders: a task's sessions.md says which session holds it, a second session's task take is refused until the holder releases it or you agree to a takeover, checkpoint is refused for a task the session does not hold, task here prints the session-start menu for the folder's repository, and a removed task stays in the store's Git history.

• Track Work's script carries what shaped the work across compactions, converts Schema 4 records, and measures recovery against a budget. discussion list numbers your messages since the last checkpoint, read from Claude Code's session log or a plain User:/Assistant: export (--transcript), messages sent while a turn ran included and resends left out; discussion save keeps the ones that shaped the work, word for word, as a block in sources/discussion.md, each with the agent's line saying what it answered; discussion drop removes a block, and checkpoint lists the blocks whose work is closed. migrate converts a Schema 4 record to Schema 5, in place or into the store with --project, keeping the old record whole in sources/. The recovery budget counts only the memory the agent shapes and scales with the square root of the context window (about 10,000 words at 200,000 tokens, from FREEFLOW_CONTEXT_WINDOW), in normal or expanded mode (task set-budget); Current Context and Future Work keep fixed budgets, and the rules, the skills and the files the record's Recovery list marks always, not counted (accepted Specs, Plans and the skills the work follows) are read and never counted. budget prints it before the agent writes, and init and checkpoint print it too; it only warns. The record's Recovery section lists what recovery reads, each line marked always, always, not counted or when <trigger>, a file optionally cut to (lines a–b). checkpoint --input rewrites the record's In flight section (where the step stands, and what was observed, tried or is pending) and, after a Recovery: line, replaces the Recovery list, which is otherwise kept (Recovery: none empties it); the checkpoint prints each Recovery line's size and share of the budget, and names a definition the new list dropped. view bundle prints everything recovery reads, each file whole or for its lines, with its sizes; without a task, checkpoint --session writes a session summary that view bundle --session prints, with the files its Recovery lines name.

• Track Work's script keeps delegations for Schema 5 tasks: delegate open assigns D-NNN, writes the brief in delegations/D-NNN-<slug>/ from the template, makes a writing worker's worktree on its own branch at the base, and writes the delegation's line in Current Work; --parent opens a sub-worker's delegation inside its worker's folder and refuses a fourth level. delegate amend appends a dated change to the brief; delegate status lists open delegations and their sub-workers; delegate check-return refuses a return with a missing heading or a commit that is not on the brief's branch; delegate close records the outcome, model, effort, tokens, minutes and merge commit in one History entry. view recover --delegation <ID> is a worker's recovery: its rule, then its brief, progress and return. Execute Work's delegation reference names these commands where a step used to be kept by hand.

• Evaluate Behavior's pilot (--pilot) checks each shell arm's harness before its first subject, with no model call: a command in the workspace, one naming a path outside it, the first command again, a write under /tmp, and which of node, python3 and git the shell has. It stops the pilot when the shell stops working after a probe or the arms found different things, and otherwise prints the findings, which apply to every arm.

• Evaluate Behavior refuses a run before any subject when a container image an arm runs in, or the engine that runs it, is missing, saying what to install or pull; nothing is pulled.

• Research Work's study.mjs lock refuses a study plan whose pilot shows the reference arm passing every unit, since such a study has no room to show a gain, unless --saturated gives a written reason, which the lock records. The plan records the pilot in one Pilot result: line.

• Execute Work has a delegation reference for handing work to other agents (subagents, parallel workers, reviewers, trial and eval agents): when handing work out pays, the smallest capable model by default and the strongest only with your yes, briefs that point to files, one folder per delegation holding its brief, progress and return, writers in their own worktrees, a return checked before it is accepted, and each delegation's model, effort, tokens and minutes recorded. A worker may hand mechanical checks, gathering or research to sub-workers on the smallest model, three levels at most, and only the agent you talk to asks you anything. Write Skill's trials, Review Work's reviewers and Research Work's workers point to it.

• Research Work's figures list x labels that overlap and text past the canvas, and an x.rotate option turns long category labels.

• Track Work measures what work uses and plans from it. slice start, each checkpoint and slice close keep, in one line the agent never types, the context a Slice added, the compaction cycles it touched, its working and wall-clock time and, per model and effort, its billed tokens and their cost at API list price, read from the harness's transcript (Freeflow's Claude Code mod names it) or given with --used; delegate close measures a worker from its own log. Each Slice starts with a prediction from past Slices (the task's, else its project's or the store's), corrected by how far past predictions were off; its cost comes from those run on the model and effort it starts on once three were, else from all of them, and the prediction names the model its cost was measured on. estimate --plan lays the Slices left across compaction cycles, flags any too big for one, shows what could run in parallel and prices past delegations and a fan-out; estimate --project and --store add up what was measured. Discuss Work's agreement shows the work's size in compaction cycles and its cost (choices.mjs agreement --plan), with the plan under Technical. Prices come from a dated list-price table that FREEFLOW_PRICES can replace; the planner shows costs and never picks a model.

• Research Work, a new skill (/research-work) for answering a question from evidence gathered and checked first, starting with in-depth reports on code, papers or docs: a research brief agreed with you, a source ledger saying how each source was checked, a claims register with an evidence level per claim, and checks that every path:line citation exists at its pinned commit, every quote appears in its source and every number in the report traces to a registered claim. Its statistics script gives intervals, paired comparisons, clustered runs, rater agreement, multiple-comparison correction, pass@k and power, and Evaluate Behavior now uses it.

• Research Work runs studies and quick checks: a study plan answering twelve questions and locked before the runs that count, a receipt for every run (failed ones included), deviations logged with who cleared them, a validation record before a model judge's verdicts count, and checks that a confirmatory claim was planned, that held-out items ran only under the lock, that every registered number appears in its result file, and that each judge score quotes the output it judged. A Bayesian interval covers pass or fail results in few clusters. The general method of study design and measurement moves from Evaluate Behavior into Research Work, and Evaluate Behavior points to it.

• Research Work writes papers: an outline checked against the claims register (a proposition a result could contradict, contributions with their claim IDs, one sentence per planned paragraph, figures with their data files, the objections and where each is answered), the writing techniques with the evidence behind each, one review and revision by patch, and a rebuttal ledger for the venue's reviewers that records your choice and reason for each comment, refuses submission while a commitment has no place it was fulfilled, and lists requests that are new in a later round. A literature review gets an evidence table. The research report's shape moves from Write Docs into Research Work, which states each finding's strength as its evidence level; Write Docs routes research documents there.

• Research Work has tools for writing the paper: figures drawn from their data files with a receipt the outline checks, a bibliography from the source ledger that marks every source not verified, checks a draft must pass before review (abstract numbers in the body, citations, figure and section references, word limits), a venue copy without claim IDs, revision by patch where each change names its finding, a build to PDF, Word, LaTeX or HTML through Pandoc, a check of the built PDF's pages, words and required sections, and a default project layout.

• Research Work checks three things its guidance asked for: a claim that something is new cites the search behind it, every analysis variant a study plan lists is reported, and a plan can declare the models in its method with their exact snapshots (study.mjs check notes a plan that does not). A literature review's evidence table can name each study's weakness.

• Research Work aggregates results over several seeds and tasks: the interquartile mean, mean, median and optimality gap with stratified bootstrap intervals, the probability that one method beats another, and an interval for pass^k for one task or a suite.

• Research Work checks more of a study before its result counts: the plan names the method that computes each confirmatory rule, and a verdict computed by another method is refused; a model that labels the data counts as a judge; the arms compared get the same budget; a validity check that fails holds the analysis until you clear it; the plan records how each route of contamination is controlled; and the plan lists each source of variance. Weighted kappa takes quadratic weights and reports raw agreement beside it. A study with human participants stops for you and your institution.

• Research Work checks that a key claim's cited lines or passage actually show it: a separate reader sees only the claim and its evidence and answers supported, partial or unsupported with a quote, and the check counts the answers and holds the report until each partial or unsupported one is settled. Lookups no longer verify a correction notice, a reply or another part of the work, or a record whose year or first author differs; a row with no identifier can be searched by title for a candidate DOI, and a dead link is looked up in the Wayback Machine. Reports and drafts get more checks: a percentage that does not follow from its counts, wording stronger than a claim's evidence level or against a number's sign, an undated "latest", passages copied from a source without quotation marks, and sources never cited. Rechecks add Cohen's d from t and degrees of freedom against the sample size, and accept a corrected p. Text inside a source is treated as data, never as instructions. A quote beside a source in any other form is listed as not checked rather than passed, and a citation sentence counts for the claim named right after it. Model names such as GPT-4 no longer count as numbers to trace, search counts trace to the search ledger, the bibliography takes titles and authors from verified lookups, and a source ledger's Supports is checked against the claims that cite it.

• Research Work rechecks the numbers another study reports: whether a mean, a percentage or an SD is possible for its sample size (GRIM, GRIMMER, DEBIT), and whether a p value follows from its test statistic, in a table whose verdicts only the computation can write.

• Research Work looks sources up online when you ask: a DOI through Crossref with any retraction or correction notice, an arXiv ID, whether a link's page names the source, each matched on the title and an author, cached so a second run stays offline, and never marking a source fabricated because nothing was found. A code citation can be checked against the lines the agent actually read. A study plan's lock names the git commit that holds it when the plan is committed, and a plan is refused when it stops as soon as a result turns significant or gives a comparison no sample size.

• Research Work supports systematic reviews: screening criteria tagged by stage, so a criterion that needs the full text cannot exclude a study at the title and abstract; a model that screens counts only with a judge validation record that passes; two screeners' raw agreement, kappa and the disagreements a person settles; a PRISMA-style flow figure drawn from the search ledger's counts, never typed; each study's risk-of-bias tool and judgment in the evidence table; and stats.mjs meta, fixed and random-effects pooling with tau², I² and the Hartung-Knapp interval, matching statsmodels on the BCG vaccine trials. The paper guidance says what an abstract holds.

• Research Work's systematic-review checks hold tighter: a model screener's judge record must be for the rubric the model was given; a flow figure is recomputed from the search ledger it names, so a count edited by hand is refused even when its sums still add up; a hit both screeners decided cannot be left in another state without a person settling it; stats.mjs meta warns when the Hartung-Knapp interval is narrower than the studies' own evidence and gives the truncated interval to report instead; a randomized trial with a secondary cohort analysis is no longer refused RoB 2; and stats.mjs meta --method leave-one-out refits without each study in turn and names a study the pooled answer rests on.

• Research Work fits a review the agent runs: the reviewing agent can record itself as the screener, without a judge record, and the counts and flow say it screened alone; citation chasing is its own method, counted apart from the databases as PRISMA does; a query can carry the service's own count of records returned, so those not screened show in the flow; a claim above L1 citing a source whose recheck is a mismatch is refused when the recheck table is given; stats.mjs effect makes risk differences, log odds ratios and log risk ratios with their variances, unpaired or paired, in the form meta reads; and init project --kind review lays out a review's synthesis folder without the study and paper folders. validate now notes and ignores --sources on an artifact that does not read it.

• Research Work checks a report or paper with one command: research.mjs gate <folder> takes the rigor from the brief, runs every offline check that rigor requires on the files present (the brief, ledgers and register, the study's records, citations and numbers, a paper's draft checks and PDF, and at publication rigor every source opened and the citation-support answers), and prints each check as passed, failed or not run with why, then what is left before the work goes out. Evaluate Behavior says how a Research Work study plan's method, budgets, validity check, contamination and judges map onto its runs; Review Work's Judge Contract covers the citation-support reader; and the open choices of a research brief and a study plan go into the task's decision list.

• Research Work's gate says what it did not check: at publication rigor it names every claim the report or paper cites that has no support answer, for you to add or keep out with --unsupported-ok, which it lists as not checked; a paper's PDF counts as checked at publication only against the venue's limits or required sections it is given, and with none given it is not checked (below publication a PDF is shown without holding the gate); a passed check's notes print beneath it; a report that cites nothing is not checked; and a register with a confirmatory claim but no study plan fails. The packets for the support check can come from the report and the paper together. The gate finds a source's saved copy in the sources folder by its ID or pin, so quotes are checked without a --copy for each.

• Freeflow keeps an event log of what happens in each session's loop, on Claude Code and on Pi: session start and end, turns, model requests with their tokens by model and effort, tool calls with whether they failed, the exit code where the host gives one, how long they took, the paths a file tool named and a shell command's text, compactions and who ran them, workers started and stopped, and Freeflow's own actions. A line never holds a prompt, an answer, a file's content or a tool's output; a command's keys and tokens are replaced with [redacted] and it is cut to 200 characters. The log stays on this machine, in events/<session>.jsonl in the Freeflow home, which the store's Git ignores, and each checkpoint and task release commits a short summary of it into the task's folder (events/<session>.json). Track Work's events summary and events show read it, and events append is how the drivers write it. The events.enabled setting turns it off, in every scope.

• Freeflow says what it can do in each session. Each driver writes its claims for the requests Freeflow knows (pin, inject, forget, compact, checkpoint, rewind, route, spawn, send, wake, ask, block, sensors, timers): yes for what it carries out today, possible for what the host offers and Freeflow does not use yet, no for what the host cannot do, each with how or why not. /freeflow capabilities lists them on Claude Code and Pi, and Setup Freeflow's capabilities.mjs lists them for the agent (check <request> exits 0 only for yes) on every host, saying where no driver runs that only the session-start guidance arrives.

• Freeflow arriving in a session that is already running catches up at the next turn. When the plugin is enabled or updated mid-session, enabled is switched on, or a harness skips the session-start hook, what session start would have given (the guidance, the task menu, the window, the claims, the store's pull) comes at the start of the next turn, once, with a line saying Freeflow started mid-session; on Pi, a reload that brings Freeflow in, or enabled switched on, brings the menu at the next run. Each session keeps which steps of its start ran in the Freeflow home's sessions/<session>/start.json, so a reload or a normal session gets nothing twice; a step that fails is logged and tried once more at the next turn.

• On Claude Code, Freeflow's guidance (the core prompt, the Interaction Contract and the Working Method) is a section of the system prompt, so it is in every request and stays after every compaction; the session-start hooks still run, and their copies are left out while the section carries the text, so it is not sent twice. A resumed session keeps the prompt it recorded, so one recorded before this change gets the hooks' copies until its next compaction. pin is now yes in /freeflow capabilities on Claude Code.

• Freeflow on Codex does what Codex's hooks allow, as its mod does on Claude Code: after the session-start guidance, the task menu with your rules, taking back the task a resumed session held; a context row at 50, 60 and 70 percent of the window and the checkpoint notice near Codex's own compaction, added after the next tool call or prompt; after Codex compacts, the task's record as of its last checkpoint after Codex's summary; the event log; the store synced at each turn's end; and the hold released when the session ends, pushed at the next start. Its claims: pin, inject, checkpoint and sensors yes, block possible, the rest no. Approve Freeflow's hooks again in /hooks after updating. Checked with recorded hook inputs shaped by Codex's hook schemas, not in a live Codex session.

• Track Work's task release --no-push commits the release on this machine only, and the next store sync pushes it, for a session end that leaves no time for the network.

• Freeflow checks four rules before each tool call on Claude Code and Pi, and for now only warns: no change before an agreement, no change outside the record without an open Slice while a task is held, a reminder that a commit, push, tag, merge, pull request, publish or release needs your own yes, and a worker writing only what its brief's May write: line allows and never the task's record. The agent reads the rule, why and the way through, once per gate in a turn; the call runs as it would have. Each gate is off, warn (the default) or block in every scope (gates.agreement, gates.slice, gates.delivery, gates.delegation); under block the call is refused with the same text, and a delivery step becomes a question to you where someone can answer. The event log counts each would-fire, events summary prints them per gate and estimate --store adds them up, so you can decide from data when a gate should block. See Gates.

• Track Work keeps the gates' state in sessions/<session>/gates.json in the Freeflow home, written by the commands that change it (taking or releasing a task, an agreement's open or close, a Slice's start, pause, resume or close, a delegation's open or close). agree --outcome <text> records the agreement of a session that holds no task, with --exact-spec "<reason>" when your request fixes every choice, logged for a reviewer; delegate open --writes <glob> puts a May write: line in the brief's Scope.

• Delegation across sessions (Track Work): delegate open --session hands a part of a task to a separate session and prints its start command for Claude Code and Pi; the worker runs delegate join, keeps its progress.md with checkpoint --delegation and recovers with view bundle --delegation, and its session is refused every command that writes the record. Each delegation event is a line in the task folder's channel.jsonl, printed by delegate log; an accepted return's Left open choices join decisions.md; session status reports a Slice's Waits on with what came back. claim and release keep claims on paths in the store, delegate open --writes claims the worker's scope, and the delegation gate warns before a write to a path another session claims.

• Claude Code's mod runs a worker session as such: its notice asks for checkpoint --delegation, its compaction installs the worker's bundle, and its end releases its claims; when a delegation the current Slice waits on comes back, the coordinator gets one row naming it, and an idle interactive session is woken with it. Its notice to a subagent worker and the block of a worker's stop are logged in the task's delegation log.

• On Pi, a worker session's checkpoint notice asks for checkpoint --delegation, its compaction installs the worker's bundle, and its end releases its claims; when a delegation the current Slice waits on comes back, the coordinator gets one row naming it, and an idle session is woken with it (delegation.wakeOnReturn).

• Execute Work's delegation reference covers workers in separate sessions (the lead assigns every part; workers talk only to their coordinator), and when to message another session, what to send, and that a received message is information; Pi's Messaging skill points to it.

• Settings delegation.claimHours (how long a claim on paths lasts, 4 hours by default) and delegation.wakeOnReturn (whether a returned delegation wakes the waiting session, on by default), in every scope, on Pi's /freeflow settings screen and Claude Code's.

• The gates run on Codex too, through its PreToolUse hook: a warning reaches the agent before the call runs, once per gate in a turn, and under block Codex refuses the call with the gate's text; a delivery step under block is refused, since Codex cannot ask you. Codex does not run its hooks for hosted tools such as web search, so the gates do not see those. capabilities.mjs now lists block as yes on Codex.

• Review Work plans each review from the change itself: review-plan.mjs computes how deep it goes (Quick, Standard or Deep, with its tier, reviewers, rounds and the humans the policy asks for, and why) from the diff, the repository's review.depth rules read from the base commit, so a branch never supplies its own policy, the agreement's Review: lines and built-in triggers for security, stored data, CI and release files and a public interface found by content (a skill's name or description, a command, a settings key, a package's bin, exports or main). A Deep review is three reviewers who see none of each other's reports until all have written theirs, with one adjudication. Reviews are kept in the task's reviews/ folder, synced with the store, and check-adjudication.mjs --record binds each to the commit it reviewed, so review-status.mjs, and Deliver Work's delivery-state.mjs, say whether a review is on record for the head before a pull request opens. Until Freeflow's gates arrive, that check is the skill's, not enforced.

• Freeflow on Claude Code has a cost governor. After each model request it reads your plan's usage windows and the session's cost: on a subscription it holds the seven-day window to a daily pace (what was left of it when this day of the window began, over the days until it resets), and with a task whose plan predicts its cost (estimate --plan), the task to the plan's high end. At 80% of a cap the agent gets one row naming the cap, the use and the reset; at 100% one notice, or under governor.mode stop the ask to stop at its next safe point, checkpoint and ask you. governor.cap sets one cap of your own: a percent of the seven-day window, or dollars with an API key. Each response is a governor line in the event log, and events summary lists them.

• Discuss Work's drift.mjs --base <ref> lists the hunks of a change that no decision item's Shows at covers, those in code a feature file covers first, so the account at the end and a reviewer see the choices nobody agreed; choices.mjs return --base <ref> prints how many.

• On Claude Code, Freeflow keeps a status line under the prompt (the held task and its Slice or agreement, the context and its cycle, the weekly window, the open delegations) and a pane, /freeflow pane, with four views: Tasks (every open task, what needs you first), Agents (the held task's workers, sub-workers nested), Cost (this session, the task by model and effort, the plan's windows, the Slices left) and Decisions (waiting first). Its keys open, create, move and release tasks, view or message a worker and check a return, each running Track Work's own command and telling the agent in one line. pane.enabled and pane.statusLine turn them off; Track Work adds project list --json, delegate status --json and estimate --spent for it.

• Two-tier routing (SPEC-010): delegate open without --agent takes a worker's model and effort from the routing table you own, rules/routing.md in the Freeflow store (a project's own projects/<project>/rules/routing.md read first), by the work's --kind, --settled yes|no and --check scripted|tests|judgement, prints the Route line, and writes Settled, Check and Route in the brief; a row that asks you first is refused until the agent gives --agent after your yes, and no table, a table that does not parse, or no matching row is refused with the reason. A new store gets the default table: the cheap tier (Haiku on Claude) at xhigh for gathering, research, evals, reviews and settled builds, and the coordinator's own model at high, asked first, for the rest. estimate --plan and estimate --store print how many delegations of each kind, check and model were sent back, and why.

Changed

• Track Work's checkpoint --compact asks for Freeflow's compaction only where the session's driver claims it can compact (Claude Code's mod and Pi's extension do). Elsewhere it writes the checkpoint, leaves no request that nothing would answer, and says so: "No Freeflow driver here compacts (no capabilities for this session). The harness compacts on its own; after it, recover with view recover."

• Self-review is verification: checking your own change or document before you report it done is Verify Work's Check Your Own Result, with the self-review script at skills/verify-work/scripts/self-review.mjs (it was Execute Work's) and Review Work's lenses for the kind. Review Work means independent review in another context, and adjudicating its report.

• The design reference, how to shape modules, interfaces, state and failure, is Discuss Work's, where approaches are chosen; diagnose stays in Execute Work.

• Freeflow's words follow its design map: a context cycle (formerly compaction cycle) runs from a session's start or a compaction to the next compaction, and the Return (formerly hand-over) is where the agreed work comes back to you to accept. The cycle reads agree, build and verify, review and return. The skills, the scripts' output, the notices on Claude Code and Pi and the docs say so; choices.mjs return lists the choices you have not seen, and choices.mjs handover still works.

• Freeflow on Claude Code obeys enabled: with it off, its task menu, notices, context rows, compaction, task hold and store sync stop as well as the session-start context, and /freeflow settings enabled on brings them back from the next event. Every setting is now one row of one table, which the validators, Pi's screen and the settings script share; the configuration files accept an optional "v": 1, which a later Freeflow writes.

• Freeflow's messaging on Pi lists the task each session holds in the Freeflow store, with its project, and the inbound policy project delivers messages from sessions that hold a task in the same project.

• Freeflow compaction on Pi works as on Claude Code, through Track Work. One soft notice a compaction cycle comes before Pi's own limit (at 75% of the window, or a tenth of the window before Pi's trigger if earlier), after rows at 50, 60 and 70%; at a safe point the agent checkpoints its task with checkpoint --compact and ends its turn, and Freeflow replaces the conversation with the task's bundle and continues the run. With no task, a session summary takes the record's place, with or without a store. Pi's own compaction stays the fallback: once the agent has checkpointed, the bundle replaces Pi's summary; otherwise the bundle as of the last checkpoint and your messages since follow it. Where the Freeflow store exists, a Pi session gets the task menu and your rules with its first turn, the footer shows the task it holds, the store syncs after a run that changed it, and the hold is released when the session ends. Track Work's discussion list reads Pi's session file along its active branch.

• Track Work's planner sizes each Slice from the files it will add or change (Size: <n> files) and the measured cost per file of past Slices, so a large Slice is no longer planned as the median one. slice start records the work repository's commit (Base), slice close counts the files the Slice changed (Files), and slice size adds that count to Slices closed before. The correction starts from the first Slice with its actual, pulled toward none; a reading that found nothing no longer counts as a Slice that used nothing; and estimate --plan and Discuss Work's agreement lead with the cost as a range and say what it rests on.

• Track Work's recovery view and bundle open their checks with the task folder's path, so an agent after a compaction finds the files the record names.

• Write Docs' docs check says when a Verified at commit is missing because the clone is shallow, as a cloud session's may be, and how to fetch its history.

• Freeflow on Claude Code compacts only when the agent asks, with Track Work's checkpoint --compact: the mod answers the request once, at the end of that turn, with the record in place of the conversation, then starts the next turn. The notice at 75% reminds the agent to do so; a checkpoint without --compact, before a pause or a switch, never compacts; and the agent may ask earlier, at a boundary where the conversation holds mostly finished work.

• Discuss Work's agreement reply puts its Size line last, after Technical, so the work's size stands out.

• Track Work's guidance describes Schema 5 tasks: taking only the task your message points to from the session-start menu, the agreement in your words, Slices with one-line updates that point to their evidence, the recovery budget, the checkpoint at a safe point before a compaction or a transfer, and recovery from Freeflow's bundle. A task is kept when the work will outlast the current compaction cycle, which estimate helps judge, and the agent asks one question before making one, with where it goes: a project or none. Execute Work checks, when it sets the route, whether the work fits in what is left of the context. The store, projects and holds are part of its format reference. Schema 4's format and method, which Pi's Task Memory keeps, are in a reference of their own (skills/track-work/references/schema-4.md), and Pi's task-memory and compaction skills point to it.

• A stop on the route that you agreed, such as a commit, a review, a decision or a hand-over, is now called a return point, and the work agreement names it (in a Working Record, its Back at line); "checkpoint" means only Track Work's save before a compaction. Freeflow's core prompt, Execute Work, Deliver Work, Discuss Work, Research Work, Write Docs, Review Work and Write Skill say so. Deliver Work's rule against publishing Working Records names the Freeflow store's task folders too, and lets only Track Work's script sync the store, to your own private remote. Discuss Work's choices.mjs --record reads a Schema 5 task's decisions.md, and its catch-up the current Slice's update lines. Review Work's briefs say that reading files is inspection, not a check that needs May run.

• On Claude Code, Freeflow's checkpoint notice comes once a compaction cycle and no longer repeats every 5%: it asks the agent to keep working to a safe point (a finished step whose result it knows), then checkpoint and end its turn, and says where Claude Code would compact on its own. Before it, a one-line row shows the context's share at 50%, 60% and 70% of the window. The rows and the notice name the compaction cycle, counted for each session in the store and kept when it is resumed. A worker gets one notice in each of its compaction cycles.

• Evaluate Behavior runs four subjects at once by default, or one per two CPUs when arms run in containers; --jobs 1 runs one at a time. Its skill gives every eval one route: count the runs, check-tasks for a coding task, a pilot, --max-cost from the pilot's cost per run and your yes, the batch in the background, --reuse after a stop, and flagged runs held out until you clear them.

• Write Docs' docs check can move a stale document's Verified at itself (docs-check.mjs <docs> --stamp), so the document goes into the same commit as the code it covers instead of a commit of its own. Feature files, which only driving updates, are left alone.

• Write Skill tries a new or changed skill on a real task before measuring it: Evaluate Behavior's new Trial mode runs one agent that keeps a friction log, which Review Work adjudicates like a review. Evaluate Behavior now asks for your yes, with the run count and estimated cost, before any run that calls a model, unless the task's agreement already covers it, and never asks a measured arm for notes.

• Research Work's citation-support check judges the claim as the report states it: each packet carries the report's and paper's sentences that cite the claim, so a sentence that drops a condition is caught, and at publication every cited claim needs a packet, quoted or not. A paper's quote form "the exact words" [@S3] is checked like (S3), a verdict may quote one whole short line, and a quote's passage keeps its line breaks.

• Research Work's gate checks what it used to skip: a review's numbers against the result files its register cites, even with no study plan; a review's evidence table against the source ledger; and a report or paper given on stdin (--report -). A study or publication plan must have its method, budgets, contamination record and models before it is locked, and a lookup no longer verifies a "Part I" record for a "Part II" source.

• Research Work's guidance is in three references, one per stage (evidence, study, reporting), instead of seven, so a stage's guidance and its formats are in one file and a route opens one or two files instead of three or four; each artifact's format now sits beside the method that writes it.

• Write Skill explains why one capability skill that routes to its references and scripts (a trunk) beats many narrow skills, keeps a trunk's body to its routing table, common route and Rules, and asks for a design record per skill in the developer docs; Write Docs adds the skill design record shape under dev-docs/skills/.

• Write Docs keeps history in git: developer docs drop their Changes lists, and decisions cite the commit where they were made.

• Model judges follow one rule across Review Work, Evaluate Behavior and Research Work: Research Work says what a judge needs before its answers count, a judge counts as calibrated only with a passing judge validation record (repeatability included; an advisory review needs none), and by default the judge is a different model from the one it grades, another family being optional. Literature reviews and other research that needs checked sources now route to Research Work, which still writes its report in Write Docs' Research shape.

• Review Work's independent reviewers may run probes of the changed code on scratch copies by default, and a code Issue shows the command run and what it printed; the adjudicator reruns a Blocking code Issue's command before accepting it. review-packet.mjs finds the project's Review Rules when they are a ## Review Rules section of a Markdown file (check-brief.mjs refuses Review rules: none when one exists), points the reviewer at the base's copy of Review Work, reads a REVIEW.md from the base so a change cannot supply its own rules, takes Review 2's diff from the previous review of the same change when reviews of several changes interleave, keeps another change's brief that has not reported, and prints the correction diff's size for Review 2. Corrections that change what a check accepts or refuses justify a focused Review 2, and a new check-adjudication.mjs refuses a report until each item has an Accepted, Rejected or Open disposition with a reason (and refuses two items with one ID), and counts them for the Working Record's Review line.

• Freeflow's Codex hook delivers its guidance at a forked session's start too, as on Claude Code.

• check-adjudication.mjs refuses an adjudicated judgment the dispositions contradict: an Accepted Blocking item with Pass or Non-blocking. Freeflow's own sensitive paths move from its Review Rules into its .freeflow/config.json review policy: a Standard review for every pull request, Deep where a built-in fires.

• Verify Work's self-review.mjs says whether each requirement's check ran after the last edit from the session's event log where the harness keeps one: the last tool call running the check the requirements file gives (R<n> <text> :: <command>, or check: <command>), against later edits by the agent of the paths the requirement names. Where there is no log it reads check --id records as before, and the report names the source of each.

• delegate close --outcome "sent back" requires --reason brief|capability|scope, and a delegation's History entry keeps its Settled, Check, Route and Reason. Execute Work's delegation reference chooses a worker's model through the routing table and the Route line, and Review Work's reviewer model is the table's review row (the security-tier row for the security tier) unless review.model is set.

Fixed

• With every runtime prompt off, the hook hosts still deliver the review and skills lines, as the settings page says; they used to drop them. Setup Freeflow no longer calls skills an unsupported key, and the settings page names OpenCode as reading no settings.

• Freeflow on Claude Code no longer sends its "continue" prompt late. After its own compaction it prompts the agent to go on only when nothing else started the next turn: a notification or message queued during the compaction starts a turn that goes on from the record itself, and the prompt used to wait behind that turn and arrive after it, sometimes long after.

• Freeflow on Claude Code no longer loses a compaction the agent asked for with checkpoint --compact when queued input, such as a notification or a message typed during the turn, starts the next turn first: the request stays until the record replaces the conversation, the next turn end tries again, and a line in the conversation says when a compaction did not run.

• Track Work measures a Claude Code session that was resumed in another folder from its newest log, instead of whichever copy it found first.

• Track Work's recovery and Freeflow's compaction bundle find the files a task names in the repositories it changes, such as a skill or AGENTS.md, when the session runs outside those repositories: a pointer that is in neither the task folder nor the work repository is looked up in each repository the record's Space names, where the store last saw it on this machine. An always Recovery line that names no file now gets a line in the checks, instead of being left out without a word.

• Freeflow on Claude Code gives a session your rules at its start, after the task menu: the store's rules/ and those of the folder's project and of the task the session holds. Before, a session saw them only once it took a task and recovered it. Track Work's task here --rules prints them for any harness layer.

• Freeflow on Claude Code takes up a store added to a session that has already started, as a repository attached to a running cloud session is, at the end of that turn: the transcript that measures Slices, a pull, the scan for a task's repositories, and the store's file permissions, which it used to leave off for the rest of the session.

• Track Work's validate no longer takes a session's ID, a hex word after "session" in a Slice's update line, for a commit that does not resolve.

• Track Work's store init --remote <url> uses a folder that already holds an empty clone of that repository, as a cloud session has it, instead of refusing it.

• Discuss Work's choices.mjs validate accepts a decision list with no items yet, such as a new task's decisions.md, and its catch-up no longer lists a Slice's Predicted: and Measured: lines as work that ran.

• Track Work's checkpoint --input takes a labelled In flight line that says only none (- Pending: none) as no line, instead of refusing it; a plain line under Future Work is refused with the shape a proposed Slice takes; and a Schema 5 Slice accepts the Review gate line Review Work records.

• Claude Code no longer reports a failing hook ("Cannot find module '/hooks/adapters/gemini-session-start.mjs'") at every session start: it reads Gemini's hooks/hooks.json from the plugin's root beside its own hooks, and that hook now names its adapter so it resolves under both hosts and stays silent under Claude Code.

• Research Work's judge validation record accepts not applicable for Both orders when the judge rates one output at a time, so a rubric judge's record can pass; Review Work and Evaluate Behavior now say that review --calibrate gives agreement and kappa (the interval comes from stats.mjs), that a labelled judge is calibrated only with a passing record, and that an uncalibrated reviewer's verdict is weighed in adjudication, never obeyed alone.

• Evaluate Behavior's evaluator: a suite's decision cut short by the budget or a stop no longer claims "beats" or "worse" (its claim is none, reason cancelled, with the counts that ran and k the trials that completed); --jobs and --cpu-jobs hold even when a new start arrives as a slot is freed; the plan line also counts host-extension builds, which run on the host outside the seal; the transcript scan flags a host name with no dot, such as http://intranet, as an external network target (loopback and localhost stay internal), so more runs are held for you to read; judge calibration and agreement between two judges add linear-weighted kappa for 0-2 dimensions beside the unchanged kappa; and a decision or combined judge answer over a very long list of values no longer fails.

• skill-author compare --all-units lists every reworded unit that is not rule-like, under "Other reworded: confirm the meaning survived" in its JSON (otherReworded) and --markdown output, so the meaning check Write Skill asks for after a substantial revision can reach each one; the exit status is unchanged.

• Review Work's review-packet.mjs, run with --root from another folder, names the Docs and Review rules files relative to the repository instead of the current folder, so the brief it writes passes check-brief.mjs instead of being refused for paths that do not exist.

• Track Work's migrate converts a task record written before the one Recovery list: Defined by, Read on recovery, Read when and Carry lines become Recovery lines (always, not counted, always, when <trigger>), in place, keeping the old record in sources/record-before-recovery.md. Every other command refused such a record, so a task kept with an earlier Freeflow could not be recovered.

• Track Work's delegate check-return no longer takes a hex number inside an email address (the GitHub ID in a noreply author email), a UUID, or a folder name between two slashes of a path for a commit. Such a return was refused with "commit … does not exist", and delegate close --outcome accepted could not close its delegation. A commit the return names from another repository, such as a host's source the worker pinned, is named by the coordinator with --elsewhere <hash>=<owner/name> on check-return and close: it is not looked for here, the output names it, and the History entry records it on an Elsewhere line. Every other commit-shaped word is checked as before, a commit in a GitHub blob/, tree/ or commit/ URL included: refused when it is not in the repository or not on the brief's branch.

Removed

• Pi's compact_context tool, its result index (r12), the carried copies of your latest messages, and the compaction capability skill with its summary format: on Pi the agent checkpoints with Track Work instead, and /freeflow compact asks it to checkpoint with --compact.
• Pi's context reuse: tool results are no longer carried across a compaction; the bundle carries the files the agent names in its record's Recovery list. The Context reuse switch goes from /freeflow settings, and compaction.carry in a config still loads and does nothing.
• Cognitive Routing, Pi's Coordinator, Helper and Executor profiles: their context projection, the delegate_work, return_work, routing_unit and select_evidence tools, /freeflow profile, /freeflow resume, the Ctrl+Shift+R and Ctrl+Shift+A shortcuts, the settings rows and footer states, the routing prompt and its capability skill. A config that still sets cognitiveRouting is refused, saying the feature was removed and the key to delete, on Pi and the hook hosts. Pi now claims forget and route as possible. Routing entries already in a Pi session stay and nothing reads them. Handing work to other agents stays with Execute Work's delegation reference.

0.9.0 - 2026-10-24

Breaking Changes

• Freeflow has ten skills instead of twenty-five, and the Workflow skill is gone: its body reached the agent only when the agent opened it, which it rarely did. Its cycle (agree before building, build and verify, review and hand over), what authorizes work, and where to stop are now in the always-present core guidance as "How Freeflow Works", and each skill's description says when to use it, so no skill routes the others; the line telling the agent to open a skill by its subject rather than a keyword is gone. Workflow's other parts moved to the skill open when they matter: route preparation, re-entry when the basis changes, and Domain Skill Composition to Execute Work; work that grows, remedies that change what you own, and its Asking The User reference to Discuss Work; questions and "stop" mid-work to the Interaction Contract. Every skill that said "return to Workflow" names the skill that takes over. No removed or merged skill or command below has an alias: update links, scripts and commands that name them, including skills/workflow and skills/workflow/references/asking-the-user.md. How Freeflow Works maps each removed name to where its job went.
• Discuss, Agree Work and Decision Gate are one skill, Discuss Work (skills/discuss-work, /discuss-work); skills/discuss, skills/agree-work, skills/decision-gate and the /discuss command are removed. The agreement now runs before building, and the core guidance carries it: the agent reads Discuss Work at a task's first request, before its first tool call, and before the first change on a task that builds or changes behavior it sends one message with what it will do, where it stops, and your decisions, each with its default and why, then waits. It lists every choice the request, code and docs leave open, technical ones too such as names, messages and files. "Go" accepts every default, and a correction changes only the line it names. A question needs no agreement; an exactly specified change, or a run where no one can answer, counts as one, with its defaults recorded and reported; a request that merely looks clear no longer stands in for one. The choices are kept in one decision list through the task (sources/decisions.md beside a Working Record, where only the choices you answered become Decisions), self-review checks the work against it, and the final report shows only choices you have not seen. Discuss Work's first page covers the common path: exploring while what or how is open, the agreement, when the wait is skipped, choices during the work, asking one question, and accounting at the end. A learning action (an experiment or prototype that answers one question, shared with Execute Work) and keeping a discussion across context loss are references read only when needed.
• The Action Selection skill is removed. Its description matched almost every search or command and its body was almost never opened; its one rule that reached the work, keeping tool output small and saying when it was cut, is now in the Working Method on every host, and the rest repeated the Working Method or other skills. The /action-selection command is gone. No alias replaces it.
• Bypass is no longer a skill, and /bypass is removed with no alias. Discuss Work now says what it did: when you explicitly ask to skip an optional step, such as waiting for the agreement, a plan, a review or a record, the agent skips only that, takes its defaults and reports them, still asks before a hard-to-reverse choice, and changes no authority, checkpoint you selected, or claim. When that skip must outlast the conversation and a Working Record exists, the agent records it in the Work agreement.
• Commit Work, Finish Branch, Release Work and Launch Work are one skill, Deliver Work (/deliver-work); /commit-work, /finish-branch, /release-work and /launch-work are removed. Its first page routes by situation and carries a plain commit in full: inspect, stage only what is yours, write the message, check the result. Closing a branch (a push, a merge or pull request, keeping or discarding it), a release and a production launch each have their own page, read only when that route applies. The rules the four shared, such as each route needing its own yes, never staging Working Records or secrets, and inspecting what changed before retrying a failed step, are stated once, with one stop list and one report. The commit step says to fix conflict markers or whitespace damage in the content they belong to, never to edit content just to silence the check.
• Design for Depth, Simplify Code, Diagnose Failure and Migration Work are part of Execute Work (/execute-work); /simplify-code, /migration-work and /diagnose-failure are removed, and so are Execute Work's Execute Work Edges and Domain Skill Composition references and Design for Depth's Implementation Decisions reference: what they held that nothing else did is now in Execute Work, its design reference and Track Work. Execute Work's first page is enough for ordinary implementation: a table of situations, the rules not already in the always-present guidance, what to settle before the first edit, one method at a time, where to go back when the evidence changes, and when to stop. Five references hold the rest, each read only when its situation arises: design (settling a choice later work depends on, interfaces, module dependencies, a change that keeps touching many places, and state that must survive failures), a behavior-preserving cleanup, a failure with no known cause, moving users or data to a replacement, and code practices, now read only before adding edge-case handling or a comment that explains why, which points durable rationale to the developer docs. Track Work's Checkpoint table names the skill that handles each Checkpoint when it is due.
• The Handoff skill and its /handoff command are removed; writing a handoff is part of Track Work (skills/track-work/references/handoff.md), opened when work pauses or passes to another session or person. Its page covers where the handoff goes (asking when that would change privacy, durability or audience), what the next context needs, and the templates. Resuming from a handoff goes through Track Work's own recovery, which now also says to check a completion, review or commit claim against its evidence before repeating it, and what to do with a handoff and no record. The Working Record format's second Checkpoint table is gone: the format points to Track Work's table and still reads the earlier type names. Update links, scripts and commands that name skills/handoff.
• Write Spec and Write Plan are part of Write Docs (/write-docs), now for any document a reader acts on; /write-spec and /write-plan are removed. Its first page says how specs and plans (task artifacts kept beside the Working Record, drafted and then accepted) differ from documentation (repository files that change with the code), states the shared rules once (a document grants no permission, no invented requirements, proposals labelled as proposals, claims checked against their sources), the shared method (reader, sources, shape, self-review), and the header, status and source trail for specs, plans and decision records, with one status list for all of them: Draft, Reviewed, Accepted, Rejected, Superseded, Retired (it replaces Approved, Ready, Proposed and Abandoned). A decision record can be Retired, with the date and the reason, when nothing replaces it, and a durable decision that shapes how existing software works is also stated, with a pointer to its record, in the owning subsystem doc's Decisions section. Two references hold the rest: spec and plan shapes, with decision records as one of its sections, and documentation shapes, which holds the reader test for a new or rewritten subsystem doc or overview. Update links, scripts and commands that name skills/write-spec or skills/write-plan, or their spec-shapes, plan-shapes and artifact-standards references.
• Review Artifact is merged into Review Work, and /review-artifact is removed: use /review-work, which now reviews code and other finished work as well as documents that guide later work (specs, plans, designs, decision records, handoffs and skills). Its rules, review budget and judgments are unchanged; each kind keeps its own sources, job checks and lenses, and one reviewer contract and one adjudication reference cover both.
• Evaluate Skill is renamed Evaluate Behavior (/evaluate-skill becomes /evaluate-behavior), and its subject is now any declared part of the agent's setup, such as its skills, instruction files, model, or host extensions and settings. Update links, commands and scripts that name skills/evaluate-skill; the evaluator script is still scripts/skill-eval.mjs, and definitions stay under .skill-eval/.
• Evaluate Behavior definitions are schema 2, and schema 1 files no longer load: rewrite them in the new shape. A group is now a task (prompt, fixture, tools, expectations) plus a configuration (host, model, the skill under test, and optionally Freeflow and a runtime); arms.baseline and arms.candidate each overlay it, and component names the only paths where the two may differ, such as subject.source or model.thinking. A group whose arms differ anywhere else, or that declares a difference that is not there, is refused before anything runs, and component: [] runs the same configuration twice to measure run-to-run variation. extends shares one configuration file across groups. The authoring reference shows the full shape.
• skill-eval run refuses, before anything starts, a run whose inputs are not committed: the definition files, the fixture, runtime bundles, and working-tree skills and context must match the repository's commit, which the result then records. Add --dry-run to run anyway; the result is marked as a dry run and supports no claim. A configuration's host.version, when declared, must match the installed pi --version.

Added

• On Pi, Freeflow pushes a few lines of guidance at the tool call that needs them: Deliver Work's commit essentials on a git commit result (with a reminder of Write Skill's loss check when the commit holds instruction text), the key lines of Execute Work's diagnose method when the same test command fails a second time, a reminder to run Execute Work's self-review when a test passes after a change, and, on the first tool result of a run while Execute Work is not in the agent's context, a request to read it (a read of a Freeflow skill does not trigger it, so reading Discuss Work first is not interrupted). The Guidance notices row under Tool Execution in /freeflow settings turns them off for the session, for you or for the repository (toolExecution.guidanceNotices).

• Skills now come with scripts that put the facts a decision needs in front of the agent. Execute Work's touch-map.mjs answers what a change touches (entry points, readers, writers, scheduled code, covering tests and the developer docs covering each file, each block saying what it did not search), and self-review.mjs writes one report before the agent reports a change: status, diff stat, every changed existing test or fixture with its hunk, each new test and whether it fails on the base, and whether each requirement's check ran after the last edit.

• Discuss Work's choices.mjs checks the decision list and renders the agreement, the hand-over's unseen choices, and a catch-up after an unattended run (defaults taken, choices waiting, what ran).

• Deliver Work's delivery-state.mjs reports branch, upstream, uncommitted work, an operation in progress, worktrees (flagging the session's own), the latest tag, version and changelog in one read-only call; commit-state.mjs tells your changes from pre-existing staged work; release-preflight.mjs and push-route.mjs check a release and a simple push locally without performing them.

• Review Work's review-packet.mjs prefills a reviewer's brief, names the review gate's triggers and the round budget, and runs check-brief.mjs. Write Docs' plan-lint.mjs lists Plan steps that name no check, and artifact-check.mjs checks a Spec, Plan or decision record's status and source trail.

• Track Work's working-record.mjs view recover gives, in one call after context loss, the resume view, each defining artifact and Recovery source with its trigger and whether it resolves, and where live Git state disagrees with the record; validate now warns about Material updates pointers (files, commits) that do not resolve, and --strict fails on those an Evidence or Result line names.

• Evaluate Behavior can declare Freeflow's Tool Execution tools in a container subject on Pi: bash_background and monitor run their command in the subject's container (they need a container environment in every arm), the folder where Freeflow saves their output is readable there, stop_background stops the command in the container as well as on the host, and apply_patch may only name paths inside the workspace. Freeflow's own checks of a shell command see it as the model wrote it.

• Evaluate Behavior body groups on Pi can close and resume the subject's session between turns: input.resume_before names the turns to resume before, with runtime.session on.

• skill-eval check-tasks lists, for every group, what the task's copy lacks against the setting it came from: Git history (a workspace is never a repository), ignored files the fixture holds (a clone lacks them) or the task names (such as .env), and tools or network the task asks for but the subject lacks, with each arm's tools and network. It reports these without refusing, and still calls no model.

• Evaluate Behavior scans every run's transcript and flags reads outside the workspace and declared resources, attempts to reach an external network target, reads of instruction files (CLAUDE.md, AGENTS.md, .claude/) outside the workspace, and hidden-test or reference-solution text in the subject's answer or files. A flagged run stays in the results but is held out of every count and decision, and stops a pilot, until you clear it with skill-eval clear <result> --variant <arm> --flag <id> --reason <text>, which records your reason beside the run and recounts every aggregate that lists it.

• Evaluate Behavior configurations can declare network: "none" seals the subject, so its bash, declared commands and command graders all run confined with no network and none of your files, including the provider login on disk, and a group that would run declared commands or graders on the host is refused; "host" allows them on the host on purpose. Each run records sealing (what its code could reach and where each part ran), the plan line names arms whose code would run on the host, and a declared command no longer receives the path of Pi's login directory or a login variable.

• Evaluate Behavior checks that each run shows a model at work before grading it: a run the host reported complete but with no assistant message, zero tokens, or no answer and nothing written (as after a failed login) is reported invalid with its reasons, never as a fail; it counts in no comparison, metric summary or decision, and it stops a pilot. Tokens are the signal rather than cost, which is zero for real work on a model with no configured price.

• Evaluate Behavior groups can run any number of named arms against a reference arm (reference, default baseline), or a single arm that measures one setup with nothing to compare (pass^k, metrics and judged scores, no comparison claim). Two-arm groups keep working unchanged.

• A suite can declare a decision rule before it runs (the measure, the two arms, the direction, alpha and the minimum cases): the aggregate then reports "beats", "worse" or "no difference shown" from an exact sign test over cases, and only then says "beats". A rule's trials schedule adds trials only to cases still undecided, up to a maximum.

• Every run records metrics (duration, turns, tool calls and errors, tokens, cost, cache hit rate), and an aggregate summarizes them per arm with paired differences against the reference; a decision can use them as its measure.

• Evaluate Behavior run metrics on Pi add peakContext, the largest single request a run sent (input plus cache reads plus cache writes), and skillReads and skillReadTokens, every read of a declared skill's files or of the loaded Freeflow package's skills and prompts, re-reads included, with tokens estimated from bytes. Aggregates report them per arm with paired differences, and a decision can use them as its measure.

• Judged evaluation: a group's rubric is answered by declared judges for each run alone, blind to its arm (skill-eval review --rubric), combined by a declared rule, stored apart from run and grade files, with agreement between judges and calibration against hand labels (--calibrate). --swap-sample checks order on a sample of groups.

• Coding tasks: command expectations run hidden tests, a linter or a build on a copy of the agent's final work and pass on an exit code or named tests; a reference_solution proves a task solvable, and skill-eval check-tasks checks it with no model call, including that the unchanged task fails its new tests.

• Several participants in one run: a conversation with a simulated user who knows only its card, or a pipeline of stages that each see only what they declare (such as two independent reviews and an adjudicator); arms may differ in their participants.

• Host extensions can be built from an exact commit or a committed folder, arms may differ in declared environment variables, and run --source <arm>=<commit> measures an arm at another commit without editing the definition.

• A subject may use a shell only behind a declared isolation that the evaluator first proves confined with six probes, or in a container from a digest-pinned image through the standard docker command; when something is missing, the run says exactly what and how to install it, and never installs or pulls anything itself.

• skill-eval run gains --jobs and --cpu-jobs for parallel subjects and local work, --reuse to count identical earlier runs instead of rerunning them, --pilot <n> to try the first groups before the batch, and --results <dir>; skill-eval view --html <file> writes one self-contained page of a result.

• Evaluate Behavior guidance covers each eval mode, how to size and read results (claim classes, run-to-run noise, held-out cases, fair tasks, judge practice), and how to measure reviewers and other detectors on clean, seeded and real cases. Write Skill adds choosing what to change from evidence, a deletion trigger, and one authoring loop; Review Work's judge contract covers rubric judges, and its eval-definition review checks a definition before any run.

• skill-eval review --limit <name>=<chars> sets how much the advisory reviewer is shown (each response, tool-call arguments, each file, and the task materials in total; the defaults are unchanged). The review records the effective limits, and anything cut is recorded as the contract gap materials truncated, because the judge contract asks for full files.

• Adds Task Memory on native Pi as a preview, off by default (the Task Memory switch in /freeflow settings, or taskMemory.enabled). A session attaches the Working Records it works on; Freeflow delivers the focused record's resume view when it becomes the focus and after a compaction, reload, resume, fork or /tree navigation, and refuses record writes to records the session has not attached. Projects group tasks, with records under ~/.freeflow (or FREEFLOW_HOME), IDs such as my-app/task-003 and one owning session each; each task's resume view lists the project's other tasks, which the agent reads and searches when they bear on its work. Fan-out creates a child record with its own Git worktree and branch for a parallel session and gives a command to paste into a new terminal, where Pi offers to attach the child. Everything can be asked for in plain language ("list my projects", "open the retry task", "split the parser off"): the agent proposes, and anything that creates something or lets the session write opens a dialog for the user to confirm. /freeflow task and /freeflow project commands do the same directly. Task-memory steps and delivered resume views show as one line in the transcript and expand to the full text. The task_memory tool's description names Track Work and the Task Memory skill, so the tool leads to them.

• Track Work gains projects, child records, task IDs, worktree fan-out (with a start command for the host's agent) and record search as working-record.mjs commands on every host, and view entry <ID> to read closed History entries by ID.

• On Codex, Claude Code, Gemini CLI, Cursor, and GitHub Copilot, a prompts setting in .freeflow/config.json or .freeflow/local.json turns each of Freeflow's session-start prompts on or off: core, interactionContract, and workingMethod, each on by default. Pi always delivers all of them.

• A review setting in .freeflow/config.json or .freeflow/local.json, on every host, sets when finished work gets an independent review: mode is auto (the default: Review Work's risk check decides), off (the agent only proposes a review, with its reason and cost, and runs it on your yes) or always, and model names the model a reviewer runs on. The personal file overrides the shared one field by field, and auto there returns a shared choice to the default. A setting other than the default appears in the agent's Runtime State, so the agent follows it without reading the files. On Pi, /freeflow settings sets both in the Personal and Repository scopes: the Review row cycles the mode, and Reviewer model picks from your authenticated models.

• Task Memory works under automatic Cognitive Routing: the Coordinator handles task memory with you, Helper and Executor workers only read it and put any action they need in their report, and every profile receives the focused record's resume view, also after a worker compacts.

• Task Memory's taskMemory.autoApprove switches let the agent take some actions without the confirmation dialog: attach, create, env, fanout and projects, each off by default and set in /freeflow settings (Personal or Repository) or a config file. An action taken this way says so in the transcript.

• On Pi, the agent can put a choice that is yours to make into a dialog (ask_user) and continue on your answer in the same turn, instead of asking in its reply and stopping: one to four questions, each with two to four options and their trade-offs, the agent's recommendation first, a row for your own answer and a note per question. Esc closes it without answering, and the agent then does not act on that choice. Without a UI the agent asks in its reply as before. Task Memory's confirmations use the same dialog.

• With Tool Execution on, monitor watches a command's output and tells the agent each line it prints as it happens, so it can react to a log or watcher while it runs, including after it went idle. Lines within 200 ms arrive together; a monitor ends when its command exits, after its time limit (5 minutes by default, at most 30) or with stop_background, and one that sends more than 20 messages a minute is stopped.

• On Pi, Messaging (a preview, off by default: the Messaging switch in /freeflow settings, or messaging.enabled) lets the agents in your Pi sessions on this machine send each other plain-text messages: ask one session to tell, ask or answer another, and the reply comes back on its own. A message reaches the other agent after its current tool calls, or starts a turn when it is idle; a session that has had no prompt yet shows it and reads it with your first prompt. A message is information from another agent, never your instruction. Ask before delivering (messaging.inbound) can hold messages for you to accept: never (the default), from outside the repository's Task Memory project, every message, or refuse all. Sessions are addressed by session ID and shown by name, and each step is one line in the transcript. The send_message tool's description says to read the Messaging skill first.

• Task Memory links each repository in a project, and each child's worktree, to the project's store at .freeflow/project, so you can open and edit its records in your editor while the agent works. The link is kept out of Git through the clone's .git/info/exclude, and made again at session start when missing.

• Task Memory can remove tasks and projects: ask the agent ("remove the trial project") or run /freeflow task remove <ID> or /freeflow project remove <name>. A dialog always asks first, names what goes and which Git worktrees stay. Removed records move to ~/.freeflow/trash/, and only you delete them for good, with /freeflow trash empty; the agent cannot. Track Work's CLI has task remove and project remove for other hosts, and task numbers are never reused.

• Review Work reviews two more kinds of thing: a report or record of work done (a final report, a results note, a Working Record), checked claim by claim against the outputs and files it describes; and an eval definition (a case, suite, fixture or grader), checked before its runs are paid for, for whether a correct answer can pass, a wrong one cannot, and its defects are real. It also adds a judge contract for any model whose verdict on another agent's output is used as evidence: what to record about the judge, what it must be shown, and how to combine verdicts. Before a model reviews anything, the deterministic checks that apply run first, and an adjudicated review is recorded in the task's Working Record.

• Evaluate Behavior can run a subject with Freeflow loaded, built from an exact commit, with repository and personal settings declared in the configuration and checked by that build's own validator before anything runs; comparing two settings, such as Task Memory off and on, is one component. run prints its plan (subjects, models, Freeflow builds) before starting, and asks on an interactive terminal unless --yes is given. Aggregates now count grade errors and run states, report pass^k per check (whether it passed in every trial) and the per-trial pairs per comparison, and name the strongest claim the counts support. A file-text expectation can check one line, such as a review's first-line judgment.

• skill-eval review checks its reviewer against Review Work's judge contract: it shows the reviewer the task's fixture and each run's written files in full, hides run paths and arm names, records the reviewer's model family against the subject's, and with --swap reviews again with the runs in the other order to show whether position decided the answers.

• Evaluate Behavior body groups may give the subject Pi's ls, find and grep, confined like read: without a path they work in the run's workspace, and a path outside the evaluation environment is refused. A reviewer can then list the files it was given instead of guessing their paths. bash and powershell stay unsupported.

• An eval configuration declares the host's Pi extensions and settings: host.extensions names installed Pi packages by exact name and version (such as an Anthropic subscription's auth extension), and host.settings becomes each subject's Pi settings.json. Both are recorded with every run and may be the compared component, so a definition can evaluate any Pi setup, not only Pi's defaults. skill-eval review --configuration <file> gives the advisory reviewer its model, extensions and settings the same way.

• Evaluate Behavior can run its agents in Claude Code as well as Pi: a configuration with "host": { "name": "claude-code" } runs subjects, judges and simulated users in headless Claude Code, with only the declared tools, no settings, instruction files, MCP servers or slash commands from the machine, and the same confinement as on Pi. Bash runs only in a container environment, and the login comes from your environment (such as CLAUDE_CODE_OAUTH_TOKEN, which claude setup-token prints), never from a copied file. Each run records what Claude Code sent to the model, since Claude Code adds a line about itself and a note about the environment to every request.

• Evaluate Behavior accepts an optional group field "revision": "description-only": before any subject runs, the evaluator checks that the two target skills differ only in their frontmatter description, and refuses the group otherwise.

• A Working Record can hold a Work agreement: an optional ### Work agreement heading directly after Goal, for what done looks like, what the agent does without asking, what needs your yes first, where it comes back and how long that holds (each line led by Done when, Without asking:, Ask first:, Back or Holds until), with your reply quoted. init writes it only when its input has one, and validate rejects it when empty or anywhere else. Records without it stay valid, and nothing is migrated. In a record that has one, return conditions and actions that need your yes move there from Boundaries.

• Verify Work checks changes to existing tests: test-changes.mjs lists every test file, fixture, snapshot and shared test setup file that changed, moved or was deleted since a base commit, with the changed hunks, and the agent gives each one a reason (it keeps what the test checked, or follows a behavior change you agreed) or brings it to you before calling the work done; --new lists added test files. Its guidance also asks new tests to assert only agreed behavior, names signs of a test too weak to catch a bug, runs a bug fix's regression test on the unfixed code, bounds a speedup by the share of the run that changed, and treats a no-regression claim without a baseline as unproven.

• Write Docs covers a feature map: one file per user-facing feature in the developer docs, saying what the user sees and the exact steps and results that show it working in the running software, plus one shared guide for launching, checking, driving and cleaning up, and which steps cost a model call. When a project with code has no developer docs, the agent recommends creating them and waits for your yes, instead of putting that knowledge in AGENTS.md or CLAUDE.md.

• Verify Work uses a project's feature map when a claim needs the running software: it finds the feature files that cover the changed code, reads only those, the shared guide and its helper, drives the steps through the saved helper, and when a step fails decides whether the steps drifted, miss the claim, or the product is wrong. A product bug is reported, never written into the steps. Corrected steps are saved with the change when your agreement covers docs, and proposed otherwise.

• Write Docs' docs check gains --covering <path>: it lists the documents whose Covers header includes each path (the file, or a folder holding it), with the commit each was verified at and whether it is current or stale, so a change can find the docs it should reread. Without document arguments it searches the project's docs index, and it reports how many documents have no Covers line.

• Write Docs has a default developer-docs layout for a project that has none (dev-docs/ with an overview, then subsystems/, features/, guides/ and adr/ as each is needed), proposed to you rather than created; a project with its own docs keeps them, found in the order dev-docs/README.md, ARCHITECTURE.md, a README.md in docs/. It also says which kind of knowledge belongs where: developer docs, instruction files, the task's record, or your host's memory.

• Verify Work can set up a feature map: when you want a tested way to check your software live, the agent studies the repository and writes a feature map in your developer docs (one file per user-facing feature, with the exact steps and the results to expect), a shared guide, and a helper script that launches the software in an isolated run, drives it the way a user does, keeps evidence, and cleans up. It drives every step it writes before calling it verified, marks the rest unverified, and later rechecks the map feature by feature when you ask, reporting a product bug instead of editing the steps to pass. Steps that call a model or another paid service run only with your yes, and the helper starts the software without credentials otherwise. Verify Work proposes it when a claim needs the running software and no recipe exists. This lives in Verify Work's feature map reference, not in a skill of its own.

• Evaluate Behavior pipelines can hand a stage's whole workspace to the next: sees: ["<stage>.workspace"] starts that stage in a copy of the earlier stage's final workspace, binary files included, so it can run what the earlier stage wrote. <stage>.files still delivers written files as text to read.

• Before any container starts, Evaluate Behavior checks that your container engine shares the folder the workspaces live under, and refuses with the folder and the fix when it does not. A VM-based engine such as Colima shares only your home folder by default, so a workspace elsewhere (check-tasks uses the system temp folder) used to arrive empty and fail its graders for no visible reason.

• Execute Work covers one mechanical edit repeated across many sites: the agent edits the first site by hand, writes a script or codemod, checks that the script reproduces the hand edit on that site, then runs it on the rest and points to the script in its report so a reviewer can rerun it. A few sites, or sites that each need their own decision, are still edited by hand.

• skill-author compare reports what a revision of skills, references, runtime prompts or AGENTS.md no longer says: with no arguments it compares the working tree, uncommitted edits included, with where the branch left the default branch, or two named refs, or a folder copy (--base) for text kept outside Git. It lists every bullet, step, table row and sentence that was dropped, moved or reworded, and exits nonzero while a dropped rule (under a Rules heading, a numbered step, or a never, always, must, only, do not or stop sentence) has no verdict in a --verdicts file. Reasons (because, so that, otherwise, why) are protected like rules, and --all-units needs a verdict for every unmatched unit in a substantial revision. skill-author validate now lists link cycles among the references a skill reaches, and with --routing-map <file> checks that the map's row for the skill names the same sibling skills and resources its SKILL.md links.

• Write Docs' docs check takes --driven: a covered change counts even when it was committed with the document, for feature files whose verified commit is the last live drive, so editing a feature file's text does not count as driving it.

• /freeflow settings has Runtime prompts and Skills sections. Each row is a master switch (prompts.enabled for all three prompts, skills.enabled for every skill but Setup Freeflow), with Each prompt and Each skill under it opening a switch per item (prompts.<name>, skills.<name>). On Pi an off prompt is left out and an off skill is not loaded, and its command says it is off; Codex, Claude Code and the other hosts already read prompts and now also tell the agent which skills are off, since they load plugin skills themselves. This brings back the switches 0.7.0 removed, with skills.enabled valid again.

• Every setting has a row in all three scopes of /freeflow settings: Session now also has Review, Reviewer model, Ask before delivering, Auto-approve, Runtime prompts and Skills, and a test fails when a setting is missing from any scope.

• Verify Work points at the project's feature map: a claim about what a user sees in a feature a feature file covers is checked by driving that file's steps, found with docs-check.mjs --covering <path> --driven. Execute Work's self-review report lists the feature files covering the change and whether each was driven live since its code changed.

Changed

• Every skill's description is broader: it names the requests each of its references and scripts serves, in the words a request would use, and drops the "Not for" exclusions, since a skill read when it was not needed costs less than one missed when it was. The bodies of Execute Work, Discuss Work, Review Work and Write Docs list their scripts in their routing tables. Write Skill now says to keep a merged skill's triggers in its owner's description, to write as long as recall needs up to the host's 1,024-character limit, and to add an exclusion only when the read would do harm.
• The runtime prompts and the skills are one layer. Core's cycle names, at each step, the skill that holds its method in the words that skill's description uses, then the references and scripts its routing table gives for common moments, and says to read the skill's whole body before acting, even for a small change; the method itself lives only in the skills. Outside the cycle, core names Track Work (memory beyond the conversation, and its handoff reference) and Evaluate Behavior (before writing or running an eval), read when their situation comes up at any step. The Working Method keeps its five rules and Keep output small, and gives each step a one-line habit that names the skill, reference or script holding it; the evidence method it held moved into Verify Work, and reading the request and diagnosing into Execute Work.
• The agent reads Execute Work before its first tool call on a task, even a small or read-only one, instead of before its first edit: reading, searching and diagnosing are Execute Work's work too. Discuss Work is read at a task's first request.
• On Pi, Freeflow is developed and tested against Pi 1.4.0 (was 1.0.1); Pi 0.99.1 or later is still supported. When Pi compacts on its own, Freeflow now asks Pi's summarizer to keep the summary under 8,000 tokens, the limit an agent's own summary has: from Pi 1.4.0 that summary is no longer capped by Pi's reserve. Cognitive Routing's tools stay inactive until routing turns them on, like Freeflow's other tools.
• Evaluate Behavior's authoring references no longer restate the field rules its loader enforces with an error naming the field; they point to skill-eval check-tasks, keep the rules needed while designing a group as one line each, and keep meanings, defaults and choices.
• Evaluate Behavior checks expectations and a suite's decision when the definition loads, so skill-eval check-tasks, run and npm run check:eval-definitions refuse them before anything is spent, where before most became grade errors after the subjects were paid for. A kind in a group type that cannot grade it (such as response-text in a description group or skill-read in a body group), a variant that is not an arm, a turn the input does not declare, a value its grader rejects, or comparison members that are not one check is refused; so is a decision that could only exclude cases: a group without a decision arm, a measure recorded in one decision arm but not the other, an unknown metric, or a measure no group records in both arms. A group that records the measure in neither arm, such as a control case, still loads. An unknown expectation kind still loads and becomes a grade error.
• Evaluate Behavior names the group's file when a suite's group fails to load (group <id> (<file>): <reason>), in each check-tasks line, and when a reference check refuses a run.
• Write Skill has new rules for shaping skills: a skill's main file must be enough for the common case, with a routing table first and a reference only for a narrow, large situation; a script or tool output is preferred to prose that may never be read; skills that do one job split by type are merged; a removed or merged skill gets no alias. Before committing a substantial revision, the agent runs skill-author compare and settles every rule it no longer states, which replaces snapshotting the old package by hand. Its five references are now two: Placement And Dependencies (where text lives, references, scripts and how skills depend on each other) and Activation And Wording (when a skill is read and how its text reads); update links to the old reference files.
• Cognitive Routing's skill is split by role: the skill keeps what every profile shares, and the Coordinator's method (with one section per delegation mode) and the workers' method are the references coordinator.md and worker.md, replacing helper-mode.md, executor-mode.md and both-mode.md. Under automatic routing each profile now reads the skill and its own reference before its first command or edit, and Freeflow refuses those calls until both are in view; a worker reads about 2,200 words instead of 3,700. Update links to the old mode references.
• Setup Freeflow is one skill file: its activation-contract and host-setup references are folded in, with the unsupported config keys in one list. Update links to skills/setup-freeflow/references/.
• Rules repeated across skills keep one owner: what counts as a choice that is yours is defined once in Discuss Work, which now also owns the self-review decision check; the others point there. Verify Work's two report shapes are one.
• Review Work, Verify Work and Evaluate Behavior state each rule once and keep fewer, larger references, one per situation. Review Work's review gate is now in the skill itself, and its references are work.md (now with the security risk lens and the work reviewer's brief and instructions), artifact.md (now with reports and Working Records, and the prompt for any independent review that is not of work), adjudication.md, and evals-and-judges.md (eval definition review and the judge contract); reviewer-contract.md, review-gate.md, report-and-record.md, security-risk-lens.md, eval-definition.md and judge-contract.md are gone. Verify Work's integration, browser, performance and project-recipe references are one runtime-evidence.md. Evaluate Behavior's core is shorter, opens with a routing table, and has five references: design-and-measurement.md, authoring.md (the definition schema), coding-tasks.md, conversations-pipelines-judges.md and running-and-evidence.md. Update links to the old reference files.
• An independent reviewer runs only what its brief's May run line names, by default the project's declared checks (tests, build, typecheck) in its own copy, and Verify Work now counts that line, like your request, as covering the checks it runs. A report or Working Record is reviewed as an artifact.
• An independent reviewer of work is now briefed with pointers to its inputs (the Working Record, the covering dev docs, the Review Rules, the diff range, the builder's evidence, what it may run, and where to write its report) instead of a long prompt with everything pasted in. It reads them and the reviewer instructions itself. A new script, skills/review-work/scripts/check-brief.mjs, refuses a brief missing a line or naming a path or commit that does not exist, and the agent runs it before dispatching. In a 135-review trial this found the same defects as the pasted prompt at about 16% lower cost per review. Artifact reviews are unchanged.
• The hand-over, Deliver Work's pull-request description or the final report, now carries what the agreement said done looks like against what was done, the choices the work made that nobody agreed to, each check run on the final state with its result, and the review outcome with every Rejected finding and why, built from the Working Record when there is one.
• On Pi with Tool Execution on, the Runtime State lists the Freeflow skills already read in the context (from the next prompt on, and not under routing projection), and a compaction summary names the skills read in the cycle it ends.
• Freeflow's always-present guidance now tells the agent to read a project's developer docs index and the docs covering the code before changing or judging it, so behavior the docs record as intended is not "fixed" as a bug, and to keep what it learns where it lasts: task state in the Working Record, how the project works in the developer docs, and only agent rules in AGENTS.md or CLAUDE.md. A resumed session, or a new message after a pause, no longer counts as context loss while the conversation is still in context, so the agent keeps using the skills it already read instead of reading them again.
• Agents propose and keep the Work Agreement. When the outcome, scope or endpoint is unclear, the agent says what it will do, what it won't and when it comes back, and asks once; an unanswered proposal is not agreed. The agreement grows step by step: at its edge the agent reports and proposes the next step. It is kept in the lightest place the next context reads: the conversation, the compaction summary (a new Work agreement heading in the summary for work without a record), the Working Record's Work agreement section, and for long or unattended runs an exchange log in the task's sources/. After a compaction or a new session the agent checks the recovered agreement against your latest direction before acting on it. A narrower instruction such as "just diagnose first" holds until you lift it, also after a compaction, and when you change direction the agent updates the Working Record's agreement before continuing. At the edge of what you agreed, it ends with the next step as a question.
• Write Skill now also covers other text an agent reads and acts on: instruction files such as AGENTS.md or CLAUDE.md, system or runtime prompts, tool descriptions, subagent briefs and judge prompts. Its method applies to them as to skills, apart from what concerns a skill package (the description, resource files and validate); Evaluate Behavior returns revisions of instruction files to it.
• Every judge, adjudicator and simulated user sees run material inside fenced blocks with a fixed rule that it is evidence, never instructions; text in a run that tries to steer the verdict is reported, not obeyed. Judge prompts changed, so earlier calibrations do not carry over.
• Review Work's Rule against chasing a Pass now reads "Never repeat a review merely to obtain Pass"; the old "Never review until Pass" read literally as forbidding review before a Pass.
• Review Work judges from evidence the reviewer can recover itself: when it can run an authorized check or read the code, it judges from what it observed, so a check the author skipped and the reviewer has since run is no longer reported as Needs evidence. On Haiku this let correct changes proceed in 91% of reviews instead of 77%, with defect detection unchanged.
• Track Work recovers a Working Record after context loss from its resume view, which now ends with a one-line index of closed History, and opens only the History entries the next action needs, instead of reading the whole record. On a long task this loads a fraction of the record.
• Codex, Claude Code, Gemini CLI, Cursor, and GitHub Copilot now receive Freeflow's Working Method (the rules every task keeps, a one-line habit for each step naming the skill, reference or script that holds its method, and keeping output small) at session start, as Pi already did. It adds about 600 words to the session-start context.
• On Pi, Freeflow's tools drop the freeflow_ prefix, which models confused with /freeflow commands: Cognitive Routing's freeflow_delegate, freeflow_return, freeflow_unit and freeflow_project are now delegate_work, return_work, routing_unit and select_evidence, and freeflow_compact is compact_context. Sessions saved earlier keep working: their history keeps the old names, and routing and compaction still read it.
• On Pi, a background command's exit and /freeflow compact now reach the agent as Freeflow's own messages, shown as one-line rows, instead of as messages from you. Freeflow's part of the system prompt now stays the same on the turns they start; working around the Pi issue that dropped it was why these were sent as your messages.
• /freeflow settings on Pi reads at a glance: each capability's switch is its section's row (no more "Enabled" rows under every section), values read on in green and off in red, marked (inherited) when the tab you are in does not set them (the help line says from where), and a setting whose section is off is greyed with a line saying it takes effect once that switch is on, while it can still be set up. Sections run Freeflow, Compaction, Tool Execution, Task Memory, Messaging, Cognitive Routing. Pi's footer reads freeflow: on, or freeflow: on (all capabilities off), instead of freeflow: active; with Cognitive Routing on it shows routing's profile, control and mode. Settings lists every setting, its key, values and default, what Freeflow turns on by default, and how to read the footer.
• Tool Execution is on by default on Pi whenever Freeflow is enabled: its working guidance, file tracking, clearer edit errors, apply_patch, background commands and monitors. Turn it off with "toolExecution": { "enabled": false } or in /freeflow settings. Task Memory and Messaging stay off by default.
• On Pi, Freeflow's notices to the agent (compaction, background exits, monitors, changed files, /freeflow compact) are marked with a <freeflow-notice> tag instead of the [Freeflow notice, not from the user] prefix; Pi gives the model every such message as the user's, so the tag is what tells it otherwise. Your own messages that compaction carries over stay yours: they are quoted inside the notice in <user-message> tags, which nothing else in it can open or close. Compaction's warnings and recovery message, and the changed-file notice, now show as one-line rows that expand, instead of the full text.
• Evaluate Behavior runs every subject and reviewer in its own home, temporary directory and Pi agent directory, with only the declared model's provider login copied in and removed when it exits. Your own Pi settings, such as the default thinking level, retries and compaction, no longer affect eval runs; Pi's defaults and the definition apply instead, so results from before this change may differ for that reason. A login close to expiry is refreshed once, by Pi itself in your own agent directory, before the batch and again whenever one has under 30 minutes left, so no run refreshes and rotates its copy and you are not asked to log in again unless the refresh itself fails.
• Review Work's independence rule now says what the research supports: an independent review needs a separately selected reviewer in a separate context, repeating a review with the same model adds no independent vote, and a reviewer from a different model family changes what gets flagged without a measured gain in real defects found. Reviews record the reviewer's model and family.
• Evaluate Behavior rejects, before any subject runs, an expectation field its kind does not define (a misspelled field was silently ignored before) and a group with no expectations and no review questions. A run whose selected checks are all unavailable now exits nonzero, because it observed nothing.
• Verify Work's performance guidance asks for more before a comparison is trusted: write the expected claim sentence before measuring, count failed and non-success results, confirm the timed work actually ran, name no winner against a side left on default settings, and alternate the sides over at least five runs each, reporting median and range. A claim that nothing visible changed needs an image diff against the saved baseline.
• Review Work decides at the end of the agreed work whether an independent review runs, by a review mode you can set as "review": { "mode": ..., "model": ... } in .freeflow/local.json or .freeflow/config.json. With no mode (auto), the agent dispatches a review when the change touches security, auth or secrets, data loss or migrations, CI or release files, a public interface, a path your Review Rules mark sensitive, or anything your agreement names; off proposes such a review with its reason and estimated cost and runs it only on your yes; always reviews every time. The agent records that decision, and each review's outcome counts, in the Working Record. Its self-review now lists the choices the agreement did not settle, marking which ones are yours to decide, and justifies every change to an existing test, fixture or setup. Reviewers may run the project's read-only checks (tests, build, typecheck) in their own copy when your saved evidence is missing or unconvincing, tag defects the change did not introduce as Pre-existing (never blocking), report a defect's class and where else it occurs, and in rounds 2 and 3 review only what changed since the last round. A rejected security finding goes to you. Briefs and reports are kept in the task's scratch/reviews/ until you delete them. A claim that a change is safe now grades how its one deciding fact is known, from asserted to reproduced in the app. Freeflow's core guidance names the path from self-review through the review gate to the hand-over.
• Execute Work's design reference looks for designs where the obvious edit from one file is wrong for the rest: state with two writers, two supported ways to do one task, internals importable from outside their module, and lists kept in step by hand. When two writers share one file, key or record, it first asks whether each can write its own and the results be combined when read, and serializes them only when one shared target is required.
• Execute Work's diagnose reference asks, before a fix adds a guard, whether the failing state is allowed at all, and corrects what produced it when it is not; once the cause is supported, it looks for the same fault elsewhere, and when the deciding fact was hard to find it proposes a cheap always-on signal that would have shown it. For performance it reduces a large profile, trace or heap snapshot to a queryable form before reading it, treats a frame without a source mapping as not yet a diagnosis, and tries the cheapest kind of fix first, from dropping unneeded work to making it faster.
• Deliver Work gives a pull-request description a shape when the repository has no template or convention: a short briefing that says why the change exists, what changed, its scope and what it leaves out, what else it could affect, and how it was verified. A repository's own template or convention still comes first.
• On Pi with Tool Execution on, each of Freeflow's tools now says when to use it at the start of its own description: bash_background for servers, watchers and commands over two minutes (shorter ones stay in bash), with no polling of its output file; monitor only to act on lines as they appear, and bash_background for a single ready or finished signal; stop_background once nobody needs the command. apply_patch is for several files, or for adding, deleting or moving files with other changes, and edit for one existing file; its description used to say to use it for any edit, against the prompt. The Tool Execution prompt section drops the lines these descriptions now hold, so the always-sent text does not grow.
• Each skill's description now says when to use it in plain words. Task Memory's drops its "on Pi" preamble, since Freeflow lists it only while it is on. With the cycle in the core guidance, fifteen fewer descriptions and broader ones for the ten that remain, the always-present text on Codex and Claude Code (the three runtime prompts and the skill descriptions) goes from 3,211 to about 3,350 words (wc -w); on Pi with every capability on it is about 5,550.
• The Working Method has a new "Keep output small" section for every host: cap searches and command output, say when output was cut (a capped result does not show that nothing else matched), and save long output to a scratch file and query it instead of rerunning the command. On Pi, Tool Execution's prompt no longer repeats this, so it is stated once. When the agent lists what a change touches, it now decides for each thing whether it changes too because the goal needs it, or whether its users must still get exactly what they get now; the request not mentioning something is no longer a reason to leave it out.
• Under Cognitive Routing, the Coordinator takes names, messages and other contracts that the request and repository leave open to you before delegating, instead of fixing them in a worker's assignment, and writes your own decisions and changes to the Work agreement into the Working Record itself, so they are no longer held as "noted, not recorded" until a worker returns.

Fixed

• On Pi 1.2.0 and later, /freeflow resume of a worker's assignment sent its first request on the Coordinator's model: Pi now prepares runs an extension message starts, and Freeflow prepared the resumed run a second time, which returned control to the Coordinator.
• On Pi 1.2.0 and later, a run started by a background exit, a monitor event or another session's message dropped the system-prompt sections other extensions set only for prompts (such as Pi's MCP server list), which changed the cached prompt; it keeps them again. Freeflow's own sections on such a run now follow what Freeflow set for it, so a change made since the last prompt reaches that run.
• A Freeflow skill command (/review-work and the others) entered while Pi was working, and on Pi 1.2.0 and later also while a run was starting, failed with "Agent is already processing"; it now waits and runs when the current work ends.
• Evaluate Behavior refuses host inside a configuration's runtime. It was accepted and overrode host.name for the subject while the run used host.name, so one group could run on two hosts; the host is configuration.host.name alone.
• Evaluate Behavior: a Pi run in which an extension starts a turn between prompts (Freeflow's notice that a background command exited or a monitor printed) is recorded in the turn before it; before, it ended the run as a protocol error. A command Pi stops in a container (a timeout or abort) now stops in the container too, and a write to a path starting with ~ is checked at the home directory it resolves to, where before it could write outside the workspace.
• Evaluate Behavior: in a container environment, the subject's bash and its file tools now agree on paths. Bash ran at the container's workdir (such as /testbed) while Pi reported, and its read, write and edit tools used, the workspace's host path, so an edit to a /testbed path failed with ENOENT and bash could not find the stated working directory, pushing subjects to rewrite files through bash. The workspace is now mounted at its host path, where bash and declared commands start, and workdir is a link to it, so the image's references to it, such as GIT_WORK_TREE, still work. An image must now have its workdir empty or absent.
• Evaluate Behavior: in a container environment, the subject's bash can run its skills' scripts. Each declared skill, context file, runtime resource and Freeflow's package is mounted read-only in the subject's container at the path the subject was given, so a command such as node <skill>/scripts/test-changes.mjs works; before, only the workspace was mounted and the path did not exist.
• Evaluate Behavior: a link the subject makes in its workspace, such as a CLI an installer links into a scratch prefix, is recorded as a link with its target and never followed, instead of failing the whole run as infrastructure and losing its transcript. A fixture's or skill's relative link is now copied as it is; it used to be rewritten into an absolute link and refused.
• Evaluate Behavior: --reuse can count a run made without it. Every complete canonical run is now indexed; before, only runs made with --reuse were, so a pilot run on its own was run again as a new trial.
• Evaluate Behavior: each result's summary.json records its own cost (cost.spent, with how many subjects ran and how many have no measured cost, including a run that used tokens at a cost of 0, as on a model Pi has no price for), and an aggregate lists each trial's cost. A trial's budget.spent used to be the whole run's running total, which read like that trial's own cost; the summary now names it budget.runTotal.
• Track Work: creating the first inline task record works in a repository whose only matching ignore rule is directory-only, such as .freeflow/*/ in a fresh clone of Freeflow. Before, it failed with "Record path is not ignored by Git" because the tasks folder did not exist yet.
• Evaluate Behavior: in a container environment, a subject's declared commands (run_command) run in its container, as bash does, instead of on the host, and the container starts for a group that declares commands without bash; graders already ran in the image.
• Evaluate Behavior: judges and the pairwise reviewer run with the evaluator's Pi defaults (automatic retry and compaction off) under their declared settings, as subjects do.
• A trial aggregate counts a trial whose grade file is unreadable, or a check that could not be graded, as unavailable for that check, so a check no longer reads "passed in every trial" over fewer trials than ran.
• Cognitive Routing no longer trusts an entry Pi holds in memory but never wrote to the session file just because the current branch matches the file; after such a match, moving to that entry's branch is blocked until the history can be verified, instead of proceeding as if it were saved.
• Cognitive Routing: when the Coordinator requests an evidence recovery while an assessment waits for new user input, the assessment keeps waiting for that input after the recovery returns, instead of resuming on its own and skipping where unseen evidence should be placed.
• After Pi compacts on its own, Freeflow's next compaction keeps the files read or changed in the part of the history Pi kept unsummarized in its session-wide file lists; before, those files dropped out of every later list.
• Compaction notices and carried files: a Coordinator under projection is told at compact now that Pi also compacts when a request overflows the model's window, as other agents are; a carried file that ends with a newline no longer gets an extra empty numbered line, and a carried file whose last line looks like Pi's partial-read note is numbered like the rest.
• The prompt-cache keep-alive no longer replays a request on Sign in with ChatGPT after you switch to it from an API key on the same model during a hold; the route rejects replays, so the hold now stops instead of sending one.
• Track Work works in a repository reached through a symlinked directory (such as macOS /tmp or /var). Before, it refused every command there because its Git ignore check compared a symlinked path with Git's resolved one.
• Claude Code now receives Freeflow's whole session-start context. Claude Code caps each hook's context at 10,000 characters and shows longer output only as a short preview, so Freeflow now delivers each prompt through its own hook, and also at the start of forked sessions.
• Codex now runs Freeflow's session-start hook. Since 0.7.1, Codex loaded Freeflow's skills but none of its hooks, because it ignores hooks in a plugin that carries the Agent Plugins manifest the other hosts need. Codex now installs Freeflow from its npm package, which leaves that manifest out, and the hook raises Codex's context limit so the whole context fits. After upgrading the freeflow marketplace, approve the Freeflow hook in Codex's /hooks; Codex skips it until you do.
• Freeflow no longer goes silently inactive on Codex, Claude Code, Gemini CLI, Cursor, and GitHub Copilot in a repository whose .freeflow/config.json or .freeflow/local.json has toolExecution or compaction settings, such as those written by /freeflow settings on Pi. The session-start hooks now check configuration with the same validator as Pi, and an existing invalid configuration file now produces a short configuration error naming the file instead of no Freeflow context.
• /freeflow settings showed Cognitive Routing's Context projection as off (default); routing turns projection on by default, and the screen now says so.
• /freeflow settings offered every thinking level for a Cognitive Routing preset (off to max) on any reasoning model; it now offers only the levels Pi's model data gives that model, such as low to xhigh for grok-4.7.
• /freeflow enable and /freeflow disable reported success even when .freeflow/local.json or a session override still decided otherwise, since they write only the repository file. They now say which setting still wins.
• Under Cognitive Routing, a Coordinator in executor mode could run commands and edits itself because it never read the routing skill, and after a compaction neither profile read it again. Each profile's commands and edits (also from codemode) now wait until it has read the skill, and the refusal names the file to read.
• With Cognitive Routing on, starting Pi with --model or --thinking holds routing until /freeflow profile auto, as designed, but the footer gave the reason as acknowledgment_unclassified; it now reads startup_selection, and the Cognitive Routing page explains the hold.
• Under Cognitive Routing, a worker whose run ended without handing its work back left the session waiting: the Coordinator saw the assignment as still in progress. The Coordinator is now told the run ended and how to continue, and the worker is told to carry out its assignment and return it, which helps after a compaction when the routing skill is out of view. While assessing, the Coordinator is told that the worker's turns in its view are the worker's. The Coordinator says a decision is noted, not recorded, until the record update returns; a message to another session marks a choice the user has not made as open; and send_message says that a session nobody has prompted yet reads a message with its first prompt.
• Under Cognitive Routing on Anthropic models, a notice that arrived while a worker ran (a monitor line, for example) could break the session: the Coordinator's next request put the worker's evidence between its last tool calls and their results, and Anthropic rejected it (400 unexpected tool_use_id found in tool_result blocks). Evidence now comes after the call group. The routing skill also says a worker's background commands and monitors keep running after it returns, so a Coordinator no longer refuses to delegate a watcher.
• Under Cognitive Routing, a worker whose return was blocked by a selection problem was told the report would be delivered, so it could end its turn with the Coordinator never getting it. Its receipt now says nothing reaches the Coordinator until the problem is fixed, and how.
• On Pi, two background commands started together when 15 were running could both start, past the limit of 16, and one started as the session ended could keep running into the next session.
• skill-eval review shows the reviewer a reply shape with one entry per review question; with a one-entry example, a reviewer sometimes answered only the first question and the review failed.
• Evaluate Behavior grades skill-file reads in one-shot description runs and keeps their tool activity for the advisory review; a run that loses its context observation keeps its transcript, response and usage; and one trial's unreadable grade no longer aborts the whole aggregate (it is counted as unreadableGrades).

0.8.0 - 2026-10-03

Breaking Changes

• Replaces the Astra effort-history entry type with freeflow-openai-effort-v1 and removes the old Astra provider-support import paths. Existing freeflow-astra-effort-v1 entries are not replayed or migrated; the next supported request starts a fresh effort chain.
• Requires native Pi 0.99.1 or later for the Pi extension; Pi 1.0 and 1.0.1 are supported, and earlier Pi versions are no longer supported.
• Turns Cognitive Routing projection on by default. A configuration that omits projection now gives the Coordinator the worker evidence it selects instead of every worker turn; set projection: false to keep the previous behavior.
• Removes the Freeflow Context tool (freeflow_context, /freeflow context), Context Virtualization, and Conversation History; Context Control v2 remains unavailable as a replacement. Before updating, delete contextVirtualization and conversationHistory from .freeflow/config.json and .freeflow/local.json wherever present. Either key makes configuration invalid and blocks Freeflow activation until removed; no automatic migration occurs.
• Removes Freeflow-owned PiFlow host integration and Evaluate Skill's PiFlow runtime selection; use native Pi for Freeflow's Pi extension. Existing PiFlow installations and state are not changed or automatically uninstalled.
• Removes Cognitive Routing evidence refs to assistant messages (ctx:<entry> on an assistant message and ctx:<entry>#text); only tool results can be selected as evidence, and worker narration belongs in the report. Assistant selections saved in existing sessions are no longer delivered to the Coordinator.

Added

• Extends cache-aware effort-history adaptation from GPT-6 Astra to GPT-6 Luna and Sol on qualified OpenAI Responses and OpenAI-Codex Responses routes; provider cache hits, billing savings, and model-quality improvements remain unguaranteed.
• Adds experimental native-Pi Tool Execution, off by default: a layer over Pi's own tools with guidance on working in the environment, platform and shell facts, file tracking that refuses to overwrite a file the model has not read and names files changed behind it, edit errors that show the closest lines, apply_patch in OpenAI Codex's format (grammar-constrained for GPT-5 and later on OpenAI endpoints), and bash_background/stop_background, which notify the model when a command exits. bash refuses a trailing & and a foreground sleep of 10 seconds or more.
• Adds Freeflow compaction on native Pi, on by default: Freeflow warns before Pi's own limit, the agent compacts at a safe point with freeflow_compact from its own summary, Working Record, and carried files and tool results (numbered by line), and the same run continues from a recovery message. /freeflow compact asks for a compaction now, and /freeflow status shows the cycle and the context against each threshold. Pi's own compaction stays on as the fallback, with Freeflow's instructions and state added. Under Cognitive Routing, workers compact mid-assignment and the Coordinator delegates compaction. Configure it with compaction.enabled and compaction.carry.
• Adds a Working Method section to Freeflow's prompt on Pi: how to approach, check, and report work.
• Warns once when back-to-back requests to the same model and effort repeatedly miss the prompt cache with no compaction, navigation, reload, or model change in between, and shows the warning in /freeflow status.
• Warns when a Cognitive Routing worker preset costs as much per input token as Coordinator or more, or shares Coordinator's model at a different effort on a route that does not keep the prompt cache across effort changes.
• Keeps a Cognitive Routing Coordinator's prompt cache reachable after a worker run: when the worker's turns push the Coordinator's previous cache entry past the provider's lookback window, Freeflow places a cache breakpoint on that entry on Anthropic Messages and GPT-5.6+ OpenAI Responses routes. The ChatGPT Codex backend needs no breakpoint and is not changed.
• Keeps a suspended Coordinator's prompt cache warm while its delegated worker runs, on models that declare a cache lifetime and prices, by replaying its last request with a one-token output cap. A hold stops when the worker returns, the run ends, a refresh stops reading the cache, or after 6 hours or $2; refreshes are recorded as freeflow-cache-keepalive-v1 session entries. The ChatGPT Codex backend is excluded because it rejects output caps.
• Advises PI_CACHE_RETENTION=long once and in /freeflow status when the Cognitive Routing Coordinator's model has a longer prompt-cache tier than the host uses; Freeflow does not change retention.
• Adds a prompt caching guide covering provider cache behavior, what Freeflow adds to requests, how it keeps them cache-safe, and the rules for changing request assembly.
• Adds Track Work slice record, which records a Slice that finished before it could be recorded directly into History with Occurred and Recorded: retroactively on <date>, without closing a live Slice or supplying placeholder fields. Working Record commands also accept an absolute --record path from any directory.
• Adds the Write Docs skill (/write-docs) for documentation of how existing software works and why: which document serves which reader, adaptable shapes for overviews, subsystem docs, folder READMEs, and user guides, correcting documentation in the same change that makes it wrong, and a docs-check.mjs script that reports missing named paths and documents whose covered code changed since they were verified. Execute Work, Track Work, and Workflow point to it where documentation matters.
• Gives each Track Work task a scratch/ directory for temporary work, created by init; with Tool Execution, the guidance puts scratch files there when a Working Record exists.
• Ships a NOTICE and the Apache-2.0 license text for the apply_patch code ported from OpenAI Codex.

Changed

• Turns Cognitive Routing off for the session, visibly in /freeflow settings and the footer, when you pick a model or effort in Pi itself (/model, Shift+Tab, or a virtual model) instead of leaving it in a hidden inactive state. /freeflow profile auto or a profile hold, Ctrl+Shift+A, Ctrl+Shift+R, or the Session switch turns it back on and returns control to the automatic Coordinator.
• Separates user and developer documentation. plugin-docs/ keeps the user docs; the developer pages move to dev-docs/: architecture (now dev-docs/README.md), prompt architecture (dev-docs/subsystems/prompt-assembly.md), skill routing, performance, the release process, and decision records. Cognitive Routing, Pi integration, and prompt caching are split: their user pages stay, and their internals move to dev-docs/subsystems/cognitive-routing.md, dev-docs/subsystems/pi-extension.md, and dev-docs/guides/prompt-cache.md. Links to the old developer pages break.
• Keeps Freeflow's own work on each native Pi request, turn, and session start from growing with session length: routing history replays in one pass, the session branch is walked once per change instead of dozens of times per prompt, request history and routing attribution reuse Pi's session projection instead of re-hashing the conversation, each message in a routed view is rendered once and reused, history and GPT-6 effort records are written only when their state changes, compaction measures context from the turn's own usage, and session checks read only the entries appended since Pi loaded the file. On a 24 MB routed session Freeflow's added time per prompt fell from about 28 to 14 ms with routing and its startup from about 180 to 50 ms; with 8,000 messages in live context, routing's per-request work fell from about 73 to 25 ms. A disabled repository no longer adds routing provenance, and GPT-6 effort adaptation stays off when a configured repository disables Freeflow. Requests sent to the provider are unchanged.
• Replaces /freeflow settings with one screen: Session, Personal, and Repository scopes switched with Tab, switches that change in place (three-way switches cycle inherit, enabled, and disabled), and the source of each value. The Session scope can also override Cognitive Routing, projection, Tool Execution, Compaction, and Context reuse.
• Leaves OpenAI's Sign in with ChatGPT route (Pi 0.99 and later) untouched: no cache breakpoints, Coordinator keep-alive, or effort-history rewriting, which that route rejects. Cognitive Routing presets that switch effort on that route warn that it keeps a separate prompt cache per effort.
• Allows Cognitive Routing tools only as direct calls, not from codemode scripts; other tools a script calls are admitted under routing like direct calls.
• Tightens shipped guidance: Track Work recovery confirms that a pointed-to Working Record belongs to the current work before reading its sources, the Interaction Contract reports that something happened only from a source that would show it, and the routing, Workflow, Verify Work, and Evaluate Skill guidance carry refinements from agent-behavior research.
• Lets native Pi sessions override the Cognitive Routing delegation mode and stage any profile preset, while showing the effective mode in the footer without changing repository or personal configuration.
• Resumes a Cognitive Routing worker run automatically when a crash or reload interrupted it and no new user input has arrived; reopening an idle session only notes that an unchanged assignment can be resumed.
• Shows prompt-cache diagnostics (Coordinator keep-alive, context replay, and the GPT-6 effort baseline) on the prompt cache line of /freeflow status instead of the footer, which now shows only current Freeflow settings.
• Shows the Coordinator only the tool calls of worker turns it did not select, so another model's reasoning no longer arrives as text, and gives each completed worker run one provenance note.
• Shares a Cognitive Routing profile's private reasoning with another profile only where both would send the same request: a turn produced on the receiving profile's model and under the same view. Otherwise each profile sees only its own reasoning, the Coordinator never receives worker reasoning under projection, and OpenAI function-call items are unpaired where their reasoning is withheld.
• Applies Cognitive Routing profile changes made while Pi is idle (manual holds, releases, and session presets) to Pi's model when the next prompt is submitted; the footer shows the pending model until then, and a model picked in Pi's own picker cancels it.
• Writes no Freeflow session entries before a session's first prompt, and records routing control and session setting changes made between prompts as one net change at the next prompt instead of one entry per switch.
• Has Cognitive Routing workers select evidence and submit their return in the same response, correcting reported problems with a return retry, instead of spending a separate request waiting for the selection receipt.
• Refuses a new Cognitive Routing assignment while attached evidence recovery is open, and refuses cancelling recovery or closing a unit while a worker run for that work is unresolved.

Fixed

• Stops trusting the session file as verified after /reload, which keeps Pi's session in memory without re-reading the file; an entry that a failed write left only in memory now blocks Cognitive Routing instead of being treated as persisted.
• Keeps Cognitive Routing correct on Pi 0.99 for runs that an extension's message starts: the run is handed to the Coordinator before its first request instead of waking an idle worker.
• Explains a Cognitive Routing recovery refusal when a context ref is passed as a captured result id: the ref belongs in the request, where the worker selects it as evidence.
• Preserves Pi's historical system-prompt and tool timeline by contributing Freeflow guidance as a structured section and composing the full request transcript rather than forcing a replacement system head.
• Keeps Cognitive Routing manual-hold and automatic-release shortcuts in step with the host model: requests run in order, the next manual hold is chosen from the latest state, and a profile is recorded only after its model is applied.
• Applies the same ordering to Cognitive Routing resume, session presets, rebinding, re-enabling, and navigation, so a failed model switch records nothing; a manual hold whose model was changed outside routing is reported once and shown in the footer instead of being overridden.
• Corrects the Cognitive Routing skill: profiles on the same model reuse the prompt cache only at matching effort or on routes that keep it across effort changes (currently the supported GPT-6 routes and Claude models that take per-message effort).
• Delivers evidence reused from an earlier assignment where it was selected, so a returning Coordinator request extends its cached prefix instead of rewriting it.
• Delivers evidence that an attention view left out where the assessment resumed, so the resumed Coordinator request extends its cached prefix instead of rewriting it.
• Keeps Freeflow runtime state and GPT-6 effort history at their original positions after /tree branch navigation with a summary, so the request after the branch point reuses the cached path instead of rewriting it; only compaction starts a new history.
• Counts cache writes in prompt-cache health checks and compares a Cognitive Routing profile that resumes on its own model with its previous request, so write-heavy and handoff misses are reported.
• Fixes the Cognitive Routing profile-cycle and automatic-release shortcuts, which read a stale model and took several presses to switch.
• Sends the Freeflow system section even when Cognitive Routing fails at a session's first prompt.
• Stops the Coordinator keep-alive from replaying Claude requests that use budget-based thinking, which a one-token replay cannot refresh.
• Keeps the Coordinator's cache anchor when a Claude request ends with a mid-conversation system update.
• No longer warns that a same-model Cognitive Routing preset at a different effort loses the prompt cache on Claude models that take per-message effort.

0.7.3 - 2026-09-16

Added

• Adds an optional Cognitive Routing Helper profile and executor, helper, and both delegation modes with mode-aware presets, manual holds, durable worker-specific continuation, and shared worker history.
• Adds cache-aware Pi request assembly and qualified Astra effort-history adaptation; provider cache hits, billing savings, and model-quality improvements remain unguaranteed.
• Adds attached Cognitive Routing evidence recovery with exact-path reads, preserved original reports and assessments, separate supplements, explicit cancellation, and direct selection of eligible occurrence-linked evidence refs.
• Adds session-only Cognitive Routing profile presets for Coordinator and enabled workers with complete model/effort pairs, inheritance, reset, and local/shared configuration isolation.
• Adds a practical Freeflow user guide for prompting, skill selection, Workflow and Track Work management, settings, Cognitive Routing presets, and evidence and cost boundaries.

Changed

• Clarifies mode-aware Coordinator/Helper/Executor ownership, implementation boundaries, evidence projection, recovery, and Coordinator assessment responsibilities.
• Batches worker evidence selection during return preparation while preserving saved reports, unresolved evidence, and handoff limits.
• Repositions Freeflow around Memory, planned Context, and Compute, and expands Cognitive Routing and PiFlow documentation with qualified preset and cache-reuse boundaries.

Fixed

• Clears session-local Cognitive Routing manual-hold state before validating a newly bound session.
• Clarifies evidence-selection operation shapes, remove-only withdrawal reasons, and the distinction between eligible result bodies and routing controls.
• Prevents pre-prompt /reload and Cognitive Routing preset changes from blocking on Pi's not-yet-materialized session file.
• Preserves Astra effort-history replay across temporary model round trips and reloads when the qualified request lineage remains compatible.

0.7.2 - 2026-09-11

Breaking Changes

• Consolidates experimental routing reads into freeflow_project inspect with scoped candidates and freeflow_unit inspect with current/history/detail views; earlier list, status, and history operation names are no longer advertised or accepted.
• Replaces the experimental Cognitive Routing switch/boundary protocol with Coordinator/Executor assignments, separate delegate/return/unit/projection tools, and projection/thinking configuration. Old experimental configuration and tools are not migrated; redesigned PiFlow routing and composition with legacy context transforms remain unavailable pending qualification.

Added

• Adds exact assistant-visible-text evidence refs, bounded saved-work detail/history recovery, snapshot-based inspection pagination, and explicit target limitations in expanded routing output.
• Adds saved-report retry, explicit same-unit assignment replacement, strict read-only session acknowledgment reconciliation, and assessment-preserving evidence projection with attention suspension and restoration.

Changed

• Retires the old experimental routing source and tests into the historical archive, adds replacement-contract regression suites, and cleans generated extension output before building.
• Shows live routing tool arguments in a six-line trailing preview with full expansion, and replaces internal collapsed receipt labels with readable operation outcomes and evidence counts.
• Clarifies Cognitive Routing's Coordinator/Executor assignment boundary, design-decision transfer, selective evidence projection, and Coordinator assessment responsibilities in the shipped guidance.

Fixed

• Limits normal evidence inspection to usable candidates and removes source-content previews, while preserving saved-selection diagnostics.
• Preserves delivered-user identity across native compaction and explicit resume, so stored-but-undelivered history does not interrupt an outstanding Executor assignment while genuinely new input still does.
• Keeps streamed routing contracts and reports visible in collapsed receipts; limitations and replacement reasons remain available in expanded views instead of obscuring current prose.
• Preserves source attribution throughout routing request views and complete report metadata during handoff/recovery; excludes routing controls from new evidence selections, clarifies inspection counts and historical discovery, and distinguishes invalid lookup refs from unavailable work.
• Preserves admitted routing communication and active evidence across closure, replacement and attention; removes duplicate runtime communication and selection no-op churn, preserves identical-call receipts, indexes native exchanges, and streams long-session reconciliation with explicit resource limits. Request planning no longer treats base64 as text or a model output maximum as an invariably reserved allocation.
• Reconciles native routing navigation and explicit assignment resume, guards stale session operations, preserves evidence withdrawal details and cross-model tool-result carriers, and reduces history replay and routine journal writes. Routing tools now show readable receipts and role-appropriate controls.

0.7.1 - 2026-09-04

Added

• Adds Agent Plugins 1.0, Gemini CLI, Cursor, GitHub Copilot/VS Code, OpenCode v2, and Hermes distribution metadata or compatibility over the same canonical 25-skill tree, with Kiro compatibility through the portable Agent Plugins skill surface.

Changed

• Separates shared runtime-context rendering from Codex, Claude, Gemini, Cursor, and Copilot/VS Code hook adapters while preserving existing Pi/PiFlow capability boundaries and lifecycle behavior.

Fixed

• Aligns OpenCode v2 skill configuration, Gemini lifecycle matching, and Copilot session-start context output with their documented host contracts.

0.7.0 - 2026-09-03

Breaking Changes

• Removes Freeflow's selectable modes, mode commands, session mode state, and defaultMode configuration; all work now uses one adaptive Workflow.
• Removes the interactionContract and skills configuration toggles. The separately editable Interaction Contract and 25 base skills are always present whenever Freeflow is enabled, while optional capabilities remain independently gated.
• Replaces the current Schema 3 Track Work package with compact Schema 4 Markdown task memory and lifecycle commands. Existing Schema 2/3 records remain untouched and require a later explicit migration.

Added

• Adds Cognitive Routing support to normal Pi through its official model, thinking-level, model-registry, and session-entry APIs while preserving the existing PiFlow host path, transition recovery, native-override handling, and rollback evidence.

Changed

• Refines core runtime prompts and workflow guidance with explicit authority and evidence boundaries, current-owner routing, bounded environment interactions, peer execution methods, and expanded design and skill-authoring references.
• Changes Cognitive Routing automatic control to start and return in Reasoning, keeps all substantive user-facing interaction in Reasoning while Standard transfers execution state at return conditions, adds Yield/Delegate/Act Bounded routing with model-written execution boundaries, and refreshes Runtime State only after context reconstruction or displayed-state changes.
• Reconciles the shipped skill-routing map with current direct routes and resource dependencies.
• Documents the Pi 0.84.3+ support floor and Pi 0.84.4 integration test target.
• Rewrites Cognitive Routing guidance around shared context, Reasoning-governed boundary-first routing, a persistent Delegate loop, standalone Yield, Reasoning-owned self-review, and explicitly bounded Act Bounded execution while preserving execution-boundary lifecycle semantics.

Fixed

• Keeps extension-generated Runtime State before the latest genuine user message so automatic profile refreshes cannot masquerade as user interruptions and prematurely return delegated work.
• Prevents stock-Pi model and thinking events emitted by Freeflow-owned profile transitions from being treated as native user overrides.
• Expands direct Pi skill commands through Pi’s sendUserMessage API before dispatching them to the model.
• Renders Schema 4 Current Work, Future Work, and History entities as compact field-list rows while preserving expanded reads, and expands Track Work operation help with fragment fields and stdin guidance.

0.6.0 - 2026-08-25

Added

• Adds a deterministic v2 Track Work runtime with strict schema-driven updates, bounded views, decision and checkpoint lifecycles, historical reopening, stale-lock recovery, loss-resistant migration and compression, candidate round-trip validation, and atomic persistence.
• Rebuilds Track Work as one complete lifecycle method for task-memory creation and recovery, Current Slice continuity, proposals, decisions, checkpoints, evidence, Notes, closure, and reconciliation while keeping exact command mechanics schema-driven.
• Extends Evaluate Skill with explicit runtime profiles, PiFlow host variants, extension bundles, prompt/context evidence, tool-call predicates, and stronger isolation and evidence safeguards for behavioral evaluation.
• Adds the Pi-only Cognitive Routing capability with standard/reasoning profiles, manual unsplit control, Reasoning-led automatic execution boundaries with Standard delegation, state restoration, runtime Control/Profile delivery, transition history, and PiFlow host integration; keeps it experimental pending behavioral acceptance.
• Adds Action Selection as a cross-host skill for bounding uncertain or broad environment interactions before choosing tools or repeated actions.
• Adds opt-in Pi-only Context Virtualization for archiving classified tool results from future model context while preserving canonical session history, with archive/restore controls and working-set policy.
• Adds opt-in Pi-only Conversation History retrieval for bounded current-branch recovery, with passage ranking, cancellation handling, and explicit recovery-policy safeguards.
• Adds committed exact-revision Freeflow development snapshots for Pi/PiFlow with provenance, atomic refresh, package validation, and isolated targets while separating Freeflow policy from PiFlow host ownership.
• Adds human-controlled release automation, pull-request/main CI, deterministic version and changelog preparation, metadata validation, tag-verified npm/GitHub Release publishing, recovery support, release-note extraction, and PR changelog declaration validation.
• Adds a canonical public documentation hub, Pi/PiFlow Getting Started guidance, versioned release evidence, consolidated ADR ownership, tracked historical project-doc archiving, and deterministic documentation validation.

Changed

• Simplifies the Interaction Contract into compact evidence-based interaction semantics: separates user goals from factual claims, answers mixed question/action turns before acting, and proceeds on clear requests without silently expanding them; adds focused baseline-versus-candidate behavioral evaluation cases.
• Scopes workflow authority by requested outcome, permitted effects, evidence boundary, and stop condition; distinguishes passive observation, active evidence generation, and mutation or delivery; and consolidates detailed policy in Workflow so mode, skill selection, usefulness, or new evidence cannot silently authorize the next action.
• Aligns discussion, diagnosis, execution, mode, TDD, verification, and review guidance with the shared authority model; separates review adjudication from remediation; moves Working Record selection to Discuss and Workflow while Track Work operates established memory; defines entry-required, activity-required, and conditional reference reads; makes child skills own their reference activation; and keeps reference filenames aligned with their visible titles.
• Moves the Interaction Contract into layered runtime prompt fragments and hides retained historical material under .deprecated/, updating live loaders, package checks, documentation, and links.
• Adds layered prompt-fragment, Runtime State, and discoverable-skill delivery with capability gating so hosts receive stable guidance and opt-in Pi capabilities through separate runtime surfaces.
• Requires silent self-review after every bounded activity—tasks, slices, subtasks, artifact revisions, and small local changes—before its result is accepted, reused, or claimed complete; keeps corrections inside the existing authority envelope and reinforces the boundary in execution, bypass, task completion, plan defaults, and pre-activation setup.
• Hardens changelog governance and tag-driven release CI with canonical category validation, released-history immutability, pre-publication release-note checks, exact artifact verification, and recovery safeguards.

Removed

• Removes the deprecated Output Router from the Pi runtime, tools, settings command, capability guidance, and active evaluation surface; it is no longer available for use. Legacy router-shaped configuration remains inert for activation compatibility, while the implementation and evidence are archived under .deprecated/output-router/.
• Removes the legacy Pi-only /discover and /execute-plan compatibility aliases; use /discuss and /execute-work instead.

0.5.0 - 2026-08-13

• Adds deterministic session-only Freeflow mode switching for Codex and Claude Code without restarting the conversation.
• Restores session mode across startup, resume, clear, and compact lifecycle boundaries using isolated plugin-owned state, including a bounded host-process-scoped, one-shot Claude /clear handoff; session controls never edit repository or personal configuration.
• Supports explicit natural-language mode controls plus Claude namespaced skill invocation and Codex $mode-contract mentions while leaving ordinary prompts, questions, and hypotheticals inert.
• Clarifies configured-default scope: explicit personal/local requests target .freeflow/local.json, explicit shared/repository requests target .freeflow/config.json, and unqualified requests ask before editing.
• Keeps host-native skill dispatch and the 25-skill Codex/Claude surface while preserving Output Router as Pi-only.

0.4.0 - 2026-07-21

• Reframes Freeflow as a feedback-based control system for coding agents, with a directed Interaction Lifecycle, internal Feedback Loop, and evidence-supported exits instead of a fixed phase pipeline.
• Uses the compact Interaction Contract plus one Workflow bootstrap as runtime guidance, while keeping mode and capability state independently gated.
• Adds required repository activation, optional per-checkout personal core overrides, Pi session-mode precedence, fail-closed invalid-local behavior, and explicit delivery evidence.
• Replaces the canonical discover and execute-plan model skills with discuss, track-work, and execute-work; Pi retains /discover and /execute-plan only as compatibility aliases.
• Keeps factual verification with the active agent, distinguishes silent self-review from selected independent review, and makes Pass, Non-blocking, Inconclusive, and Blocking valid review exits.
• Gives Specs and Plans separate independent Review Artifact boundaries, keeps findings non-authorizing, and requires explicit correction and focused follow-up authority.
• Adds the composite Track Work method for context-first Working Records, coherent write-ahead slice extensions, state-transition history, inert Notes, and restoration after context loss or session navigation.
• Aligns Mode Contract, Setup Freeflow, Bypass, Commit Work, migration, release, launch, handoff, branch finish, diagnosis, TDD, simplification, and design-depth methods with the feedback-based model.
• Keeps skill readiness outside subject SKILL.md files and repairs Skill Author validation for readable project-contained sibling and runtime dependencies.
• Refreshes package and marketplace identity, root and plugin documentation, release/current-state contracts, activation validation, and the typed 25-skill routing/dependency map.
• Replaces the retired Skill Author and Skill Eval machinery with fresh init, validate, inspect, run, and view surfaces, exact canonical evidence, deterministic baseline/candidate grading, isolated one-shot and multi-turn Pi subjects, serial batch continuation, and compact generated views.
• Reorganizes the Pi extension source, tests, and generated distribution by feature while preserving its stable package entrypoint, and adds Workflow and Feedback Loop diagrams to the root documentation.
• Preserves Output Router as an explicit optional capability and keeps its existing runtime behavior and evidence boundaries unchanged in this migration.
• Leaves the adaptive candidate Unverified pending current baseline-vs-with-skill behavioral evaluation; deterministic structure and delivery checks do not establish behavioral readiness.

0.3.0 - 2026-06-28

• Adds plugin-bundled runtime context loading for mode-contract, workflow, interview-gate, discovery-light, and output-router, including Pi every-turn context injection.
• Enforces the conversation-mode boundary so mutating or consequential work requires workflow or strict-workflow mode.
• Adds the direct /output-router route and exposes the Freeflow search/run/batch/status evidence surface in Pi.
• Expands Output Router with observed routing, vault-wide indexing, deterministic transform/reducer routing, storage-policy dedupe, and exact recovery guidance.
• Adds proof-gated sandboxed script producers/transforms for JavaScript, Python, and jq behind explicit scriptTransform opt-in, with no unsandboxed fallback.
• Adds processing reducers for access logs, tests, diagnostics, build output, tables, MCP tools, browser snapshots, git logs, and query-aware JSON facts.
• Records Context Mode comparison evidence, storage-policy evidence, script-sandbox proof evidence, observed-routing evidence, and updated output-router release evidence.
• Simplifies runtime skill context, tightens output-router safety-policy docs, and refreshes public README/plugin docs with the workflow map and current positioning.
• Fixes Pi runtime context loading on every turn and makes the discover skill description YAML-safe.

0.2.0 - 2026-06-19

• Adds Freeflow output-router tooling for routed repo/vault evidence, noisy command routing, and exact raw-output recovery.
• Adds deterministic retrieval, command-output, optional local-index, and Codex Structured Q&A router benchmarks.
• Keeps scanner retrieval as the default backend; the no-dependency local index remains experimental.
• Keeps native post-tool safety-net routing off unless explicitly configured.
• Adds opt-in outputRouter setup/config guidance while preserving minimal setup as only defaultMode.
• Replaces research-brief, grill-context, and capture-decisions with the deeper research discovery skill.
• Moves deprecated discovery skills to root deprecated/skills/ outside the runtime skill surface.
• Updates the direct command surface to use /research.
• Clarifies write-skill line budgets as best practice, not a hard cap for deep skills.
• Adds parent adjudication and a three-pass hard cap for artifact/work review loops.
• Deepens execute-plan for multi-slice execution, TDD slice contracts, review-failure routing, and scope-change backward edges.
• Tightens workflow/review skills so non-passing reviews route to adjudication before more implementation.

0.1.0 - 2026-05-26

• Initial Freeflow package.
• Ships the accepted v0.1 workflow skill set.
• Supports Codex and Claude plugin metadata.
• Adds public workflow, skills, architecture, release evidence, and ADR docs.
• Keeps native slash handlers, hooks, and CLI enforcement out of scope.