feature-flow-cli 0.1.3__tar.gz → 0.1.4__tar.gz

{feature_flow_cli-0.1.3/feature_flow_cli.egg-info → feature_flow_cli-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: feature-flow-cli
-Version: 0.1.3
+Version: 0.1.4
 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
@@ -206,6 +206,7 @@ A session's context fills up, so the flow moves to a fresh session every few tic
 
 - **One owner at a time.** `start` gives the session a token, and every later call must carry it, so two sessions can never drive the same feature. `HANDOFF` and `DONE` release it.
 - **Resuming after a closed session.** If a session ended without `HANDOFF` (you closed it, it crashed, it ran out of budget), the feature is still owned by it, and a new session stops and says so. Once you are sure the old session is gone, answer yes when the new session asks, or start it with `FLOW_TAKEOVER=1`. With `auto` the skill never takes over on its own.
+- **Stuck on a ticket.** `python3 scripts/flow.py <feature> reset` (or `feature-flow reset <feature>`) reopens a ticket left `claimed` or `in-progress`, commits that, and clears the conductor's run state, so the next `/feature-flow <feature>` starts clean from the ticket files. `reset <NN>` reopens that one ticket, even a resolved one, to build it again. While a session owns the feature it needs `FLOW_TAKEOVER=1`. A mistyped command or feature name gets a `did you mean` hint.
 - **Relay mode.** `FLOW_RELAY=1` hands off after every build and every review, so each phase gets a session of its own.
 - **Nobody needs to watch.** With `auto` the skill asks nothing, and a Claude Code cloud session keeps working while you are away. You only come back to type the `HANDOFF` line.
 

{feature_flow_cli-0.1.3 → feature_flow_cli-0.1.4}/README.md

@@ -187,6 +187,7 @@ A session's context fills up, so the flow moves to a fresh session every few tic
 
 - **One owner at a time.** `start` gives the session a token, and every later call must carry it, so two sessions can never drive the same feature. `HANDOFF` and `DONE` release it.
 - **Resuming after a closed session.** If a session ended without `HANDOFF` (you closed it, it crashed, it ran out of budget), the feature is still owned by it, and a new session stops and says so. Once you are sure the old session is gone, answer yes when the new session asks, or start it with `FLOW_TAKEOVER=1`. With `auto` the skill never takes over on its own.
+- **Stuck on a ticket.** `python3 scripts/flow.py <feature> reset` (or `feature-flow reset <feature>`) reopens a ticket left `claimed` or `in-progress`, commits that, and clears the conductor's run state, so the next `/feature-flow <feature>` starts clean from the ticket files. `reset <NN>` reopens that one ticket, even a resolved one, to build it again. While a session owns the feature it needs `FLOW_TAKEOVER=1`. A mistyped command or feature name gets a `did you mean` hint.
 - **Relay mode.** `FLOW_RELAY=1` hands off after every build and every review, so each phase gets a session of its own.
 - **Nobody needs to watch.** With `auto` the skill asks nothing, and a Claude Code cloud session keeps working while you are away. You only come back to type the `HANDOFF` line.
 

{feature_flow_cli-0.1.3 → feature_flow_cli-0.1.4}/adapters/codex/feature-flow/SKILL.md

@@ -39,6 +39,8 @@ Then run `FLOW_INVOKE='$feature-flow' python3 scripts/flow.py <feature> start`.
 
 If `start` prints `STOP` naming another owner, another session may still be working this feature. Ask the user whether that session is closed. Only on a clear yes, run `start` once more with `FLOW_TAKEOVER=1`. In `auto` mode, never take over: report and stop.
 
+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.
 
 ## The loop

{feature_flow_cli-0.1.3 → feature_flow_cli-0.1.4}/feature_flow/__init__.py

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

{feature_flow_cli-0.1.3 → feature_flow_cli-0.1.4}/feature_flow/cli.py

@@ -3,18 +3,23 @@
 import sys
 from pathlib import Path
 
+from feature_flow import suggest
 from feature_flow.conductor import Conductor, NoPhase, Stop
 
-USAGE = ("usage: python3 scripts/flow.py <feature> start | next | prompt | verdict <file>\n"
+USAGE = ("usage: python3 scripts/flow.py <feature> start | next | prompt | verdict <file> | reset [NN]\n"
          "       python3 scripts/flow.py <feature> plan-prompt <brief> [findings] | plan-review-prompt | plan-accept")
-COMMANDS = ("start", "next", "prompt", "verdict", "plan-prompt", "plan-review-prompt", "plan-accept")
-ARGS = {"verdict": (3,), "plan-prompt": (3, 4)}
+COMMANDS = ("start", "next", "prompt", "verdict", "plan-prompt", "plan-review-prompt", "plan-accept", "reset")
+ARGS = {"verdict": (3,), "plan-prompt": (3, 4), "reset": (2, 3)}
 
 
 def main(argv=None, scripts=None):
     args = list(sys.argv[1:] if argv is None else argv)
     if len(args) < 2 or args[1] not in COMMANDS or not args[0] or args[0].startswith("-"):
         print(USAGE, file=sys.stderr)
+        if len(args) >= 2 and args[0] in COMMANDS:
+            sys.stderr.write("did you mean: flow.py %s %s?\n" % (args[1], args[0]))
+        elif len(args) >= 2:
+            sys.stderr.write(suggest.hint(args[1], COMMANDS))
         return 2
     feature, command = args[0], args[1]
     if feature in (".", "..") or any(c in feature for c in "/\\:"):
@@ -37,6 +42,8 @@ def main(argv=None, scripts=None):
             line = conductor.plan_accept()
         elif command == "prompt":
             line = conductor.prompt()
+        elif command == "reset":
+            line = conductor.reset(args[2] if len(args) == 3 else None)
         elif command == "start":
             line = conductor.start()
         else:

{feature_flow_cli-0.1.3 → feature_flow_cli-0.1.4}/feature_flow/command.py

@@ -7,18 +7,25 @@ python3 scripts/flow.py, with the copy the installer put there.
 import os
 import sys
 
-from feature_flow import __version__, install, status, view
+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]
        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 --version
 install copies the skill, its roles, scripts and guides into a repo; feature-flow install --help says more.
 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.
 """
 
 
+COMMANDS = ("install", "status", "view", "reset", "--version", "--help")
+
+
 def main(argv=None):
     args = list(sys.argv[1:] if argv is None else argv)
     if not args or args[0] in ("-h", "--help", "help"):
@@ -35,5 +42,10 @@ def main(argv=None):
         return status.main(rest)
     if command == "view":
         return view.main(rest, here=os.path.join(install.source_root(), "scripts"))
-    sys.stderr.write("unknown command: %s\n%s" % (command, USAGE))
+    if command == "reset":
+        if not rest or len(rest) > 2:
+            sys.stderr.write(USAGE)
+            return 2
+        return cli.main(rest[:1] + ["reset"] + rest[1:], scripts=Path.cwd() / "scripts")
+    sys.stderr.write("unknown command: %s\n%s%s" % (command, suggest.hint(command, COMMANDS), USAGE))
     return 2

{feature_flow_cli-0.1.3 → feature_flow_cli-0.1.4}/feature_flow/conductor.py

@@ -10,7 +10,7 @@ import secrets
 import shutil
 from pathlib import Path
 
-from feature_flow import checks, git, prompts, state, tickets
+from feature_flow import checks, git, prompts, state, suggest, tickets
 
 
 VERDICT = re.compile(r"^REVIEW: (PASS|FAIL)[ \t\r\f\v]*$")
@@ -254,6 +254,45 @@ class Conductor:
             return self.judge_review()
         return self.pick_ticket()
 
+    def reset(self, num=None):
+        """Put the feature back to a clean start: reopen a half-built ticket (or ticket num), commit that,
+        and forget the run. The tickets stay the truth; only the conductor's note and counters go."""
+        if not self.plan.is_dir():
+            hint = suggest.hint(self.feature, suggest.features(self.root)).strip()
+            raise Stop("no plan folder %s%s" % (self.plan, ". " + hint if hint else ""))
+        owner = self.get("owner")
+        if owner and os.environ.get("FLOW_TAKEOVER", "0") != "1":
+            raise Stop("%s is owned by session %s. if that session is closed or dead, run reset with FLOW_TAKEOVER=1"
+                       % (self.feature, owner))
+        paths = tickets.ticket_files(str(self.plan / (os.environ.get("FLOW_TICKETS") or "tasks")))
+        if num is not None:
+            chosen = [p for p in paths if tickets.number(p) == num.zfill(2)]
+            if not chosen:
+                raise Stop("no ticket %s in %s" % (num, self.plan))
+        else:
+            chosen = [p for p in paths if tickets.status(p) in tickets.RESET]
+        reopened = []
+        for path in chosen:
+            if tickets.status(path) != "open":
+                tickets.set_open(path)
+                reopened.append(path)
+        if reopened:
+            nums = ", ".join(tickets.number(p) for p in reopened)
+            if not git.commit_paths(reopened, "chore(%s): reset %s to open" % (self.feature, nums)):
+                raise Stop("reopened %s but could not commit it. this session must be allowed to run git commit"
+                           % nums)
+        had_run = self.state_file.is_file()
+        for path in (self.state_file, self.findings_file):
+            if path.is_file():
+                path.unlink()
+        if not reopened and not had_run:
+            return "OK nothing to reset for %s. run %s %s" % (self.feature, self.invoke, self.feature)
+        self.st = {}
+        self.log("RESET")
+        done = ["cleared the run state"] if had_run else []
+        done += ["reopened %s" % tickets.name(p) for p in reopened]
+        return "OK %s. run %s %s" % (", ".join(done), self.invoke, self.feature)
+
     def judge_review(self):
         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")

{feature_flow_cli-0.1.3 → feature_flow_cli-0.1.4}/feature_flow/git.py

@@ -72,6 +72,14 @@ def tracked_clean():
             and _git("diff", "--cached", "--quiet", check=False).returncode == 0)
 
 
