feature-flow-cli 0.1.5__tar.gz → 0.2.0__tar.gz

{feature_flow_cli-0.1.5/feature_flow_cli.egg-info → feature_flow_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: feature-flow-cli
-Version: 0.1.5
+Version: 0.2.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
@@ -55,19 +55,21 @@ The package puts a `feature-flow` command on your PATH with `install`, `status <
 
 The installer lists what it wrote in `.feature-flow/installed.txt`, with each file's hash in `.feature-flow/installed.sha256`. Commit those files (`git add --pathspec-from-file=.feature-flow/installed.txt`); until you do, the flow does not count them as uncommitted changes. Installing a newer version over an older one updates every file nobody edited since it was installed, and keeps (and names) the ones you changed; `--force` replaces those too.
 
+To keep the install out of git, so only your plans and tickets get committed, install with `--private`. It lists the installed files in `.git/info/exclude`, which git reads like `.gitignore` but never commits, and later installs keep that list up to date. If you already committed the install, it prints the `git rm --cached` command that untracks it and keeps the files. Every clone then needs its own install.
+
 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`.
 
@@ -173,7 +175,7 @@ Floor: allow config        optional, only when a human decides the guard may let
 - **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.
 
@@ -239,12 +241,13 @@ 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 |
+| `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) that grows with the ticket count, recomputed at every pick, so a loop of failures cannot go on forever.
 
 ## What is tested
 
@@ -271,7 +274,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, 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 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`.
 
@@ -302,7 +305,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.5 → feature_flow_cli-0.2.0}/README.md

@@ -36,19 +36,21 @@ The package puts a `feature-flow` command on your PATH with `install`, `status <
 
 The installer lists what it wrote in `.feature-flow/installed.txt`, with each file's hash in `.feature-flow/installed.sha256`. Commit those files (`git add --pathspec-from-file=.feature-flow/installed.txt`); until you do, the flow does not count them as uncommitted changes. Installing a newer version over an older one updates every file nobody edited since it was installed, and keeps (and names) the ones you changed; `--force` replaces those too.
 
+To keep the install out of git, so only your plans and tickets get committed, install with `--private`. It lists the installed files in `.git/info/exclude`, which git reads like `.gitignore` but never commits, and later installs keep that list up to date. If you already committed the install, it prints the `git rm --cached` command that untracks it and keeps the files. Every clone then needs its own install.
+
 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`.
 
@@ -154,7 +156,7 @@ Floor: allow config        optional, only when a human decides the guard may let
 - **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.
 
@@ -220,12 +222,13 @@ 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 |
+| `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) that grows with the ticket count, recomputed at every pick, so a loop of failures cannot go on forever.
 
 ## What is tested
 
@@ -252,7 +255,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, 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 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`.
 
@@ -283,7 +286,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.5 → feature_flow_cli-0.2.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,7 +41,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 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
 
@@ -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.5 → feature_flow_cli-0.2.0}/feature_flow/__init__.py

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

