release: v2.5.1 — fix IS_BLOCKED_BY enforcement in advance_item (#89) (#89)

* feat(plugin): add tiered execution model (Direct/Delegated/Parallel)

Output style now classifies work into three tiers with proportional
process. Direct tier (1-2 files, known fix) implements inline — no
subagent dispatch, no plan mode, no separate review. Delegated and
Parallel tiers preserve the full pipeline.

Changes:
- workflow-orchestrator.md: tier classification section, conditional
  principles, Direct Tier Workflow section, frontmatter added, removed
  project-specific references (session-retrospective, quick-fix schema,
  gradlew), removed redundant delegation templates
- implement skill: tier-conditional Steps 1/3/4/5, two-dimensional
  classification (tier + interaction mode), resume-with-tier-awareness
- pre-plan.mjs: Direct tier safety net message

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* refactor(plugin): trim workflow-orchestrator to universally valuable content

Remove project-specific details, redundant templates, and niche
operational guidance. Condense worktree dispatch to 4 universal
principles, session tasks to one line, completion format to inline.
Drop schema tag row, delegation metadata section, return format
templates, and guidancePointer rendering convention.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* chore(plugin): minor cleanup — schema context in implement skill, analyst zone updates

- Implement skill: add schema context to session-tracking note reference
- Workflow-analyst Zone 2: add Delegation Metadata section, tier-aware
  Parallel Dispatch reference
- Workflow-analyst Zone 3: replace stale manifest monitoring with tier
  classification monitoring, connect analysis layer to /session-retrospective

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* refactor(plugin): strengthen planning hooks and enforce WHAT/HOW separation

Planning hooks now use imperative gate language (PREREQUISITE/MUST/NEXT STEP)
instead of suggestive phrasing that lost attention competition with plan mode.
Output style trimmed to WHAT-level principles — procedural HOW detail moved to
skills where it belongs. Worktree Dispatch section removed (prescriptive technique,
not a principle). Skills get explicit handoff sections for clean control flow.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: enforce IS_BLOCKED_BY deps in advance_item and unblock detection

IS_BLOCKED_BY dependencies were checked by get_blocked_items and
get_next_item but silently ignored by advance_item (validateTransition)
and CascadeDetector (findUnblockedItems/isFullyUnblocked). This meant
agents could advance items past IS_BLOCKED_BY gates that the read-only
tools correctly reported as blocked.

- RoleTransitionHandler.validateTransition now queries findByFromItemId
  for outgoing IS_BLOCKED_BY edges in addition to findByToItemId for
  incoming BLOCKS edges
- CascadeDetector.findUnblockedItems discovers IS_BLOCKED_BY targets
  via findByToItemId (incoming IS_BLOCKED_BY on the transitioning item)
- CascadeDetector.isFullyUnblocked checks outgoing IS_BLOCKED_BY edges
  on the target item via findByFromItemId
- All existing tests updated with explicit dep mocks (no relaxed defaults)
- Added IS_BLOCKED_BY coverage for GetBlockedItemsTool, GetNextItemTool,
  and GetNextStatusTool (satisfied, unsatisfied, mixed, custom unblockAt)
- Fixed reversed dependency example in quick-start.md

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* refactor(plugin): improve manage-schemas templates and guidance generation

- Updated feature-implementation and bug-fix schema templates to align
  with spec-quality and review-quality frameworks
- Added guidance generation rules (lead with consumer, structure over
  prose, concrete over generic, session-tracking prompt)
- Added cross-schema duplication check when editing guidance values
- Companion template now preserves markdown formatting in guidance text

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* release: bump to v2.5.1 — plugin v2.7.2

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* style: fix ktlint multiline expression formatting

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

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

Author: jpicklyk

.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "task-orchestrator",
-      "version": "2.7.1",
+      "version": "2.7.2",
       "description": "Skills, hooks, and workflows for MCP Task Orchestrator. Schema-aware context, note-driven workflow, and session hooks.",
       "author": {
         "name": "Jeff Picklyk",

CHANGELOG.md

@@ -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.1] - 2026-03-31 (Plugin v2.7.2)
+
+### Fixed
+- Fixed `IS_BLOCKED_BY` dependencies not being enforced by `advance_item` — items could advance past IS_BLOCKED_BY gates that `get_blocked_items` and `get_next_item` correctly reported as blocked
+- Fixed `advance_item` unblock detection not discovering items with IS_BLOCKED_BY edges when their blocker completes
+- Fixed reversed dependency example in quick-start documentation
+
+### Changed
+- Improved manage-schemas skill templates to align with spec-quality and review-quality frameworks
+- Added guidance generation rules and cross-schema duplication checks to manage-schemas edit workflow
+- Bumped plugin version to 2.7.2
+
+---
+
 ## [2.5.0] - 2026-03-30 (Plugin v2.7.1)
 
 ### Changed

claude-plugins/CLAUDE.md

@@ -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.1` |
+| `task-orchestrator` | `claude-plugins/task-orchestrator/` | `2.7.2` |
 
 > Updated automatically by `/prepare-release`. Do not bump manually.
 

claude-plugins/task-orchestrator/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "task-orchestrator",
-  "version": "2.7.1",
+  "version": "2.7.2",
   "description": "Claude Code integration for MCP Task Orchestrator — schema-aware context, note-driven workflow",
   "skills": "./skills",
   "hooks": "./hooks/hooks-config.json",

claude-plugins/task-orchestrator/skills/manage-schemas/references/companion-template.md

@@ -2,7 +2,7 @@
 
 Use this template when the user requests a companion skill in Step 4. Write to `.claude/skills/<schema-name>/SKILL.md`. Create the directory if it doesn't exist. This is a project-local skill available immediately as `/<schema-name>` — no plugin version bump required.
 
-Replace all `<placeholders>` with actual values from the schema built in Steps 1-2.
+Replace all `<placeholders>` with actual values from the schema built in Steps 1-2. Guidance text from the schema may contain markdown (bold headers, bullet points). Render it verbatim in the `**What to write:**` line — do not reformat.
 
 ---
 

claude-plugins/task-orchestrator/skills/manage-schemas/references/create-workflow.md

@@ -12,10 +12,10 @@ Otherwise, ask via `AskUserQuestion`:
 
 ```
 ◆ How would you like to create the schema?
-  1. Feature implementation — full lifecycle with design gates, implementation evidence,
-     and optional deploy verification (5 notes across queue/work/review)
-  2. Bug fix — lightweight schema for bug fixes: root cause before code,
-     verification after (4 notes across queue/work)
+  1. Feature implementation — specification gate (queue), implementation evidence
+     + session tracking (work), review checklist (review) — 4 notes
+  2. Bug fix — diagnosis gate (queue), implementation evidence + session tracking (work),
+     review checklist (review) — 4 notes
   3. Start from scratch — answer questions to build a custom schema
 ```
 
@@ -29,31 +29,26 @@ Show this schema to the user:
 
 ```yaml
 feature-implementation:
-  - key: requirements
+  - key: specification
     role: queue
     required: true
-    description: "Problem statement and acceptance criteria."
-    guidance: "Describe what problem this solves and who benefits. List 2-5 concrete acceptance criteria that define done."
-  - key: design
-    role: queue
-    required: true
-    description: "Chosen approach, alternatives considered, key risks."
-    guidance: "Explain the implementation approach. Note any alternatives you ruled out and why. Call out risks or constraints."
+    description: "Problem statement, approach, and pre-work plan."
+    guidance: "This note is read by the implementation agent before writing code. Cover: **Problem statement** — what breaks or is missing, who is affected. **Acceptance criteria** — 2-5 concrete, testable criteria that define done. **Alternatives considered** — min 2 real options plus 'do nothing'; for each, state the trade-off that ruled it out (not strawman rejections). **Non-goals** — at least one thing a reader might expect this work to include that is deliberately excluded. **Blast radius** — every file, module, and interface the change touches; trace downstream consumers. **Risk flags** — the 1-2 things most likely to go wrong. **Test strategy** — name specific scenarios for happy paths, failure paths, and edge cases; 'add tests' is not a strategy."
   - key: implementation-notes
     role: work
     required: true
-    description: "Key decisions made during implementation, deviations from design."
-    guidance: "Document any surprises, wrong-turns, or deviations from the planned approach."
-  - key: test-results
+    description: "Context handoff for downstream agents — deviations, surprises, decisions."
+    guidance: "This note is read by review agents and dependent tasks. They need to know: what decisions were made that weren't in the specification, which files were changed and why, any API or interface surprises encountered, assumptions from the specification that turned out wrong, and patterns discovered that affect dependent work."
+  - key: session-tracking
     role: work
     required: true
-    description: "Test pass/fail count and any new tests added."
-    guidance: "Run tests and report total count and failures. List any new test classes or test cases added."
-  - key: deploy-notes
+    description: "Session context — what was done, how it went, anything the retrospective should know."
+    guidance: "This note feeds retrospective analysis. Structure: **Outcome**: success | partial | failure. **Files changed**: list with one-line rationale each. **Deviations**: anything that differed from the specification. **Friction**: tool errors, unexpected roundtrips, API confusion — include type (optimization/friction/bug/missing-capability) and description. **Test results**: pass/fail counts, new tests added."
+  - key: review-checklist
     role: review
-    required: false
-    description: "Deploy needed? Version bump? Reconnect required?"
-    guidance: "Note whether a rebuild/deploy was done, what version was bumped to, and whether reconnect was required."
+    required: true
+    description: "Quality gate — plan alignment, test quality, simplification, verdict."
+    guidance: "Run the test suite first — record total count and pass/fail. Then verify: (1) **Plan alignment** — walk each acceptance criterion from the specification and identify the code that satisfies it; flag criteria with no implementation and unplanned changes with no justification. (2) **Test quality** — map tests to the specification's test strategy; watch for tautological assertions, mock-heavy tests that verify nothing real, happy-path-only coverage when failure paths were required, and overly broad assertions like 'result != null'. (3) **Simplification** — note any unnecessary complexity, duplication, or over-engineering in changed files (do not apply fixes, only report). End with a verdict: **Pass** | **Fail — blocking issues** (list each) | **Pass with observations**."
 ```
 
 ### Bug Fix Template
@@ -62,26 +57,26 @@ Show this schema to the user:
 
 ```yaml
 bug-fix:
-  - key: reproduction-steps
+  - key: diagnosis
     role: queue
     required: true
-    description: "Step-by-step reproduction with expected vs actual result."
-    guidance: "Include the exact steps or tool call that triggers the bug. State expected output and actual output."
-  - key: root-cause
-    role: queue
-    required: true
-    description: "Why it happens — file, line, and condition."
-    guidance: "Identify the specific file and function where the defect lives. Explain the condition that triggers it."
-  - key: fix-summary
+    description: "Reproduction, root cause, fix approach, and test strategy."
+    guidance: "This note is read by the implementation agent before writing code. Cover: **Reproduction steps** — exact inputs (tool call, parameters, or user action) plus expected output and actual output. **Root cause** — the specific file, function, and condition that causes the bug; state why that code path produces the wrong result. **Fix approach** — your chosen approach plus min 2 alternatives (including 'do nothing'); for each, state the trade-off that ruled it out. **Blast radius** — files and interfaces the fix touches; similar code paths that may have the same defect. **Test strategy** — a regression test that would have caught the original bug, plus edge cases around the fix boundary."
+  - key: implementation-notes
     role: work
     required: true
-    description: "What was changed and which files were modified."
-    guidance: "List each file changed and summarize the change. Note any patterns that should be applied elsewhere."
-  - key: test-verification
+    description: "Context handoff — what changed, deviations from diagnosis, patterns to apply."
+    guidance: "This note is read by review agents and dependent tasks. State: which files changed and what the specific change was, whether the root cause matched the diagnosis or differed (and how), patterns found in similar code paths that should be applied elsewhere, and edge cases discovered during implementation that weren't in the diagnosis."
+  - key: session-tracking
     role: work
     required: true
-    description: "How the fix was verified and test results after fix."
-    guidance: "Run tests and report results. Note if a new test was added to cover the fix."
+    description: "Session context — what was done, how it went, anything the retrospective should know."
+    guidance: "This note feeds retrospective analysis. Structure: **Outcome**: success | partial | failure. **Files changed**: list with one-line rationale each. **Deviations**: anything that differed from the diagnosis. **Friction**: tool errors, unexpected roundtrips, API confusion — include type (optimization/friction/bug/missing-capability) and description. **Test results**: pass/fail counts, new tests added."
+  - key: review-checklist
+    role: review
+    required: true
+    description: "Quality gate — fix alignment, regression coverage, simplification, verdict."
+    guidance: "Run the test suite first — record total count and pass/fail. Then verify: (1) **Fix alignment** — confirm the fix addresses the diagnosed root cause and does not merely mask symptoms; check implementation-notes for any deviation from the diagnosis. (2) **Regression test** — a test must exist that would have caught the original bug; verify it tests the actual failure condition, not just 'result != null'. (3) **Edge case coverage** — verify tests exist for edge cases named in the diagnosis test strategy. (4) **Simplification** — note any unnecessary complexity in changed files (do not apply fixes, only report). End with a verdict: **Pass** | **Fail — blocking issues** (list each) | **Pass with observations**."
 ```
 
 ### After showing the template
@@ -135,11 +130,24 @@ Using answers from the gathering step, produce the YAML block. Apply these defau
 - First queue note's `guidance` should open with: `"Run /<schema-name> for the full lifecycle guide. For this note: <specific guidance>."` if a companion skill will be created
 - Use kebab-case for all keys
 - Keep `description` values under 80 chars
+- If a `session-tracking` note was added, use the standard structured guidance (see rule 4 below)
 
 Show the generated YAML to the user and ask for confirmation before writing.
 
 For YAML format reference and field rules, see `references/config-format.md` in this skill folder.
 
+### Guidance Generation Rules
+
+Apply these four disciplines when writing `guidance` values for any note — whether from a template customization or from-scratch Q&A:
+
+1. **Lead with the consumer.** Open with who reads this note and what they need from it. Example: "This note is read by the review agent. They need to know which files changed and whether the implementation matches the specification."
+
+2. **Structure over prose.** If the note covers 3 or more topics, use bold section headers (`**Header**`) rather than a prose paragraph. Agents and reviewers scan — they don't read walls of text.
+
+3. **Concrete over generic.** Specify the actual verification action, not the category. "State which files changed and the specific function modified" instead of "describe the approach." "Name specific test scenarios for happy paths and failure paths" instead of "add tests."
+
+4. **Session-tracking prompt.** If the schema includes a work phase, ask: "Most schemas include a session-tracking note (work phase) for retrospective analysis. Add one? [Yes/No]" If yes, use this standard guidance: `"This note feeds retrospective analysis. Structure: **Outcome**: success | partial | failure. **Files changed**: list with one-line rationale each. **Deviations**: from plan or diagnosis. **Friction**: tool errors, unexpected roundtrips, API confusion — include type (optimization/friction/bug/missing-capability) and description. **Test results**: pass/fail counts, new tests added."`
+
 ---
 
 ## Step 4 — Write Config

claude-plugins/task-orchestrator/skills/manage-schemas/references/edit-workflow.md

@@ -44,6 +44,12 @@ What would you like to change?
 Ask for: key (kebab-case), role (queue/work/review), required (yes/no), description (under 80 chars), guidance (optional).
 Append the new note entry to the schema's list in the correct role group.
 
+When writing guidance for the new note, apply these generation rules:
+- **Lead with the consumer** — open with who reads this note and what they need from it
+- **Structure over prose** — use bold section headers (`**Header**`) if the note covers 3 or more topics
+- **Concrete over generic** — "state which files changed" not "describe the approach"
+- If adding a `session-tracking` note, offer the standard structured guidance: `"This note feeds retrospective analysis. Structure: **Outcome**: success | partial | failure. **Files changed**: list with one-line rationale each. **Deviations**: from plan or diagnosis. **Friction**: tool errors, unexpected roundtrips, API confusion — include type and description. **Test results**: pass/fail counts, new tests added."`
+
 ### Remove a Note
 Show numbered list, ask which to remove. Warn: "Existing notes on items under this key will become orphaned ad-hoc notes — they won't be deleted but will no longer be schema-enforced."
 Remove the entry from the YAML list.
@@ -56,6 +62,30 @@ Warn if toggling to required: "Items that have already passed this phase without
 Show current value, ask for the new value. Apply.
 Remind: descriptions should stay under 80 chars.
 
+#### Cross-Schema Duplication Check
+
+After the user provides a new guidance value, scan all schemas in `.taskorchestrator/config.yaml` for notes with the **same key name** (e.g., `session-tracking`, `implementation-notes`).
+
+If any other schema contains a note with the same key:
+1. Compare guidance text — classify as **identical** (exact match), **near-identical** (same structure, minor wording differences), or **different**
+2. Present the finding:
+
+```
+◆ This key also appears in other schemas:
+  - "feature-task" → session-tracking (guidance is identical)
+  - "bug-fix" → session-tracking (guidance is near-identical)
+
+Update all instances?
+  1. Yes — update all to the new value
+  2. No — only update this schema
+  3. Show me the differences first
+```
+
+3. If the user selects "Show me the differences", display the current schema's old value alongside each other schema's current value, then re-ask
+4. Apply based on choice — when updating all, report each schema updated in the Write Back summary
+
+This check triggers on **key name match** regardless of guidance similarity. The value is catching drift cases where the same concept (e.g., `session-tracking`) has diverged across schemas over time.
+
 ### Rename Key
 Show current key, ask for the new key name.
 **WARNING:** "Renaming a key orphans all existing notes written under the old key name. Those notes will remain on their items as ad-hoc notes but will no longer match the schema. There is no automatic migration. Proceed?"

current/docs/quick-start.md

@@ -218,8 +218,8 @@ create_work_tree(
     {ref: "tests",  title: "Integration tests"}
   ],
   deps=[
-    {from: "tests", to: "api"},
-    {from: "tests", to: "ui"}
+    {from: "api",   to: "tests"},
+    {from: "ui",    to: "tests"}
   ]
 )