feat(workflow): config-driven status labels with query response support (#71)

* feat: add session retrospective skill and run manifest tracking

Introduces structured post-implementation analysis — a /session-retrospective
skill that evaluates schema effectiveness, delegation alignment, note quality,
plan-to-execution fit, and friction across five dimensions. Includes run manifest
instructions in the shared orchestrator output style for durable session telemetry,
and a retrospective nudge after implementation completions.

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

* fix: improve session-retrospective skill robustness

Address issues found during skill review: remove hardcoded absolute
paths, add early exit for empty sessions, expand trigger description,
simplify terminal advancement, and add recency filter to fallback mode.

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

* feat: upgrade MCP Kotlin SDK from 0.8.4 to 0.9.0

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

* feat: adopt ClientConnection and kotlin-sdk-testing from MCP SDK 0.9.0

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

* fix: enforce note schema gates on cascade-to-TERMINAL transitions

Cascade auto-completion previously bypassed gate enforcement, allowing
parent items with schema tags to reach TERMINAL with required notes
unfilled. Now cascade-to-TERMINAL checks all required notes (matching
the "complete" trigger behavior). Schema-free parents cascade freely.

Also extracts buildMissingNotesArray() to NoteSchemaJsonHelpers and
replaces inline filledKeys computation with buildFilledKeys() across
all three gate-check paths.

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

* docs: document local-first squash flow in implement skill and CLAUDE.md

Update the /implement skill to reflect the local-first git workflow:
branches stay local, squash-merge into local main, and PRs are batched.
Align CLAUDE.md git workflow section to match.

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

* feat: schema improvement — role validation, AdvanceItemTool consolidation

- Add VALID_SCHEMA_ROLES validation in YamlNoteSchemaService.parseEntry()
  to catch typos and invalid role values at config load time (warns + skips)
- Consolidate AdvanceItemTool response fields to use shared
  computePhaseNoteContext() instead of manual NoteSchemaJsonHelpers calls
- Remove findGuidancePointer() and buildNoteProgress() from
  NoteSchemaJsonHelpers (now gate-check helpers only)
- Add plugin-change schema to config.yaml (gitignored, local only)

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

* refactor(test): create shared test infrastructure — TestBase, fixtures, and helpers

Add reusable test utilities under current/src/test/.../test/:
- TestFixtures.kt: makeItem(), blocksDep(), makeNote(), JSON param helpers, response extractors
- BaseRepositoryTest.kt: H2 in-memory DB base class with createPersistedItem/Note/Dependency
- MockRepositoryProvider.kt: MockK-based RepositoryProvider factory with context() builder
- TestNoteSchemaService.kt: In-memory NoteSchemaService with FEATURE_IMPLEMENTATION/BUG_FIX presets
- TestInfrastructureTest.kt: 27 validation tests covering all shared infrastructure

Migrated SQLiteWorkItemRepositoryTest to extend BaseRepositoryTest as proof of concept.

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

* fix: broaden retrospective nudge to cover all terminal transition paths

The retrospective nudge previously only fired after complete_tree, missing
single-item runs that reach terminal via advance_item. Updated the nudge
condition to trigger on any terminal transition during an /implement run,
with single-item, multi-item, and fallback detection rules.

Also: minor AdvanceItemTool optimization — derive existingKeys from
notesByKey instead of a separate .map() pass.

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

* feat: replace session manifest with distributed session-tracking notes

The monolithic run manifest (stored as a CC session task) had a 100%
creation failure rate. Replace it with distributed `session-tracking`
notes on each work item, enforced by schema gates.

- Add default schema fallback to YamlNoteSchemaService (one-line change)
- Add session-tracking note to feature-implementation, bug-fix, and
  plugin-change schemas in config.yaml
- Create new `default` schema as catch-all for untagged items
- Rewrite session-retrospective skill to aggregate distributed notes
- Remove manifest section from workflow-orchestrator output style
- Add lightweight delegation-metadata pattern for orchestrator-side data
- Simplify retrospective nudge (remove manifest references)

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

* feat: add feature-task schema for lighter child work item gates

Split feature work into two schema tiers: feature-implementation for the
parent container (full spec, holistic review with /simplify) and feature-task
for child work items (task-scope, task-level review). Plugin skills updated
to remain generic — they reference config.yaml for schema discovery rather
than hardcoding specific tag names.

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

* feat(workflow): add config-driven status labels and surface in query responses

Add StatusLabelService for trigger-to-label auto-mapping on role transitions.
Labels are configured in .taskorchestrator/config.yaml (status_labels section)
with hardcoded defaults as fallback. Label precedence: hardcoded resolution
(cancel/reopen) > config-driven > null.

Changes:
- NEW: StatusLabelService interface + NoOpStatusLabelService defaults
- NEW: YamlStatusLabelService reads config with AGENT_CONFIG_DIR support
- Wire label resolution into AdvanceItemTool, CompleteTreeTool (including cascade)
- Surface statusLabel in QueryItemsTool search, overview, and get responses
- Add statusLabel to toMinimalJson and toFullJson serializers
- 23 new tests: YamlStatusLabelService (11), AdvanceItemTool (6),
  CompleteTreeTool (2), QueryItemsTool (4) — covering config-driven labels,
  cascade labels, label precedence, block/resume, and query responses
- Update workflow-guide.md and api-reference.md documentation
- Enforce explicit model parameter in delegation table (plugin/skill update)

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

---------

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

Author: jpicklyk

.claude/skills/implement/SKILL.md

@@ -126,6 +126,17 @@ UUID inclusion). The key decisions at this step are:
 - **Multiple child tasks, dependent:** dispatch sequentially — wait for each agent
   to return before dispatching the next.
 
