Skip to content

release: v2.0.1 — v3 architecture with circular parentId protection and BFS cycle fix#33

Merged
jpicklyk merged 138 commits intomainfrom
overhaul
Feb 19, 2026
Merged

release: v2.0.1 — v3 architecture with circular parentId protection and BFS cycle fix#33
jpicklyk merged 138 commits intomainfrom
overhaul

Conversation

@jpicklyk
Copy link
Owner

Summary

  • v3 complete rewrite: Unified WorkItem model replaces the Project → Feature → Task hierarchy with a single flexible entity (depth 0–3) and a role-based lifecycle engine (queue → work → review → terminal)
  • 13 MCP tools replacing the prior architecture — no migration path; fresh database required
  • Note schema gate system: YAML-configured schemas gate role transitions — required notes must be filled before advancing to the next workflow phase
  • HTTP transport: Ktor Streamable HTTP (MCP spec 2025-03-26) alongside stdio
  • SQLite WAL mode for concurrent multi-process read access
  • Claude Code plugin v1.0.14 with 6 skills and Workflow Analyst output style
  • Bug fixes (2.0.1): circular parentId guards, BFS cycle detection in ancestor chains, Docker version context fix

Version

2.0.0 → 2.0.1

Test plan

  • 1,637+ tests passing (0 failures, 0 errors, 0 skipped)
  • Docker build and deployment verified
  • All 13 MCP tools audited against implementation
  • Manual smoke test: work-summary, create-item skill, role transitions, dependency management
  • Real-world multi-session usage feedback (post-merge)

🤖 Prepared with /bump-version

jpicklyk and others added 30 commits November 5, 2025 14:15
Removed session-start hook from plugin architecture as it duplicates
functionality provided by orchestrator-prompt.txt system prompt.

Changes:
- Removed hook files: session-start.js, session-start.sh, hooks.json
- Updated plugin.json to remove hooks reference
- Updated documentation to remove hook sections
- Fixed project-setup-workflow.md with v2.0 tool syntax and template discovery
- Updated initialize-task-orchestrator.md to guide plugin installation
- Updated migration docs to document v2.1 hook removal

Benefits:
- Eliminates redundancy: single source of truth for orchestration guidance
- Token savings: ~600 tokens when using orchestrator mode
- Cleaner architecture: one comprehensive system prompt vs fragmented hooks
- Easier maintenance: update one file instead of syncing multiple sources

Orchestrator mode (via system prompt) is now the recommended approach,
providing both orchestration logic and communication style in one file.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

Remove features that Claude Code now provides natively, preserving the
MCP's unique value: persistent hierarchical storage, templates, rich
dependencies, token-optimized queries, and configurable status workflows.

Deleted resources (~55 skill files, 10 agent files, plugin, workflows,
output styles, config files). Removed 7 Kotlin tools: ListTagsTool,
GetTagUsageTool, RenameTagTool, QueryWorkflowStateTool, SetupProjectTool,
GetAgentDefinitionTool, RecommendAgentTool. Removed supporting services:
AgentRecommendationService, AgentDirectoryManager,
TaskOrchestratorConfigManager, AgentResources, WorkflowPromptsGuidance.

Updated McpServer.kt registration, simplified MCP resources and AI
guidance to remove Skills/Agent references.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
New MCP tool that provides a higher-level interface for status transitions
using named triggers (start, complete, cancel, block, hold) instead of
raw status values. Validates transitions against the workflow config,
checks prerequisites via StatusValidator, and detects cascade events
after applying changes.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add role annotations (queue, work, review, blocked, terminal) to status
definitions in default-config.yaml for all container types. Roles provide
semantic context for AI decision-making about workflow state.

