create-battle-plan 1.2.0 → 1.4.0

package/package.json

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

@@ -72,6 +72,18 @@ Run these in parallel:
 
 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 1.6: Events context-debt warning (silent unless overdue)
+
+`events.yml` carries past events that haven't been gated yet (transcript / spawned-tasks / insight not captured). Wrap-up's Step 4.5d handles these — but if the user skipped it or no wrap-up ran, they accumulate as context-debt.
+
+Run `node tools/events/due-for-gate.js --json` and check whether any returned event has `end || start < (now - 2 days)`. If so, surface in the briefing:
+
+> ⚠️ **Context-debt: N past event(s) ungated >2d** — EVT-{id} {title} ({start date}). Run `/wrap-up` Step 4.5d to capture transcript + insights.
+
+Don't walk the gate during good-morning — wrap-up is the right time for that. Just flag it so the user knows.
+
+If no events are returned, or none are >2d old, this step is silent.
+
 ## Step 2: Present the Briefing
 
 Print a compact morning report with these sections:
@@ -97,6 +109,7 @@ Pull all defined metrics from `metrics.yml`. If targets are defined in the battl
 
 End with 2-3 short questions:
 - "Anything happen since we last talked? Replies, updates, new info?"
+- "Any new events to schedule? Calls, demos, meetings I should add to `events.yml`?" — if they name anything, call `node tools/events/add.js --title "..." --start "ISO" [--lead-id <id-if-any>] --source manual-chat`.
 - If there are stale items (no progress for 2+ days), ask about them specifically
 - If a key deliverable is outstanding, ask about it
 

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,64 @@ 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").
+
+**4.5d — Events gate (REQUIRED when past events exist):**
+
+`events.yml` is the single source of truth for time-based events (calls, demos, meetings). Past events that haven't been "gated" (transcript + insights + spawned tasks captured) accumulate as context-debt. This step cycles the user through each one so context lands in the right docs before the event is archived.
+
+Run `node tools/events/due-for-gate.js --json` and parse. If empty, this step is silent — skip to Step 5.
+
+For each event returned, walk the user through them one-by-one (ONE at a time, sequential — do NOT batch):
+
+```
+Gate EVT-{id} — {title}  ({start HH:MM}, type={type})
+  [a] Transcript path? (drag/paste a file path, or "none" for no recording)
+  [b] Hypothesis impacts? (comma-separated like "H47, H49", or "none" — skip if your project has no hypothesis tracker)
+  [c] Tasks spawned? (free-text bullets; each becomes a `tools/tasks/add.js` call)
+  [d] Insight worth saving? (yes → append to the relevant cascade-target doc; no/skip otherwise)
+  [skip]  ← leave gate open, will resurface tomorrow
+```
+
+**Apply each answer immediately:**
+
+- (a) → If a path was provided, copy/symlink the raw transcript to `docs/archive/transcripts/<slug>-YYYY-MM-DD.<ext>` (save raw verbatim FIRST, then distill). Store the final path on the event's `transcript_path` field via the events lib:
+  ```js
+  const E = require('./tools/events/lib/events');
+  const state = E.load();
+  E.upsert(state, { id: <id>, transcript_path: '<path>' });
+  E.save(state);
+  ```
+- (b) → For each `H{n}`, append a short `> **[UPDATE YYYY-MM-DD · Source: EVT-{id} {title}]**` block to `docs/validation/hypotheses.md` (or your equivalent) near the relevant hypothesis. Store the list in the event's `hypothesis_impacts` field via the events lib. Skip if no hypothesis tracker exists.
+- (c) → For each task description, run `node tools/tasks/add.js "<title>" [--due ...] [--lane ...] [--priority ...]`. Capture returned `TASK-N` ids into the event's `spawned_tasks` field.
+- (d) → Append a dated section to the relevant cascade-target doc (e.g. `docs/validation/external-insights.md` for conversation findings) using its `Compression: chronological` format: `## YYYY-MM-DD — <title>` heading.
+- After ALL non-skipped answers applied → stamp `gate_completed_at` (ISO now) on the event via the events lib.
+- If the user picked `[skip]` → leave `gate_completed_at` null; the event resurfaces in tomorrow's wrap-up.
+
+**Outreach add-on (Profile B only):** if `outreach/leads.csv` exists, also ask `[e] Lead status change? (e.g. call_done → verbal, or call_done → dead; "none" if unchanged)`. Update `leads.csv` via the Node load-mutate-save pattern in `tools/outreach/lib/leads.js`, then `node tools/outreach/sync-metrics.js`.
+
+**Finally:** run `node tools/events/archive.js`. Moves gated events (terminal status + `gate_completed_at` set) → `events-archive.yml`. Idempotent.
+
 ## Step 5: Report
 
 Print:
