chore(release): v0.1.18 — rebalance hydration philosophy (#17)

* feat: rebalance hydration philosophy — outcome-level checkboxes, not implementation scripts

- Skill v1.1.0: rewrote hydration guidance with adaptive planning philosophy
- Worker agent: 'one checkbox per meaningful outcome' replaces 'one per unit of work'
- Reviewer agent: added plan granularity guidance to prevent over-specification demands
- Prompt/STATUS templates: updated hydration banners
- TP-007 Step 0: collapsed 8 micro-checkboxes to 3 outcome-level items
- TP-007/009/012: updated hydration banners for pending tasks

* chore(release): prepare v0.1.18

Author: HenryLach

package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskplane",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "description": "AI agent orchestration for pi — parallel task execution with checkpoint discipline",
   "keywords": [
     "pi-package",

skills/create-taskplane-task/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: create-taskplane-task
+version: 1.1.0
 description: Creates structured Taskplane task packets (PROMPT.md, STATUS.md) for autonomous agent execution via the task-runner and task-orchestrator extensions. Use when asked to "create a task", "create a taskplane task", "stage a task", "prepare a task for execution", "write a PROMPT.md", "set up work for the agent", "queue a task", or whenever the user wants to define work that will be executed autonomously by another agent instance.
 ---
 
@@ -172,45 +173,81 @@ Docs in `task-runner.yaml → never_load` must NOT appear in any task.
 
 ## STATUS.md Hydration
 
-STATUS.md is the worker's ONLY memory between iterations. Granularity directly
-determines how much progress survives when an iteration ends mid-step.
+STATUS.md is the worker's ONLY memory between iterations. It needs enough
+structure so progress survives when an iteration ends mid-step — but not so much
+structure that it becomes a rigid script the worker follows mechanically.
+
+### Philosophy: Adaptive Planning, Not Exhaustive Scripting
+
+Hydration exists because workers discover things at runtime they couldn't know
+upfront: the actual function signatures, the edge cases that emerge from reading
+source, the reviewer feedback that reshapes approach. The goal is **adaptability
+in the face of unknowns** — not granularity for its own sake.
+
+**The right level of detail depends on predictability:**
+
+| How predictable is the work? | Approach |
+|------------------------------|----------|
+| You know exactly what files/methods/tests are needed | List them as checkboxes |
+| You know the general shape but details depend on source code | Write intent-level checkboxes; trust the worker to figure out implementation specifics |
+| You genuinely don't know what's needed until a prior step runs | Use `⚠️ Hydrate` marker |
+
+**Anti-pattern to avoid:** Creating 15+ micro-checkboxes that spell out every
+function name, parameter, and assertion before the worker has even read the
+source code. This wastes task-creation time, produces items that frequently need
+revision anyway, and turns the worker into a checkbox-follower instead of a
+problem-solver.
 
 ### Task Creator Responsibilities
 
-**Pre-hydrate STATUS.md to match PROMPT.md granularity.** Since the skill creates
-both files at the same time, there is no reason for STATUS.md to be coarser than
-PROMPT.md.
+**Match STATUS.md to PROMPT.md granularity — no more, no less.** PROMPT.md steps
+should express *outcomes* the worker needs to achieve, not dictate *how* to
+achieve them.
+
+Good granularity examples:
 
 | PROMPT.md says | STATUS.md should have |
 |----------------|-----------------------|
-| "Implement Create, Update, Get, List, Publish, Clone" | One checkbox per method (6 checkboxes) |
-| "Test happy path, validation, auth, tenant isolation" | One checkbox per test category (4 checkboxes) |
-| "Create file X, file Y, file Z" | One checkbox per file (3 checkboxes) |
+| "Implement CRUD operations for Projects" | `- [ ] Implement Create, Read, Update, Delete for Projects` (one checkbox — the worker can figure out 4 methods) |
+| "Add repo-aware fields to persistence schema" | `- [ ] Add repo fields to schema and update serialization` |
+| "Test merge failure scenarios" | `- [ ] Add tests for merge failure paths` |
+| "Update merge flow to work per-repo" | `- [ ] Refactor merge to partition by repo` and `- [ ] Aggregate per-repo results` (two checkboxes — these are genuinely distinct outcomes) |
+
+Over-hydrated examples (avoid):
+
+| ❌ Too granular | ✅ Better |
+|----------------|-----------|
+| 10 checkboxes naming every function, parameter, and import to change | 2-3 checkboxes describing the behavioral changes |
+| Separate checkboxes for "create file", "add imports", "add function", "export function" | One checkbox: "Create helper module with X capability" |
+| One checkbox per test assertion | One checkbox per test scenario or category |
 
 **Use `⚠️ Hydrate` markers** for steps that genuinely depend on runtime
 discoveries — where the task creator cannot know the items upfront:
 
 ```markdown
-### Step 3: Create Task Files
+### Step 2: Handle migration
 **Status:** ⬜ Not Started
-> ⚠️ Hydrate: Expand with per-item checkboxes once Step 2 identifies the task list
+> ⚠️ Hydrate: Expand based on schema gaps identified in Step 1
 
-- [ ] Read create-taskplane-task skill and prompt template
-- [ ] Create task files (expand after Step 2)
+- [ ] Implement v1→v2 compatibility (details depend on Step 1 findings)
 ```
 
 **When to use markers vs. pre-hydration:**
 
 | Situation | Approach |
 |-----------|----------|
-| Items are known at creation time | Pre-hydrate (one checkbox per item) |
-| Items depend on analysis/discovery in a prior step | `⚠️ Hydrate` marker |
-| Items depend on what exists on disk (preflight) | `⚠️ Hydrate` marker |
-| Reviewer feedback adds new items | Worker hydrates (handled by worker agent) |
-
-The worker agent has full hydration rules (commit-before-implement,
-REVISE-triggered hydration). Task creators just need to provide the right
-starting granularity.
+| Outcomes are known at creation time | Pre-hydrate with outcome-level checkboxes |
+| Details depend on analysis/discovery in a prior step | `⚠️ Hydrate` marker |
+| Details depend on what exists on disk | `⚠️ Hydrate` marker |
+| Reviewer feedback adds new items | Worker adds items (handled by worker agent) |
+
+### Worker Hydration at Runtime
+
+Workers may expand checkboxes when entering a step — but should apply the same
+principle: **add checkboxes for distinct outcomes discovered during exploration,
+not for every individual code change.** The worker agent has hydration rules
+(commit-before-implement, REVISE-triggered expansion). The goal is a useful
+resumability checkpoint, not a line-by-line implementation journal.
 
 ### Constraint: No New Steps at Runtime
 

skills/create-taskplane-task/references/prompt-template.md

@@ -67,9 +67,8 @@ Copy this template when creating a new task. Replace all `[bracketed]` fields.
 
 ## Steps
 
-> **Hydration:** STATUS.md checkboxes must match the granularity below. Steps that
-> depend on runtime discoveries should be marked with `⚠️ Hydrate` in STATUS.md.
-> See task-worker agent for full hydration rules.
+> **Hydration:** STATUS.md tracks outcomes, not individual code changes. Workers
+> expand steps when runtime discoveries warrant it. See task-worker agent for rules.
 
 ### Step 0: Preflight
 
@@ -163,9 +162,9 @@ this from PROMPT.md.
 **Iteration:** 0
 **Size:** [S | M | L]
 
-> **Hydration:** Checkboxes below must be granular — one per unit of work.
-> Steps marked `⚠️ Hydrate` will be expanded by the worker when discoveries
-> from prior steps are available. See task-worker agent for rules.
+> **Hydration:** Checkboxes represent meaningful outcomes, not individual code
+> changes. Workers expand steps when runtime discoveries warrant it — aim for
+> 2-5 outcome-level items per step, not exhaustive implementation scripts.
 
 ---
 

taskplane-tasks/TP-007-resume-reconciliation-across-repos/PROMPT.md

@@ -56,13 +56,14 @@ Extend /orch-resume to reconstruct and continue polyrepo batches using repo-awar
 
 ## Steps
 
-> **Hydration:** STATUS.md checkboxes must match the granularity below.
-> See task-worker agent for full hydration rules.
+> **Hydration:** STATUS.md tracks outcomes, not individual code changes. Workers
+> expand steps when runtime discoveries warrant it. See task-worker agent for rules.
 
 ### Step 0: Implement repo-aware reconciliation
 
-- [ ] Match persisted tasks/lanes to live sessions using repo-aware identifiers
-- [ ] Resolve alive/dead/.DONE states correctly across repo-specific worktrees
+- [ ] Match persisted tasks/lanes to live sessions using repo-aware identifiers (with v1 fallback when repo fields are absent)
+- [ ] Resolve alive/dead/.DONE/worktree states correctly across repo-specific roots
+- [ ] Add tests for mixed-repo reconciliation scenarios
 
 ### Step 1: Compute repo-aware resume point
 

taskplane-tasks/TP-007-resume-reconciliation-across-repos/STATUS.md

@@ -8,16 +8,18 @@
 **Iteration:** 0
 **Size:** L
 
-> **Hydration:** Checkboxes below must be granular — one per unit of work.
-> Steps marked `⚠️ Hydrate` will be expanded by the worker.
+> **Hydration:** Checkboxes represent meaningful outcomes, not individual code
+> changes. Workers expand steps when runtime discoveries warrant it — aim for
+> 2-5 outcome-level items per step, not exhaustive implementation scripts.
 
 ---
 
 ### Step 0: Implement repo-aware reconciliation
 **Status:** ⬜ Not Started
 
-- [ ] Match persisted tasks/lanes to live sessions using repo-aware identifiers
-- [ ] Resolve alive/dead/.DONE states correctly across repo-specific worktrees
+- [ ] Match persisted tasks/lanes to live sessions using repo-aware identifiers (with v1 fallback when repo fields are absent)
+- [ ] Resolve alive/dead/.DONE/worktree states correctly across repo-specific roots
+- [ ] Add tests for mixed-repo reconciliation scenarios
 
 ---
 

taskplane-tasks/TP-009-dashboard-repo-aware-observability/PROMPT.md

@@ -55,8 +55,8 @@ Make orchestrator observability repo-aware so operators in large teams can quick
 
 ## Steps
 
-> **Hydration:** STATUS.md checkboxes must match the granularity below.
-> See task-worker agent for full hydration rules.
+> **Hydration:** STATUS.md tracks outcomes, not individual code changes. Workers
+> expand steps when runtime discoveries warrant it. See task-worker agent for rules.
 
 ### Step 0: Extend dashboard data model
 

taskplane-tasks/TP-009-dashboard-repo-aware-observability/STATUS.md

@@ -8,8 +8,9 @@
 **Iteration:** 0
 **Size:** M
 
-> **Hydration:** Checkboxes below must be granular — one per unit of work.
-> Steps marked `⚠️ Hydrate` will be expanded by the worker.
+> **Hydration:** Checkboxes represent meaningful outcomes, not individual code
+> changes. Workers expand steps when runtime discoveries warrant it — aim for
+> 2-5 outcome-level items per step, not exhaustive implementation scripts.
 
 ---
 

taskplane-tasks/TP-012-polyrepo-fixtures-and-regression-suite/PROMPT.md

@@ -61,8 +61,8 @@ Build an integration-grade polyrepo fixture and automated regression suite that
 
 ## Steps
 
-> **Hydration:** STATUS.md checkboxes must match the granularity below.
-> See task-worker agent for full hydration rules.
+> **Hydration:** STATUS.md tracks outcomes, not individual code changes. Workers
+> expand steps when runtime discoveries warrant it. See task-worker agent for rules.
 
 ### Step 0: Build polyrepo fixture workspace
 

taskplane-tasks/TP-012-polyrepo-fixtures-and-regression-suite/STATUS.md

@@ -8,8 +8,9 @@
 **Iteration:** 0
 **Size:** L
 
-> **Hydration:** Checkboxes below must be granular — one per unit of work.
-> Steps marked `⚠️ Hydrate` will be expanded by the worker.
+> **Hydration:** Checkboxes represent meaningful outcomes, not individual code
+> changes. Workers expand steps when runtime discoveries warrant it — aim for
+> 2-5 outcome-level items per step, not exhaustive implementation scripts.
 
 ---
 

templates/agents/task-reviewer.md

@@ -72,6 +72,34 @@ Write to the specified output file using the `write` tool:
 - [Optional improvements, not blocking]
 ```
 
+## Plan Granularity Guidance
+
+When reviewing plans, assess whether the worker's approach will achieve the
+step's **outcomes** — not whether they've listed every function, parameter, and
+import they'll touch.
+
+**Good plan:** Identifies the key behavioral changes, calls out non-obvious
+risks or edge cases, and has a clear testing strategy.
+
+**Over-specified plan (do NOT demand):** 15+ line items naming every helper
+function, every parameter signature, every file to import from. This level of
+detail changes constantly during implementation and turns the worker into a
+checkbox-follower instead of a problem-solver.
+
+When issuing REVISE on a plan, ask for:
+- Missing **outcomes** (what should be true when the step is done)
+- Missing **risk mitigation** (edge cases, backward compatibility, failure paths)
+- Missing **test coverage intent** (what scenarios need testing)
+
+Do NOT ask for:
+- Function-level implementation checklists
+- Per-file change manifests
+- Exhaustive assertion-by-assertion test plans
+
+The worker is an LLM with full codebase access — trust it to figure out
+implementation specifics. Your job is to catch gaps in **what** needs to happen
+and **why**, not to dictate **how** at the code level.
+
 ## Rules
 
 - Be specific — reference actual files and line numbers