{feature_flow_cli-0.1.5 → feature_flow_cli-0.2.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.2.0/feature_flow/codehash.py

@@ -0,0 +1,61 @@
+"""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"):
+        for folder, names in (("agents", prompts.ROLES), ("guides", prompts.GUIDES)):
+            try:
+                found.append(prompts.find_file(scripts, folder, names[phase]).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 {}

{feature_flow_cli-0.1.5 → feature_flow_cli-0.2.0}/feature_flow/command.py

@@ -12,7 +12,7 @@ from pathlib import Path
 from feature_flow import __version__, cli, install, status, suggest, view
 
 USAGE = """\
-usage: feature-flow install [target-repo] [--agent claude|codex|all] [--user] [--force] [--dry-run]
+usage: feature-flow install [target-repo] [--agent claude|codex|all] [--user] [--private] [--force] [--dry-run]
        feature-flow status <feature> [--next | --counts | --check | --mermaid [plain] | --json]
        feature-flow view <feature> [--watch] [--no-open] [--out FILE]
        feature-flow reset <feature> [NN]

{feature_flow_cli-0.1.5 → feature_flow_cli-0.2.0}/feature_flow/conductor.py

@@ -10,7 +10,7 @@ import secrets
 import shutil
 from pathlib import Path
 
-from feature_flow import checks, git, prompts, state, suggest, tickets
+from feature_flow import checks, codehash, floorguard, gate, git, prompts, state, suggest, tickets
 
 
 VERDICT = re.compile(r"^REVIEW: (PASS|FAIL)[ \t\r\f\v]*$")
@@ -41,6 +41,7 @@ class Conductor:
         self.commands = self.plan / "commands.md"
         self.max_retries = _env_int("FLOW_MAX_RETRIES", 2)
         self.max_rounds = _env_int("FLOW_MAX_REVIEW_ROUNDS", 3)
+        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.relay = os.environ.get("FLOW_RELAY", "0") == "1"
@@ -101,10 +102,17 @@ class Conductor:
         cmd = self.smoke_command()
         if not cmd:
             return
-        result = checks.smoke(cmd)
+        result = checks.smoke(cmd, self.gate_timeout)
         if not result.ok:
-            raise Stop("smoke test failed before %s: the base is already broken. fix it first. command: %s"
-                       % (self.ticket_name(), cmd))
+            log = self.state_file.with_name("%s.smoke.log" % self.feature)
+            text = result.out
+            if result.timed_out:
+                text += "\nsmoke test timed out after %d minutes\n" % self.gate_timeout
+            log.write_text(gate.tail(text), encoding="utf-8")
+            raise Stop("smoke test %s before %s: the base is already broken. fix it first. command: %s. "
+                       "the last %d lines are in %s"
+                       % ("timed out after %d minutes" % self.gate_timeout if result.timed_out else "failed",
+                          self.ticket_name(), cmd, gate.TAIL, log))
 
     def run_limit(self):
         result = checks.flow_status(self.scripts, self.feature, "--counts")
@@ -118,7 +126,7 @@ class Conductor:
         runs = self.num("runs") + 1
         limit = self.num("limit")
         if runs > limit:
-            raise Stop("run limit of %d sessions reached, stopping" % limit)
+            raise Stop("run limit of %d phases reached, stopping" % limit)
         self.st["runs"] = runs
 
     # ---- phases --------------------------------------------------------
@@ -180,12 +188,41 @@ class Conductor:
         if self.per_session > 0 and self.num("session_done") >= self.per_session:
             return self.handoff()
         path = nxt.out.strip().splitlines()[-1]
+        self.st["limit"] = self.run_limit()
         self.st.update({"ticket": path, "num": tickets.number(path), "base": git.head(), "phase": "",
-                        "attempt": 0, "review_attempt": 0, "round": 0, "review_sha": ""})
+                        "attempt": 0, "review_attempt": 0, "round": 0, "review_sha": "", "guard_warning": ""})
+        self.snapshot_code()
         self.run_smoke()
         return self.hand_out_build()
 
+    def snapshot_code(self):
+        whole, each = codehash.flow_code(self.scripts)
+        self.st["code_sha"] = whole
+        self.st["code_files"] = codehash.dump(each)
+
+    def check_code(self, allowed=False):
+        """Stop when the files the conductor runs from changed since the ticket was picked."""
+        whole, each = codehash.flow_code(self.scripts)
+        if whole == self.get("code_sha"):
+            return
+        if allowed:
+            self.snapshot_code()
+            return
+        names = codehash.changed(codehash.load(self.get("code_files")), each)
+        raise Stop("flow code changed while building %s: %s. if intended, the ticket needs a line: "
+                   "Floor: allow flow-edit" % (self.ticket_name(), ", ".join(names)))
+
+    def flow_edit_allowed(self):
+        try:
+            source = git._git("show", "%s:%s" % (self.get("base"), Path(self.ticket()).as_posix()), check=False)
+        except OSError:
+            return False
+        if source.returncode != 0:
+            return False
+        return "flow-edit" in floorguard.allow_line(source.stdout).split()
+
     def judge_build(self):
+        self.check_code(self.flow_edit_allowed())
         status = tickets.status(self.ticket())
         if status not in tickets.DONE:
             if status in tickets.RESET:
@@ -196,7 +233,7 @@ 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)
+            result = checks.gate(self.scripts, self.feature, self.gate_timeout)
             self.log("GATE-PASS" if result.ok else "GATE-FAIL")
             if not result.ok:
                 return self.send_back("gate", result.out)
@@ -204,6 +241,8 @@ class Conductor:
         self.log("GUARD-PASS" if result.ok else "GUARD-FAIL")
         if not result.ok:
             return self.send_back("floor guard", result.out)
+        warnings = [l for l in result.out.splitlines() if l.startswith("warning:")]
+        self.st["guard_warning"] = warnings[0] if warnings else ""
         return self.hand_out_review()
 
     # ---- commands ------------------------------------------------------
@@ -294,6 +333,7 @@ class Conductor:
         return "OK %s. run %s %s" % (", ".join(done), self.invoke, self.feature)
 
     def judge_review(self):
+        self.check_code()
         if not git.tracked_clean() or git.head() != self.get("review_sha"):
             raise Stop("the reviewer changed tracked files, which a reviewer must never do")
         verdict = self.get("verdict")
@@ -318,7 +358,8 @@ class Conductor:
         if phase not in ("build", "review"):
             raise NoPhase("no BUILD or REVIEW is pending for %s" % self.feature)
         try:
-            return prompts.build(phase, self.scripts, self.feature, self.ticket(), self.get("num"), self.get("base"))
+            return prompts.build(phase, self.scripts, self.feature, self.ticket(), self.get("num"), self.get("base"),
+                                 self.get("guard_warning") if phase == "review" else "")
         except FileNotFoundError as err:
             raise Stop(str(err))