create-battle-plan 1.3.0 → 1.4.1

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 "========================="