create-battle-plan 1.1.2 → 1.2.0

package/package.json

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

@@ -4,6 +4,21 @@ 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.**
+
+- **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.
+
+**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.
+- `verify-cascade.sh` Check 6 confirms `today.md` is not stale relative to `tasks.yml`.
+
+---
+
 ## 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,57 @@
+#!/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]
+
+const tasks = require('./lib/tasks');
+
+function parseArgs(argv) {
+  const args = { title: null, due: null, tags: [], priority: 2, 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 === '--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] [--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 (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,
+  tags: args.tags,
+  title: args.title,
+  context: args.context || null,
+  done_at: null,
+  snoozed_until: args.snooze || null
+};
+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(',') : ''})`);
+console.log(`  ${args.title}`);
+console.log('');
+console.log('Run `node tools/tasks/render-today.js` to regenerate docs/today.md.');

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

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+// tools/tasks/flush-today.js — reconciles docs/today.md checkbox edits back into tasks.yml.
+// Archives the processed file to docs/today-archive/YYYY-MM-DD.md.
+//
+// Recognized checkbox states (Obsidian Tasks plugin conventions):
+//   [ ]   open
+//   [x]   done
+//   [X]   done (case-insensitive)
+//   [-]   cancelled
+//   [/]   in-progress (treated as open; surfaces to today section)
+//
+// Tolerated inline metadata (emitted by Obsidian Tasks plugin):
+//   ✅ YYYY-MM-DD  -> done date (overrides today)
+//   📅 YYYY-MM-DD  -> due date (updates if changed)
+//   🛫 YYYY-MM-DD  -> snooze-until (sets status=snoozed)
+//   ⏫ / 🔼 / 🔽    -> priority (updates if changed)
+
+const fs = require('fs');
+const path = require('path');
+const tasks = require('./lib/tasks');
+
+const ROOT = path.resolve(__dirname, '../..');
+const TODAY_MD = path.join(ROOT, 'docs/today.md');
+const ARCHIVE_DIR = path.join(ROOT, 'docs/today-archive');
+
+if (!fs.existsSync(TODAY_MD)) {
+  console.error(`No ${path.relative(ROOT, TODAY_MD)} to flush. Run render-today.js first.`);
+  process.exit(1);
+}
+
+const text = fs.readFileSync(TODAY_MD, 'utf8');
+const lines = text.split('\n');
+
+const state = tasks.load();
+const byId = new Map(state.tasks.map(t => [t.id, t]));
+
+const LINE_RE = /^\s*-\s+\[([ xX\-/])\]\s+TASK-(\d+)\b/;
+const DUE_RE = /📅\s*(\d{4}-\d{2}-\d{2})/;
+const DONE_RE = /✅\s*(\d{4}-\d{2}-\d{2})/;
+const SNOOZE_RE = /🛫\s*(\d{4}-\d{2}-\d{2})/;
+
+function mapCheckbox(ch) {
+  if (ch === ' ') return 'open';
+  if (ch === 'x' || ch === 'X') return 'done';
+  if (ch === '-') return 'cancelled';
+  if (ch === '/') return 'open';
+  return 'open';
+}
+
+let changed = 0;
+const changeLog = [];
+
+for (const line of lines) {
+  const m = line.match(LINE_RE);
+  if (!m) continue;
+  const state_ch = m[1];
+  const id = parseInt(m[2], 10);
+  const task = byId.get(id);
+  if (!task) {
+    console.warn(`⚠️  TASK-${id} in today.md not found in tasks.yml — skipping`);
+    continue;
+  }
+
+  const newStatus = mapCheckbox(state_ch);
+  const dueMatch = line.match(DUE_RE);
+  const doneMatch = line.match(DONE_RE);
+  const snoozeMatch = line.match(SNOOZE_RE);
+
+  const prevStatus = task.status;
+  const patch = {};
+
+  if (snoozeMatch) {
+    patch.status = 'snoozed';
+    patch.snoozed_until = snoozeMatch[1];
+  } else if (newStatus === 'done') {
+    patch.status = 'done';
+    patch.done_at = doneMatch ? doneMatch[1] : tasks.today();
+  } else if (newStatus === 'cancelled') {
+    patch.status = 'cancelled';
+    patch.done_at = doneMatch ? doneMatch[1] : tasks.today();
+  } else {
+    if (prevStatus === 'done' || prevStatus === 'cancelled' || prevStatus === 'snoozed') {
+      patch.status = 'open';
+      patch.done_at = null;
+      patch.snoozed_until = null;
+    }
+  }
+
+  if (dueMatch && dueMatch[1] !== task.due) {
+    patch.due = dueMatch[1];
+  }
+
+  let thisChanged = false;
+  for (const k of Object.keys(patch)) {
+    if (task[k] !== patch[k]) {
+      task[k] = patch[k];
+      thisChanged = true;
+    }
+  }
+
+  if (thisChanged) {
+    changed++;
+    changeLog.push(`  TASK-${id} ${prevStatus} → ${task.status}${task.done_at ? ' (' + task.done_at + ')' : ''} · ${task.title}`);
+  }
+}
+
+if (changed === 0) {
+  console.log('No checkbox changes to flush.');
+  process.exit(0);
+}
+
+tasks.save(state);
+
+if (!fs.existsSync(ARCHIVE_DIR)) fs.mkdirSync(ARCHIVE_DIR, { recursive: true });
+const archivePath = path.join(ARCHIVE_DIR, `${tasks.today()}.md`);
+fs.copyFileSync(TODAY_MD, archivePath);
+
+console.log(`✓ Flushed ${changed} change(s) to tasks.yml`);
+for (const entry of changeLog) console.log(entry);
+console.log(`✓ Archived today.md → ${path.relative(ROOT, archivePath)}`);
+console.log('');
+console.log('Run `node tools/tasks/render-today.js` to regenerate docs/today.md.');

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

@@ -0,0 +1,165 @@
+const fs = require('fs');
+const path = require('path');
+
+const TASKS_PATH = path.resolve(__dirname, '../../../tasks.yml');
+
+const VALID_STATUS = new Set(['open', 'done', 'cancelled', 'snoozed']);
+const VALID_PRIORITY = new Set([1, 2, 3]);
+
+// Minimal YAML reader/writer for our constrained schema.
+// Schema:
+//   last_updated: YYYY-MM-DD
+//   next_id: N
+//   tasks:
+//     - id: N
+//       created: YYYY-MM-DD
+//       due: YYYY-MM-DD | null
+//       status: open|done|cancelled|snoozed
+//       priority: 1|2|3
+//       tags: [a, b]
+//       title: "..."
+//       context: "..."
+//       done_at: YYYY-MM-DD | null
+//       snoozed_until: YYYY-MM-DD | null
+
+const FIELD_ORDER = [
+  'id', 'created', 'due', 'status', 'priority', 'tags',
+  'title', 'context', 'done_at', 'snoozed_until'
+];
+
+function today() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+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 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 => 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 load() {
+  if (!fs.existsSync(TASKS_PATH)) {
+    return { last_updated: today(), next_id: 1, tasks: [] };
+  }
+  const text = fs.readFileSync(TASKS_PATH, 'utf8');
+  const lines = text.split('\n');
+
+  const result = { last_updated: today(), next_id: 1, 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; }
+    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.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.next_id = typeof result.next_id === 'number' ? result.next_id : parseInt(result.next_id, 10) || 1;
+  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 save(state) {
+  state.last_updated = today();
+  const maxId = state.tasks.reduce((m, t) => Math.max(m, t.id || 0), 0);
+  if (state.next_id <= maxId) state.next_id = maxId + 1;
+
+  const out = [];
+  out.push('# tasks.yml — structured task log. Source of truth for docs/today.md.');
+  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}`);
+  out.push('tasks:');
+  for (const t of state.tasks) {
+    let first = true;
+    for (const k of FIELD_ORDER) {
+      if (!(k in t)) continue;
+      const prefix = first ? '  - ' : '    ';
+      out.push(`${prefix}${k}: ${serializeScalar(t[k])}`);
+      first = false;
+    }
+    if (first) continue;
+  }
+  fs.writeFileSync(TASKS_PATH, out.join('\n') + '\n');
+}
+
+function nextId(state) {
+  const id = state.next_id;
+  state.next_id = id + 1;
+  return id;
+}
+
+function resolveSnoozed(state) {
+  const t = today();
+  let changed = 0;
+  for (const task of state.tasks) {
+    if (task.status === 'snoozed' && task.snoozed_until && task.snoozed_until <= t) {
+      task.status = 'open';
+      task.snoozed_until = null;
+      changed++;
+    }
+  }
+  return changed;
+}
+
+module.exports = {
+  TASKS_PATH, VALID_STATUS, VALID_PRIORITY, FIELD_ORDER,
+  today, load, save, nextId, resolveSnoozed
+};

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

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+// tools/tasks/render-today.js — generates docs/today.md from tasks.yml (+ metrics.yml + optional outreach).
+// Idempotent. Safe to run multiple times per day.
+// Flags: --all (include full backlog instead of first 5), --quiet
+
+const fs = require('fs');
+const path = require('path');
+const tasks = require('./lib/tasks');
+
+const ROOT = path.resolve(__dirname, '../..');
+const TODAY_MD = path.join(ROOT, 'docs/today.md');
+const METRICS_YML = path.join(ROOT, 'metrics.yml');
+
+const args = process.argv.slice(2);
+const showAll = args.includes('--all');
+const quiet = args.includes('--quiet');
+
+function readMetrics() {
+  if (!fs.existsSync(METRICS_YML)) return {};
+  const text = fs.readFileSync(METRICS_YML, 'utf8');
+  const out = {};
+  for (const line of text.split('\n')) {
+    const m = line.match(/^(\w+)\s*:\s*(.+?)\s*(#.*)?$/);
+    if (m) {
+      const v = m[2].trim().replace(/^["']|["']$/g, '');
+      out[m[1]] = /^-?\d+$/.test(v) ? parseInt(v, 10) : v;
+    }
+  }
+  return out;
+}
+
+function readLeadsLight() {
+  // Optional — only available when the outreach add-on is installed.
+  const leadsCsv = path.join(ROOT, 'outreach/leads.csv');
+  const leadsLib = path.join(ROOT, 'tools/outreach/lib/leads.js');
+  if (!fs.existsSync(leadsCsv) || !fs.existsSync(leadsLib)) return [];
+  try {
+    const leads = require(leadsLib);
+    return leads.load();
+  } catch (e) {
+    return [];
+  }
+}
+
+function todayStr() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function weekdayName(date) {
+  return ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'][date.getDay()];
+}
+
+function priorityEmoji(p) {
+  if (p === 1) return '⏫';
+  if (p === 2) return '🔼';
+  if (p === 3) return '🔽';
+  return '';
+}
+
+function renderTaskLine(t) {
+  const parts = [];
+  parts.push(`- [ ] TASK-${t.id} ${t.title}`);
+  if (t.due) parts.push(`📅 ${t.due}`);
+  const pe = priorityEmoji(t.priority);
+  if (pe) parts.push(pe);
+  if (Array.isArray(t.tags) && t.tags.length) {
+    parts.push(t.tags.map(x => '#' + x).join(' '));
+  }
+  return parts.join(' ');
+}
+
+function buildCallsSection(leads) {
+  const today = todayStr();
+  const calls = leads.filter(r => r.call_at && r.call_at.startsWith(today) && ['call_booked', 'replied'].includes(r.status));
+  if (calls.length === 0) return null;
+  const lines = ['## Calls & meetings'];
+  for (const c of calls) {
+    const name = [c.first_name, c.last_name].filter(Boolean).join(' ') || '(unnamed)';
+    const time = c.call_at.slice(11, 16) || 'TBD';
+    const note = c.title ? ` (${c.title})` : '';
+    lines.push(`- ${time} — ${name} / ${c.company}${note}`);
+  }
+  return lines.join('\n');
+}
+
+function buildPulseSection(leads, metrics) {
+  if (!leads.length && !Object.keys(metrics).length) return null;
+  const lines = ['## Pulse'];
+  if (leads.length) {
+    const pipeline = leads.filter(r => ['replied', 'call_booked', 'call_done', 'verbal', 'loi'].includes(r.status));
+    const by = s => pipeline.filter(r => r.status === s).length;
+    lines.push(`- Active: ${pipeline.length} (${by('call_booked')} call_booked · ${by('call_done')} call_done · ${by('verbal')} verbal · ${by('replied')} replied)`);
+  }
+  if (metrics.outreach_sent !== undefined) {
+    lines.push(`- Total sent: ${metrics.outreach_sent}${metrics.connections_sent !== undefined ? ` (${metrics.connections_sent} conn + ${metrics.inmails_sent} inmail)` : ''} · ${metrics.responses || 0} replies · ${metrics.discovery_calls || 0} calls · ${metrics.verbal_commitments || 0} verbal`);
+  }
+  if (leads.length) {
+    const warm = leads.filter(r => r.status === 'replied' && r.replied_at);
+    const stale = warm.filter(r => {
+      const d = new Date(r.replied_at);
+      const age = (Date.now() - d.getTime()) / (1000 * 60 * 60 * 24);
+      return age >= 2;
+    }).slice(0, 6);
+    if (stale.length) {
+      const names = stale.map(r => [r.first_name, r.last_name].filter(Boolean).join(' ').trim() || r.company).slice(0, 6);
+      lines.push(`- Needs reply (replied ≥2d ago): ${names.join(', ')}`);
+    }
+  }
+  return lines.length > 1 ? lines.join('\n') : null;
+}
+
+function buildQuerySections(state) {
+  const sections = [];
+  const open = state.tasks.filter(t => t.status === 'open');
+  const byP = p => open.filter(t => t.priority === p).length;
+
+  const commonOpts = [
+    'path includes today.md',
+    'not done',
+    'sort by due',
+    'hide backlink',
+    'hide edit button',
+    'hide task count'
+  ];
+
+  if (byP(1) > 0) {
+    sections.push([
+      '## Today',
+      '```tasks',
+      ...commonOpts,
+      'priority is high',
+      '```'
+    ].join('\n'));
+  }
+  if (byP(2) > 0) {
+    sections.push([
+      '## This week',
+      '```tasks',
+      ...commonOpts,
+      'priority is medium',
+      '```'
+    ].join('\n'));
+  }
+  if (byP(3) > 0) {
+    sections.push([
+      '## Backlog',
+      '```tasks',
+      ...commonOpts,
+      'priority is low',
+      '```'
+    ].join('\n'));
+  }
+
+  const snoozed = state.tasks.filter(t => t.status === 'snoozed');
+  if (snoozed.length) {
+    snoozed.sort((a, b) => (a.snoozed_until || '').localeCompare(b.snoozed_until || ''));
+    const lines = snoozed.slice(0, 5).map(t => `- TASK-${t.id} ${t.title} *(resurfaces ${t.snoozed_until || 'TBD'})*`);
+    sections.push('## Snoozed\n' + lines.join('\n'));
+  }
+
+  return sections;
+}
+
+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 raw = rendered.map(renderTaskLine).join('\n');
+  return [
+    '---',
+    '',
+    '## 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');
+}
+
+// --- Main ---
+
+const state = tasks.load();
+const resurfaced = tasks.resolveSnoozed(state);
+if (resurfaced > 0) {
+  tasks.save(state);
+  if (!quiet) console.log(`↑ Resurfaced ${resurfaced} snoozed task(s) whose date has passed.`);
+}
+
+const metrics = readMetrics();
+const leads = readLeadsLight();
+
+const date = new Date();
+const header = `# Today · ${todayStr()} ${weekdayName(date)}`;
+
+const sections = [];
+sections.push(header);
+
+const preamble = `> *Your daily surface. Check the boxes in Obsidian, then flush with \`node tools/tasks/flush-today.js\`.*\n> *Underlying source of truth: \`tasks.yml\`. Never hand-edit that file while this doc has unflushed changes.*`;
+sections.push(preamble);
+
+const callsBlock = buildCallsSection(leads);
+if (callsBlock) sections.push(callsBlock);
+
+const pulseBlock = buildPulseSection(leads, metrics);
+if (pulseBlock) sections.push(pulseBlock);
+
+for (const s of buildQuerySections(state)) sections.push(s);
+
+sections.push(buildTaskDataSection(state));
+
+const now = new Date();
+const stamp = `${todayStr()} ${String(now.getHours()).padStart(2, '0')}:${String(now.getMinutes()).padStart(2, '0')}`;
+sections.push(`*Generated ${stamp}. Queries above are live — edit checkboxes anywhere, then \`node tools/tasks/flush-today.js\`.*`);
+
+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))`);

package/template/tools/verify-cascade.sh

@@ -136,6 +136,22 @@ while IFS= read -r doc; do
   done < <(grep -oE '\(→ [^)]+\)' "$doc" 2>/dev/null || true)
 done < <(find "$DOCS_DIR" -name "*.md" -not -path "*/examples/*" 2>/dev/null)
 
+# --- Check 6: today.md freshness (task subsystem) ---
+echo ""
+echo "--- Check 6: today.md Freshness ---"
+
+TASKS_YML="$REPO_ROOT/tasks.yml"
+TODAY_MD="$DOCS_DIR/today.md"
+if [ -f "$TASKS_YML" ] && [ -f "$TODAY_MD" ]; then
+  if [ "$TASKS_YML" -nt "$TODAY_MD" ]; then
+    echo "WARNING: tasks.yml is newer than docs/today.md — run \`node tools/tasks/render-today.js\`"
+    WARNINGS=$((WARNINGS + 1))
+  fi
+elif [ -f "$TASKS_YML" ] && [ ! -f "$TODAY_MD" ]; then
+  echo "WARNING: tasks.yml exists but docs/today.md does not — run \`node tools/tasks/render-today.js\`"
+  WARNINGS=$((WARNINGS + 1))
+fi
+
 # --- Summary ---
 echo ""
 echo "========================="