Update NextStatusRecommendation.Ready with optional currentRole/nextRole
fields. StatusProgressionServiceImpl parses roles from config with
fallback inference from terminal/emergency status lists. GetNextStatusTool
includes roles in JSON output.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Remove ~400 lines of Skills, Agents, Orchestration Mode, Decision Gates,
and Specialist Routing content that referenced deleted features. Add
concise MCP Tools section documenting all 12 tools with usage patterns
for request_transition, scoped overview, and template discovery.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Delete claude-plugins/ directory (48 stale skill/agent files)
- Delete 7 orphaned tool docs and 6 stale doc files
- Update api-reference.md, quick-start.md, ai-guidelines.md, index.md
  to reflect current 12-tool architecture
- Remove unimplemented config sections (parallelism, automation, etc.)
- Add DEPLOYED status to ProjectStatus enum with V8 migration
- Add GetBlockedTasksTool unit tests (33 tests)
- Remove unused gradle deps (slf4j-nop, exposed-migration)

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

Templates now provide brief 4-7 line prompts telling the AI WHAT to
document rather than prescriptive multi-page workflows telling HOW to
plan. This preserves the template system's value (minimum required
sections) while allowing Claude's native planning to evolve freely.

Changes:
- Trim 6 template creators from ~930 lines of contentSample to ~110
- Rename 3 templates: Task Implementation Workflow → Task Implementation,
  Bug Investigation Workflow → Bug Investigation, Testing Strategy → Test Plan
- Delete 2 redundant sections: Technical Decision Log, Testing Checkpoints
- Change 2 sections to optional: Integration Considerations, Production Readiness
- Add V9 Flyway migration to update templates in existing databases
- Update TemplateInitializerImpl with new template names
- Update migration tests for new names, counts (26→24 sections), and titles

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

Replace the old MCP-tool-based deployment approach with a proper Claude Code
plugin at claude-plugins/task-orchestrator/. The plugin provides 4 lean skills
(task-orchestration, feature-orchestration, status-progression,
dependency-analysis), a SessionStart hook for auto-overview, and marketplace
distribution via the existing .claude-plugin/marketplace.json.

Also fixes ~60 stale pre-v2.0 tool name references across MCP resources and
prompts (list_templates, get_overview, create_task, etc.), adds missing
get_next_status and request_transition documentation resources, and adds YAML
frontmatter to deploy_to_docker command.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Adds an optional output style that transforms the main Claude session into
a pure orchestrator — strips coding instructions and adds delegation patterns.
Covers both standard subagents and experimental agent teams, with clear
distinction between MCP task orchestrator (persistent) and Claude Code
delegation (session-scoped).

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

Adds one-way mirroring from MCP Task Orchestrator tasks to Claude Code's
terminal task display (Ctrl+T). The output style deterministically requires
mirroring when active; the skill provides detailed mapping patterns (14 MCP
statuses → 3 CC statuses, dependency mirroring, metadata correlation).
Only tasks related to the current focus are mirrored, not the entire database.

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

Add deterministic reinforcement for three high-risk skill behaviors:
partial updates (never fetch-modify-save), cascade event handling
(check parent status after transitions), and feature completion
verification (all tasks done, sections reviewed before completing).
These ensure correct behavior even when skills don't probabilistically
activate.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
When a feature is completed or archived, its child tasks are transient
work items that have served their purpose. This adds a configurable
CompletionCleanupService that synchronously deletes child tasks (with
their sections and dependencies) during status transitions. Bug-tagged
tasks are retained for diagnostic value. Cleanup is config-gated via
completion_cleanup.enabled and respects existing terminal_statuses
from the workflow config to support custom flows.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Move default-config.yaml from resources/claude/configuration/ to
resources/configuration/ — the claude/ prefix was a holdover from
before the plugin migration. Delete empty hooks/ directory and
remove PLUGIN-STRUCTURE.md which referenced agents and files that
no longer exist. Update all 5 references (3 tests, 2 docs).

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

