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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: feature-flow-cli
-Version: 0.5.0
+Version: 0.7.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
@@ -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
 
@@ -266,13 +272,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
 

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

@@ -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
 
@@ -247,13 +253,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
 

{feature_flow_cli-0.5.0 → feature_flow_cli-0.7.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.7.0}/feature_flow/__init__.py

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

{feature_flow_cli-0.5.0 → feature_flow_cli-0.7.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.7.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.7.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)

{feature_flow_cli-0.5.0 → feature_flow_cli-0.7.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.7.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"

{feature_flow_cli-0.5.0 → feature_flow_cli-0.7.0}/feature_flow/prompts.py

@@ -8,8 +8,10 @@ import shlex
 from pathlib import Path
 
 ROLES = {"build": "ticket-builder.md", "review": "ticket-reviewer.md", "review-quality": "ticket-reviewer.md",
+         "review-single": "ticket-reviewer.md",
          "plan": "feature-planner.md", "plan-review": "plan-reviewer.md"}
-GUIDES = {"build": "build.md", "review": "review.md", "review-quality": "review-quality.md", "plan": "plan.md", "plan-review": "plan-review.md"}
+GUIDES = {"build": "build.md", "review": "review.md", "review-quality": "review-quality.md",
+          "review-single": "review-single.md", "plan": "plan.md", "plan-review": "plan-review.md"}
 
 
 def find_file(scripts, folder, name):
@@ -83,7 +85,7 @@ def build(phase, scripts, feature, ticket, num, sha, notes=(), retry=False):
         task = ("Your task: review ticket %s of the feature `%s` (`%s %s %s`) (%s pass). The ticket is `%s`, and the "
                 "work started at commit `%s`.\n%s\nDo not edit any file or create a commit. Your final reply must end "
                 "with exactly `REVIEW: PASS` or `REVIEW: FAIL`."
-                % (num, feature, feature, num, sha, "quality" if phase == "review-quality" else "spec", ticket, sha,
+                % (num, feature, feature, num, sha, {"review-quality": "quality", "review-single": "single"}.get(phase, "spec"), ticket, sha,
                    fresh))
         for note in notes:
             task += "\nThe conductor notes: %s" % note

{feature_flow_cli-0.5.0 → feature_flow_cli-0.7.0}/feature_flow/proof.py

@@ -152,6 +152,16 @@ def wants_test_first(text):
     return False
 
 
+def review_mode(text):
+    """`full` when the ticket's header lines (before its first `## ` heading) say `Review: full`, else `auto`."""
+    for line in text.split("\n"):
+        if line.startswith("## "):
+            break
+        if re.match(r"^Review:[ \t]*full\b", line, re.IGNORECASE):
+            return "full"
+    return "auto"
+
+
 def repo_relative(path):
     """path as a posix path relative to the repository root (git's own spelling), when it is inside it."""
     top = git.toplevel()

{feature_flow_cli-0.5.0 → feature_flow_cli-0.7.0}/feature_flow/status.py

@@ -162,6 +162,8 @@ def _check(g, ready, nready, unfinished, out):
             errors.append(lab + ": no ## Done when section")
         if t in g.hastf and g.tf[t] not in ("yes", "no"):
             errors.append(lab + ": Test first must be yes or no")
+        if t in g.hasreview and g.review[t] not in ("full", "auto"):
+            errors.append(lab + ": Review must be full or auto")
         for d in g.blk[t]:
             if d == t:
                 errors.append(lab + ": blocked by itself")

{feature_flow_cli-0.5.0 → feature_flow_cli-0.7.0}/feature_flow/tickets.py

@@ -109,6 +109,7 @@ class Graph:
         self.hasstatus, self.hasdone, self.blk = {}, {}, {}
         self.hasblk, self.hastype, self.hastf, self.hastitle = set(), set(), set(), set()
         self.typ, self.tf = {}, {}
+        self.hasreview, self.review = set(), {}
         self.mentions = {}
         for p in paths:
             self._read(p)
@@ -147,6 +148,9 @@ class Graph:
             if head and line.startswith("Test first:") and cur not in self.hastf:
                 self.hastf.add(cur)
                 self.tf[cur] = _first_word(line.lower(), "test first:")
+            if head and line.startswith("Review:") and cur not in self.hasreview:
+                self.hasreview.add(cur)
+                self.review[cur] = _first_word(line.lower(), "review:")
             if line.startswith("# ") and cur not in self.hastitle:
                 self.hastitle.add(cur)
                 self.title[cur] = line[2:]

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: feature-flow-cli
-Version: 0.5.0
+Version: 0.7.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
@@ -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
 
@@ -266,13 +272,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
 

{feature_flow_cli-0.5.0 → feature_flow_cli-0.7.0}/feature_flow_cli.egg-info/SOURCES.txt

@@ -42,6 +42,7 @@ guides/debug.md
 guides/plan-review.md
 guides/plan.md
 guides/review-quality.md
+guides/review-single.md
 guides/review.md
 guides/show.md
 guides/templates/commands.md

{feature_flow_cli-0.5.0 → feature_flow_cli-0.7.0}/guides/plan-review.md

@@ -9,10 +9,10 @@ You cannot edit or write anything. You may read, search, run the plan check, and
 1. **The brief is covered.** Every part of the brief's What and In scope is planned by some ticket. Name each part that is not.
 2. **Nothing outside the brief.** No ticket builds what the brief puts under Out, or what the brief never asked for and the bar does not need.
 3. **The bar holds.** The spec's bar matches the brief's bar, and the last ticket is the acceptance ticket that runs it.
-4. **The commands are real.** Each command in `commands.md` exists in the project's own config, and Smoke runs and exits 0 now. Run it.
+4. **The commands are real.** Each command in `commands.md` exists in the project's own config, and Smoke runs and exits 0 now. Run it. If `commands.md` has `Quick:`, run it too and report that it exits 0, that it is part of what `Test` runs, and whether it covers the areas the tickets touch.
 5. **Done when is checkable by a stranger.** Each bullet names a command and the result it should print, or an outcome someone who has not read the plan can observe.
 6. **Forks belong to the right person.** A choice that changes what the user gets is a `settle` ticket or an open question, not a decision the planner made quietly.
-7. **The graph is sound.** Run `FLOW_DIR=.feature-flow/state/draft python3 scripts/flow-status.py <feature> --check` and report any problem or warning. Tickets are small (about 5 Done when bullets at most), and `Blocked by` lists only real dependencies.
+7. **The graph is sound.** Run `FLOW_DIR=.feature-flow/state/draft python3 scripts/flow-status.py <feature> --check` and report any problem or warning. Tickets are small (about 5 Done when bullets at most), and `Blocked by` lists only real dependencies. No ticket is so small it should have been folded into another: name it and the ticket it belongs with.
 8. **Outside facts have sources.** Each fact about a library or outside API that a ticket relies on has a source line in `map.md`.
 
 Do not check style, wording or ticket order beyond what the list says.

{feature_flow_cli-0.5.0 → feature_flow_cli-0.7.0}/guides/plan.md

@@ -31,6 +31,8 @@ If your prompt carries review findings from an earlier round, the draft is alrea
 
 **The codebase first.** Find similar features and how they were built, the files that will change, the existing types and APIs the feature touches, and the test conventions. Find the **real** build, test and lint commands: read them from `package.json`, `Makefile`, `Taskfile.yml`, CI config or the project's agent instructions file (CLAUDE.md or AGENTS.md). Do not guess. Pick a **smoke command**: the quickest one that proves the base is healthy (usually build plus the fast tests). The flow runs it before every ticket, and runs Build, Test and Lint after every ticket, so all of them must run without asking anything and exit non zero on failure.
 
+Add a `Quick:` line to `commands.md` only when the project's own config has a clearly faster subset of Test (a unit-only target, a fast marker or folder). It must be a strict subset of `Test`, must exit non zero on failure, and must run without asking anything. Otherwise leave it out: no `Quick:` means the full Test runs every time. The planner never invents one.
+
 **Outside only where the code cannot answer.** For a library or API the feature uses, read the version the lockfile pins, then that version's official documentation. When the brief names a hard problem, look for how others solved it. Never research what the codebase already decides. Write every outside fact you rely on into `map.md` under Decisions so far with its source (`docs: <url>`). If you cannot reach the web, say so in your reply and plan from the codebase.
 
 ## Step 3: Draft the graph
@@ -51,6 +53,7 @@ Then a lazy pass over your draft. For each ticket ask, in order: does the bar st
 ### Ticket rules
 
 1. **One ticket is one change that leaves the build green**, small enough for one session. If Done when needs more than about 5 bullets, or Not in this ticket spans two areas, split it.
+1a. **A change too small to stand alone is folded in.** A rename, a doc line, a config value or a one-line fix that has no Done when of its own goes into the ticket whose work it belongs to, not a ticket of its own. Every ticket costs a builder, the gate and at least one reviewer, whatever its size.
 2. **`Blocked by` only for a real dependency**: the ticket cannot start without another's output. Independent tickets stay unblocked. Do not chain tickets just because of their numbers.
 3. **Types**:
    - `task`: normal work.
@@ -68,6 +71,7 @@ prints OK
 6. **Survive code drift**: no line numbers. Name functions and classes, and give a search hint for insertion points ("after the call to `parseConfig()`").
 7. **Tests ride with the code they cover**: every ticket adds its own. Frontend tickets come after the API shape is stable.
 8. **Set `Test first:`** on every ticket. `yes` for anything that adds or changes logic (the builder must commit a failing test alone first, and the conductor checks it), `no` for config, docs, renames and migrations that a command already proves. Do not set `yes` on a ticket whose test cannot fail before the code.
+8a. **Set `Review: full`** on a ticket that is small but risky (validation at a trust boundary, security, the flow's own code, data that could be lost). Leave it out otherwise: the conductor gives a small ticket whose check block passed one combined review, and a larger one the spec and quality passes. `Type: convert` always gets both.
 9. **The last ticket is the acceptance ticket**: it runs the map's bar end to end and is blocked by every ticket that leaves the bar unproven.
 10. **Number from 01 and never renumber.** Tickets added later get the next number.
 11. **More than about 12 tickets?** Plan in rounds: `plans/<feature>/` first, then `plans/<feature>-round-two/` with its own map that links back.
@@ -77,7 +81,7 @@ prints OK
 
 ## Step 5: Check
 
-Run `FLOW_DIR=.feature-flow/state/draft python3 scripts/flow-status.py <feature> --check`. It fails on a missing blocker, a cycle, a missing Done when, a duplicate number, a bad `Test first` value, or no ready ticket, and it warns about tickets that name another ticket in their text without being ordered against it. If the script is not installed, check those by hand. Fix every problem and every warning before you reply.
+Run `FLOW_DIR=.feature-flow/state/draft python3 scripts/flow-status.py <feature> --check`. It fails on a missing blocker, a cycle, a missing Done when, a duplicate number, a bad `Test first` value, a bad `Review` value, or no ready ticket, and it warns about tickets that name another ticket in their text without being ordered against it. If the script is not installed, check those by hand. Fix every problem and every warning before you reply.
 
 ## Step 6: Reply
 

feature_flow_cli-0.7.0/guides/review-single.md

@@ -0,0 +1,87 @@
+# Review one ticket: single pass
+
+You are the **reviewer**, not the author. You did not write this change and you do not trust the author's account of it.
+
+You are given: the feature, the ticket number (two digits), and optionally the commit the work started from. If no base commit is given, review `HEAD~1..HEAD`.
+
+**You must be a fresh session.** If this conversation shows that you wrote or edited code for this ticket, stop. Do not review it here. Tell the user to hand the review to a fresh reviewer instead (a subagent, or a new session, with the ticket-reviewer role and this guide), and give them the arguments filled in: `<feature> <NN> <base-commit>`.
+
+## What you may read
+
+The author writes the `## Answer` into the ticket itself, so the ticket as it stands now carries their account of the change, and so does the ticket's own hunk in the diff. Both routes leak it into your context before you notice. Avoid both:
+
+**The ticket, as it was before the work.** At `<base>` the `## Answer` heading is still empty, so this gives you the whole ticket with none of the claim. Resolve the exact filename first, then ask for that one blob:
+
+```
+TICKET=$(git ls-files 'plans/<feature>/tasks/NN-*.md')   # exactly one path, or fix the pattern
+git show "<base>:$TICKET"
+```
+
+Never put a `*` inside the `<rev>:<path>` argument. `git show '<base>:plans/<feature>/tasks/NN-*.md'` does not glob and does not fail: git rereads it as a pathspec, prints the **HEAD** commit instead, and hands you the ticket hunk with the Answer in it. Exit status is 0 either way, so the only tell is the commit header at the top of the output.
+
+Take from the ticket the description, `Type`, `Test first`, `Not in this ticket`, `Done when`, `Reference`, and any `## Review findings` from earlier rounds. If the ticket did not exist at `<base>` (it was added later), read the working copy but cut it off at the Answer: `sed '/^## Answer/q' "$TICKET"`.
+
+**The range: stop at the ticket's own last commit, not at `HEAD`.** `HEAD` keeps moving. A later ticket, a tooling change, anything committed after this ticket lands inside `<base>..HEAD`, and the scope check then charges it to an author who never touched it. Find where this ticket's work actually ends:
+
+```
+END=$(git log --format=%H "<base>..HEAD" -- "$TICKET" | head -1)   # newest commit touching this ticket
+[ -n "$END" ] || END=HEAD                                          # none found: fall back, and say so
+```
+
+Every commit for a ticket touches its ticket file, because the author commits the code, the ticket and the map together. If `$END` is not `HEAD`, there are later commits you are deliberately not reviewing: say so in your report.
+
+**The diff, with the ticket folder held back:**
+
+```
+git diff --stat "<base>..$END"                                   # every changed file, for the scope check
+git diff "<base>..$END" -- . ':(exclude)plans/<feature>/tasks/'  # the content you review
+```
+
+Read the files that diff touches. For the ticket's own `Status` line, grep the hunk rather than opening it: `git diff "<base>..$END" -- "$TICKET" | grep '^[+-]Status:'`.
+
+(Substitute the repo's own ticket folder if it keeps them elsewhere.)
+
+**Do not read `## Answer`.** It is the author's claim. Your job is to check the work without it. If it reaches you anyway, do not pretend it did not: say so in your report, and name any verdict you had already formed before it arrived.
+
+## What you must not do
+
+Edit, write, stage, commit, stash, check out or reset anything. You may run read-only commands and the commands in `Done when`. If a command leaves files behind, say so in your report and leave them.
+
+## Verdict: does it meet the ticket, and is it good?
+
+This is a small ticket, so one pass covers both the spec and the quality. Do these four in order.
+
+1. **Scope**: over `<base>..$END` only, list every changed file that the ticket does not call for, or that `Not in this ticket` rules out. Unrelated refactors, renames and reformatting count. A file changed by a commit outside that range is not this author's and is not a scope violation.
+
+2. **Done when**: for every bullet, write `MET` or `NOT MET` with what the command printed. If the conductor's notes say the ticket's `check` block passed, write `MET (conductor)` for each bullet that block covers and do not run it again. Run the prose-only bullets yourself, now. A bullet you could not run is `NOT MET`.
+
+3. **Test first**: if the ticket says `Test first: yes`, check that the diff adds or changes a test, and say whether that test would fail without the production change.
+
+4. **Quality**: look for, in this order:
+
+- bugs and missing handling at boundaries (input, files, network, empty and error cases)
+- checks made weaker instead of being met: skipped or deleted tests, silenced linters, empty catches, lowered thresholds, tests that cannot fail
+- code that need not exist: something the standard library, the platform or the codebase already provides; a feature nobody asked for; a longer way of doing a shorter thing
+- anything a later ticket will trip over
+
+Rate each finding blocker, major or minor, name the file, and say what to change.
+
+## Output
+
+Use exactly this shape. Keep it short; no praise.
+
+    SPEC
+    - <Done when bullet>: MET | MET (conductor) | NOT MET - <command and what it printed>
+    - scope: OK | <files outside the ticket>
+    - test first: n/a | OK | MISSING
+
+    QUALITY
+    1. blocker|major|minor <file>: <finding> - <what to change>
+
+    REVIEW: PASS
+
+The indentation above only marks where the template starts and stops. Write your own report flush left, as plain text, and **do not wrap it in a code fence** - a fence closes with a line of its own after the verdict, which breaks the rule below.
+
+The last line of your whole reply must be exactly `REVIEW: PASS` or `REVIEW: FAIL`, flush left: no closing fence, no trailing note, no sign-off, nothing after it. The flow (`scripts/flow.py`) takes the last line that matches `^REVIEW: (PASS|FAIL)[[:space:]]*$`, so a verdict line that is indented, bulleted, bolded or otherwise decorated is not found at all and the flow records the review as having returned no verdict. Anything you still want to say goes above the verdict line.
+
+`PASS` only if every Done when bullet is `MET` or `MET (conductor)`, scope is `OK`, test first is not `MISSING`, and there is no `blocker` or `major` finding. `minor` findings are listed but do not fail the review. When in doubt, fail it and say why.

{feature_flow_cli-0.5.0 → feature_flow_cli-0.7.0}/guides/templates/commands.md

@@ -5,11 +5,14 @@ Taskfile, CI). Approved by a human when the plan is approved. Workers read this
 must not change it.
 
 The flow runs Smoke before every ticket and Build, Test and Lint after every
-ticket, so each must run without asking anything and exit non zero on failure. Delete a line
+ticket, so each must run without asking anything and exit non zero on failure. `Quick:` is
+optional: when set, it runs in place of Test after the tickets in the middle of the plan, and
+Test runs after the last ticket and before each handoff. Delete a line
 you do not have; a line left as a placeholder is skipped.
 
 Build: `<command>`
 Test: `<command>`
+Quick: `<optional: the fast subset of Test, run after the tickets in the middle of the plan; Test runs after the last ticket and before each handoff>`
 Lint: `<command>`
 Smoke: `<the quickest command that proves the base is healthy, run before every ticket>`
 Run: `<command, if the feature has something to start>`

{feature_flow_cli-0.5.0 → feature_flow_cli-0.7.0}/guides/templates/ticket.md

@@ -4,6 +4,7 @@ Type: task
 Status: open
 Blocked by: —
 Test first: yes
+Review: auto
 
 <What to do and why, in prose. Name files, functions and types. Never use line numbers.
 For Type: settle, say what has to be decided and who decides. For Type: convert, say what

{feature_flow_cli-0.5.0 → feature_flow_cli-0.7.0}/scripts/flow-trust.py

@@ -42,7 +42,7 @@ DURING = "STOP flow code changed during %s: %s"
 STATE_CHANGED = "STOP the run state was changed by something other than the conductor during %s"
 NO_REPORT = "STOP the conductor did not report its state (it crashed?) during %s"
 SCRIPTS = ("flow.py", "flow-status.py", "gate.py", "floor-guard.py", "flow-view.py", "flow-trust.py")
-GUIDES = ("build.md", "review.md", "review-quality.md", "plan.md", "plan-review.md", "debug.md")  # prompts.GUIDES + debug.md
+GUIDES = ("build.md", "review.md", "review-quality.md", "review-single.md", "plan.md", "plan-review.md", "debug.md")  # prompts.GUIDES + debug.md
 SKILL_GUIDES = ("brief.md", "show.md")  # read by the skills themselves
 TEMPLATES = ("commands.md", "learnings.md", "map.md", "spec.md", "ticket.md", "ui-mockup.md")  # guides/templates/
 ROLES = ("ticket-builder.md", "ticket-reviewer.md", "feature-planner.md", "plan-reviewer.md")  # prompts.ROLES

{feature_flow_cli-0.5.0 → feature_flow_cli-0.7.0}/skills/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 subagent'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,7 +57,7 @@ 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 fresh reviewer subagent for each review pass. 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