trekoon 0.2.9 → 0.3.1

package/docs/machine-contracts.md

@@ -246,6 +246,126 @@ Behavior:
 - machine output includes `metadata.compatibility` with migration guidance and
   removal timing
 
+## Compact envelope mode
+
+```bash
+trekoon --toon --compact task list
+```
+
+When `--compact` is passed, the `metadata` key is omitted from the TOON/JSON
+envelope. The `ok`, `command`, `data`, `error`, and `meta` keys are unaffected.
+
+## Status transition error contract
+
+Invalid status transitions return:
+
+```text
+ok: false
+error:
+  code: status_transition_invalid
+  message: "cannot transition <kind> <id> from '<from>' to '<to>'"
+  details:
+    entity: epic|task|subtask
+    id: <entity-id>
+    fromStatus: <current-status>
+    toStatus: <attempted-status>
+    allowedTransitions[]: <valid targets from current status>
+```
+
+## Epic progress contract
+
+```bash
+trekoon --toon epic progress <epic-id>
+```
+
+Payload fields:
+
+```text
+ok: true
+command: epic.progress
+data:
+  epicId: <epic-id>
+  title: <epic-title>
+  total
+  doneCount
+  inProgressCount
+  blockedCount
+  todoCount
+  readyCount
+  nextCandidate: { id, title } | null
+```
+
+## Task done enhanced contract
+
+```bash
+trekoon --toon task done <task-id>
+```
+
+Payload fields:
+
+```text
+ok: true
+command: task.done
+data:
+  completed: { ...task record... }
+  openSubtaskCount
+  openSubtaskIds[]
+  warning: "Warning: N subtask(s) still open." | null
+  unblocked[]:
+    id
+    kind: task
+    title
+    status
+    wasBlockedBy[]
+  next: { ...task tree... } | null
+  nextDeps[]
+  readiness:
+    readyCount
+    blockedCount
+```
+
+## Suggest command contract
+
+```bash
+trekoon --toon suggest [--epic <epic-id>]
+```
+
+Payload fields:
+
+```text
+ok: true
+command: suggest
+data:
+  suggestions[]:
+    priority
+    action
+    command
+    reason
+    category: recovery|sync|execution|planning
+  context:
+    totalEpics
+    activeEpic: <epic-id> | null
+    readyTasks
+    blockedTasks
+    inProgressTasks
+    syncBehind
+    pendingConflicts
+```
+
+## Owner field in update payloads
+
+Task and subtask update payloads now include `owner` in their event data:
+
+```text
+data:
+  task | subtask:
+    ...existing fields...
+    owner: <string> | null
+```
+
+The board API accepts `owner` on `PATCH /api/tasks/{id}` and
+`PATCH /api/subtasks/{id}`.
+
 ## Related docs
 
 - [Quickstart](quickstart.md)

package/docs/plans/r1-unified-skill-rewrite.md