- Add .dockerignore to reduce build context from ~412MB to ~8MB
- Add non-root user (appuser:1001) to Dockerfile for security hardening
- Add OCI metadata labels to Docker image
- Optimize Dockerfile layer caching with dedicated dependency download step
- Make LOG_LEVEL env var functional via logback.xml variable substitution
- Modernize docker-compose.yml: add AGENT_CONFIG_DIR, project mount, resource
  limits, remove dead env vars (JAVA_TOOL_OPTIONS, MCP_DEBUG)
- Replace misleading docker-clean-and-build.bat with cross-platform
  docker-build.sh and docker-build.bat scripts
- Add Buildx, GHA cache, multi-platform (amd64/arm64), and Trivy scanning
  to CI/CD pipeline
- Remove dead MCP_DEBUG env var references across all documentation
- Update deploy skill, CLAUDE.md, installation guide, and troubleshooting docs

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Migrate Tool.Input/Tool.Output to ToolSchema (types package reorganization)
- Update all imports from sdk root to sdk.types subpackage
- Handle nullable request.arguments with fallback to empty JsonObject
- Rename _meta to meta in GetPromptResult (API change)
- Update Role.assistant to Role.Assistant (enum case change)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Install shadow-utils via dnf for groupadd/useradd support on Amazon Linux 2023
minimal images, and move git install before Gradle dependency download since
build.gradle.kts requires git at configuration time for version calculation.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Addresses arbitrary code execution vulnerability via conditional
configuration file processing (CVSS 5.9, medium severity).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The source field requires an object with source type and path, not a
plain string.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Fix MCP SDK version (0.7.2 -> 0.8.3)
- Fix Exposed ORM version (v1 -> 1.0.0-beta-2)
- Fix tool count (12 -> 13)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Rewrite Quick Start with two clear paths: Claude Code (plugin
  install) and Other MCP Clients (Docker pull + configure)
- Add GHCR MCP server declaration to plugin.json so plugin install
  includes the MCP server for Claude Code users
- Remove phantom references (setup_project, initialize_task_orchestrator)
- Fix MCP SDK version (0.7.2 -> 0.8.3) in Technical Stack
- Fix broken docs/plugin-installation.md link
- Reframe sub-agents as optional/configurable, not pre-packaged
- Add .mcp.json to .gitignore (local dev MCP config)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
StatusProgressionServiceImpl now loads the bundled default-config.yaml
from the classpath when no .taskorchestrator/config.yaml exists on the
filesystem. This ensures get_next_status and request_transition work
out of the box for new users without manual config setup.

Malformed user configs still fail explicitly (no silent fallback).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Audited all tool docs against source implementations and fixed ~80 discrepancies
across 12 of 13 tools. Key fixes: corrected status enum tables for all container
types, replaced old tool name references, fixed response field names and formats,
added missing response fields, removed phantom fields, added DEPRECATED notices.