+**Model selection — always set `model` explicitly on every Agent dispatch:**
+
+| Agent purpose | Model |
+|--------------|-------|
+| Implementation, code changes, test writing | `model="sonnet"` |
+| Architecture, complex multi-file synthesis | `model="opus"` |
+| MCP bulk ops, materialization | `model="haiku"` |
+
+Omitting `model` causes the agent to inherit the orchestrator's model (typically
+opus), wasting tokens on sonnet-eligible implementation work.
+
 **After implementation agents return:**
 
 If agents used worktree isolation, the Agent tool result includes the **worktree

claude-plugins/task-orchestrator/output-styles/workflow-orchestrator.md

@@ -33,7 +33,7 @@ If `get_context` returns no `noteSchema` for a tagged item, schemas may not be c
 | Code reading, implementation, test writing | `sonnet` |
 | Architecture, complex tradeoffs, multi-file synthesis | `opus` |
 
-Set via the `model` parameter on the Agent tool. Default inherits orchestrator model — always override for haiku-eligible work.
+Set via the `model` parameter on the Agent tool. Default inherits orchestrator model — **always set `model` explicitly** on every Agent dispatch. Omitting it causes sonnet-eligible work to run on opus (wasting tokens) or opus-eligible work to run on a weaker model.
 
 **Rule: Never make 3+ MCP write calls in a single turn.** Parallelized reads (e.g., `get_context` + `query_items overview`) are fine and encouraged. Use the Agent tool with `model: "haiku"` to delegate bulk MCP write work (multiple item/dependency/note creates) and keep the orchestrator context clean.
 

current/docs/api-reference.md

@@ -212,7 +212,7 @@ hierarchical overview.
 }
 ```
 
-Search returns minimal fields (`id`, `parentId`, `title`, `role`, `priority`, `depth`, `tags`).
+Search returns minimal fields (`id`, `parentId`, `title`, `role`, `statusLabel`, `priority`, `depth`, `tags`). `statusLabel` is only present when non-null.
 Use `get` for full item JSON including `description`, `summary`, `statusLabel`, timestamps, and
 `roleChangedAt`.
 
@@ -228,7 +228,7 @@ Use `get` for full item JSON including `description`, `summary`, `statusLabel`,
 }
 ```
 
-Scoped overview returns the full item JSON in `item`, a count per role in `childCounts`, and a minimal JSON list of direct children in `children`. The global overview (no `itemId`) returns a flat `items` array of root items each with `id`, `title`, `role`, `priority`, and `childCounts`. In global mode `total` reflects the count of root items returned (not a total-in-DB count).
+Scoped overview returns the full item JSON in `item`, a count per role in `childCounts`, and a minimal JSON list of direct children in `children` (each child includes `statusLabel` when non-null). The global overview (no `itemId`) returns a flat `items` array of root items each with `id`, `title`, `role`, `statusLabel` (when non-null), `priority`, and `childCounts`. When `includeChildren` is true, each child object also includes `statusLabel` when non-null. In global mode `total` reflects the count of root items returned (not a total-in-DB count).
 
 ---
 

