test(P13.3): propose backend tests — 19 tests covering CRUD, accept/reject/reopen, code generation, feat_task_id protection, edit restrictions, permissions

tests/conftest.py

@@ -26,6 +26,10 @@ try:
     import app.models.apikey  # noqa: F401
 except ImportError:
     pass
+try:
+    import app.models.webhook  # noqa: F401
+except ImportError:
+    pass
 
 TEST_DATABASE_URL = "sqlite://"  # in-memory
 

tests/test_propose.py

@@ -0,0 +1,559 @@
+"""P13.3 — Propose backend tests.
+
+Covers:
+- CRUD: create, list, get, update
+- propose_code per-project incrementing
+- accept → auto-generate feature story task + feat_task_id
+- accept with non-open milestone → fail
+- reject → status change
+- rejected → reopen back to open
+- feat_task_id cannot be set manually
+- edit restrictions (only open proposes editable)
+- permission checks for accept/reject/reopen
+"""
+import pytest
+from app.models.milestone import MilestoneStatus
+from app.models.task import TaskStatus
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _propose_url(project_id: int, propose_id: int | None = None) -> str:
+    base = f"/projects/{project_id}/proposes"
+    return f"{base}/{propose_id}" if propose_id else base
+
+
+# ===========================================================================
+# CRUD
+# ===========================================================================
+
+class TestProposeCRUD:
+    """Basic create / list / get / update."""
+
+    def test_create_propose(
+        self, client, db, make_user, make_project, seed_roles_and_permissions, make_member, auth_header,
+    ):
+        admin_role, mgr_role, dev_role = seed_roles_and_permissions
+        user = make_user()
+        project = make_project(owner_id=user.id, project_code="PROJ")
+        make_member(project.id, user.id, dev_role.id)
+
+        resp = client.post(
+            _propose_url(project.id),
+            json={"title": "New Feature Idea", "description": "Some details"},
+            headers=auth_header(user),
+        )
+        assert resp.status_code == 201
+        data = resp.json()
+        assert data["title"] == "New Feature Idea"
+        assert data["status"] == "open"
+        assert data["propose_code"].startswith("PROJ:P")
+        assert data["feat_task_id"] is None
+
+    def test_list_proposes(
+        self, client, db, make_user, make_project, seed_roles_and_permissions, make_member, auth_header,
+    ):
+        admin_role, mgr_role, dev_role = seed_roles_and_permissions
+        user = make_user()
+        project = make_project(owner_id=user.id)
+        make_member(project.id, user.id, dev_role.id)
+
+        # Create two proposes
+        client.post(_propose_url(project.id), json={"title": "P1"}, headers=auth_header(user))
+        client.post(_propose_url(project.id), json={"title": "P2"}, headers=auth_header(user))
+
+        resp = client.get(_propose_url(project.id), headers=auth_header(user))
+        assert resp.status_code == 200
+        assert len(resp.json()) == 2
+
+    def test_get_propose(
+        self, client, db, make_user, make_project, seed_roles_and_permissions, make_member, auth_header,
+    ):
+        admin_role, mgr_role, dev_role = seed_roles_and_permissions
+        user = make_user()
+        project = make_project(owner_id=user.id)
+        make_member(project.id, user.id, dev_role.id)
+
+        create_resp = client.post(_propose_url(project.id), json={"title": "P1"}, headers=auth_header(user))
+        propose_id = create_resp.json()["id"]
+
+        resp = client.get(_propose_url(project.id, propose_id), headers=auth_header(user))
+        assert resp.status_code == 200
+        assert resp.json()["title"] == "P1"
+
+    def test_update_propose_open(
+        self, client, db, make_user, make_project, seed_roles_and_permissions, make_member, auth_header,
+    ):
+        admin_role, mgr_role, dev_role = seed_roles_and_permissions
+        user = make_user()
+        project = make_project(owner_id=user.id)
+        make_member(project.id, user.id, dev_role.id)
+
+        create_resp = client.post(_propose_url(project.id), json={"title": "Old"}, headers=auth_header(user))
+        propose_id = create_resp.json()["id"]
+
+        resp = client.patch(
+            _propose_url(project.id, propose_id),
+            json={"title": "New Title", "description": "Updated"},
+            headers=auth_header(user),
+        )
+        assert resp.status_code == 200
+        assert resp.json()["title"] == "New Title"
+        assert resp.json()["description"] == "Updated"
+
+
+# ===========================================================================
+# Propose Code
+# ===========================================================================
+
+class TestProposeCode:
+    """P1.4 — propose_code increments per project independently."""
+
+    def test_code_increments_per_project(
+        self, client, db, make_user, make_project, seed_roles_and_permissions, make_member, auth_header,
+    ):
+        admin_role, mgr_role, dev_role = seed_roles_and_permissions
+        user = make_user()
+        proj_a = make_project(owner_id=user.id, project_code="ALPHA")
+        proj_b = make_project(owner_id=user.id, project_code="BETA")
+        make_member(proj_a.id, user.id, dev_role.id)
+        make_member(proj_b.id, user.id, dev_role.id)
+
+        # Create 2 in ALPHA
+        r1 = client.post(_propose_url(proj_a.id), json={"title": "A1"}, headers=auth_header(user))
+        r2 = client.post(_propose_url(proj_a.id), json={"title": "A2"}, headers=auth_header(user))
+
+        # Create 1 in BETA
+        r3 = client.post(_propose_url(proj_b.id), json={"title": "B1"}, headers=auth_header(user))
+
+        code1 = r1.json()["propose_code"]
+        code2 = r2.json()["propose_code"]
+        code3 = r3.json()["propose_code"]
+
+        assert code1.startswith("ALPHA:P")
+        assert code2.startswith("ALPHA:P")
+        assert code3.startswith("BETA:P")
+        # They should be distinct
+        assert code1 != code2
+
+
+# ===========================================================================
+# Accept
+# ===========================================================================
+
+class TestAccept:
+    """P6.2 — accept propose → create feature story task."""
+
+    def test_accept_success(
+        self, client, db, make_user, make_project, make_milestone, seed_roles_and_permissions, make_member, auth_header,
+    ):
+        admin_role, mgr_role, dev_role = seed_roles_and_permissions
+        mgr = make_user()
+        project = make_project(owner_id=mgr.id)
+        make_member(project.id, mgr.id, mgr_role.id)
+
+        ms = make_milestone(project.id, mgr.id, status=MilestoneStatus.OPEN)
+
+        create_resp = client.post(
+            _propose_url(project.id),
+            json={"title": "Cool Feature", "description": "Do something cool"},
+            headers=auth_header(mgr),
+        )
+        propose_id = create_resp.json()["id"]
+
+        resp = client.post(
+            _propose_url(project.id, propose_id) + "/accept",
+            json={"milestone_id": ms.id},
+            headers=auth_header(mgr),
+        )
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["status"] == "accepted"
+        assert data["feat_task_id"] is not None
+
+        # Verify the generated task exists
+        from app.models.task import Task
+        task = db.query(Task).filter(Task.id == int(data["feat_task_id"])).first()
+        assert task is not None
+        assert task.title == "Cool Feature"
+        assert task.description == "Do something cool"
+        assert task.task_type == "story"
+        assert task.task_subtype == "feature"
+        task_status = task.status.value if hasattr(task.status, "value") else task.status
+        assert task_status == "pending"
+        assert task.milestone_id == ms.id
+
+    def test_accept_non_open_milestone_fails(
+        self, client, db, make_user, make_project, make_milestone, seed_roles_and_permissions, make_member, auth_header,
+    ):
+        admin_role, mgr_role, dev_role = seed_roles_and_permissions
+        mgr = make_user()
+        project = make_project(owner_id=mgr.id)
+        make_member(project.id, mgr.id, mgr_role.id)
+
+        ms = make_milestone(project.id, mgr.id, status=MilestoneStatus.FREEZE)
+
+        create_resp = client.post(
+            _propose_url(project.id),
+            json={"title": "Feature X"},
+            headers=auth_header(mgr),
+        )
+        propose_id = create_resp.json()["id"]
+
+        resp = client.post(
+            _propose_url(project.id, propose_id) + "/accept",
+            json={"milestone_id": ms.id},
+            headers=auth_header(mgr),
+        )
+        assert resp.status_code == 400
+        assert "open" in resp.json()["detail"].lower()
+
+    def test_accept_already_accepted_fails(
+        self, client, db, make_user, make_project, make_milestone, seed_roles_and_permissions, make_member, auth_header,
+    ):
+        admin_role, mgr_role, dev_role = seed_roles_and_permissions
+        mgr = make_user()
+        project = make_project(owner_id=mgr.id)
+        make_member(project.id, mgr.id, mgr_role.id)
+
+        ms = make_milestone(project.id, mgr.id, status=MilestoneStatus.OPEN)
+
+        create_resp = client.post(
+            _propose_url(project.id), json={"title": "F"}, headers=auth_header(mgr),
+        )
+        propose_id = create_resp.json()["id"]
+
+        # First accept
+        client.post(
+            _propose_url(project.id, propose_id) + "/accept",
+            json={"milestone_id": ms.id},
+            headers=auth_header(mgr),
+        )
+
+        # Second accept should fail
+        resp = client.post(
+            _propose_url(project.id, propose_id) + "/accept",
+            json={"milestone_id": ms.id},
+            headers=auth_header(mgr),
+        )
+        assert resp.status_code == 400
+
+    def test_accept_auto_fills_feat_task_id(
+        self, client, db, make_user, make_project, make_milestone, seed_roles_and_permissions, make_member, auth_header,
+    ):
+        admin_role, mgr_role, dev_role = seed_roles_and_permissions
+        mgr = make_user()
+        project = make_project(owner_id=mgr.id)
+        make_member(project.id, mgr.id, mgr_role.id)
+
+        ms = make_milestone(project.id, mgr.id, status=MilestoneStatus.OPEN)
+
+        create_resp = client.post(
+            _propose_url(project.id), json={"title": "F"}, headers=auth_header(mgr),
+        )
+        propose_id = create_resp.json()["id"]
+
+        resp = client.post(
+            _propose_url(project.id, propose_id) + "/accept",
+            json={"milestone_id": ms.id},
+            headers=auth_header(mgr),
+        )
+        data = resp.json()
+        assert data["feat_task_id"] is not None
+
+        # Re-fetch to confirm persistence
+        get_resp = client.get(_propose_url(project.id, propose_id), headers=auth_header(mgr))
+        assert get_resp.json()["feat_task_id"] == data["feat_task_id"]
+
+    def test_accept_no_permission_fails(
+        self, client, db, make_user, make_project, make_milestone, seed_roles_and_permissions, make_member, auth_header,
+    ):
+        """dev role should not have propose.accept permission."""
+        admin_role, mgr_role, dev_role = seed_roles_and_permissions
+        owner = make_user()
+        dev_user = make_user()
+        project = make_project(owner_id=owner.id)
+        make_member(project.id, owner.id, mgr_role.id)
+        make_member(project.id, dev_user.id, dev_role.id)
+
+        ms = make_milestone(project.id, owner.id, status=MilestoneStatus.OPEN)
+
+        # Dev creates the propose
+        create_resp = client.post(
+            _propose_url(project.id), json={"title": "F"}, headers=auth_header(dev_user),
+        )
+        propose_id = create_resp.json()["id"]
+
+        # Dev tries to accept — should fail
+        resp = client.post(
+            _propose_url(project.id, propose_id) + "/accept",
+            json={"milestone_id": ms.id},
+            headers=auth_header(dev_user),
+        )
+        assert resp.status_code == 403
+
+
+# ===========================================================================
+# Reject
+# ===========================================================================
+
+class TestReject:
+    """P6.3 — reject propose."""
+
+    def test_reject_success(
+        self, client, db, make_user, make_project, seed_roles_and_permissions, make_member, auth_header,
+    ):
+        admin_role, mgr_role, dev_role = seed_roles_and_permissions
+        mgr = make_user()
+        project = make_project(owner_id=mgr.id)
+        make_member(project.id, mgr.id, mgr_role.id)
+
+        create_resp = client.post(
+            _propose_url(project.id), json={"title": "F"}, headers=auth_header(mgr),
+        )
+        propose_id = create_resp.json()["id"]
+
+        resp = client.post(
+            _propose_url(project.id, propose_id) + "/reject",
+            json={"reason": "Not needed"},
+            headers=auth_header(mgr),
+        )
+        assert resp.status_code == 200
+        assert resp.json()["status"] == "rejected"
+
+    def test_reject_non_open_fails(
+        self, client, db, make_user, make_project, make_milestone, seed_roles_and_permissions, make_member, auth_header,
+    ):
+        admin_role, mgr_role, dev_role = seed_roles_and_permissions
+        mgr = make_user()
+        project = make_project(owner_id=mgr.id)
+        make_member(project.id, mgr.id, mgr_role.id)
+
+        ms = make_milestone(project.id, mgr.id, status=MilestoneStatus.OPEN)
+
+        create_resp = client.post(
+            _propose_url(project.id), json={"title": "F"}, headers=auth_header(mgr),
+        )
+        propose_id = create_resp.json()["id"]
+
+        # Accept first
+        client.post(
+            _propose_url(project.id, propose_id) + "/accept",
+            json={"milestone_id": ms.id},
+            headers=auth_header(mgr),
+        )
+
+        # Now reject should fail
+        resp = client.post(
+            _propose_url(project.id, propose_id) + "/reject",
+            json={"reason": "Changed mind"},
+            headers=auth_header(mgr),
+        )
+        assert resp.status_code == 400
+
+    def test_reject_no_permission_fails(
+        self, client, db, make_user, make_project, seed_roles_and_permissions, make_member, auth_header,
+    ):
+        admin_role, mgr_role, dev_role = seed_roles_and_permissions
+        owner = make_user()
+        dev_user = make_user()
+        project = make_project(owner_id=owner.id)
+        make_member(project.id, owner.id, mgr_role.id)
+        make_member(project.id, dev_user.id, dev_role.id)
+
+        create_resp = client.post(
+            _propose_url(project.id), json={"title": "F"}, headers=auth_header(dev_user),
+        )
+        propose_id = create_resp.json()["id"]
+
+        resp = client.post(
+            _propose_url(project.id, propose_id) + "/reject",
+            json={"reason": "nah"},
+            headers=auth_header(dev_user),
+        )
+        assert resp.status_code == 403
+
+
+# ===========================================================================
+# Reopen
+# ===========================================================================
+
+class TestReopen:
+    """P6.4 — reopen rejected propose."""
+
+    def test_reopen_success(
+        self, client, db, make_user, make_project, seed_roles_and_permissions, make_member, auth_header,
+    ):
+        admin_role, mgr_role, dev_role = seed_roles_and_permissions
+        mgr = make_user()
+        project = make_project(owner_id=mgr.id)
+        make_member(project.id, mgr.id, mgr_role.id)
+
+        create_resp = client.post(
+            _propose_url(project.id), json={"title": "F"}, headers=auth_header(mgr),
+        )
+        propose_id = create_resp.json()["id"]
+
+        # Reject first
+        client.post(
+            _propose_url(project.id, propose_id) + "/reject",
+            json={"reason": "wait"},
+            headers=auth_header(mgr),
+        )
+
+        # Reopen
+        resp = client.post(
+            _propose_url(project.id, propose_id) + "/reopen",
+            headers=auth_header(mgr),
+        )
+        assert resp.status_code == 200
+        assert resp.json()["status"] == "open"
+
+    def test_reopen_non_rejected_fails(
+        self, client, db, make_user, make_project, seed_roles_and_permissions, make_member, auth_header,
+    ):
+        admin_role, mgr_role, dev_role = seed_roles_and_permissions
+        mgr = make_user()
+        project = make_project(owner_id=mgr.id)
+        make_member(project.id, mgr.id, mgr_role.id)
+
+        create_resp = client.post(
+            _propose_url(project.id), json={"title": "F"}, headers=auth_header(mgr),
+        )
+        propose_id = create_resp.json()["id"]
+
+        # Try reopen on open propose — should fail
+        resp = client.post(
+            _propose_url(project.id, propose_id) + "/reopen",
+            headers=auth_header(mgr),
+        )
+        assert resp.status_code == 400
+
+    def test_reopen_no_permission_fails(
+        self, client, db, make_user, make_project, seed_roles_and_permissions, make_member, auth_header,
+    ):
+        admin_role, mgr_role, dev_role = seed_roles_and_permissions
+        owner = make_user()
+        dev_user = make_user()
+        project = make_project(owner_id=owner.id)
+        make_member(project.id, owner.id, mgr_role.id)
+        make_member(project.id, dev_user.id, dev_role.id)
+
+        create_resp = client.post(
+            _propose_url(project.id), json={"title": "F"}, headers=auth_header(dev_user),
+        )
+        propose_id = create_resp.json()["id"]
+
+        # Owner rejects
+        client.post(
+            _propose_url(project.id, propose_id) + "/reject",
+            json={"reason": "nah"},
+            headers=auth_header(owner),
+        )
+
+        # Dev tries to reopen — should fail
+        resp = client.post(
+            _propose_url(project.id, propose_id) + "/reopen",
+            headers=auth_header(dev_user),
+        )
+        assert resp.status_code == 403
+
+
+# ===========================================================================
+# feat_task_id protection
+# ===========================================================================
+
+class TestFeatTaskIdProtection:
+    """P6.5 — feat_task_id is server-side only, cannot be set by client."""
+
+    def test_update_cannot_set_feat_task_id(
+        self, client, db, make_user, make_project, seed_roles_and_permissions, make_member, auth_header,
+    ):
+        admin_role, mgr_role, dev_role = seed_roles_and_permissions
+        user = make_user()
+        project = make_project(owner_id=user.id)
+        make_member(project.id, user.id, dev_role.id)
+
+        create_resp = client.post(
+            _propose_url(project.id), json={"title": "F"}, headers=auth_header(user),
+        )
+        propose_id = create_resp.json()["id"]
+
+        # Try to set feat_task_id via PATCH
+        resp = client.patch(
+            _propose_url(project.id, propose_id),
+            json={"feat_task_id": "999"},
+            headers=auth_header(user),
+        )
+        assert resp.status_code == 200
+        # feat_task_id should still be None (server ignores it)
+        assert resp.json()["feat_task_id"] is None
+
+
+# ===========================================================================
+# Edit restrictions
+# ===========================================================================
+
+class TestEditRestrictions:
+    """Propose editing is only allowed in open status."""
+
+    def test_edit_accepted_propose_fails(
+        self, client, db, make_user, make_project, make_milestone, seed_roles_and_permissions, make_member, auth_header,
+    ):
+        admin_role, mgr_role, dev_role = seed_roles_and_permissions
+        mgr = make_user()
+        project = make_project(owner_id=mgr.id)
+        make_member(project.id, mgr.id, mgr_role.id)
+
+        ms = make_milestone(project.id, mgr.id, status=MilestoneStatus.OPEN)
+
+        create_resp = client.post(
+            _propose_url(project.id), json={"title": "F"}, headers=auth_header(mgr),
+        )
+        propose_id = create_resp.json()["id"]
+
+        # Accept
+        client.post(
+            _propose_url(project.id, propose_id) + "/accept",
+            json={"milestone_id": ms.id},
+            headers=auth_header(mgr),
+        )
+
+        # Try to edit
+        resp = client.patch(
+            _propose_url(project.id, propose_id),
+            json={"title": "Changed"},
+            headers=auth_header(mgr),
+        )
+        assert resp.status_code == 400
+        assert "open" in resp.json()["detail"].lower()
+
+    def test_edit_rejected_propose_fails(
+        self, client, db, make_user, make_project, seed_roles_and_permissions, make_member, auth_header,
+    ):
+        admin_role, mgr_role, dev_role = seed_roles_and_permissions
+        mgr = make_user()
+        project = make_project(owner_id=mgr.id)
+        make_member(project.id, mgr.id, mgr_role.id)
+
+        create_resp = client.post(
+            _propose_url(project.id), json={"title": "F"}, headers=auth_header(mgr),
+        )
+        propose_id = create_resp.json()["id"]
+
+        # Reject
+        client.post(
+            _propose_url(project.id, propose_id) + "/reject",
+            json={"reason": "no"},
+            headers=auth_header(mgr),
+        )
+
+        # Try to edit
+        resp = client.patch(
+            _propose_url(project.id, propose_id),
+            json={"title": "Changed"},
+            headers=auth_header(mgr),
+        )
+        assert resp.status_code == 400