@@ -0,0 +1,290 @@
+# R1: Unified Trekoon Skill Rewrite
+
+## Problem
+
+The current skill stack requires three separate files loaded simultaneously:
+
+| File | Lines | Tokens (~) | Purpose |
+|------|-------|-----------|---------|
+| `writing-plans/SKILL.md` | 264 | ~1300 | Planning methodology + Trekoon commands |
+| `executing-plans/SKILL.md` | 205 | ~1000 | Execution orchestration + Trekoon commands |
+| `trekoon/SKILL.md` | 333 | ~1600 | CLI operating guide |
+| **Total** | **802** | **~3900** | |
+
+Issues:
+- ~800 lines of instructions loaded into every agent's context
+- Significant duplication: `--toon` usage explained 3x, compact spec escaping 2x, session/next/done loop 2x
+- `executing-plans` and `executing-plans-wt` are 80% identical
+- Without the external skills, the base `trekoon` SKILL.md teaches mechanics but not methodology
+- Agent must load 3 skills to get the full plan-execute workflow
+
+## Proposed Solution
+
+Replace the three-file stack with a single enhanced `SKILL.md` that has three operating modes activated by context. The agent loads ONE file and gets planning methodology, execution orchestration, AND CLI operations in ~450 lines (~2200 tokens) — a 44% reduction.
+
+The `executing-plans-wt` variant stays separate because it adds TeamCreate/tmux-specific orchestration that only applies when the user explicitly requests worker teams.
+
+## Rewritten Skill
+
+```markdown
+---
+name: trekoon
+description: Use Trekoon to create issues/tasks, plan backlog and sprints, create epics, update status, track progress, and manage dependencies/sync across repository workflows.
+---
+
+# Trekoon Skill
+
+Trekoon is a local-first issue tracker for epics, tasks, and subtasks.
+This skill covers planning, execution, and CLI operations. Use the mode
+that matches your current activity.
+
+## Non-negotiable defaults
+
+- Always include `--toon` on every Trekoon command.
+- Prefer the smallest sufficient scope.
+- Prefer transactional bulk commands over many single-item commands.
+- Prefer `--append` for progress notes instead of rewriting descriptions.
+- Preview replace before `--apply`.
+- Prefer `--ids` over `--all` for bulk updates.
+- Never edit `.trekoon/trekoon.db` directly.
+- Treat `.trekoon` as shared repo-scoped state; keep it gitignored.
+- Never run `trekoon wipe --yes --toon` unless user explicitly asks.
+- Statuses: `todo`, `in_progress`, `done`, `blocked` — use only these.
+
+---
+
+## Mode A: Planning
+
+Activate when: user asks to plan, design, or break down work.
+
+### Clarify first
+
+If requirements are unclear or have meaningful tradeoffs, ask before planning.
+Present options with tradeoffs. Don't guess when the user can clarify in 10 seconds.
+
+### Data model
+
+- **Epic** = full feature outcome and constraints
+- **Task** = one subsystem/domain work unit ownable by one agent
+- **Subtask** = concrete implementation/test/verification step
+- **Dependency** = strict prerequisite only (not "nice to have")
+
+### Writing standard
+
+**Epic title:** `<Area>: <deliverable> to <outcome> (<constraint>)`
+**Epic description:** Goal & why now | In scope | Out of scope | Success criteria | Risks | Verification gates
+
+**Task title:** `[<Subsystem>] <verb> <artifact> to <observable outcome>`
+**Task description must include:**
+- Concrete scope and affected paths/symbols
+- Acceptance criteria (observable behavior)
+- Verification commands
+- File scope: Target files | Read-first files | Do-not-touch paths
+- Parallelism note: "Can run in parallel with ..." or "Blocked by ..."
+- Context loading hints: reference existing patterns to follow
+
+**Subtask:** Imperative, specific titles. Description states exact artifact and completion signal.
+
+### Parallelism & dependencies
+
+- Tasks with no edge between them are parallel candidates
+- Different subsystems = parallel; same subsystem = combine or sequence
+- 3-4 tasks max per subsystem lane
+- Add edges only for hard prerequisites; prefer task-to-task deps
+- Validate acyclic assumptions before finalizing
+
+### Execution handoff contract
+
+Every plan must be directly executable without re-interpretation:
+1. Lane ownership in title (`[Subsystem] ...`)
+2. Dependency intent (explicit blocked-by / parallel-with)
+3. Verification evidence (exact commands + expected outcome)
+4. Completion semantics (`done` = verified; `blocked` = with reason)
+
+### Create the plan
+
+Use one-shot `epic create` when the graph is known. Use `epic expand` when
+adding to existing epics. See Command Reference below for syntax.
+
+Return to user: Epic ID + tasks by lane + dependency list + parallel batches + verification commands.
+
+---
+
+## Mode B: Execution
+
+Activate when: user asks to execute, implement, or work through a plan/epic.
+
+### Setup
+
+1. Create a branch unless trivial
+2. Ensure Trekoon initialized (`trekoon init --toon` if needed)
+3. Load epic: `trekoon --toon session --epic <id>` or `trekoon --toon epic show <id> --all`
+
+### Execution loop
+
+```
+1. trekoon --toon session [--epic <id>]     # Orient
+2. [if behind] trekoon --toon sync pull --from main
+3. trekoon --toon task update <id> --status in_progress  # Claim
+4. [do work, update subtasks]
+5. trekoon --toon task done <id>            # Done + get next
+6. Repeat from 3
+```
+
+### Orchestration (sub-agents)
+
+Build execution graph from scheduler primitives:
+- `task next --epic <id>` for top candidate
+- `task ready --epic <id> --limit 50` for batch decisions
+- `dep reverse <id>` for impact of completions
+
+Group ready tasks by subsystem to minimize context loading:
+- Same directory prefix / domain / intent = group together
+- 3-4 tasks max per group
+- Parallel groups: different subsystems
+- Sequential groups: have dependency edges
+
+Dispatch sub-agents per group with:
+- Task IDs and titles to execute IN ORDER
+- Instructions to claim (in_progress), update subtasks, append progress, and mark done
+- Blocker reporting: append reason + set blocked status
+
+### Auto-recovery
+
+1. `dependency_blocked` error: refresh with `task ready`/`task next`, continue with ready candidate
+2. Agent attempts fix (has context)
+3. Can't fix: report failure with error output
+4. Same error twice: stop and ask user
+
+### Verify before completing
+
+1. Code review all changes
+2. Run full test suite
+3. Manual verification (curl endpoints, run CLI commands, feed real data)
+4. DX quality check (error messages, noise, consistency)
+
+Record verification evidence via `--append`. Keep original descriptions stable.
+
+---
+
+## Mode C: Operations (Default)
+
+Active always. CLI reference for reads, writes, search, sync.
+
+### Agent loop (quick reference)
+
+**session → claim → work → done → repeat**
+
+`session` returns diagnostics, sync status, next task tree, blockers, readiness.
+`task done` marks done and returns next candidate with full tree.
+
+### Read policy
+
+| Need | Command |
+|---|---|
+| Session startup | `trekoon --toon session` |
+| Next task only | `trekoon --toon task next` |
+| Ready options | `trekoon --toon task ready --limit 5` |
+| Blockers for task | `trekoon --toon dep list <id>` |
+| What item unblocks | `trekoon --toon dep reverse <id>` |
+| Full task | `trekoon --toon task show <id> --all` |
+| Full epic tree | `trekoon --toon epic show <id> --all` |
+
+Avoid `task list --all` or `epic show --all` when narrower commands suffice.
+
+### Creation policy
+
+| Situation | Command |
+|---|---|
+| New epic + full graph | `epic create --task --subtask --dep` |
+| Add to existing epic | `epic expand <id> --task --subtask --dep` |
+| Sibling tasks | `task create-many --epic <id> --task` |
+| Sibling subtasks | `subtask create-many <id> --subtask` |
+| Dep edges on existing IDs | `dep add-many --dep` |
+
+**Compact spec format:** `tempkey|title|description|status`
+**Subtask spec:** `@parent-key|tempkey|title|description|status`
+**Dep spec:** `@source|@target` or `<id>|<id>`
+
+**Escaping:** `\|` = literal pipe, `\\` = backslash, `\n` = newline.
+Any other `\X` is rejected. Rephrase operators like `!==` in descriptions.
+
+**Temp keys:** `@key` references work only within the same invocation.
+`dep add-many` requires real persisted IDs.
+
+### Update policy
+
+```bash
+trekoon --toon task update <id> --append "note" --status in_progress
+trekoon --toon task done <id>
+trekoon --toon task update <id> --append "Blocked by <reason>" --status blocked
+```
+
+Bulk: `--ids id1,id2` or `--all` with `--append` and/or `--status`.
+
+### Search & replace
+
+1. Search: `trekoon --toon epic search <id> "text"`
+2. Preview: `trekoon --toon epic replace <id> --search "old" --replace "new"`
+3. Apply: add `--apply` after preview looks correct
+
+Scope: subtask (narrowest) > task > epic (widest). Use `--fields title,description`.
+
+### Sync
+
+- Same-branch sync is a no-op
+- Cross-branch: `trekoon --toon sync pull --from main` before merge
+- Conflicts: `sync conflicts list` → `sync conflicts show <id>` → `sync resolve <id> --use ours|theirs`
+
+### Setup & recovery
+
+```bash
+trekoon --toon init
+trekoon --toon session
+trekoon --toon quickstart
+```
+
+Stop if `recoveryRequired` persists. Don't commit `.trekoon/trekoon.db`.
+
+### Worktree notes
+
+`sharedStorageRoot` may differ from `worktreeRoot` — expected.
+`wipe` deletes shared storage for all linked worktrees.
+
+## Tool selection
+
+Use dedicated tools (Glob, Grep, Read, Edit, Write) over bash for file ops.
+Run Trekoon, git, build/test commands via Bash.
+```
+
+## Token Analysis
+
+| Metric | Before (3 files) | After (1 file) | Savings |
+|--------|------------------|-----------------|---------|
+| Lines | 802 | ~450 | -44% |
+| Est. tokens | ~3900 | ~2200 | -44% |
+| Files loaded | 3 | 1 | -67% |
+| Duplicated concepts | 8+ | 0 | -100% |
+
+## What Was Removed
+
+1. **Tool selection tables** — duplicated across all 3 files; kept once at bottom
+2. **LSP tool references** — OpenCode-specific; moved to executing-plans-wt only
+3. **Mandatory commit policy** — project-level concern, belongs in AGENTS.md not skill
+4. **Repeated `--toon` reminders** — mentioned once in defaults, not repeated per section
+5. **Verification details** — condensed from 25 lines to 4 lines (same checklist, less prose)
+6. **Compact spec examples** — kept 1 example per type instead of 2-3 per file
+
+## What Was Added
+
+1. **Mode-based activation** — agent knows which section to focus on based on context
+2. **Status enforcement note** — only use `todo | in_progress | done | blocked`
+3. **Condensed execution loop** — 6-line quick reference instead of spread across sections
+4. **Orchestration in same file** — no need to load separate executing-plans skill
+
+## Migration Path
+
+1. Replace `.agents/skills/trekoon/SKILL.md` with the unified version
+2. Keep `writing-plans` and `executing-plans` as deprecated aliases that redirect
+3. Keep `executing-plans-wt` as standalone (adds TeamCreate-specific content)
+4. Update `docs/ai-agents.md` to reference single skill instead of stack

