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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: feature-flow-cli
-Version: 0.1.3
+Version: 0.1.5
 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
@@ -53,7 +53,7 @@ uvx feature-flow-cli install /path/to/your/repo --agent all   # or: pipx run fea
 
 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 installer lists what it wrote in `.feature-flow/installed.txt`. Commit those files (`git add --pathspec-from-file=.feature-flow/installed.txt`); until you do, the flow does not count them as uncommitted changes.
+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.
 
 Then, in your repo, in the agent:
 
@@ -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.5}/README.md

@@ -34,7 +34,7 @@ uvx feature-flow-cli install /path/to/your/repo --agent all   # or: pipx run fea
 
 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 installer lists what it wrote in `.feature-flow/installed.txt`. Commit those files (`git add --pathspec-from-file=.feature-flow/installed.txt`); until you do, the flow does not count them as uncommitted changes.
+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.
 
 Then, in your repo, in the agent:
 
@@ -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.5}/adapters/codex/feature-flow/SKILL.md

@@ -31,7 +31,7 @@ To add tickets to a plan that exists, edit it by hand following the ticket rules
 
 With a plan present, check these before `start`, and stop at the first that fails:
 
-- `git status --porcelain` is empty, apart from untracked Python bytecode (`__pycache__/`, `*.pyc`) and untracked files listed in `.feature-flow/installed.txt`: those are feature-flow's own install, so never stop for them. Suggest committing them (`git add --pathspec-from-file=.feature-flow/installed.txt && git commit -m "chore: install feature-flow"`) and carry on.
+- `git status --porcelain` is empty, apart from untracked Python bytecode (`__pycache__/`, `*.pyc`) and files listed in `.feature-flow/installed.txt` and that list itself: those are feature-flow's own install or upgrade, so never stop for them (`next` still stops if one of them was edited). Suggest committing them (`git add --pathspec-from-file=.feature-flow/installed.txt && git commit -m "chore: install feature-flow"`) and carry on.
 - `python3 scripts/flow-status.py <feature> --check` prints `OK`.
 - `.agents/flow-roles/ticket-builder.md` and `.agents/flow-roles/ticket-reviewer.md` exist. If not, say to run `uvx feature-flow-cli install . --agent codex` in this repo (or `python3 install.py <repo> --agent codex` from a feature-flow clone).
 
@@ -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.5}/feature_flow/__init__.py

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

{feature_flow_cli-0.1.3 → feature_flow_cli-0.1.5}/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.5}/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.5}/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.5}/feature_flow/git.py

@@ -1,5 +1,6 @@
 """The few git calls the conductor needs, each one an argument list, never a shell string."""
 
+import hashlib
 import subprocess
 from pathlib import Path
 
@@ -30,17 +31,30 @@ def head():
     return _git("rev-parse", "HEAD").stdout.strip()
 
 
+# the installer's record of what it wrote: the paths, and the sha256 of each as it wrote it
+INSTALLED = Path(".feature-flow") / "installed.txt"
+HASHES = Path(".feature-flow") / "installed.sha256"
+
+
+def _read_lines(path):
+    try:
+        return path.read_text(encoding="utf-8").splitlines()
+    except (OSError, UnicodeDecodeError):
+        return []
+
+
 def changes():
     """Every changed path, untracked files included, as `git status --porcelain` sees them, except
-    the untracked files feature-flow's installer wrote (an install not committed yet is not a change)
-    and untracked Python bytecode, which the flow's own Python runs leave behind."""
-    installed = set()
+    feature-flow's own install: a file still exactly as the installer wrote it, an untracked file it
+    lists without a hash (an install from before it kept hashes), and its two record files, which every
+    install rewrites; and untracked Python bytecode, which the flow's own Python runs leave behind."""
+    listed, hashes = set(), {}
     top = toplevel()
     if top is not None:
