create-battle-plan 1.2.0 → 1.4.0

package/template/tools/events/lib/events.js

@@ -0,0 +1,221 @@
+// tools/events/lib/events.js — YAML reader/writer for events.yml + events-archive.yml.
+// Mirrors the shape of tools/tasks/lib/tasks.js — self-contained, no external YAML deps.
+// An "event" is something with a start datetime AND a counterparty (calls, demos, meetings,
+// dentist appointments). Deadline-only items (no time-of-day, no attendee) belong in tasks.yml.
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '../../..');
+const EVENTS_PATH = path.join(ROOT, 'events.yml');
+const ARCHIVE_PATH = path.join(ROOT, 'events-archive.yml');
+
+const VALID_STATUS = new Set(['scheduled', 'in_progress', 'done', 'cancelled', 'no_show', 'rescheduled']);
+// VALID_TYPE is intentionally permissive — adapt per project. The set below lists common types;
+// any string passes through (add.js validates against this set only for known categories).
+const VALID_TYPE = new Set(['demo', 'discovery', 'investor', 'admin', 'personal', 'unspecified', 'other']);
+
+const FIELD_ORDER = [
+  'id', 'title', 'start', 'end', 'type', 'status',
+  'attendees', 'lead_id', 'location', 'notes',
+  'source', 'created_at',
+  'transcript_path', 'spawned_tasks', 'hypothesis_impacts', 'gate_completed_at'
+];
+
+function today() { return new Date().toISOString().slice(0, 10); }
+function nowIso() { return new Date().toISOString(); }
+
+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 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 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 loadFile(p) {
+  if (!fs.existsSync(p)) {
+    return { last_updated: today(), next_id: 1, events: [] };
+  }
+  const text = fs.readFileSync(p, 'utf8');
+  const lines = text.split('\n');
+  const result = { last_updated: today(), next_id: 1, events: [] };
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (/^\s*#/.test(line) || line.trim() === '') { i++; continue; }
+    if (/^events\s*:\s*$/.test(line)) { i++; break; }
+    const m = line.match(/^(\w+)\s*:\s*(.*)$/);
+    if (m) result[m[1]] = parseScalar(m[2]);
+    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.events.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.events.push(cur);
+  result.next_id = typeof result.next_id === 'number' ? result.next_id : parseInt(result.next_id, 10) || 1;
+  result.events.forEach(e => {
+    if (typeof e.id === 'string') e.id = parseInt(e.id, 10);
+    for (const k of ['attendees', 'spawned_tasks', 'hypothesis_impacts']) {
+      if (e[k] && !Array.isArray(e[k])) e[k] = [e[k]];
+    }
+  });
+  return result;
+}
+
+function saveFile(p, state, header) {
+  state.last_updated = today();
+  const maxId = state.events.reduce((m, e) => Math.max(m, e.id || 0), 0);
+  if (state.next_id <= maxId) state.next_id = maxId + 1;
+  const out = [];
+  out.push(header);
+  out.push(`last_updated: ${state.last_updated}`);
+  out.push(`next_id: ${state.next_id}`);
+  out.push('events:');
+  for (const e of state.events) {
+    let first = true;
+    for (const k of FIELD_ORDER) {
+      if (!(k in e)) continue;
+      const prefix = first ? '  - ' : '    ';
+      out.push(`${prefix}${k}: ${serializeScalar(e[k])}`);
+      first = false;
+    }
+  }
+  fs.writeFileSync(p, out.join('\n') + '\n');
+}
+
+function load() { return loadFile(EVENTS_PATH); }
+function loadArchive() { return loadFile(ARCHIVE_PATH); }
+
+function save(state) {
+  saveFile(EVENTS_PATH, state,
+    '# events.yml — single source of truth for future time-based events (calls, demos, meetings).\n# Past/completed events live in events-archive.yml. Tasks (deadline-only, no time-span) live in tasks.yml.');
+}
+
+function saveArchive(state) {
+  saveFile(ARCHIVE_PATH, state,
+    '# events-archive.yml — past/completed events. Mirrors events.yml schema.\n# Wrap-up gate moves events here after transcript + insights captured.');
+}
+
+function nextId(state) {
+  // Shared ID space across events.yml + events-archive.yml. An event's ID never changes when archived.
+  const cur = state.next_id || 1;
+  const archived = loadArchive();
+  const maxArch = archived.events.reduce((m, e) => Math.max(m, e.id || 0), 0);
+  const id = Math.max(cur, maxArch + 1);
+  state.next_id = id + 1;
+  return id;
+}
+
+// Idempotent: matches on (id) first, then (lead_id + start) tuple. Safe to call from
+// retried flush-* scripts without creating duplicate rows for the same real-world event.
+function upsert(state, event) {
+  let idx = -1;
+  if (event.id) idx = state.events.findIndex(e => e.id === event.id);
+  if (idx < 0 && event.lead_id && event.start) {
+    idx = state.events.findIndex(e => e.lead_id === event.lead_id && e.start === event.start);
+  }
+  if (idx >= 0) {
+    state.events[idx] = { ...state.events[idx], ...event };
+    return { action: 'updated', event: state.events[idx] };
+  }
+  if (!event.id) event.id = nextId(state);
+  if (!event.created_at) event.created_at = nowIso();
+  state.events.push(event);
+  return { action: 'inserted', event };
+}
+
+function upcoming({ from = nowIso() } = {}) {
+  return load().events
+    .filter(e => e.start && e.start >= from && (e.status === 'scheduled' || e.status === 'in_progress' || e.status === 'done'))
+    .sort((a, b) => String(a.start).localeCompare(String(b.start)));
+}
+
+function todayEvents({ on = today() } = {}) {
+  return load().events
+    .filter(e => e.start && String(e.start).startsWith(on)
+      && (e.status === 'scheduled' || e.status === 'in_progress' || e.status === 'done'))
+    .sort((a, b) => String(a.start).localeCompare(String(b.start)));
+}
+
+function dueForGate({ now = nowIso() } = {}) {
+  return load().events
+    .filter(e => {
+      if (e.gate_completed_at) return false;
+      if (e.status === 'cancelled' || e.status === 'rescheduled') return false;
+      const endOrStart = e.end || e.start;
+      return endOrStart && endOrStart < now;
+    })
+    .sort((a, b) => String(a.start).localeCompare(String(b.start)));
+}
+
+// Lead-level lookup — used by metrics scripts to know if a lead ever had a call.
+// Unions events.yml + events-archive.yml so historical calls survive after archival.
+function leadHadCall(leadId) {
+  if (!leadId) return false;
+  const all = [...load().events, ...loadArchive().events];
+  return all.some(e => e.lead_id === leadId
+    && (e.status === 'done' || e.status === 'in_progress'
+        || (e.status === 'scheduled' && e.start && e.start < nowIso())));
+}
+
+function eventsByLead(leadId) {
+  if (!leadId) return [];
+  return [...load().events, ...loadArchive().events].filter(e => e.lead_id === leadId);
+}
+
+function defaultEnd(startIso, durationMin = 30) {
+  if (!startIso) return null;
+  const d = new Date(startIso);
+  if (isNaN(d.getTime())) return null;
+  d.setMinutes(d.getMinutes() + durationMin);
+  return d.toISOString();
+}
+
+module.exports = {
+  EVENTS_PATH, ARCHIVE_PATH, VALID_STATUS, VALID_TYPE, FIELD_ORDER,
+  today, nowIso, defaultEnd,
+  load, loadArchive, save, saveArchive, nextId, upsert,
+  upcoming, todayEvents, dueForGate, leadHadCall, eventsByLead
+};

package/template/tools/events/migrate-from-csv.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+// tools/events/migrate-from-csv.js — one-shot migration for installs that previously stored
+// scheduled calls as outreach/leads.csv:call_at. Splits the column into events.yml (future)
+// + events-archive.yml (past), then strips the call_at values from leads.csv.
+//
+// Idempotent — keys on (lead_id + start). Safe to re-run; already-present rows are skipped.
+// Profile A (base only) installs without leads.csv: the script no-ops with a helpful message.
+//
+// Run with --commit to persist; otherwise dry-run.
+
+const fs = require('fs');
+const path = require('path');
+const E = require('./lib/events');
+
+const commit = process.argv.includes('--commit');
+const todayStr = E.today();
+
+const LEADS_LIB = path.resolve(__dirname, '../outreach/lib/leads.js');
+if (!fs.existsSync(LEADS_LIB)) {
+  console.log('No outreach/lib/leads.js found — this install has no CSV to migrate from.');
+  console.log('events.yml + events-archive.yml will be created on first add.');
+  process.exit(0);
+}
+
+const L = require('../outreach/lib/leads');
+const rows = L.load();
+const withCallAt = rows.filter(r => r.call_at && String(r.call_at).trim() !== '');
+
+console.log(`Found ${withCallAt.length} leads with call_at set.`);
+if (withCallAt.length === 0) {
+  console.log('Nothing to migrate.');
+  process.exit(0);
+}
+
+const future = E.load();
+const archive = E.loadArchive();
+
+let nFuture = 0, nArchive = 0, nSkipped = 0;
+
+for (const r of withCallAt) {
+  const raw = String(r.call_at).trim();
+  // Bare YYYY-MM-DD → assume UTC midnight so date doesn't shift. Adapt offset if relevant.
+  const start = raw.length === 10 ? `${raw}T00:00:00+00:00` : raw;
+  const dateOnly = raw.slice(0, 10);
+  const isFuture = dateOnly >= todayStr;
+  const target = isFuture ? future : archive;
+  const status = isFuture ? 'scheduled' : 'done';
+  const name = [r.first_name, r.last_name].filter(Boolean).join(' ') || r.company || r.linkedin_url;
+  const title = `${status === 'done' ? 'Call' : 'Call (scheduled)'} — ${name}${r.company ? ` / ${r.company}` : ''}`;
+
+  const event = {
+    title,
+    start,
+    end: isFuture ? E.defaultEnd(start, 30) : null,
+    type: 'unspecified',
+    status,
+    attendees: [],
+    lead_id: r.linkedin_url || null,
+    location: null,
+    notes: null,
+    source: 'migrate-from-csv',
+  };
+
+  const existingIdx = target.events.findIndex(e => e.lead_id === event.lead_id && e.start === event.start);
+  if (existingIdx >= 0) { nSkipped++; continue; }
+
+  E.upsert(target, event);
+  if (isFuture) nFuture++; else nArchive++;
+}
+
+console.log(`Future events to insert:  ${nFuture}`);
+console.log(`Archive events to insert: ${nArchive}`);
+console.log(`Already-present skipped:  ${nSkipped}`);
+
+if (!commit) {
+  console.log('\nDry-run. Re-run with --commit to write events.yml + events-archive.yml + strip call_at.');
+  process.exit(0);
+}
+
+E.save(future);
+E.saveArchive(archive);
+console.log('\nWrote events.yml + events-archive.yml.');
+
+console.log('\nStripping call_at values from leads.csv...');
+let stripped = 0;
+for (const r of rows) {
+  if (r.call_at && r.call_at !== '') { r.call_at = ''; stripped++; }
+}
+L.save(rows);
+console.log(`Cleared call_at on ${stripped} rows. The column itself is dropped on next save once HEADERS is updated.`);

package/template/tools/events/upcoming.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+// tools/events/upcoming.js — list scheduled events from now forward.
+// Flags: --json | --today (only events starting today) | --days N (next N days)
+// Used by render-today.js, good-morning, wrap-up.
+
+const E = require('./lib/events');
+
+const args = process.argv.slice(2);
+const asJson = args.includes('--json');
+const onlyToday = args.includes('--today');
+const daysIdx = args.indexOf('--days');
+const days = daysIdx >= 0 ? parseInt(args[daysIdx + 1], 10) : null;
+
+let events;
+if (onlyToday) {
+  events = E.todayEvents();
+} else if (days) {
+  const now = new Date();
+  const until = new Date(now.getTime() + days * 86400 * 1000).toISOString();
+  events = E.upcoming().filter(e => e.start <= until);
+} else {
+  events = E.upcoming();
+}
+
+if (asJson) {
+  console.log(JSON.stringify(events, null, 2));
+} else {
+  if (!events.length) { console.log('(no upcoming events)'); process.exit(0); }
+  for (const e of events) {
+    const time = e.start.length >= 16 ? e.start.slice(0, 16).replace('T', ' ') : e.start.slice(0, 10);
+    console.log(`EVT-${e.id}  ${time}  [${e.type}/${e.status}]  ${e.title}`);
+  }
+}

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;
     }
   }