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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: feature-flow-cli
-Version: 0.7.0
+Version: 0.8.0
 Summary: A ticket-graph workflow for coding agents: installs the feature-flow skill into a repo
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/hamilton-sky/feature-flow
@@ -25,10 +25,10 @@ Dynamic: license-file
 
 Plan a feature as a graph of small tickets, then build them in the session you are already in. One command, `/feature-flow`, does both. Every ticket is built by one fresh subagent and checked by another that never saw the builder's reasoning. A script, not the agent, decides the order of the steps, runs the build and tests, and watches for work that weakens the checks, and the whole run has limits.
 
-One skill, 2 agent roles, a Python conductor, 4 Python scripts, an installer for both agents, a demo and a test suite. All of it is Python (standard library only), so it runs on Linux, macOS and Windows. MIT licensed.
+One skill, 4 agent roles, a Python conductor, 6 Python scripts (`flow`, `flow-trust`, `flow-status`, `flow-view`, `gate`, `floor-guard`), an installer for both agents, a demo and a test suite. All of it is Python (standard library only), so it runs on Linux, macOS and Windows. MIT licensed.
 
 - [Quick start](#quick-start) · [How a ticket flows](#how-a-ticket-flows) · [The skill and the roles](#the-skill-and-the-roles) · [Plans and tickets](#plans-and-tickets)
-- [See the graph](#see-the-graph) · [Long features and handoff](#long-features-and-handoff) · [What is tested](#what-is-tested) · [Upgrading](#upgrading) · [Caution](#caution)
+- [See the graph](#see-the-graph) · [Long features and handoff](#long-features-and-handoff) · [What is tested](#what-is-tested) · [Limits](#limits) · [Upgrading](#upgrading) · [Caution](#caution)
 
 ## Quick start
 
@@ -51,7 +51,7 @@ Without a clone, the same installer runs from [PyPI](https://pypi.org/project/fe
 uvx feature-flow-cli install /path/to/your/repo --agent all   # or: pipx run feature-flow-cli install ...
 ```
 
-The package puts a `feature-flow` command on your PATH with `install`, `status <feature>` and `view <feature>`. It installs the same files, byte for byte, as `install.py` from a clone.
+The package puts a `feature-flow` command on your PATH with `install`, `uninstall`, `status <feature>`, `view <feature>`, `reset <feature>` and `report <feature>`. It installs the same files, byte for byte, as `install.py` from a clone.
 
 The installer lists what it wrote in `.feature-flow/installed.txt`, with each file's hash in `.feature-flow/installed.sha256`. Commit those files (`git add --pathspec-from-file=.feature-flow/installed.txt`); until you do, the flow does not count them as uncommitted changes. Installing a newer version over an older one updates every file nobody edited since it was installed, and keeps (and names) the ones you changed; `--force` replaces those too.
 
@@ -203,14 +203,18 @@ prints OK
 - **The Answers are the handoff between subagents.** The next builder reads the Answers of the tickets it depends on.
 - `settle` tickets record a decision. `convert` tickets migrate something and must be safe to run twice.
 - **A worker may change only** its own Status line and Answer, lines appended to `map.md` and `learnings.md`, and the code the ticket calls for. Rewriting its own Done when, editing another ticket, or touching `commands.md` fails the guard.
-- `Floor:` categories: `skip`, `suppress`, `empty-catch`, `test-delete`, `threshold`, `config`, `ticket-edit`, `commands-edit`, and `flow-edit` (allows the conductor's code check below, for the build only). `skip` covers skipped, expected-fail and focused tests (`.only(`, `fit(`, `fdescribe(` on test paths); `config` covers more lint and test config files, the lint and test sections of `pyproject.toml` and `setup.cfg`, scripts and test keys in `package.json`, new skip or xfail words in `conftest.py`, and a `Makefile` only when `commands.md` uses `make`. A test file that loses assertions is shown to the reviewer as a warning, not a finding. The line is read from the ticket as it was before the work started, so a worker cannot excuse itself.
+- `Floor:` categories: `skip`, `suppress`, `empty-catch`, `test-delete`, `threshold`, `trivial-assert` (an assertion that cannot fail, added to a test file: `assert True`, `assertEqual(x, x)`, `expect(v).toBe(v)`), `config`, `ticket-edit`, `commands-edit`, and `flow-edit` (allows the conductor's code check below, for the build only). `skip` covers skipped, expected-fail and focused tests (`.only(`, `fit(`, `fdescribe(` on test paths); `config` covers more lint and test config files, the lint and test sections of `pyproject.toml` and `setup.cfg`, scripts and test keys in `package.json`, new skip or xfail words in `conftest.py`, and a `Makefile` only when `commands.md` uses `make`. A test file that loses assertions is shown to the reviewer as a warning, not a finding. The line is read from the ticket as it was before the work started, so a worker cannot excuse itself.
 - The guard needs the plan to be tracked by git. If you keep tickets in an ignored folder, it cannot see changes to them.
 - The commands in `commands.md` run with nobody watching and must exit non zero on failure.
 
 ## See the graph
 
+![The animated ticket graph for the demo plan: five of ten tickets resolved, two ready, one in progress](docs/flow-view.png)
+
+*The page `flow-view` writes, shown for the demo plan from `examples/demo.sh`: resolved tickets in green, ready ones in amber, the one being worked in blue, the rest waiting. Press Replay to watch the run back from git history.*
+
 ```bash
-python3 scripts/flow-view.py csv-export            write the page and open it
+python3 scripts/flow-view.py csv-export            write the page and open it (or: feature-flow view csv-export)
 python3 scripts/flow-view.py csv-export --watch    keep it updating while tickets are built
 bash examples/demo.sh --open                    try it on a made up project, no setup needed
 ```
@@ -251,6 +255,8 @@ python3 scripts/flow-status.py <feature>                  table of tickets and w
 python3 scripts/flow-status.py <feature> --next           path of the next ready ticket (exit 10 = done, 11 = stuck)
 python3 scripts/flow-status.py <feature> --counts         one line of counts
 python3 scripts/flow-status.py <feature> --check          cycles, missing blockers, missing Done when, unordered mentions
+python3 scripts/flow-status.py <feature> --lint           --check plus: a check block (or `Check: none <why>`) on every ticket, a Test command
+feature-flow report <feature>                             what a run did, from its log: builds, reviews, failed checks, stops
 python3 scripts/flow-status.py <feature> --mermaid        the ticket graph, coloured by status (add "plain" for none)
 python3 scripts/flow-status.py <feature> --json           every ticket with status, blockers and readiness
 python3 scripts/flow-view.py <feature> [--watch]          the animated graph page, opened in your browser
@@ -314,6 +320,17 @@ A `package` job builds the wheel and the sdist and runs `tests/package_smoke.py`
 
 `RUN_REAL=1 bash tests/smoke-real.sh --interactive` is the acceptance run with Claude Code. It runs real sessions on the demo project and spends money, which is why it asks for `RUN_REAL=1`.
 
+## Limits
+
+feature-flow's layers are tripwires, not a security boundary. They catch accidents and lazy shortcuts by an agent; a determined agent that controls the session could still get around them.
+
+- **The verdict relay is trusted.** The session saves a reviewer's reply and hands it to `flow.py verdict`. The conductor reads `REVIEW: PASS` or `REVIEW: FAIL` from that file and cannot prove the session passed it on unedited.
+- **The floor guard reads diffs with patterns.** It does not see a test made trivially true by other means (a mock that returns the expected answer, an `assert` on something that is always set, a test that no longer exercises the code), or an assertion weakened without being deleted. It does catch assertions that cannot fail (`trivial-assert`) and warns the reviewer when a test file loses assertions. A new test with no assertion at all is not caught. The red-first proof only covers tickets with `Test first: yes`.
+- **A plan can be wrong and still pass.** The plan lint checks that every ticket has a way to be proven and that `commands.md` has a Test command. It cannot tell whether the plan builds the right thing; the second yes is yours.
+- **The trust runner stops accidents, not the session.** It catches a builder editing the conductor mid-run. The session that runs it is the thing it cannot check; a hand-run `flow-trust.py` is unprotected (see above).
+- **Little real-world use so far.** Almost everything has been built by feature-flow on its own repo. The Codex skill and the Codex planner have not been run by hand, and the Quick gate has only been run by tests. See [docs/field-run.md](docs/field-run.md) for how to try it on your own repo and what to send back.
+- **One ticket at a time**, with a handoff to a new session every few tickets.
+
 ## Upgrading
 
 Earlier versions had seven skills and an unattended loop. The five flow skills are gone, and `/feature-flow` replaces them:

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

@@ -6,10 +6,10 @@
 
 Plan a feature as a graph of small tickets, then build them in the session you are already in. One command, `/feature-flow`, does both. Every ticket is built by one fresh subagent and checked by another that never saw the builder's reasoning. A script, not the agent, decides the order of the steps, runs the build and tests, and watches for work that weakens the checks, and the whole run has limits.
 
-One skill, 2 agent roles, a Python conductor, 4 Python scripts, an installer for both agents, a demo and a test suite. All of it is Python (standard library only), so it runs on Linux, macOS and Windows. MIT licensed.
+One skill, 4 agent roles, a Python conductor, 6 Python scripts (`flow`, `flow-trust`, `flow-status`, `flow-view`, `gate`, `floor-guard`), an installer for both agents, a demo and a test suite. All of it is Python (standard library only), so it runs on Linux, macOS and Windows. MIT licensed.
 
 - [Quick start](#quick-start) · [How a ticket flows](#how-a-ticket-flows) · [The skill and the roles](#the-skill-and-the-roles) · [Plans and tickets](#plans-and-tickets)
-- [See the graph](#see-the-graph) · [Long features and handoff](#long-features-and-handoff) · [What is tested](#what-is-tested) · [Upgrading](#upgrading) · [Caution](#caution)
+- [See the graph](#see-the-graph) · [Long features and handoff](#long-features-and-handoff) · [What is tested](#what-is-tested) · [Limits](#limits) · [Upgrading](#upgrading) · [Caution](#caution)
 
 ## Quick start
 
@@ -32,7 +32,7 @@ Without a clone, the same installer runs from [PyPI](https://pypi.org/project/fe
 uvx feature-flow-cli install /path/to/your/repo --agent all   # or: pipx run feature-flow-cli install ...
 ```
 
-The package puts a `feature-flow` command on your PATH with `install`, `status <feature>` and `view <feature>`. It installs the same files, byte for byte, as `install.py` from a clone.
+The package puts a `feature-flow` command on your PATH with `install`, `uninstall`, `status <feature>`, `view <feature>`, `reset <feature>` and `report <feature>`. It installs the same files, byte for byte, as `install.py` from a clone.
 
 The installer lists what it wrote in `.feature-flow/installed.txt`, with each file's hash in `.feature-flow/installed.sha256`. Commit those files (`git add --pathspec-from-file=.feature-flow/installed.txt`); until you do, the flow does not count them as uncommitted changes. Installing a newer version over an older one updates every file nobody edited since it was installed, and keeps (and names) the ones you changed; `--force` replaces those too.
 
@@ -184,14 +184,18 @@ prints OK
 - **The Answers are the handoff between subagents.** The next builder reads the Answers of the tickets it depends on.
 - `settle` tickets record a decision. `convert` tickets migrate something and must be safe to run twice.
 - **A worker may change only** its own Status line and Answer, lines appended to `map.md` and `learnings.md`, and the code the ticket calls for. Rewriting its own Done when, editing another ticket, or touching `commands.md` fails the guard.
-- `Floor:` categories: `skip`, `suppress`, `empty-catch`, `test-delete`, `threshold`, `config`, `ticket-edit`, `commands-edit`, and `flow-edit` (allows the conductor's code check below, for the build only). `skip` covers skipped, expected-fail and focused tests (`.only(`, `fit(`, `fdescribe(` on test paths); `config` covers more lint and test config files, the lint and test sections of `pyproject.toml` and `setup.cfg`, scripts and test keys in `package.json`, new skip or xfail words in `conftest.py`, and a `Makefile` only when `commands.md` uses `make`. A test file that loses assertions is shown to the reviewer as a warning, not a finding. The line is read from the ticket as it was before the work started, so a worker cannot excuse itself.
+- `Floor:` categories: `skip`, `suppress`, `empty-catch`, `test-delete`, `threshold`, `trivial-assert` (an assertion that cannot fail, added to a test file: `assert True`, `assertEqual(x, x)`, `expect(v).toBe(v)`), `config`, `ticket-edit`, `commands-edit`, and `flow-edit` (allows the conductor's code check below, for the build only). `skip` covers skipped, expected-fail and focused tests (`.only(`, `fit(`, `fdescribe(` on test paths); `config` covers more lint and test config files, the lint and test sections of `pyproject.toml` and `setup.cfg`, scripts and test keys in `package.json`, new skip or xfail words in `conftest.py`, and a `Makefile` only when `commands.md` uses `make`. A test file that loses assertions is shown to the reviewer as a warning, not a finding. The line is read from the ticket as it was before the work started, so a worker cannot excuse itself.
 - The guard needs the plan to be tracked by git. If you keep tickets in an ignored folder, it cannot see changes to them.
 - The commands in `commands.md` run with nobody watching and must exit non zero on failure.
 
 ## See the graph
 
+![The animated ticket graph for the demo plan: five of ten tickets resolved, two ready, one in progress](docs/flow-view.png)
+
+*The page `flow-view` writes, shown for the demo plan from `examples/demo.sh`: resolved tickets in green, ready ones in amber, the one being worked in blue, the rest waiting. Press Replay to watch the run back from git history.*
+
 ```bash
-python3 scripts/flow-view.py csv-export            write the page and open it
+python3 scripts/flow-view.py csv-export            write the page and open it (or: feature-flow view csv-export)
 python3 scripts/flow-view.py csv-export --watch    keep it updating while tickets are built
 bash examples/demo.sh --open                    try it on a made up project, no setup needed
 ```
@@ -232,6 +236,8 @@ python3 scripts/flow-status.py <feature>                  table of tickets and w
 python3 scripts/flow-status.py <feature> --next           path of the next ready ticket (exit 10 = done, 11 = stuck)
 python3 scripts/flow-status.py <feature> --counts         one line of counts
 python3 scripts/flow-status.py <feature> --check          cycles, missing blockers, missing Done when, unordered mentions
+python3 scripts/flow-status.py <feature> --lint           --check plus: a check block (or `Check: none <why>`) on every ticket, a Test command
+feature-flow report <feature>                             what a run did, from its log: builds, reviews, failed checks, stops
 python3 scripts/flow-status.py <feature> --mermaid        the ticket graph, coloured by status (add "plain" for none)
 python3 scripts/flow-status.py <feature> --json           every ticket with status, blockers and readiness
 python3 scripts/flow-view.py <feature> [--watch]          the animated graph page, opened in your browser
@@ -295,6 +301,17 @@ A `package` job builds the wheel and the sdist and runs `tests/package_smoke.py`
 
 `RUN_REAL=1 bash tests/smoke-real.sh --interactive` is the acceptance run with Claude Code. It runs real sessions on the demo project and spends money, which is why it asks for `RUN_REAL=1`.
 
+## Limits
+
+feature-flow's layers are tripwires, not a security boundary. They catch accidents and lazy shortcuts by an agent; a determined agent that controls the session could still get around them.
+
+- **The verdict relay is trusted.** The session saves a reviewer's reply and hands it to `flow.py verdict`. The conductor reads `REVIEW: PASS` or `REVIEW: FAIL` from that file and cannot prove the session passed it on unedited.
+- **The floor guard reads diffs with patterns.** It does not see a test made trivially true by other means (a mock that returns the expected answer, an `assert` on something that is always set, a test that no longer exercises the code), or an assertion weakened without being deleted. It does catch assertions that cannot fail (`trivial-assert`) and warns the reviewer when a test file loses assertions. A new test with no assertion at all is not caught. The red-first proof only covers tickets with `Test first: yes`.
+- **A plan can be wrong and still pass.** The plan lint checks that every ticket has a way to be proven and that `commands.md` has a Test command. It cannot tell whether the plan builds the right thing; the second yes is yours.
+- **The trust runner stops accidents, not the session.** It catches a builder editing the conductor mid-run. The session that runs it is the thing it cannot check; a hand-run `flow-trust.py` is unprotected (see above).
+- **Little real-world use so far.** Almost everything has been built by feature-flow on its own repo. The Codex skill and the Codex planner have not been run by hand, and the Quick gate has only been run by tests. See [docs/field-run.md](docs/field-run.md) for how to try it on your own repo and what to send back.
+- **One ticket at a time**, with a handoff to a new session every few tickets.
+
 ## Upgrading
 
 Earlier versions had seven skills and an unattended loop. The five flow skills are gone, and `/feature-flow` replaces them:

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

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

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

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

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

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

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

@@ -573,7 +573,7 @@ class Conductor:
         self.no_plan_yet()
         if not self.draft.is_dir():
             raise Stop("no draft plan in %s. run the planner first" % self.draft_text())
-        check = checks.flow_status(self.scripts, self.feature, "--check", root=self.draft_root)
+        check = checks.flow_status(self.scripts, self.feature, "--lint", root=self.draft_root)
         if not check.ok:
             raise Stop("the draft fails the plan check, fix it first: %s"
                        % " ".join(check.out.split())[:400])

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

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

feature_flow_cli-0.8.0/feature_flow/report.py

@@ -0,0 +1,89 @@
+"""feature-flow report <feature>: what a run did, read from its log.
+
+usage: feature-flow report <feature>
+Reads .feature-flow/state/flow-<feature>.log (one `time,ticket,EVENT` line per step) and prints, per
+ticket, how many times it was built and reviewed and which checks failed, then the run's STOPs, resets
+and handoffs. Read-only. It cannot see a trust-runner STOP (the runner stops before the conductor
+logs anything): the session's own output shows those, so count them by hand.
+"""
+
+import sys
+from pathlib import Path
+
+from feature_flow import git, state, suggest
+
+USAGE = "usage: feature-flow report <feature>"
+FAILS = ("GATE-FAIL", "GUARD-FAIL", "DONEWHEN-FAIL", "TESTFIRST-FAIL", "VERDICT-FAIL")
+RUN_EVENTS = ("START", "TAKEOVER", "RESET", "HANDOFF", "STOP")
+
+
+def parse(text):
+    """[(ticket, event, detail)] for each well formed line; a bad line is skipped."""
+    rows = []
+    for line in text.splitlines():
+        parts = line.split(",", 2)
+        if len(parts) != 3 or not parts[2].strip():
+            continue
+        event, _, detail = parts[2].strip().partition(" ")
+        rows.append((parts[1].strip(), event, detail.strip()))
+    return rows
+
+
+def summarize(rows):
+    """(per-ticket dict in first-seen order, run-level counts, STOP reasons)."""
+    tickets = {}
+    run = {name: 0 for name in RUN_EVENTS}
+    stops = []
+    for num, event, detail in rows:
+        if event in RUN_EVENTS:
+            run[event] += 1
+            if event == "STOP":
+                stops.append((num, detail or "(no reason logged)"))
+        if num in ("", "-") or event in RUN_EVENTS:
+            continue
+        row = tickets.setdefault(num, {})
+        row[event] = row.get(event, 0) + 1
+    return tickets, run, stops
+
+
+def render(feature, rows):
+    tickets, run, stops = summarize(rows)
+    out = ["report for %s: %d log line(s)" % (feature, len(rows)), ""]
+    if tickets:
+        out.append("ticket  builds  reviews  small  quick-gate  full-gate  failures")
+        for num, row in tickets.items():
+            fails = ", ".join("%s x%d" % (name, row[name]) for name in FAILS if row.get(name))
+            out.append("%-6s  %6d  %7d  %5d  %10d  %9d  %s"
+                       % (num, row.get("BUILD", 0), row.get("REVIEW", 0), row.get("REVIEW-SMALL", 0),
+                          row.get("GATE-QUICK", 0), row.get("GATE-FULL", 0), fails or "none"))
+        reworked = [n for n, row in tickets.items() if row.get("BUILD", 0) > 1]
+        out += ["", "tickets built more than once (reworked): %s" % (", ".join(reworked) or "none")]
+    else:
+        out.append("no ticket events yet")
+    out += ["", "starts %d, takeovers %d, resets %d, handoffs %d, stops %d"
+            % (run["START"], run["TAKEOVER"], run["RESET"], run["HANDOFF"], run["STOP"])]
+    for num, reason in stops:
+        out.append("  STOP at ticket %s: %s" % (num, reason))
+    out += ["", "trust-runner STOPs are not in this log: count them from the session by hand"]
+    return "\n".join(out) + "\n"
+
+
+def main(argv, out=None, err=None):
+    out = out or sys.stdout
+    err = err or sys.stderr
+    if len(argv) != 1 or argv[0].startswith("-"):
+        err.write(USAGE + "\n")
+        return 2
+    feature = argv[0]
+    top = git.toplevel()
+    if top is None:
+        err.write("not inside a git repo\n")
+        return 2
+    path = state.log_path(Path(top) / state.STATE_DIR, feature)
+    text = state.read_text(path)
+    if text is None:
+        err.write("no run log for %s (%s)\n" % (feature, path))
+        err.write(suggest.hint(feature, [p.name[5:-4] for p in path.parent.glob("flow-*.log")]))
+        return 2
+    out.write(render(feature, parse(text)))
+    return 0

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

@@ -1,16 +1,18 @@
 """The ticket graph reader, ported from the bash script of the same name.
 
-usage: python3 scripts/flow-status.py <feature> [--next | --counts | --check | --mermaid [plain] | --json]
+usage: python3 scripts/flow-status.py <feature> [--next | --counts | --check | --lint | --mermaid [plain] | --json]
 Exit codes for --next: 0 a ready ticket path is printed, 10 all done, 11 unfinished but nothing ready.
 """
 
 import os
 import re
+import shlex
+import shutil
 import sys
 
 from feature_flow import suggest, tickets
 
-USAGE = "usage: python3 scripts/flow-status.py <feature> [--next | --counts | --check | --mermaid [plain] | --json]"
+USAGE = "usage: python3 scripts/flow-status.py <feature> [--next | --counts | --check | --lint | --mermaid [plain] | --json]"
 
 
 def _env(name, default):
@@ -55,7 +57,7 @@ def run(argv, out, err):
         err.write("no tickets in %s\n" % folder)
         return 2
 
-    if mode == "--check":
+    if mode in ("--check", "--lint"):
         learnings = "%s/%s/learnings.md" % (root, feature)
         if os.path.isfile(learnings):
             lines = sum(1 for line in tickets.records(learnings) if line.strip(" \t\n\v\f\r") != "")
@@ -64,10 +66,10 @@ def run(argv, out, err):
                           % lines)
 
     g = tickets.Graph(paths)
-    return _report(g, mode, opt, feature, out, err)
+    return _report(g, mode, opt, feature, out, err, root)
 
 
-def _report(g, mode, opt, feature, out, err):
+def _report(g, mode, opt, feature, out, err, root="plans"):
     n = len(g.order)
     count = {"resolved": 0, "open": 0, "claimed": 0, "waiting": 0, "parked": 0, "unknown": 0}
     ready = {}
@@ -138,8 +140,9 @@ def _report(g, mode, opt, feature, out, err):
                       "  classDef parked fill:#eeeeee,stroke:#bbbbbb,stroke-dasharray:4 3\n")
         return 0
 
-    if mode == "--check":
-        return _check(g, ready, nready, unfinished, out)
+    if mode in ("--check", "--lint"):
+        extra = lint(g, "%s/%s" % (root, feature)) if mode == "--lint" else ([], [])
+        return _check(g, ready, nready, unfinished, out, extra)
 
     for t in g.order:
         bl = ",".join("%02d" % d for d in g.blk[t])
@@ -148,8 +151,47 @@ def _report(g, mode, opt, feature, out, err):
     return 0
 
 
-def _check(g, ready, nready, unfinished, out):
-    errors = []
+def lint(g, plan_dir):
+    """(errors, warnings) the stricter plan lint adds to --check: every ticket carries a check block or
+    says `Check: none <why>`, and commands.md names a Test command that can be found."""
+    errors, warnings = [], []
+    for t in g.order:
+        lab = g.lab[t]
+        if g.typ.get(t) == "settle":
+            continue
+        lines = tickets.records(g.path[t])
+        has_block = any(line.startswith("```check") for line in lines)
+        none = next((line for line in lines[:20] if line.startswith("Check:")), None)
+        if none is not None:
+            reason = none[len("Check:"):].strip()
+            if not reason.lower().startswith("none") or not reason[4:].strip(" \t:-"):
+                errors.append(lab + ": `Check:` must read `Check: none <why>`")
+        elif not has_block:
+            errors.append(lab + ": no check block. add one under Done when, or `Check: none <why>` in the header")
+        for line in lines:
+            if line.strip().startswith("##"):
+                continue
+            for ref in re.findall(r"`([A-Za-z0-9_./-]+/[A-Za-z0-9_.-]+\.[A-Za-z0-9]+)`", line):
+                if "new" not in line.lower() and "plans/" not in ref and not os.path.exists(ref):
+                    warnings.append("%s: names `%s`, which does not exist here (say `new` if it will be created)" % (lab, ref))
+    commands = "%s/commands.md" % plan_dir
+    test = tickets.commands_value(commands, "Test")
+    if not os.path.isfile(commands):
+        errors.append("commands.md is missing")
+    elif not test:
+        errors.append("commands.md has no Test command (a placeholder in angle brackets does not count)")
+    else:
+        try:
+            first = shlex.split(test, posix=(os.name != "nt"))[0].strip("\"'")
+        except (ValueError, IndexError):
+            first = test.split()[0]
+        if "=" not in first and shutil.which(first) is None and first not in ("cd", "set", "export"):
+            warnings.append("commands.md Test starts with `%s`, which is not on PATH here" % first)
+    return errors, list(dict.fromkeys(warnings))
+
+
+def _check(g, ready, nready, unfinished, out, extra=([], [])):
+    errors = list(extra[0])
     for t in g.order:
         lab = g.lab[t]
         if t in g.dup:
@@ -209,6 +251,8 @@ def _check(g, ready, nready, unfinished, out):
                 continue
             out.write("warning: %s: mentions ticket %s but is not ordered against it. add it to Blocked by, or reword\n"
                       % (g.lab[t], g.lab[m]))
+    for w in extra[1]:
+        out.write("warning: " + w + "\n")
     if errors:
         for e in errors:
             out.write(e + "\n")

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: feature-flow-cli
-Version: 0.7.0
+Version: 0.8.0
 Summary: A ticket-graph workflow for coding agents: installs the feature-flow skill into a repo
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/hamilton-sky/feature-flow
@@ -25,10 +25,10 @@ Dynamic: license-file
 
 Plan a feature as a graph of small tickets, then build them in the session you are already in. One command, `/feature-flow`, does both. Every ticket is built by one fresh subagent and checked by another that never saw the builder's reasoning. A script, not the agent, decides the order of the steps, runs the build and tests, and watches for work that weakens the checks, and the whole run has limits.
 
-One skill, 2 agent roles, a Python conductor, 4 Python scripts, an installer for both agents, a demo and a test suite. All of it is Python (standard library only), so it runs on Linux, macOS and Windows. MIT licensed.
+One skill, 4 agent roles, a Python conductor, 6 Python scripts (`flow`, `flow-trust`, `flow-status`, `flow-view`, `gate`, `floor-guard`), an installer for both agents, a demo and a test suite. All of it is Python (standard library only), so it runs on Linux, macOS and Windows. MIT licensed.
 
 - [Quick start](#quick-start) · [How a ticket flows](#how-a-ticket-flows) · [The skill and the roles](#the-skill-and-the-roles) · [Plans and tickets](#plans-and-tickets)
-- [See the graph](#see-the-graph) · [Long features and handoff](#long-features-and-handoff) · [What is tested](#what-is-tested) · [Upgrading](#upgrading) · [Caution](#caution)
+- [See the graph](#see-the-graph) · [Long features and handoff](#long-features-and-handoff) · [What is tested](#what-is-tested) · [Limits](#limits) · [Upgrading](#upgrading) · [Caution](#caution)
 
 ## Quick start
 
@@ -51,7 +51,7 @@ Without a clone, the same installer runs from [PyPI](https://pypi.org/project/fe
 uvx feature-flow-cli install /path/to/your/repo --agent all   # or: pipx run feature-flow-cli install ...
 ```
 
-The package puts a `feature-flow` command on your PATH with `install`, `status <feature>` and `view <feature>`. It installs the same files, byte for byte, as `install.py` from a clone.
+The package puts a `feature-flow` command on your PATH with `install`, `uninstall`, `status <feature>`, `view <feature>`, `reset <feature>` and `report <feature>`. It installs the same files, byte for byte, as `install.py` from a clone.
 
 The installer lists what it wrote in `.feature-flow/installed.txt`, with each file's hash in `.feature-flow/installed.sha256`. Commit those files (`git add --pathspec-from-file=.feature-flow/installed.txt`); until you do, the flow does not count them as uncommitted changes. Installing a newer version over an older one updates every file nobody edited since it was installed, and keeps (and names) the ones you changed; `--force` replaces those too.
 
@@ -203,14 +203,18 @@ prints OK
 - **The Answers are the handoff between subagents.** The next builder reads the Answers of the tickets it depends on.
 - `settle` tickets record a decision. `convert` tickets migrate something and must be safe to run twice.
 - **A worker may change only** its own Status line and Answer, lines appended to `map.md` and `learnings.md`, and the code the ticket calls for. Rewriting its own Done when, editing another ticket, or touching `commands.md` fails the guard.
-- `Floor:` categories: `skip`, `suppress`, `empty-catch`, `test-delete`, `threshold`, `config`, `ticket-edit`, `commands-edit`, and `flow-edit` (allows the conductor's code check below, for the build only). `skip` covers skipped, expected-fail and focused tests (`.only(`, `fit(`, `fdescribe(` on test paths); `config` covers more lint and test config files, the lint and test sections of `pyproject.toml` and `setup.cfg`, scripts and test keys in `package.json`, new skip or xfail words in `conftest.py`, and a `Makefile` only when `commands.md` uses `make`. A test file that loses assertions is shown to the reviewer as a warning, not a finding. The line is read from the ticket as it was before the work started, so a worker cannot excuse itself.
+- `Floor:` categories: `skip`, `suppress`, `empty-catch`, `test-delete`, `threshold`, `trivial-assert` (an assertion that cannot fail, added to a test file: `assert True`, `assertEqual(x, x)`, `expect(v).toBe(v)`), `config`, `ticket-edit`, `commands-edit`, and `flow-edit` (allows the conductor's code check below, for the build only). `skip` covers skipped, expected-fail and focused tests (`.only(`, `fit(`, `fdescribe(` on test paths); `config` covers more lint and test config files, the lint and test sections of `pyproject.toml` and `setup.cfg`, scripts and test keys in `package.json`, new skip or xfail words in `conftest.py`, and a `Makefile` only when `commands.md` uses `make`. A test file that loses assertions is shown to the reviewer as a warning, not a finding. The line is read from the ticket as it was before the work started, so a worker cannot excuse itself.
 - The guard needs the plan to be tracked by git. If you keep tickets in an ignored folder, it cannot see changes to them.
 - The commands in `commands.md` run with nobody watching and must exit non zero on failure.
 
 ## See the graph
 
+![The animated ticket graph for the demo plan: five of ten tickets resolved, two ready, one in progress](docs/flow-view.png)
+
+*The page `flow-view` writes, shown for the demo plan from `examples/demo.sh`: resolved tickets in green, ready ones in amber, the one being worked in blue, the rest waiting. Press Replay to watch the run back from git history.*
+
 ```bash
-python3 scripts/flow-view.py csv-export            write the page and open it
+python3 scripts/flow-view.py csv-export            write the page and open it (or: feature-flow view csv-export)
 python3 scripts/flow-view.py csv-export --watch    keep it updating while tickets are built
 bash examples/demo.sh --open                    try it on a made up project, no setup needed
 ```
@@ -251,6 +255,8 @@ python3 scripts/flow-status.py <feature>                  table of tickets and w
 python3 scripts/flow-status.py <feature> --next           path of the next ready ticket (exit 10 = done, 11 = stuck)
 python3 scripts/flow-status.py <feature> --counts         one line of counts
 python3 scripts/flow-status.py <feature> --check          cycles, missing blockers, missing Done when, unordered mentions
+python3 scripts/flow-status.py <feature> --lint           --check plus: a check block (or `Check: none <why>`) on every ticket, a Test command
+feature-flow report <feature>                             what a run did, from its log: builds, reviews, failed checks, stops
 python3 scripts/flow-status.py <feature> --mermaid        the ticket graph, coloured by status (add "plain" for none)
 python3 scripts/flow-status.py <feature> --json           every ticket with status, blockers and readiness
 python3 scripts/flow-view.py <feature> [--watch]          the animated graph page, opened in your browser
@@ -314,6 +320,17 @@ A `package` job builds the wheel and the sdist and runs `tests/package_smoke.py`
 
 `RUN_REAL=1 bash tests/smoke-real.sh --interactive` is the acceptance run with Claude Code. It runs real sessions on the demo project and spends money, which is why it asks for `RUN_REAL=1`.
 
+## Limits
+
+feature-flow's layers are tripwires, not a security boundary. They catch accidents and lazy shortcuts by an agent; a determined agent that controls the session could still get around them.
+
+- **The verdict relay is trusted.** The session saves a reviewer's reply and hands it to `flow.py verdict`. The conductor reads `REVIEW: PASS` or `REVIEW: FAIL` from that file and cannot prove the session passed it on unedited.
+- **The floor guard reads diffs with patterns.** It does not see a test made trivially true by other means (a mock that returns the expected answer, an `assert` on something that is always set, a test that no longer exercises the code), or an assertion weakened without being deleted. It does catch assertions that cannot fail (`trivial-assert`) and warns the reviewer when a test file loses assertions. A new test with no assertion at all is not caught. The red-first proof only covers tickets with `Test first: yes`.
+- **A plan can be wrong and still pass.** The plan lint checks that every ticket has a way to be proven and that `commands.md` has a Test command. It cannot tell whether the plan builds the right thing; the second yes is yours.
+- **The trust runner stops accidents, not the session.** It catches a builder editing the conductor mid-run. The session that runs it is the thing it cannot check; a hand-run `flow-trust.py` is unprotected (see above).
+- **Little real-world use so far.** Almost everything has been built by feature-flow on its own repo. The Codex skill and the Codex planner have not been run by hand, and the Quick gate has only been run by tests. See [docs/field-run.md](docs/field-run.md) for how to try it on your own repo and what to send back.
+- **One ticket at a time**, with a handoff to a new session every few tickets.
+
 ## Upgrading
 
 Earlier versions had seven skills and an unattended loop. The five flow skills are gone, and `/feature-flow` replaces them:

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

@@ -25,6 +25,7 @@ feature_flow/proc.py
 feature_flow/prompts.py
 feature_flow/proof.py
 feature_flow/released.py
+feature_flow/report.py
 feature_flow/state.py
 feature_flow/status.py
 feature_flow/suggest.py

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

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

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

@@ -75,13 +75,13 @@ prints OK
 9. **The last ticket is the acceptance ticket**: it runs the map's bar end to end and is blocked by every ticket that leaves the bar unproven.
 10. **Number from 01 and never renumber.** Tickets added later get the next number.
 11. **More than about 12 tickets?** Plan in rounds: `plans/<feature>/` first, then `plans/<feature>-round-two/` with its own map that links back.
-12. **`Floor: allow <categories>` only when the brief says so.** The floor guard fails a ticket whose diff skips or deletes tests, silences checks, adds empty catches, lowers thresholds, or edits lint, test or CI config. It also fails a worker that edits anything in the plan except its own Status and Answer, appended lines in `map.md` and `learnings.md`, and it fails any change to `commands.md`. If a ticket legitimately has to (for example "migrate the test runner", which changes `commands.md`), add a line such as `Floor: allow config, test-delete, commands-edit` to that ticket, and say so in your reply. 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 add it for itself.
+12. **`Floor: allow <categories>` only when the brief says so.** The floor guard fails a ticket whose diff skips or deletes tests, silences checks, adds empty catches, lowers thresholds, or edits lint, test or CI config. It also fails a worker that edits anything in the plan except its own Status and Answer, appended lines in `map.md` and `learnings.md`, and it fails any change to `commands.md`. If a ticket legitimately has to (for example "migrate the test runner", which changes `commands.md`), add a line such as `Floor: allow config, test-delete, commands-edit` to that ticket, and say so in your reply. Categories: `skip`, `suppress`, `empty-catch`, `test-delete`, `threshold`, `trivial-assert`, `config`, `ticket-edit`, `commands-edit`. The line is read from the ticket as it was before the work started, so a worker cannot add it for itself.
 13. **Name a ticket in prose only if it is ordered against this one.** If a ticket's text says "uses the output of ticket 02", list 02 under `Blocked by`. `--check` warns about mentions that are not ordered.
 
 
 ## Step 5: Check
 
-Run `FLOW_DIR=.feature-flow/state/draft python3 scripts/flow-status.py <feature> --check`. It fails on a missing blocker, a cycle, a missing Done when, a duplicate number, a bad `Test first` value, a bad `Review` value, or no ready ticket, and it warns about tickets that name another ticket in their text without being ordered against it. If the script is not installed, check those by hand. Fix every problem and every warning before you reply.
+Run `FLOW_DIR=.feature-flow/state/draft python3 scripts/flow-status.py <feature> --check`. It fails on a missing blocker, a cycle, a missing Done when, a duplicate number, a bad `Test first` value, a bad `Review` value, or no ready ticket, and it warns about tickets that name another ticket in their text without being ordered against it. If the script is not installed, check those by hand. Then run it again with `--lint` instead of `--check`: the same checks, and it also fails a ticket that has no `check` block (unless it is `Type: settle`, or its header says `Check: none <why>` with a real reason) and a `commands.md` with no Test command, and it warns about a Test command that is not on the PATH and about files a ticket names that do not exist (say `new` on that line when the ticket will create it). `plan-accept` runs the `--lint` rules too. Fix every problem and every warning before you reply.
 
 ## Step 6: Reply
 

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

@@ -20,7 +20,7 @@ is being converted and what the safe default is for anything that does not match
 - <every bullet is checkable by someone who has not read the rest of the plan>
 
 ```check
-# The conductor runs this block before review. One `$` line per bullet that names a command.
+# The conductor runs this block before review. No command can prove the ticket? Drop the block and put `Check: none <why>` in the header instead. One `$` line per bullet that names a command.
 $ <the command from a bullet, read-only, run from the repo's top folder>
 prints <text the output must contain>
 ```