-        try:
-            installed = set((top / ".feature-flow" / "installed.txt").read_text(encoding="utf-8").splitlines())
-        except (OSError, UnicodeDecodeError):
-            pass
+        listed = set(_read_lines(top / INSTALLED))
+        for line in _read_lines(top / HASHES):
+            digest, _, name = line.partition("  ")
+            hashes[name] = digest
     entries = _git("status", "--porcelain", "-z", "-uall").stdout.split("\0")
     found = []
     i = 0
@@ -52,12 +66,26 @@ def changes():
         code, path = entry[:2], entry[3:]
         if code[0] in "RC":
             i += 1  # the rename's source path follows
-        if code == "??" and (path in installed or _bytecode(path)):
+        if path in (INSTALLED.as_posix(), HASHES.as_posix()):
+            continue
+        if path in hashes:
+            # only a worktree change: a staged version would ride along in the next commit
+            if (code[0] in " ?" and code[1] != "T" and top is not None and not (top / path).is_symlink()
+                    and _sha256(top / path) == hashes[path]):
+                continue
+        elif code == "??" and (path in listed or _bytecode(path)):
             continue
         found.append(path)
     return found
 
 
+def _sha256(path):
+    try:
+        return hashlib.sha256(path.read_bytes()).hexdigest()
+    except OSError:
+        return None
+
+
 def _bytecode(path):
     return path.endswith(".pyc") or "__pycache__/" in "/" + path
 
@@ -72,6 +100,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.5}/feature_flow/install.py

@@ -2,7 +2,8 @@
 
 usage: python3 install.py [target-repo] [--agent claude|codex|all] [--user] [--force] [--dry-run]
 copies the feature-flow skill, its roles, scripts and guides into a repo so the flow works there.