+def commit_paths(paths, message):
+    """Commit these paths only, whatever else is staged."""
+    paths = [str(p) for p in paths]
+    if _git("add", "--", *paths, check=False).returncode != 0:
+        return False
+    return _git("commit", "-q", "-m", message, "--", *paths, check=False).returncode == 0
+
+
 def commit_file(path, message):
     if _git("add", "--", str(path), check=False).returncode != 0:
         return False

{feature_flow_cli-0.1.3 → feature_flow_cli-0.1.4}/feature_flow/status.py

@@ -8,7 +8,7 @@ import os
 import re
 import sys
 
-from feature_flow import tickets
+from feature_flow import suggest, tickets
 
 USAGE = "usage: python3 scripts/flow-status.py <feature> [--next | --counts | --check | --mermaid [plain] | --json]"
 
@@ -48,6 +48,7 @@ def run(argv, out, err):
     folder = "%s/%s/%s" % (root, feature, _env("FLOW_TICKETS", "tasks"))
     if not os.path.isdir(folder):
         err.write("no ticket folder: %s\n" % folder)
+        err.write(suggest.hint(feature, suggest.features(root)))
         return 2
     paths = tickets.ticket_files(folder)
     if not paths:

feature_flow_cli-0.1.4/feature_flow/suggest.py