@@ -49,6 +107,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

@@ -1,144 +1,171 @@
-# Battle Plan — System Prompt
+# Battle Plan — Project Instructions
 
-You are helping manage an interconnected documentation system. Every document stays in sync through a cascade protocol. Follow these rules exactly.
+## How this project works — read this first
 
----
-
-## Two-View Model — Read This First
+Two views of the same project, and Claude operates across both.
 
-**The cascade is your orientation layer. `docs/today.md` is the user's operating surface.**
+**Claude's view (the cascade):** `docs/battle-plan.md` at the top, source docs below it (under `docs/`), `metrics.yml` as numeric truth, `events.yml` for time-based events, `tasks.yml` for strategic tasks. Narrative, deep, linked. Claude reads and writes this freely — it's how project state is reconstructed across sessions.
 
-- **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.
+**User's view:** `docs/today.md` — generated by `tools/tasks/render-today.js` from `tasks.yml`, rendered in Obsidian Tasks plugin format (query blocks projecting 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`. Their other primary surface is this chat — when they want deep context, they ask, and Claude traverses 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`.
+**Core principle:** the user should never have to look at the cascade, the battle plan, `tasks.yml`, `events.yml`, or any internal markdown to operate the system. The chat with Claude is the UI; the cascade is Claude's memory; `docs/today.md` is a thin clickable surface for ticking through the day. Everything else exists for Claude, not them.
 
 ---
 
-## The Cascade Protocol
+## The Cascade — the core protocol
 
-**Trigger:** Any incoming information that relates to the project — calls, messages, research, signals, status changes, decisions.
+**Trigger:** any information shared in chat (or surfaced from tool output) that affects project state. This includes:
+- Conversations, calls, or meetings (any signal — positive, negative, ambiguous)
+- Research findings (desk research, web search, competitor intel)
+- New targets, contacts, or refinements
+- Metric changes
+- Information that validates, invalidates, or adds nuance to a hypothesis
+- New time-based events (calls, demos, meetings, anything with a start datetime + counterparty)
+- Outreach activity (if the outreach add-on is installed — Profile B)
 
-When triggered, update in this exact order:
+When triggered, update top-down in this exact order. Each step depends on the one above it. Never skip.
 
-### Step 0: Update `metrics.yml`
-If any key metric changed, update `metrics.yml` first. This is the numeric source of truth.
+```
+Step 0: raw state changes → metrics.yml / tasks.yml / events.yml / (leads.csv if Profile B)
+   ↓
+Step 1: docs/battle-plan.md           ← TL;DR + Key Metrics table + Daily Log entry
+   ↓
+Step 2: source docs (only the relevant ones):
+   ├── docs/validation/external-insights.md   ← conversations & meetings (chronological)
+   ├── docs/validation/hypotheses.md          ← validation/invalidation (amended)
+   ├── docs/market/                           ← persona / strategy / competitive intel
+   ├── docs/research/                         ← foundational knowledge
+   └── (any other domain docs you've added)
+   ↓
+Step 3: tools/touch-date.sh           ← stamp Last Updated on every modified file
+   ↓
+Step 4: tools/verify-cascade.sh       ← verify TL;DR / metrics / dates / today.md staleness
+```
 
-### Step 1: Update Battle Plan (`docs/battle-plan.md`)
-- Update the **TL;DR** with current status
-- Update the **Key Metrics** table (numbers reference metrics.yml)
-- Update **Today's Priorities** if relevant
-- Append to **Daily Log** for today
+If `outreach/leads.csv` exists (Profile B — outreach add-on), Step 0 also covers leads.csv mutations, and `sync-metrics.js` auto-chains from every `flush-*.js` script (it derives `metrics.yml` from the CSV — never hand-edit metrics directly).
 