-a file that already exists and differs is kept and reported, unless --force is given.
+a file that already exists and differs is kept and reported, unless --force is given or nobody
+edited it since an earlier feature-flow install wrote it (then it is updated).
 nothing is ever deleted. CLAUDE_HOME overrides ~/.claude and AGENTS_HOME overrides ~/.agents for --user.
 
 Files are compared and written as bytes, and the two text transforms (the Codex skill header and
@@ -11,12 +12,15 @@ so the installed tree is the same byte for byte. Files are listed in byte order,
 with LC_ALL=C.
 """
 
+import hashlib
 import os
 import re
 import shutil
 import subprocess
 import sys
 
+from feature_flow.released import RELEASED
+
 # the help text
 USAGE = """\
 usage: python3 install.py [target-repo] [--agent claude|codex|all] [--user] [--force] [--dry-run]
@@ -30,7 +34,8 @@ copies the feature-flow skill, its roles, scripts and guides into a repo so the
   --agent all does both.
   scripts go to <target>/scripts/ and guides, roles and the Python package to <target>/.feature-flow/
     (always: the skill and scripts/flow.py read them from the repo)
-a file that already exists and differs is kept and reported, unless --force is given.
+a file that already exists and differs is kept and reported, unless --force is given or it is
+  still exactly what an earlier feature-flow install wrote (then it is updated).
 nothing is ever deleted. CLAUDE_HOME overrides ~/.claude and AGENTS_HOME overrides ~/.agents for --user.
 """
 
@@ -42,6 +47,16 @@ SKILLS = ("feature-flow", "architect-review", "automation-design")
 # the in-repo files an install wrote, one path per line, relative to the target. The conductor does not
 # count them as a dirty tree while they are untracked, and `git add --pathspec-from-file` commits them.
 INSTALLED = ".feature-flow/installed.txt"
+# the sha256 of each of those files as the install wrote it, `<sha256>  <path>` per line. A later install
+# replaces a file that still has its recorded bytes: nobody edited it, so it is not the user's version.
+HASHES = ".feature-flow/installed.sha256"
+# the same record for a --user install, in ~/.claude and ~/.agents, paths relative to that folder
+USER_HASHES = "feature-flow.sha256"
+
+
+def _sha256(data):
+    return hashlib.sha256(data).hexdigest()
+
 
 # an old skill that runs the ticket script (the bash one or the Python one) or ends a review with a verdict
 LEFTOVER = re.compile(rb"scripts/flow-status\.(?:sh|py)|REVIEW: PASS")
@@ -172,7 +187,14 @@ class Installer:
             package = os.path.dirname(os.path.abspath(__file__))
         self.package = package
         self.added = self.updated = self.same = self.kept = 0
-        self.written = []
+        self.written = {}
+        # each folder this installs into, with its hash record; the target's own comes first
+        self.records = [(target, HASHES)]
+        if user_level and agent in ("claude", "all"):
+            self.records.append((self.claude_dir, USER_HASHES))
+        if user_level and agent in ("codex", "all"):
+            self.records.append((self.agents_dir, USER_HASHES))
+        self.recorded = dict((root, self._read_hashes(root + "/" + record)) for root, record in self.records)
 
     def place(self, file, dest, data=None):
         """One file: add it, replace it (--force), leave it alone (same) or keep the user's version.
@@ -181,23 +203,55 @@ class Installer:
         if not os.path.exists(dest):
             self.out("  add     " + dest)
             self.added += 1
-            self.written.append(dest)
+            self.written[dest] = new
             if not self.dry:
                 os.makedirs(os.path.dirname(dest), exist_ok=True)
                 self._copy(file, dest, data)
         elif new is not None and _read(dest) == new:
             self.same += 1
-            self.written.append(dest)
-        elif self.force:
+            self.written[dest] = new
+        elif self.force or self.untouched(dest):
             self.out("  update  " + dest)
             self.updated += 1
-            self.written.append(dest)
+            self.written[dest] = new
             if not self.dry:
                 self._copy(file, dest, data)
         else:
             self.out("  kept    " + dest + " (differs from this version, use --force to replace it)")
             self.kept += 1
 
+    def locate(self, dest):
+        """The install folder dest is in and dest relative to it, or (None, None)."""
+        for root, _ in sorted(self.records, key=lambda r: -len(r[0])):
+            if dest.startswith(root + "/"):
+                return root, dest[len(root) + 1:]
+        return None, None
+
+    @staticmethod
+    def _read_hashes(path):
+        recorded = {}
+        try:
+            with open(path, encoding="utf-8") as f:
+                for line in f:
+                    digest, _, name = line.rstrip("\n").partition("  ")
+                    if name:
+                        recorded[name] = digest
+        except (OSError, UnicodeDecodeError):
+            pass
+        return recorded
+
+    def untouched(self, dest):
+        """dest still holds the bytes an earlier feature-flow install wrote there. Never a symlink or a
+        file with other hard links: writing through it would change the file it shares bytes with."""
+        if os.path.islink(dest) or os.stat(dest).st_nlink > 1:
+            return False
+        old = _read(dest)
+        if old is None:
+            return False
+        digest = _sha256(old)
+        root, rel = self.locate(dest)
+        return digest in RELEASED or self.recorded.get(root, {}).get(rel) == digest
+
     @staticmethod
     def _copy(file, dest, data):
         """cp -p: contents, mode and times."""
@@ -243,21 +297,48 @@ class Installer:
                        role_body(data if data is not None else b""))
 
     def write_installed(self):
-        """Add this run's in-repo files to the list, keeping the earlier runs' files that still exist."""
-        path = self.target + "/" + INSTALLED
+        """Add this run's in-repo files to the list, and every file's hash to its folder's record, keeping
+        the earlier runs' entries for files that still exist. True when the target's list or record changed."""
         names = set()
         try:
-            with open(path, encoding="utf-8") as old:
+            with open(self.target + "/" + INSTALLED, encoding="utf-8") as old:
                 names.update(line.strip() for line in old)
         except OSError:
             pass
