blueprint-feature-tracker-sync

What this skill does

Synchronize the feature tracker JSON with TODO.md and manage task progress.

## When to Use This Skill

| Use this skill when... | Use blueprint-feature-tracker-status instead when... |
|---|---|
| You're reconciling TODO.md checkboxes with the tracker | You want a read-only view of completion stats |
| You're draining WO entries from a taskwarrior sidecar (`--drain-wave`) | You want PRD coverage or ready-to-start lists |
| You're recalculating completion statistics after work | Use feature-tracking instead for low-level FR-code edits |
| You want a markdown progress summary via `--summary` | You need a quick "where are we?" snapshot without writes |

**Note**: As of v1.1.0, feature-tracker.json is the single source of truth for progress tracking. The `tasks` section replaces work-overview.md.

**Usage**: `/blueprint:feature-tracker-sync [--summary] [--drain-wave WO-A,WO-B,...] [--evidence-files <list>] [--evidence <text>]`

**Flags**:
| Flag | Description |
|------|-------------|
| `--summary` | Generate human-readable markdown summary (stdout only, no file) |
| `--drain-wave WO-A,WO-B,...` | Sidecar mode: drain a comma-separated list of completed WOs from `tasks.pending` into `tasks.completed`, then flip any FRs whose `implementing_wos` are now all closed |
| `--evidence-files <list>` | Comma-separated list of files (one per WO) holding the evidence string for `--drain-wave`. Pairs positionally with the WO list |
| `--evidence <text>` | Inline evidence string (single WO only). Use when the text is short and free of single quotes |

---

## Mode Selection (run first)

Decide which mode applies before any work:

1. If `--summary` is present, run **Mode: Generate Summary** and exit.
2. If `--drain-wave` is present, run **Mode: Taskwarrior Sidecar Drain** and exit.
3. Otherwise, run sidecar detection (Step 0 below). If a sidecar is detected and
   `TODO.md` is absent, prefer **Sidecar Drain** semantics for any user-facing
   completion prompts; otherwise run **Mode: Full Sync (Default)**.

---

## Mode: Generate Summary (`--summary`)

When `--summary` is provided, generate a human-readable progress report without modifying any files:

```bash
jq -r '
  "# Work Overview: \(.project)\n\n" +
  "## Current Phase: \(.current_phase // "Not set")\n\n" +
  "**Progress**: \(.statistics.complete)/\(.statistics.total_features) features (\(.statistics.completion_percentage)%)\n\n" +
  "### In Progress\n" +
  (if (.tasks.in_progress | length) == 0 then "- (none)\n" else (.tasks.in_progress | map("- \(.description) [\(.id)]") | join("\n")) + "\n" end) +
  "\n### Pending\n" +
  (if (.tasks.pending | length) == 0 then "- (none)\n" else (.tasks.pending | map("- \(.description) [\(.id)]") | join("\n")) + "\n" end) +
  "\n### Recently Completed\n" +
  (if (.tasks.completed | length) == 0 then "- (none)\n" else (.tasks.completed | map("- \(.description) [\(.id)]") | join("\n")) + "\n" end) +
  "\n## Phase Status\n" +
  (.phases | map("- \(.name): \(.status)") | join("\n"))
' docs/blueprint/feature-tracker.json
```

Output example:
```markdown
# Work Overview: my-project

## Current Phase: phase-1

**Progress**: 22/42 features (52.4%)

### In Progress
- Implement OAuth integration [FR2.3]
- Add rate limiting [FR3.1]

### Pending
- Webhook support [FR4.1]
- Admin dashboard [FR5.1]

### Recently Completed
- User authentication [FR2.1]
- Session management [FR2.2]

## Phase Status
- Foundation: complete
- Core Features: in_progress
- Advanced Features: not_started
```

**Exit** after displaying summary.

## Mode: Full Sync (Default)

### Step 0: Detect taskwarrior sidecar

Determine whether this project uses the taskwarrior-sidecar convention
(taskwarrior is the authoritative pending/completed queue, linked to blueprint
via the `bpid`/`bpdoc` UDAs). Either signal is sufficient:

