feat(store,api): hard-delete a feature alongside cancel — the tombstone edge (v0.23.0) (#55)

Follow-up to #47: that shipped cancel-with-audit (close + `cancelled` lane); this adds
the hard-delete sibling the issue's "and/or" also called for, so the operator chooses
per-case instead of the maintainer baking one in.

  • store.delete_feature(fid, reason) → `br delete --reason "deleted: …"` — a tombstone
    in the JSONL (recoverable), run THROUGH the board so board ↔ JSONL stay in step
    (vs the raw `br` reach-around the issue warned desyncs the board). Refuses via `br`'s
    non-zero exit when the feature has dependents (deleting would orphan them) — cancel
    or re-point first. Returns the pre-delete snapshot for the API echo.
  • DELETE /features/{fid} (the route the issue proposed; reason optional, body or none).

cancel stays the recommended default (visible, reopenable audit lane); delete is for a
feature that should leave no trace. Verified `br delete` tombstones + the dependent
guard against real `br` 0.1.23; unit-tested both methods + the route.

Ref #47

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

Author: mabry1985

api.py

@@ -230,4 +230,12 @@ async def _cancel(fid: str, body: dict = Body(default={})):
         being deleted out-of-band (which desyncs the board ↔ JSONL)."""
         return _guard(lambda: store().cancel_feature(fid, str((body or {}).get("reason", ""))))
 
+    @router.delete("/features/{fid}")
+    async def _delete(fid: str, body: dict = Body(default={})):
+        """Hard-delete a feature created in error — a `br` tombstone (the harder sibling
+        of POST …/cancel). Goes through the board so board ↔ JSONL stay consistent;
+        refuses (400) if the feature has dependents (deleting would orphan them). Prefer
+        cancel to keep a visible, reopenable audit lane; use delete to leave no trace."""
+        return _guard(lambda: store().delete_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.22.0
+version: 0.23.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.22.0"
+version = "0.23.0"
 description = "Board-driven coding-orchestration plugin for protoAgent (beads board + ACP spawn loop + planning layer + console view)."
 requires-python = ">=3.11"
 

store.py

@@ -351,6 +351,19 @@ def cancel_feature(self, fid: str, reason: str = "") -> dict:
         self._run("close", fid, "-r", f"cancelled: {reason}" if reason else "cancelled")
         return self.get_feature(fid)
 
+    def delete_feature(self, fid: str, reason: str = "") -> dict:
+        """Hard-delete a feature (a `br` tombstone) — the harder sibling of
+        ``cancel_feature``. For a feature that should leave NO trace on the board (a pure
+        mistake / duplicate), vs a cancel which keeps a visible, reopenable `cancelled`
+        lane. Still goes THROUGH the board (not a raw `br` reach-around) so board ↔ JSONL
+        stay in step; `br delete` tombstones in the JSONL (recoverable) rather than
+        nuking history. Refuses (BoardError, via `br`'s non-zero exit) when the feature
+        has dependents — deleting it would orphan them; cancel or re-point them first.
+        Returns the deleted feature's last projection (the API echo)."""
+        f = self._require(fid)
+        self._run("delete", fid, "--reason", f"deleted: {reason}" if reason else "deleted")
+        return f
+
     # ── Blocked flag (not a lane) ─────────────────────────────────────────────
     def flag_blocked(self, fid: str, reason: str) -> dict:
         self._require(fid)

tests/test_api.py

@@ -74,6 +74,9 @@ def clear_blocked(self, fid):
     def cancel_feature(self, fid, reason=""):
         return self._rec("cancel_feature", fid, reason)
 
+    def delete_feature(self, fid, reason=""):
+        return self._rec("delete_feature", fid, reason)
+
     def bounce_ci_fail(self, fid, reason):
         return self._rec("bounce_ci_fail", fid, reason)
 
@@ -170,6 +173,19 @@ def test_cancel_route_calls_cancel_feature_with_reason(monkeypatch):
     assert ("cancel_feature", ("bd-8", ""), {}) in store.calls
 
 
+def test_delete_route_calls_delete_feature(monkeypatch):
+    """DELETE /features/{fid} — the hard-delete sibling of cancel (#47). Carries an
+    optional reason; works with no body too."""
+    store = FakeStore()
+    c = _client(monkeypatch, store)
+    r = c.request("DELETE", "/api/plugins/project_board/features/bd-7", json={"reason": "mistake"})
+    assert r.status_code == 200
+    assert ("delete_feature", ("bd-7", "mistake"), {}) in store.calls
+    r2 = c.delete("/api/plugins/project_board/features/bd-8")
+    assert r2.status_code == 200
+    assert ("delete_feature", ("bd-8", ""), {}) in store.calls
+
+
 # ── the single Done edge: the merge webhook ─────────────────────────────────────
 
 

tests/test_store.py

@@ -253,6 +253,26 @@ def test_cancel_feature_unknown_id_raises(make_board, monkeypatch):
         b.cancel_feature("nope")
 
 
+def test_delete_feature_tombstones_with_reason(make_board, monkeypatch):
+    """The harder sibling of cancel: `br delete` (tombstone) with an audit reason, run
+    THROUGH the board so board↔JSONL stay in step. Returns the pre-delete snapshot."""
+    br = Br()
+    b = make_board(br)
+    snapshot = {"id": "bd-9", "board_state": "backlog", "title": "oops"}
+    monkeypatch.setattr(b, "get_feature", lambda fid: snapshot)
+    f = b.delete_feature("bd-9", "duplicate")
+    delete = next(c for c in br.calls if c[0] == "delete")
+    assert delete[:2] == ("delete", "bd-9") and "--reason" in delete and "deleted: duplicate" in delete
+    assert f == snapshot  # the API echoes what was removed
+
+
+def test_delete_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.delete_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"})