-### Step 2: Update Cascade Docs
-Update only the docs relevant to the new information. Route new info to the appropriate domain doc under `docs/`. Common patterns:
+**Sources of truth — one per concept, no parallel stores:**
+- `metrics.yml` — every metric (derived from leads.csv when outreach is installed; hand-edited otherwise)
+- `events.yml` / `events-archive.yml` — every time-based event
+- `tasks.yml` — every strategic / build / milestone task
+- `docs/battle-plan.md` — current state ("where are we right now")
+- `outreach/leads.csv` (Profile B only) — every lead
 
-| Info type | Route to... |
-|-----------|------------|
-| Conversation, call, or meeting | `docs/external-insights.md` — append as new dated session |
-| Evidence for/against a hypothesis | The relevant domain doc — amend the claim with an `[UPDATE]` block |
-| Outreach sent/received | The relevant market or sales doc — update tracking tables |
-| Competitor intel | The relevant strategy or market doc |
-| New foundational knowledge | The relevant research or domain doc |
+Never put state in markdown tables that lives somewhere structured. Never create a parallel store.
 
-If no doc exists for the info, append it to the closest domain overview doc. Only create a new file if the info doesn't fit anywhere.
+---
 
-### Step 3: Update Dates
-Run `tools/touch-date.sh` on every file you modified in this session:
+## Behavioral rules — when X happens, do Y
 
-```bash
-tools/touch-date.sh docs/battle-plan.md docs/validation/hypotheses.md [etc.]
-```
+**When the user mentions a time-based event** ("demo with X Thursday 2pm", "advisor call Friday 10am", "dentist Monday 9am"): call `node tools/events/add.js --title "..." --start "ISO" [--lead-id <id>] [--attendee "X"] [--type ...]`. Two criteria for an event (both required): a start datetime AND a counterparty/attendee. Anything failing either stays in `tasks.yml`.
 
-### Step 4: Verify
-Run `tools/verify-cascade.sh` and fix any issues it reports:
+**When the user drops a transcript** (paste, file path, attachment): save the raw verbatim file FIRST to `docs/archive/transcripts/<slug>-YYYY-MM-DD.<ext>`. Do not rewrite, summarize, or trim. THEN distill into the appropriate cascade-target doc. Always link back: `_Raw transcript: [path](...)._` Never delete transcripts — they're immutable audit trail.
 
-```bash
-tools/verify-cascade.sh
-```
+**When the user drops new tasks:** add via `node tools/tasks/add.js "..." --lane LANE [--due ...] [--tag ...] [--priority 1|2|3] [--implication PATH] [--blocked-by N]`. `--lane` is required (one of: `build` / `outreach` / `discovery` / `infra` / `fundraising` / `meta` — customize in `tools/tasks/lib/tasks.js`). After any task mutation, run `node tools/tasks/render-today.js` so `docs/today.md` stays fresh.
 
----
+**When a number from one doc appears in another:** annotate as a markdown link.
+- Tier 1 — numbers in `metrics.yml`: `[**42**](metrics.yml#outreach_sent)`
+- Tier 2 — numbers from another doc: `[**60%**](external-insights.md#session-2) of time on evidence`
+
+Numbers native to a doc (where they originate) have no annotation. Verified by `tools/check-metrics.sh`.
 
-## Source Reference Rules
+**When stating a claim:** mark its confidence — `Unvalidated` / `Soft signal` / `Practitioner-validated` / `Data-validated`. Include the source.
 
-### Registry Metrics (Tier 1 — deterministic)
-Numbers defined in `metrics.yml`. Reference as: `[**N**](metrics.yml#field_name)`
+**When `verify-cascade.sh` reports an issue:** fix it before ending the turn. Don't ship a known-stale state.
 
-This renders as a bold clickable number. Example: `[**42**](metrics.yml#outreach_sent)`
+### Outreach add-on (Profile B only — when `outreach/leads.csv` exists)
 