package/docs/plans/r10-suggest-command-skill-integration.md

@@ -0,0 +1,152 @@
+# R10: Suggest Command — Skill Integration Guide
+
+## Feature Summary
+
+A new `trekoon --toon suggest` command that returns actionable next-step
+recommendations based on current tracker state. Designed for agents operating
+without the full skill stack — makes Trekoon self-guiding.
+
+### Response Shape
+
+```
+{
+  suggestions: [
+    {
+      priority: 1,
+      action: "sync pull --from main",
+      command: "trekoon --toon sync pull --from main",
+      reason: "3 events behind main branch",
+      category: "sync"
+    },
+    {
+      priority: 2,
+      action: "claim task task-5",
+      command: "trekoon --toon task update task-5 --status in_progress",
+      reason: "highest priority ready task: [API] Design endpoint schema",
+      category: "execution"
+    },
+    {
+      priority: 3,
+      action: "resolve conflict conflict-2",
+      command: "trekoon --toon sync conflicts show conflict-2",
+      reason: "1 unresolved sync conflict blocking accurate state",
+      category: "sync"
+    }
+  ],
+  context: {
+    totalEpics: 3,
+    activeEpic: "epic-1",
+    readyTasks: 4,
+    blockedTasks: 2,
+    inProgressTasks: 1,
+    syncBehind: 3,
+    pendingConflicts: 1
+  }
+}
+```
+
+## Suggestion Rules Engine
+
+The command evaluates these conditions in priority order:
+
+| Priority | Condition | Suggestion |
+|----------|-----------|------------|
+| 1 | `recoveryRequired = true` | Run `trekoon init` to repair storage |
+| 2 | `pendingConflicts > 0` | Inspect and resolve sync conflicts |
+| 3 | `syncBehind > 0` | `sync pull --from main` |
+| 4 | Tasks with `in_progress` status exist | Continue working on in-progress task (show task ID + title) |
+| 5 | Ready tasks available | Claim highest-priority ready task |
+| 6 | All tasks blocked | Show which dependencies are blocking and suggest focusing on those |
+| 7 | All tasks done | Mark epic as done |
+| 8 | No epics exist | Create first epic or run quickstart |
+
+Maximum 3 suggestions returned to keep the response compact.
+
+## Skill Integration
+
+### Where to Document
+
+In the unified SKILL.md, add to Mode C: Operations as a new section:
+
+```markdown
+### Guided mode (for bare agent usage)
+
+When operating without the full planning/execution skill stack, use `suggest`
+to get state-aware next steps:
+
+    trekoon --toon suggest [--epic <id>]
+
+Returns up to 3 prioritized suggestions with ready-to-run commands.
+Use this instead of manually combining session + ready + sync calls
+when you need a quick decision about what to do next.
+
+Suggestions cover: sync hygiene, conflict resolution, task claiming,
+blocker analysis, and epic completion.
+```
+
+### Where to Reference in Default Agent Loop
+
+Update the "Orient with a single call" section:
+
+```markdown
+### 1. Orient
+
+For full diagnostics: `trekoon --toon session`
+For quick "what should I do?": `trekoon --toon suggest`
+
+`suggest` is lighter than `session` — it returns actionable commands
+rather than raw state. Use `session` when you need the full picture;
+use `suggest` when you just need the next step.
+```
+
+## Agent Behavior Change
+
+### Before (bare agent, no skills)
+
+```
+agent receives "work on this project"
+→ trekoon --toon session           # raw diagnostics (agent must interpret)
+→ trekoon --toon task ready        # (agent must decide what to do)
+→ trekoon --toon sync status       # (agent must check sync separately)
+→ (agent reasons about priorities and decides action)
+```
+
+The agent must understand Trekoon's state model to make good decisions.
+Without the executing-plans skill, it often makes suboptimal choices.
+
+### After (with suggest)
+
+```
+agent receives "work on this project"
+→ trekoon --toon suggest
+→ response: "sync pull (3 behind), then claim task-5 (highest priority ready)"
+→ agent executes the suggested commands directly
+→ trekoon --toon suggest           # after completing, ask again
+```
+
+The agent doesn't need to understand Trekoon internals — the suggest command
+encodes the decision logic that the executing-plans skill currently provides
+through instruction text.
+
+## Token Impact
+
+| Scenario | Before (without skills) | After (with suggest) |
+|----------|------------------------|---------------------|
+| Orient + decide | session + ready + sync status = 3 calls | suggest = 1 call |
+| Context needed | Agent reads ~400 token session response + reasons | Agent reads ~150 token suggest response + executes |
+| Decision quality | Depends on agent's understanding of Trekoon | Consistent, encoded in suggest logic |
+
+## Key Design Principle
+
+`suggest` moves decision logic from the skill file (instruction tokens loaded
+into every agent) into the CLI itself (zero token cost, computed at runtime).
+This is the most direct way to make Trekoon work well without external skills.
+
+## Implementation Notes
+
+- The suggest command should be read-only (no mutations)
+- Epic-scoped: `--epic <id>` limits suggestions to that epic's context
+- Without `--epic`: considers all epics, suggests the most active one
+- Reuses existing `buildTaskReadiness()` and `resolveSyncStatus()` internally
+- Should be fast: single DB open, no transactions needed
+- Human output: numbered list with reasons; TOON output: structured array