@@ -0,0 +1,23 @@
+"""Did-you-mean hints for a mistyped command or feature name."""
+
+import difflib
+import os
+
+
+def closest(word, choices):
+    """The choice nearest to word, or "" when none is close."""
+    found = difflib.get_close_matches(word, list(choices), n=1, cutoff=0.6)
+    return found[0] if found else ""
+
+
+def features(root):
+    """The plan folders under root (plans/ or FLOW_DIR)."""
+    try:
+        return sorted(name for name in os.listdir(str(root)) if os.path.isdir(os.path.join(str(root), name)))
+    except OSError:
+        return []
+
+
+def hint(word, choices, template="did you mean: %s?"):
+    match = closest(word, choices)
+    return (template % match + "\n") if match else ""

{feature_flow_cli-0.1.3 → feature_flow_cli-0.1.4/feature_flow_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: feature-flow-cli
-Version: 0.1.3
+Version: 0.1.4
 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
@@ -206,6 +206,7 @@ A session's context fills up, so the flow moves to a fresh session every few tic
 
 - **One owner at a time.** `start` gives the session a token, and every later call must carry it, so two sessions can never drive the same feature. `HANDOFF` and `DONE` release it.
 - **Resuming after a closed session.** If a session ended without `HANDOFF` (you closed it, it crashed, it ran out of budget), the feature is still owned by it, and a new session stops and says so. Once you are sure the old session is gone, answer yes when the new session asks, or start it with `FLOW_TAKEOVER=1`. With `auto` the skill never takes over on its own.
+- **Stuck on a ticket.** `python3 scripts/flow.py <feature> reset` (or `feature-flow reset <feature>`) reopens a ticket left `claimed` or `in-progress`, commits that, and clears the conductor's run state, so the next `/feature-flow <feature>` starts clean from the ticket files. `reset <NN>` reopens that one ticket, even a resolved one, to build it again. While a session owns the feature it needs `FLOW_TAKEOVER=1`. A mistyped command or feature name gets a `did you mean` hint.
 - **Relay mode.** `FLOW_RELAY=1` hands off after every build and every review, so each phase gets a session of its own.
 - **Nobody needs to watch.** With `auto` the skill asks nothing, and a Claude Code cloud session keeps working while you are away. You only come back to type the `HANDOFF` line.
 

{feature_flow_cli-0.1.3 → feature_flow_cli-0.1.4}/feature_flow_cli.egg-info/SOURCES.txt

@@ -23,6 +23,7 @@ feature_flow/install.py
 feature_flow/prompts.py
 feature_flow/state.py
 feature_flow/status.py
+feature_flow/suggest.py
 feature_flow/tickets.py
 feature_flow/view.py
 feature_flow_cli.egg-info/PKG-INFO

{feature_flow_cli-0.1.3 → feature_flow_cli-0.1.4}/skills/feature-flow/SKILL.md

@@ -39,6 +39,8 @@ Then run `FLOW_INVOKE=/feature-flow python3 scripts/flow.py <feature> start`. It
 
 If `start` prints `STOP` naming another owner, another session may still be working this feature. Ask the user whether that session is closed. Only on a clear yes, run `start` once more with `FLOW_TAKEOVER=1`. In `auto` mode, never take over: report and stop.
 
+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.
 
 ## The loop