-These are verified by exact numeric comparison via `tools/check-metrics.sh`.
+**When the user mentions a lead** (reply, accept, call booked, status change, new contact, dead): update `leads.csv` — do not just acknowledge in chat. Options: drop a line into `outreach/inbox/updates.md` + `flush-updates.js` (Haiku-powered), or a Node one-liner. Then run the cascade.
 
-### Inline Metrics (Tier 2 — LLM-verified)
-Less common numbers from another doc. Reference as: `[**N**](source-doc.md#section-slug)`
+**When the user reports a routine lead-by-name follow-up** ("chase X", "second follow-up to Y"): do NOT add to `tasks.yml`. The blitz pipeline (`daily-targets.js`) rotates these automatically from `leads.csv` flags. `tasks.yml` is for strategic / milestone / multi-party work.
 
-Example: `60% of time on evidence [**60**](external-insights.md#session-2-key-insights)`
+**When the user drops names** ("did we already contact X?"): run `node tools/outreach/lookup.js "Name1, Name2, ..."` FIRST. Fuzzy-matches against `leads.csv` — prevents duplicates.
 
-**Rule:** Every number referenced from another document MUST include a source annotation. Only numbers native to a doc (where they originate) have no annotation.
+**When the user asks for numbers** ("how many in X bucket?", "what's the funnel?"): run `node tools/outreach/stats.js` first. Live tally with template performance, weekly breakdown, channel split, FU template breakdown.
 
 ---
 
-## Document Format
+## Schemas & format
 
-Every doc in `docs/` must have this frontmatter:
+### Document frontmatter (every doc in `docs/`)
 
 ```markdown
 # Document Title
 
-**Last Updated:** 2026-04-07
+**Last Updated:** YYYY-MM-DD
 **Status:** Active | Draft | Archived
 **Role:** source-of-truth | cascade-target
 **Compression:** chronological | amended | none
 
-**TL;DR:** One paragraph summary with key numbers and source references.
-
----
+**TL;DR:** One paragraph with key numbers and source references.
 ```
 
