@ai-is-gonna/get-tasks-done 0.2.0

package/get-tasks-done/references/planner-gap-closure.md

@@ -0,0 +1,71 @@
+# Gap Closure Mode — Planner Reference
+
+Triggered by `--gaps` flag. Creates plans to address verification or UAT failures.
+
+**Important: Skip deferred items.** When reading VERIFICATION.md, only the `gaps:` section contains actionable items that need closure plans. The `deferred:` section (if present) lists items explicitly addressed in later milestone phases — these are NOT gaps and must be ignored during gap closure planning. Creating plans for deferred items wastes effort on work already scheduled for future phases.
+
+**1. Find gap sources:**
+
+Use init context (from load_project_state) which provides `phase_dir`:
+
+```bash
+# Check for VERIFICATION.md (code verification gaps)
+ls "$phase_dir"/*-VERIFICATION.md 2>/dev/null
+
+# Check for UAT.md with diagnosed status (user testing gaps)
+grep -l "status: diagnosed" "$phase_dir"/*-UAT.md 2>/dev/null
+```
+
+**2. Parse gaps:** Each gap has: truth (failed behavior), reason, artifacts (files with issues), missing (things to add/fix).
+
+**3. Load existing SUMMARYs** to understand what's already built.
+
+**4. Find next plan number:** If plans 01-03 exist, next is 04.
+
+**5. Group gaps into plans** by: same artifact, same concern, dependency order (can't wire if artifact is stub → fix stub first).
+
+**6. Create gap closure tasks:**
+
+```xml
+<task name="{fix_description}" type="auto">
+  <files>{artifact.path}</files>
+  <read_first>{artifact.path}, {relevant SUMMARY/source files}</read_first>
+  <boundaries>
+    Allowed: write only {artifact.path}.
+    Forbidden: {related files/dirs owned by other tasks}
+    Out of scope: deferred items and unrelated verification gaps.
+  </boundaries>
+  <action>
+    {For each item in gap.missing:}
+    - {missing item}
+
+    Reference existing code: {from SUMMARYs}
+    Gap reason: {gap.reason}
+  </action>
+  <acceptance_criteria>
+    - {Mechanical proof the missing item is fixed}
+  </acceptance_criteria>
+  <verify>{How to confirm gap is closed}</verify>
+  <done>{Observable truth now achievable}</done>
+</task>
+```
+
+**7. Assign waves using standard dependency analysis** (same as `assign_waves` step):
+- Plans with no dependencies → wave 1
+- Plans that depend on other gap closure plans → max(dependency waves) + 1
+- Also consider dependencies on existing (non-gap) plans in the phase
+
+**8. Write PLAN.md files:**
+
+```yaml
+---
+phase: XX-name
+plan: NN              # Sequential after existing
+type: execute
+wave: N               # Computed from depends_on (see assign_waves)
+depends_on: [...]     # Other plans this depends on (gap or existing)
+files_modified: [...]
+autonomous: true
+gap_closure: true     # Flag for tracking
+---
+```

package/get-tasks-done/references/planner-graphify-auto-update.md

@@ -0,0 +1,67 @@
+# Graphify Auto-Update — Status Surfacing
+
+> Documents how `gtd-planner` and `gtd-phase-researcher` surface the opt-in graphify auto-update state (issue #3347). The status surface lives inside `graphifyStatus()` in `get-tasks-done/bin/lib/graphify.cjs`; no planner-side prompt changes are required.
+
+## Why this exists
+
+The graph at `.planning/graphs/graph.json` is consumed automatically (every `gtd-planner` and `gtd-phase-researcher` step) but produced manually (`/gtd:graphify build` per session at best). Without auto-update, the producer-consumer gap silently widens with every commit. The existing `stale: true` annotation tells the consumer the mtime is old; it cannot tell the consumer whether the auto-build hook has been running, just failed, or is in flight.
+
+When `graphify.auto_update: true`, the bundled `hooks/gtd-graphify-update.sh` PostToolUse hook fires after HEAD-advancing git operations on the default branch and dispatches `graphify update .` in a detached subprocess. The hook writes a status file synchronously before detach; the detached process rewrites it on completion.
+
+## The status file
+
+`.planning/graphs/.last-build-status.json`:
+
+```json
+{
+  "ts": "2026-05-15T14:02:23Z",
+  "status": "running" | "ok" | "failed",
+  "exit_code": null | <int>,
+  "duration_ms": null | <int>,
+  "head_at_build": "<commit-sha>",
+  "graphify_version": null | "<version>"
+}
+```
+
+The hook writes `status: "running"` synchronously **before** detach, so the next planner invocation can see the in-flight signal even if `graphify update .` has not finished. The detached `hooks/lib/gtd-graphify-rebuild.sh` rewrites the file to `ok` or `failed` on completion (with `exit_code` and `duration_ms`).
+
+## How the planner surfaces it (zero new prompt content)
+
+`graphifyStatus()` in `get-tasks-done/bin/lib/graphify.cjs` reads `.last-build-status.json` and folds the `running` / `failed` states into the existing `stale: true` signal:
+
+```javascript
+const autoUpdateStale =
+  lastBuildAutoUpdate &&
+  (lastBuildAutoUpdate.status === 'failed' || lastBuildAutoUpdate.status === 'running');
+
+return {
+  ...
+  stale: age > STALE_MS || Boolean(autoUpdateStale),
+  ...
+  last_build_auto_update: lastBuildAutoUpdate || null,
+};
+```
+
+The planner and researcher already run `node ... graphify status` inside their `<step name="load_graph_context">` blocks and already have the rule:
+
+> If the status response has `stale: true`, note for later: "Graph is `{age_hours}h` old — treat semantic relationships as approximate."
+
+That rule now fires correctly in three additional cases:
+
+| Trigger | What user sees |
+|---------|----------------|
+| Auto-build status = `failed` | Existing "treat as approximate" note fires (because `stale: true`). The full `last_build_auto_update` object is in the JSON for callers that want exit-code / duration / commit-sha context. |
+| Auto-build status = `running` | Same — the next planner invocation knows the graph is mid-rebuild and treats it as approximate until the detached process completes. |
+| Auto-build status = `ok` AND mtime < 24h | Annotation is silent — the graph is fresh and the most recent auto-build succeeded. |
+
+The file-missing case is silent (the operator either has not opted in or has not yet triggered a HEAD-advancing git op since enabling).
+
+## Why this design
+
+- **No planner-side prompt changes.** Folding into `stale: true` reuses the existing rule, which means no new content in `agents/gtd-planner.md` (which is already at the `< 48K` decomposition limit per `DEFECT.AGENT-FILE-SIZE-CAP-BREACH`).
+- **Tests catch regressions on the seam.** `tests/feat-3347-graphify-auto-update-config.test.cjs` pins `graphifyStatus` behavior for status=`failed` / `running` / `ok` / file-missing.
+- **Backwards compatible.** Callers that don't read `last_build_auto_update` see the same shape as before, with `stale` reflecting both mtime AND auto-build state. No consumer breakage.
+
+## Opt-in reminder
+
+The auto-update mechanism is opt-in (`graphify.auto_update: false` by default per issue #3347). Users who haven't opted in will never produce this file. `graphifyStatus()` returns `last_build_auto_update: null` and falls back to the mtime-only `stale` rule.

package/get-tasks-done/references/planner-human-verify-mode.md

@@ -0,0 +1,57 @@
+# Planner — Human Verification Mode
+
+> Loaded by `gtd-planner` when deciding whether to emit `<task type="checkpoint:human-verify">` tasks. Read `workflow.human_verify_mode` from `.planning/config.json` (default `end-of-phase` since #3309).
+
+## The two modes
+
+### `end-of-phase` (default — issue #3309)
+
+Do **not** emit any `<task type="checkpoint:human-verify">` tasks. Every mid-flight halt costs a full executor cold-start (CLAUDE.md, MEMORY.md, STATE.md, plan re-read on respawn) because subagent context is discarded across the pause; a plan with N human-verify checkpoints pays the cold-start cost N+1 times — measured at "tens of thousands of tokens" per round-trip on real projects. This is the default for that reason.
+
+Instead, fold each would-be verification step into the relevant `auto` task using a `<verify><human-check>` sub-block:
+
+```xml
+<task type="auto">
+  <name>Wire dashboard route</name>
+  <files>app/dashboard/page.tsx, app/api/dashboard/route.ts</files>
+  <action>...</action>
+  <verify>
+    <automated>npm test -- --filter=dashboard</automated>
+    <human-check>
+      <test>Visit http://localhost:3000/dashboard</test>
+      <expected>Sidebar left, content right on desktop &gt;1024px; collapses to hamburger at 768px</expected>
+      <why_human>Visual layout — grep cannot verify breakpoint behavior</why_human>
+    </human-check>
+  </verify>
+  <done>Layout renders correctly across breakpoints</done>
+</task>
+```
+
+The verifier (Step 8) harvests every `<verify><human-check>` block at end-of-phase and consolidates them into the existing `human_needed` → HUMAN-UAT.md path in `workflows/work-task-issue.md`. The user reviews everything in one batch instead of paying a cold-start cost per item.
+
+### `mid-flight` (opt-back-in — pre-#3309 behavior)
+
+Set `gtd config-set workflow.human_verify_mode mid-flight` to restore the canonical mid-flight pattern: emit `<task type="checkpoint:human-verify">` tasks at the points where human confirmation is required, and the executor halts at each one to ask the user.
+
+```xml
+<task type="checkpoint:human-verify" gate="blocking">
+  <what-built>Dev server running at http://localhost:3000</what-built>
+  <how-to-verify>
+    1. Visit /dashboard
+    2. Sidebar collapses at 768px
+  </how-to-verify>
+  <resume-signal>"approved" or describe issues</resume-signal>
+</task>
+```
+
+Choose `mid-flight` when you genuinely need the work to stop before any subsequent task runs (e.g., the next task depends on visual confirmation of the previous one), and you accept the cold-start cost as the price of that hard barrier.
+
+## What is *not* affected
+
+`checkpoint:decision` and `checkpoint:human-action` tasks are still emitted in `end-of-phase` mode. Those gate the work itself (a choice the executor needs from the user, or an auth step only the user can perform), not post-hoc verification of completed work. Only `checkpoint:human-verify` is suppressed.
+
+## Compatibility with other modes
+
+- **`workflow.tdd_mode`**: orthogonal. TDD tasks still emit `tdd="true"` and `<behavior>`; the `<verify>` block carries the human-check sub-element when `human_verify_mode = end-of-phase`.
+- **`MVP_MODE`**: orthogonal. Vertical-slice ordering is unchanged. The first task remains a failing end-to-end test; later auto tasks may carry `<verify><human-check>` instead of standalone checkpoint tasks.
+- **`workflow.auto_advance` / `_auto_chain_active`**: in mid-flight mode these auto-approve checkpoint:human-verify halts. In end-of-phase mode there are no halts to auto-approve, so the flags have no effect on this code path.

package/get-tasks-done/references/planner-mvp-mode.md

@@ -0,0 +1,53 @@
+# Planner — MVP Mode (Vertical Slice Strategy)
+
+> Loaded by `gtd-planner` only when `MVP_MODE=true`. Standard horizontal-layer planning rules continue to apply for all other phases.
+
+## Core Rule
+
+**Decompose by feature slice, not by technical layer.** Every task must move the user-facing capability forward. After each task, a real user can click through more of the feature than they could before.
+
+**Forbidden** in MVP mode:
+- "Create the database schema" as a standalone task
+- "Build the API layer" as a standalone task
+- "Wire up the UI" as a final integration task
+
+**Required** in MVP mode:
+- The first non-test task produces a working end-to-end path. Stubs are allowed for non-critical branches; the happy path must be real.
+- Each subsequent task either adds a new slice OR refines an existing slice (validation, error states, edge cases).
+- The phase goal is framed as a user story: "**As a** [user], **I want to** [do X], **so that** [Y]."
+
+## Task Order Pattern
+
+For a feature `F`:
+
+1. **Failing end-to-end test** for the happy path of `F`.
+2. **Thinnest viable slice** — UI form → API endpoint → DB read/write — that makes the test pass. Hard-coded values, missing validation, no error states are fine here.
+3. **Real data layer** — replace any stubs from Task 2 with real queries.
+4. **Validation + error states** — invalid input, network failure, empty states.
+5. **Production polish** — loading indicators, edge cases, accessibility checks.
+
+Tasks 3-5 are not always all needed; gate by the phase's acceptance criteria.
+
+## Walking Skeleton Mode (`WALKING_SKELETON=true`)
+
+When the orchestrator sets `WALKING_SKELETON=true` (Phase 1 of a new project under `--mvp`), the plan changes shape:
+
+- The "feature" is the application itself. Pick the smallest meaningful capability that proves the full stack works (e.g., "user can sign up and see their name on a dashboard").
+- The plan **must include**:
+  - Project scaffold (framework init, routing, build, lint)
+  - One real DB read/write
+  - One real UI interaction wired to the API
+  - Deployment to a dev environment (or a documented local-run command that exercises the full stack)
+- The plan **must produce** `SKELETON.md` in the phase directory alongside `PLAN.md`. Use the template at `@~/.claude/get-tasks-done/references/skeleton-template.md`. `SKELETON.md` records the architectural decisions that subsequent phases will build on (chosen framework, DB, deployment target, auth approach, directory layout).
+
+`SKELETON.md` is the architectural backbone for every later vertical slice; treat it as a contract, not a scratchpad.
+
+## Anti-Patterns to Reject
+
+- **Layer cake disguised as slices.** Three "vertical" tasks where Task 1 is "all the schemas", Task 2 is "all the endpoints", Task 3 is "all the UI" — that is horizontal planning with new labels. Reject.
+- **Skeleton bloat.** Walking Skeleton is the *thinnest* working stack, not "Phase 1 of a normal app." If Skeleton has more than ~5 tasks, you are not skeletonizing.
+- **Premature SPIDR splitting.** SPIDR splitting is the `mvp-phase` command's job (Phase 2 of the PRD), not the planner's. If the phase scope feels too large, surface it via the verification loop, do not split silently.
+
+## Acceptance Test for Your Plan
+
+Before emitting the plan, ask: **after Task N completes, can a real user *do* something they could not do after Task N-1?** If the answer is "no, but the foundation is laid", you have a horizontal task disguised as a slice. Restructure.

package/get-tasks-done/references/planner-reviews.md

@@ -0,0 +1,39 @@
+# Reviews Mode — Planner Reference
+
+Triggered when orchestrator sets Mode to `reviews`. Replanning from scratch with REVIEWS.md feedback as additional context.
+
+**Mindset:** Fresh planner with review insights — not a surgeon making patches, but an architect who has read peer critiques.
+
+### Step 1: Load REVIEWS.md
+Read the reviews file from `<files_to_read>`. Parse:
+- Per-reviewer feedback (strengths, concerns, suggestions)
+- Consensus Summary (agreed concerns = highest priority to address)
+- Divergent Views (investigate, make a judgment call)
+
+### Step 2: Categorize Feedback
+Group review feedback into:
+- **Must address**: HIGH severity consensus concerns
+- **Should address**: MEDIUM severity concerns from 2+ reviewers
+- **Consider**: Individual reviewer suggestions, LOW severity items
+
+### Step 3: Plan Fresh with Review Context
+Create new plans following the standard planning process, but with review feedback as additional constraints:
+- Each HIGH severity consensus concern MUST have a task that addresses it
+- MEDIUM concerns should be addressed where feasible without over-engineering
+- Note in task actions: "Addresses review concern: {concern}" for traceability
+
+### Step 4: Return
+Use standard PLANNING COMPLETE return format, adding a reviews section:
+
+```markdown
+### Review Feedback Addressed
+
+| Concern | Severity | How Addressed |
+|---------|----------|---------------|
+| {concern} | HIGH | Plan {N}, Task {M}: {how} |
+
+### Review Feedback Deferred
+| Concern | Reason |
+|---------|--------|
+| {concern} | {why — out of scope, disagree, etc.} |
+```

package/get-tasks-done/references/planner-revision.md

@@ -0,0 +1,87 @@
+# Revision Mode — Planner Reference
+
+Triggered when orchestrator provides `<revision_context>` with checker issues. NOT starting fresh — making targeted updates to existing plans.
+
+**Mindset:** Surgeon, not architect. Minimal changes for specific issues.
+
+### Step 1: Load Existing Plans
+
+```bash
+cat .planning/phases/$PHASE-*/$PHASE-*-PLAN.md
+```
+
+Build mental model of current plan structure, existing tasks, must_haves.
+
+### Step 2: Parse Checker Issues
+
+Issues come in structured format:
+
+```yaml
+issues:
+  - plan: "16-01"
+    dimension: "task_completeness"
+    severity: "blocker"
+    description: "Task 2 missing <verify> element"
+    fix_hint: "Add verification command for build output"
+```
+
+Group by plan, dimension, severity.
+
+### Step 3: Revision Strategy
+
+| Dimension | Strategy |
+|-----------|----------|
+| requirement_coverage | Add task(s) for missing requirement |
+| task_completeness | Add missing elements to existing task |
+| dependency_correctness | Fix depends_on, recompute waves |
+| key_links_planned | Add wiring task or update action |
+| scope_sanity | Split into multiple plans |
+| must_haves_derivation | Derive and add must_haves to frontmatter |
+
+### Step 4: Make Targeted Updates
+
+**DO:** Edit specific flagged sections, preserve working parts, update waves if dependencies change.
+
+**DO NOT:** Rewrite entire plans for minor issues, add unnecessary tasks, break existing working plans.
+
+### Step 5: Validate Changes
+
+- [ ] All flagged issues addressed
+- [ ] No new issues introduced
+- [ ] Wave numbers still valid
+- [ ] Dependencies still correct
+- [ ] Files on disk updated
+
+### Step 6: Commit
+
+```bash
+gtd-sdk query commit "fix($PHASE): revise plans based on checker feedback" --files .planning/phases/$PHASE-*/$PHASE-*-PLAN.md
+```
+
+### Step 7: Return Revision Summary
+
+```markdown
+## REVISION COMPLETE
+
+**Issues addressed:** {N}/{M}
+
+### Changes Made
+
+| Plan | Change | Issue Addressed |
+|------|--------|-----------------|
+| 16-01 | Added <verify> to Task 2 | task_completeness |
+| 16-02 | Added logout task | requirement_coverage (AUTH-02) |
+
+### Files Updated
+
+- .planning/phases/16-xxx/16-01-PLAN.md
+- .planning/phases/16-xxx/16-02-PLAN.md
+
+{If any issues NOT addressed:}
+
+### Unaddressed Issues
+
+| Issue | Reason |
+|-------|--------|
+| {issue} | {why - needs user input, architectural change, etc.} |
+```

package/get-tasks-done/references/planner-source-audit.md

@@ -0,0 +1,73 @@
+# Planner Source Audit & Authority Limits
+
+Reference for `agents/gtd-planner.md` — extended rules for multi-source coverage audits and planner authority constraints.
+
+## Multi-Source Coverage Audit Format
+
+Before finalizing plans, produce a **source audit** covering ALL four artifact types:
+
+```
+SOURCE    | ID      | Feature/Requirement          | Plan  | Status    | Notes
+--------- | ------- | ---------------------------- | ----- | --------- | ------
+GOAL      | —       | {phase goal from ROADMAP.md}  | 01-03 | COVERED   |
+REQ       | REQ-14  | OAuth login with Google + GH | 02    | COVERED   |
+REQ       | REQ-22  | Email verification flow      | 03    | COVERED   |
+RESEARCH  | —       | Rate limiting on auth routes | 01    | COVERED   |
+RESEARCH  | —       | Refresh token rotation       | NONE  | ⚠ MISSING | No plan covers this
+CONTEXT   | D-01    | Use jose library for JWT     | 02    | COVERED   |
+CONTEXT   | D-04    | 15min access / 7day refresh  | 02    | COVERED   |
+```
+
+### Four Source Types
+
+1. **GOAL** — The `goal:` field from ROADMAP.md for this phase. The primary success condition.
+2. **REQ** — Every REQ-ID in `phase_req_ids`. Cross-reference REQUIREMENTS.md for descriptions.
+3. **RESEARCH** — Technical approaches, discovered constraints, and features identified in RESEARCH.md. Exclude items explicitly marked "out of scope" or "future work" by the researcher.
+4. **CONTEXT** — Every D-XX decision from CONTEXT.md `<decisions>` section.
+
+### What is NOT a Gap
+
+Do not flag these as MISSING:
+- Items in `## Deferred Ideas` in CONTEXT.md — developer chose to defer these
+- Items scoped to a different phase via `phase_req_ids` — not assigned to this phase
+- Items in RESEARCH.md explicitly marked "out of scope" or "future work" by the researcher
+
+### Handling MISSING Items
+
+If ANY row is `⚠ MISSING`, do NOT finalize the plan set silently. Return to the orchestrator:
+
+```
+## ⚠ Source Audit: Unplanned Items Found
+
+The following items from source artifacts have no corresponding plan:
+
+1. **{SOURCE}: {item description}** (from {artifact file}, section "{section}")
+   - {why this was identified as required}
+
+   Options:
+   A) Add a plan to cover this item
+   B) Split phase: move to a sub-phase
+   C) Defer explicitly: add to backlog with developer confirmation
+
+   → Awaiting developer decision before finalizing plan set.
+```
+
+If ALL rows are COVERED → return `## PLANNING COMPLETE` as normal.
+
+---
+
+## Authority Limits — Constraint Examples
+
+The planner's only legitimate reasons to split or flag a feature are **constraints**, not judgments about difficulty:
+
+**Valid (constraints):**
+- ✓ "This task touches 9 files and would consume ~45% context — split into two tasks"
+- ✓ "No API key or endpoint is defined in any source artifact — need developer input"
+- ✓ "This feature depends on the auth system built in Phase 03, which is not yet complete"
+
+**Invalid (difficulty judgments):**
+- ✗ "This is complex and would be difficult to implement correctly"
+- ✗ "Integrating with an external service could take a long time"
+- ✗ "This is a challenging feature that might be better left to a future phase"
+
+If a feature has none of the three legitimate constraints (context cost, missing information, dependency conflict), it gets planned. Period.