create-battle-plan 1.2.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-battle-plan",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Scaffold a Battle Plan project — a markdown-based context system for LLM-powered project management",
   "bin": {
     "create-battle-plan": "./bin/cli.js"

package/template/.claude/commands/weekly-triage.md

@@ -0,0 +1,93 @@
+---
+description: Walk through every open task lane-by-lane with a multi-choice action menu. Closes stale items, merges duplicates, re-lanes mis-classified work. Stamps last_triage_at when done.
+---
+
+# Weekly Triage
+
+Run this once a week to keep `tasks.yml` honest. The user clicks through each open task with arrow-key choices; you apply each decision to `tasks.yml` immediately.
+
+## Step 0 — Anchor to real time
+
+Run `date` to anchor today's date. Don't infer from session context.
+
+## Step 1 — Gather state
+
+Run `node tools/tasks/triage.js --json` and parse the output. Also run `git log --oneline -30` for context on recent commits.
+
+## Step 2 — Briefing
+
+Tell the user the headline numbers from the report's `stats` block:
+
+- Total open
+- Overdue
+- Stale (≥ stale_threshold_days, not overdue)
+- Distribution by lane
+
+Surface anything notable: the worst overdue, the most stale lane, any drift flags.
+
+Ask:
+
+> Walk through lane-by-lane in order (build → outreach → discovery → infra → fundraising → meta), or start with a specific lane?
+
+## Step 3 — Walk one task at a time
+
+For each open task in the chosen order:
+
+1. Show 3-4 lines: title, key flags, a one-line context snippet, and the script's `suggestion` if any.
+2. Use `AskUserQuestion` with these standard options (label them concisely — these are the most common decisions):
+   - **Done** — task is complete
+   - **Snooze 7 days** — defer; resurfaces in a week
+   - **Demote** — drop priority by one
+   - **Merge into TASK-X** — kill this task, fold into another (ask for X)
+3. The user can pick "Other" to type a custom action: `delete`, `promote`, `keep`, `lane <LANE>`, `priority <N>`, `snooze <N>` for a custom snooze window, etc.
+
+**Pacing:** present **one task at a time**. If the user says "go faster" or "skip ahead", batch 3-5 per message. If they say "keep all of these", apply `keep` to the whole lane.
+
+## Step 4 — Apply decisions immediately (no batching)
+
+For each user choice, Edit `tasks.yml` right away. Map decisions:
+
+| Choice | Field changes |
+|---|---|
+| `done` | `status: done`, `done_at: <today>` |
+| `snooze N` | `status: snoozed`, `snoozed_until: <today + N days>` |
+| `demote` | `priority: priority + 1` (capped at 3) |
+| `promote` | `priority: priority - 1` (floored at 1) |
+| `merge X` | `status: cancelled`, prepend `"Merged into TASK-X — <today>"` to context |
+| `delete` | `status: cancelled`, prepend `"Deleted via triage <today>"` to context |
+| `lane <LANE>` | `lane: <LANE>` (validate against VALID_LANES in lib/tasks.js) |
+| `priority <N>` | `priority: <N>` |
+| `keep` | no change |
+
+The "Merge into X" action is high-leverage when triaging a long pile — collapse scattered concerns into a single owner with consolidated context.
+
+## Step 5 — Wrap up
+
+Three things, in order:
+
+### 5a. Stamp `last_triage_at`
+
+This suppresses the SessionStart triage-due nudge until the next cycle. Without this, the nudge keeps firing on every session start and becomes spam.
+
+```bash
+node -e "const t=require('./tools/tasks/lib/tasks'); const s=t.load(); s.last_triage_at='$(date +%Y-%m-%d)'; t.save(s);"
+```
+
+### 5b. Regenerate today.md
+
+```bash
+node tools/tasks/render-today.js
+```
+
+### 5c. Print summary
+
+- Tasks closed: N
+- Tasks snoozed: N
+- Tasks merged: N
+- Tasks re-laned: N
+- Open tasks remaining: N (was N before)
+- Implications-drift heads-up: list any tasks where the linked doc still hasn't moved and the user kept the task open
+
+## Tone
+
+Direct. Bounded decisions. Don't editorialize on each task — you're a UI, not a coach.

package/template/.claude/commands/wrap-up.md

@@ -42,6 +42,28 @@ With all info gathered, run the full cascade from CLAUDE.md:
 4. Run `tools/touch-date.sh` on every modified file
 5. Run `tools/verify-cascade.sh` — fix any errors
 
+## Step 4.5: Task hygiene — REQUIRED daily
+
+This step keeps `tasks.yml` honest. Run before regenerating `today.md` so any closures land in the day's surface.
+
+**4.5a — Detect drift (tasks that should be closed but aren't):**
+
+Run `node tools/tasks/triage.js --json` and scan the output for any open task with non-empty `recent_commits` (commits mentioning `TASK-N` since the task was created). For each:
+- Surface to the user: "TASK-{id} ({title}) — recent commit '{subject}' suggests it's done. Mark closed?"
+- If yes → set `status: done`, `done_at: <today>` via Edit on `tasks.yml`. If no → leave it.
+
+Also surface any open task with `implications_drift` flagged (linked doc untouched since task created) — the user may have closed the work without updating the doc, OR the doc work is genuinely pending.
+
+**4.5b — Archive old closed tasks:**
+
+Run `node tools/tasks/archive.js`. This moves any `status: done|cancelled` row with `done_at < today - 14d` into `tasks-archive.yaml` (created on first run). Idempotent. Default retention = 14 days; pass `--days N` to override or `--all` to archive everything closed.
+
+**4.5c — Regenerate today.md:**
+
+Run `node tools/tasks/render-today.js --quiet` so today's surface reflects any closures from 4.5a.
+
+If 4.5a/4.5b changed anything, list it in Step 5 ("Task hygiene: N closed via git-drift, M archived").
+
 ## Step 5: Report
 
 Print:
@@ -49,6 +71,7 @@ Print:
 - **Docs updated** (list of files touched)
 - **Verification warnings** (if any)
 - **Tomorrow's top priorities** (carry-forwards + known agenda items)
+- **Task hygiene** (if Step 4.5 changed anything)
 
 ## Step 6: Commit
 

package/template/.claude/settings.json

@@ -1,3 +1,16 @@
 {
-  "hooks": {}
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node tools/tasks/triage-due.js 2>/dev/null || true",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
 }

package/template/CLAUDE.md

@@ -6,19 +6,89 @@ You are helping manage an interconnected documentation system. Every document st
 
 ## Two-View Model — Read This First
 
-**The cascade is your orientation layer. `docs/today.md` is the user's operating surface.**
+**The cascade is your orientation layer. `docs/today.md` is the user's operating surface. The chat is the user's only UI.**
 
-- **Your view (the cascade):** `docs/battle-plan.md` at the top, source docs below it, `metrics.yml` as numeric truth. Narrative, deep, linked. You read and write this freely — it is how you reconstruct project state and cascade new information.
-- **User's view:** `docs/today.md`, generated by `tools/tasks/render-today.js` from `tasks.yml`. Rendered in Obsidian Tasks plugin format — query blocks project pill-styled lists over a raw `## Task data` section at the bottom. The user checks boxes in Obsidian; `tools/tasks/flush-today.js` reconciles those edits back into `tasks.yml`. The user's other primary surface is chat — when they want deep context, they ask, and you traverse the cascade on their behalf.
+The user should never have to look at the cascade, the battle plan, `tasks.yml`, or any internal markdown to operate the system. The chat with you is the UI; the cascade is your memory; `docs/today.md` is a thin clickable surface in their editor for ticking through the day. Everything else exists for *you*, not them.
+
+- **Your view (the cascade):** `docs/battle-plan.md` at the top, source docs below it, `metrics.yml` as numeric truth, `tasks.yml` as the structured task log. Narrative, deep, linked. You read and write this freely — it is how you reconstruct project state and cascade new information.
+- **User's view:** `docs/today.md`, generated by `tools/tasks/render-today.js` from `tasks.yml`. Rendered in Obsidian Tasks plugin format — query blocks project pill-styled lists over a raw `## Task data` section at the bottom (lane-grouped within each priority bucket). The user checks boxes in Obsidian; `tools/tasks/flush-today.js` reconciles those edits back into `tasks.yml`. When they want deep context, they ask you in chat — you traverse the cascade on their behalf.
 
 **Rules:**
 - Never grow the battle plan's TL;DR into a wall of prose. Keep header blocks terse; append Daily Log entries chronologically.
-- When the user drops new tasks, add them via `node tools/tasks/add.js "..." [--due YYYY-MM-DD] [--tag X] [--priority 1|2|3]`. Don't bury tasks in battle plan prose.
-- After any task mutation (add, complete, snooze), run `node tools/tasks/render-today.js` so `docs/today.md` stays fresh.
+- When the user drops new tasks, add them via `node tools/tasks/add.js "..." [--due YYYY-MM-DD] [--tag X] [--priority 1|2|3] [--lane LANE] [--implication PATH]`. Don't bury tasks in battle plan prose.
+- After any task mutation (add, complete, snooze, triage), run `node tools/tasks/render-today.js` so `docs/today.md` stays fresh.
 - `verify-cascade.sh` Check 6 confirms `today.md` is not stale relative to `tasks.yml`.
 
 ---
 
+## Task Lanes — what goes where
+
+Every task has a `lane` (groups by *primary action*, not topic). The default vocabulary:
+
+| Lane | Primary action |
+|---|---|
+| `build` | Build, design, or document the product itself (MVP, demos, architecture, integrations) |
+| `outreach` | Cold DMs / InMails / posts / templates / cold-email infra-as-pipeline |
+| `discovery` | Chase or nurture a *named human relationship* — warm intros, follow-ups, scheduling specific calls |
+| `infra` | Plumbing — DNS, GCP/AWS, deploy, env, secrets, cold-email domain warm-up |
+| `fundraising` | Apply to or maintain relationships with accelerators / VCs / angels |
+| `meta` | Doc/process work with no other natural lane (default fallback) |
+
+**Adapt this set to your project.** Lanes are configurable in `tools/tasks/lib/tasks.js` (`VALID_LANES`) — when you change them, also update `tools/tasks/migrate-lanes.js` keyword buckets and the `LANE_DISPLAY` / `LANE_ORDER` tables in `tools/tasks/render-today.js`.
+
+**Personalities don't get their own lane.** A specific advisor or co-founder's input flows into all the action lanes. A task like "ask <advisor> about X" is `discovery` (relationship), `build` (product feedback), or `meta` (process), depending on what *closing* the task produces.
+
+### Strategic vs routine — what belongs in `tasks.yml`
+
+`tasks.yml` is for **ad-hoc strategic / build / discovery-protocol / high-stakes individual conversations.** Examples: a milestone call with a specific stakeholder where multiple people join; a piece of pitch copy that needs to be written by a specific date; a load-bearing architecture decision that gates other work.
+
+Routine lead-by-name follow-ups ("X accepted, send DM") belong in the **outreach blitz pipeline**, not in `tasks.yml`. The blitz already surfaces those through `daily-targets.js` + `leads.csv` flags + accepted-not-replied detection on timers. Don't duplicate that work as tasks.
+
+When uncertain, default to the blitz. `tasks.yml` is a journal of strategic intent, not a worklist.
+
+---
+
+## Weekly Triage — `/weekly-triage`
+
+Run weekly to keep `tasks.yml` honest. The skill (`.claude/commands/weekly-triage.md`) walks the user through every open task one at a time using `AskUserQuestion`'s arrow-key UI. Each decision (`done` / `snooze N` / `demote` / `merge X` / `delete` / `lane LANE` / `priority N` / `keep`) is applied to `tasks.yml` immediately — no batching.
+
+Two automation layers support this:
+
+- **`tools/tasks/triage.js`** — read-only data layer. Surfaces overdue/stale tasks, recent commits mentioning each task ID (signals "this is probably done"), and *implications drift* (when a task's linked doc hasn't been modified since the task was created — meaning the cascade hasn't actually reached the doc). Output as Markdown by default, JSON via `--json` for programmatic consumers.
+- **`tools/tasks/triage-due.js`** — lightweight SessionStart-hook nudge. Silent unless one of three thresholds trips: time-based (≥7d since last triage), stale-task (≥20 open tasks ≥14d old), or volume (≥60 open). Wired in `.claude/settings.json`. The skill stamps `last_triage_at` in `tasks.yml` on completion to suppress the nudge until the next cycle.
+
+When you see the SessionStart nudge fire, mention it in chat ("📋 Last triage was 9d ago — want to run `/weekly-triage`?") but never auto-invoke. The user decides.
+
+### Implications field
+
+Tasks may carry `implications: [docs/path-a.md, docs/path-b.md]` — a list of docs that should change when the task closes. `triage.js` flags drift when a linked doc's last git commit predates the task: the status flip happened, but the cascaded doc-update didn't. When you create a task whose closure should mutate a specific doc, pass `--implication path/to/doc.md` to `add.js` so triage can hold you accountable later.
+
+### `blocked_by` field
+
+Tasks may also carry `blocked_by: [TASK-IDs]` — an array of TASK-IDs that must close before this task is actionable. Set via `add.js --blocked-by N` (repeatable; comma-separated also accepted; each ID validated against existing rows). When at least one blocker is still open:
+
+- `triage.js` shows a `🚧 Blocked by:` line listing each blocker's id, status, and title (open ones flagged 🚧, closed ones ✅).
+- The stale-flag and snooze-or-demote suggestion are **suppressed** — a task waiting on a deliberate blocker shouldn't be penalized for not progressing.
+- The replacement suggestion becomes "blocked — chase blocker(s) or demote".
+- Stats gain a `Blocked by another open task: N` line.
+- `render-today.js` emits a `🚧 blocked-by:TASK-N,TASK-M` token on the task's line — but only for *still-open* blockers, so the token disappears once the blocker closes.
+
+When the user describes a task that genuinely depends on another, set the blocker explicitly (`--blocked-by N`) instead of letting the dependency live in prose. Closure of the blocker doesn't auto-close the dependent — the user picks the action during the next triage.
+
+---
+
+## Task archive — `node tools/tasks/archive.js`
+
+`tasks.yml` is append-only by design (audit trail), but it shouldn't grow forever. The archive script moves any `status: done|cancelled` row with `done_at < today - 14d` into `tasks-archive.yaml` (created on first run, same schema, sorted by `done_at` ascending).
+
+- **Default retention:** 14 days. Pass `--days N` to override, or `--all` to archive every closed row regardless of age.
+- **Idempotent:** dedups by `id` against the existing archive. Safe to run on every `/wrap-up`.
+- **Wired into `/wrap-up` Step 4.5b** — runs daily as part of end-of-day routine.
+- **Backfill safety:** closed rows missing `done_at` get stamped today and kept one cycle (so a date-less row doesn't get archived without chronological position).
+- **Re-importing a task:** intentional friction. Manually move the row from `tasks-archive.yaml` → `tasks.yml` and set `status: open`.
+
+---
+
 ## The Cascade Protocol
 
 **Trigger:** Any incoming information that relates to the project — calls, messages, research, signals, status changes, decisions.

package/template/tools/tasks/add.js

@@ -1,17 +1,33 @@
 #!/usr/bin/env node
 // tools/tasks/add.js — CLI to append a task to tasks.yml.
-// Usage: node tools/tasks/add.js "title" [--due YYYY-MM-DD] [--tag X] [--priority 1|2|3] [--context "..."] [--snooze YYYY-MM-DD]
+// Usage: node tools/tasks/add.js "title" [--due YYYY-MM-DD] [--tag X] [--priority 1|2|3]
+//                                         [--lane LANE] [--implication PATH] [--blocked-by N]
+//                                         [--context "..."] [--snooze YYYY-MM-DD]
+//   --blocked-by: TASK-ID (number) that must close first. Repeatable; comma-separated also accepted.
 
 const tasks = require('./lib/tasks');
 
 function parseArgs(argv) {
-  const args = { title: null, due: null, tags: [], priority: 2, context: null, snooze: null };
+  const args = {
+    title: null, due: null, tags: [], priority: 2,
+    lane: 'meta', implications: [], blockedBy: [],
+    context: null, snooze: null
+  };
   const positional = [];
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--due') args.due = argv[++i];
     else if (a === '--tag') args.tags.push(argv[++i]);
     else if (a === '--priority') args.priority = parseInt(argv[++i], 10);
+    else if (a === '--lane') args.lane = argv[++i];
+    else if (a === '--implication') args.implications.push(argv[++i]);
+    else if (a === '--blocked-by') {
+      const v = argv[++i];
+      for (const part of String(v).split(',')) {
+        const n = parseInt(part.trim(), 10);
+        if (!isNaN(n)) args.blockedBy.push(n);
+      }
+    }
     else if (a === '--context') args.context = argv[++i];
     else if (a === '--snooze') args.snooze = argv[++i];
     else positional.push(a);
@@ -22,13 +38,17 @@ function parseArgs(argv) {
 
 const args = parseArgs(process.argv.slice(2));
 if (!args.title) {
-  console.error('Usage: node tools/tasks/add.js "title" [--due YYYY-MM-DD] [--tag X] [--priority 1|2|3] [--context "..."] [--snooze YYYY-MM-DD]');
+  console.error('Usage: node tools/tasks/add.js "title" [--due YYYY-MM-DD] [--tag X] [--priority 1|2|3] [--lane LANE] [--implication PATH] [--blocked-by N] [--context "..."] [--snooze YYYY-MM-DD]');
   process.exit(1);
 }
 if (!tasks.VALID_PRIORITY.has(args.priority)) {
   console.error(`Invalid priority ${args.priority} — must be 1, 2, or 3.`);
   process.exit(1);
 }
+if (!tasks.VALID_LANES.has(args.lane)) {
+  console.error(`Invalid lane "${args.lane}" — must be one of: ${[...tasks.VALID_LANES].join(', ')}.`);
+  process.exit(1);
+}
 if (args.due && !/^\d{4}-\d{2}-\d{2}$/.test(args.due)) {
   console.error(`Invalid --due ${args.due} — must be YYYY-MM-DD.`);
   process.exit(1);
@@ -42,16 +62,35 @@ const task = {
   due: args.due || null,
   status: args.snooze ? 'snoozed' : 'open',
   priority: args.priority,
+  lane: args.lane,
   tags: args.tags,
   title: args.title,
   context: args.context || null,
   done_at: null,
   snoozed_until: args.snooze || null
 };
+if (args.implications.length) task.implications = args.implications;
+if (args.blockedBy.length) {
+  const knownIds = new Set(state.tasks.map(t => t.id));
+  const unknown = args.blockedBy.filter(n => !knownIds.has(n));
+  if (unknown.length) {
+    console.error(`Invalid --blocked-by: TASK-${unknown.join(', TASK-')} not found in tasks.yml.`);
+    process.exit(1);
+  }
+  task.blocked_by = args.blockedBy;
+}
 state.tasks.push(task);
 tasks.save(state);
 
-console.log(`✓ Added TASK-${id} (priority ${args.priority}${args.due ? ', due ' + args.due : ''}${args.tags.length ? ', tags ' + args.tags.join(',') : ''})`);
+const flagSummary = [
+  `priority ${args.priority}`,
+  `lane ${args.lane}`,
+  args.due && `due ${args.due}`,
+  args.tags.length && `tags ${args.tags.join(',')}`,
+  args.implications.length && `implications ${args.implications.join(',')}`,
+  args.blockedBy.length && `blocked-by TASK-${args.blockedBy.join(' TASK-')}`
+].filter(Boolean).join(', ');
+console.log(`✓ Added TASK-${id} (${flagSummary})`);
 console.log(`  ${args.title}`);
 console.log('');
 console.log('Run `node tools/tasks/render-today.js` to regenerate docs/today.md.');

package/template/tools/tasks/archive.js

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+// tools/tasks/archive.js — move done/cancelled tasks older than N days from tasks.yml → tasks-archive.yaml
+//
+// Purpose: keep tasks.yml lean. Audit trail preserved in tasks-archive.yaml (same schema).
+//
+// Usage:
+//   node tools/tasks/archive.js                  # default: archive done/cancelled with done_at < today - 14d
+//   node tools/tasks/archive.js --days N         # custom threshold
+//   node tools/tasks/archive.js --dry-run        # preview, no writes
+//   node tools/tasks/archive.js --all            # archive ALL done/cancelled regardless of age
+//
+// Idempotent. Safe to run on every /wrap-up.
+
+const fs = require('fs');
+const path = require('path');
+const tasks = require('./lib/tasks');
+
+const ARCHIVE_PATH = path.resolve(__dirname, '../../tasks-archive.yaml');
+const DEFAULT_DAYS = 14;
+
+const args = process.argv.slice(2);
+const dryRun = args.includes('--dry-run');
+const archiveAll = args.includes('--all');
+const daysArg = args.indexOf('--days');
+const days = daysArg >= 0 && args[daysArg + 1] ? parseInt(args[daysArg + 1], 10) : DEFAULT_DAYS;
+
+function today() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function daysAgo(n) {
+  const d = new Date();
+  d.setDate(d.getDate() - n);
+  return d.toISOString().slice(0, 10);
+}
+
+function serializeScalar(v) {
+  if (v === null || v === undefined) return 'null';
+  if (typeof v === 'number' || typeof v === 'boolean') return String(v);
+  if (Array.isArray(v)) {
+    if (v.length === 0) return '[]';
+    return '[' + v.map(x => (typeof x === 'number' || typeof x === 'boolean') ? String(x) : serializeString(x)).join(', ') + ']';
+  }
+  return serializeString(v);
+}
+
+function serializeString(s) {
+  s = String(s);
+  if (s === '' || /^(null|true|false|~)$/.test(s) || /^-?\d+$/.test(s)) {
+    return '"' + s.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
+  }
+  if (/[:#\[\]{},&*!|>'"%@`\n]|^[\s-?]/.test(s)) {
+    return '"' + s.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
+  }
+  return s;
+}
+
+function parseScalar(raw) {
+  const s = raw.trim();
+  if (s === '' || s === 'null' || s === '~') return null;
+  if (s === 'true') return true;
+  if (s === 'false') return false;
+  if (/^-?\d+$/.test(s)) return parseInt(s, 10);
+  if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
+    return s.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, '\\');
+  }
+  if (s.startsWith('[') && s.endsWith(']')) {
+    const inner = s.slice(1, -1).trim();
+    if (!inner) return [];
+    return inner.split(',').map(x => parseScalar(x.trim()));
+  }
+  return s;
+}
+
+function loadArchive() {
+  if (!fs.existsSync(ARCHIVE_PATH)) {
+    return { tasks: [] };
+  }
+  const text = fs.readFileSync(ARCHIVE_PATH, 'utf8');
+  const lines = text.split('\n');
+  const result = { tasks: [] };
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (/^\s*#/.test(line) || line.trim() === '') { i++; continue; }
+    if (/^tasks\s*:\s*$/.test(line)) { i++; break; }
+    i++;
+  }
+  let cur = null;
+  for (; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^\s*#/.test(line) || line.trim() === '') continue;
+    const listItem = line.match(/^\s*-\s+(\w+)\s*:\s*(.*)$/);
+    if (listItem) {
+      if (cur) result.tasks.push(cur);
+      cur = {};
+      cur[listItem[1]] = parseScalar(listItem[2]);
+      continue;
+    }
+    const field = line.match(/^\s+(\w+)\s*:\s*(.*)$/);
+    if (field && cur) {
+      cur[field[1]] = parseScalar(field[2]);
+    }
+  }
+  if (cur) result.tasks.push(cur);
+  result.tasks.forEach(t => {
+    if (typeof t.id === 'string') t.id = parseInt(t.id, 10);
+    if (typeof t.priority === 'string') t.priority = parseInt(t.priority, 10);
+    if (!Array.isArray(t.tags)) t.tags = t.tags ? [t.tags] : [];
+  });
+  return result;
+}
+
+function saveArchive(state) {
+  state.tasks.sort((a, b) => {
+    const ad = a.done_at || '9999-99-99';
+    const bd = b.done_at || '9999-99-99';
+    if (ad !== bd) return ad.localeCompare(bd);
+    return (a.id || 0) - (b.id || 0);
+  });
+
+  const out = [];
+  out.push('# tasks-archive.yaml — done/cancelled tasks moved out of tasks.yml. Audit trail.');
+  out.push('# Same schema as tasks.yml. Sorted by done_at ascending.');
+  out.push(`last_updated: ${today()}`);
+  out.push('tasks:');
+  for (const t of state.tasks) {
+    let first = true;
+    for (const k of tasks.FIELD_ORDER) {
+      if (!(k in t)) continue;
+      const prefix = first ? '  - ' : '    ';
+      out.push(`${prefix}${k}: ${serializeScalar(t[k])}`);
+      first = false;
+    }
+  }
+  fs.writeFileSync(ARCHIVE_PATH, out.join('\n') + '\n');
+}
+
+const state = tasks.load();
+const archive = loadArchive();
+const t0 = today();
+const cutoff = archiveAll ? '9999-99-99' : daysAgo(days);
+
+const toArchive = [];
+const toKeep = [];
+
+for (const t of state.tasks) {
+  const isClosed = t.status === 'done' || t.status === 'cancelled';
+  const closedDate = t.done_at;
+
+  if (isClosed && closedDate && (archiveAll || closedDate < cutoff)) {
+    toArchive.push(t);
+  } else if (isClosed && !closedDate) {
+    // Backfill safety: stamp today and keep one cycle.
+    t.done_at = t0;
+    toKeep.push(t);
+  } else {
+    toKeep.push(t);
+  }
+}
+
+const archivedIds = new Set(archive.tasks.map(t => t.id));
+const newToArchive = toArchive.filter(t => !archivedIds.has(t.id));
+const dupes = toArchive.length - newToArchive.length;
+
+if (dryRun) {
+  console.log(`[DRY RUN] Would archive ${newToArchive.length} task(s) (cutoff: done_at < ${cutoff})`);
+  if (dupes > 0) console.log(`         ${dupes} already in archive (skipped)`);
+  for (const t of newToArchive) {
+    console.log(`  - TASK-${t.id} [${t.status}] done_at=${t.done_at}: ${(t.title || '').slice(0, 80)}`);
+  }
+  console.log(`\nWould keep ${toKeep.length} task(s) in tasks.yml.`);
+  process.exit(0);
+}
+
+if (newToArchive.length === 0) {
+  const closedCount = state.tasks.filter(t => t.status === 'done' || t.status === 'cancelled').length;
+  console.log(`No tasks to archive (cutoff: done_at < ${cutoff}). ${closedCount} closed task(s) still within retention window.`);
+  process.exit(0);
+}
+
+archive.tasks.push(...newToArchive);
+saveArchive(archive);
+
+state.tasks = toKeep;
+tasks.save(state);
+
+console.log(`✓ Archived ${newToArchive.length} task(s) to tasks-archive.yaml`);
+console.log(`  tasks.yml: ${toKeep.length} remaining (was ${toKeep.length + newToArchive.length})`);
+if (dupes > 0) console.log(`  Skipped ${dupes} already-archived task(s).`);
+
+const oldest = newToArchive.reduce((a, b) => ((a.done_at || '9') < (b.done_at || '9') ? a : b));
+const newest = newToArchive.reduce((a, b) => ((a.done_at || '0') > (b.done_at || '0') ? a : b));
+console.log(`  Date range: ${oldest.done_at} → ${newest.done_at}`);

package/template/tools/tasks/flush-today.js

@@ -43,7 +43,7 @@ function mapCheckbox(ch) {
   if (ch === ' ') return 'open';
   if (ch === 'x' || ch === 'X') return 'done';
   if (ch === '-') return 'cancelled';
-  if (ch === '/') return 'open';
+  if (ch === '/') return 'in_progress';
   return 'open';
 }
 
@@ -79,10 +79,14 @@ for (const line of lines) {
     patch.status = 'cancelled';
     patch.done_at = doneMatch ? doneMatch[1] : tasks.today();
   } else {
+    // newStatus is 'open' or 'in_progress'. Resurrect terminal-state tasks and
+    // honor open ↔ in_progress transitions.
     if (prevStatus === 'done' || prevStatus === 'cancelled' || prevStatus === 'snoozed') {
-      patch.status = 'open';
+      patch.status = newStatus;
       patch.done_at = null;
       patch.snoozed_until = null;
+    } else if (prevStatus !== newStatus) {
+      patch.status = newStatus;
     }
   }
 

package/template/tools/tasks/lib/tasks.js

@@ -3,28 +3,37 @@ const path = require('path');
 
 const TASKS_PATH = path.resolve(__dirname, '../../../tasks.yml');
 
-const VALID_STATUS = new Set(['open', 'done', 'cancelled', 'snoozed']);
+const VALID_STATUS = new Set(['open', 'done', 'cancelled', 'snoozed', 'in_progress']);
 const VALID_PRIORITY = new Set([1, 2, 3]);
 
+// Default lane vocabulary. Adapt this to your project — lanes group tasks by
+// primary action, not topic. Update the LANE_KEYWORDS table in
+// tools/tasks/migrate-lanes.js if you change this set.
+const VALID_LANES = new Set(['build', 'outreach', 'discovery', 'infra', 'fundraising', 'meta']);
+
 // Minimal YAML reader/writer for our constrained schema.
 // Schema:
 //   last_updated: YYYY-MM-DD
 //   next_id: N
+//   last_triage_at: YYYY-MM-DD          # optional — set by /weekly-triage to suppress SessionStart nudge
 //   tasks:
 //     - id: N
 //       created: YYYY-MM-DD
 //       due: YYYY-MM-DD | null
-//       status: open|done|cancelled|snoozed
+//       status: open|done|cancelled|snoozed|in_progress
 //       priority: 1|2|3
+//       lane: build|outreach|discovery|infra|fundraising|meta
 //       tags: [a, b]
 //       title: "..."
 //       context: "..."
 //       done_at: YYYY-MM-DD | null
 //       snoozed_until: YYYY-MM-DD | null
+//       implications: [docs/path-a.md, docs/path-b.md]   # optional — docs that should change when this task closes
+//       blocked_by: [TASK-IDs]                             # optional — task IDs that must close before this one is actionable
 
 const FIELD_ORDER = [
-  'id', 'created', 'due', 'status', 'priority', 'tags',
-  'title', 'context', 'done_at', 'snoozed_until'
+  'id', 'created', 'due', 'status', 'priority', 'lane', 'tags',
+  'title', 'context', 'done_at', 'snoozed_until', 'implications', 'blocked_by'
 ];
 
 function today() {
@@ -53,7 +62,9 @@ function serializeScalar(v) {
   if (typeof v === 'number' || typeof v === 'boolean') return String(v);
   if (Array.isArray(v)) {
     if (v.length === 0) return '[]';
-    return '[' + v.map(x => serializeString(x)).join(', ') + ']';
+    // Preserve number/boolean primitives so int-arrays (e.g. blocked_by) don't
+    // get re-quoted as strings on round-trip.
+    return '[' + v.map(x => (typeof x === 'number' || typeof x === 'boolean') ? String(x) : serializeString(x)).join(', ') + ']';
   }
   return serializeString(v);
 }
@@ -126,6 +137,7 @@ function save(state) {
   out.push('# Never hand-edit while today.md has unflushed checkbox changes — flush first.');
   out.push(`last_updated: ${state.last_updated}`);
   out.push(`next_id: ${state.next_id}`);
+  if (state.last_triage_at) out.push(`last_triage_at: ${state.last_triage_at}`);
   out.push('tasks:');
   for (const t of state.tasks) {
     let first = true;
@@ -160,6 +172,6 @@ function resolveSnoozed(state) {
 }
 
 module.exports = {
-  TASKS_PATH, VALID_STATUS, VALID_PRIORITY, FIELD_ORDER,
+  TASKS_PATH, VALID_STATUS, VALID_PRIORITY, VALID_LANES, FIELD_ORDER,
   today, load, save, nextId, resolveSnoozed
 };

package/template/tools/tasks/migrate-lanes.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+// tools/tasks/migrate-lanes.js — one-shot heuristic backfill of `lane` field.
+// Idempotent: skips tasks that already have a valid lane.
+//
+// Usage:
+//   node tools/tasks/migrate-lanes.js          # apply heuristic, write tasks.yml
+//   node tools/tasks/migrate-lanes.js --dry    # show classifications, write nothing
+//
+// Heuristic is intentionally generic. ADAPT the LANE_KEYWORDS table below to
+// your project's vocabulary. Two-pass design: tags first (curated, high
+// signal-to-noise), then title (less curated). Context is NEVER consulted —
+// it often contains incidental words that contaminate classification.
+//
+// Tasks that match no keyword bucket fall back to `meta`. Re-run anytime —
+// already-laned tasks stay put.
+
+const tasks = require('./lib/tasks');
+
+// Adapt these keyword buckets to your project. Lane order matters when a task
+// matches multiple — the first lane in this object wins.
+const LANE_KEYWORDS = {
+  build: [
+    'mvp', 'demo', 'arch', 'architecture', 'integrations', 'product',
+    'feature', 'build', 'ship', 'design', 'frontend', 'backend', 'api', 'ui'
+  ],
+  outreach: [
+    'outreach', 'blitz', 'cold-email', 'cold-dm', 'linkedin', 'template',
+    'cadence', 'pitch-copy', 'content', 'post', 'campaign', 'sequence'
+  ],
+  discovery: [
+    'warm', 'warm-intro', 'intro', 'intros', 'discovery', 'door-opener',
+    'follow-up', 'lead', 'customer', 'prospect', 'champion'
+  ],
+  infra: [
+    'infra', 'gcp', 'aws', 'dns', 'domain', 'ci', 'deploy', 'env',
+    'secrets', 'database', 'monitoring', 'logging'
+  ],
+  fundraising: [
+    'fundraising', 'investor', 'vc', 'angel', 'pitch', 'fund',
+    'accelerator', 'yc', 'spc', 'demo-day'
+  ]
+};
+
+const argv = process.argv.slice(2);
+const dryRun = argv.includes('--dry');
+
+function matchLane(needle) {
+  if (!needle) return null;
+  const lower = needle.toLowerCase();
+  for (const [lane, keywords] of Object.entries(LANE_KEYWORDS)) {
+    for (const kw of keywords) {
+      const re = new RegExp('\\b' + kw.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '\\b', 'i');
+      if (re.test(lower)) return lane;
+    }
+  }
+  return null;
+}
+
+function classify(task) {
+  if (task.lane && tasks.VALID_LANES.has(task.lane)) return { lane: task.lane, source: 'preserved' };
+  // Pass 1: tags (curated, high signal).
+  const tagsNeedle = (Array.isArray(task.tags) ? task.tags : []).join(' ');
+  const fromTags = matchLane(tagsNeedle);
+  if (fromTags) return { lane: fromTags, source: 'tags' };
+  // Pass 2: title (less curated).
+  const fromTitle = matchLane(task.title || '');
+  if (fromTitle) return { lane: fromTitle, source: 'title' };
+  return { lane: 'meta', source: 'fallback' };
+}
+
+const state = tasks.load();
+let changed = 0;
+let kept = 0;
+const summary = { tags: 0, title: 0, fallback: 0, preserved: 0 };
+
+for (const t of state.tasks) {
+  const { lane, source } = classify(t);
+  summary[source]++;
+  if (source === 'preserved') {
+    kept++;
+    continue;
+  }
+  if (t.lane !== lane) {
+    if (!dryRun) t.lane = lane;
+    changed++;
+    if (dryRun) {
+      console.log(`[dry] TASK-${t.id} → ${lane} (via ${source}): ${t.title}`);
+    }
+  }
+}
+
+if (!dryRun && changed > 0) tasks.save(state);
+
+console.log('');
+console.log(`Migration ${dryRun ? '(dry-run) ' : ''}complete.`);
+console.log(`  Preserved (already laned): ${kept}`);
+console.log(`  Classified via tags:       ${summary.tags}`);
+console.log(`  Classified via title:      ${summary.title}`);
+console.log(`  Fell back to meta:         ${summary.fallback}`);
+console.log(`  Total updated:             ${changed}`);
+if (dryRun) {
+  console.log('');
+  console.log('Re-run without --dry to apply.');
+}

package/template/tools/tasks/render-today.js

@@ -57,12 +57,40 @@ function priorityEmoji(p) {
   return '';
 }
 
-function renderTaskLine(t) {
+// Lane vocabulary (mirrors VALID_LANES in lib/tasks.js). Drives display order
+// in today.md and the human-readable label per lane group. Adapt to your project.
+const LANE_DISPLAY = {
+  build: 'Build',
+  outreach: 'Outreach',
+  discovery: 'Discovery',
+  infra: 'Infra',
+  fundraising: 'Fundraising',
+  meta: 'Meta'
+};
+const LANE_ORDER = ['build', 'outreach', 'discovery', 'infra', 'fundraising', 'meta'];
+const PRIORITY_HEADERS = {
+  1: '### ⏫ Today (P1)',
+  2: '### 🔼 This week (P2)',
+  3: '### 🔽 Backlog (P3)'
+};
+
+function renderTaskLine(t, openIds) {
   const parts = [];
-  parts.push(`- [ ] TASK-${t.id} ${t.title}`);
+  const box = t.status === 'in_progress' ? '/' : ' ';
+  parts.push(`- [${box}] TASK-${t.id} ${t.title}`);
   if (t.due) parts.push(`📅 ${t.due}`);
   const pe = priorityEmoji(t.priority);
   if (pe) parts.push(pe);
+  // Nested hashtag — Obsidian Tasks plugin treats this as a filterable lane group.
+  if (t.lane) parts.push(`#lane/${t.lane}`);
+  // Surface still-open blockers only — once the blocker closes, the token disappears
+  // from the daily surface. flush-today.js ignores this token (LINE_RE matches checkbox + TASK-N).
+  if (Array.isArray(t.blocked_by) && t.blocked_by.length) {
+    const stillOpen = openIds ? t.blocked_by.filter(id => openIds.has(id)) : t.blocked_by;
+    if (stillOpen.length) {
+      parts.push(`🚧 blocked-by:TASK-${stillOpen.join(',TASK-')}`);
+    }
+  }
   if (Array.isArray(t.tags) && t.tags.length) {
     parts.push(t.tags.map(x => '#' + x).join(' '));
   }
@@ -111,7 +139,7 @@ function buildPulseSection(leads, metrics) {
 
 function buildQuerySections(state) {
   const sections = [];
-  const open = state.tasks.filter(t => t.status === 'open');
+  const open = state.tasks.filter(t => t.status === 'open' || t.status === 'in_progress');
   const byP = p => open.filter(t => t.priority === p).length;
 
   const commonOpts = [
@@ -162,32 +190,62 @@ function buildQuerySections(state) {
 }
 
 function buildTaskDataSection(state) {
-  const open = state.tasks.filter(t => t.status === 'open');
-  open.sort((a, b) => {
-    if (a.priority !== b.priority) return a.priority - b.priority;
-    if (a.due && b.due) return a.due.localeCompare(b.due);
-    if (a.due) return -1;
-    if (b.due) return 1;
-    return a.id - b.id;
-  });
-
-  let rendered = open;
-  if (!showAll) {
-    const highMed = open.filter(t => t.priority <= 2);
-    const low = open.filter(t => t.priority === 3).slice(0, 5);
-    rendered = [...highMed, ...low];
+  const open = state.tasks.filter(t => t.status === 'open' || t.status === 'in_progress');
+  const openIds = new Set(open.map(t => t.id));
+
+  // Group by priority, then lane.
+  const byPriority = { 1: [], 2: [], 3: [] };
+  for (const t of open) {
+    const p = byPriority[t.priority] || (byPriority[t.priority] = []);
+    p.push(t);
   }
 
-  const raw = rendered.map(renderTaskLine).join('\n');
-  return [
+  const out = [
     '---',
     '',
     '## Task data',
     '',
     '*Source rows for the queries above. `flush-today.js` reads these. Editable — checkboxes, due dates, priorities, snooze (`🛫 YYYY-MM-DD`) all round-trip. Run `node tools/tasks/flush-today.js` after edits.*',
-    '',
-    raw
-  ].join('\n');
+    ''
+  ];
+
+  for (const priority of [1, 2, 3]) {
+    let pTasks = byPriority[priority] || [];
+    if (pTasks.length === 0) continue;
+
+    // P3 (backlog) is collapsed to first 5 unless --all.
+    if (priority === 3 && !showAll) pTasks = pTasks.slice(0, 5);
+
+    out.push(PRIORITY_HEADERS[priority] || `### P${priority}`);
+    out.push('');
+
+    // Group by lane within priority.
+    const byLane = {};
+    for (const t of pTasks) {
+      const lane = t.lane || 'meta';
+      (byLane[lane] = byLane[lane] || []).push(t);
+    }
+
+    const orderedLanes = [
+      ...LANE_ORDER.filter(l => byLane[l]),
+      ...Object.keys(byLane).filter(l => !LANE_ORDER.includes(l))
+    ];
+
+    for (const lane of orderedLanes) {
+      const laneTasks = byLane[lane];
+      laneTasks.sort((a, b) => {
+        if (a.due && b.due) return a.due.localeCompare(b.due);
+        if (a.due) return -1;
+        if (b.due) return 1;
+        return a.id - b.id;
+      });
+      out.push(`**${LANE_DISPLAY[lane] || lane}** (${laneTasks.length})`);
+      for (const t of laneTasks) out.push(renderTaskLine(t, openIds));
+      out.push('');
+    }
+  }
+
+  return out.join('\n').trimEnd();
 }
 
 // --- Main ---
@@ -228,4 +286,8 @@ sections.push(`*Generated ${stamp}. Queries above are live — edit checkboxes a
 const content = sections.join('\n\n') + '\n';
 if (!fs.existsSync(path.dirname(TODAY_MD))) fs.mkdirSync(path.dirname(TODAY_MD), { recursive: true });
 fs.writeFileSync(TODAY_MD, content);
-if (!quiet) console.log(`✓ Wrote ${path.relative(ROOT, TODAY_MD)} (${state.tasks.filter(t => t.status === 'open').length} open task(s))`);
+if (!quiet) {
+  const openCount = state.tasks.filter(t => t.status === 'open').length;
+  const ipCount = state.tasks.filter(t => t.status === 'in_progress').length;
+  console.log(`✓ Wrote ${path.relative(ROOT, TODAY_MD)} (${openCount} open + ${ipCount} in_progress)`);
+}

package/template/tools/tasks/triage-due.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+// tools/tasks/triage-due.js — lightweight SessionStart-hook nudge.
+//
+// Reads tasks.yml only. No git scans, no LLM calls, no per-doc checks.
+// Silent by default — outputs nothing when triage isn't due.
+// Only surfaces when one of the trigger conditions actually fires.
+//
+// Trigger conditions:
+//   1. Time-based:    last_triage_at >= TRIAGE_INTERVAL_DAYS ago, or never triaged with ≥30 open tasks
+//   2. Stale-task:    ≥ STALE_TASK_THRESHOLD open tasks with age ≥ STALE_AGE_DAYS
+//   3. Volume:        ≥ VOLUME_THRESHOLD open total
+//
+// Adjust thresholds for your project's task scale.
+//
+// Flags:
+//   --explain   write all signals to stderr (debug)
+//   --quiet     suppress nudge output (testing)
+
+const tasks = require('./lib/tasks');
+
+const TRIAGE_INTERVAL_DAYS = 7;
+const STALE_TASK_THRESHOLD = 20;
+const STALE_AGE_DAYS = 14;
+const VOLUME_THRESHOLD = 60;
+const NEVER_TRIAGED_MIN_OPEN = 30;
+
+const argv = process.argv.slice(2);
+const explain = argv.includes('--explain');
+const quiet = argv.includes('--quiet');
+
+function daysBetween(a, b) {
+  const ad = new Date(a);
+  const bd = new Date(b);
+  return Math.floor((bd - ad) / 86400000);
+}
+
+const state = tasks.load();
+const today = tasks.today();
+const open = state.tasks.filter(t => t.status === 'open' || t.status === 'in_progress');
+const stale = open.filter(t => {
+  if (!t.created) return false;
+  return daysBetween(t.created, today) >= STALE_AGE_DAYS;
+});
+
+const triggers = [];
+
+if (state.last_triage_at) {
+  const sinceDays = daysBetween(state.last_triage_at, today);
+  if (sinceDays >= TRIAGE_INTERVAL_DAYS) {
+    triggers.push({ kind: 'time', detail: `last triage ${sinceDays}d ago (interval ${TRIAGE_INTERVAL_DAYS}d)` });
+  }
+} else if (open.length >= NEVER_TRIAGED_MIN_OPEN) {
+  triggers.push({ kind: 'never_triaged', detail: `no last_triage_at recorded, ${open.length} open tasks` });
+}
+
+if (stale.length >= STALE_TASK_THRESHOLD) {
+  triggers.push({ kind: 'stale', detail: `${stale.length} open tasks ≥${STALE_AGE_DAYS}d old` });
+}
+
+if (open.length >= VOLUME_THRESHOLD) {
+  triggers.push({ kind: 'volume', detail: `${open.length} open tasks (threshold ${VOLUME_THRESHOLD})` });
+}
+
+if (explain) {
+  process.stderr.write(`triage-due check @ ${today}\n`);
+  process.stderr.write(`  open: ${open.length}, stale (≥${STALE_AGE_DAYS}d): ${stale.length}\n`);
+  process.stderr.write(`  last_triage_at: ${state.last_triage_at || '(never)'}\n`);
+  process.stderr.write(`  triggers: ${triggers.length ? triggers.map(t => t.kind).join(', ') : 'none'}\n`);
+}
+
+if (triggers.length === 0 || quiet) process.exit(0);
+
+const reasons = triggers.map(t => t.detail).join('; ');
+process.stdout.write(`📋 Weekly triage is due — ${reasons}. Run \`/weekly-triage\` when convenient.\n`);

package/template/tools/tasks/triage.js

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+// tools/tasks/triage.js — read-only triage report.
+// Surfaces overdue/stale tasks, recent commits mentioning each task,
+// and "implications drift" (linked doc untouched since task created).
+//
+// Usage:
+//   node tools/tasks/triage.js                  # markdown to stdout
+//   node tools/tasks/triage.js --json           # JSON for programmatic consumers
+//   node tools/tasks/triage.js --lane build     # filter to one lane
+//   node tools/tasks/triage.js --stale-days 14  # tighten staleness threshold (default 7)
+//
+// Strictly read-only. Does NOT mutate tasks.yml.
+// Decisions are applied by the /weekly-triage skill via Edit calls.
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const tasks = require('./lib/tasks');
+
+const ROOT = path.resolve(__dirname, '../..');
+
+const argv = process.argv.slice(2);
+const asJson = argv.includes('--json');
+const laneIdx = argv.indexOf('--lane');
+const laneFilter = laneIdx >= 0 ? argv[laneIdx + 1] : null;
+const staleIdx = argv.indexOf('--stale-days');
+const STALE_DAYS = staleIdx >= 0 ? parseInt(argv[staleIdx + 1], 10) : 7;
+
+function daysBetween(a, b) {
+  const ad = new Date(a);
+  const bd = new Date(b);
+  return Math.floor((bd - ad) / 86400000);
+}
+
+function fileLastMod(relPath) {
+  const abs = path.join(ROOT, relPath);
+  if (!fs.existsSync(abs)) return null;
+  try {
+    const out = execSync(
+      `git -C "${ROOT}" log -1 --format=%cI -- "${relPath}"`,
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }
+    ).trim();
+    return out ? out.slice(0, 10) : null;
+  } catch {
+    return null;
+  }
+}
+
+function commitsMentioning(id) {
+  try {
+    const out = execSync(
+      `git -C "${ROOT}" log --since="60 days ago" --pretty=format:"%h %s" --grep="TASK-${id}\\b" -i`,
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }
+    );
+    return out.trim().split('\n').filter(Boolean).slice(0, 3);
+  } catch {
+    return [];
+  }
+}
+
+// Build a {YYYY-MM-DD: "Day N — title"} map by scanning docs/battle-plan.md for headings.
+// Three formats accepted (covers our actual heading conventions and most plausible variants).
+let _battlePlanDayMap = null;
+function battlePlanDayMap() {
+  if (_battlePlanDayMap !== null) return _battlePlanDayMap;
+  _battlePlanDayMap = {};
+  const bp = path.join(ROOT, 'docs/battle-plan.md');
+  if (!fs.existsSync(bp)) return _battlePlanDayMap;
+  const text = fs.readFileSync(bp, 'utf8');
+  for (const line of text.split('\n')) {
+    // Format A: "### Day N — Weekday Month D *(... · YYYY-MM-DD)*"
+    let m = line.match(/^#{2,4}\s+Day\s+(\d+)\s*[—-]\s*([^*]+?)\s*\*\([^·]*·\s*(\d{4}-\d{2}-\d{2})\)\*\s*$/);
+    if (m) { _battlePlanDayMap[m[3]] = `Day ${m[1]} — ${m[2].trim()}`; continue; }
+    // Format B: "## Day N (YYYY-MM-DD)" or "### Day N (YYYY-MM-DD) — title"
+    m = line.match(/^#{2,4}\s+Day\s+(\d+)\s*\((\d{4}-\d{2}-\d{2})\)\s*(?:[—-]\s*(.+))?$/);
+    if (m) { _battlePlanDayMap[m[2]] = `Day ${m[1]}${m[3] ? ' — ' + m[3].trim() : ''}`; continue; }
+    // Format C: "## YYYY-MM-DD — title"
+    m = line.match(/^#{2,4}\s+(\d{4}-\d{2}-\d{2})\s*(?:[—-]\s*(.+))?$/);
+    if (m) { _battlePlanDayMap[m[1]] = m[2] ? m[2].trim() : 'battle-plan entry'; }
+  }
+  return _battlePlanDayMap;
+}
+
+// Extract transcript paths referenced from a task's tags + context.
+function transcriptRefs(t) {
+  const haystack = [t.context || '', ...(t.tags || [])].join(' ');
+  const matches = haystack.match(/docs\/archive\/validation\/transcripts\/[^\s,;)]+/g);
+  return matches ? Array.from(new Set(matches)) : [];
+}
+
+// Source/origin context — where did this task come from?
+function sourceContext(t) {
+  const out = [];
+  if (t.created) {
+    const dayLabel = battlePlanDayMap()[t.created];
+    if (dayLabel) out.push(`battle-plan: ${dayLabel}`);
+  }
+  for (const tr of transcriptRefs(t)) out.push(`transcript: ${tr}`);
+  const hintTags = (t.tags || []).filter(tag => /^(spawned-by-|from-|call-|h\d+)/i.test(tag));
+  if (hintTags.length) out.push(`tags: ${hintTags.join(', ')}`);
+  return out.length ? out : null;
+}
+
+// Resolve blocked_by IDs to {id, status, title, open} entries.
+function resolveBlockedBy(t, allTasks) {
+  if (!Array.isArray(t.blocked_by) || !t.blocked_by.length) return null;
+  const byId = new Map(allTasks.map(x => [x.id, x]));
+  return t.blocked_by.map(id => {
+    const b = byId.get(id);
+    if (!b) return { id, status: 'unknown', title: '?', open: false };
+    const open = b.status === 'open' || b.status === 'in_progress';
+    return { id, status: b.status, title: (b.title || '').slice(0, 60), open };
+  });
+}
+
+function implicationsDrift(t) {
+  if (!Array.isArray(t.implications) || !t.implications.length) return null;
+  const drift = [];
+  for (const docPath of t.implications) {
+    const lastMod = fileLastMod(docPath);
+    if (!lastMod) {
+      drift.push(`${docPath} (file missing)`);
+      continue;
+    }
+    if (t.created && lastMod < t.created) {
+      drift.push(`${docPath} (last modified ${lastMod}, predates task)`);
+    }
+  }
+  return drift.length ? drift : null;
+}
+
+function suggestion(flags, t) {
+  if (flags.blockedByOpen) return 'blocked — chase blocker(s) or demote';
+  if (flags.overdue && flags.overdueDays > 14) return 'demote (overdue >14d — losing momentum)';
+  if (flags.stale && !t.due) return `snooze ${STALE_DAYS}d or demote (open ${flags.ageDays}d, no due)`;
+  if (flags.commitMentions) return 'check if recent commits closed this — done?';
+  if (flags.drift) return 'close (no longer needed) or promote (chase the doc)';
+  return null;
+}
+
+function buildReport() {
+  const state = tasks.load();
+  const today = tasks.today();
+
+  let open = state.tasks.filter(t => t.status === 'open' || t.status === 'in_progress');
+  if (laneFilter) open = open.filter(t => t.lane === laneFilter);
+
+  const items = [];
+  for (const t of open) {
+    const ageDays = t.created ? daysBetween(t.created, today) : 0;
+    const overdueDays = t.due ? daysBetween(t.due, today) : 0;
+    const blockers = resolveBlockedBy(t, state.tasks);
+    const blockedByOpen = blockers ? blockers.some(b => b.open) : false;
+    const flags = {
+      overdue: t.due && overdueDays > 0,
+      overdueDays,
+      // Suppress the stale flag when the only reason a task is sitting open is a deliberate blocker.
+      stale: !t.due && ageDays >= STALE_DAYS && !blockedByOpen,
+      ageDays,
+      commitMentions: false,
+      drift: false,
+      blockedByOpen
+    };
+    const commits = commitsMentioning(t.id);
+    flags.commitMentions = commits.length > 0;
+    const drift = implicationsDrift(t);
+    flags.drift = drift !== null;
+    const source = sourceContext(t);
+
+    items.push({
+      id: t.id,
+      title: t.title,
+      context: t.context || null,
+      tags: t.tags || [],
+      lane: t.lane || 'meta',
+      priority: t.priority,
+      status: t.status,
+      due: t.due || null,
+      created: t.created || null,
+      ageDays,
+      overdueDays,
+      flags,
+      commits,
+      drift,
+      blockers: blockers || [],
+      source_context: source || [],
+      suggestion: suggestion(flags, t)
+    });
+  }
+
+  items.sort((a, b) => {
+    if (a.flags.overdue !== b.flags.overdue) return a.flags.overdue ? -1 : 1;
+    if (a.priority !== b.priority) return a.priority - b.priority;
+    return b.ageDays - a.ageDays;
+  });
+
+  const stats = {
+    total_open: open.length,
+    overdue: items.filter(i => i.flags.overdue).length,
+    stale: items.filter(i => i.flags.stale && !i.flags.overdue).length,
+    blocked: items.filter(i => i.flags.blockedByOpen).length,
+    by_lane: {}
+  };
+  for (const i of items) {
+    stats.by_lane[i.lane] = (stats.by_lane[i.lane] || 0) + 1;
+  }
+
+  return {
+    generated_at: today,
+    last_triage_at: state.last_triage_at || null,
+    stale_threshold_days: STALE_DAYS,
+    stats,
+    items
+  };
+}
+
+function renderMarkdown(report) {
+  const out = [];
+  out.push(`# Task Triage Report — ${report.generated_at}`);
+  out.push('');
+  if (report.last_triage_at) {
+    const since = daysBetween(report.last_triage_at, report.generated_at);
+    out.push(`*Last triage: ${report.last_triage_at} (${since}d ago).*`);
+  } else {
+    out.push('*No prior triage recorded.*');
+  }
+  out.push('');
+  out.push('## Stats');
+  out.push('');
+  out.push(`- Total open: ${report.stats.total_open}`);
+  out.push(`- Overdue: ${report.stats.overdue}`);
+  out.push(`- Stale (≥${report.stale_threshold_days}d, not overdue, not blocked): ${report.stats.stale}`);
+  out.push(`- Blocked by another open task: ${report.stats.blocked}`);
+  out.push('- By lane:');
+  for (const [lane, n] of Object.entries(report.stats.by_lane)) {
+    out.push(`  - ${lane}: ${n}`);
+  }
+  out.push('');
+  out.push('---');
+  out.push('');
+
+  for (const i of report.items) {
+    const flagBits = [];
+    if (i.flags.overdue) flagBits.push(`\`overdue ${i.flags.overdueDays}d\``);
+    if (i.flags.stale && !i.flags.overdue) flagBits.push(`\`open ${i.flags.ageDays}d\``);
+    if (i.flags.blockedByOpen) {
+      const openIds = i.blockers.filter(b => b.open).map(b => b.id);
+      flagBits.push(`\`blocked by TASK-${openIds.join(', TASK-')}\``);
+    }
+    if (i.flags.drift) flagBits.push('`drift`');
+    if (i.flags.commitMentions) flagBits.push('`commit-mentioned`');
+    const flagStr = flagBits.length ? ' — ' + flagBits.join(' ') : '';
+    const dueStr = i.due ? `due ${i.due}` : 'no due';
+    out.push(`### TASK-${i.id} (P${i.priority} · ${i.lane} · ${dueStr} · age ${i.ageDays}d)${flagStr}`);
+    out.push('');
+    out.push(`**${i.title}**`);
+    if (i.source_context && i.source_context.length) {
+      out.push('');
+      out.push(`*Source:* ${i.source_context.join(' · ')}`);
+    }
+    if (i.context) {
+      out.push('');
+      out.push(`> ${i.context}`);
+    }
+    if (i.tags.length) {
+      out.push('');
+      out.push(`Tags: ${i.tags.map(t => '`' + t + '`').join(' ')}`);
+    }
+    if (i.blockers && i.blockers.length) {
+      const labels = i.blockers.map(b => `TASK-${b.id} [${b.status}]${b.open ? ' 🚧' : ' ✅'} ${b.title}`);
+      out.push('');
+      out.push(`*🚧 Blocked by:* ${labels.join(' · ')}`);
+    }
+    if (i.drift) {
+      out.push('');
+      out.push(`*⚠️ Implications drift:*`);
+      for (const d of i.drift) out.push(`- ${d}`);
+    }
+    if (i.commits.length) {
+      out.push('');
+      out.push('*Recent commits mentioning this task:*');
+      for (const c of i.commits) out.push(`- ${c}`);
+    }
+    if (i.suggestion) {
+      out.push('');
+      out.push(`*Suggestion:* ${i.suggestion}`);
+    }
+    out.push('');
+    out.push('Actions: `[done]` · `[snooze N]` · `[demote]` · `[promote]` · `[merge X]` · `[delete]` · `[keep]` · `[lane LANE]` · `[priority N]`');
+    out.push('');
+    out.push('---');
+    out.push('');
+  }
+  return out.join('\n');
+}
+
+const report = buildReport();
+if (asJson) {
+  process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+} else {
+  process.stdout.write(renderMarkdown(report));
+}