package/docs/plans/r9-task-done-diff-skill-integration.md

@@ -0,0 +1,113 @@
+# R9: Task Done Diff Response — Skill Integration Guide
+
+## Feature Summary
+
+When `task done <id>` completes, the response will include not just the next
+candidate but also which tasks/subtasks were newly unblocked by this completion.
+
+### Current Response Shape
+
+```
+{
+  markedDone: { id, title, status: "done" },
+  next: { id, epicId, title, description, status, subtasks[] } | null,
+  nextDeps: DependencyBlocker[],
+  readiness: { readyCount, blockedCount }
+}
+```
+
+### Proposed Response Shape
+
+```
+{
+  markedDone: { id, title, status: "done" },
+  unblocked: [
+    { id, kind: "task"|"subtask", title, status, wasBlockedBy: [<completed-id>] }
+  ],
+  next: { ... } | null,
+  nextDeps: DependencyBlocker[],
+  readiness: { readyCount, blockedCount }
+}
+```
+
+The `unblocked` array contains entities that transitioned from "has incomplete
+dependencies" to "all dependencies done" as a direct result of this completion.
+
+## Skill Integration
+
+### Where to Document
+
+In the unified SKILL.md (Mode B: Execution and Mode C: Operations), update the
+`task done` documentation:
+
+### Mode C: Operations — Update Policy
+
+Add after the `task done` line:
+
+```markdown
+`task done` returns:
+- `markedDone`: the completed task
+- `unblocked`: tasks/subtasks newly unblocked by this completion
+- `next`: next ready candidate with full tree
+- `readiness`: updated ready/blocked counts
+
+Use `unblocked` to decide whether to dispatch new sub-agents immediately
+rather than calling `dep reverse` separately.
+```
+
+### Mode B: Execution — Orchestration
+
+Replace the current "As tasks complete, re-evaluate graph readiness" with:
+
+```markdown
+### After task completion
+
+When `task done` returns, check the `unblocked` array:
+- If unblocked items belong to the same subsystem as an active agent, notify
+  that agent via SendMessage (worker teams) or include in next dispatch
+- If unblocked items form a new parallel lane, dispatch a new sub-agent
+- If `unblocked` is empty, no new work was freed — continue with `next`
+
+This eliminates the need for a separate `dep reverse` call after each completion.
+```
+
+### Token Savings Per Execution Cycle
+
+| Before | After | Saved |
+|--------|-------|-------|
+| `task done <id>` + `dep reverse <id>` = 2 calls | `task done <id>` = 1 call | 1 Trekoon invocation + response parsing per task completion |
+
+For a 20-task epic, this saves ~20 CLI calls and ~20 response parses during execution.
+
+## Agent Behavior Change
+
+### Before (current)
+
+```
+agent completes task-5
+→ trekoon task done task-5          # get next candidate
+→ trekoon dep reverse task-5        # see what was unblocked
+→ (agent reasons about whether to dispatch new sub-agents)
+→ trekoon task ready --epic X       # refresh ready queue
+```
+
+### After (with R9)
+
+```
+agent completes task-5
+→ trekoon task done task-5          # get next + unblocked list
+→ (agent immediately knows: task-8 and task-12 were unblocked)
+→ (dispatch decisions happen inline without extra calls)
+```
+
+## Implementation Notes
+
+The `unblocked` computation should:
+1. Snapshot the "blocked" set before marking done
+2. Mark the task done
+3. Recompute readiness for previously-blocked items
+4. Return items that transitioned from blocked to ready
+
+This is a diff of two readiness snapshots, not a full graph recomputation.
+Keep it scoped to direct reverse dependencies of the completed task to avoid
+O(all-tasks) cost on every completion.