-- **Last Updated** must match today's date on any file modified in the current session.
-- **Status:** `Active` = live, `Draft` = WIP, `Archived` = excluded from cascade.
-- **Role:** `source-of-truth` = authoritative for its numbers. `cascade-target` = references numbers from elsewhere.
-- **Compression:** required field. One of `chronological`, `amended`, or `none` (see Compression Modes section below).
-- **TL;DR** must exist and contain all key metrics that appear in the doc.
-
----
-
-## Compression Modes & Timestamping Rules
-
-Every doc declares a `Compression:` mode in frontmatter. This tells the `/distill` command (and humans) how new info gets added to the doc and how old info gets compressed when it grows too long. The mode IS the timestamping rule for new info.
-
-### `Compression: chronological`
-The doc is an append-only log of dated entries. Each new piece of info goes in a new dated section.
-
-- **Timestamping rule:** every new entry MUST start with a dated heading: `## Session N (YYYY-MM-DD) — <title>`, `## YYYY-MM-DD — <title>`, or `## DD Month YYYY — <title>`. No exceptions.
-- **Examples:** `docs/battle-plan.md` (daily log), `docs/validation/external-insights.md` (conversation journal).
-- **`/distill` behavior:** keeps the N most recent dated sections verbatim, archives the rest into `docs/archive/<same-path>`, replaces them with a thorough summary.
-
-### `Compression: amended`
-The doc is a living reference. Claims are amended in place over time.
-
-- **Timestamping rule:** every new finding that revises an existing claim MUST be added as an inline `> **[UPDATE YYYY-MM-DD · Source: ...]**` block placed immediately above the claim it modifies. Brand-new claims with no prior version don't need a stamp; they're stamped implicitly by the doc's `Last Updated` date and git history.
-- **Examples:** `docs/validation/hypotheses.md`, `docs/market/icp-and-targets.md`, `docs/market/competitive-landscape.md`.
-- **`/distill` behavior:** collapses old `[UPDATE]` blocks into the body text (preserving their content as integrated current-state), archives the raw blocks verbatim. Keeps the N most recent amendments per section inline.
-
-### `Compression: none`
-The doc is a static thesis or reference. It gets rewritten, not amended. Git history is the timeline.
-
-- **Timestamping rule:** none. Just edit the doc and let `Last Updated` + git track changes.
-- **Examples:** `docs/strategy/product-thesis.md`, `docs/research/domain-101.md`.
-- **`/distill` behavior:** refuses to run. If a `none` doc has grown unwieldy, rewrite it manually or change its `Compression:` mode first.
-
-### Why this matters
-The TL;DR is current state, not history. It can't tell `/distill` what's new vs old. The `Compression:` mode + timestamping rule is the only mechanism that makes distillation deterministic. Skipping the timestamp on a new entry in a `chronological` or `amended` doc is a bug; it will get silently absorbed into the wrong era during distillation.
-
-When in doubt about which mode a new doc should use: chronological logs choose `chronological`, claim trackers choose `amended`, everything else is `none`.
+- `Last Updated` must match today's date on any file modified in the current session.
+- `Status` — `Active` = live; `Draft` = WIP; `Archived` = excluded from cascade.
+- `Role` — `source-of-truth` = authoritative for its numbers. `cascade-target` = references numbers from elsewhere.
+- `TL;DR` contains all key metrics that appear in the doc.
+
+### Compression modes (drives `/distill`)
+
+| Mode | Doc type | Timestamp rule for new entries |
+|---|---|---|
+| `chronological` | append-only log (battle-plan.md, external-insights.md) | every entry MUST start with a dated heading: `## YYYY-MM-DD — <title>` or `## Session N (YYYY-MM-DD) — <title>` |
+| `amended` | living reference (hypotheses.md, icp-and-targets.md, competitive-landscape.md) | every revision MUST be a `> **[UPDATE YYYY-MM-DD · Source: ...]**` block placed immediately above the claim it modifies |
+| `none` | static thesis (product-thesis.md, domain-101.md) | none — rewrite, don't amend. Git history is the timeline. `/distill` refuses to run. |
+
+Skipping the timestamp on a new entry in a `chronological` or `amended` doc is a bug — it gets silently absorbed into the wrong era during distillation.
+
+### `tasks.yml` — task lanes
+
+Every task has a `lane` (groups by *primary action*, not topic). Default vocabulary (customize in `tools/tasks/lib/tasks.js`):
+
+| Lane | Primary action |
+|---|---|
+| `build` | Build, design, or document the product itself |
+| `outreach` | Cold DMs / InMails / templates / cold-email infra |
+| `discovery` | Chase or nurture a named human relationship |
+| `infra` | Plumbing — DNS, GCP/AWS, deploy, env, secrets |
+| `fundraising` | Accelerator / VC / angel relationships |
+| `meta` | Doc/process work with no other natural lane (default fallback) |
+
+Tasks may carry:
+- `due: YYYY-MM-DD` — deadline (sorted to top by date).
+- `priority: 1|2|3` — Today / This week / Backlog.
+- `implications: [docs/path-a.md, ...]` — docs that should change when the task closes. `triage.js` flags drift when a linked doc's last commit predates the task.
+- `blocked_by: [TASK-IDs]` — tasks that must close first. `render-today.js` emits the marker only for *still-open* blockers.
+
+**Strategic vs routine:** `tasks.yml` is for strategic / multi-party / load-bearing work. Routine name-by-name follow-ups belong in the outreach blitz (Profile B), not here.
+
+### `events.yml` — time-based events
+
+Single source of truth for calls, demos, meetings, advisor sessions, dentist appointments, anything with a start datetime + counterparty.
+
+- `events.yml` — future scheduled events.
+- `events-archive.yml` — terminal events after the wrap-up gate has captured transcript / spawned tasks / insights.
+
+```yaml
+- id: 1
+  title: Demo v1 walkthrough — Counterparty / Company
+  start: "2026-05-14T14:00:00+02:00"   # ISO 8601 with TZ
+  end: "2026-05-14T14:45:00+02:00"
+  type: demo                            # demo|discovery|investor|admin|personal|unspecified|other
+  status: scheduled                     # scheduled|in_progress|done|cancelled|no_show|rescheduled
+  attendees: [Counterparty, Me]
+  lead_id: https://www.linkedin.com/in/example   # nullable (links to leads.csv if Profile B)
+  location: Google Meet
+  notes: free-form
+  source: manual-chat                   # manual-chat|flush-updates|migrate-from-csv|hand-edit
+  created_at: "2026-05-11T10:38:00.372Z"
+  # populated by the wrap-up gate after the event ends:
+  transcript_path: docs/archive/transcripts/...
+  spawned_tasks: [TASK-86, TASK-87]
+  hypothesis_impacts: [H47, H49]
+  gate_completed_at: "2026-05-14T16:30:00+02:00"
+```
 
