feat(store,api): cancel a feature created in error — the second terminal edge (v0.21.0) (#53)

There was no in-board way to cancel a feature created in error (bad decomposition,
duplicate, scope cut): DELETE /features/{fid} → 405, and no store method. The only
escape was reaching past the board into `br` directly, which bypasses the board cache
and risks board ↔ JSONL desync.

A cancel is a SECOND terminal edge, so it's modeled deliberately to preserve the
one-Done-edge invariant rather than as a raw delete:
  • store.cancel_feature(fid, reason) → tag `cancelled` + clear assignee, then
    `br close -r "cancelled: …"` (audit-preserving — bead + reason survive; not a
    `br delete` tombstone)
  • board_state projects a closed+`cancelled` bead as a distinct `cancelled` state,
    NOT `done` — so the merge/CI reconcilers (which only touch in_review) and the
    loop-retro (which mines done/blocked) never mistake it for shipped/regressed work
  • POST /features/{fid}/cancel (mirrors the block/unblock transition style; reason
    optional)

Decision (maintainer was away): chose CANCEL-with-audit (`br close -r`) over a hard
delete — lower-risk, reversible-by-reopen, keeps the audit trail. Easy to swap to a
hard delete later if the intent turns out to be tombstoning. Cancelled features drop
out of the active Kanban (the point of a cancel); a `cancelled` list section rides
with #26.

Closes #47

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: mabry1985

api.py

@@ -222,4 +222,12 @@ async def _block(fid: str, body: dict = Body(...)):
     async def _unblock(fid: str):
         return _guard(lambda: store().clear_blocked(fid))
 
+    @router.post("/features/{fid}/cancel")
+    async def _cancel(fid: str, body: dict = Body(default={})):
+        """Cancel a feature created in error — the second terminal edge (#47). Closes
+        the bead with an audit reason and tags it `cancelled` (a distinct state, not
+        `done`), so a bad decomposition/duplicate leaves the board cleanly instead of
+        being deleted out-of-band (which desyncs the board ↔ JSONL)."""
+        return _guard(lambda: store().cancel_feature(fid, str((body or {}).get("reason", ""))))
+
     return router

protoagent.plugin.yaml

@@ -1,6 +1,6 @@
 id: project_board
 name: Project Board (coding orchestration)
-version: 0.20.1
+version: 0.21.0
 description: >-
   A board-driven coding-orchestration plugin: a lean 6-state board (backlog → ready
   → in_progress → in_review → done, + a blocked flag) backed by **beads** (`br`), an

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "project-board"
-version = "0.20.1"
+version = "0.21.0"
 description = "Board-driven coding-orchestration plugin for protoAgent (beads board + ACP spawn loop + planning layer + console view)."
 requires-python = ">=3.11"
 

store.py

@@ -47,6 +47,11 @@
 LABEL_READY = "ready"
 LABEL_IN_REVIEW = "in-review"
 LABEL_BLOCKED = "blocked"
+# A SECOND terminal edge (#47): a feature closed because it was created in error
+# (bad decomposition, duplicate, scope cut) — closed like `done`, but tagged so the
+# projection shows a distinct `cancelled` state and reconcilers/retro never mistake it
+# for shipped work. Preserves the one-Done-edge invariant (only record_merge → `done`).
+LABEL_CANCELLED = "cancelled"
 # A feature others build *on*: dependents gate on its MERGE, never its review (vs a
 # non-foundation blocker, which can release dependents at in_review under dep_gate:
 # review). Inert under the default dep_gate: merge (then every blocker gates on merge).
@@ -328,6 +333,24 @@ def record_merge(self, *, pr_url: str) -> dict | None:
             self._run("close", f["id"], "-r", f"merged: {pr_url}")
         return self.get_feature(f["id"])
 
+    # ── the second terminal edge: cancel (not merge) ──────────────────────────
+    def cancel_feature(self, fid: str, reason: str = "") -> dict:
+        """Cancel a feature created in error (bad decomposition, duplicate, scope cut).
+
+        Modeled DELIBERATELY as a second terminal edge so it doesn't break the
+        one-Done-edge invariant: it tags the bead `cancelled` and closes it with an
+        auditable reason (`br close -r`). The `cancelled` label makes the projection show
+        a distinct `cancelled` state — NOT `done` — so the merge/CI reconcilers (which
+        only touch `in_review`) and the loop-retro (which mines done/blocked) never
+        mistake a cancel for shipped or regressed work. Audit-preserving (the bead + its
+        history survive), vs a hard `br delete` tombstone. Clears the assignee so a
+        revived id could be re-claimed. Idempotent-ish: re-cancelling a cancelled feature
+        just re-closes it."""
+        self._require(fid)
+        self._run("update", fid, "--add-label", LABEL_CANCELLED, "--assignee", "")
+        self._run("close", fid, "-r", f"cancelled: {reason}" if reason else "cancelled")
+        return self.get_feature(fid)
+
     # ── Blocked flag (not a lane) ─────────────────────────────────────────────
     def flag_blocked(self, fid: str, reason: str) -> dict:
         self._require(fid)
@@ -512,7 +535,9 @@ def board_state(bead: dict) -> str:
         labels = set(bead.get("labels") or [])
         status = bead.get("status")
         if status == "closed":
-            return "done"
+            # A closed bead is `done` UNLESS it was cancelled (the second terminal edge):
+            # a cancel keeps it closed + auditable but distinct from shipped work (#47).
+            return "cancelled" if LABEL_CANCELLED in labels else "done"
         if LABEL_BLOCKED in labels:
             return "blocked"
         if status == "in_progress":
@@ -552,6 +577,7 @@ def _project(self, bead: dict) -> dict:
             "pr_url": bead.get("external_ref", ""),
             "assignee": bead.get("assignee", ""),
             "blocked": LABEL_BLOCKED in labels,
+            "cancelled": LABEL_CANCELLED in labels,
             "foundation": LABEL_FOUNDATION in labels,
             "difficulty": diff,
             "attempts": attempts,

tests/test_api.py

@@ -71,6 +71,9 @@ def flag_blocked(self, fid, reason):
     def clear_blocked(self, fid):
         return self._rec("clear_blocked", fid)
 
+    def cancel_feature(self, fid, reason=""):
+        return self._rec("cancel_feature", fid, reason)
+
     def bounce_ci_fail(self, fid, reason):
         return self._rec("bounce_ci_fail", fid, reason)
 
@@ -153,6 +156,20 @@ def test_ready_gate_rejection_surfaces_as_400(monkeypatch):
     assert r.status_code == 400 and "Ready gate" in r.json()["detail"]
 
 
+def test_cancel_route_calls_cancel_feature_with_reason(monkeypatch):
+    """POST /features/{fid}/cancel — the second terminal edge (#47). Carries the
+    optional reason through; works with no body too."""
+    store = FakeStore()
+    c = _client(monkeypatch, store)
+    r = c.post("/api/plugins/project_board/features/bd-7/cancel", json={"reason": "duplicate"})
+    assert r.status_code == 200
+    assert ("cancel_feature", ("bd-7", "duplicate"), {}) in store.calls
+    # No body → cancels with an empty reason (still a valid request, not a 422).
+    r2 = c.post("/api/plugins/project_board/features/bd-8/cancel")
+    assert r2.status_code == 200
+    assert ("cancel_feature", ("bd-8", ""), {}) in store.calls
+
+
 # ── the single Done edge: the merge webhook ─────────────────────────────────────
 
 

tests/test_store.py

@@ -45,10 +45,13 @@ def cmds(self, name):
         ({"status": "in_progress", "labels": []}, "in_progress"),
         ({"status": "in_progress", "labels": ["in-review"]}, "in_review"),
         ({"status": "closed", "labels": []}, "done"),
+        ({"status": "closed", "labels": ["cancelled"]}, "cancelled"),  # the second terminal edge (#47)
         ({"status": "deferred", "labels": []}, "backlog"),
         ({"status": "open", "labels": ["blocked"]}, "blocked"),
         # precedence: closed beats a stray blocked label; blocked beats in-review.
         ({"status": "closed", "labels": ["blocked", "ready"]}, "done"),
+        # a cancelled+closed bead is `cancelled`, not `done`, even with other labels.
+        ({"status": "closed", "labels": ["cancelled", "blocked"]}, "cancelled"),
         ({"status": "in_progress", "labels": ["blocked", "in-review"]}, "blocked"),
     ],
 )
