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

{feature_flow_cli-0.2.0/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.2.0
+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
@@ -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,9 +176,14 @@ 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.
@@ -240,14 +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 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.
+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
 
@@ -274,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 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`.
 

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

@@ -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,9 +157,14 @@ 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.
@@ -221,14 +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 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.
+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
 
@@ -255,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 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`.
 

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

@@ -47,8 +47,8 @@ Say what will happen: for each ticket, a builder subagent and then a reviewer su
 
 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.

{feature_flow_cli-0.2.0 → 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.2.0"
+__version__ = "0.3.0"

{feature_flow_cli-0.2.0 → feature_flow_cli-0.3.0}/feature_flow/codehash.py

@@ -12,12 +12,16 @@ 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 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))
 
 

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

@@ -10,9 +10,10 @@ import secrets
 import shutil
 from pathlib import Path
 
-from feature_flow import checks, codehash, floorguard, gate, git, prompts, state, suggest, tickets
+from feature_flow import checks, codehash, floorguard, gate, git, prompts, proof, state, suggest, tickets
 
 
+NOTE_SEP = "\t"  # the state file keeps one line per key, so the review notes are tab separated
 VERDICT = re.compile(r"^REVIEW: (PASS|FAIL)[ \t\r\f\v]*$")
 
 
@@ -120,7 +121,7 @@ class Conductor:
         for word in result.out.split():
             if word.startswith("total="):
                 total = int(word[len("total="):])
-        return total * 2 * self.max_retries * (self.max_rounds + 1) + 1
+        return total * 3 * self.max_retries * (self.max_rounds + 1) + 1
 
     def count_run(self):
         runs = self.num("runs") + 1
@@ -142,6 +143,7 @@ class Conductor:
     def hand_out_review(self):
         self.count_run()
         self.st["phase"] = "review"
+        self.st["review_pass"] = self.get("review_pass") or "spec"
         self.st["review_attempt"] = self.num("review_attempt") + 1
         self.st["review_sha"] = git.head()
         self.st["relay_handoff"] = "1" if self.relay else ""
@@ -162,6 +164,7 @@ class Conductor:
                        % (source, self.ticket_name()))
         self.st["attempt"] = 0
         self.st["review_attempt"] = 0
+        self.st["review_pass"] = "spec"
         return self.hand_out_build()
 
     def pick_ticket(self):
@@ -190,7 +193,7 @@ class Conductor:
         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": "", "guard_warning": ""})
+                        "attempt": 0, "review_attempt": 0, "round": 0, "review_sha": "", "review_notes": "", "review_pass": "spec"})
         self.snapshot_code()
         self.run_smoke()
         return self.hand_out_build()
@@ -242,9 +245,70 @@ class Conductor:
         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 ""
+        notes = warnings[:1]
+        if self.gate_on:
+            report, note = self.run_done_when()
+            if report is not None:
+                return self.send_back("done when", report)
+            notes.append(note)
+            report, note = self.run_test_first()
+            if report is not None:
+                return self.send_back("test first", report)
+            if note:
+                notes.append(note)
+        self.st["review_notes"] = NOTE_SEP.join(notes)
         return self.hand_out_review()
 
+    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())
+        listed = git._git("ls-tree", "--name-only", self.get("base"), "--", rel, check=False)
+        if listed.returncode != 0:
+            raise Stop("cannot read %s at the base commit: %s" % (rel, listed.stderr.strip()))
+        if listed.stdout.strip():
+            return git.show_text("%s:%s" % (self.get("base"), rel))
+        text = Path(self.ticket()).read_text(encoding="utf-8")
+        return text.split("\n## Answer", 1)[0]
+
+    def run_done_when(self):
+        """Run the ticket's check block. Returns (failure report or None, note for the reviewer)."""
+        try:
+            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))
+        if not found:
+            self.log("DONEWHEN-SKIP")
+            return None, "the conductor ran no Done when checks: the ticket has no check block"
+        ok, report = proof.run_checks(found, self.gate_timeout)
+        dirty = git.changes()
+        if dirty:
+            raise Stop("a Done when check of %s changed the working tree: %s. a check command must not change it"
+                       % (self.ticket_name(), " ".join(dirty[:5])))
+        self.log("DONEWHEN-PASS" if ok else "DONEWHEN-FAIL")
+        if not ok:
+            return report, ""
+        return None, "the conductor ran %d Done when check(s) and all passed" % len(found)
+
+    def run_test_first(self):
+        """For a `Test first: yes` ticket, prove a test-only commit failed the Test command.
+        Returns (failure report or None, note for the reviewer or "")."""
+        if not proof.wants_test_first(self.ticket_at_base()):
+            return None, ""
+        test = tickets.commands_value(self.commands, "Test")
+        if not test:
+            self.log("TESTFIRST-SKIP")
+            return None, "the conductor did not check test first: commands.md has no Test command"
+
+        def remember(value):
+            self.st["restore"] = value
+            self.save()
+        try:
+            ok, text = proof.test_first(self.get("base"), test, self.plan, self.gate_timeout, remember)
+        except proof.GitError as err:
+            raise Stop("test first check of %s: %s" % (self.ticket_name(), err))
+        self.log("TESTFIRST-PASS" if ok else "TESTFIRST-FAIL")
+        return (None, text) if ok else (text, "")
+
     # ---- commands ------------------------------------------------------
 
     def handoff(self):
