jpicklyk
diff --git a/‎.claude-plugin/marketplace.json‎
Lines changed: 1 addition & 1 deletion b/‎.claude-plugin/marketplace.json‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎CHANGELOG.md‎
Lines changed: 14 additions & 0 deletions b/‎CHANGELOG.md‎
Lines changed: 14 additions & 0 deletions
diff --git a/‎claude-plugins/CLAUDE.md‎
Lines changed: 1 addition & 1 deletion b/‎claude-plugins/CLAUDE.md‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎claude-plugins/task-orchestrator/.claude-plugin/plugin.json‎
Lines changed: 1 addition & 1 deletion b/‎claude-plugins/task-orchestrator/.claude-plugin/plugin.json‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎claude-plugins/task-orchestrator/skills/manage-schemas/references/example-schemas.md‎
Lines changed: 15 additions & 0 deletions b/‎claude-plugins/task-orchestrator/skills/manage-schemas/references/example-schemas.md‎
Lines changed: 15 additions & 0 deletions
diff --git a/‎current/src/main/kotlin/io/github/jpicklyk/mcptask/current/application/service/CascadeDetector.kt‎
Lines changed: 18 additions & 0 deletions b/‎current/src/main/kotlin/io/github/jpicklyk/mcptask/current/application/service/CascadeDetector.kt‎
Lines changed: 18 additions & 0 deletions
diff --git a/‎current/src/main/kotlin/io/github/jpicklyk/mcptask/current/application/service/NoteSchemaService.kt‎
Lines changed: 7 additions & 0 deletions b/‎current/src/main/kotlin/io/github/jpicklyk/mcptask/current/application/service/NoteSchemaService.kt‎
Lines changed: 7 additions & 0 deletions
diff --git a/‎current/src/main/kotlin/io/github/jpicklyk/mcptask/current/application/service/SchemaEntryJsonBuilder.kt‎
Lines changed: 69 additions & 0 deletions b/‎current/src/main/kotlin/io/github/jpicklyk/mcptask/current/application/service/SchemaEntryJsonBuilder.kt‎
Lines changed: 69 additions & 0 deletions
diff --git a/‎current/src/main/kotlin/io/github/jpicklyk/mcptask/current/application/tools/compound/CreateWorkTreeTool.kt‎
Lines changed: 11 additions & 42 deletions b/‎current/src/main/kotlin/io/github/jpicklyk/mcptask/current/application/tools/compound/CreateWorkTreeTool.kt‎
Lines changed: 11 additions & 42 deletions
diff --git a/‎current/src/main/kotlin/io/github/jpicklyk/mcptask/current/application/tools/items/CreateItemHandler.kt‎
Lines changed: 4 additions & 17 deletions b/‎current/src/main/kotlin/io/github/jpicklyk/mcptask/current/application/tools/items/CreateItemHandler.kt‎
Lines changed: 4 additions & 17 deletions
@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "task-orchestrator",
-      "version": "2.7.2",
+      "version": "2.7.3",
       "description": "Skills, hooks, and workflows for MCP Task Orchestrator. Schema-aware context, note-driven workflow, and session hooks.",
       "author": {
         "name": "Jeff Picklyk",
 
@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.5.2] - 2026-04-03 (Plugin v2.7.3)
+
+### Fixed
+- Fixed `manage_items` create response to always include `expectedNotes` and `schemaMatch` fields — agents no longer need a separate `get_context` call after item creation
+
+### Improved
+- Unified schema-to-JSON serialization across `manage_items`, `create_work_tree`, `advance_item`, and `get_context` via shared `SchemaEntryJsonBuilder`
+- Added structured warning collection to schema config loading — config issues are surfaced programmatically via `getLoadWarnings()` instead of silently logged
+- Deduplicated WorkTreeService insert/upsert logic with shared repository helpers
+- Expanded test coverage across 12 identified gaps — WorkTreeService rollback, cascade detection, schema loading edge cases, note preservation, and gate lifecycle
+- Bumped plugin version to 2.7.3 — added `container` schema example to manage-schemas skill
+
+---
+
 ## [2.5.1] - 2026-03-31 (Plugin v2.7.2)
 
 ### Fixed
 
@@ -10,7 +10,7 @@ removing and re-adding the marketplace in Claude Code. No version bump is needed
 
 | Plugin | Directory | Current Version |
 |--------|-----------|-----------------|