current/docs/workflow-guide.md

@@ -466,7 +466,53 @@ Use manage_notes(operation="upsert") with itemId="abc-123", key="design", role="
 
 ---
 
-## 6. Dependency Blocking
+## 6. Status Labels
+
+Status labels are human-readable strings automatically set on WorkItems during role transitions. They provide a display-friendly status name alongside the semantic role.
+
+### Default Labels
+
+| Trigger    | Status Label     | Description                                     |
+|------------|------------------|-------------------------------------------------|
+| `start`    | `"in-progress"`  | Item has begun active work.                     |
+| `complete` | `"done"`         | Item finished successfully.                     |
+| `block`    | `"blocked"`      | Item is paused due to a dependency or hold.     |
+| `cancel`   | `"cancelled"`    | Item was explicitly cancelled.                  |
+| `cascade`  | `"done"`         | Item auto-completed via cascade from children.  |
+| `resume`   | *(null)*         | Preserves the label from before the block.      |
+| `reopen`   | *(null/cleared)* | Clears the label when reopening a terminal item.|
+
+### Label Precedence
+
+1. **Resolution label** — hardcoded for `cancel` ("cancelled") and `reopen` (null/cleared). Always wins when non-null.
+2. **Config-driven label** — resolved from `StatusLabelService` for the trigger. Used when the resolution label is null.
+3. **Resume behavior** — `applyTransition` preserves the pre-block label automatically.
+
+### Customizing Labels
+
+Override default labels in `.taskorchestrator/config.yaml`:
+
+```yaml
+status_labels:
+  start: "working"
+  complete: "finished"
+  block: "on-hold"
+  cancel: "abandoned"
+  cascade: "auto-completed"
+```
+
+Triggers not listed in the config get no label override (null). If no `status_labels` section exists, the hardcoded defaults above are used.
+
+### Where Labels Appear
+
+- **`advance_item` response** — each successful result includes `"statusLabel"` when set.
+- **`complete_tree` response** — each completed/cancelled item includes `"statusLabel"` when set.
+- **Cascade events** — cascade results in both tools include `"statusLabel"` when set.
+- **`query_items` responses** — the `statusLabel` field is included in item JSON when non-null.
+
+---
+
+## 7. Dependency Blocking
 
 ### BLOCKS Edges
 
@@ -573,7 +619,7 @@ Items in `unblockedItems` are now eligible to be started.
 
 ---
 
-## 7. Efficient Queries
+## 8. Efficient Queries
 
 ### Role-Based Filtering
 
@@ -649,7 +695,7 @@ get_next_item(parentId="feature-uuid")
 
 ---
 
-## 8. Config Reference
+## 9. Config Reference
 
 The full schema for `.taskorchestrator/config.yaml`:
 

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

@@ -0,0 +1,45 @@
+package io.github.jpicklyk.mcptask.current.application.service
+
+/**
+ * Provides trigger-to-label mappings for status labels on role transitions.
+ *
+ * Labels are resolved from `.taskorchestrator/config.yaml` under the `status_labels` section.
+ * When no config is present, hardcoded defaults are used:
+ * - start -> "in-progress"
+ * - complete -> "done"
+ * - block -> "blocked"
+ * - cancel -> "cancelled"
+ * - cascade -> "done"
+ * - resume -> null (preserves pre-block label)
+ * - reopen -> null (clears label)
+ *
+ * Label precedence in AdvanceItemTool:
+ * 1. resolution.statusLabel (hardcoded cancel/reopen) — if non-null, use it
+ * 2. Config-driven label from resolveLabel(trigger) — if resolution was null
+ * 3. For resume: existing applyTransition logic preserves pre-block label
+ */
+interface StatusLabelService {
+
+    /**
+     * Returns the status label for the given trigger, or null if the trigger
+     * should not set a label (e.g., resume, reopen).
+     */
+    fun resolveLabel(trigger: String): String?
+}
+
+/**
+ * No-op implementation that returns hardcoded defaults.
+ * Used when no config file is present or as a fallback.
+ */
+object NoOpStatusLabelService : StatusLabelService {
+    private val defaults = mapOf(
+        "start" to "in-progress",
+        "complete" to "done",
+        "block" to "blocked",
+        "cancel" to "cancelled",
+        "cascade" to "done"
+        // resume and reopen intentionally absent — null means no label override
+    )
+
+    override fun resolveLabel(trigger: String): String? = defaults[trigger]
+}

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