@@ -278,6 +342,14 @@ class Conductor:
 
     def next(self):
         self.check_owner()
+        if self.get("restore"):
+            try:
+                git._git("checkout", "-q", self.get("restore"))
+            except RuntimeError as err:
+                raise Stop("cannot put the working copy back after the test first check: %s. run `git checkout %s` "
+                           "by hand" % (err, self.get("restore")))
+            self.st["restore"] = ""
+            self.save()
         if not self.plan.is_dir():
             raise Stop("no plan folder %s" % self.plan)
         if self.get("relay_handoff") == "1":
@@ -338,6 +410,10 @@ 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":
+            self.st["review_pass"] = "quality"
+            self.st["review_attempt"] = 0
+            return self.hand_out_review()
         if verdict == "pass":
             self.st["phase"] = ""
             self.st["done"] = self.num("done") + 1
@@ -346,7 +422,8 @@ class Conductor:
             return self.pick_ticket()
         if verdict == "fail":
             findings = self.findings_file.read_text(encoding="utf-8") if self.findings_file.is_file() else ""
-            return self.send_back("independent review", findings)
+            return self.send_back("quality review" if self.get("review_pass") == "quality" else "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()
@@ -358,8 +435,11 @@ 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"
             return prompts.build(phase, self.scripts, self.feature, self.ticket(), self.get("num"), self.get("base"),
-                                 self.get("guard_warning") if phase == "review" else "")
+                                 [n for n in self.get("review_notes").split(NOTE_SEP) if n] if phase != "build" else (),
+                                 retry=self.num("round") > 0)
         except FileNotFoundError as err:
             raise Stop(str(err))
 

{feature_flow_cli-0.2.0 → feature_flow_cli-0.3.0}/feature_flow/git.py

@@ -13,6 +13,14 @@ def _git(*args, check=True):
     return result
 
 
+def show_text(revision_path):
+    """`git show <rev>:<path>` decoded as UTF-8 (the platform's default encoding is not what a ticket is written in)."""
+    result = subprocess.run(["git", "show", revision_path], stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+    if result.returncode != 0:
+        raise RuntimeError("git show %s failed: %s" % (revision_path, result.stderr.decode("utf-8", "replace").strip()))
+    return result.stdout.decode("utf-8", "replace").replace("\r\n", "\n")
+
+
 def git_dir():
     result = _git("rev-parse", "--absolute-git-dir", check=False)
     if result.returncode != 0:

{feature_flow_cli-0.2.0 → feature_flow_cli-0.3.0}/feature_flow/prompts.py

@@ -5,9 +5,9 @@ The text is runtime neutral: any agent that can read a prompt can follow it.
 
 from pathlib import Path
 
-ROLES = {"build": "ticket-builder.md", "review": "ticket-reviewer.md",
+ROLES = {"build": "ticket-builder.md", "review": "ticket-reviewer.md", "review-quality": "ticket-reviewer.md",
          "plan": "feature-planner.md", "plan-review": "plan-reviewer.md"}
-GUIDES = {"build": "build.md", "review": "review.md", "plan": "plan.md", "plan-review": "plan-review.md"}
+GUIDES = {"build": "build.md", "review": "review.md", "review-quality": "review-quality.md", "plan": "plan.md", "plan-review": "plan-review.md"}
 
 
 def find_file(scripts, folder, name):
@@ -32,7 +32,7 @@ def _body(path):
     return text.strip("\n")
 
 
-def build(phase, scripts, feature, ticket, num, sha, warning=""):
+def build(phase, scripts, feature, ticket, num, sha, notes=(), retry=False):
     role = _body(find_file(scripts, "agents", ROLES[phase]))
     guide = _body(find_file(scripts, "guides", GUIDES[phase]))
     for placeholder, value in (("<feature>", feature), ("<NN>", num), ("<ticket>", ticket), ("<sha>", sha),
@@ -46,13 +46,19 @@ def build(phase, scripts, feature, ticket, num, sha, warning=""):
                 "commit. Do not review your own work." % (num, feature, feature, num, ticket, sha, fresh))
         intro = "The build guide follows. Follow it exactly."
     else:
-        task = ("Your task: review ticket %s of the feature `%s` (`%s %s %s`). 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, ticket, sha, fresh))
-        if warning:
-            task += "\nThe floor guard warns: %s" % warning
+        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,
+                   fresh))
+        for note in notes:
+            task += "\nThe conductor notes: %s" % note
         intro = "The review guide follows. Follow it exactly."
-    return "\n\n".join([role, "---", intro, guide, "---", task]) + "\n"
+    parts = [role, "---", intro, guide, "---", task]
+    if retry and phase == "build":
+        parts += ["The debugging guide follows. Follow it before you change any code.",
+                  _body(find_file(scripts, "guides", "debug.md"))]
+    return "\n\n".join(parts) + "\n"
 
 
 def plan(phase, scripts, feature, draft, brief, findings=""):