feature-flow-cli 0.5.0__tar.gz → 0.8.0__tar.gz

{feature_flow_cli-0.5.0/feature_flow_cli.egg-info → feature_flow_cli-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: feature-flow-cli
-Version: 0.5.0
+Version: 0.8.0
 Summary: A ticket-graph workflow for coding agents: installs the feature-flow skill into a repo
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/hamilton-sky/feature-flow
@@ -25,10 +25,10 @@ Dynamic: license-file
 
 Plan a feature as a graph of small tickets, then build them in the session you are already in. One command, `/feature-flow`, does both. Every ticket is built by one fresh subagent and checked by another that never saw the builder's reasoning. A script, not the agent, decides the order of the steps, runs the build and tests, and watches for work that weakens the checks, and the whole run has limits.
 
-One skill, 2 agent roles, a Python conductor, 4 Python scripts, an installer for both agents, a demo and a test suite. All of it is Python (standard library only), so it runs on Linux, macOS and Windows. MIT licensed.
+One skill, 4 agent roles, a Python conductor, 6 Python scripts (`flow`, `flow-trust`, `flow-status`, `flow-view`, `gate`, `floor-guard`), an installer for both agents, a demo and a test suite. All of it is Python (standard library only), so it runs on Linux, macOS and Windows. MIT licensed.
 
 - [Quick start](#quick-start) · [How a ticket flows](#how-a-ticket-flows) · [The skill and the roles](#the-skill-and-the-roles) · [Plans and tickets](#plans-and-tickets)
-- [See the graph](#see-the-graph) · [Long features and handoff](#long-features-and-handoff) · [What is tested](#what-is-tested) · [Upgrading](#upgrading) · [Caution](#caution)
+- [See the graph](#see-the-graph) · [Long features and handoff](#long-features-and-handoff) · [What is tested](#what-is-tested) · [Limits](#limits) · [Upgrading](#upgrading) · [Caution](#caution)
 
 ## Quick start
 
@@ -51,7 +51,7 @@ Without a clone, the same installer runs from [PyPI](https://pypi.org/project/fe
 uvx feature-flow-cli install /path/to/your/repo --agent all   # or: pipx run feature-flow-cli install ...
 ```
 
-The package puts a `feature-flow` command on your PATH with `install`, `status <feature>` and `view <feature>`. It installs the same files, byte for byte, as `install.py` from a clone.
+The package puts a `feature-flow` command on your PATH with `install`, `uninstall`, `status <feature>`, `view <feature>`, `reset <feature>` and `report <feature>`. It installs the same files, byte for byte, as `install.py` from a clone.
 
 The installer lists what it wrote in `.feature-flow/installed.txt`, with each file's hash in `.feature-flow/installed.sha256`. Commit those files (`git add --pathspec-from-file=.feature-flow/installed.txt`); until you do, the flow does not count them as uncommitted changes. Installing a newer version over an older one updates every file nobody edited since it was installed, and keeps (and names) the ones you changed; `--force` replaces those too.
 
@@ -71,7 +71,7 @@ Then, in your repo, in the agent:
 
 The same command plans when `plans/csv-export/` does not exist yet and builds when it does. After your second yes it commits the new plan folder, and only that folder, then goes straight on to building it; say so if you want it to stop after planning.
 
-**Planning asks you twice.** First the session shows a short feature brief, written from your conversation (what, why, scope, the bar, and anything it had to assume), and waits for yes, edit or cancel. Then a fresh `feature-planner` subagent, given only that brief, reads the code, looks up outside docs where the code cannot answer, and writes a draft plan into the git-ignored `.feature-flow/state/draft/`. A fresh `plan-reviewer` checks the draft against the brief. The session shows you the goal, the commands, the ticket graph, what was dropped and the review result, and waits for a second yes. Only then does `flow.py plan-accept` copy the draft into `plans/<feature>/`, and the session commits it and starts the build.
+**Planning asks you twice.** First the session shows a short feature brief, written from your conversation (what, why, scope, the bar, and anything it had to assume), and waits for yes, edit or cancel. Then a fresh `feature-planner` subagent, given only that brief, reads the code, looks up outside docs where the code cannot answer, and writes a draft plan into the git-ignored `.feature-flow/state/draft/`. The planner folds changes too small to stand alone into the ticket they belong to, and sets `Review: full` on a ticket that deserves both reviews whatever its size. A fresh `plan-reviewer` checks the draft against the brief. The session shows you the goal, the commands, the ticket graph, what was dropped and the review result, and waits for a second yes. Only then does `flow.py plan-accept` copy the draft into `plans/<feature>/`, and the session commits it and starts the build.
 
 Try the graph first, with no setup and no agent: `bash examples/demo.sh --open`.
 
@@ -121,6 +121,8 @@ The Claude Code skill is `skills/feature-flow/`. The Codex skill is written by h
                                               │ PASS                │
                                               ▼                     │
  quality review: a second fresh reviewer subagent             FAIL ─┤
+   (a small ticket whose check block passed gets one combined
+    review instead of these two; see below)
                                               │ PASS                ▼
                                               ▼        findings written into the ticket,
                                      next ticket       reopened, built again (3 rounds max);
@@ -130,7 +132,11 @@ The Claude Code skill is `skills/feature-flow/`. The Codex skill is written by h
 
 `scripts/flow.py` is the conductor. The session asks it `next`, and it answers with one line: `BUILD`, `REVIEW`, `DONE`, `STOP` or `HANDOFF`. It prints the full prompt for each subagent from runtime-neutral guides, so the session never writes one itself.
 
-**What the script checks and what it trusts.** The conductor verifies the build from the repo: the ticket file must say `resolved`, the tree must be clean and committed, and it runs the gate and the floor guard itself. It also runs the `check` block under each ticket's Done when and compares the exit code and printed text, and for a `Test first: yes` ticket it proves the red test commit itself: it checks out the test-only commit, runs Test, and requires it to fail before the code. A failure of either goes back to the builder before any reviewer is started. It also checks that the reviewer changed no tracked file and made no commit. The review verdicts are different: each reviewer's reply (spec review, then quality review) is relayed by the session, which saves it to a file and hands it to `flow.py verdict`. The script reads `REVIEW: PASS` or `REVIEW: FAIL` from that reply; it cannot prove the session passed it on unedited. A ticket moves on only after two PASS verdicts.
+**What the script checks and what it trusts.** The conductor verifies the build from the repo: the ticket file must say `resolved`, the tree must be clean and committed, and it runs the gate and the floor guard itself. It also runs the `check` block under each ticket's Done when and compares the exit code and printed text, and for a `Test first: yes` ticket it proves the red test commit itself: it checks out the test-only commit, runs Test, and requires it to fail before the code. A failure of either goes back to the builder before any reviewer is started. It also checks that the reviewer changed no tracked file and made no commit. The review verdicts are different: each reviewer's reply (spec review, then quality review) is relayed by the session, which saves it to a file and hands it to `flow.py verdict`. The script reads `REVIEW: PASS` or `REVIEW: FAIL` from that reply; it cannot prove the session passed it on unedited. A ticket moves on only after two PASS verdicts, or one for a ticket the conductor judged small. The size is measured from the repo (`git diff` against the commit the ticket started from), never taken from the builder.
+
+**The gate: full or quick.** The gate runs Build, Test and Lint after every ticket. With an optional `Quick:` line in `commands.md` (a faster subset of `Test`), it runs Build, Quick and Lint after the tickets in the middle of a plan, and the full Build, Test and Lint after the last ticket, before a handoff, and under `FLOW_GATE_FULL=1`. A plan without `Quick:` runs the full gate every time. The test-first proof still runs the full `Test` command.
+
+**One review for a small ticket.** A ticket whose built diff is 3 files and 60 changed lines at most (the plan folder left out), and whose `check` block ran and passed, gets one combined review instead of the spec and quality reviews. The conductor measures the diff itself. `Review: full` in the ticket (as it was at the start), `Type: convert`, no `check` block, or `FLOW_GATE=off` keep both reviews. Every other conductor check still runs on every ticket.
 
 ## The skill and the roles
 
@@ -197,14 +203,18 @@ prints OK
 - **The Answers are the handoff between subagents.** The next builder reads the Answers of the tickets it depends on.
 - `settle` tickets record a decision. `convert` tickets migrate something and must be safe to run twice.
 - **A worker may change only** its own Status line and Answer, lines appended to `map.md` and `learnings.md`, and the code the ticket calls for. Rewriting its own Done when, editing another ticket, or touching `commands.md` fails the guard.
-- `Floor:` categories: `skip`, `suppress`, `empty-catch`, `test-delete`, `threshold`, `config`, `ticket-edit`, `commands-edit`, and `flow-edit` (allows the conductor's code check below, for the build only). `skip` covers skipped, expected-fail and focused tests (`.only(`, `fit(`, `fdescribe(` on test paths); `config` covers more lint and test config files, the lint and test sections of `pyproject.toml` and `setup.cfg`, scripts and test keys in `package.json`, new skip or xfail words in `conftest.py`, and a `Makefile` only when `commands.md` uses `make`. A test file that loses assertions is shown to the reviewer as a warning, not a finding. The line is read from the ticket as it was before the work started, so a worker cannot excuse itself.
+- `Floor:` categories: `skip`, `suppress`, `empty-catch`, `test-delete`, `threshold`, `trivial-assert` (an assertion that cannot fail, added to a test file: `assert True`, `assertEqual(x, x)`, `expect(v).toBe(v)`), `config`, `ticket-edit`, `commands-edit`, and `flow-edit` (allows the conductor's code check below, for the build only). `skip` covers skipped, expected-fail and focused tests (`.only(`, `fit(`, `fdescribe(` on test paths); `config` covers more lint and test config files, the lint and test sections of `pyproject.toml` and `setup.cfg`, scripts and test keys in `package.json`, new skip or xfail words in `conftest.py`, and a `Makefile` only when `commands.md` uses `make`. A test file that loses assertions is shown to the reviewer as a warning, not a finding. The line is read from the ticket as it was before the work started, so a worker cannot excuse itself.
 - The guard needs the plan to be tracked by git. If you keep tickets in an ignored folder, it cannot see changes to them.
 - The commands in `commands.md` run with nobody watching and must exit non zero on failure.
 
 ## See the graph
 
+![The animated ticket graph for the demo plan: five of ten tickets resolved, two ready, one in progress](docs/flow-view.png)
+
+*The page `flow-view` writes, shown for the demo plan from `examples/demo.sh`: resolved tickets in green, ready ones in amber, the one being worked in blue, the rest waiting. Press Replay to watch the run back from git history.*
+
 ```bash
-python3 scripts/flow-view.py csv-export            write the page and open it
+python3 scripts/flow-view.py csv-export            write the page and open it (or: feature-flow view csv-export)
 python3 scripts/flow-view.py csv-export --watch    keep it updating while tickets are built
 bash examples/demo.sh --open                    try it on a made up project, no setup needed
 ```
@@ -245,6 +255,8 @@ python3 scripts/flow-status.py <feature>                  table of tickets and w
 python3 scripts/flow-status.py <feature> --next           path of the next ready ticket (exit 10 = done, 11 = stuck)
 python3 scripts/flow-status.py <feature> --counts         one line of counts
 python3 scripts/flow-status.py <feature> --check          cycles, missing blockers, missing Done when, unordered mentions
+python3 scripts/flow-status.py <feature> --lint           --check plus: a check block (or `Check: none <why>`) on every ticket, a Test command
+feature-flow report <feature>                             what a run did, from its log: builds, reviews, failed checks, stops
 python3 scripts/flow-status.py <feature> --mermaid        the ticket graph, coloured by status (add "plain" for none)
 python3 scripts/flow-status.py <feature> --json           every ticket with status, blockers and readiness
 python3 scripts/flow-view.py <feature> [--watch]          the animated graph page, opened in your browser
@@ -266,13 +278,16 @@ The commands in `commands.md` run through `bash -c` on Linux and macOS and throu
 | `FLOW_MAX_RETRIES` | `2` | builds or reviews per step before the run stops |
 | `FLOW_MAX_REVIEW_ROUNDS` | `3` | times a ticket may be sent back before the run stops |
 | `FLOW_GATE` | `on` | `off` skips Build, Test and Lint after each ticket, and also the Done when and test-first checks |
+| `FLOW_GATE_FULL` | unset | `1` runs the full Build, Test and Lint after every ticket, even when `commands.md` has a `Quick:` line |
+| `FLOW_SMALL_FILES` | `3` | most files a ticket may change and still get the single review |
+| `FLOW_SMALL_LINES` | `60` | most changed lines for the single review; `0` turns the single review off |
 | `FLOW_GATE_TIMEOUT` | `30` | minutes each gate command and the smoke test may run; `0` means no limit. A failed smoke test writes `.feature-flow/state/<feature>.smoke.log` |
 | `FLOW_SMOKE` | the `Smoke:` line of `commands.md` | command run before every ticket; the run stops if it fails |
 | `FLOW_DIR`, `FLOW_TICKETS` | `plans`, `tasks` | where the plans and the ticket folder live |
 | `FLOW_NO_OPEN` | unset | `1` makes `flow-view.py` never open a browser |
 | `FLOW_WATCH_SECONDS` | `3` | how often `flow-view.py --watch` rewrites the page |
 
-The run also stops on its own after a number of phases (`BUILD` and `REVIEW` hand-outs, the spec review and the quality review each counting as one) that grows with the ticket count, recomputed at every pick, so a loop of failures cannot go on forever.
+The run also stops on its own after a number of phases (`BUILD` and `REVIEW` hand-outs, the spec review and the quality review each counting as one, a single review counting as one) that grows with the ticket count, recomputed at every pick, so a loop of failures cannot go on forever.
 
 ## What is tested
 
@@ -305,6 +320,17 @@ A `package` job builds the wheel and the sdist and runs `tests/package_smoke.py`
 
 `RUN_REAL=1 bash tests/smoke-real.sh --interactive` is the acceptance run with Claude Code. It runs real sessions on the demo project and spends money, which is why it asks for `RUN_REAL=1`.
 
+## Limits
+
+feature-flow's layers are tripwires, not a security boundary. They catch accidents and lazy shortcuts by an agent; a determined agent that controls the session could still get around them.
+
+- **The verdict relay is trusted.** The session saves a reviewer's reply and hands it to `flow.py verdict`. The conductor reads `REVIEW: PASS` or `REVIEW: FAIL` from that file and cannot prove the session passed it on unedited.
+- **The floor guard reads diffs with patterns.** It does not see a test made trivially true by other means (a mock that returns the expected answer, an `assert` on something that is always set, a test that no longer exercises the code), or an assertion weakened without being deleted. It does catch assertions that cannot fail (`trivial-assert`) and warns the reviewer when a test file loses assertions. A new test with no assertion at all is not caught. The red-first proof only covers tickets with `Test first: yes`.
+- **A plan can be wrong and still pass.** The plan lint checks that every ticket has a way to be proven and that `commands.md` has a Test command. It cannot tell whether the plan builds the right thing; the second yes is yours.
+- **The trust runner stops accidents, not the session.** It catches a builder editing the conductor mid-run. The session that runs it is the thing it cannot check; a hand-run `flow-trust.py` is unprotected (see above).
+- **Little real-world use so far.** Almost everything has been built by feature-flow on its own repo. The Codex skill and the Codex planner have not been run by hand, and the Quick gate has only been run by tests. See [docs/field-run.md](docs/field-run.md) for how to try it on your own repo and what to send back.
+- **One ticket at a time**, with a handoff to a new session every few tickets.
+
 ## Upgrading
 
 Earlier versions had seven skills and an unattended loop. The five flow skills are gone, and `/feature-flow` replaces them:

{feature_flow_cli-0.5.0 → feature_flow_cli-0.8.0}/README.md

@@ -6,10 +6,10 @@
 
 Plan a feature as a graph of small tickets, then build them in the session you are already in. One command, `/feature-flow`, does both. Every ticket is built by one fresh subagent and checked by another that never saw the builder's reasoning. A script, not the agent, decides the order of the steps, runs the build and tests, and watches for work that weakens the checks, and the whole run has limits.
 
-One skill, 2 agent roles, a Python conductor, 4 Python scripts, an installer for both agents, a demo and a test suite. All of it is Python (standard library only), so it runs on Linux, macOS and Windows. MIT licensed.
+One skill, 4 agent roles, a Python conductor, 6 Python scripts (`flow`, `flow-trust`, `flow-status`, `flow-view`, `gate`, `floor-guard`), an installer for both agents, a demo and a test suite. All of it is Python (standard library only), so it runs on Linux, macOS and Windows. MIT licensed.
 
 - [Quick start](#quick-start) · [How a ticket flows](#how-a-ticket-flows) · [The skill and the roles](#the-skill-and-the-roles) · [Plans and tickets](#plans-and-tickets)
-- [See the graph](#see-the-graph) · [Long features and handoff](#long-features-and-handoff) · [What is tested](#what-is-tested) · [Upgrading](#upgrading) · [Caution](#caution)
+- [See the graph](#see-the-graph) · [Long features and handoff](#long-features-and-handoff) · [What is tested](#what-is-tested) · [Limits](#limits) · [Upgrading](#upgrading) · [Caution](#caution)
 
 ## Quick start
 
@@ -32,7 +32,7 @@ Without a clone, the same installer runs from [PyPI](https://pypi.org/project/fe
 uvx feature-flow-cli install /path/to/your/repo --agent all   # or: pipx run feature-flow-cli install ...
 ```
 
-The package puts a `feature-flow` command on your PATH with `install`, `status <feature>` and `view <feature>`. It installs the same files, byte for byte, as `install.py` from a clone.
+The package puts a `feature-flow` command on your PATH with `install`, `uninstall`, `status <feature>`, `view <feature>`, `reset <feature>` and `report <feature>`. It installs the same files, byte for byte, as `install.py` from a clone.
 
 The installer lists what it wrote in `.feature-flow/installed.txt`, with each file's hash in `.feature-flow/installed.sha256`. Commit those files (`git add --pathspec-from-file=.feature-flow/installed.txt`); until you do, the flow does not count them as uncommitted changes. Installing a newer version over an older one updates every file nobody edited since it was installed, and keeps (and names) the ones you changed; `--force` replaces those too.
 
@@ -52,7 +52,7 @@ Then, in your repo, in the agent:
 
 The same command plans when `plans/csv-export/` does not exist yet and builds when it does. After your second yes it commits the new plan folder, and only that folder, then goes straight on to building it; say so if you want it to stop after planning.
 
-**Planning asks you twice.** First the session shows a short feature brief, written from your conversation (what, why, scope, the bar, and anything it had to assume), and waits for yes, edit or cancel. Then a fresh `feature-planner` subagent, given only that brief, reads the code, looks up outside docs where the code cannot answer, and writes a draft plan into the git-ignored `.feature-flow/state/draft/`. A fresh `plan-reviewer` checks the draft against the brief. The session shows you the goal, the commands, the ticket graph, what was dropped and the review result, and waits for a second yes. Only then does `flow.py plan-accept` copy the draft into `plans/<feature>/`, and the session commits it and starts the build.
+**Planning asks you twice.** First the session shows a short feature brief, written from your conversation (what, why, scope, the bar, and anything it had to assume), and waits for yes, edit or cancel. Then a fresh `feature-planner` subagent, given only that brief, reads the code, looks up outside docs where the code cannot answer, and writes a draft plan into the git-ignored `.feature-flow/state/draft/`. The planner folds changes too small to stand alone into the ticket they belong to, and sets `Review: full` on a ticket that deserves both reviews whatever its size. A fresh `plan-reviewer` checks the draft against the brief. The session shows you the goal, the commands, the ticket graph, what was dropped and the review result, and waits for a second yes. Only then does `flow.py plan-accept` copy the draft into `plans/<feature>/`, and the session commits it and starts the build.
 
 Try the graph first, with no setup and no agent: `bash examples/demo.sh --open`.
 
@@ -102,6 +102,8 @@ The Claude Code skill is `skills/feature-flow/`. The Codex skill is written by h
                                               │ PASS                │
                                               ▼                     │
  quality review: a second fresh reviewer subagent             FAIL ─┤
+   (a small ticket whose check block passed gets one combined
+    review instead of these two; see below)
                                               │ PASS                ▼
                                               ▼        findings written into the ticket,
                                      next ticket       reopened, built again (3 rounds max);
@@ -111,7 +113,11 @@ The Claude Code skill is `skills/feature-flow/`. The Codex skill is written by h
 
 `scripts/flow.py` is the conductor. The session asks it `next`, and it answers with one line: `BUILD`, `REVIEW`, `DONE`, `STOP` or `HANDOFF`. It prints the full prompt for each subagent from runtime-neutral guides, so the session never writes one itself.
 
-**What the script checks and what it trusts.** The conductor verifies the build from the repo: the ticket file must say `resolved`, the tree must be clean and committed, and it runs the gate and the floor guard itself. It also runs the `check` block under each ticket's Done when and compares the exit code and printed text, and for a `Test first: yes` ticket it proves the red test commit itself: it checks out the test-only commit, runs Test, and requires it to fail before the code. A failure of either goes back to the builder before any reviewer is started. It also checks that the reviewer changed no tracked file and made no commit. The review verdicts are different: each reviewer's reply (spec review, then quality review) is relayed by the session, which saves it to a file and hands it to `flow.py verdict`. The script reads `REVIEW: PASS` or `REVIEW: FAIL` from that reply; it cannot prove the session passed it on unedited. A ticket moves on only after two PASS verdicts.
+**What the script checks and what it trusts.** The conductor verifies the build from the repo: the ticket file must say `resolved`, the tree must be clean and committed, and it runs the gate and the floor guard itself. It also runs the `check` block under each ticket's Done when and compares the exit code and printed text, and for a `Test first: yes` ticket it proves the red test commit itself: it checks out the test-only commit, runs Test, and requires it to fail before the code. A failure of either goes back to the builder before any reviewer is started. It also checks that the reviewer changed no tracked file and made no commit. The review verdicts are different: each reviewer's reply (spec review, then quality review) is relayed by the session, which saves it to a file and hands it to `flow.py verdict`. The script reads `REVIEW: PASS` or `REVIEW: FAIL` from that reply; it cannot prove the session passed it on unedited. A ticket moves on only after two PASS verdicts, or one for a ticket the conductor judged small. The size is measured from the repo (`git diff` against the commit the ticket started from), never taken from the builder.
+
+**The gate: full or quick.** The gate runs Build, Test and Lint after every ticket. With an optional `Quick:` line in `commands.md` (a faster subset of `Test`), it runs Build, Quick and Lint after the tickets in the middle of a plan, and the full Build, Test and Lint after the last ticket, before a handoff, and under `FLOW_GATE_FULL=1`. A plan without `Quick:` runs the full gate every time. The test-first proof still runs the full `Test` command.
+
+**One review for a small ticket.** A ticket whose built diff is 3 files and 60 changed lines at most (the plan folder left out), and whose `check` block ran and passed, gets one combined review instead of the spec and quality reviews. The conductor measures the diff itself. `Review: full` in the ticket (as it was at the start), `Type: convert`, no `check` block, or `FLOW_GATE=off` keep both reviews. Every other conductor check still runs on every ticket.
 
 ## The skill and the roles
 
@@ -178,14 +184,18 @@ prints OK
 - **The Answers are the handoff between subagents.** The next builder reads the Answers of the tickets it depends on.
 - `settle` tickets record a decision. `convert` tickets migrate something and must be safe to run twice.
 - **A worker may change only** its own Status line and Answer, lines appended to `map.md` and `learnings.md`, and the code the ticket calls for. Rewriting its own Done when, editing another ticket, or touching `commands.md` fails the guard.
-- `Floor:` categories: `skip`, `suppress`, `empty-catch`, `test-delete`, `threshold`, `config`, `ticket-edit`, `commands-edit`, and `flow-edit` (allows the conductor's code check below, for the build only). `skip` covers skipped, expected-fail and focused tests (`.only(`, `fit(`, `fdescribe(` on test paths); `config` covers more lint and test config files, the lint and test sections of `pyproject.toml` and `setup.cfg`, scripts and test keys in `package.json`, new skip or xfail words in `conftest.py`, and a `Makefile` only when `commands.md` uses `make`. A test file that loses assertions is shown to the reviewer as a warning, not a finding. The line is read from the ticket as it was before the work started, so a worker cannot excuse itself.
+- `Floor:` categories: `skip`, `suppress`, `empty-catch`, `test-delete`, `threshold`, `trivial-assert` (an assertion that cannot fail, added to a test file: `assert True`, `assertEqual(x, x)`, `expect(v).toBe(v)`), `config`, `ticket-edit`, `commands-edit`, and `flow-edit` (allows the conductor's code check below, for the build only). `skip` covers skipped, expected-fail and focused tests (`.only(`, `fit(`, `fdescribe(` on test paths); `config` covers more lint and test config files, the lint and test sections of `pyproject.toml` and `setup.cfg`, scripts and test keys in `package.json`, new skip or xfail words in `conftest.py`, and a `Makefile` only when `commands.md` uses `make`. A test file that loses assertions is shown to the reviewer as a warning, not a finding. The line is read from the ticket as it was before the work started, so a worker cannot excuse itself.
 - The guard needs the plan to be tracked by git. If you keep tickets in an ignored folder, it cannot see changes to them.
 - The commands in `commands.md` run with nobody watching and must exit non zero on failure.
 
 ## See the graph
 
+![The animated ticket graph for the demo plan: five of ten tickets resolved, two ready, one in progress](docs/flow-view.png)
+
+*The page `flow-view` writes, shown for the demo plan from `examples/demo.sh`: resolved tickets in green, ready ones in amber, the one being worked in blue, the rest waiting. Press Replay to watch the run back from git history.*
+
 ```bash
-python3 scripts/flow-view.py csv-export            write the page and open it
+python3 scripts/flow-view.py csv-export            write the page and open it (or: feature-flow view csv-export)
 python3 scripts/flow-view.py csv-export --watch    keep it updating while tickets are built
 bash examples/demo.sh --open                    try it on a made up project, no setup needed
 ```
@@ -226,6 +236,8 @@ python3 scripts/flow-status.py <feature>                  table of tickets and w
 python3 scripts/flow-status.py <feature> --next           path of the next ready ticket (exit 10 = done, 11 = stuck)
 python3 scripts/flow-status.py <feature> --counts         one line of counts
 python3 scripts/flow-status.py <feature> --check          cycles, missing blockers, missing Done when, unordered mentions
+python3 scripts/flow-status.py <feature> --lint           --check plus: a check block (or `Check: none <why>`) on every ticket, a Test command
+feature-flow report <feature>                             what a run did, from its log: builds, reviews, failed checks, stops
 python3 scripts/flow-status.py <feature> --mermaid        the ticket graph, coloured by status (add "plain" for none)
 python3 scripts/flow-status.py <feature> --json           every ticket with status, blockers and readiness
 python3 scripts/flow-view.py <feature> [--watch]          the animated graph page, opened in your browser
@@ -247,13 +259,16 @@ The commands in `commands.md` run through `bash -c` on Linux and macOS and throu
 | `FLOW_MAX_RETRIES` | `2` | builds or reviews per step before the run stops |
 | `FLOW_MAX_REVIEW_ROUNDS` | `3` | times a ticket may be sent back before the run stops |
 | `FLOW_GATE` | `on` | `off` skips Build, Test and Lint after each ticket, and also the Done when and test-first checks |
+| `FLOW_GATE_FULL` | unset | `1` runs the full Build, Test and Lint after every ticket, even when `commands.md` has a `Quick:` line |
+| `FLOW_SMALL_FILES` | `3` | most files a ticket may change and still get the single review |
+| `FLOW_SMALL_LINES` | `60` | most changed lines for the single review; `0` turns the single review off |
 | `FLOW_GATE_TIMEOUT` | `30` | minutes each gate command and the smoke test may run; `0` means no limit. A failed smoke test writes `.feature-flow/state/<feature>.smoke.log` |
 | `FLOW_SMOKE` | the `Smoke:` line of `commands.md` | command run before every ticket; the run stops if it fails |
 | `FLOW_DIR`, `FLOW_TICKETS` | `plans`, `tasks` | where the plans and the ticket folder live |
 | `FLOW_NO_OPEN` | unset | `1` makes `flow-view.py` never open a browser |
 | `FLOW_WATCH_SECONDS` | `3` | how often `flow-view.py --watch` rewrites the page |
 
-The run also stops on its own after a number of phases (`BUILD` and `REVIEW` hand-outs, the spec review and the quality review each counting as one) that grows with the ticket count, recomputed at every pick, so a loop of failures cannot go on forever.
+The run also stops on its own after a number of phases (`BUILD` and `REVIEW` hand-outs, the spec review and the quality review each counting as one, a single review counting as one) that grows with the ticket count, recomputed at every pick, so a loop of failures cannot go on forever.
 
 ## What is tested
 
@@ -286,6 +301,17 @@ A `package` job builds the wheel and the sdist and runs `tests/package_smoke.py`
 
 `RUN_REAL=1 bash tests/smoke-real.sh --interactive` is the acceptance run with Claude Code. It runs real sessions on the demo project and spends money, which is why it asks for `RUN_REAL=1`.
 
+## Limits
+
+feature-flow's layers are tripwires, not a security boundary. They catch accidents and lazy shortcuts by an agent; a determined agent that controls the session could still get around them.
+
+- **The verdict relay is trusted.** The session saves a reviewer's reply and hands it to `flow.py verdict`. The conductor reads `REVIEW: PASS` or `REVIEW: FAIL` from that file and cannot prove the session passed it on unedited.
+- **The floor guard reads diffs with patterns.** It does not see a test made trivially true by other means (a mock that returns the expected answer, an `assert` on something that is always set, a test that no longer exercises the code), or an assertion weakened without being deleted. It does catch assertions that cannot fail (`trivial-assert`) and warns the reviewer when a test file loses assertions. A new test with no assertion at all is not caught. The red-first proof only covers tickets with `Test first: yes`.
+- **A plan can be wrong and still pass.** The plan lint checks that every ticket has a way to be proven and that `commands.md` has a Test command. It cannot tell whether the plan builds the right thing; the second yes is yours.
+- **The trust runner stops accidents, not the session.** It catches a builder editing the conductor mid-run. The session that runs it is the thing it cannot check; a hand-run `flow-trust.py` is unprotected (see above).
+- **Little real-world use so far.** Almost everything has been built by feature-flow on its own repo. The Codex skill and the Codex planner have not been run by hand, and the Quick gate has only been run by tests. See [docs/field-run.md](docs/field-run.md) for how to try it on your own repo and what to send back.
+- **One ticket at a time**, with a handoff to a new session every few tickets.
+
 ## Upgrading
 
 Earlier versions had seven skills and an unattended loop. The five flow skills are gone, and `/feature-flow` replaces them:

{feature_flow_cli-0.5.0 → feature_flow_cli-0.8.0}/adapters/codex/feature-flow/SKILL.md

@@ -15,15 +15,15 @@ The conductor is `python3 scripts/flow.py <feature> <command>`. If `scripts/flow
 
 Every conductor command (`start`, `next`, `prompt`, `verdict`, `reset`, `plan-prompt`, `plan-review-prompt`, `plan-accept`) runs through `flow-trust.py`, never `flow.py` itself. `<S>` below is the folder of the `flow.py` picked above: `scripts` for the repo's own install, else `"${FEATURE_FLOW_HOME:-$HOME/.feature-flow}/scripts"`. `flow-trust.py` is started by this loader line, which checks the file against the sha256 pinned here and runs those same bytes. Copy it exactly, replacing only `<S>`:
 
-    python3 -I -c "import hashlib,sys;b=open(sys.argv[1],'rb').read().replace(b'\r\n',b'\n');sys.exit(exec(compile(b,'flow-trust','exec')) if hashlib.sha256(b).hexdigest()==sys.argv[2] else 'flow-trust.py does not match this skill')" <S>/flow-trust.py ec4e2430b3ed4dae4fa5d9190c3e1726294a0f854bf92584c0c756a07b9029d9
+    python3 -I -c "import hashlib,sys;b=open(sys.argv[1],'rb').read().replace(b'\r\n',b'\n');sys.exit(exec(compile(b,'flow-trust','exec')) if hashlib.sha256(b).hexdigest()==sys.argv[2] else 'flow-trust.py does not match this skill')" <S>/flow-trust.py 3a4b28b079b7c657e9a6d843cf1e69ac3c794639ea072f3be96cf94726ab370e
 
 A full conductor command, here `next` (any other command and its arguments go where `next` is):
 
-    FLOW_TRUST=<digest> FLOW_SESSION=<token> FLOW_INVOKE='$feature-flow' python3 -I -c "import hashlib,sys;b=open(sys.argv[1],'rb').read().replace(b'\r\n',b'\n');sys.exit(exec(compile(b,'flow-trust','exec')) if hashlib.sha256(b).hexdigest()==sys.argv[2] else 'flow-trust.py does not match this skill')" <S>/flow-trust.py ec4e2430b3ed4dae4fa5d9190c3e1726294a0f854bf92584c0c756a07b9029d9 <feature> next
+    FLOW_TRUST=<digest> FLOW_SESSION=<token> FLOW_INVOKE='$feature-flow' python3 -I -c "import hashlib,sys;b=open(sys.argv[1],'rb').read().replace(b'\r\n',b'\n');sys.exit(exec(compile(b,'flow-trust','exec')) if hashlib.sha256(b).hexdigest()==sys.argv[2] else 'flow-trust.py does not match this skill')" <S>/flow-trust.py 3a4b28b079b7c657e9a6d843cf1e69ac3c794639ea072f3be96cf94726ab370e <feature> next
 
 - The first line of the output is `TRUST <digest>`. Keep that digest and pass it as `FLOW_TRUST` on the next conductor call. Treat the rest as the conductor's output and act on it as below (for `prompt`, `plan-prompt` and `plan-review-prompt`, the child agent's prompt is everything after the `TRUST` line). Use `FLOW_TRUST=new` only on this session's first conductor call, or when resuming from an old-style `HANDOFF` line (below).
 - If you no longer have the last `TRUST` digest, stop and say so. Never guess it, and never use `new` in its place.
-- On the `next` right after a `BUILD <ticket> <NN> <sha>`, add `--after-build <ticket> <sha>` before the feature: `... <S>/flow-trust.py ec4e2430b3ed4dae4fa5d9190c3e1726294a0f854bf92584c0c756a07b9029d9 --after-build <ticket> <sha> <feature> next`. If the output has a `FLOW-EDIT <paths>` line after `TRUST`, the build changed feature-flow's own files and its ticket allows that: carry on; without `auto`, first tell the user which flow files changed.
+- On the `next` right after a `BUILD <ticket> <NN> <sha>`, add `--after-build <ticket> <sha>` before the feature: `... <S>/flow-trust.py 3a4b28b079b7c657e9a6d843cf1e69ac3c794639ea072f3be96cf94726ab370e --after-build <ticket> <sha> <feature> next`. If the output has a `FLOW-EDIT <paths>` line after `TRUST`, the build changed feature-flow's own files and its ticket allows that: carry on; without `auto`, first tell the user which flow files changed.
 - If the first line is `STOP` (from `flow-trust.py`), or the loader prints `flow-trust.py does not match this skill` (say to reinstall feature-flow: the skill and `flow-trust.py` do not match), report it, show the `python3 <S>/flow-status.py <feature>` table, and stop. A `STOP` first line may be followed by the conductor's own output: never act on that. Never fix it and carry on.
 - A `HANDOFF` line from `flow-trust.py` has a third field after the invocation and the feature: the digest. When the feature is followed by a `<16 hex>.<16 hex>` word, the user is resuming from a `HANDOFF` line and that word is the digest: pass it as `FLOW_TRUST` on `start`. When a resumed session gets no digest (an old-style `HANDOFF` line), use `FLOW_TRUST=new` and warn the user that the flow's files could not be checked since the last session.
 
@@ -57,14 +57,14 @@ If `start` prints `STOP` naming another owner, another session may still be work
 
 If the user says the flow is stuck on a ticket or asks for a reset, run `reset` (or `reset <NN>` to redo one ticket): it reopens a half-built ticket, commits that, and clears the run, then run `start` again. It needs `FLOW_TAKEOVER=1` while a session owns the feature, on the same clear yes. Never reset on your own.
 
-Say what will happen: for each ticket, a builder subagent and then a reviewer subagent. After every few tickets (`FLOW_TICKETS_PER_SESSION`, default 4) you hand off to a new session. Ask for a yes, unless `auto` was given or you came straight from planning: the plan's yes already covered the build.
+Say what will happen: for each ticket, a builder subagent and then a fresh reviewer subagent for each review pass, one or two per ticket. After every few tickets (`FLOW_TICKETS_PER_SESSION`, default 4) you hand off to a new session. Ask for a yes, unless `auto` was given or you came straight from planning: the plan's yes already covered the build.
 
 ## The loop
 
 Run `next`, act on its one line after `TRUST` (and any `FLOW-EDIT` line), and repeat:
 
 - `BUILD <ticket> <NN> <sha>`: run `prompt`. Start the builder with `spawn_agent(task_name="ticket_builder_<NN>_<k>", fork_turns="none", message=...)`. The message is "Work only in <repo>." followed by the whole `prompt` output, which already starts with the builder role. Use a new `task_name` for every spawn: keep a count per ticket in this session, and `<k>` is the number of builders already started for this ticket, plus 1 (1 for the first, then up each time `next` sends the ticket back to a builder). Get its final reply with `wait_agent`, then run `next` with `--after-build <ticket> <sha>` from that `BUILD` line.
-- `REVIEW <ticket> <NN> <sha>`: run `prompt`. Start a new reviewer the same way, with `fork_turns="none"` so it never sees the builder's context, and a unique `task_name` per spawn: `ticket_reviewer_<NN>_<pass>_<k>`, where `<pass>` is `spec` or `quality` by the pass the prompt names (`(spec pass)` or `(quality pass)`; `review` if it names none) and `<k>` is the number of reviews already started for this ticket in this session, plus 1 (1 for the first). Count every review, also one that ended in `RETRY` or a failed review followed by a rebuild, so a repeated pass never reuses a name. Get its final reply with `wait_agent`. A child cannot be made read-only, so the reviewer works from its instructions; the conductor catches any edit it makes. Save the whole reply with the shell: `cat > .feature-flow/state/flow-review-<feature>.txt <<'EOF'` ... `EOF`. Then run `verdict .feature-flow/state/flow-review-<feature>.txt` and `next`. If `verdict` prints `RETRY`, just run `next`.
+- `REVIEW <ticket> <NN> <sha>`: run `prompt`. Start a new reviewer the same way, with `fork_turns="none"` so it never sees the builder's context, and a unique `task_name` per spawn: `ticket_reviewer_<NN>_<pass>_<k>`, where `<pass>` is `spec`, `quality` or `single` by the pass the prompt names (`(spec pass)`, `(quality pass)` or `(single pass)`; `review` if it names none) and `<k>` is the number of reviews already started for this ticket in this session, plus 1 (1 for the first). Count every review, also one that ended in `RETRY` or a failed review followed by a rebuild, so a repeated pass never reuses a name. Get its final reply with `wait_agent`. A child cannot be made read-only, so the reviewer works from its instructions; the conductor catches any edit it makes. Save the whole reply with the shell: `cat > .feature-flow/state/flow-review-<feature>.txt <<'EOF'` ... `EOF`. Then run `verdict .feature-flow/state/flow-review-<feature>.txt` and `next`. If `verdict` prints `RETRY`, just run `next`.
 - `DONE <summary>`: report it and suggest `$feature-flow <feature> show`.
 - `STOP <reason>`: report the reason, run `python3 scripts/flow-status.py <feature>`, show the table, and stop.
 - `HANDOFF <line>`: stop here. Tell the user to open a new session and type exactly `<line>`, the whole line with its digest at the end. The new session resumes where this one stopped.

{feature_flow_cli-0.5.0 → feature_flow_cli-0.8.0}/feature_flow/__init__.py

@@ -1,3 +1,3 @@
 """Feature Flow: a ticket-graph workflow for coding agents."""
 
-__version__ = "0.5.0"
+__version__ = "0.8.0"

{feature_flow_cli-0.5.0 → feature_flow_cli-0.8.0}/feature_flow/checks.py

@@ -55,11 +55,11 @@ def flow_status(scripts, feature, mode, root=None):
     return Result(code, out.text())
 
 
-def gate(scripts, feature, timeout=None):
+def gate(scripts, feature, timeout=None, quick=False):
     """The gate, run in process. stderr is folded into the output as the subprocess call did.
-    timeout is minutes, None for FLOW_GATE_TIMEOUT."""
+    timeout is minutes, None for FLOW_GATE_TIMEOUT. quick runs Quick in the place of Test."""
     chunks = []
-    code = gate_module.run(str(feature), chunks.append, chunks.append, timeout)
+    code = gate_module.run(str(feature), chunks.append, chunks.append, timeout, quick)
     out = "".join(chunks).encode("utf-8", "surrogateescape").decode("utf-8", "replace")
     out = out.replace("\r\n", "\n").replace("\r", "\n")
     return Result(code, out)

{feature_flow_cli-0.5.0 → feature_flow_cli-0.8.0}/feature_flow/cli.py

@@ -107,7 +107,7 @@ def run(args, scripts, trusted):
     except Stop as stop:
         line = "STOP %s" % stop
         if conductor is not None:
-            conductor.log("STOP")
+            conductor.log("STOP " + " ".join(str(stop).split())[:200])
         print(line)
         return 1
     out = sys.stdout

{feature_flow_cli-0.5.0 → feature_flow_cli-0.8.0}/feature_flow/codehash.py

@@ -16,7 +16,7 @@ def _files(scripts):
     found = [p for p in package.rglob("*.py") if "__pycache__" not in p.parts]
     folder = Path(scripts).resolve()
     found += [folder / name for name in SCRIPTS if (folder / name).is_file()]
-    for phase in ("build", "review", "review-quality"):
+    for phase in ("build", "review", "review-quality", "review-single"):
         for folder, names in (("agents", prompts.ROLES), ("guides", prompts.GUIDES)):
             try:
                 found.append(prompts.find_file(scripts, folder, names[phase]).resolve())

{feature_flow_cli-0.5.0 → feature_flow_cli-0.8.0}/feature_flow/command.py

@@ -9,7 +9,7 @@ import sys
 
 from pathlib import Path
 
-from feature_flow import __version__, cli, install, status, suggest, uninstall, view
+from feature_flow import __version__, cli, install, report, status, suggest, uninstall, view
 
 USAGE = """\
 usage: feature-flow install [target-repo] [--agent claude|codex|all] [--user] [--private] [--force] [--dry-run]
@@ -17,15 +17,17 @@ usage: feature-flow install [target-repo] [--agent claude|codex|all] [--user] [-
        feature-flow status <feature> [--next | --counts | --check | --mermaid [plain] | --json]
        feature-flow view <feature> [--watch] [--no-open] [--out FILE]
        feature-flow reset <feature> [NN]
+       feature-flow report <feature>
        feature-flow --version
 install copies the skill, its roles, scripts and guides into a repo; --user installs them once for every repo, in ~/.claude, ~/.agents and ~/.feature-flow, and writes nothing into a repo. feature-flow install --help says more.
 uninstall removes exactly what install wrote (files you edited are kept); --user removes the personal install in ~/.claude, ~/.agents and ~/.feature-flow.
 status and view read plans/<feature>/ in the current directory, like scripts/flow-status.py and scripts/flow-view.py.
 reset reopens a half-built ticket (or ticket NN), commits that, and clears the run, like scripts/flow.py <feature> reset.
+report prints what a run did (builds, reviews, failed checks, stops) from its log in .feature-flow/state/. Read-only.
 """
 
 
-COMMANDS = ("install", "uninstall", "status", "view", "reset", "--version", "--help")
+COMMANDS = ("install", "uninstall", "status", "view", "reset", "report", "--version", "--help")
 
 
 def main(argv=None):
@@ -46,6 +48,8 @@ def main(argv=None):
         return status.main(rest)
     if command == "view":
         return view.main(rest, here=os.path.join(install.source_root(), "scripts"))
+    if command == "report":
+        return report.main(rest)
     if command == "reset":
         if not rest or len(rest) > 2:
             sys.stderr.write(USAGE)

{feature_flow_cli-0.5.0 → feature_flow_cli-0.8.0}/feature_flow/conductor.py

@@ -51,6 +51,9 @@ class Conductor:
         self.gate_timeout = _env_int("FLOW_GATE_TIMEOUT", 30)
         self.gate_on = os.environ.get("FLOW_GATE", "on") != "off"
         self.per_session = _env_int("FLOW_TICKETS_PER_SESSION", 4)
+        self.small_files = _env_int("FLOW_SMALL_FILES", 3)
+        self.small_lines = _env_int("FLOW_SMALL_LINES", 60)
+        self.checks_ran = False
         self.relay = os.environ.get("FLOW_RELAY", "0") == "1"
         self.invoke = os.environ.get("FLOW_INVOKE") or "/feature-flow"
         top = git.toplevel()
@@ -125,6 +128,21 @@ class Conductor:
                        % ("timed out after %d minutes" % self.gate_timeout if result.timed_out else "failed",
                           self.ticket_name(), cmd, gate.TAIL, log))
 
+    def gate_quick(self):
+        """True when this ticket's gate may run Quick in place of Test."""
+        if os.environ.get("FLOW_GATE_FULL") == "1":
+            return False
+        if not tickets.commands_value(self.commands, "Quick"):
+            return False
+        if self.per_session > 0 and self.num("session_done") + 1 >= self.per_session:
+            return False
+        counts = {}
+        for word in checks.flow_status(self.scripts, self.feature, "--counts").out.split():
+            key, _, value = word.partition("=")
+            if value.isdigit():
+                counts[key] = int(value)
+        return sum(counts.get(k, 0) for k in ("open", "claimed", "waiting", "unknown")) > 0
+
     def run_limit(self):
         result = checks.flow_status(self.scripts, self.feature, "--counts")
         total = 0
@@ -246,10 +264,12 @@ class Conductor:
         if not git.is_clean():
             raise Stop("working tree is dirty after %s, it should have been committed" % self.ticket_name())
         if self.gate_on:
-            result = checks.gate(self.scripts, self.feature, self.gate_timeout)
+            quick = self.gate_quick()
+            result = checks.gate(self.scripts, self.feature, self.gate_timeout, quick=quick)
+            self.log("GATE-QUICK" if quick else "GATE-FULL")
             self.log("GATE-PASS" if result.ok else "GATE-FAIL")
             if not result.ok:
-                return self.send_back("gate", result.out)
+                return self.send_back("gate (quick)" if quick else "gate (full)", result.out)
         result = checks.floor_guard(self.scripts, self.feature, self.get("num"), self.get("base"))
         self.log("GUARD-PASS" if result.ok else "GUARD-FAIL")
         if not result.ok:
@@ -266,9 +286,29 @@ class Conductor:
                 return self.send_back("test first", report)
             if note:
                 notes.append(note)
+        self.st["review_pass"] = "spec"
+        if self.gate_on and self.checks_ran:
+            small = self.small_note()
+            if small:
+                self.st["review_pass"] = "single"
+                self.log("REVIEW-SMALL")
+                notes.append(small)
         self.st["review_notes"] = NOTE_SEP.join(notes)
         return self.hand_out_review()
 
+    def small_note(self):
+        """The note for the reviewer when the built diff is small enough for one review, else ""."""
+        base = self.ticket_at_base()
+        if proof.review_mode(base) != "auto" or self.small_lines <= 0:
+            return ""
+        if re.search(r"^Type:[ \t]*convert\b", base.split("\n## ", 1)[0], re.IGNORECASE | re.MULTILINE):
+            return ""
+        files, lines, binary = git.diff_size(self.get("base"), "HEAD", self.plan.as_posix())
+        if binary or files > self.small_files or lines > self.small_lines:
+            return ""
+        return ("the conductor judged this ticket small (%d files, %d lines): one review covers the spec and "
+                "quality passes" % (files, lines))
+
     def ticket_at_base(self):
         """The ticket text as it was at the base commit, so a builder cannot change what is checked."""
         rel = proof.repo_relative(self.ticket())
@@ -286,6 +326,7 @@ class Conductor:
             found = proof.checks_in(self.ticket_at_base())
         except proof.ParseError as err:
             raise Stop("%s has a check block the conductor cannot read: %s" % (self.ticket_name(), err))
+        self.checks_ran = bool(found)
         if not found:
             self.log("DONEWHEN-SKIP")
             return None, "the conductor ran no Done when checks: the ticket has no check block"
@@ -424,7 +465,7 @@ class Conductor:
             raise Stop("the reviewer changed tracked files, which a reviewer must never do")
         verdict = self.get("verdict")
         self.st["verdict"] = ""
-        if verdict == "pass" and self.get("review_pass", "spec") != "quality":
+        if verdict == "pass" and self.get("review_pass", "spec") == "spec":
             self.st["review_pass"] = "quality"
             self.st["review_attempt"] = 0
             return self.hand_out_review()
@@ -436,8 +477,8 @@ class Conductor:
             return self.pick_ticket()
         if verdict == "fail":
             findings = state.read_text(self.findings_file, "findings") or ""
-            return self.send_back("quality review" if self.get("review_pass") == "quality" else "spec review",
-                                  findings)
+            return self.send_back({"quality": "quality review", "single": "single review"}.get(
+                self.get("review_pass"), "spec review"), findings)
         if self.num("review_attempt") >= self.max_retries:
             raise Stop("no review verdict for %s after %d attempt(s)" % (self.ticket_name(), self.max_retries))
         return self.hand_out_review()
@@ -449,8 +490,8 @@ class Conductor:
         if phase not in ("build", "review"):
             raise NoPhase("no BUILD or REVIEW is pending for %s" % self.feature)
         try:
-            if phase == "review" and self.get("review_pass") == "quality":
-                phase = "review-quality"
+            if phase == "review" and self.get("review_pass") in ("quality", "single"):
+                phase = "review-" + self.get("review_pass")
             return prompts.build(phase, self.scripts, self.feature, self.ticket(), self.get("num"), self.get("base"),
                                  [n for n in self.get("review_notes").split(NOTE_SEP) if n] if phase != "build" else (),
                                  retry=self.num("round") > 0)
@@ -532,7 +573,7 @@ class Conductor:
         self.no_plan_yet()
         if not self.draft.is_dir():
             raise Stop("no draft plan in %s. run the planner first" % self.draft_text())
-        check = checks.flow_status(self.scripts, self.feature, "--check", root=self.draft_root)
+        check = checks.flow_status(self.scripts, self.feature, "--lint", root=self.draft_root)
         if not check.ok:
             raise Stop("the draft fails the plan check, fix it first: %s"
                        % " ".join(check.out.split())[:400])

{feature_flow_cli-0.5.0 → feature_flow_cli-0.8.0}/feature_flow/floorguard.py

@@ -7,7 +7,7 @@ lowered thresholds, edited lint or test config.
 it also protects the plan from the worker: only the ticket's own Status line and Answer,
 appended lines in map.md and learnings.md may change, and nothing else under the plans folder.
 a ticket can allow categories with a line "Floor: allow skip, suppress" (skip, suppress,
-empty-catch, test-delete, threshold, config, ticket-edit, commands-edit). the line is
+empty-catch, test-delete, threshold, trivial-assert, config, ticket-edit, commands-edit). the line is
 read from the ticket as it was at base-commit, so a worker cannot excuse itself.
 run it from the repo root. exit 0 clean, 1 findings, 2 usage error.
 
@@ -29,6 +29,13 @@ FOCUSED = re.compile(r"\.only\(|(?<!def )(?<![A-Za-z0-9_.])(fit|fdescribe)\(")
 SUPPRESS = re.compile(r"# noqa|# type: ignore|# pylint: disable|# pragma: no cover|# fmt: off|# ruff: noqa"
                       r"|eslint-disable|@ts-ignore|@ts-expect-error|// nolint|#\[allow\(|--no-verify")
 EMPTY_CATCH = re.compile(r"except[^:]*:[ \t]*pass[ \t]*$|catch[ \t]*(\([^)]*\))?[ \t]*\{[ \t]*\}")
+# an assertion that cannot fail, added to a test file: assert True, assertEqual(x, x), expect(true), expect(x).toBe(x)
+TRIVIAL = (re.compile(r"(^|[^A-Za-z_.])assert\s+(True|1\s*==\s*1|not\s+False)\s*(#.*)?$"),
+           re.compile(r"assertTrue\(\s*True\s*[,)]"),
+           re.compile(r"assertEqual\(\s*([A-Za-z_][\w.]*|\d+)\s*,\s*\1\s*[,)]"),
+           re.compile(r"(^|[^A-Za-z_.])assert\s+([A-Za-z_][\w.]*)\s*==\s*\2\s*(#.*)?$"),
+           re.compile(r"expect\(\s*true\s*\)\.(toBe\(\s*true\s*\)|toBeTruthy\(\))"),
+           re.compile(r"expect\(\s*([A-Za-z_][\w.]*)\s*\)\.toBe\(\s*\1\s*\)"))
 THRESHOLD = re.compile(r"fail_under|fail-under|coverageThreshold|cov-fail-under")
 DELETED_TEST = re.compile(r"(^|/)(test_[^/]*\.py|[^/]*_test\.[a-z]+|[^/]*\.(test|spec)\.[a-z]+|tests?/|__tests__/)")
 # Makefile is judged by content, not name: a Makefile change only counts when the plan's commands.md has a
@@ -77,7 +84,7 @@ def allow_line(source):
 
 
 def diff_findings(diff, allow):
-    """The pass over added lines: skip, suppress, empty-catch and threshold."""
+    """The pass over added lines: skip, suppress, empty-catch, threshold and trivial-assert."""
     allow = " " + allow + " "
     out = []
     file = ""
@@ -105,6 +112,8 @@ def diff_findings(diff, allow):
                 report("empty-catch", line)
             if THRESHOLD.search(line):
                 report("threshold", line)
+            if DELETED_TEST.search(file) and any(r.search(line) for r in TRIVIAL):
+                report("trivial-assert", line)
     return "".join(out)
 
 

{feature_flow_cli-0.5.0 → feature_flow_cli-0.8.0}/feature_flow/gate.py

@@ -60,9 +60,10 @@ def timeout_minutes():
         raise ValueError("FLOW_GATE_TIMEOUT must be a whole number, not %s" % value)
 
 
-def run(feature, out, err, timeout=None):
+def run(feature, out, err, timeout=None, quick=False):
     """Run the gate for feature. out and err take text. timeout is minutes (a float is fine), 0 for none;
-    None reads FLOW_GATE_TIMEOUT. Returns the exit code."""
+    None reads FLOW_GATE_TIMEOUT. With quick, a usable Quick: value runs in the place of Test.
+    Returns the exit code."""
     if not feature:
         err("usage: python3 scripts/gate.py <feature>\n")
         return 2
@@ -77,8 +78,11 @@ def run(feature, out, err, timeout=None):
         out("gate: no commands.md for " + feature + ", nothing to run\n")
         return 0
     ran = 0
+    quick_cmd = command(path, "Quick") if quick else ""
     for key in KEYS:
         cmd = command(path, key)
+        if key == "Test" and quick_cmd != "" and not quick_cmd.startswith("<"):
+            key, cmd = "Quick", quick_cmd
         if cmd == "" or cmd.startswith("<"):
             continue
         ran += 1

{feature_flow_cli-0.5.0 → feature_flow_cli-0.8.0}/feature_flow/git.py

@@ -39,6 +39,24 @@ def head():
     return _git("rev-parse", "HEAD").stdout.strip()
 
 
+def diff_size(base, head, exclude):
+    """(files, lines, binary) of the diff base..head outside the exclude path: the changed paths, the
+    added plus removed lines of the text files, and whether any file is binary (`-` counts in numstat).
+    Renames are off so a renamed file is one delete plus one add whatever `diff.renames` says."""
+    out = _git("diff", "--numstat", "--no-renames", base, head, "--", ".", ":(exclude)%s" % exclude).stdout
+    files, lines, binary = 0, 0, False
+    for line in out.splitlines():
+        if not line.strip():
+            continue
+        added, removed = line.split("\t", 2)[:2]
+        files += 1
+        if added == "-" or removed == "-":
+            binary = True
+        else:
+            lines += int(added) + int(removed)
+    return files, lines, binary
+
+
 # the installer's record of what it wrote: the paths, and the sha256 of each as it wrote it
 INSTALLED = Path(".feature-flow") / "installed.txt"
 HASHES = Path(".feature-flow") / "installed.sha256"