-        names = set(n for n in names if n and os.path.isfile(self.target + "/" + n))
-        prefix = self.target + "/"
-        names.update(dest[len(prefix):] for dest in self.written if dest.startswith(prefix))
-        names.add(INSTALLED)
+        hashes = dict((root, dict(self.recorded[root])) for root, _ in self.records)
+        for dest, data in self.written.items():
+            root, rel = self.locate(dest)
+            if root == self.target:
+                names.add(rel)
+            if root is not None and data is not None:
+                hashes[root][rel] = _sha256(data)
+        names.update((INSTALLED, HASHES))
+        names = sorted(n for n in names
+                       if n in (INSTALLED, HASHES) or (n and os.path.isfile(self.target + "/" + n)))
+        changed = self._write(self.target + "/" + INSTALLED, "".join(n + "\n" for n in names))
+        for root, record in self.records:
+            kept = names if root == self.target else sorted(
+                n for n in hashes[root] if os.path.isfile(root + "/" + n))
+            text = "".join("%s  %s\n" % (hashes[root][n], n) for n in kept if n in hashes[root])
+            if self._write(root + "/" + record, text) and root == self.target:
+                changed = True
+        return changed
+
+    @staticmethod
+    def _write(path, text):
+        try:
+            with open(path, encoding="utf-8", newline="") as f:
+                if f.read() == text:
+                    return False
+        except (OSError, UnicodeDecodeError):
+            pass
         os.makedirs(os.path.dirname(path), exist_ok=True)