-| `task-orchestrator` | `claude-plugins/task-orchestrator/` | `2.7.2` |
+| `task-orchestrator` | `claude-plugins/task-orchestrator/` | `2.7.3` |
 
 > Updated automatically by `/prepare-release`. Do not bump manually.
 
 
@@ -1,6 +1,6 @@
 {
   "name": "task-orchestrator",
-  "version": "2.7.2",
+  "version": "2.7.3",
   "description": "Claude Code integration for MCP Task Orchestrator — schema-aware context, note-driven workflow",
   "skills": "./skills",
   "hooks": "./hooks/hooks-config.json",
 
@@ -91,6 +91,21 @@ bug-fix:
     guidance: "Run tests and report results. Note if a new test was added to cover the fix."
 ```
 
+## `container` (gate-free organizational grouping)
+
+Schema for root-level category containers (Features, Bugs, Tech Debt, etc.) that exist only to group child work items. No required notes at any phase — containers advance freely without gate friction. Without this, containers fall back to the `default` schema and get gated on notes like `session-tracking` that make no sense for organizational items.
+
+```yaml
+container:
+  - key: container-summary
+    role: queue
+    required: false
+    description: "Optional high-level description of what this container organizes."
+    guidance: "Brief description of the container's purpose and scope. Not required — containers exist to group work items, not to carry implementation detail."
+```
+
+Tag root containers with `container` so they match this schema instead of `default`.
+
 ## `agent-observation` (queue only, minimal)
 
 Single-note schema for lightweight tracking — no work phase gates.
 
@@ -40,6 +40,24 @@ data class UnblockedItem(
  *
  * 2. **Unblock detection** -- when a WorkItem transitions, find any downstream items
  *    whose incoming blocking dependencies are now fully satisfied.
+ *
+ * ## Transaction-gap caveat
+ *
+ * Detection and application are intentionally **separate transactions**. The detect phase
+ * reads a snapshot of DB state, computes which cascade events are warranted, and returns
+ * them to the caller. The caller then applies each event in its own transaction. No single
+ * transaction spans both detect and apply.
+ *
+ * In theory this creates a window where concurrent writers could observe stale state
+ * (e.g. a sibling's role changes between detect and apply). In practice SQLite's
+ * single-writer model means only one write can proceed at a time, which eliminates
+ * the concurrency risk for the common deployment scenario.
+ *
+ * For multi-level hierarchies (child → parent → grandparent), [AdvanceItemTool]
+ * compensates with an **iterative detect-apply loop**: after each cascade event is
+ * applied and persisted, detection is re-run on the newly advanced item with fresh
+ * DB state. This ensures each level's decision is based on accurate, up-to-date data.
+ * The split-transaction design is intentional — not a bug.
  */
 class CascadeDetector {
     companion object {
 
@@ -25,6 +25,13 @@ interface NoteSchemaService {
      * Returns false when no schema matches (schema-free mode — skip REVIEW).
      */
     fun hasReviewPhase(tags: List<String>): Boolean = getSchemaForTags(tags)?.any { it.role == Role.REVIEW } ?: false
+
+    /**
+     * Returns any warnings collected during schema loading (e.g., malformed entries,
+     * missing required fields). Returns an empty list if no warnings were generated or
+     * if this implementation does not support warning collection.
+     */
+    fun getLoadWarnings(): List<String> = emptyList()
 }
 
 /**
 
@@ -0,0 +1,69 @@
+package io.github.jpicklyk.mcptask.current.application.service
+
+import io.github.jpicklyk.mcptask.current.application.tools.toJsonString
+import io.github.jpicklyk.mcptask.current.domain.model.NoteSchemaEntry
+import io.github.jpicklyk.mcptask.current.domain.model.Role
+import kotlinx.serialization.json.*
+
+/**
+ * Result of schema lookup + JSON serialization for tool responses.
+ *
+ * @property schemaMatch True when the item's tags matched a configured note schema.
+ * @property expectedNotes JSON array of schema entries, empty when no schema matched.
+ */
+data class SchemaResponseFields(
+    val schemaMatch: Boolean,
+    val expectedNotes: JsonArray
+)
+
+/**
+ * Build expectedNotes JSON array from schema entries.
+ *
+ * Supports three shapes:
+ * - Shape 1 (creation): exists=false for all, no filled field
+ * - Shape 2 (transition): exists checked against existingNoteKeys
+ * - Shape 3 (context): exists + filled checked against notes
+ *
+ * @param schema Schema entries, or null if no schema matches
+ * @param existingNoteKeys Keys of notes that exist (empty = all false)
+ * @param filledNoteKeys Keys of notes with non-blank body, or null to omit "filled" field
+ * @param filterRole If non-null, only include entries matching this role
+ */
+fun buildExpectedNotesJson(
+    schema: List<NoteSchemaEntry>?,
+    existingNoteKeys: Set<String> = emptySet(),
+    filledNoteKeys: Set<String>? = null,
+    filterRole: Role? = null
+): JsonArray {
+    if (schema == null) return JsonArray(emptyList())
+    val entries = if (filterRole != null) schema.filter { it.role == filterRole } else schema
+    return JsonArray(
+        entries.map { entry ->
+            buildJsonObject {
+                put("key", JsonPrimitive(entry.key))
+                put("role", JsonPrimitive(entry.role.toJsonString()))
+                put("required", JsonPrimitive(entry.required))
+                put("description", JsonPrimitive(entry.description))
+                entry.guidance?.let { put("guidance", JsonPrimitive(it)) }
+                put("exists", JsonPrimitive(entry.key in existingNoteKeys))
+                if (filledNoteKeys != null) {
+                    put("filled", JsonPrimitive(entry.key in filledNoteKeys))
+                }
+            }
+        }
+    )
+}
+
+/**
+ * Build both schemaMatch and expectedNotes for tool responses.
+ * Convenience wrapper for creation responses (exists=false, no filled).
+ *
+ * @param schema Schema entries, or null if no schema matches
+ */
+fun buildSchemaResponseFields(
+    schema: List<NoteSchemaEntry>?
+): SchemaResponseFields =
+    SchemaResponseFields(
+        schemaMatch = schema != null,
+        expectedNotes = buildExpectedNotesJson(schema)
+    )
@@ -2,6 +2,7 @@ package io.github.jpicklyk.mcptask.current.application.tools.compound
 
 import io.github.jpicklyk.mcptask.current.application.service.TreeDepSpec
 import io.github.jpicklyk.mcptask.current.application.service.WorkTreeInput
+import io.github.jpicklyk.mcptask.current.application.service.buildSchemaResponseFields
 import io.github.jpicklyk.mcptask.current.application.tools.*
 import io.github.jpicklyk.mcptask.current.domain.model.*
 import io.github.jpicklyk.mcptask.current.domain.repository.Result
@@ -351,68 +352,36 @@ Atomically create a hierarchical work tree: root item, child items, dependencies
         val idToRef = treeResult.refToId.entries.associate { (ref, id) -> id to ref }
 
         val rootResultItem = treeResult.items.first()
+        val rootSchemaFields = buildSchemaResponseFields(
+            context.noteSchemaService().getSchemaForTags(rootResultItem.tagList())
+        )
         val rootJson =
             buildJsonObject {
                 put("id", JsonPrimitive(rootResultItem.id.toString()))
                 put("title", JsonPrimitive(rootResultItem.title))
                 put("role", JsonPrimitive(rootResultItem.role.toJsonString()))
                 put("depth", JsonPrimitive(rootResultItem.depth))
                 rootResultItem.tags?.let { put("tags", JsonPrimitive(it)) }
-                // Add expectedNotes from schema
-                rootResultItem.tags?.let { tags ->
-                    val schemaEntries = context.noteSchemaService().getSchemaForTags(rootResultItem.tagList())
-                    if (!schemaEntries.isNullOrEmpty()) {
-                        put(
-                            "expectedNotes",
-                            JsonArray(
-                                schemaEntries.map { entry ->
-                                    buildJsonObject {
-                                        put("key", JsonPrimitive(entry.key))
-                                        put("role", JsonPrimitive(entry.role.toJsonString()))
-                                        put("required", JsonPrimitive(entry.required))
-                                        put("description", JsonPrimitive(entry.description))
-                                        entry.guidance?.let { put("guidance", JsonPrimitive(it)) }
-                                        put("exists", JsonPrimitive(false))
-                                    }
-                                }
-                            )
-                        )
-                    }
-                }
+                put("schemaMatch", JsonPrimitive(rootSchemaFields.schemaMatch))
+                put("expectedNotes", rootSchemaFields.expectedNotes)
             }
 
         val childrenJson =
             JsonArray(
                 treeResult.items.drop(1).map { item ->
                     val ref = idToRef[item.id] ?: "unknown"
+                    val childSchemaFields = buildSchemaResponseFields(
+                        context.noteSchemaService().getSchemaForTags(item.tagList())
+                    )
                     buildJsonObject {
                         put("ref", JsonPrimitive(ref))
                         put("id", JsonPrimitive(item.id.toString()))
                         put("title", JsonPrimitive(item.title))
                         put("role", JsonPrimitive(item.role.toJsonString()))
                         put("depth", JsonPrimitive(item.depth))
                         item.tags?.let { put("tags", JsonPrimitive(it)) }
-                        // Add expectedNotes from schema
-                        item.tags?.let {
-                            val schemaEntries = context.noteSchemaService().getSchemaForTags(item.tagList())
-                            if (!schemaEntries.isNullOrEmpty()) {
-                                put(
-                                    "expectedNotes",
-                                    JsonArray(
-                                        schemaEntries.map { entry ->
-                                            buildJsonObject {
-                                                put("key", JsonPrimitive(entry.key))
-                                                put("role", JsonPrimitive(entry.role.toJsonString()))
-                                                put("required", JsonPrimitive(entry.required))
-                                                put("description", JsonPrimitive(entry.description))
-                                                entry.guidance?.let { put("guidance", JsonPrimitive(it)) }
-                                                put("exists", JsonPrimitive(false))
-                                            }
-                                        }
-                                    )
-                                )
-                            }
-                        }
+                        put("schemaMatch", JsonPrimitive(childSchemaFields.schemaMatch))
+                        put("expectedNotes", childSchemaFields.expectedNotes)
                     }
                 }
             )
 
@@ -1,6 +1,7 @@
 package io.github.jpicklyk.mcptask.current.application.tools.items
 
 import io.github.jpicklyk.mcptask.current.application.service.ItemHierarchyValidator
+import io.github.jpicklyk.mcptask.current.application.service.buildSchemaResponseFields
 import io.github.jpicklyk.mcptask.current.application.tools.ResponseUtil
 import io.github.jpicklyk.mcptask.current.application.tools.ToolExecutionContext
 import io.github.jpicklyk.mcptask.current.application.tools.ToolValidationException
@@ -138,6 +139,7 @@ class CreateItemHandler(
                                 ?.filter { it.isNotBlank() }
                                 ?: emptyList()
                         val schemaEntries = context.noteSchemaService().getSchemaForTags(tagList)
+                        val schemaFields = buildSchemaResponseFields(schemaEntries)
                         createdItems.add(
                             buildJsonObject {
                                 put("id", JsonPrimitive(result.data.id.toString()))
@@ -151,23 +153,8 @@ class CreateItemHandler(
                                 } else {
                                     put("tags", JsonNull)
                                 }
-                                if (!schemaEntries.isNullOrEmpty()) {
-                                    put(
-                                        "expectedNotes",
-                                        JsonArray(
-                                            schemaEntries.map { entry ->
-                                                buildJsonObject {
-                                                    put("key", JsonPrimitive(entry.key))
-                                                    put("role", JsonPrimitive(entry.role.toJsonString()))
-                                                    put("required", JsonPrimitive(entry.required))
-                                                    put("description", JsonPrimitive(entry.description))
-                                                    entry.guidance?.let { put("guidance", JsonPrimitive(it)) }
-                                                    put("exists", JsonPrimitive(false))
-                                                }
-                                            }
-                                        )
-                                    )
-                                }
+                                put("schemaMatch", JsonPrimitive(schemaFields.schemaMatch))
+                                put("expectedNotes", schemaFields.expectedNotes)
                             }
                         )
                     }
Original file line number	Diff line number	Diff line change
`@@ -10,7 +10,7 @@`
`10`	`10`	`"plugins": [`
`11`	`11`	`{`
`12`	`12`	`"name": "task-orchestrator",`
`13`		`- "version": "2.7.2",`
	`13`	`+ "version": "2.7.3",`
`14`	`14`	`"description": "Skills, hooks, and workflows for MCP Task Orchestrator. Schema-aware context, note-driven workflow, and session hooks.",`
`15`	`15`	`"author": {`
`16`	`16`	`"name": "Jeff Picklyk",`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "task-orchestrator",`
`3`		`- "version": "2.7.2",`
	`3`	`+ "version": "2.7.3",`
`4`	`4`	`"description": "Claude Code integration for MCP Task Orchestrator — schema-aware context, note-driven workflow",`
`5`	`5`	`"skills": "./skills",`
`6`	`6`	`"hooks": "./hooks/hooks-config.json",`