----
+Lifecycle: `scheduled` → `done` → `gated` (wrap-up Step 4.5d fills `gate_completed_at`) → archived (`tools/events/archive.js` moves to events-archive.yml). Personal events (gym, dentist) can carry `type: personal` and skip the gate.
 
-## Vault Rules
+### Vault rules
 
 1. **Update, don't duplicate.** Amend with `> **[UPDATE YYYY-MM-DD · Source: ...]**`
 2. **Cross-link everything.** Claims reference their source doc.
@@ -146,95 +173,33 @@ When in doubt about which mode a new doc should use: chronological logs choose `
 4. **Source everything.** Who said it, when, confidence level.
 5. **Minimize file count.** Append, don't create new files.
 
----
-
-## The `/wrap-up` Protocol
-
-When the user says `/wrap-up`, run this end-of-day sequence:
-
-**Step 1 — Scan:** Read the battle plan. Identify all tasks for today. Categorize: done, partially done, not started, new.
+### Outreach `leads.csv` — Profile B only
 
-**Step 2 — Present:** Show the user: "Here's today's status: [list]. Does this look right?"
+If `outreach/leads.csv` exists in the project, the outreach add-on is active. See `outreach/README.md` for setup. `leads.csv` is the single source of truth for outreach metrics — `metrics.yml` is derived from it via `sync-metrics.js` (auto-chained from every `flush-*.js`).
 
-**Step 3 — Prompt:** Ask: "Anything else happen today? Even small things — a reply, an accept, a thought, a link. Everything counts."
+Key columns (full HEADERS list in `tools/outreach/lib/leads.js`): `linkedin_url`, `first_name`, `last_name`, `title`, `company`, `country`, `email`, `source`, `tags`, `status`, `priority`, `contacted_at`, `replied_at`, `followed_up_at`, `channel`, `template`, `inmail_template`, `followup_template`, `notes`.
 
-**Step 4 — Cascade:** With all info gathered, run the full cascade (Steps 0-4 above).
+Status flow: `new → dm_sent → replied → call_booked → call_done → verbal → loi → paying`. Branches: `dead`, `withdrawn`.
 
-**Step 5 — Report:** Print:
-- Metrics changed today (before → after)
-- Docs updated
-- Verification warnings (if any)
-- Tomorrow's top priorities
-
-**Step 6 — Commit:** Ask: "Want me to commit today's updates?" If yes, commit with message: `eod YYYY-MM-DD: [summary]`
+Tags grow forward with `, ` separator. Notes grow forward with `| ` separator — never overwrite.
 
 ---
 
-## Outreach System (Add-on)
-
-**Trigger:** If `outreach/leads.csv` exists in the project, the outreach system is active.
-
-### Overview
-
-The outreach system tracks a LinkedIn (or any channel) outreach pipeline through `outreach/leads.csv`. This CSV is the **single source of truth** for all outreach metrics — `metrics.yml` is derived from it, never edited directly for outreach numbers.
-
-### First-Time Setup
-
-If `outreach/leads.csv` exists but `.outreach-initialized` does NOT exist, read `outreach/README.md` and follow the Interactive Setup instructions to onboard the user.
-
-### Daily Workflow Integration
-
-The outreach system plugs into the cascade protocol:
-
-1. User runs `node tools/outreach/daily-targets.js` → generates blitz checklist
-2. User sends messages, ticks checkboxes
-3. User runs `node tools/outreach/flush-targets.js` → updates leads.csv
-4. `flush-targets.js` calls `sync-metrics.js` → derives metrics.yml from CSV
-5. `sync-metrics.js` calls `update-dashboard.js` → regenerates mermaid dashboard
-6. The cascade protocol takes over: metrics.yml → battle-plan.md → domain docs
-
-### Scripts Reference
-
-| Script | Purpose |
-|--------|---------|
-| `tools/outreach/daily-targets.js [N]` | Generate daily blitz checklist |
-| `tools/outreach/flush-targets.js` | Process checked items from blitz |
-| `tools/outreach/flush-updates.js` | Parse free-form natural language updates |
-| `tools/outreach/flush-accepts.js` | Batch-process connection accepts |
-| `tools/outreach/flush-inbox.js` | Add leads from manual URL list |
-| `tools/outreach/sync-metrics.js` | Derive metrics.yml from leads.csv |
-| `tools/outreach/update-dashboard.js` | Regenerate mermaid conversion dashboard |
-| `tools/outreach/stats.js` | Print pipeline summary |
-| `tools/outreach/lookup.js "Name"` | Fuzzy-search leads |
-
-### Metrics Derivation
-
-These metrics in `metrics.yml` are **derived** from leads.csv (never hand-edit):
-
-- `outreach_sent` = leads with status past `new` or `contacted_at` set
-- `responses` = `replied_at` set or status past `replied`
-- `invitations_accepted` = leads tagged `accepted`
-- `discovery_calls` = `call_at` in the past or status `call_done`
-- `calls_booked` = status `call_booked` (snapshot)
-- `verbal_commitments` = status `verbal`, `loi`, or `paying`
-
-### Template System
-
-Message templates live in `tools/outreach/templates.json`. The daily blitz assigns templates based on the `country_template_map` field (or round-robin if no mapping). Template performance (sent/accepted/replied/calls) is tracked automatically and displayed in the blitz checklist.
-
-### Mermaid Dashboard
+## Pointers
 
-`docs/analysis/icp-conversion.md` is auto-generated — never hand-edit. It contains:
-- Overall funnel chart (contacted → accepted → replied → call → verbal)
-- Conversion breakdown by role, company size, country, company type
-- Template A/B comparison
-- Kill/Keep/Scale verdicts per segment
+**Daily scripts:**
+- `tools/tasks/` — task lifecycle: `add.js`, `render-today.js`, `flush-today.js`, `triage.js`, `archive.js`, `migrate-lanes.js`
+- `tools/events/` — events lifecycle: `add.js`, `upcoming.js`, `due-for-gate.js`, `archive.js`, `migrate-from-csv.js`
+- `tools/touch-date.sh` — stamp Last Updated in frontmatter
+- `tools/verify-cascade.sh` — verify TL;DR / metrics / dates / today.md staleness
+- `tools/check-metrics.sh` — verify Tier 1 metric link references
 
-View in any mermaid-capable renderer (GitHub, VS Code preview, etc.).
+**Outreach scripts (Profile B):** `tools/outreach/` — `daily-targets.js`, `flush-targets.js`, `flush-updates.js`, `flush-accepts.js`, `flush-inbox.js`, `sync-metrics.js`, `update-dashboard.js`, `stats.js`, `lookup.js`, `stale-invitations.js`.
 
-### Adapting the System
+**Skills (`.claude/commands/`):**
+- `good-morning` — morning standup (metrics + today.md + events context-debt check)
+- `wrap-up` — end-of-day reconciliation + task hygiene + events gate
+- `weekly-triage` — task-pile sweep
+- `distill` — compress chronological / amended doc history
 
-- **Different metrics:** Edit the derivation rules in `tools/outreach/sync-metrics.js`
-- **Different time horizon:** The system tracks weekly breakdowns — adjust `daily-targets.js` count parameter
-- **Different channels:** The `channel` column supports any value (connection, inmail, email, etc.)
-- **Different statuses:** Add to `VALID_STATUS` in `tools/outreach/lib/leads.js` and update derivation rules
+**Auto-nudges:** `tools/tasks/triage-due.js` runs on every session start. When it prints a nudge, mention `/weekly-triage` to the user — do not auto-invoke.