1. **Marker rule file**: `test -f .claude/rules/task-tracking.md`.
2. **Live taskwarrior linkage**: any task carries a `bpid` matching one of the
   project's blueprint IDs.

   Use the parallel-safe `export | jq` idiom (see
   `.claude/rules/parallel-safe-queries.md`) — never `task list`, which exits
   1 on empty results and silently cancels sibling tool calls in a parallel
   Bash batch:

   ```bash
   task bpid.any: status:any export | jq 'length'
   ```

   Treat any non-zero count as "sidecar present".

If a sidecar is detected, set `SIDECAR=true` and:

- Skip the `TODO.md` reconciliation steps (Steps 4–5, 8) — there is no
  authoritative TODO file to align against.
- Continue with statistics recalculation (Step 6) and tracker write (Step 7),
  using taskwarrior `status:completed` as the truth signal for WO entries.
- When the user is closing one or more WOs, route them to **Mode: Taskwarrior
  Sidecar Drain** instead of editing `TODO.md`.

### Step 1: Check if feature tracking is enabled

```bash
test -f docs/blueprint/feature-tracker.json
```

**If not found**, report:
```
Feature tracking not enabled in this project.
Run `/blueprint:init` and enable feature tracking to get started.
```

### Step 2: Load current state

- Read `docs/blueprint/feature-tracker.json` for current feature and task status
- Read `TODO.md` for checkbox states (if exists)
- Read manifest for configuration

### Step 3: Analyze each feature

For each feature in the tracker:

a. **Verify status consistency**:
   - `complete`: Check TODO.md has `[x]` (if tracked there)
   - `partial`: Some checkboxes checked, some not
   - `in_progress`: Should have entry in `tasks.in_progress`
   - `not_started`: Check TODO.md has `[ ]`, not in completed
   - `blocked`: Note if blocking reason is documented

b. **Check implementation evidence** (REQUIRED — drives status inference for shipped code). For each feature with non-empty `implementation.files`: verify each file exists, backfill `implementation.commits` via `git log --follow --format="%H" -- <file>` (deduped, merged into existing array), and backfill `implementation.tests` via `Glob` on conventional patterns (`tests/**/*<slug>*`, `**/*<slug>*.test.*`, `**/test_*<slug>*.py`).

   **Infer status from evidence** ONLY when current `status == "not_started"`:

   | Evidence | Inferred status |
   |---|---|
   | All files exist AND ≥1 commit touches them | `complete` (pending Step 5 user confirmation) |
   | Some files exist, others missing | `partial` |
   | No listed files exist | leave as `not_started` |

   Never silently downgrade an already-`complete`/`in_progress`/`partial` feature. List flipped features under "Inferred from evidence" in the Step 9 sync report. See [REFERENCE.md](REFERENCE.md#evidence-backfill-jq-recipe) for the canonical merge `jq`.

### Step 4: Detect discrepancies

Look for inconsistencies:
- Feature marked `complete` in tracker but unchecked in TODO.md
- Feature checked in TODO.md but not `complete` in tracker
- Feature in `tasks.in_progress` but tracker says `complete`
- PRD status doesn't match feature implementation status
- Feature marked `not_started` but Step 3b inferred shipped code (confirm via Step 5)

### Step 5: Ask user about discrepancies

If discrepancies found (use AskUserQuestion):
```
question: "Found {N} discrepancies. How should they be resolved?"
options:
  - label: "Update tracker from TODO.md"
    description: "Trust TODO.md, update tracker to match"
  - label: "Update TODO.md from tracker"
    description: "Trust the tracker, update TODO.md to match"
  - label: "Review each discrepancy"
    description: "Show each discrepancy and decide individually"
  - label: "Skip - don't resolve discrepancies"
    description: "Report discrepancies but don't change anything"
```

### Step 6: Recalculate statistics

- Count features by status across all nested levels
- Calculate completion percentage: `(complete / total) * 100`
- Update phase status based on contained features:
  - `complete` if all features complete
  - `in_progress` if any feature in_progress
  - `partial` if some complete, some not
  - `not_started` if no features started

### S