create-battle-plan 1.1.2 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-battle-plan",
-  "version": "1.1.2",
+  "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/good-morning.md

@@ -63,11 +63,15 @@ Then show a **compact metrics table** (all zeros, no targets yet) and transition
 
 *Skip this on first run (Step 0 handles it). On all subsequent runs, start here.*
 
-Read all of these in parallel:
-- `metrics.yml` — current numbers
-- `docs/battle-plan.md` — TL;DR + latest day log (find today or the most recent day entry)
+Run these in parallel:
+- `node tools/tasks/render-today.js --quiet` — regenerate `docs/today.md` from `tasks.yml`
+- Read `metrics.yml` — current numbers
+- Read `docs/today.md` — user's daily surface (open tasks, calls, pulse)
+- Read `docs/battle-plan.md` TL;DR + latest day log *only if needed for deep context*
 - Run `git log --oneline -15` — what changed since last session
 
+The battle plan is your orientation layer — read it on demand, not by default. `docs/today.md` is what the user sees, so lead with that.
+
 ## Step 2: Present the Briefing
 
 Print a compact morning report with these sections:
@@ -99,6 +103,7 @@ End with 2-3 short questions:
 ## Step 4: Prep the Day
 
 After the user answers:
+- If they drop new tasks verbally, run `node tools/tasks/add.js "..." [--due ...] [--tag ...] [--priority 1|2|3]` for each, then re-run `render-today.js`.
 - If they report any updates → run the full cascade (Steps 0-4 from CLAUDE.md)
 - Update the battle plan day log with today's plan
 

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

@@ -4,6 +4,91 @@ 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 chat is the user's only UI.**
+
+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] [--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/tasks.yml

@@ -0,0 +1,5 @@
+# tasks.yml — structured task log. Source of truth for docs/today.md.
+# Never hand-edit while today.md has unflushed checkbox changes — flush first.
+last_updated: 1970-01-01
+next_id: 1
+tasks:

package/template/tools/tasks/add.js

@@ -0,0 +1,96 @@
+#!/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]
+//                                         [--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,
+    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);
+  }
+  args.title = positional.join(' ');
+  return args;
+}
+
+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] [--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);
+}
+
+const state = tasks.load();
+const id = tasks.nextId(state);
+const task = {
+  id,
+  created: tasks.today(),
+  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);
+
+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}`);