create-battle-plan 1.3.0 → 1.4.0

package/package.json

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

@@ -64,6 +64,42 @@ Run `node tools/tasks/render-today.js --quiet` so today's surface reflects any c
 
 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:

package/template/CLAUDE.md

@@ -1,214 +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
-
-**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
+Two views of the same project, and Claude operates across both.
 
-Every task has a `lane` (groups by *primary action*, not topic). The default vocabulary:
+**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.
 
-| 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.
+**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.
 
-### 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.
+**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.
 
 ---
 
-## 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.
+## The Cascade — the core protocol
 
-Two automation layers support this:
+**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)
 
-- **`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 triggered, update top-down in this exact order. Each step depends on the one above it. Never skip.
 
-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
+```
+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
+```
 
-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:
+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).
 
-- `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.
+**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
 
-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.
+Never put state in markdown tables that lives somewhere structured. Never create a parallel store.
 
 ---
 
-## 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`.
-
----
+## Behavioral rules — when X happens, do Y
 
-## The Cascade Protocol
+**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`.
 
-**Trigger:** Any incoming information that relates to the project — calls, messages, research, signals, status changes, decisions.
+**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.
 
-When triggered, update in this exact order:
+**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.
 
-### Step 0: Update `metrics.yml`
-If any key metric changed, update `metrics.yml` first. This is the numeric source of truth.
+**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`
 
-### 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
+Numbers native to a doc (where they originate) have no annotation. Verified by `tools/check-metrics.sh`.
 
-### 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:
+**When stating a claim:** mark its confidence — `Unvalidated` / `Soft signal` / `Practitioner-validated` / `Data-validated`. Include the source.
 
-| 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 |
+**When `verify-cascade.sh` reports an issue:** fix it before ending the turn. Don't ship a known-stale state.
 
-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.
+### Outreach add-on (Profile B only — when `outreach/leads.csv` exists)
 
-### Step 3: Update Dates
-Run `tools/touch-date.sh` on every file you modified in this session:
+**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.
 
-```bash
-tools/touch-date.sh docs/battle-plan.md docs/validation/hypotheses.md [etc.]
-```
+**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.
 
-### Step 4: Verify
-Run `tools/verify-cascade.sh` and fix any issues it reports:
+**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.
 
-```bash
-tools/verify-cascade.sh
-```
+**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.
 
 ---
 
-## Source Reference Rules
-
-### Registry Metrics (Tier 1 — deterministic)
-Numbers defined in `metrics.yml`. Reference as: `[**N**](metrics.yml#field_name)`
-
-This renders as a bold clickable number. Example: `[**42**](metrics.yml#outreach_sent)`
-
-These are verified by exact numeric comparison via `tools/check-metrics.sh`.
+## Schemas & format
 
-### Inline Metrics (Tier 2 — LLM-verified)
-Less common numbers from another doc. Reference as: `[**N**](source-doc.md#section-slug)`
-
-Example: `60% of time on evidence [**60**](external-insights.md#session-2-key-insights)`
-
-**Rule:** Every number referenced from another document MUST include a source annotation. Only numbers native to a doc (where they originate) have no annotation.
-
----
-
-## Document 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.
+- `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.
 
-- **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 modes (drives `/distill`)
 
-### `Compression: amended`
-The doc is a living reference. Claims are amended in place over time.
+| 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. |
 
-- **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.
+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.
 
-### `Compression: none`
-The doc is a static thesis or reference. It gets rewritten, not amended. Git history is the timeline.
+### `tasks.yml` — task lanes
 
-- **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.
+Every task has a `lane` (groups by *primary action*, not topic). Default vocabulary (customize in `tools/tasks/lib/tasks.js`):
 
-### 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.
+| 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) |
 
-When in doubt about which mode a new doc should use: chronological logs choose `chronological`, claim trackers choose `amended`, everything else is `none`.
+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.
@@ -216,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.