-        with open(path, "w", encoding="utf-8", newline="\n") as new:
-            new.write("".join(n + "\n" for n in sorted(names)))
+        # a new file moved into place: a link at the path is replaced, never written through
+        tmp = path + ".tmp"
+        with open(tmp, "w", encoding="utf-8", newline="\n") as f:
+            f.write(text)
+        os.replace(tmp, path)
+        return True
 
     def report_leftovers(self, dirs):
         """A skill folder this installer does not own but that drives the flow (it runs the ticket
@@ -294,8 +375,7 @@ class Installer:
         self.copy_tree(here + "/guides", self.target + "/.feature-flow/guides")
         self.copy_tree(here + "/agents", self.target + "/.feature-flow/agents")
         self.copy_tree(self.package, self.target + "/.feature-flow/feature_flow", skip=BUNDLE)
-        if not self.dry:
-            self.write_installed()
+        listed = not self.dry and self.write_installed()
 
         self.out("")
         verb = "would add" if self.dry else "added"
@@ -311,7 +391,7 @@ class Installer:
                 git = 127
             if git != 0:
                 self.out("note: %s is not a git repository, and the flow needs one" % self.target)
-            elif self.added or self.updated:
+            elif self.added or self.updated or listed:
                 git_c = ""
                 if os.path.realpath(self.target) != os.path.realpath(os.getcwd()):
                     git_c = '-C "%s" ' % self.target if " " in self.target else "-C %s " % self.target

feature_flow_cli-0.1.5/feature_flow/released.py

@@ -0,0 +1,90 @@
+"""The sha256 of every file that feature-flow-cli 0.1.0 to 0.1.4 installed (all three --agent
+choices; .feature-flow/installed.txt aside). Those releases kept no record of what they wrote, so an
+install over one of them replaces a file whose bytes are on this list: nobody edited it since. Later
+installs record their own hashes in .feature-flow/installed.sha256, so this list never grows."""
+
+RELEASED = frozenset((
+    "03111666084be6a375a0e7a42784ea8c5aed7a5a1e71e83cf2ad44fd656f758c",
+    "0385988f5d4a23daf13556a391b71bb387a25ab2b7fa8bba81b0276321028e07",
+    "0597a52bee02482ee472218b98ee6c507900df02c4f081ca795b0038eebc21bd",
+    "08419881ab53935e0a739d8ae7fc6e5cdfaeb597394bdd5c11d538a5a8086091",
+    "0b2544121889d10f5b3295700ed49d03940291243edbe6f69b5cc9eb5c2678db",
+    "0fbc776b32836e8050c07cd95d50265a415999f558c00bc7131a8b1c8f8dd893",
+    "116af2cb64dd22b061e7217a7aec96ecc2fa9193905f17154ce73542b8a3a049",
+    "158be4902bdd7a039c9fd844188545c148e289c8ca168a0a93890b9321342252",
+    "1598ed3851313756552c258447b74a7b59aca36365760ce66ecd0695a8614021",
+    "16e75f565e30ac0d4e418d813f9c399928607a26a7c84f4b983bb1e8fc4e30c1",
+    "1bdbe5d780580a9931d123decccdf5c06293b11e3481658dbfe50a8511326b85",
+    "1ee3b01e4c92e9fa9f8124a18fa89ea336562d2597325201ec0595ee431f0c09",
+    "2a3416153494015130e81876ee94f452a9c94848757cff488309ac056048887a",
+    "2a799ddadcfc4744c0837cb0a087f74556cdb88945be93ed8e508a5667c1f65a",
+    "2ae68f7df0e92d59a9e69dbd3da5103da9ab3de9b9a2ab7aec3054c410cb5ad1",
+    "2c6350ef4162ee3d208145821818c4540a99dcf4bb17915f0fdfca8a89e01bfb",
+    "2d2666ff07b3bafa9b257b013a1ef5f889b95c6657cc553f580bc74ef1232038",
+    "2f5b589e2acafc5bfefbcbf68d69bc57c028dc509d4766160762695be532aa9b",
+    "2f94fd1730077974774efa75d49741a6277e9a060041041c023ff9ff4d6129e7",
+    "38901e898c4f78b41527dede20bfca26080de99683b3e5bba0019d87046ae338",
+    "38b2d2b4c45e8c76ecd0381ef0820ca4cc516c4ac1f117b2ec99ac6ce3c2e300",
+    "39d97eb189726b3c92a399dc60e736d12b12a8252d637588c5b2a31fc2020b5f",
+    "3ff57472860da0076ac1d8a8a0537eddd29f3c63989cd5068906e5f31e7abebc",
+    "408779e5a420a8b90cf0422830660f1593efdd9c4999665a1beb0097219c2749",
+    "447f0c9f2eccb2f5313ca913d91d7fb9c336b30fa03b5d534609cd22de040703",
+    "45b62b9d60f88ef8ac8f22f585d662a3004b1dce3875f125b5a1649958511392",
+    "45cc664cb168ea82b3d04d16cd96c4392bcc21741f55749306e69fd8f2a0f68c",
+    "46ad183898dfa8d860480a123049a74c1bae56d364434ddcd51ed955fec02ca1",
+    "4bb17e6f9d9b3c77e858f061b888ab9a7bea9e3ef2cf269230c1c3d42d800a91",
+    "52c8362a637ea80835743fd568bce4c05c591d758608c5b89316391779b0166b",
+    "569951f6d447ae256d1802ab29ac287af6858e38a34879d3f4534d732097babc",
+    "5a2b9d23bbc192412b574d96cc26c09e486173c4ecf3b1d72e4f989f600bbaa9",
+    "5b4611c7d419c54d645189cf3e67630678b10d5300f7a6dbe32f75d87876dbf4",
+    "5e3895c34a7a0a95cd784c3c99beab4e102bc0a84edd76a9e7586007f55df16b",
+    "631fd0f9243caca088bf8ff37a08c1f5e75bcd42589b73a18137936259d211b7",
+    "6981a0e0de889d7296bc680f030adf3e354785424d589548257863ca6ae82835",
+    "69b13a131466af54a172e7255fade246aad706b177fa3601a843af7a873cb226",
+    "6b559ad3ea84b358417700469b7aa0aa48079fc6cddcc9fcbc2dbe312a6ccec8",
+    "71c83d16835bf50ee9e78a4a4183a101a1124d5059390e219b7509c96b70488c",
+    "71d26991a5263aade812bc9aaf90ddbee44b9c61263302fa5fbcf0093f74be6b",
+    "7530aa90149353b607560eb9c16a8ce9be75846f68fb3b71c5a2c9173d21a9b3",
+    "761710d8db4ffcb3c9c1a3d941210fa052569994bc2138e974ad44cc6ffe6ba3",
+    "774116e163377390b58dc779d008825013d4aff023a2c30332f46db53b473edd",
+    "7e42e219a8bb55cad10239ffa290a3d12912350635e8c846c105888dfada5670",
+    "800e3a2518755ca20f64ba8518943a11f60e14c8e0ec77bc7a631b7660968861",
+    "80535d95ae9fb56ddf746240e9ce6fcf6eaac401e0516ac37584b411113b7017",
+    "89522ebb5bf8891a5faab80c86715e3f610808ef588ce0bb261c5ba4bb83c115",
+    "8cfd3af473fa146477117cbc406841c542bc137516951fb801204395b444233b",
+    "9551f7f94fed0f7e1bb6f35dc6826e2eec37ae18f840ac741fbf369c0fb0bfe7",
+    "983395967e1e26bca59cf4da539481f426c3c3d02e67028076cd4d204527ac44",
+    "9892816825e0de4f5a40dbaf2506b30d1b3568d0aeadc6597c4a1fc0fd872225",
+    "9de945fd57f367ae4db739d8a63d45996912f3797450b53f3ad04f8c43f5cbd5",
+    "a0b250ed64f1d38dd9029507a8a34fdbd2bc3aa78a930c439029889f6acfd89f",
+    "a666d3eba10f164f50a5005ef70c19b1d5f33c3d43fdf926ac7a9a6815514366",
+    "a6d0a0b7ba5c5ccedf2a4d27e0b06e61b8e9563e81fdcd7617da9d4bc3506d71",
+    "a7871218beabd7928dc63729cd5141539dc291bb037baa1b9c82e8269c0e272a",
+    "aafd905d9d98879c7b6747aa544542df23f6d565cdcef47f7a207808983900d9",
+    "ae0790f7fca8c996c3844827e9904ee95b2ced3854277bd440faa59213603935",
+    "ae999c50a91a234b4943dff8731d40d30da7d04b2ba4cf13911a6ac6236d2c60",
+    "af9a25625f44a64770d6aebce5882c08dbda89b116a25d430a1b7855b8b0d9cf",
+    "b922951702a7837923fb52820930ca32fc96c13fc1f0a44650ee135828b4aa80",
+    "bc2f066334afbee46bd97168513c36ae129a098179c389c1986b0b7a47f98621",
+    "bd24f9b858bab7411493eb97a2c011d906ec56d7a7efb2c7e116cc308b0e4c55",
+    "bd7a2653a1015b9e42366c21a2dd60d1c4ea3ca07ca0afee9dddf3d36ec7741e",
+    "bda718088ea2b848b000dca2ff78e35795d4400b57ecbc0bfbccdab451245f45",
+    "c0a28ab04d02c5eff6f94ed3cdc543257919adcaaf30ec108cd6692a5319081c",
+    "c2dbc3162f8bd47a15cb0a10e6cade2cefd3f951ea8c75b175957be1cdceb174",
+    "c35e773600d4c3340b5e49eff9cc8eb2682adf7ab8a56599a2ce3fa709c10cbf",
+    "c36d2575c40b7f71abc45a58124e6a18b6f423919b9bc1ec69a1a1ff0095589d",
+    "c3a0196ebb59f110e968173ff40df3778e73e7eded2afe58deea9dc0734a9e20",
+    "cf78e2cfe6e224e3854017787634bffc3e048b48709b767b7ae953e20b707746",
+    "d3a2313826088d95dc0bc2625b0222f98223636eda3a59efeac5838f362e5b2b",
+    "e0a98bc037bfdef778a0d5d14a4d9abc2b23c4c0ea754491cba307e9c0e2169f",
+    "e8194c0aa46b169d8412837f9345c8f32378570b8474a2357c5570080093b7ce",
+    "eb346f05cd6359292749a0915fe8b3412b3f99a493a21b294e763a3da0a80852",
+    "ee7c8f100721d6ad36ad653a0b82c11eab02217f015344bc707c158f32a08c93",
+    "f05d890a79379ee8b89bcef86361acc93ca6b3f7b277500126d058243a60f9f2",
+    "f335488f1e89e63bf2f0588a71feccbfece080ef9dcb5fac15f89868576434f0",
+    "f34612dfc665fccc1a47f041d096877fa8a4d9c00aad832646d9ab6408305bba",
+    "f6352f7ca92571045aa0c7d8ffbe2708f8315c6bd852433e7f32fc8b4af65fdb",
+    "f714136a9c949bcb23b67755a3072d0946ca5a6c0a484f6a42f80c23964e5758",
+    "f799e5372b598cda13cf2b2d8b888c1703fed71a3af2ec2aa802b838a7de39ba",
+    "fded1be6a891c062ad84d14960b47daa0d2424d87ade33922d7f9acfe2b64600",
+))

{feature_flow_cli-0.1.3 → feature_flow_cli-0.1.5}/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.5/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.5/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.5
 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
@@ -53,7 +53,7 @@ uvx feature-flow-cli install /path/to/your/repo --agent all   # or: pipx run fea
 
 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 installer lists what it wrote in `.feature-flow/installed.txt`. Commit those files (`git add --pathspec-from-file=.feature-flow/installed.txt`); until you do, the flow does not count them as uncommitted changes.
+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.
 
 Then, in your repo, in the agent:
 
@@ -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.5}/feature_flow_cli.egg-info/SOURCES.txt

@@ -21,8 +21,10 @@ feature_flow/gate.py
 feature_flow/git.py
 feature_flow/install.py
 feature_flow/prompts.py
+feature_flow/released.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.5}/guides/build.md

@@ -12,7 +12,7 @@ Follow the repo's documented ticket location if it has one. Otherwise they are i
 
 ## Step 2: Pre-flight
 
-Run `git status --porcelain`. Untracked files listed in `.feature-flow/installed.txt` are feature-flow's own install and do not count, and neither does untracked Python bytecode (`__pycache__/`, `*.pyc`).
+Run `git status --porcelain`. Files listed in `.feature-flow/installed.txt`, and that list itself, are feature-flow's own install and do not count, and neither does untracked Python bytecode (`__pycache__/`, `*.pyc`).
 
 - Clean: continue.
 - Dirty, manual: show the files and offer to commit, stash, or continue anyway.

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

@@ -31,7 +31,7 @@ To add tickets to a plan that exists, edit it by hand following the ticket rules
 
 With a plan present, check these before `start`, and stop at the first that fails:
 
-- `git status --porcelain` is empty, apart from untracked Python bytecode (`__pycache__/`, `*.pyc`) and untracked files listed in `.feature-flow/installed.txt`: those are feature-flow's own install, so never stop for them. Suggest committing them (`git add --pathspec-from-file=.feature-flow/installed.txt && git commit -m "chore: install feature-flow"`) and carry on.
+- `git status --porcelain` is empty, apart from untracked Python bytecode (`__pycache__/`, `*.pyc`) and files listed in `.feature-flow/installed.txt` and that list itself: those are feature-flow's own install or upgrade, so never stop for them (`next` still stops if one of them was edited). Suggest committing them (`git add --pathspec-from-file=.feature-flow/installed.txt && git commit -m "chore: install feature-flow"`) and carry on.
 - `python3 scripts/flow-status.py <feature> --check` prints `OK`.
 - `ticket-builder.md` and `ticket-reviewer.md` are in `.claude/agents/`, `~/.claude/agents/`, or `$CLAUDE_HOME/agents/` when `CLAUDE_HOME` is set. If not, say to run `uvx feature-flow-cli install .` in this repo (or `python3 install.py <repo>` from a feature-flow clone).
 
@@ -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