Also: restructured plugin for dev use (removed bundled mcpServers), consolidated
session-start hook into plugin, updated README Quick Start and CONTRIBUTING.md
with accurate developer setup instructions.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Fix marketplace.json owner field to match schema (name only, no url)
- Remove broken extraKnownMarketplaces from settings.json (relative
  directory paths not resolved by Claude Code, filed #23978)
- Add explicit skills and hooks fields to plugin.json manifest
- Rename hooks.json to session-hooks.json to avoid conflict with
  auto-discovery convention while keeping explicit manifest declaration

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
GetNextTaskTool and GetBlockedTasksTool were incorrectly marked as
deprecated pointing to non-existent query_tasks queryType parameters.
Also fixes error code mapping in ManageContainerTool to return proper
VALIDATION_ERROR/NOT_FOUND/CONFLICT codes instead of generic DATABASE_ERROR,
and updates stale Related tool cross-references across tool descriptions.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
PreToolUse:EnterPlanMode hook guides the agent through structured planning:
template discovery, container sizing, user confirmation, and plan writing
with templates as the structural floor. PostToolUse:ExitPlanMode hook
materializes approved plans into MCP containers with UUIDs written back
into plan.md, dependency setup, and verification.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Git on Windows auto-converted LF to CRLF in shell scripts. The \r
characters embedded in JSON output caused Claude Code to show "hook
error" despite the context injection still working. Fixed all scripts
to LF and added .gitattributes to enforce LF for *.sh files.

Also updated hook scripts with refined planning workflow guidance:
templates as structural floor, multiSelect template confirmation,
and hookEventName field restored per docs.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Added matcher: "startup" to the SessionStart hook so it only fires on
new sessions. Previously it had no matcher, causing it to also fire on
context compaction which interrupted the agent's current work by
prompting a full project overview.

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

Add getRoleForStatus() to StatusProgressionService and include previousRole/
newRole fields in request_transition responses. Create two new plugin hooks:
- PostToolUse status-sync hook detects role boundary crossings and reminds
  the agent to update mirrored CC task status
- TaskCompleted hook enforces MCP-first completion order using a block-once
  pattern with temp file markers

Update task mirroring convention to prefix CC task subjects with [short-hash]
for visual correlation and hook-based identification. Update skills and output
style with CC-MCP sync guidance.

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

- Output style: 887→343 words (61% reduction). Removed sections duplicated
  by hooks (Session Start, Error Handling, Handoff) and skills (partial
  updates, cascade events). Keeps identity, response format, delegation
  pattern, and decision heuristics.

- task-mirroring skill: 836→300 words (64% reduction). Hooks handle
  post-transition sync (status-sync.sh) and completion enforcement
  (task-complete-sync.sh) deterministically. Skill now only covers
  bootstrapping — initial mirror creation, status mapping, and
  dependency mirroring.

- Cross-skill deduplication: Each concept now has a single owner skill.
  Status flows/triggers/tags → status-progression. CC mirror sync →
  task-mirroring. Partial updates → task-orchestration. Other skills
  reference the owner with one-liner pointers instead of repeating content.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…ation from all skills

New hooks:
- PostToolUse on manage_container: auto-prompts CC mirror creation for new tasks
- PostToolUseFailure on MCP tools: contextual error recovery guidance
- SubagentStop: prompts MCP task status sync when subagents reference MCP entities

SessionStart matcher expanded from "startup" to "startup|resume|compact" so MCP
state reloads on session resume and after context compaction.

New skills: template-management (manage_template, apply_template coverage),
project-orchestration (project-tier lifecycle coordination).

All 7 skills rewritten to remove verbose tool-call code blocks that duplicated
the 9.4k tokens of parameter documentation already provided by tool schemas.
Skills now contain only workflow patterns, decision heuristics, and key parameter
hints. Total skill word count: 1,828 words across 7 files.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
jpicklyk and others added 28 commits February 17, 2026 22:43
Closes a workflow gap: agents creating schema-tagged items had no way to
know which queue-phase notes to fill before advance_item(trigger=start),
forcing an extra get_context call or risking a gate block.

Changes:
- ManageItemsTool: after create, calls NoteSchemaService.getSchemaForTags()
  and includes tags (always) and expectedNotes (when schema matches) in
  each created item's response entry. expectedNotes omitted when no schema
  matches. exists is always false at creation time.
- ManageItemsToolTest: 3 new tests covering schema match, no tags, and
  tags with no matching schema
- CLAUDE.md: documented manage_items create response enrichment fields

618 tests passing.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…Summary, context limit

- search total now reflects full match count (countByFilters + offset pagination)
- query_items(get) nonexistent ID error includes requestedId as structured field
- create_work_tree userSummary extracts cause from result JSON (no longer generic)
- get_context session-resume accepts limit param (1-200, default 50)

Closes observations: 48763e28, fe89d620, 00378df7, 547b74ae

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- manage_items(delete, recursive=true) deletes all descendants before the root,
  traversing leaves-first to satisfy FK ordering
- manage_items(delete) without recursive flag now returns a clean error message
  when the item has children (pre-flight findChildren check, no raw DB exception)
- Added deleteAll(Set<UUID>) to WorkItemRepository for bulk deletion
- Fixed ORM schema mismatch: NotesTable, DependenciesTable, RoleTransitionsTable
  now declare onDelete=ReferenceOption.CASCADE, matching the Flyway SQL migrations

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…ner Done footer

Three display improvements (v1.0.9):
- In Progress: collapse children of active parents — if a parent is already shown
  as active, its active descendants are suppressed (parent implies active children)
- Pending Work: only show containers with non-terminal children (queue/work/review > 0);
  containers whose children are all done are excluded
- Done footer: two-tier format — named containers (≥1 child) listed by title,
  standalone items (0 children) collapsed to (+N standalone) count

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…paths

- QueryItemsTool: extract error message from result envelope in userSummary
  so agents see "Query failed: WorkItem not found: <id>" instead of bare "Query failed"
- ManageDependenciesTool: same fix — surfacing cycle/self-dep error detail
- SetupVersionSyncTest: update file paths from claude-plugins/task-orchestrator/
  to claude-plugins/clockwork/ (plugin was renamed during v3 refactor)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- git mv src/ → clockwork/src/ (history preserved)
- Create clockwork/build.gradle.kts (derived from root, with deprecation header)
- Create clockwork/DEPRECATED.md (archive docs, build/run instructions)
- Add startup deprecation warning to clockwork/src/main/kotlin/Main.kt
- Replace root build.gradle.kts with minimal aggregator (no src, apply false)
- Update settings.gradle.kts: include :clockwork alongside :current
- Dockerfile: :current:jar only in builder; update runtime-v2 copy path to
  clockwork/build/libs/; add COPY clockwork/build.gradle.kts and
  clockwork/src in builder stage
- CI: :current:test only; explicit runtime-current Docker target;
  :clockwork:printTagVersion for version validation

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…ent/

Phase 1 - Archive v2 docs:
- git mv docs/ → clockwork/docs/ (history preserved)
- Update ToolDocumentationResources.kt: docs/tools/ → clockwork/docs/tools/
- Fix clockwork/src/main/resources/db/migration/README.md path reference
- Update root CLAUDE.md Documentation section with correct paths

Phase 2 - Remove docs from Dockerfile:
- Remove COPY docs docs from builder stage
- Remove COPY --from=builder /app/docs /app/docs from runtime-base
- v3 (current) does not load docs at runtime

Phase 3 - Write fresh v3 docs:
- current/docs/quick-start.md — setup, config, first item
- current/docs/api-reference.md — all 13 tools with parameters and examples
- current/docs/workflow-guide.md — roles, note schemas, gates, dependencies

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…n to v1.0.12

HTTP transport:
- Dockerfile: add MCP_HTTP_HOST/PORT env vars and EXPOSE 3001
- docker-compose.yml: add current-http profile service (port 3001)
- CurrentMcpServer.kt: HTTP transport implementation via Ktor Streamable HTTP
- CLAUDE.md: document MCP_TRANSPORT/MCP_HTTP_HOST/MCP_HTTP_PORT env vars and HTTP run command
- gradle/libs.versions.toml: MCP SDK 0.8.3 → 0.8.4 (Ktor Streamable HTTP transport)

Deploy skill (/deploy_to_docker):
- Flip default target from runtime-v2 to runtime-current (v3 is now the default)
- Rename --current flag to --clockwork (v2 is now opt-in, not v3)
- Add transport mode selection step: STDIO (recommended) vs HTTP
- HTTP mode: runs detached with port 3001, named container, .mcp.json reminder
- Note SDK protocol version limitation (0.8.4 supports 2025-06-18, CC requires 2025-11-25)

Plugin v1.0.9 → v1.0.12:
- output-styles/current-analyst.md: full expansion with all 13 tools, note schema
  workflow, efficient patterns, delegation discipline, action items, analysis block rules
- skills/schema-builder/skill.md: complete rewrite with schema mechanics documentation,
  interactive phase design, config generation, and companion skill creation
- Version bumped in plugin.json, marketplace.json, and claude-plugins/CLAUDE.md

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Rewrites the README to accurately reflect the v3 WorkItem graph model:
- Replace Projects/Features/Tasks hierarchy with unified WorkItem depth model
- Remove v2-only sections: template system, planning tiers, completion gates
- Update tool catalog to 13 v3 tools with accurate names and descriptions
- Add Note Schemas section covering config, gates, and get_context usage
- Add role-based workflow diagram with triggers table
- Update Quick Start to match current/docs/quick-start.md (CLI-first)
- Update all doc links to current/docs/, image tag :latest → :main, SDK 0.8.4
- Align Solution framing: "summary-based handoffs" maps to Anthropic research

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Add PRAGMA journal_mode=WAL to DatabaseManager: eliminates read/write
  lock contention when two container instances share the same SQLite
  volume (Claude Code spawns concurrent MCP connections per session context)
- Add PRAGMA busy_timeout=5000: prevents indefinite blocking on the rare
  write-write collision; surfaces SQLITE_BUSY after 5s instead of hanging
- Add mapRowToWorkItemSafe to SQLiteWorkItemRepository: wraps all bulk-read
  .map calls with try-catch, skips corrupt rows (e.g. title > 500 chars)
  with a WARN log rather than crashing the entire tool call
- Bump plugin to v1.0.13 with redesigned /work-summary skill: insight-driven
  dashboard with agent observation blocks, root item classification, and
  3-call parallel data collection (no redundant queries)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…create)