tests/test_task_transitions.py

@@ -0,0 +1,564 @@
+"""P13.2 — Task state-machine transition tests.
+
+Covers:
+- pending → open: success, milestone not undergoing, deps not met
+- open → undergoing: success, no assignee, non-assignee blocked
+- undergoing → completed: success with comment, no comment fails, non-assignee blocked
+- close from pending/open/undergoing: permission required
+- reopen from completed/closed → open: distinct permissions
+- invalid transitions: rejected by state machine
+- edit restrictions: P5.7 body edit guards by status/assignee
+"""
+import json
+
+import pytest
+from app.models.milestone import MilestoneStatus
+from app.models.task import TaskStatus
+
+
+# -----------------------------------------------------------------------
+# Helpers
+# -----------------------------------------------------------------------
+
+def _transition(client, task_id, new_status, headers, comment=None):
+    """POST /tasks/{id}/transition?new_status=..."""
+    body = {}
+    if comment is not None:
+        body["comment"] = comment
+    return client.post(
+        f"/tasks/{task_id}/transition?new_status={new_status}",
+        json=body,
+        headers=headers,
+    )
+
+
+# -----------------------------------------------------------------------
+# pending → open
+# -----------------------------------------------------------------------
+
+class TestPendingToOpen:
+
+    def test_success(
+        self, client, db, make_user, make_project, make_milestone,
+        make_task, seed_roles_and_permissions, make_member, auth_header,
+    ):
+        """pending→open succeeds when milestone is undergoing and no deps."""
+        admin_role, mgr_role, _ = seed_roles_and_permissions
+        user = make_user()
+        project = make_project(owner_id=user.id)
+        make_member(project.id, user.id, mgr_role.id)
+        ms = make_milestone(project.id, user.id, status=MilestoneStatus.UNDERGOING)
+        task = make_task(project.id, ms.id, user.id, status=TaskStatus.PENDING)
+
+        resp = _transition(client, task.id, "open", auth_header(user))
+        assert resp.status_code == 200, resp.text
+        assert resp.json()["status"] == "open"
+
+    def test_milestone_not_undergoing(
+        self, client, db, make_user, make_project, make_milestone,
+        make_task, seed_roles_and_permissions, make_member, auth_header,
+    ):
+        """pending→open rejected when milestone is still open."""
+        _, mgr_role, _ = seed_roles_and_permissions
+        user = make_user()
+        project = make_project(owner_id=user.id)
+        make_member(project.id, user.id, mgr_role.id)
+        ms = make_milestone(project.id, user.id, status=MilestoneStatus.OPEN)
+        task = make_task(project.id, ms.id, user.id, status=TaskStatus.PENDING)
+
+        resp = _transition(client, task.id, "open", auth_header(user))
+        assert resp.status_code == 400
+        assert "undergoing" in resp.json()["detail"].lower()
+
+    def test_deps_not_satisfied(
+        self, client, db, make_user, make_project, make_milestone,
+        make_task, seed_roles_and_permissions, make_member, auth_header,
+    ):
+        """pending→open rejected when depend_on tasks are not completed."""
+        _, mgr_role, _ = seed_roles_and_permissions
+        user = make_user()
+        project = make_project(owner_id=user.id)
+        make_member(project.id, user.id, mgr_role.id)
+        ms = make_milestone(project.id, user.id, status=MilestoneStatus.UNDERGOING)
+
+        dep_task = make_task(project.id, ms.id, user.id, status=TaskStatus.OPEN)
+        task = make_task(
+            project.id, ms.id, user.id,
+            status=TaskStatus.PENDING,
+            depend_on=json.dumps([dep_task.id]),
+        )
+
+        resp = _transition(client, task.id, "open", auth_header(user))
+        assert resp.status_code == 400
+        assert "depend" in resp.json()["detail"].lower() or "block" in resp.json()["detail"].lower()
+
+    def test_deps_satisfied(
+        self, client, db, make_user, make_project, make_milestone,
+        make_task, seed_roles_and_permissions, make_member, auth_header,
+    ):
+        """pending→open succeeds when all depend_on tasks are completed."""
+        _, mgr_role, _ = seed_roles_and_permissions
+        user = make_user()
+        project = make_project(owner_id=user.id)
+        make_member(project.id, user.id, mgr_role.id)
+        ms = make_milestone(project.id, user.id, status=MilestoneStatus.UNDERGOING)
+
+        dep_task = make_task(project.id, ms.id, user.id, status=TaskStatus.COMPLETED)
+        task = make_task(
+            project.id, ms.id, user.id,
+            status=TaskStatus.PENDING,
+            depend_on=json.dumps([dep_task.id]),
+        )
+
+        resp = _transition(client, task.id, "open", auth_header(user))
+        assert resp.status_code == 200
+        assert resp.json()["status"] == "open"
+
+
+# -----------------------------------------------------------------------
+# open → undergoing
+# -----------------------------------------------------------------------
+
+class TestOpenToUndergoing:
+
+    def test_success_assignee_starts(
+        self, client, db, make_user, make_project, make_milestone,
+        make_task, seed_roles_and_permissions, make_member, auth_header,
+    ):
+        """Assignee can start their own task."""
+        _, mgr_role, _ = seed_roles_and_permissions
+        user = make_user()
+        project = make_project(owner_id=user.id)
+        make_member(project.id, user.id, mgr_role.id)
+        ms = make_milestone(project.id, user.id, status=MilestoneStatus.UNDERGOING)
+        task = make_task(
+            project.id, ms.id, user.id,
+            status=TaskStatus.OPEN,
+            assignee_id=user.id,
+        )
+
+        resp = _transition(client, task.id, "undergoing", auth_header(user))
+        assert resp.status_code == 200
+        assert resp.json()["status"] == "undergoing"
+        db.refresh(task)
+        assert task.started_on is not None
+
+    def test_no_assignee_fails(
+        self, client, db, make_user, make_project, make_milestone,
+        make_task, seed_roles_and_permissions, make_member, auth_header,
+    ):
+        """Cannot start a task without an assignee."""
+        _, mgr_role, _ = seed_roles_and_permissions
+        user = make_user()
+        project = make_project(owner_id=user.id)
+        make_member(project.id, user.id, mgr_role.id)
+        ms = make_milestone(project.id, user.id, status=MilestoneStatus.UNDERGOING)
+        task = make_task(project.id, ms.id, user.id, status=TaskStatus.OPEN)
+
+        resp = _transition(client, task.id, "undergoing", auth_header(user))
+        assert resp.status_code == 400
+        assert "assignee" in resp.json()["detail"].lower()
+
+    def test_non_assignee_blocked(
+        self, client, db, make_user, make_project, make_milestone,
+        make_task, seed_roles_and_permissions, make_member, auth_header,
+    ):
+        """A different user cannot start someone else's task."""
+        _, mgr_role, _ = seed_roles_and_permissions
+        owner = make_user()
+        other = make_user()
+        project = make_project(owner_id=owner.id)
+        make_member(project.id, owner.id, mgr_role.id)
+        make_member(project.id, other.id, mgr_role.id)
+        ms = make_milestone(project.id, owner.id, status=MilestoneStatus.UNDERGOING)
+        task = make_task(
+            project.id, ms.id, owner.id,
+            status=TaskStatus.OPEN,
+            assignee_id=owner.id,
+        )
+
+        resp = _transition(client, task.id, "undergoing", auth_header(other))
+        assert resp.status_code == 403
+        assert "assigned" in resp.json()["detail"].lower()
+
+
+# -----------------------------------------------------------------------
+# undergoing → completed
+# -----------------------------------------------------------------------
+
+class TestUndergoingToCompleted:
+
+    def test_success_with_comment(
+        self, client, db, make_user, make_project, make_milestone,
+        make_task, seed_roles_and_permissions, make_member, auth_header,
+    ):
+        """Assignee can complete a task with a completion comment."""
+        _, mgr_role, _ = seed_roles_and_permissions
+        user = make_user()
+        project = make_project(owner_id=user.id)
+        make_member(project.id, user.id, mgr_role.id)
+        ms = make_milestone(project.id, user.id, status=MilestoneStatus.UNDERGOING)
+        task = make_task(
+            project.id, ms.id, user.id,
+            status=TaskStatus.UNDERGOING,
+            assignee_id=user.id,
+        )
+
+        resp = _transition(client, task.id, "completed", auth_header(user), comment="Done!")
+        assert resp.status_code == 200
+        assert resp.json()["status"] == "completed"
+        db.refresh(task)
+        assert task.finished_on is not None
+
+    def test_no_comment_fails(
+        self, client, db, make_user, make_project, make_milestone,
+        make_task, seed_roles_and_permissions, make_member, auth_header,
+    ):
+        """Cannot complete without a comment."""
+        _, mgr_role, _ = seed_roles_and_permissions
+        user = make_user()
+        project = make_project(owner_id=user.id)
+        make_member(project.id, user.id, mgr_role.id)
+        ms = make_milestone(project.id, user.id, status=MilestoneStatus.UNDERGOING)
+        task = make_task(
+            project.id, ms.id, user.id,
+            status=TaskStatus.UNDERGOING,
+            assignee_id=user.id,
+        )
+
+        resp = _transition(client, task.id, "completed", auth_header(user))
+        assert resp.status_code == 400
+        assert "comment" in resp.json()["detail"].lower()
+
+    def test_empty_comment_fails(
+        self, client, db, make_user, make_project, make_milestone,
+        make_task, seed_roles_and_permissions, make_member, auth_header,
+    ):
+        """Empty/whitespace comment is rejected."""
+        _, mgr_role, _ = seed_roles_and_permissions
+        user = make_user()
+        project = make_project(owner_id=user.id)
+        make_member(project.id, user.id, mgr_role.id)
+        ms = make_milestone(project.id, user.id, status=MilestoneStatus.UNDERGOING)
+        task = make_task(
+            project.id, ms.id, user.id,
+            status=TaskStatus.UNDERGOING,
+            assignee_id=user.id,
+        )
+
+        resp = _transition(client, task.id, "completed", auth_header(user), comment="   ")
+        assert resp.status_code == 400
+        assert "comment" in resp.json()["detail"].lower()
+
+    def test_non_assignee_blocked(
+        self, client, db, make_user, make_project, make_milestone,
+        make_task, seed_roles_and_permissions, make_member, auth_header,
+    ):
+        """Non-assignee cannot complete the task."""
+        _, mgr_role, _ = seed_roles_and_permissions
+        owner = make_user()
+        other = make_user()
+        project = make_project(owner_id=owner.id)
+        make_member(project.id, owner.id, mgr_role.id)
+        make_member(project.id, other.id, mgr_role.id)
+        ms = make_milestone(project.id, owner.id, status=MilestoneStatus.UNDERGOING)
+        task = make_task(
+            project.id, ms.id, owner.id,
+            status=TaskStatus.UNDERGOING,
+            assignee_id=owner.id,
+        )
+
+        resp = _transition(client, task.id, "completed", auth_header(other), comment="I finished it")
+        assert resp.status_code == 403
+
+
+# -----------------------------------------------------------------------
+# Close task (from various states)
+# -----------------------------------------------------------------------
+
+class TestCloseTask:
+
+    @pytest.mark.parametrize("initial_status", [
+        TaskStatus.PENDING,
+        TaskStatus.OPEN,
+        TaskStatus.UNDERGOING,
+    ])
+    def test_close_from_valid_states(
+        self, initial_status,
+        client, db, make_user, make_project, make_milestone,
+        make_task, seed_roles_and_permissions, make_member, auth_header,
+    ):
+        """Close is allowed from pending/open/undergoing with permission."""
+        _, mgr_role, _ = seed_roles_and_permissions
+        user = make_user()
+        project = make_project(owner_id=user.id)
+        make_member(project.id, user.id, mgr_role.id)
+        ms = make_milestone(project.id, user.id, status=MilestoneStatus.UNDERGOING)
+        task = make_task(project.id, ms.id, user.id, status=initial_status)
+
+        resp = _transition(client, task.id, "closed", auth_header(user))
+        assert resp.status_code == 200, resp.text
+        assert resp.json()["status"] == "closed"
+
+    @pytest.mark.parametrize("initial_status", [
+        TaskStatus.COMPLETED,
+        TaskStatus.CLOSED,
+    ])
+    def test_close_from_terminal_states_fails(
+        self, initial_status,
+        client, db, make_user, make_project, make_milestone,
+        make_task, seed_roles_and_permissions, make_member, auth_header,
+    ):
+        """Cannot close from completed or already closed."""
+        _, mgr_role, _ = seed_roles_and_permissions
+        user = make_user()
+        project = make_project(owner_id=user.id)
+        make_member(project.id, user.id, mgr_role.id)
+        ms = make_milestone(project.id, user.id, status=MilestoneStatus.UNDERGOING)
+        task = make_task(project.id, ms.id, user.id, status=initial_status)
+
+        resp = _transition(client, task.id, "closed", auth_header(user))
+        assert resp.status_code == 400
+
+    def test_close_without_permission_fails(
+        self, client, db, make_user, make_project, make_milestone,
+        make_task, seed_roles_and_permissions, make_member, auth_header,
+    ):
+        """User without task.close permission cannot close."""
+        from app.models.role_permission import Role
+        _, _, dev_role = seed_roles_and_permissions
+
+        # Create a role with NO task.close permission
+        no_close_role = Role(name="viewer", is_global=False)
+        db.add(no_close_role)
+        db.commit()
+
+        # Give viewer only basic perms (project.read, task.read)
+        from app.models.role_permission import Permission, RolePermission
+        for pname in ("project.read", "task.read"):
+            p = db.query(Permission).filter(Permission.name == pname).first()
+            if p:
+                db.add(RolePermission(role_id=no_close_role.id, permission_id=p.id))
+        db.commit()
+
+        user = make_user()
+        project = make_project(owner_id=user.id)
+        make_member(project.id, user.id, no_close_role.id)
+        ms = make_milestone(project.id, user.id, status=MilestoneStatus.UNDERGOING)
+        task = make_task(project.id, ms.id, user.id, status=TaskStatus.OPEN)
+
+        resp = _transition(client, task.id, "closed", auth_header(user))
+        assert resp.status_code == 403
+
+
+# -----------------------------------------------------------------------
+# Reopen (completed → open, closed → open)
+# -----------------------------------------------------------------------
+
+class TestReopen:
+
+    def test_reopen_completed(
+        self, client, db, make_user, make_project, make_milestone,
+        make_task, seed_roles_and_permissions, make_member, auth_header,
+    ):
+        """Reopen from completed → open with task.reopen_completed permission."""
+        _, mgr_role, _ = seed_roles_and_permissions
+        user = make_user()
+        project = make_project(owner_id=user.id)
+        make_member(project.id, user.id, mgr_role.id)
+        ms = make_milestone(project.id, user.id, status=MilestoneStatus.UNDERGOING)
+        task = make_task(project.id, ms.id, user.id, status=TaskStatus.COMPLETED)
+
+        resp = _transition(client, task.id, "open", auth_header(user))
+        assert resp.status_code == 200
+        assert resp.json()["status"] == "open"
+        # finished_on should be cleared
+        db.refresh(task)
+        assert task.finished_on is None
+
+    def test_reopen_closed(
+        self, client, db, make_user, make_project, make_milestone,
+        make_task, seed_roles_and_permissions, make_member, auth_header,
+    ):
+        """Reopen from closed → open with task.reopen_closed permission."""
+        _, mgr_role, _ = seed_roles_and_permissions
+        user = make_user()
+        project = make_project(owner_id=user.id)
+        make_member(project.id, user.id, mgr_role.id)
+        ms = make_milestone(project.id, user.id, status=MilestoneStatus.UNDERGOING)
+        task = make_task(project.id, ms.id, user.id, status=TaskStatus.CLOSED)
+
+        resp = _transition(client, task.id, "open", auth_header(user))
+        assert resp.status_code == 200
+        assert resp.json()["status"] == "open"
+
+    def test_reopen_without_permission_fails(
+        self, client, db, make_user, make_project, make_milestone,
+        make_task, seed_roles_and_permissions, make_member, auth_header,
+    ):
+        """User without reopen permission cannot reopen."""
+        from app.models.role_permission import Role, Permission, RolePermission
+
+        # Create a role with task.close but NO reopen permissions
+        limited_role = Role(name="limited", is_global=False)
+        db.add(limited_role)
+        db.commit()
+        for pname in ("project.read", "task.read", "task.write", "task.close"):
+            p = db.query(Permission).filter(Permission.name == pname).first()
+            if p:
+                db.add(RolePermission(role_id=limited_role.id, permission_id=p.id))
+        db.commit()
+
+        user = make_user()
+        project = make_project(owner_id=user.id)
+        make_member(project.id, user.id, limited_role.id)
+        ms = make_milestone(project.id, user.id, status=MilestoneStatus.UNDERGOING)
+        task = make_task(project.id, ms.id, user.id, status=TaskStatus.COMPLETED)
+
+        resp = _transition(client, task.id, "open", auth_header(user))
+        assert resp.status_code == 403
+
+
+# -----------------------------------------------------------------------
+# Invalid transitions
+# -----------------------------------------------------------------------
+
+class TestInvalidTransitions:
+
+    @pytest.mark.parametrize("from_status,to_status", [
+        (TaskStatus.PENDING, "undergoing"),
+        (TaskStatus.PENDING, "completed"),
+        (TaskStatus.OPEN, "completed"),
+        (TaskStatus.OPEN, "pending"),
+        (TaskStatus.UNDERGOING, "open"),
+        (TaskStatus.UNDERGOING, "pending"),
+        (TaskStatus.COMPLETED, "undergoing"),
+        (TaskStatus.COMPLETED, "closed"),
+        (TaskStatus.CLOSED, "undergoing"),
+        (TaskStatus.CLOSED, "completed"),
+    ])
+    def test_disallowed_transition(
+        self, from_status, to_status,
+        client, db, make_user, make_project, make_milestone,
+        make_task, seed_roles_and_permissions, make_member, auth_header,
+    ):
+        """State machine rejects transitions not in VALID_TRANSITIONS."""
+        _, mgr_role, _ = seed_roles_and_permissions
+        user = make_user()
+        project = make_project(owner_id=user.id)
+        make_member(project.id, user.id, mgr_role.id)
+        ms = make_milestone(project.id, user.id, status=MilestoneStatus.UNDERGOING)
+        task = make_task(
+            project.id, ms.id, user.id,
+            status=from_status,
+            assignee_id=user.id,
+        )
+
+        resp = _transition(client, task.id, to_status, auth_header(user))
+        assert resp.status_code == 400
+        assert "cannot transition" in resp.json()["detail"].lower()
+
+
+# -----------------------------------------------------------------------
+# Edit restrictions (PATCH)
+# -----------------------------------------------------------------------
+
+class TestEditRestrictions:
+
+    def test_undergoing_body_edit_blocked(
+        self, client, db, make_user, make_project, make_milestone,
+        make_task, seed_roles_and_permissions, make_member, auth_header,
+    ):
+        """Cannot PATCH body fields on an undergoing task."""
+        _, mgr_role, _ = seed_roles_and_permissions
+        user = make_user()
+        project = make_project(owner_id=user.id)
+        make_member(project.id, user.id, mgr_role.id)
+        ms = make_milestone(project.id, user.id, status=MilestoneStatus.UNDERGOING)
+        task = make_task(project.id, ms.id, user.id, status=TaskStatus.UNDERGOING, assignee_id=user.id)
+
+        resp = client.patch(
+            f"/tasks/{task.id}",
+            json={"title": "New Title"},
+            headers=auth_header(user),
+        )
+        assert resp.status_code == 400
+        assert "undergoing" in resp.json()["detail"].lower()
+
+    def test_completed_body_edit_blocked(
+        self, client, db, make_user, make_project, make_milestone,
+        make_task, seed_roles_and_permissions, make_member, auth_header,
+    ):
+        """Cannot PATCH body fields on a completed task."""
+        _, mgr_role, _ = seed_roles_and_permissions
+        user = make_user()
+        project = make_project(owner_id=user.id)
+        make_member(project.id, user.id, mgr_role.id)
+        ms = make_milestone(project.id, user.id, status=MilestoneStatus.UNDERGOING)
+        task = make_task(project.id, ms.id, user.id, status=TaskStatus.COMPLETED)
+
+        resp = client.patch(
+            f"/tasks/{task.id}",
+            json={"title": "Changed"},
+            headers=auth_header(user),
+        )
+        assert resp.status_code == 400
+
+    def test_open_assignee_only_edit(
+        self, client, db, make_user, make_project, make_milestone,
+        make_task, seed_roles_and_permissions, make_member, auth_header,
+    ):
+        """Open task with assignee: only assignee can edit body."""
+        _, mgr_role, _ = seed_roles_and_permissions
+        owner = make_user()
+        other = make_user()
+        project = make_project(owner_id=owner.id)
+        make_member(project.id, owner.id, mgr_role.id)
+        make_member(project.id, other.id, mgr_role.id)
+        ms = make_milestone(project.id, owner.id, status=MilestoneStatus.UNDERGOING)
+        task = make_task(
+            project.id, ms.id, owner.id,
+            status=TaskStatus.OPEN,
+            assignee_id=owner.id,
+        )
+
+        # Other user cannot edit
+        resp = client.patch(
+            f"/tasks/{task.id}",
+            json={"title": "Hijack"},
+            headers=auth_header(other),
+        )
+        assert resp.status_code == 403
+
+        # Assignee can edit
+        resp = client.patch(
+            f"/tasks/{task.id}",
+            json={"title": "My Change"},
+            headers=auth_header(owner),
+        )
+        assert resp.status_code == 200
+        assert resp.json()["title"] == "My Change"
+
+    def test_open_no_assignee_anyone_edits(
+        self, client, db, make_user, make_project, make_milestone,
+        make_task, seed_roles_and_permissions, make_member, auth_header,
+    ):
+        """Open task without assignee: any project member can edit."""
+        _, mgr_role, _ = seed_roles_and_permissions
+        user = make_user()
+        project = make_project(owner_id=user.id)
+        make_member(project.id, user.id, mgr_role.id)
+        ms = make_milestone(project.id, user.id, status=MilestoneStatus.UNDERGOING)
+        task = make_task(
+            project.id, ms.id, user.id,
+            status=TaskStatus.OPEN,
+            assignee_id=None,
+        )
+
+        resp = client.patch(
+            f"/tasks/{task.id}",
+            json={"title": "Anyone's Change"},
+            headers=auth_header(user),
+        )
+        assert resp.status_code == 200
+        assert resp.json()["title"] == "Anyone's Change"