create-battle-plan 1.4.0 → 1.4.2

package/bin/cli.js

@@ -84,7 +84,11 @@ function getDirs(dir) {
   }
 }
 
-function pickFolder(projectSlug) {
+function isDirEmpty(dir) {
+  try { return fs.readdirSync(dir).length === 0; } catch { return false; }
+}
+
+function pickFolder(shortName) {
   return new Promise((resolve) => {
     // Pause readline so we can use raw mode
     closeReadline();
@@ -97,8 +101,14 @@ function pickFolder(projectSlug) {
     function getOptions() {
       const dirs = getDirs(cwd);
       const options = [];
+      if (isDirEmpty(cwd)) {
+        options.push({
+          label: `${GREEN}● Install in this folder ${BOLD}(${path.basename(cwd)}/)${RESET}${GREEN} — no subfolder${RESET}`,
+          action: 'here_no_sub',
+        });
+      }
       options.push({ label: `${GREEN}+ Create new folder here${RESET}`, action: 'create' });
-      options.push({ label: `${CYAN}» Install here as ${BOLD}${projectSlug}/${RESET}`, action: 'here' });
+      options.push({ label: `${CYAN}» Install here as ${BOLD}${shortName}/${RESET}`, action: 'here' });
       if (path.dirname(cwd) !== cwd) {
         options.push({ label: `${DIM}../${RESET}  ${DIM}(up)${RESET}`, action: 'up' });
       }
@@ -116,14 +126,14 @@ function pickFolder(projectSlug) {
       let output = '';
 
       if (mode === 'input') {
-        output += `${CLEAR_LINE}\r${DIM}[6/6]${RESET} ${BOLD}Folder name:${RESET} ${inputBuffer}\x1b[K`;
+        output += `${CLEAR_LINE}\r${DIM}[7/7]${RESET} ${BOLD}Folder name:${RESET} ${inputBuffer}\x1b[K`;
         process.stdout.write(output);
         return;
       }
 
       output += `\x1b[H\x1b[2J`; // clear screen
       output += `\n`;
-      output += `${DIM}[6/6]${RESET} ${BOLD}Where do you want to install it?${RESET}\n`;
+      output += `${DIM}[7/7]${RESET} ${BOLD}Where do you want to install it?${RESET}\n`;
       output += `${DIM}      ${display}${RESET}\n`;
       output += `\n`;
       output += `${DIM}      ↑↓ navigate · enter select · q cancel${RESET}\n`;
@@ -156,12 +166,14 @@ function pickFolder(projectSlug) {
         const opt = options[selected];
         if (opt.action === 'create') {
           mode = 'input';
-          inputBuffer = projectSlug;
+          inputBuffer = shortName;
           process.stdout.write(`\x1b[H\x1b[2J`);
           process.stdout.write(`\n`);
-          process.stdout.write(`${DIM}[6/6]${RESET} ${BOLD}Folder name:${RESET} ${inputBuffer}`);
+          process.stdout.write(`${DIM}[7/7]${RESET} ${BOLD}Folder name:${RESET} ${inputBuffer}`);
         } else if (opt.action === 'here') {
-          finish(path.join(cwd, projectSlug));
+          finish(path.join(cwd, shortName));
+        } else if (opt.action === 'here_no_sub') {
+          finish(cwd);
         } else if (opt.action === 'up') {
           cwd = path.dirname(cwd);
           selected = 0;
@@ -189,7 +201,7 @@ function pickFolder(projectSlug) {
         // Backspace
         inputBuffer = inputBuffer.slice(0, -1);
         process.stdout.write(`\r${CLEAR_LINE}`);
-        process.stdout.write(`${DIM}[6/6]${RESET} ${BOLD}Folder name:${RESET} ${inputBuffer}`);
+        process.stdout.write(`${DIM}[7/7]${RESET} ${BOLD}Folder name:${RESET} ${inputBuffer}`);
       } else if (key === '\x1b' || key === '\x03') {
         // Escape or ctrl-c → back to browse
         mode = 'browse';
@@ -210,7 +222,7 @@ function pickFolder(projectSlug) {
       cleanup();
       process.stdout.write(`\x1b[H\x1b[2J`);
       console.log('');
-      console.log(`${DIM}[6/6]${RESET} ${BOLD}Location:${RESET} ${shortPath(dir)}`);
+      console.log(`${DIM}[7/7]${RESET} ${BOLD}Location:${RESET} ${shortPath(dir)}`);
       console.log('');
       resolve(dir);
     }
@@ -297,37 +309,55 @@ async function main() {
 
   initReadline();
 
-  // Question 1: Project name
-  const projectName = await ask(`${DIM}[1/6]${RESET} ${BOLD}What's your project in one sentence?${RESET}\n> `);
+  // Question 1: Project description (one sentence — used for context, not the folder name)
+  const projectName = await ask(`${DIM}[1/7]${RESET} ${BOLD}What's your project in one sentence?${RESET}\n> `);
   if (!projectName) { console.log('Project name is required.'); process.exit(1); }
   console.log('');
 
-  // Question 2: Time horizon
+  // Question 2: Short name (the actual folder slug). Default = cwd basename when sensible.
+  const cwdBasename = path.basename(process.cwd());
+  const cwdSlug = slugify(cwdBasename);
+  const cwdIsEmpty = (() => {
+    try { return fs.readdirSync(process.cwd()).length === 0; } catch { return false; }
+  })();
+  const sentenceSlug = slugify(projectName);
+  const truncatedSentenceSlug = sentenceSlug.split('-').slice(0, 3).join('-');
+  const genericNames = new Set(['projects', 'code', 'src', 'work', 'dev', 'repos', 'workspace', 'documents', 'desktop']);
+  const defaultShortName = (cwdIsEmpty && cwdSlug && !genericNames.has(cwdSlug))
+    ? cwdSlug
+    : (truncatedSentenceSlug || 'my-battle-plan');
+  const shortNameRaw = await ask(
+    `${DIM}[2/7]${RESET} ${BOLD}Short name for the folder?${RESET} ${DIM}(default: ${defaultShortName})${RESET}\n> `
+  );
+  const shortName = slugify(shortNameRaw) || defaultShortName;
+  console.log('');
+
+  // Question 3: Time horizon
   const horizon = await ask(
-    `${DIM}[2/6]${RESET} ${BOLD}What's your time horizon?${RESET} ${DIM}(e.g., "3 weeks to demo day", "6 months to launch", "ongoing")${RESET}\n> `
+    `${DIM}[3/7]${RESET} ${BOLD}What's your time horizon?${RESET} ${DIM}(e.g., "3 weeks to demo day", "6 months to launch", "ongoing")${RESET}\n> `
   );
   console.log('');
 
-  // Question 3: Metrics
+  // Question 4: Metrics
   const metricsRaw = await ask(
-    `${DIM}[3/6]${RESET} ${BOLD}What are the 3-5 key metrics you want to track?${RESET} ${DIM}(comma-separated, e.g., "outreach sent, calls booked, LOIs signed")${RESET}\n> `
+    `${DIM}[4/7]${RESET} ${BOLD}What are the 3-5 key metrics you want to track?${RESET} ${DIM}(comma-separated, e.g., "outreach sent, calls booked, LOIs signed")${RESET}\n> `
   );
   if (!metricsRaw) { console.log('At least one metric is required.'); process.exit(1); }
   const metrics = metricsRaw.split(',').map((m) => m.trim()).filter(Boolean);
   console.log('');
 
-  // Question 4: Domains
+  // Question 5: Domains
   const suggested = suggestDomains(projectName);
   const domainsRaw = await ask(
-    `${DIM}[4/6]${RESET} ${BOLD}What domains does your work cover?${RESET} ${DIM}(comma-separated)\nSuggested based on your project: ${suggested}${RESET}\n> `
+    `${DIM}[5/7]${RESET} ${BOLD}What domains does your work cover?${RESET} ${DIM}(comma-separated)\nSuggested based on your project: ${suggested}${RESET}\n> `
   );
   if (!domainsRaw) { console.log('At least one domain is required.'); process.exit(1); }
   const domains = domainsRaw.split(',').map((d) => d.trim().toLowerCase()).filter(Boolean);
   console.log('');
 
-  // Question 5: People
+  // Question 6: People
   const peopleRaw = await ask(
-    `${DIM}[5/6]${RESET} ${BOLD}Who are the key people you'll be working with?${RESET} ${DIM}(format: "Name:Role, Name:Role" — or press enter to skip)${RESET}\n> `
+    `${DIM}[6/7]${RESET} ${BOLD}Who are the key people you'll be working with?${RESET} ${DIM}(format: "Name:Role, Name:Role" — or press enter to skip)${RESET}\n> `
   );
   const people = peopleRaw
     ? peopleRaw.split(',').map((p) => {
@@ -337,9 +367,8 @@ async function main() {
     : [];
   console.log('');
 
-  // Question 6: Interactive folder picker
-  const projectSlug = slugify(projectName) || 'my-battle-plan';
-  const targetDir = await pickFolder(projectSlug);
+  // Question 7: Interactive folder picker
+  const targetDir = await pickFolder(shortName);
 
   // Re-init readline for any future questions
   initReadline();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-battle-plan",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "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/tools/verify-cascade.sh

@@ -1,8 +1,10 @@
 #!/usr/bin/env bash
 # verify-cascade.sh — Full verification of the Battle Plan cascade system.
-# Checks: dates, metrics, staleness, battle plan freshness.
+# Checks: dates, metrics, staleness, battle plan freshness, qualitative
+# claim drift, on-disk file presence, amended-doc UPDATE discipline,
+# chronological-doc dated-heading discipline.
 # Usage: tools/verify-cascade.sh
-# Exit 0 if clean, exit 1 if issues found.
+# Exit 0 if clean (or warnings only), exit 1 if errors found.
 
 set -euo pipefail
 
@@ -14,6 +16,26 @@ TODAY=$(date +%Y-%m-%d)
 WARNINGS=0
 ERRORS=0
 
+# Shared find-exclusion list. These paths/filenames are excluded from
+# every check because they are autogenerated, archive-only, or carry
+# their own freshness semantics that don't follow the cascade rules:
+#   - examples/        → template scaffolding shown to users
+#   - superpowers/     → plugin-skill content; not cascade docs
+#   - archive/         → frozen-in-time historical snapshots
+#   - social/          → drafts of outbound posts; cascade-irrelevant
+#   - today-archive/   → daily flushed task surfaces
+#   - today.md         → autogenerated by tools/tasks/render-today.js
+#   - CLAUDE.md        → system instructions, not a cascade doc
+FIND_EXCLUDES=(
+  -not -path "*/examples/*"
+  -not -path "*/superpowers/*"
+  -not -path "*/archive/*"
+  -not -path "*/social/*"
+  -not -path "*/today-archive/*"
+  -not -name "today.md"
+  -not -name "CLAUDE.md"
+)
+
 echo "=== Battle Plan Verification ==="
 echo "Date: $TODAY"
 echo ""
@@ -38,7 +60,7 @@ while IFS= read -r doc; do
     echo "WARNING: No Last Updated line in $doc"
     WARNINGS=$((WARNINGS + 1))
   fi
-done < <(find "$DOCS_DIR" -name "*.md" -not -path "*/examples/*" 2>/dev/null)
+done < <(find "$DOCS_DIR" -name "*.md" "${FIND_EXCLUDES[@]}" 2>/dev/null)
 
 # --- Check 2: Metrics consistency ---
 echo ""
@@ -73,7 +95,7 @@ if [ -f "$BATTLE_PLAN" ]; then
       echo "WARNING: $doc ($doc_date) is newer than battle plan ($bp_date)"
       WARNINGS=$((WARNINGS + 1))
     fi
-  done < <(find "$DOCS_DIR" -name "*.md" -not -path "*/examples/*" 2>/dev/null)
+  done < <(find "$DOCS_DIR" -name "*.md" "${FIND_EXCLUDES[@]}" 2>/dev/null)
 else
   echo "WARNING: Battle plan not found at $BATTLE_PLAN"
   WARNINGS=$((WARNINGS + 1))
@@ -96,7 +118,7 @@ while IFS= read -r doc; do
     echo "WARNING: No TL;DR in $doc"
     WARNINGS=$((WARNINGS + 1))
   fi
-done < <(find "$DOCS_DIR" -name "*.md" -not -path "*/examples/*" 2>/dev/null)
+done < <(find "$DOCS_DIR" -name "*.md" "${FIND_EXCLUDES[@]}" 2>/dev/null)
 
 # --- Check 5: Stale inline references ---
 echo ""
@@ -119,7 +141,7 @@ while IFS= read -r doc; do
     # Skip metrics.yml references (handled by check-metrics)
     [[ "$ref" == *"metrics.yml"* ]] && continue
 
-    ref_path=$(find "$DOCS_DIR" -name "$ref_file" -not -path "*/examples/*" 2>/dev/null | head -1)
+    ref_path=$(find "$DOCS_DIR" -name "$ref_file" -not -path "*/examples/*" -not -path "*/superpowers/*" 2>/dev/null | head -1)
     if [ -z "$ref_path" ]; then
       echo "WARNING: Referenced file $ref_file not found (from $doc)"
       WARNINGS=$((WARNINGS + 1))
@@ -134,7 +156,7 @@ while IFS= read -r doc; do
       WARNINGS=$((WARNINGS + 1))
     fi
   done < <(grep -oE '\(→ [^)]+\)' "$doc" 2>/dev/null || true)
-done < <(find "$DOCS_DIR" -name "*.md" -not -path "*/examples/*" 2>/dev/null)
+done < <(find "$DOCS_DIR" -name "*.md" "${FIND_EXCLUDES[@]}" 2>/dev/null)
 
 # --- Check 6: today.md freshness (task subsystem) ---
 echo ""
@@ -142,16 +164,276 @@ 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))
+  else
+    echo "today.md is fresh relative to tasks.yml"
   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
 
+# --- Check 7: Qualitative wrappers near metric links ---
+#
+# Surfaces phrases that DEPEND on the linked metric's current value
+# ("exceeded N", "target hit ✓", "Nx better than baseline", etc.).
+# When the metric value changes — which can happen automatically via
+# sync-metrics — these wrapper phrases can become factually wrong
+# without the metric substitution itself looking suspicious.
+#
+# Example failure mode: a doc once said "we've now exceeded our 40-DM
+# target [**42**](metrics.yml#outreach_sent)". A week later the metric
+# updates to 38 (e.g. dead leads recounted, derivation logic changed).
+# The `[**38**]` substitution is silent; the word "exceeded" is now
+# factually wrong but the link still resolves and looks fine.
+#
+# This is heuristic and informational: hits are WARNINGS, never ERRORS.
+# Tune by editing the QUALITATIVE_REGEX below or excluding paths.
+echo ""
+echo "--- Check 7: Qualitative Wrappers Near Metric Links ---"
+
+# Phrases that flag a metric-linked number as a fragile narrative claim.
+# Each is matched on a line that also contains a `metrics.yml#` reference.
+QUALITATIVE_REGEX='(exceeded|target (was|hit)|hit ✓|/[0-9]+ ✓|[0-9]+x better|[0-9]+x the rate|[0-9]+x higher|doubled|tripled|crossed [0-9]+|achieved|surpassed|outperformed)'
+
+QW_FILES_FOUND=0
+while IFS= read -r doc; do
+  [ -z "$doc" ] && continue
+  [[ "$doc" == "$DOCS_DIR/README.md" ]] && continue
+
+  # Pull lines that contain BOTH a metric link AND a qualitative wrapper.
+  # Using `grep -P` would be cleaner but BSD grep on macOS lacks -P, so we
+  # chain two extended-regex matches instead.
+  matches=$(grep -nE 'metrics\.yml#' "$doc" 2>/dev/null \
+    | grep -iE "$QUALITATIVE_REGEX" \
+    || true)
+
+  if [ -n "$matches" ]; then
+    QW_FILES_FOUND=$((QW_FILES_FOUND + 1))
+    rel="${doc#$REPO_ROOT/}"
+    echo "WARNING: qualitative wrapper near metric link in $rel"
+    WARNINGS=$((WARNINGS + 1))
+    while IFS= read -r m; do
+      [ -z "$m" ] && continue
+      # Trim long lines for readability — keep first 200 chars.
+      lineno=$(echo "$m" | cut -d: -f1)
+      preview=$(echo "$m" | cut -d: -f2- | cut -c1-200)
+      echo "  L$lineno: $preview"
+    done <<<"$matches"
+  fi
+done < <(find "$DOCS_DIR" -name "*.md" "${FIND_EXCLUDES[@]}" 2>/dev/null)
+
+if [ $QW_FILES_FOUND -eq 0 ]; then
+  echo "No qualitative wrappers found near metric links."
+else
+  echo ""
+  echo "  ↑ Re-validate each phrase against the current metric value."
+  echo "    A wrapper that was true at write-time can become factually"
+  echo "    wrong after sync-metrics updates the linked number."
+fi
+
+# --- Check 8: Personal-surface files present on disk ---
+#
+# tasks.yml + events.yml + events-archive.yml are typically gitignored
+# (they are your personal daily-task / events surface — not shared with
+# collaborators, and not visible to a teammate's Claude session). They
+# must still exist on disk for render-today.js / due-for-gate.js /
+# /wrap-up to work.
+#
+# Failure mode this catches: a routine gitignore commit that uses
+# `git rm <file>` instead of `git rm --cached <file>` deletes the
+# on-disk copies. Nothing crashes — the scripts silently no-op when
+# the files are missing: today.md renders empty, due-for-gate returns
+# []. Fail loud here so the same mistake surfaces immediately next
+# time instead of after several days of empty surfaces.
+#
+# Fresh installs: a file that's missing AND has never been tracked in
+# git is treated as "not bootstrapped yet" rather than "lost" — silently
+# noted, never errored. Run `tools/init-project.sh` (or just create the
+# empty files) to bootstrap. The error only fires when a file was once
+# tracked but is now gone from disk — that's the real recovery scenario.
+echo ""
+echo "--- Check 8: Personal-Surface Files On Disk ---"
+
+CHECK8_MISSING=0
+CHECK8_NOT_BOOTSTRAPPED=0
+HAS_GIT=0
+if git -C "$REPO_ROOT" rev-parse --git-dir >/dev/null 2>&1; then
+  HAS_GIT=1
+fi
+
+for f in tasks.yml events.yml events-archive.yml; do
+  [ -f "$REPO_ROOT/$f" ] && continue
+
+  # Was this file ever tracked? If so, missing-on-disk is a real recovery
+  # scenario. If never tracked (or no git at all), treat as "not bootstrapped".
+  was_tracked=0
+  if [ $HAS_GIT -eq 1 ]; then
+    if [ -n "$(git -C "$REPO_ROOT" rev-list --all -- "$f" 2>/dev/null | head -1)" ]; then
+      was_tracked=1
+    fi
+  fi
+
+  if [ $was_tracked -eq 1 ]; then
+    echo "ERROR: $f is missing on disk (but was previously tracked in git)."
+    echo "  This file is typically gitignored but must exist locally. Likely cause:"
+    echo "  someone ran 'git rm $f' (not 'git rm --cached $f') in a past"
+    echo "  gitignore commit. Recover with:"
+    echo "    git log --all --diff-filter=D -- $f   # find the deletion commit <C>"
+    echo "    git show <C>^:$f > $f                  # restore the last tracked version"
+    ERRORS=$((ERRORS + 1))
+    CHECK8_MISSING=$((CHECK8_MISSING + 1))
+  else
+    CHECK8_NOT_BOOTSTRAPPED=$((CHECK8_NOT_BOOTSTRAPPED + 1))
+  fi
+done
+
+if [ $CHECK8_MISSING -eq 0 ] && [ $CHECK8_NOT_BOOTSTRAPPED -eq 0 ]; then
+  echo "All personal-surface files present."
+elif [ $CHECK8_MISSING -eq 0 ] && [ $CHECK8_NOT_BOOTSTRAPPED -gt 0 ]; then
+  echo "Note: $CHECK8_NOT_BOOTSTRAPPED personal-surface file(s) not yet bootstrapped (never tracked). Run \`tools/init-project.sh\` or create empty stubs to start using them."
+fi
+
+# --- Check 9: Amended-doc UPDATE block discipline ---
+#
+# Amended-compression docs require every revision to be a
+# `> **[UPDATE YYYY-MM-DD · Source: ...]**` block placed immediately
+# above the claim it modifies. Without UPDATE blocks, /distill cannot
+# tell what's new vs old when collapsing the doc, and the timeline of
+# how a claim evolved is silently lost.
+#
+# Heuristic: if an amended doc was modified vs origin/main (or HEAD if
+# origin/main is unavailable) and the diff added content lines but no
+# new UPDATE block, warn. Allows some false positives (e.g. UPDATE
+# block continuation lines, frontmatter touches) — tunable below.
+#
+# Skipped silently when there's no git history yet (fresh repo).
+echo ""
+echo "--- Check 9: Amended-Doc UPDATE Block Discipline ---"
+
+# Pick the diff base. Prefer origin/main; fall back to HEAD.
+DIFF_BASE=""
+if git -C "$REPO_ROOT" rev-parse --verify --quiet origin/main >/dev/null 2>&1; then
+  DIFF_BASE="origin/main"
+elif git -C "$REPO_ROOT" rev-parse --verify --quiet HEAD >/dev/null 2>&1; then
+  DIFF_BASE="HEAD"
+fi
+
+if [ -z "$DIFF_BASE" ]; then
+  echo "No git base ref to diff against (no origin/main, no HEAD) — skipping Check 9."
+else
+  CHECK9_HITS=0
+  while IFS= read -r doc; do
+    [ -z "$doc" ] && continue
+    [[ "$doc" == "$DOCS_DIR/README.md" ]] && continue
+
+    compression=$(grep '^\*\*Compression:\*\*' "$doc" | head -1 | sed 's/\*\*Compression:\*\* //' || true)
+    [[ "$compression" != "amended" ]] && continue
+
+    rel="${doc#$REPO_ROOT/}"
+
+    # Diff against base. Suppress errors if file is untracked.
+    diff_out=$(git -C "$REPO_ROOT" diff "$DIFF_BASE" -- "$rel" 2>/dev/null || true)
+    [ -z "$diff_out" ] && continue
+
+    # Count added content lines (excluding diff headers, frontmatter, blank lines).
+    # Frontmatter lines start with **Last Updated:**, **Status:**, etc.
+    added_content=$(echo "$diff_out" \
+      | grep -E '^\+[^+]' \
+      | grep -vE '^\+\s*$' \
+      | grep -vE '^\+\*\*(Last Updated|Status|Role|Compression|TL;DR):' \
+      | wc -l | tr -d ' ')
+
+    # Count added UPDATE blocks.
+    added_updates=$(echo "$diff_out" \
+      | grep -cE '^\+> \*\*\[UPDATE [0-9]{4}-[0-9]{2}-[0-9]{2}' \
+      || true)
+
+    # Warn if content added but no UPDATE block added.
+    if [ "$added_content" -gt 0 ] && [ "$added_updates" -eq 0 ]; then
+      echo "WARNING: $rel — $added_content content line(s) added vs $DIFF_BASE but no new UPDATE block."
+      echo "  Amended-compression docs require '> **[UPDATE YYYY-MM-DD · Source: ...]**' for every revision."
+      WARNINGS=$((WARNINGS + 1))
+      CHECK9_HITS=$((CHECK9_HITS + 1))
+    fi
+  done < <(find "$DOCS_DIR" -name "*.md" "${FIND_EXCLUDES[@]}" 2>/dev/null)
+
+  if [ $CHECK9_HITS -eq 0 ]; then
+    echo "All amended-doc edits have proper UPDATE blocks (or no amended docs modified)."
+  fi
+fi
+
+# --- Check 10: Chronological-doc dated-heading discipline ---
+#
+# Chronological-compression docs require every new entry to start with
+# a dated heading: `## YYYY-MM-DD — <title>`, `## Session N (YYYY-MM-DD)
+# — <title>`, `### Day N — <weekday>`, etc. Undated entries get
+# silently absorbed into the wrong era during /distill, scrambling the
+# timeline of a doc that exists specifically to preserve a timeline.
+#
+# Heuristic: for each chronological doc modified vs the diff base, find
+# every heading added in the diff (lines starting with +## or +###) and
+# verify it matches one of the dated patterns. Standard fixed section
+# headings (TL;DR, Status, Pipeline, etc.) are exempted via a second
+# allowlist regex — extend FIXED_HEADING_REGEX below if your project
+# introduces new fixed section names.
+#
+# Skipped silently when there's no git history yet (fresh repo).
+echo ""
+echo "--- Check 10: Chronological-Doc Dated Headings ---"
+
+if [ -z "$DIFF_BASE" ]; then
+  echo "No git base ref to diff against — skipping Check 10."
+else
+  # Allowed heading patterns (extended-regex):
+  # - "## 2026-05-21" or "## 2026-05-21 — ..."
+  # - "## Session 17" or "## Session 17 (2026-05-20) — ..."
+  # - "### Day 53" or "### Day 53 — ..."
+  DATED_HEADING_REGEX='^\+#{2,3} (([0-9]{4}-[0-9]{2}-[0-9]{2})|((Day|Session) [0-9]+))'
+  # Standard fixed headings used in battle-plan / hypotheses / insights
+  # docs. Extend this list if your project introduces new fixed sections.
+  FIXED_HEADING_REGEX='^\+#{2,4} (Daily Log|Sessions|Recent Sessions|TL;DR|Status|Pipeline|Key Metrics|Weekly plan|Contingency Plans|Documents This Plan Depends On|Rules for This Document|Next milestones|Scope locks|Role|Compression|Timeline|Goal|Notes|References|Cross-references|Validation protocol|Kill criteria|Hypothesis statement|Confidence|Impact)'
+
+  CHECK10_HITS=0
+  while IFS= read -r doc; do
+    [ -z "$doc" ] && continue
+    [[ "$doc" == "$DOCS_DIR/README.md" ]] && continue
+
+    compression=$(grep '^\*\*Compression:\*\*' "$doc" | head -1 | sed 's/\*\*Compression:\*\* //' || true)
+    [[ "$compression" != "chronological" ]] && continue
+
+    rel="${doc#$REPO_ROOT/}"
+    diff_out=$(git -C "$REPO_ROOT" diff "$DIFF_BASE" -- "$rel" 2>/dev/null || true)
+    [ -z "$diff_out" ] && continue
+
+    # Find added headings (## or ###) that match neither dated nor fixed patterns.
+    bad_headings=$(echo "$diff_out" \
+      | grep -E '^\+#{2,3} ' \
+      | grep -vE "$DATED_HEADING_REGEX" \
+      | grep -vE "$FIXED_HEADING_REGEX" \
+      || true)
+
+    if [ -n "$bad_headings" ]; then
+      echo "WARNING: $rel — undated heading(s) added vs $DIFF_BASE:"
+      while IFS= read -r h; do
+        [ -z "$h" ] && continue
+        echo "  ${h:1:200}"
+      done <<<"$bad_headings"
+      echo "  Chronological-compression docs require '## YYYY-MM-DD — <title>' or '## Session N (YYYY-MM-DD) — <title>' or '### Day N — <weekday>'."
+      WARNINGS=$((WARNINGS + 1))
+      CHECK10_HITS=$((CHECK10_HITS + 1))
+    fi
+  done < <(find "$DOCS_DIR" -name "*.md" "${FIND_EXCLUDES[@]}" 2>/dev/null)
+
+  if [ $CHECK10_HITS -eq 0 ]; then
+    echo "All chronological-doc new headings are properly dated (or no chronological docs modified)."
+  fi
+fi
+
 # --- Summary ---
 echo ""
 echo "========================="

package/template/CLAUDE.md.backup-2026-05-11

@@ -1,310 +0,0 @@
-# Battle Plan — System Prompt
-
-You are helping manage an interconnected documentation system. Every document stays in sync through a cascade protocol. Follow these rules exactly.
-
----
-
-## Two-View Model — Read This First
-
-**The cascade is your orientation layer. `docs/today.md` is the user's operating surface. The chat is the user's only UI.**
-
-The user should never have to look at the cascade, the battle plan, `tasks.yml`, or any internal markdown to operate the system. The chat with you is the UI; the cascade is your memory; `docs/today.md` is a thin clickable surface in their editor for ticking through the day. Everything else exists for *you*, not them.
-
-- **Your view (the cascade):** `docs/battle-plan.md` at the top, source docs below it, `metrics.yml` as numeric truth, `tasks.yml` as the structured task log. Narrative, deep, linked. You read and write this freely — it is how you reconstruct project state and cascade new information.
-- **User's view:** `docs/today.md`, generated by `tools/tasks/render-today.js` from `tasks.yml`. Rendered in Obsidian Tasks plugin format — query blocks project pill-styled lists over a raw `## Task data` section at the bottom (lane-grouped within each priority bucket). The user checks boxes in Obsidian; `tools/tasks/flush-today.js` reconciles those edits back into `tasks.yml`. When they want deep context, they ask you in chat — you traverse the cascade on their behalf.
-
-**Rules:**
-- Never grow the battle plan's TL;DR into a wall of prose. Keep header blocks terse; append Daily Log entries chronologically.
-- When the user drops new tasks, add them via `node tools/tasks/add.js "..." [--due YYYY-MM-DD] [--tag X] [--priority 1|2|3] [--lane LANE] [--implication PATH]`. Don't bury tasks in battle plan prose.
-- After any task mutation (add, complete, snooze, triage), run `node tools/tasks/render-today.js` so `docs/today.md` stays fresh.
-- `verify-cascade.sh` Check 6 confirms `today.md` is not stale relative to `tasks.yml`.
-
----
-
-## Task Lanes — what goes where
-
-Every task has a `lane` (groups by *primary action*, not topic). The default vocabulary:
-
-| Lane | Primary action |
-|---|---|
-| `build` | Build, design, or document the product itself (MVP, demos, architecture, integrations) |
-| `outreach` | Cold DMs / InMails / posts / templates / cold-email infra-as-pipeline |
-| `discovery` | Chase or nurture a *named human relationship* — warm intros, follow-ups, scheduling specific calls |
-| `infra` | Plumbing — DNS, GCP/AWS, deploy, env, secrets, cold-email domain warm-up |
-| `fundraising` | Apply to or maintain relationships with accelerators / VCs / angels |
-| `meta` | Doc/process work with no other natural lane (default fallback) |
-
-**Adapt this set to your project.** Lanes are configurable in `tools/tasks/lib/tasks.js` (`VALID_LANES`) — when you change them, also update `tools/tasks/migrate-lanes.js` keyword buckets and the `LANE_DISPLAY` / `LANE_ORDER` tables in `tools/tasks/render-today.js`.
-
-**Personalities don't get their own lane.** A specific advisor or co-founder's input flows into all the action lanes. A task like "ask <advisor> about X" is `discovery` (relationship), `build` (product feedback), or `meta` (process), depending on what *closing* the task produces.
-
-### Strategic vs routine — what belongs in `tasks.yml`
-
-`tasks.yml` is for **ad-hoc strategic / build / discovery-protocol / high-stakes individual conversations.** Examples: a milestone call with a specific stakeholder where multiple people join; a piece of pitch copy that needs to be written by a specific date; a load-bearing architecture decision that gates other work.
-
-Routine lead-by-name follow-ups ("X accepted, send DM") belong in the **outreach blitz pipeline**, not in `tasks.yml`. The blitz already surfaces those through `daily-targets.js` + `leads.csv` flags + accepted-not-replied detection on timers. Don't duplicate that work as tasks.
-
-When uncertain, default to the blitz. `tasks.yml` is a journal of strategic intent, not a worklist.
-
----
-
-## Weekly Triage — `/weekly-triage`
-
-Run weekly to keep `tasks.yml` honest. The skill (`.claude/commands/weekly-triage.md`) walks the user through every open task one at a time using `AskUserQuestion`'s arrow-key UI. Each decision (`done` / `snooze N` / `demote` / `merge X` / `delete` / `lane LANE` / `priority N` / `keep`) is applied to `tasks.yml` immediately — no batching.
-
-Two automation layers support this:
-
-- **`tools/tasks/triage.js`** — read-only data layer. Surfaces overdue/stale tasks, recent commits mentioning each task ID (signals "this is probably done"), and *implications drift* (when a task's linked doc hasn't been modified since the task was created — meaning the cascade hasn't actually reached the doc). Output as Markdown by default, JSON via `--json` for programmatic consumers.
-- **`tools/tasks/triage-due.js`** — lightweight SessionStart-hook nudge. Silent unless one of three thresholds trips: time-based (≥7d since last triage), stale-task (≥20 open tasks ≥14d old), or volume (≥60 open). Wired in `.claude/settings.json`. The skill stamps `last_triage_at` in `tasks.yml` on completion to suppress the nudge until the next cycle.
-
-When you see the SessionStart nudge fire, mention it in chat ("📋 Last triage was 9d ago — want to run `/weekly-triage`?") but never auto-invoke. The user decides.
-
-### Implications field
-
-Tasks may carry `implications: [docs/path-a.md, docs/path-b.md]` — a list of docs that should change when the task closes. `triage.js` flags drift when a linked doc's last git commit predates the task: the status flip happened, but the cascaded doc-update didn't. When you create a task whose closure should mutate a specific doc, pass `--implication path/to/doc.md` to `add.js` so triage can hold you accountable later.
-
-### `blocked_by` field
-
-Tasks may also carry `blocked_by: [TASK-IDs]` — an array of TASK-IDs that must close before this task is actionable. Set via `add.js --blocked-by N` (repeatable; comma-separated also accepted; each ID validated against existing rows). When at least one blocker is still open:
-
-- `triage.js` shows a `🚧 Blocked by:` line listing each blocker's id, status, and title (open ones flagged 🚧, closed ones ✅).
-- The stale-flag and snooze-or-demote suggestion are **suppressed** — a task waiting on a deliberate blocker shouldn't be penalized for not progressing.
-- The replacement suggestion becomes "blocked — chase blocker(s) or demote".
-- Stats gain a `Blocked by another open task: N` line.
-- `render-today.js` emits a `🚧 blocked-by:TASK-N,TASK-M` token on the task's line — but only for *still-open* blockers, so the token disappears once the blocker closes.
-
-When the user describes a task that genuinely depends on another, set the blocker explicitly (`--blocked-by N`) instead of letting the dependency live in prose. Closure of the blocker doesn't auto-close the dependent — the user picks the action during the next triage.
-
----
-
-## Task archive — `node tools/tasks/archive.js`
-
-`tasks.yml` is append-only by design (audit trail), but it shouldn't grow forever. The archive script moves any `status: done|cancelled` row with `done_at < today - 14d` into `tasks-archive.yaml` (created on first run, same schema, sorted by `done_at` ascending).
-
-- **Default retention:** 14 days. Pass `--days N` to override, or `--all` to archive every closed row regardless of age.
-- **Idempotent:** dedups by `id` against the existing archive. Safe to run on every `/wrap-up`.
-- **Wired into `/wrap-up` Step 4.5b** — runs daily as part of end-of-day routine.
-- **Backfill safety:** closed rows missing `done_at` get stamped today and kept one cycle (so a date-less row doesn't get archived without chronological position).
-- **Re-importing a task:** intentional friction. Manually move the row from `tasks-archive.yaml` → `tasks.yml` and set `status: open`.
-
----
-
-## The Cascade Protocol
-
-**Trigger:** Any incoming information that relates to the project — calls, messages, research, signals, status changes, decisions.
-
-When triggered, update in this exact order:
-
-### Step 0: Update `metrics.yml`
-If any key metric changed, update `metrics.yml` first. This is the numeric source of truth.
-
-### 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
-
-### 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:
-
-| 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 |
-
-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:
-
-```bash
-tools/touch-date.sh docs/battle-plan.md docs/validation/hypotheses.md [etc.]
-```
-
-### Step 4: Verify
-Run `tools/verify-cascade.sh` and fix any issues it reports:
-
-```bash
-tools/verify-cascade.sh
-```
-
----
-
-## 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`.
-
-### 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:
-
-```markdown
-# Document Title
-
-**Last Updated:** 2026-04-07
-**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.
-
----
-```
-
-- **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`.
-
----
-
-## Vault Rules
-
-1. **Update, don't duplicate.** Amend with `> **[UPDATE YYYY-MM-DD · Source: ...]**`
-2. **Cross-link everything.** Claims reference their source doc.
-3. **Confidence levels:** `Unvalidated` | `Soft signal` | `Practitioner-validated` | `Data-validated`
-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.
-
-**Step 2 — Present:** Show the user: "Here's today's status: [list]. Does this look right?"
-
-**Step 3 — Prompt:** Ask: "Anything else happen today? Even small things — a reply, an accept, a thought, a link. Everything counts."
-
-**Step 4 — Cascade:** With all info gathered, run the full cascade (Steps 0-4 above).
-
-**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]`
-
----
-
-## 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
-
-`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
-
-View in any mermaid-capable renderer (GitHub, VS Code preview, etc.).
-
-### Adapting the System
-
-- **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