Validation failures (self-dependency, circular dependency) now return
`{success:true, dependencies:[], created:0, failed:N, failures:[{index,error}]}`
instead of a top-level `{success:false, error:{...}}` envelope, matching
the response shape of manage_items and manage_notes on batch rejection.

Atomic behavior is preserved. Request-level errors (invalid type parameter,
infrastructure exceptions) continue to return errorResponse unchanged.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
PRAGMA journal_mode=WAL returns a result row. Using execute() without
closing the Statement leaves a dangling prepared statement on the JDBC
connection. When Exposed later calls setTransactionIsolation() ->
ensureAutoCommit() -> COMMIT, SQLite throws SQLITE_BUSY ("SQL statements
in progress") because the open statement is still attached.

Fix: wrap all three PRAGMA calls in a single statement.use {} block so
the statement is properly closed after setupConnection runs.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
New plugin skill (v1.0.14) that creates MCP work items intelligently
from conversation context:
- Scans existing containers via query_items(overview) to anchor items
  under the right category (Bugs, Features, Tech Debt, Observations, etc.)
- Detects hierarchical vs flat structure; offers to create project root
  if none exists
- Creates single items or work trees based on inferred scope
- Applies correct tags (feature-implementation, agent-observation,*)
- Pre-fills required queue-phase notes from conversation context

Also updates output style to reference /create-item in the Action Items
section for proactive agent use.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- CLAUDE.md: manage_dependencies fromTaskId/toTaskId → fromItemId/toItemId
- CLAUDE.md: query_dependencies description corrected (BFS chain+depth, not
  critical path / bottlenecks / parallelizable groups)
- workflow-guide.md: complete trigger now correctly states gates ARE enforced
  (was incorrectly described as "bypasses phase gates")
- workflow-guide.md: get_context response example corrected — missing field is
  string array, top-level key is schema (not notes), guidancePointer is at
  data root (not inside gateStatus)
- api-reference.md: complete_tree rootId mode now explicitly states root item
  is NOT completed, only descendants; added gate enforcement note for
  trigger=complete vs trigger=cancel

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
MEDIUM fixes (api-reference.md):
- manage_items: document top-level requiresVerification is ignored (use per-item)
- manage_items: add descendantsDeleted to delete response docs
- manage_items: add requiresVerification to update response docs
- manage_notes: document additive behavior of ids + itemId delete
- manage_dependencies: document unblockAt omitted from response when default null
- manage_dependencies: document RELATES_TO + unblockAt raises ValidationException
- manage_dependencies: clarify validation failures apply to all ValidationExceptions
- advance_item: document start cascade (child WORK -> parent QUEUE auto-advances)
- advance_item: add error result shape for failed transitions
- get_next_status: document suggestion field on BLOCKED role response
- create_work_tree: fix depth cap description (children can reach depth 3)
- create_work_tree: add tags field to children response example
- get_blocked_items: clarify blockerCount is unsatisfied blockers only

LOW fixes (api-reference.md + workflow-guide.md):
- manage_items: fix complexity default (null, not 5)
- manage_items: clarify delete failure is proactive check not DB constraint
- query_items: add scoped overview response example; clarify global total meaning
- manage_notes: document silent no-op on delete of non-existent note by key
- manage_dependencies: note 0-based index in batch failures
- manage_dependencies: add delete-by-relationship and deleteAll response examples
- manage_dependencies: note pattern shortcuts return same response shape
- get_next_status: enumerate recommendation field values (Ready/Blocked/Terminal)
- create_work_tree: show populated notes array example when createNotes=true
- complete_tree: enumerate skippedReason values; document all summary fields
- get_blocked_items: define blockType values (explicit vs dependency)

Skipped: L12 (flowType) — field does not exist in v3 codebase

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- current/build.gradle.kts: 0.1.0-alpha-01 → 2.0.0
- CHANGELOG.md: add [2.0.0] entry covering the full v3 (Current)
  architecture — unified WorkItem model, 13 MCP tools, role-based
  workflow engine, note schema gates, HTTP transport, WAL mode SQLite,
  Claude Code plugin v1.0.14, and complete doc audit

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Wraps System.in with a blocking InputStream that loops until read()
returns non-zero data. Workaround for MCP SDK 0.8.4 bug where the
transport's read loop has no coroutine suspension point on a 0-byte
read, causing the JVM to peg a Dispatchers.IO thread at 100% CPU
indefinitely with no output and no recovery path.

See: modelcontextprotocol/kotlin-sdk#549

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
The builder stage referenced version.properties for the Gradle version
calculation but it was not being COPY'd into the build context, causing
the build to fail with "No such file or directory".

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Add version.properties as single source of truth for semver (2.0.0)
- Update current/build.gradle.kts to load version from properties file,
  support CI_BUILD_NUMBER suffix on dev builds, and expose printTagVersion task
- Overhaul CI workflow: remove manual v* tag trigger, auto-tag on main push,
  semver+latest Docker tags on main, branch-name tag on dev branches,
  version guard to prevent duplicate tag pushes, remove all clockwork references
- Add .claude/skills/bump-version.md skill: analyzes git diff, synthesizes
  user-facing changelog, infers semver bump, updates files, and creates the PR
- Add .claude/hooks/check-version-bump.sh PreToolUse hook that blocks the
  GitHub CLI PR creation command if version.properties is unchanged vs main
- Fix hook grep pattern to match command context only (not commit message text)
- Fix .gitignore: unblock .claude/skills/ so project-level skills are tracked
  (plugin cache lives at user-level ~/.claude/, not in the project directory)
- Track .claude/skills/feature-implementation.md (was previously gitignored)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
The ancestor chain-building loop had no cycle detection — if any item
had a circular parent reference (self-loop or A->B->A), the while loop
would spin at 100% CPU indefinitely, hanging the container.

Adds a visited set to break cycles and logs a warning when one is
detected. The BFS fetch phase above already handled cycles correctly
via cache exclusion; this fixes only the chain-building phase.

Root cause: three corrupt test-artifact items in the database had
circular parent_id references (one self-loop, one mutual A<->B cycle),
which triggered the spin on any call to includeAncestors=true.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Three layers of protection to prevent the infinite loop in
findAncestorChains caused by corrupt circular parent references:

1. ManageItemsTool create path: add self-parent and ancestor cycle
   checks matching the existing update path guards (Guard 1 & 2).
   Generates itemId before WorkItem construction so the self-parent
   check has a UUID to compare against.

2. DatabaseManager startup: integrity check queries for self-loops
   and mutual A<->B cycles on boot, logging WARN for any found.
   Does not fail startup or delete data.

3. Tests: SQLiteWorkItemRepositoryAncestorCycleTest verifies that
   findAncestorChains terminates cleanly on self-loop and A<->B
   cycle data. ManageItemsToolTest extended with create-path cycle
   guard coverage.

Also reverts the InputStream wrapper from CurrentMcpServer (the
stdin read loop was never the cause of the CPU spin).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Remove reverted StdioServerTransport busy-spin fix
- Drop pre-v3 beta/alpha changelog history (architecture is incompatible)
- Add 2.0.1 patch entry: circular parentId guards, BFS cycle fix, Docker version context, /bump-version skill

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…version skill

- Replace all :main image references with :latest (CI publishes :latest on main merges, not :main)
- Fix version badge from /release/ to /tag/ endpoint — CI creates git tags, not GitHub Releases
- Update stale version format note (now {major}.{minor}.{patch} via version.properties)
- Add Step 8 to bump-version skill: README pre-PR checklist for image tag and badge verification

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Pull image first (Step 1) so MCP client connects instantly instead of
hanging silently on first launch. Register options become Step 2 sub-options
(A/B/C). Remove redundant docker pull from Option C. Plugin install is Step 3.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…section

Remove -v workspaceFolder and -e AGENT_CONFIG_DIR from Options A and B.
Server runs in schema-free mode by default — project mount is only needed
for custom note schemas. Add Advanced section explaining the project mount
should only appear in per-project .mcp.json (Option B), not global
registrations (Option A), to avoid per-project schema bleed on shared configs.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Previously the advanced config mounted the whole project workspace into the
container, giving the MCP server read access to all source files, .env, etc.
Mount only the .taskorchestrator/ subfolder instead. The container's /project
path contains nothing else, eliminating unnecessary filesystem exposure.

No code change required — AGENT_CONFIG_DIR resolves config.yaml via
.taskorchestrator/ subdirectory convention, so mount path is the fix.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Replace full project mounts with scoped .taskorchestrator/ mounts in all docs.
No file outside .taskorchestrator/ should ever be exposed to the container.

Files changed:
- current/docs/quick-start.md: remove mount from Options A/B; fix :main→:latest;
  fix AGENT_CONFIG_DIR env var table entry; add Docker callout in note schemas section
- current/docs/workflow-guide.md: fix dev example to use scoped mount
- CLAUDE.md: fix all three dev docker run examples to use scoped mount;
  relabel "project mount" → "config mount"
- .claude/commands/deploy_to_docker.md: replace hardcoded D:/Projects/... paths
  with $(pwd)/.taskorchestrator; relabel options to "Config Mount"
- clockwork/docs/quick-start.md: fix full project mount in both examples (archived)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Removed:
- Platform Compatibility table (covered by Quick Start Option C)
- Use Cases section (restated Key Features)
- Contributing section (boilerplate; link now in Documentation)
- Release Information section (links folded into Documentation)
- Keywords section (belongs as GitHub Topics, not README prose)
- Bottom docker pull CTA (duplicated Quick Start Step 1)

Trimmed:
- The Problem + The Solution collapsed to one short paragraph
- Technical Stack: removed self-congratulatory Architecture Validation paragraph;
  updated test count to 1,600+ and added HTTP transport to protocol line

Documentation section reorganized as a flat link list.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@jpicklyk jpicklyk merged commit 76ba059 into main Feb 19, 2026
5 checks passed
@jpicklyk jpicklyk deleted the overhaul branch February 19, 2026 17:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant