feature-flow-cli 0.1.6__tar.gz → 0.3.0__tar.gz

{feature_flow_cli-0.1.6/feature_flow_cli.egg-info → feature_flow_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: feature-flow-cli
-Version: 0.1.6
+Version: 0.3.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
@@ -62,14 +62,14 @@ Then, in your repo, in the agent:
 | | Claude Code | Codex |
 |---|---|---|
 | Plan a feature (no plan yet) | `/feature-flow csv-export` | `$feature-flow csv-export` |
-| Plan what you just talked through | `/feature-flow` | `$feature-flow` |
+| Plan and build what you just talked through | `/feature-flow` | `$feature-flow` |
 | Build its tickets (a plan exists) | `/feature-flow csv-export` | `$feature-flow csv-export` |
 | The same, asking nothing | `/feature-flow csv-export auto` | `$feature-flow csv-export auto` |
 | Watch the graph, animated | `/feature-flow csv-export show` | `$feature-flow csv-export show` |
 
-The same command plans when `plans/csv-export/` does not exist yet and builds when it does. Commit the plan before you build it.
+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>/`.
+**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.
 
 Try the graph first, with no setup and no agent: `bash examples/demo.sh --open`.
 
@@ -104,16 +104,26 @@ The Claude Code skill is `skills/feature-flow/`. The Codex skill is written by h
    plan touched beyond own Status + Answer + appended lines?        │
                                               │ clean               │
                                               ▼                     │
- fresh reviewer subagent: sees only the ticket + diff,              │
- re-runs every Done when                                      FAIL ─┤
+ Done when checks (script): runs every ```check block          fail ─┤
+ test-first check (script): Test first: yes needs a test-only        │
+   commit that failed Test before the code                     fail ─┤
+                                              │ pass                │
+                                              ▼                     │
+ spec review: fresh reviewer subagent, sees only the ticket         │
+ + diff, re-runs every Done when                              FAIL ─┤
+                                              │ PASS                │
+                                              ▼                     │
+ quality review: a second fresh reviewer subagent             FAIL ─┤
                                               │ PASS                ▼
                                               ▼        findings written into the ticket,
-                                     next ticket       reopened, built again (3 rounds max)
+                                     next ticket       reopened, built again (3 rounds max);
+                                                       the builder's prompt then carries
+                                                       a root-cause debugging guide
 ```
 
 `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 checks that the reviewer changed no tracked file and made no commit. The review verdict is different: the reviewer's reply 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.
+**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.
 
 ## The skill and the roles
 
@@ -153,7 +163,7 @@ plans/
 
 One markdown file per ticket in `plans/<feature>/tasks/NN-slug.md`:
 
-```
+````
 # Add the retry policy to the job runner
 
 Type: task                 task | settle | convert
@@ -166,16 +176,21 @@ Floor: allow config        optional, only when a human decides the guard may let
 
 ## Not in this ticket
 ## Done when                 commands and the results they print
+```check
+$ python3 -m unittest discover -s tests/py
+exit 0
+prints OK
+```
 ## Reference
 ## Answer                    Built, Proof, Decisions, Shortcuts taken, Review fixes, For later tickets
-```
+````
 
 - **Order comes from `Blocked by`**, not from numbers. A ticket is *ready* when it is open and every ticket it is blocked by is resolved. Lowest number wins.
 - **Status lives only in the ticket files.** `map.md` never repeats it.
 - **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`. 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`, `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.
 
@@ -240,13 +255,14 @@ The commands in `commands.md` run through `bash -c` on Linux and macOS and throu
 | `FLOW_TAKEOVER` | unset | `1` lets `start` take a feature over from a session that is gone |
 | `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 |
+| `FLOW_GATE` | `on` | `off` skips Build, Test and Lint after each ticket, and also the Done when and test-first checks |
+| `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 steps that grows with the ticket count, 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) that grows with the ticket count, recomputed at every pick, so a loop of failures cannot go on forever.
 
 ## What is tested
 
@@ -273,7 +289,7 @@ bash tests/run.sh
 python3 -m unittest discover -s tests/py
 ```
 
-Offline and free: no model is called. The suite covers the conductor's every answer and how a run stops, sessions, handoff and takeover, a `.git` the agent cannot write, the gate, the floor guard, plan protection, the prompts and guides, both skills, the installer for both agents, the graph page and its data, and the acceptance harness. The page's layout and replay logic are also tested under Node (`tests/viewer-logic.test.js`, skipped when Node is absent). `.github/workflows/tests.yml` runs it on every push to `main` and every pull request, on Ubuntu (once with `mawk`, once with `gawk`) and on macOS. A fourth job runs the Python unit tests on Windows, including a fixture drive that takes a two-ticket plan through `python scripts/flow.py f start` and `next` to `BUILD` and then `REVIEW`. `tests/run.sh` itself is a bash harness and does not run on Windows. Windows is tested this way only: no real agent run has been done there.
+Offline and free: no model is called. The suite covers the conductor's every answer and how a run stops, sessions, handoff and takeover, a `.git` the agent cannot write, the gate, the floor guard, plan protection, the prompts and guides, both skills, the installer for both agents, the graph page and its data, the Done when checks, the test-first check, the two reviews and the debugging guide on a send-back, and the acceptance harness. `tests/run.sh` also drives a prepared demo with no model through both checks and both reviews. The page's layout and replay logic are also tested under Node (`tests/viewer-logic.test.js`, skipped when Node is absent). `.github/workflows/tests.yml` runs it on every push to `main` and every pull request, on Ubuntu and on macOS. A fourth job runs the Python unit tests on Windows, including a fixture drive that takes a two-ticket plan through `python scripts/flow.py f start` and `next` to `BUILD` and then `REVIEW`. `tests/run.sh` itself is a bash harness and does not run on Windows. Windows is tested this way only: no real agent run has been done there.
 
 A `package` job builds the wheel and the sdist and runs `tests/package_smoke.py` on Ubuntu (Python 3.9 and the latest), macOS and Windows: it installs the wheel in a fresh virtual environment, runs `feature-flow install`, and checks that the repo gets the same files as from `install.py` in a clone. Run it locally with `python3 -m pip install build && python3 tests/package_smoke.py`.
 
@@ -304,7 +320,7 @@ git tag v0.1.1 && git push origin v0.1.1
 
 ## Caution
 
-The builder subagent has edit and shell access and commits after each ticket. Each ticket costs at least two subagents. Build on a branch you can throw away. Ignore build output in `.gitignore`, because the conductor stops if the tree is dirty after a ticket. The gate runs your Build, Test and Lint commands with no time limit. The floor guard is pattern matching: it can miss things and it can raise false alarms, and `Floor: allow` is the release valve. The run stops on its own when a ticket stays unresolved, when the smoke test or the gate keeps failing, when a ticket keeps failing review, or when it reaches its step limit.
+The builder subagent has edit and shell access and commits after each ticket. Each ticket costs at least two subagents. Build on a branch you can throw away. Ignore build output in `.gitignore`, because the conductor stops if the tree is dirty after a ticket. The gate and the smoke test stop after 30 minutes (`FLOW_GATE_TIMEOUT`). The conductor also checks that the code it runs (the `feature_flow` package, `scripts/*.py` and the build and review role and guide files) did not change during a build or review; if it did, the run stops with `STOP flow code changed while building <ticket>: <files>`, and `Floor: allow flow-edit` on the ticket allows it for the build. That check is a tripwire, not a sandbox. The floor guard is pattern matching: it can miss things and it can raise false alarms, and `Floor: allow` is the release valve. The run stops on its own when a ticket stays unresolved, when the smoke test or the gate keeps failing, when a ticket keeps failing review, or when it reaches its phase limit.
 
 ## License
 

{feature_flow_cli-0.1.6 → feature_flow_cli-0.3.0}/README.md

@@ -43,14 +43,14 @@ Then, in your repo, in the agent:
 | | Claude Code | Codex |
 |---|---|---|
 | Plan a feature (no plan yet) | `/feature-flow csv-export` | `$feature-flow csv-export` |
-| Plan what you just talked through | `/feature-flow` | `$feature-flow` |
+| Plan and build what you just talked through | `/feature-flow` | `$feature-flow` |
 | Build its tickets (a plan exists) | `/feature-flow csv-export` | `$feature-flow csv-export` |
 | The same, asking nothing | `/feature-flow csv-export auto` | `$feature-flow csv-export auto` |
 | Watch the graph, animated | `/feature-flow csv-export show` | `$feature-flow csv-export show` |
 
-The same command plans when `plans/csv-export/` does not exist yet and builds when it does. Commit the plan before you build it.
+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>/`.
+**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.
 
 Try the graph first, with no setup and no agent: `bash examples/demo.sh --open`.
 
@@ -85,16 +85,26 @@ The Claude Code skill is `skills/feature-flow/`. The Codex skill is written by h
    plan touched beyond own Status + Answer + appended lines?        │
                                               │ clean               │
                                               ▼                     │
- fresh reviewer subagent: sees only the ticket + diff,              │
- re-runs every Done when                                      FAIL ─┤
+ Done when checks (script): runs every ```check block          fail ─┤
+ test-first check (script): Test first: yes needs a test-only        │
+   commit that failed Test before the code                     fail ─┤
+                                              │ pass                │
+                                              ▼                     │
+ spec review: fresh reviewer subagent, sees only the ticket         │
+ + diff, re-runs every Done when                              FAIL ─┤
+                                              │ PASS                │
+                                              ▼                     │
+ quality review: a second fresh reviewer subagent             FAIL ─┤
                                               │ PASS                ▼
                                               ▼        findings written into the ticket,
-                                     next ticket       reopened, built again (3 rounds max)
+                                     next ticket       reopened, built again (3 rounds max);
+                                                       the builder's prompt then carries
+                                                       a root-cause debugging guide
 ```
 
 `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 checks that the reviewer changed no tracked file and made no commit. The review verdict is different: the reviewer's reply 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.
+**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.
 
 ## The skill and the roles
 
@@ -134,7 +144,7 @@ plans/
 
 One markdown file per ticket in `plans/<feature>/tasks/NN-slug.md`:
 
-```
+````
 # Add the retry policy to the job runner
 
 Type: task                 task | settle | convert
@@ -147,16 +157,21 @@ Floor: allow config        optional, only when a human decides the guard may let
 
 ## Not in this ticket
 ## Done when                 commands and the results they print
+```check
+$ python3 -m unittest discover -s tests/py
+exit 0
+prints OK
+```
 ## Reference
 ## Answer                    Built, Proof, Decisions, Shortcuts taken, Review fixes, For later tickets
-```
+````
 
 - **Order comes from `Blocked by`**, not from numbers. A ticket is *ready* when it is open and every ticket it is blocked by is resolved. Lowest number wins.
 - **Status lives only in the ticket files.** `map.md` never repeats it.
 - **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`. 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`, `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.
 
@@ -221,13 +236,14 @@ The commands in `commands.md` run through `bash -c` on Linux and macOS and throu
 | `FLOW_TAKEOVER` | unset | `1` lets `start` take a feature over from a session that is gone |
 | `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 |
+| `FLOW_GATE` | `on` | `off` skips Build, Test and Lint after each ticket, and also the Done when and test-first checks |
+| `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 steps that grows with the ticket count, 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) that grows with the ticket count, recomputed at every pick, so a loop of failures cannot go on forever.
 
 ## What is tested
 
@@ -254,7 +270,7 @@ bash tests/run.sh
 python3 -m unittest discover -s tests/py
 ```
 
-Offline and free: no model is called. The suite covers the conductor's every answer and how a run stops, sessions, handoff and takeover, a `.git` the agent cannot write, the gate, the floor guard, plan protection, the prompts and guides, both skills, the installer for both agents, the graph page and its data, and the acceptance harness. The page's layout and replay logic are also tested under Node (`tests/viewer-logic.test.js`, skipped when Node is absent). `.github/workflows/tests.yml` runs it on every push to `main` and every pull request, on Ubuntu (once with `mawk`, once with `gawk`) and on macOS. A fourth job runs the Python unit tests on Windows, including a fixture drive that takes a two-ticket plan through `python scripts/flow.py f start` and `next` to `BUILD` and then `REVIEW`. `tests/run.sh` itself is a bash harness and does not run on Windows. Windows is tested this way only: no real agent run has been done there.
+Offline and free: no model is called. The suite covers the conductor's every answer and how a run stops, sessions, handoff and takeover, a `.git` the agent cannot write, the gate, the floor guard, plan protection, the prompts and guides, both skills, the installer for both agents, the graph page and its data, the Done when checks, the test-first check, the two reviews and the debugging guide on a send-back, and the acceptance harness. `tests/run.sh` also drives a prepared demo with no model through both checks and both reviews. The page's layout and replay logic are also tested under Node (`tests/viewer-logic.test.js`, skipped when Node is absent). `.github/workflows/tests.yml` runs it on every push to `main` and every pull request, on Ubuntu and on macOS. A fourth job runs the Python unit tests on Windows, including a fixture drive that takes a two-ticket plan through `python scripts/flow.py f start` and `next` to `BUILD` and then `REVIEW`. `tests/run.sh` itself is a bash harness and does not run on Windows. Windows is tested this way only: no real agent run has been done there.
 
 A `package` job builds the wheel and the sdist and runs `tests/package_smoke.py` on Ubuntu (Python 3.9 and the latest), macOS and Windows: it installs the wheel in a fresh virtual environment, runs `feature-flow install`, and checks that the repo gets the same files as from `install.py` in a clone. Run it locally with `python3 -m pip install build && python3 tests/package_smoke.py`.
 
@@ -285,7 +301,7 @@ git tag v0.1.1 && git push origin v0.1.1
 
 ## Caution
 
-The builder subagent has edit and shell access and commits after each ticket. Each ticket costs at least two subagents. Build on a branch you can throw away. Ignore build output in `.gitignore`, because the conductor stops if the tree is dirty after a ticket. The gate runs your Build, Test and Lint commands with no time limit. The floor guard is pattern matching: it can miss things and it can raise false alarms, and `Floor: allow` is the release valve. The run stops on its own when a ticket stays unresolved, when the smoke test or the gate keeps failing, when a ticket keeps failing review, or when it reaches its step limit.
+The builder subagent has edit and shell access and commits after each ticket. Each ticket costs at least two subagents. Build on a branch you can throw away. Ignore build output in `.gitignore`, because the conductor stops if the tree is dirty after a ticket. The gate and the smoke test stop after 30 minutes (`FLOW_GATE_TIMEOUT`). The conductor also checks that the code it runs (the `feature_flow` package, `scripts/*.py` and the build and review role and guide files) did not change during a build or review; if it did, the run stops with `STOP flow code changed while building <ticket>: <files>`, and `Floor: allow flow-edit` on the ticket allows it for the build. That check is a tripwire, not a sandbox. The floor guard is pattern matching: it can miss things and it can raise false alarms, and `Floor: allow` is the release valve. The run stops on its own when a ticket stays unresolved, when the smoke test or the gate keeps failing, when a ticket keeps failing review, or when it reaches its phase limit.
 
 ## License
 

{feature_flow_cli-0.1.6 → feature_flow_cli-0.3.0}/adapters/codex/feature-flow/SKILL.md

@@ -23,7 +23,7 @@ When `plans/<feature>/` does not exist, or you are planning from the conversatio
 - `plan-review-prompt`: start a new reviewer the same way, with `task_name="plan_reviewer"` and `fork_turns="none"`, never with the planner's reply. Get its final reply with `wait_agent` and save it with the shell into `.feature-flow/state/plan-review-<feature>.txt`.
 - `plan-accept`: writes `plans/<feature>/` from the draft, only after the second yes.
 
-Then run `python3 scripts/flow-status.py <feature> --check`, list the files `plan-accept` wrote, and suggest the commit command (`git add plans/<feature> && git commit -m "docs(<feature>): plan"`). Say to commit the plan and run `$feature-flow <feature>` again. While the plan is uncommitted, do not say the feature is ready to build.
+Then run `python3 scripts/flow-status.py <feature> --check` and list the files `plan-accept` wrote. The second yes also approves committing the plan, so commit the folder `plan-accept` printed (`OK <folder>`, `plans/<feature>` unless `FLOW_DIR` is set) and nothing else: `git add -- <folder> && git commit -m "docs(<feature>): plan" -- <folder>`. If the commit fails, report why and stop. Then go straight on to building it below, unless the user asked to stop after planning.
 
 To add tickets to a plan that exists, edit it by hand following the ticket rules in `.feature-flow/guides/plan.md`.
 
@@ -41,14 +41,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.
+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.
 
 ## The loop
 
 Run `next`, act on its one line, and repeat:
 
-- `BUILD <ticket> <NN> <sha>`: run `prompt`. Start the builder with `spawn_agent(task_name="ticket_builder", fork_turns="none", message=...)`. The message is "Work only in <repo>." followed by the whole `prompt` output, which already starts with the builder role. Get its final reply with `wait_agent`, then run `next`.
-- `REVIEW <ticket> <NN> <sha>`: run `prompt`. Start a new reviewer the same way, with `task_name="ticket_reviewer"` and `fork_turns="none"` so it never sees the builder's context. 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`.
+- `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`.
+- `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`.
 - `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 new session resumes where this one stopped.
@@ -62,7 +62,7 @@ A conductor command looks like this:
 These apply from `start` on, once a plan exists.
 
 - Never run the gate, the floor guard or a review yourself. The conductor runs the checks, and the reviewer subagent reviews.
-- Never edit a ticket, the plan or the code, and never commit. The builder does that.
+- Never edit a ticket, the plan or the code, and never commit, apart from the approved plan above. The builder does that.
 - Never skip a step, reorder steps, or decide the next step yourself. Only `next` decides.
 - Never read a ticket's `## Answer` into the reviewer's prompt. `prompt` already holds everything it needs.
 - Tell the user one short line per phase (`01 built`, `01 review: PASS`), not the subagents' reports.

{feature_flow_cli-0.1.6 → feature_flow_cli-0.3.0}/feature_flow/__init__.py

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

{feature_flow_cli-0.1.6 → feature_flow_cli-0.3.0}/feature_flow/checks.py

@@ -1,13 +1,14 @@
-"""The checks the conductor runs: the bash scripts it still calls, and the ported ones in process.
+"""The checks the conductor runs, in process.
 
 Each call lives in one function so plans/interactive-flow-python can swap it for an
 in-process call without touching the conductor.
 """
 
 import os
-import subprocess
+import tempfile
 from pathlib import Path
 
+from feature_flow import proc
 from feature_flow import status
 from feature_flow import gate as gate_module
 from feature_flow import floorguard
@@ -36,12 +37,6 @@ class _Collect:
         return "".join(self.parts)
 
 
-def _bash(script, *args):
-    result = subprocess.run(["bash", str(script)] + [str(a) for a in args],
-                            stdout=subprocess.PIPE, stderr=subprocess.STDOUT, universal_newlines=True)
-    return Result(result.returncode, result.stdout)
-
-
 def flow_status(scripts, feature, mode, root=None):
     """The ticket graph reader with --next, --counts or --check, in process. stderr is folded into the output.
     root, when given, stands in for FLOW_DIR for this one call (the planner's draft folder)."""
@@ -60,11 +55,13 @@ def flow_status(scripts, feature, mode, root=None):
     return Result(code, out.text())
 
 
-def gate(scripts, feature):
-    """The gate, run in process. stderr is folded into the output as the subprocess call did."""
+def gate(scripts, feature, timeout=None):
+    """The gate, run in process. stderr is folded into the output as the subprocess call did.
+    timeout is minutes, None for FLOW_GATE_TIMEOUT."""
     chunks = []
-    code = gate_module.run(str(feature), chunks.append, chunks.append)
-    out = b"".join(chunks).decode("utf-8", "replace").replace("\r\n", "\n").replace("\r", "\n")
+    code = gate_module.run(str(feature), chunks.append, chunks.append, timeout)
+    out = "".join(chunks).encode("utf-8", "surrogateescape").decode("utf-8", "replace")
+    out = out.replace("\r\n", "\n").replace("\r", "\n")
     return Result(code, out)
 
 
@@ -76,8 +73,13 @@ def floor_guard(scripts, feature, num, base):
     return Result(code, out)
 
 
-def smoke(command):
+def smoke(command, timeout=None):
+    """The smoke command. timeout is minutes, 0 or None for none. Result.timed_out is set when it ran out."""
     args, use_shell = gate_module.shell(command)
-    result = subprocess.run(args, shell=use_shell, stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
-                            universal_newlines=True)
-    return Result(result.returncode, result.stdout)
+    with tempfile.TemporaryFile() as log:
+        code, timed_out = proc.run(args, use_shell, log, timeout)
+        log.seek(0)
+        out = log.read().decode("utf-8", "replace").replace("\r\n", "\n")
+    result = Result(1 if timed_out else code, out)
+    result.timed_out = timed_out
+    return result

feature_flow_cli-0.3.0/feature_flow/codehash.py

@@ -0,0 +1,65 @@
+"""A fingerprint of the code and prompt files a conductor run uses, so a change during a build shows."""
+
+import hashlib
+import json
+import os
+from pathlib import Path
+
+from feature_flow import git, prompts
+
+
+def _files(scripts):
+    package = Path(__file__).resolve().parent
+    found = [p for p in package.rglob("*.py") if "__pycache__" not in p.parts]
+    found += Path(scripts).resolve().glob("*.py")
+    for phase in ("build", "review", "review-quality"):
+        for folder, names in (("agents", prompts.ROLES), ("guides", prompts.GUIDES)):
+            try:
+                found.append(prompts.find_file(scripts, folder, names[phase]).resolve())
+            except FileNotFoundError:
+                pass
+    try:
+        found.append(prompts.find_file(scripts, "guides", "debug.md").resolve())
+    except FileNotFoundError:
+        pass
+    return sorted(set(found))
+
+
+def _name(path, top):
+    try:
+        return path.relative_to(top).as_posix()
+    except ValueError:
+        return path.as_posix()
+
+
+def flow_code(scripts):
+    """(the sha256 over every file's path and bytes, {path relative to the repo: sha256 of the file})."""
+    top = git.toplevel()
+    top = top.resolve() if top is not None else Path(os.getcwd()).resolve()
+    each = {}
+    for path in _files(scripts):
+        try:
+            each[_name(path, top)] = hashlib.sha256(path.read_bytes()).hexdigest()
+        except OSError:
+            each[_name(path, top)] = ""
+    whole = hashlib.sha256()
+    for name in sorted(each):
+        whole.update(name.encode("utf-8") + b"\0" + each[name].encode("ascii") + b"\0")
+    return whole.hexdigest(), each
+
+
+def changed(before, now):
+    """The names that differ between two {name: sha256} maps, sorted."""
+    return sorted(name for name in set(before) | set(now) if before.get(name) != now.get(name))
+
+
+def dump(each):
+    return json.dumps(each, sort_keys=True)
+
+
+def load(text):
+    try:
+        value = json.loads(text)
+    except ValueError:
+        return {}
+    return value if isinstance(value, dict) else {}