feat: add reopen trigger and guard role changes in manage_items (#59)

* feat: add reopen trigger and guard role changes in manage_items

Close the last workflow bypass: manage_items(update) can no longer set
role directly — all role changes must go through advance_item triggers.

Add reopen trigger (TERMINAL → QUEUE) with cascade support: when a child
reopens under a terminal parent, the parent auto-cascades to WORK.

Changes:
- RoleTransitionHandler: add resolveReopen + validation bypass for
  backward TERMINAL→QUEUE transition
- CascadeDetector: add detectReopenCascades (immediate parent only)
- AdvanceItemTool: wire reopen cascade, update description/triggers
- ManageItemsTool: reject role field in update with clear error message
- GetNextStatusTool: terminal message now mentions reopen option
- Docs: api-reference.md and workflow-guide.md updated
- Tests: reopen lifecycle, cascade, role guard, integration tests

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* refactor: extract cascade helper and clean up dead code from /simplify

- Extract applyCascadeEvents() helper in AdvanceItemTool to deduplicate
  Phase 4b (start cascade) and Phase 4c (reopen cascade) blocks
- Remove dead newRole variable and redundant extractItemString call in
  ManageItemsTool role guard — use containsKey check instead

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: jpicklyk

current/docs/api-reference.md

@@ -68,6 +68,8 @@ is computed automatically from the parent; the maximum nesting depth is 3.
 fields are changed; omitted fields retain existing values. Setting `parentId` to JSON null moves
 the item to root.
 
+**Note:** The `role` field is not accepted in update operations. Use `advance_item` with an appropriate trigger instead.
+
 **Response (update).**
 
 ```json
@@ -643,7 +645,7 @@ gate enforcement, cascade detection, and unblock reporting. Supports batch trans
 | Field | Type | Required | Description |
 |---|---|---|---|
 | `itemId` | string (UUID) | Yes | Item to transition |
-| `trigger` | string | Yes | One of: `start`, `complete`, `block`, `hold`, `resume`, `cancel` |
+| `trigger` | string | Yes | One of: `start`, `complete`, `block`, `hold`, `resume`, `cancel`, `reopen` |
 | `summary` | string | No | Optional annotation stored on the transition record |
 
 **Trigger effects:**
@@ -655,14 +657,19 @@ gate enforcement, cascade detection, and unblock reporting. Supports batch trans
 | `block` / `hold` | Any non-terminal → BLOCKED (saves `previousRole`) |
 | `resume` | BLOCKED → `previousRole` |
 | `cancel` | Any non-terminal → TERMINAL with `statusLabel="cancelled"` |
+| `reopen` | TERMINAL → QUEUE (clears statusLabel, bypasses gate enforcement, cascades parent TERMINAL → WORK) |
 
 **Gate enforcement.** When the item's `tags` match a configured note schema:
 - `start`: required notes for the current phase must exist and be filled.
 - `complete`: all required notes across all phases must be filled.
 
 **Start cascade.** When a child item transitions to WORK, the parent is automatically advanced from QUEUE to WORK if it is still in QUEUE (same cascade logic applies up the ancestor chain). This appears in `cascadeEvents` in the response with `trigger="cascade"`.
 
-**Terminal cascade.** When a child item reaches TERMINAL, the parent may also automatically advance if all its children are terminal. Both cascade types are recorded in `cascadeEvents`.
+**Terminal cascade.** When a child item reaches TERMINAL, the parent may also automatically advance if all its children are terminal.
+
+**Reopen cascade.** When a child item is reopened (TERMINAL → QUEUE) and its parent is TERMINAL, the parent is automatically reopened to WORK. This ensures the parent reflects that it has active children again.
+
+All cascade types are recorded in `cascadeEvents`.
 
 **Examples.**
 
@@ -784,7 +791,7 @@ the item is Ready to advance, Blocked, or Terminal, without making any changes.
 }
 
 // Terminal
-{ "recommendation": "Terminal", "currentRole": "terminal", "reason": "Item is already terminal and cannot progress further" }
+{ "recommendation": "Terminal", "currentRole": "terminal", "reason": "Item is terminal. Use 'reopen' trigger to move back to queue, or 'cancel' if already cancelled." }
 ```
 
 When the item is in BLOCKED role, the response includes a `suggestion` field instead of `blockers`. When the item is blocked by unsatisfied dependencies, the response includes `blockers` but no `suggestion`.

current/docs/workflow-guide.md

@@ -15,7 +15,7 @@ Every WorkItem moves through a set of lifecycle phases called **roles**. Roles a
 | `queue`    | Pending, not yet started. Default role at creation.          |
 | `work`     | Actively being worked on.                                    |
 | `review`   | Work complete, undergoing verification or review.            |
-| `terminal` | Finished. No further transitions possible (unless cancelled).|
+| `terminal` | Finished. Use `reopen` to move back to queue if needed.      |
 | `blocked`  | Paused due to an unresolved dependency or explicit hold.     |
 
 ### Standard Flow
@@ -50,6 +50,7 @@ All role transitions use `advance_item(trigger=...)`. There is no direct role as
 | `hold`     | Any non-terminal          | `blocked`                | Alias for `block`.                                 |
 | `resume`   | `blocked`                 | Previous role            | Restores role saved at block time.                 |
 | `cancel`   | Any non-terminal          | `terminal`               | Sets `statusLabel = "cancelled"`.                  |
+| `reopen`   | `terminal`                | `queue`                  | Clears statusLabel, bypasses gates. Parent cascades TERMINAL → WORK. |
 
 ### Example: Advance a Work Item
 
@@ -537,7 +538,9 @@ get_blocked_items(parentId="feature-uuid", includeAncestors=true)
 
 **Terminal cascade (all children → TERMINAL):** When a child item reaches TERMINAL, if all siblings are also terminal, the parent is automatically advanced to TERMINAL. This cascade also continues up the ancestor chain.
 
-Both cascade types appear in `cascadeEvents` in the response:
+**Reopen cascade (child TERMINAL → QUEUE):** When a child item is reopened under a terminal parent, the parent is automatically reopened to WORK. This only applies to the immediate parent — no recursion.
+
+All cascade types appear in `cascadeEvents` in the response:
 
 ```json
 {
@@ -718,4 +721,5 @@ docker run -e AGENT_CONFIG_DIR=/project -v "$(pwd)"/.taskorchestrator:/project/.
 | Find blocked items                | `get_blocked_items(includeAncestors=true)`                      |
 | Create a dependency chain         | `manage_dependencies(operation="create", pattern="linear", itemIds=[...])` |
 | Cancel an item                    | `advance_item(transitions=[{itemId, trigger:"cancel"}])`        |
+| Reopen a terminal item           | `advance_item(transitions=[{itemId, trigger:"reopen"}])`        |
 | Filter by phase                   | `query_items(operation="search", role="work")`                  |

current/src/main/kotlin/io/github/jpicklyk/mcptask/current/application/service/CascadeDetector.kt

@@ -161,6 +161,40 @@ class CascadeDetector {
         ))
     }
 
+    // -----------------------------------------------------------------------
+    // Reopen Cascade Detection
+    // -----------------------------------------------------------------------
+
+    /**
+     * Detect whether reopening an item should cascade to reopen its parent.
+     * If the item was just reopened (now in QUEUE) and its parent is TERMINAL,
+     * the parent should reopen to WORK since it now has a non-terminal child.
+     * Only checks immediate parent — no recursion.
+     */
+    suspend fun detectReopenCascades(
+        item: WorkItem,
+        workItemRepository: WorkItemRepository
+    ): List<CascadeEvent> {
+        // Only applies to items that just entered QUEUE via reopen
+        if (item.role != Role.QUEUE) return emptyList()
+
+        val parentId = item.parentId ?: return emptyList()
+
+        val parent = when (val result = workItemRepository.getById(parentId)) {
+            is Result.Success -> result.data
+            is Result.Error -> return emptyList()
+        }
+
+        // Only cascade if parent is TERMINAL
+        if (parent.role != Role.TERMINAL) return emptyList()
+
+        return listOf(CascadeEvent(
+            itemId = parent.id,
+            currentRole = Role.TERMINAL,
+            targetRole = Role.WORK
+        ))
+    }
+
     // -----------------------------------------------------------------------
     // Unblock Detection
     // -----------------------------------------------------------------------

current/src/main/kotlin/io/github/jpicklyk/mcptask/current/application/service/RoleTransitionHandler.kt

@@ -64,7 +64,7 @@ data class TransitionApplyResult(
 class RoleTransitionHandler {
 
     companion object {
-        val VALID_TRIGGERS = setOf("start", "complete", "block", "hold", "resume", "cancel")
+        val VALID_TRIGGERS = setOf("start", "complete", "block", "hold", "resume", "cancel", "reopen")
     }
 
     // -----------------------------------------------------------------------
@@ -89,6 +89,7 @@ class RoleTransitionHandler {
                         "Use resolveTransition(item, trigger) instead."
             )
             "cancel" -> resolveCancel(currentRole)
+            "reopen" -> resolveReopen(currentRole)
             else -> TransitionResolution(
                 success = false,
                 error = "Unknown trigger: '$trigger'. Valid triggers: ${VALID_TRIGGERS.joinToString()}"
@@ -111,6 +112,7 @@ class RoleTransitionHandler {
             "block", "hold" -> resolveBlock(item.role)
             "resume" -> resolveResume(item)
             "cancel" -> resolveCancel(item.role)
+            "reopen" -> resolveReopen(item.role)
             else -> TransitionResolution(
                 success = false,
                 error = "Unknown trigger: '$trigger'. Valid triggers: ${VALID_TRIGGERS.joinToString()}"
@@ -183,6 +185,14 @@ class RoleTransitionHandler {
         else -> TransitionResolution(success = true, targetRole = Role.TERMINAL, statusLabel = "cancelled")
     }
 
+    private fun resolveReopen(currentRole: Role): TransitionResolution = when (currentRole) {
+        Role.TERMINAL -> TransitionResolution(success = true, targetRole = Role.QUEUE, statusLabel = null)
+        else -> TransitionResolution(
+            success = false,
+            error = "Cannot reopen: item is not terminal (current role: ${currentRole.name.lowercase()})"
+        )
+    }
+
     // -----------------------------------------------------------------------
     // Phase 2: Validation (reads dependencies, suspend for WorkItem lookups)
     // -----------------------------------------------------------------------
@@ -207,6 +217,11 @@ class RoleTransitionHandler {
             return TransitionValidation(valid = true)
         }
 
+        // Reopen transitions bypass the terminal guard (backward transition)
+        if (item.role == Role.TERMINAL && targetRole == Role.QUEUE) {
+            return TransitionValidation(valid = true)
+        }
+
         // Terminal items cannot transition further
         if (item.role == Role.TERMINAL) {
             return TransitionValidation(

current/src/main/kotlin/io/github/jpicklyk/mcptask/current/application/tools/items/ManageItemsTool.kt

@@ -44,7 +44,8 @@ Unified write operations for WorkItems (create, update, delete).
 - `tags` is always included (null if not set). `expectedNotes` is included only when the item's tags match a configured note schema — check it immediately after creation to know which notes to fill.
 
 **update** - Partial update from `items` array.
-- Each item: `{ id (required), title?, description?, summary?, role?, statusLabel?, priority?, complexity?, parentId?, metadata?, tags? }`
+- Each item: `{ id (required), title?, description?, summary?, statusLabel?, priority?, complexity?, parentId?, metadata?, tags? }`
+- Note: role changes are not allowed in update operations. Use advance_item with triggers (start, complete, block, hold, resume, cancel, reopen) instead.
 - Only provided fields are changed; omitted fields retain existing values
 - If parentId changes, depth is recomputed from new parent
 - Response: `{ items: [{id, modifiedAt}], updated: N, failed: N, failures: [{id, error}] }`
@@ -392,24 +393,22 @@ Unified write operations for WorkItems (create, update, delete).
                 val newTitle = extractItemString(itemObj, "title")
                 val newDescription = extractItemStringAllowNull(itemObj, "description", existing.description)
                 val newSummary = extractItemString(itemObj, "summary")
-                val newRoleStr = extractItemString(itemObj, "role")
+
+                // Reject role field in updates — all role changes must go through advance_item
+                if (itemObj.containsKey("role")) {
+                    throw ToolValidationException(
+                        "Item '$itemId': role changes are not allowed via manage_items update. " +
+                        "Use advance_item with an appropriate trigger instead (start, complete, block, hold, resume, cancel, reopen)."
+                    )
+                }
+
                 val newStatusLabel = extractItemStringAllowNull(itemObj, "statusLabel", existing.statusLabel)
                 val newPriorityStr = extractItemString(itemObj, "priority")
                 val newComplexity = extractItemInt(itemObj, "complexity")
                 val newRequiresVerification = itemObj["requiresVerification"]?.let { (it as? JsonPrimitive)?.booleanOrNull }
                 val newMetadata = extractItemStringAllowNull(itemObj, "metadata", existing.metadata)
                 val newTags = extractItemStringAllowNull(itemObj, "tags", existing.tags)
 
-                // Parse role if provided
-                val newRole = if (newRoleStr != null) {
-                    Role.fromString(newRoleStr)
-                        ?: throw ToolValidationException(
-                            "Item '$itemId': invalid role '$newRoleStr'. Valid: ${Role.VALID_NAMES}"
-                        )
-                } else {
-                    null
-                }
-
                 // Parse priority if provided
                 val newPriority = if (newPriorityStr != null) {
                     Priority.fromString(newPriorityStr)
@@ -488,7 +487,7 @@ Unified write operations for WorkItems (create, update, delete).
                         title = newTitle ?: item.title,
                         description = newDescription,
                         summary = newSummary ?: item.summary,
-                        role = newRole ?: item.role,
+                        role = item.role,
                         statusLabel = newStatusLabel,
                         priority = newPriority ?: item.priority,
                         complexity = newComplexity ?: item.complexity,

current/src/main/kotlin/io/github/jpicklyk/mcptask/current/application/tools/workflow/AdvanceItemTool.kt

@@ -1,6 +1,7 @@
 package io.github.jpicklyk.mcptask.current.application.tools.workflow
 
 import io.github.jpicklyk.mcptask.current.application.service.CascadeDetector
+import io.github.jpicklyk.mcptask.current.application.service.CascadeEvent
 import io.github.jpicklyk.mcptask.current.application.service.RoleTransitionHandler
 import io.github.jpicklyk.mcptask.current.application.tools.*
 import io.github.jpicklyk.mcptask.current.domain.model.Role
@@ -17,7 +18,7 @@ import java.util.UUID
  * Supports batch transitions via the `transitions` array parameter. Each transition
  * is processed independently: failures on one do not block others.
  *
- * Valid triggers: start, complete, block, hold, resume, cancel.
+ * Valid triggers: start, complete, block, hold, resume, cancel, reopen.
  *
  * NoteSchemaService integration:
  * - If the item's tags match a schema, gate enforcement applies:
@@ -35,14 +36,15 @@ Trigger-based role transitions for WorkItems with validation, cascade detection,
 
 **Parameters:**
 - `transitions` (required array): Each element: `{ itemId (required UUID), trigger (required string), summary? (optional string) }`
-- Valid triggers: start, complete, block, hold, resume, cancel
+- Valid triggers: start, complete, block, hold, resume, cancel, reopen
 
 **Trigger effects:**
 - start: QUEUE->WORK, WORK->REVIEW (or TERMINAL if no review phase in schema), REVIEW->TERMINAL
 - complete: any non-TERMINAL/BLOCKED -> TERMINAL
 - block/hold: any non-TERMINAL/BLOCKED -> BLOCKED (saves previousRole)
 - resume: BLOCKED -> previousRole
 - cancel: any non-TERMINAL -> TERMINAL (statusLabel = "cancelled")
+- reopen: TERMINAL -> QUEUE (clears statusLabel; bypasses gate enforcement)
 
 **Gate enforcement (when tags match a note schema):**
 - start: required notes for the current phase must be filled before advancing
@@ -322,28 +324,16 @@ Trigger-based role transitions for WorkItems with validation, cascade detection,
             // When the first child starts, auto-advance the parent from QUEUE to WORK.
             if (targetRole == Role.WORK) {
                 val startCascadeEvents = cascadeDetector.detectStartCascades(applyResult.item!!, context.workItemRepository())
-                for (event in startCascadeEvents) {
-                    val parentResult = context.workItemRepository().getById(event.itemId)
-                    val parentItem = when (parentResult) {
-                        is Result.Success -> parentResult.data
-                        is Result.Error -> continue
-                    }
-
-                    val cascadeApply = handler.applyTransition(
-                        parentItem, event.targetRole, "cascade",
-                        "Auto-cascaded from child start", null,
-                        context.workItemRepository(),
-                        context.roleTransitionRepository()
-                    )
+                applyCascadeEvents(startCascadeEvents, "Auto-cascaded from child start",
+                    handler, context, cascadeJsonList)
+            }
 
-                    cascadeJsonList.add(buildJsonObject {
-                        put("itemId", JsonPrimitive(event.itemId.toString()))
-                        put("title", JsonPrimitive(parentItem.title))
-                        put("previousRole", JsonPrimitive(event.currentRole.name.lowercase()))
-                        put("targetRole", JsonPrimitive(event.targetRole.name.lowercase()))
-                        put("applied", JsonPrimitive(cascadeApply.success))
-                    })
-                }
+            // Phase 4c: Reopen cascade detection (only when reopening to QUEUE)
+            // When a child is reopened under a terminal parent, the parent should reopen to WORK.
+            if (trigger == "reopen" && targetRole == Role.QUEUE) {
+                val reopenCascadeEvents = cascadeDetector.detectReopenCascades(applyResult.item!!, context.workItemRepository())
+                applyCascadeEvents(reopenCascadeEvents, "Auto-cascaded from child reopen",
+                    handler, context, cascadeJsonList)
             }
 
             // Phase 5: Unblock detection
@@ -440,6 +430,41 @@ Trigger-based role transitions for WorkItems with validation, cascade detection,
         return if (failed == 0) "Transitioned $succeeded item(s)" else "Transitioned $succeeded/$total (${failed} failed)"
     }
 
+    /**
+     * Apply a list of cascade events: fetch each parent, apply the transition, and record
+     * the cascade result as JSON. Shared by start cascade (Phase 4b) and reopen cascade (Phase 4c).
+     */
+    private suspend fun applyCascadeEvents(
+        events: List<CascadeEvent>,
+        summary: String,
+        handler: RoleTransitionHandler,
+        context: ToolExecutionContext,
+        cascadeJsonList: MutableList<JsonObject>
+    ) {
+        for (event in events) {
+            val parentResult = context.workItemRepository().getById(event.itemId)
+            val parentItem = when (parentResult) {
+                is Result.Success -> parentResult.data
+                is Result.Error -> continue
+            }
+
+            val cascadeApply = handler.applyTransition(
+                parentItem, event.targetRole, "cascade",
+                summary, null,
+                context.workItemRepository(),
+                context.roleTransitionRepository()
+            )
+
+            cascadeJsonList.add(buildJsonObject {
+                put("itemId", JsonPrimitive(event.itemId.toString()))
+                put("title", JsonPrimitive(parentItem.title))
+                put("previousRole", JsonPrimitive(event.currentRole.name.lowercase()))
+                put("targetRole", JsonPrimitive(event.targetRole.name.lowercase()))
+                put("applied", JsonPrimitive(cascadeApply.success))
+            })
+        }
+    }
+
     private fun buildErrorResult(
         itemId: UUID,
         trigger: String,

current/src/main/kotlin/io/github/jpicklyk/mcptask/current/application/tools/workflow/GetNextStatusTool.kt

@@ -78,7 +78,7 @@ Read-only status progression recommendation for a WorkItem.
                 successResponse(buildJsonObject {
                     put("recommendation", JsonPrimitive("Terminal"))
                     put("currentRole", JsonPrimitive("terminal"))
-                    put("reason", JsonPrimitive("Item is already terminal and cannot progress further"))
+                    put("reason", JsonPrimitive("Item is terminal. Use 'reopen' trigger to move back to queue, or 'cancel' if already cancelled."))
                 })
             }
 

current/src/main/kotlin/io/github/jpicklyk/mcptask/current/domain/model/RoleTransition.kt

@@ -19,6 +19,6 @@ data class RoleTransition(
     val transitionedAt: Instant = Instant.now()
 ) {
     companion object {
-        val VALID_TRIGGERS = setOf("start", "complete", "block", "hold", "resume", "cancel")
+        val VALID_TRIGGERS = setOf("start", "complete", "block", "hold", "resume", "cancel", "reopen")
     }
 }