@@ -53,6 +53,7 @@ fun WorkItem.toMinimalJson(): JsonObject = buildJsonObject {
     parentId?.let { put("parentId", JsonPrimitive(it.toString())) }
     put("title", JsonPrimitive(title))
     put("role", JsonPrimitive(role.toJsonString()))
+    statusLabel?.let { put("statusLabel", JsonPrimitive(it)) }
     put("priority", JsonPrimitive(priority.toJsonString()))
     put("depth", JsonPrimitive(depth))
     tags?.let { put("tags", JsonPrimitive(it)) }

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

@@ -2,6 +2,8 @@ package io.github.jpicklyk.mcptask.current.application.tools
 
 import io.github.jpicklyk.mcptask.current.application.service.NoteSchemaService
 import io.github.jpicklyk.mcptask.current.application.service.NoOpNoteSchemaService
+import io.github.jpicklyk.mcptask.current.application.service.NoOpStatusLabelService
+import io.github.jpicklyk.mcptask.current.application.service.StatusLabelService
 import io.github.jpicklyk.mcptask.current.application.service.WorkTreeExecutor
 import io.github.jpicklyk.mcptask.current.domain.repository.DependencyRepository
 import io.github.jpicklyk.mcptask.current.domain.repository.NoteRepository
@@ -22,7 +24,8 @@ import io.github.jpicklyk.mcptask.current.infrastructure.repository.RepositoryPr
  */
 class ToolExecutionContext(
     val repositoryProvider: RepositoryProvider,
-    private val noteSchemaService: NoteSchemaService = NoOpNoteSchemaService
+    private val noteSchemaService: NoteSchemaService = NoOpNoteSchemaService,
+    private val statusLabelService: StatusLabelService = NoOpStatusLabelService
 ) {
 
     /** Access to WorkItem CRUD and query operations. */
@@ -40,6 +43,9 @@ class ToolExecutionContext(
     /** Access to Note schema configuration service. */
     fun noteSchemaService(): NoteSchemaService = noteSchemaService
 
+    /** Access to the status label configuration service. */
+    fun statusLabelService(): StatusLabelService = statusLabelService
+
     /** Access to the atomic work-tree creation executor. */
     fun workTreeExecutor(): WorkTreeExecutor = repositoryProvider.workTreeExecutor()
 }

current/src/main/kotlin/io/github/jpicklyk/mcptask/current/application/tools/compound/CompleteTreeTool.kt

@@ -283,9 +283,11 @@ Complete or cancel all descendants of a root item (or an explicit list of items)
                 continue
             }
 
-            // Apply transition
+            // Apply transition with config-driven status label
+            val configLabel = context.statusLabelService().resolveLabel(trigger)
+            val effectiveLabel = resolution.statusLabel ?: configLabel
             val applyResult = handler.applyTransition(
-                item, resolution.targetRole, trigger, null, resolution.statusLabel,
+                item, resolution.targetRole, trigger, null, effectiveLabel,
                 context.workItemRepository(),
                 context.roleTransitionRepository()
             )
@@ -310,6 +312,7 @@ Complete or cancel all descendants of a root item (or an explicit list of items)
                 put("title", JsonPrimitive(item.title))
                 put("applied", JsonPrimitive(true))
                 put("trigger", JsonPrimitive(trigger))
+                applyResult.item?.statusLabel?.let { put("statusLabel", JsonPrimitive(it)) }
             })
         }
 
@@ -371,8 +374,10 @@ Complete or cancel all descendants of a root item (or an explicit list of items)
             return
         }
 
+        val configLabel = context.statusLabelService().resolveLabel(trigger)
+        val effectiveLabel = resolution.statusLabel ?: configLabel
         val applyResult = handler.applyTransition(
-            item, resolution.targetRole, trigger, null, resolution.statusLabel,
+            item, resolution.targetRole, trigger, null, effectiveLabel,
             context.workItemRepository(),
             context.roleTransitionRepository()
         )
@@ -395,6 +400,7 @@ Complete or cancel all descendants of a root item (or an explicit list of items)
             put("title", JsonPrimitive(item.title))
             put("applied", JsonPrimitive(true))
             put("trigger", JsonPrimitive(trigger))
+            applyResult.item?.statusLabel?.let { put("statusLabel", JsonPrimitive(it)) }
         })
     }
 

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

