v5.11

v5.11 — one validator run, gate rows with evidence, watched waits, a project tool profile

Upgrade as usual with bash hooks/local/upgrade.sh. Three shipped behaviours change (gate
reports, pre-commit, and new command refusals), and two optional project files now exist
(policies/agent-tools.yml, policies/validator-free-paths.yml). A project that adds neither
sees no new files.

This release comes from a review of Flow 5.10 against one consumer's measured release (the FuseBase
onboarding project). Every claim was checked against Flow's code first; the parts that held are
shipped, narrowed where the check found a problem, and each contract change had an independent review.

Changed: lint and typecheck run once per commit — and can skip declared docs-only commits

Agents no longer run a separate lint/typecheck pass before committing: Flow's pre-commit hook runs the
project's lint and typecheck once. The "receipt" shortcut (switched off since 4.15) is removed. If
Flow's hook is not the active hook (for example core.hooksPath points elsewhere), agents run lint and
typecheck themselves. The hook prints how long each of its checks took.

New, opt-in: a project may commit policies/validator-free-paths.yml listing paths its lint and
typecheck never read. A commit whose staged paths all match (as committed at the last commit) skips
lint and typecheck and prints tier=validator-free; the secret scan, protected paths and module size
always run. Flow ships no such file, so nothing changes until a project declares one. FR-13 now reads
"Lint+typecheck per code commit (declared docs-only paths skip)".

Changed: agents can no longer switch the commit or push hooks off

git commit -n (and its combined forms), the abbreviated --no-veri… options git accepts, and
changing git's hooks-folder setting (core.hooksPath in any setting form, which also skipped the push
check) are refused, like --no-verify already was. Flow's own install and post-update commands stay
allowed. What to do: a commit message that quotes these commands inline is refused too; write the
message to a file (git commit -F <file>).

Changed: gate reports are claims; the Product Owner side gives the verdict

Gate reports list every row as PASS or FAIL with its own evidence (no ticks, no PARTIAL). The
report no longer needs an "Operating as …" sentence. verify-gate.sh checks values, not just headings,
and stays advisory. Only the Product Owner side declares a gate passed; a gate sent back for fixes
counts against the 2-round limit, after which the work returns to the operator. What to do: old
reports with tick marks are sent back once to be rewritten as PASS/FAIL rows.

New: give a Flow agent extra tools without editing Flow's files

Commit policies/agent-tools.yml (protected; Flow never ships it) to add tools — for example an MCP
tool a task needs — to a Flow agent. Flow then generates .claude/agents/<agent>-project.md next to its
own untouched agent file; dispatch that name when a task needs the tool. Tools are only added, named
one by one; AskUserQuestion, Agent and Task are refused. Upgrades keep your profile. Tasks now
name their inputs and the tool that reads them; a task no available agent can read stops with
BLOCKED-AT-input.

Liveness: hangs are watched from outside

Flow no longer says a hang cannot be detected: it is invisible from inside the hung call, so it is
watched from outside. A bounded background watcher is the default for a session the host can wake;
the documented Claude Code wake paths (background task exit, sub-agent completion, scheduled task,
cross-session message, asyncRewake) are each "never the only wake". bounded_run writes a heartbeat
file under state/audit/liveness/ (excluded from git on install and upgrade; BOUNDED_RUN_HB_DIR=
disables it), and a new bounded_wait helper waits for a line in a file in slices under the
prompt-cache lifetime. The liveness check joins the release gate.

Smaller changes

• task-delegation: unattended runs keep cross-slice checks until every slice is done, re-dispatch
  unfinished work with its own brief, and never "proceed under a grant" after a refusal; sessions that
  hand out work keep doing already-approved independent work while a question waits (not Product
  Owner sessions).
• smoke-testing: run past failures, audit waits once, the product's latency criterion stays binding,
  rerun failed rows then one whole run on the final deploy.
• The AI Developer reads the handoff in full and ticket artifacts by slice.
• /token-waste-audit counts and prices advisor calls (earlier totals left them out), adds a wall-time
  section, and prints the 1-hour sub-agent cache break-even (about 38–40%; supersedes 5.8's flat
  "not recommended").
• /find-wasted-effort links Flow's own gate-report template and groups rounds by its recorded task
  range.
• FR-10 guidance in two adapters and violation-recovery now matches validation-and-qa; ROADMAP,
  the hooks README and the smoke template state what ships; the pre-5.0 changelog moved to
  docs/release-notes/CHANGELOG-pre-5.md.
• Four hook handlers (pre_tool_use, user_prompt_submit, post_tool_use, session_start) reply
  in the format Claude Code accepts: wired projects stop seeing "hook error" notices on every run, and
  Flow's warnings (for example the pasted-secret warning) reach the model. No allow/warn/deny decision
  changed. stop.py, pre_compact.py and permission_request.py still use the old format (backlog).

Not in this release

The Stop-hook rework (evidence counted only from what the agent itself wrote, a loop guard, and
accepting tier=validator-free as lint evidence) did not pass its final review and is not shipped;
the next release replaces the Stop gate. Filed in the backlog: an outside liveness watcher, a computed
gate tally, a typed Stop claim for sub-agents, tool-call pairing in the audit log, store provisioning
during deploy.