@@ -226,6 +229,30 @@ def test_mark_ready_rejects_an_underspecced_feature(make_board, monkeypatch, mis
     assert br.cmds("update") == []  # nothing mutated on a rejected gate
 
 
+# ── cancel_feature: the second terminal edge (#47) ──────────────────────────────
+
+
+def test_cancel_feature_tags_cancelled_and_closes_with_reason(make_board, monkeypatch):
+    """Tag `cancelled` + clear the assignee, then close with an audit reason — so the
+    projection reads `cancelled` (distinct from `done`), audit-preserved (not deleted)."""
+    br = Br()
+    b = make_board(br)
+    monkeypatch.setattr(b, "get_feature", lambda fid: {"id": fid, "board_state": "cancelled", "cancelled": True})
+    f = b.cancel_feature("bd-9", "duplicate")
+    update = next(c for c in br.calls if c[0] == "update")
+    assert "--add-label" in update and "cancelled" in update and "--assignee" in update
+    close = next(c for c in br.calls if c[0] == "close")
+    assert close[:2] == ("close", "bd-9") and "cancelled: duplicate" in close
+    assert f["board_state"] == "cancelled" and f["cancelled"] is True
+
+
+def test_cancel_feature_unknown_id_raises(make_board, monkeypatch):
+    b = make_board(Br())
+    monkeypatch.setattr(b, "get_feature", lambda fid: None)
+    with pytest.raises(BoardError, match="unknown feature"):
+        b.cancel_feature("nope")
+
+
 def test_mark_ready_rejects_a_feature_already_past_backlog(make_board, monkeypatch):
     b = make_board(Br())
     monkeypatch.setattr(b, "get_feature", lambda fid: {"id": fid, "board_state": "in_progress"})