@@ -518,6 +518,7 @@ Operations: get, search, overview
                 put("id", JsonPrimitive(item.id.toString()))
                 put("title", JsonPrimitive(item.title))
                 put("role", JsonPrimitive(item.role.toJsonString()))
+                item.statusLabel?.let { put("statusLabel", JsonPrimitive(it)) }
                 put("priority", JsonPrimitive(item.priority.toJsonString()))
                 put("childCounts", roleCountToJson(childCounts))
                 if (includeChildren) {
@@ -530,6 +531,7 @@ Operations: get, search, overview
                             put("id", JsonPrimitive(child.id.toString()))
                             put("title", JsonPrimitive(child.title))
                             put("role", JsonPrimitive(child.role.toJsonString()))
+                            child.statusLabel?.let { put("statusLabel", JsonPrimitive(it)) }
                             put("depth", JsonPrimitive(child.depth))
                         }
                     }))

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

@@ -162,6 +162,7 @@ Trigger-based role transitions for WorkItems with validation, cascade detection,
             // Phase 1: Resolve — schema-driven review phase detection
             val hasReviewPhase = noteSchemaService.hasReviewPhase(itemTags)
             val resolution = handler.resolveTransition(item, trigger, hasReviewPhase)
+            val configLabel = context.statusLabelService().resolveLabel(trigger)
             if (!resolution.success || resolution.targetRole == null) {
                 failCount++
                 resultsList.add(buildErrorResult(itemId, trigger, resolution.error ?: "Failed to resolve transition"))
@@ -249,8 +250,9 @@ Trigger-based role transitions for WorkItems with validation, cascade detection,
             }
 
             // Phase 3: Apply
+            val effectiveLabel = resolution.statusLabel ?: configLabel
             val applyResult = handler.applyTransition(
-                item, targetRole, trigger, summary, resolution.statusLabel,
+                item, targetRole, trigger, summary, effectiveLabel,
                 context.workItemRepository(),
                 context.roleTransitionRepository()
             )
@@ -316,7 +318,8 @@ Trigger-based role transitions for WorkItems with validation, cascade detection,
 
                     val cascadeApply = handler.applyTransition(
                         parentItem, event.targetRole, "cascade",
-                        "Auto-cascaded from child completion", null,
+                        "Auto-cascaded from child completion",
+                        context.statusLabelService().resolveLabel("cascade"),
                         context.workItemRepository(),
                         context.roleTransitionRepository()
                     )
@@ -327,6 +330,7 @@ Trigger-based role transitions for WorkItems with validation, cascade detection,
                         put("previousRole", JsonPrimitive(event.currentRole.toJsonString()))
                         put("targetRole", JsonPrimitive(event.targetRole.toJsonString()))
                         put("applied", JsonPrimitive(cascadeApply.success))
+                        cascadeApply.item?.statusLabel?.let { put("statusLabel", JsonPrimitive(it)) }
                     })
 
                     if (!cascadeApply.success || cascadeApply.item == null) break
@@ -421,6 +425,7 @@ Trigger-based role transitions for WorkItems with validation, cascade detection,
                 put("previousRole", JsonPrimitive(previousRole.toJsonString()))
                 put("newRole", JsonPrimitive(targetRole.toJsonString()))
                 put("trigger", JsonPrimitive(trigger))
+                applyResult.item?.statusLabel?.let { put("statusLabel", JsonPrimitive(it)) }
                 put("applied", JsonPrimitive(true))
                 if (summary != null) put("summary", JsonPrimitive(summary))
                 put("cascadeEvents", JsonArray(cascadeJsonList))
@@ -475,7 +480,7 @@ Trigger-based role transitions for WorkItems with validation, cascade detection,
 
             val cascadeApply = handler.applyTransition(
                 parentItem, event.targetRole, "cascade",
-                summary, null,
+                summary, context.statusLabelService().resolveLabel("cascade"),
                 context.workItemRepository(),
                 context.roleTransitionRepository()
             )
@@ -486,6 +491,7 @@ Trigger-based role transitions for WorkItems with validation, cascade detection,
                 put("previousRole", JsonPrimitive(event.currentRole.toJsonString()))
                 put("targetRole", JsonPrimitive(event.targetRole.toJsonString()))
                 put("applied", JsonPrimitive(cascadeApply.success))
+                cascadeApply.item?.statusLabel?.let { put("statusLabel", JsonPrimitive(it)) }
             })
         }
     }