@thebassclef/lite 1.0.2 → 1.0.3

package/dist/lite/.claude/hooks/session-reflection.d/55-orientation-gate.sh

@@ -0,0 +1,187 @@
+# tier: lite
+# 55-orientation-gate.sh
+#
+# Per bassclef#1183 + bassclef#1266 + bassclef#1275: mechanical enforcement
+# at SessionStart in bassclef AND every adopter repo. Fires a BLOCKED block
+# (per .claude/rules/blocked-items.md) when the agent is on a feature branch
+# AND no orientation marker exists for that branch. /sprint + /longrun prep
+# procedures (WU-3/WU-4) then refuse to propose work until the operator +
+# agent have oriented at the arc level — read the active bet's parent_drivers,
+# walked up parent_bet → parent_roadmap, scanned open bassclef-evolution
+# issues across the current repo + any sibling repos named in substrate.config.md.
+#
+# This closes the 2026-06-20 failure pattern: agent narrows scope to the
+# nearest leaf ticket without reading the parent thread carrying 30+ in-flight
+# items. Adopters inherit the same discipline (bassclef#1275 — sister
+# pattern "rule propagates, mechanism doesn't" surfaced in the very session
+# that shipped this hook for bassclef-only).
+#
+# Behavior:
+#   - Fires in bassclef AND adopter repos (no consumer-repo guard since bassclef#1275)
+#   - Fires on main branch too per architecture/audits/2026-06-30-session-orientation-blind-spot.md
+#     cure 2 (sister cures: 05-active-bet.sh + /longrun SKILL Step 0.4)
+#   - Silent when state/markers/orientation-gate/<branch-slug>.marker exists
+#     (on main, the slug is literally "main")
+#   - Silent when SKIP_ORIENTATION_GATE=1 (logged via trace-helper)
+#   - Silent when SKIP_ORIENTATION_GATE_ON_MAIN=1 AND branch is main/master
+#     (adopter compat shim per ADR-031 — adopters can opt out of main-firing
+#     per session if needed; bassclef-upstream itself does not set this)
+#   - Otherwise fires BLOCKED block naming active bet + resolution path
+#
+# Config (read from substrate.config.md when present):
+#   - bassclef_evolution_label  — issue label to scan (default: bassclef-evolution)
+#   - bassclef_evolution_child_repos — comma-separated owner/repo list to also scan
+#
+# Resolution:
+#   1. Read active bet's parent_drivers + acceptance + out_of_scope
+#   2. Walk parent_bet → parent_roadmap → parent_drivers chain
+#   3. Scan open bassclef-evolution issues across current repo + child repos
+#   4. Touch marker: mkdir -p state/markers/orientation-gate/ && \
+#                    touch state/markers/orientation-gate/<branch-slug>.marker
+#   OR explicitly defer: "skip orientation-gate this session"
+#
+# Override (logged):
+#   SKIP_ORIENTATION_GATE=1 <command>
+
+# Override path — silent, log via trace-helper if present
+if [ "${SKIP_ORIENTATION_GATE:-0}" = "1" ]; then
+  if [ -x ".claude/hooks/trace-helper.sh" ]; then
+    bash .claude/hooks/trace-helper.sh "orientation-gate" "skipped via SKIP_ORIENTATION_GATE=1" 2>/dev/null || true
+  fi
+  return 0 2>/dev/null || exit 0
+fi
+
+# Branch detection. Silent only when git is missing.
+BRANCH=$(git symbolic-ref --short HEAD 2>/dev/null || echo "")
+if [ -z "$BRANCH" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+
+# Adopter opt-out for main-firing (per ADR-031 we-don't-break-adopters
+# compat shim; bassclef-upstream itself does not set this).
+if [ "${SKIP_ORIENTATION_GATE_ON_MAIN:-0}" = "1" ] && { [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; }; then
+  if [ -x ".claude/hooks/trace-helper.sh" ]; then
+    bash .claude/hooks/trace-helper.sh "orientation-gate" "skipped on main via SKIP_ORIENTATION_GATE_ON_MAIN=1" 2>/dev/null || true
+  fi
+  return 0 2>/dev/null || exit 0
+fi
+
+# Branch slug: slash → dash for safe filename
+BRANCH_SLUG=$(echo "$BRANCH" | tr '/' '-')
+
+# Marker check: silent if orientation marker exists for this branch
+MARKER_PATH="state/markers/orientation-gate/${BRANCH_SLUG}.marker"
+if [ -f "$MARKER_PATH" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+
+# Read active iteration_bet from whereami (best-effort)
+ACTIVE_BET="(none in whereami)"
+if [ -f "docs/whereami.md" ]; then
+  BET_LINE=$(grep -E "^iteration_bet:" docs/whereami.md 2>/dev/null | head -1 | sed 's/^iteration_bet:[[:space:]]*//')
+  if [ -n "$BET_LINE" ]; then
+    # Trim parenthetical status notes (some whereami entries carry CLOSED/CLOSED+MERGED suffix)
+    ACTIVE_BET=$(echo "$BET_LINE" | sed 's/[[:space:]]*(.*//')
+  fi
+fi
+
+# Walk parent_bet chain recursively (bassclef#1347).
+# Reads each bet's frontmatter at docs/iteration-bets/<slug>.md, extracts
+# parent_bet field, recurses until null or max depth (cycle protection).
+# Builds ANCESTOR_CHAIN newline-separated for display in BLOCKED message.
+ANCESTOR_CHAIN=""
+walk_chain() {
+  local current="$1"
+  local depth=0
+  local max_depth=20
+  local visited=" "
+
+  while [ -n "$current" ] && [ "$depth" -lt "$max_depth" ]; do
+    # Cycle break — if we've seen this bet already, stop
+    case "$visited" in *" $current "*) break ;; esac
+    visited="$visited$current "
+
+    if [ "$depth" -gt 0 ]; then
+      ANCESTOR_CHAIN="${ANCESTOR_CHAIN}      ↳ ${current}
+"
+    fi
+
+    local bet_file="docs/iteration-bets/${current}.md"
+    [ -f "$bet_file" ] || break
+
+    local parent
+    parent=$(grep -E "^parent_bet:" "$bet_file" 2>/dev/null | head -1 | sed 's/^parent_bet:[[:space:]]*//')
+    current="$parent"
+    depth=$((depth + 1))
+  done
+}
+if [ -n "$ACTIVE_BET" ] && [ "$ACTIVE_BET" != "(none in whereami)" ]; then
+  walk_chain "$ACTIVE_BET"
+fi
+
+# Read scan config from substrate.config.md (best-effort defaults)
+EVOLUTION_LABEL="bassclef-evolution"
+CHILD_REPOS=""
+if [ -f "substrate.config.md" ]; then
+  CFG_LABEL=$(grep -E "^bassclef_evolution_label:" substrate.config.md 2>/dev/null | head -1 | sed 's/^bassclef_evolution_label:[[:space:]]*//')
+  if [ -n "$CFG_LABEL" ]; then
+    EVOLUTION_LABEL="$CFG_LABEL"
+  fi
+  CFG_CHILDREN=$(grep -E "^bassclef_evolution_child_repos:" substrate.config.md 2>/dev/null | head -1 | sed 's/^bassclef_evolution_child_repos:[[:space:]]*//')
+  if [ -n "$CFG_CHILDREN" ]; then
+    CHILD_REPOS="$CFG_CHILDREN"
+  fi
+fi
+
+# Emit BLOCKED block
+echo ""
+echo "============================================"
+echo "🛑 BLOCKED: orientation-gate"
+echo "============================================"
+echo ""
+echo "Before /sprint or /longrun prep proposes work, read the bigger picture first."
+echo ""
+echo "Active iteration_bet: ${ACTIVE_BET}"
+echo ""
+echo "Read these BEFORE picking what to do next:"
+echo "  - The active bet's parent_drivers (why this exists), acceptance (what counts as done), and out_of_scope (what NOT to do)"
+echo "  - The FULL ancestor chain (per bassclef#1347 — recursive walk, not just one level):"
+echo "      ${ACTIVE_BET}"
+if [ -n "$ANCESTOR_CHAIN" ]; then
+  printf "%s" "$ANCESTOR_CHAIN"
+else
+  echo "      (no ancestors — single bet, or bet file missing)"
+fi
+echo "    Read each ancestor bet's parent_drivers + acceptance + out_of_scope. Union them, dedupe, surface in /longrun prep."
+echo "  - The parent_roadmap (if any bet in the chain has one) and its current pending work"
+echo "  - Open bassclef-evolution issues — run these:"
+echo "      gh issue list --label \"${EVOLUTION_LABEL}\" --state open  # current repo"
+if [ -n "$CHILD_REPOS" ]; then
+  # Split on comma; trim whitespace per item
+  OLD_IFS="$IFS"
+  IFS=','
+  for repo in $CHILD_REPOS; do
+    # Trim leading/trailing whitespace
+    repo_trimmed=$(echo "$repo" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+    if [ -n "$repo_trimmed" ]; then
+      echo "      gh issue list -R ${repo_trimmed} --label \"${EVOLUTION_LABEL}\" --state open"
+    fi
+  done
+  IFS="$OLD_IFS"
+fi
+echo "  - Paused steps and open audit-drop tickets in the active arc"
+echo ""
+echo "When you've read enough to know what work makes sense, touch this marker:"
+echo "  mkdir -p state/markers/orientation-gate/"
+echo "  touch ${MARKER_PATH}"
+echo ""
+echo "OR explicitly defer per .claude/rules/blocked-items.md:"
+echo "  \"skip orientation-gate this session\""
+echo ""
+echo "Silence is not deferral. Default is read first."
+echo ""
+echo "Override (logged): SKIP_ORIENTATION_GATE=1"
+echo "Per bassclef#1183 + bassclef#1266 + bassclef#1275 + bassclef#1347."
+echo ""
+
+return 0 2>/dev/null || exit 0

package/dist/lite/.claude/hooks/session-reflection.d/56-roadmap-reconcile-gate.sh

@@ -0,0 +1,88 @@
+# tier: lite
+# 56-roadmap-reconcile-gate.sh
+#
+# Per bassclef#1183 + bassclef#504 + bassclef#1275: mechanical enforcement
+# at SessionStart in bassclef AND every adopter repo. Fires BLOCKED on
+# feature branches when no roadmap-reconcile marker exists. /sprint + /longrun
+# prep procedures (WU-3/WU-4) refuse to propose work until /roadmap-reconcile
+# --dry-run has run AND either showed no drift OR drift was resolved or
+# explicitly deferred.
+#
+# This closes the methodology-vs-mechanism gap that bassclef#504
+# left open: /roadmap-reconcile auto-fire was declared methodology
+# at /longrun prep Step 0.5, but no hook fired it. Agents skipped the
+# check across multiple sessions; canvas + roadmap drift accumulated
+# silently. Adopters inherit the same discipline (bassclef#1275 — sister
+# pattern "rule propagates, mechanism doesn't" surfaced in the same session
+# that shipped this hook for bassclef-only).
+#
+# Behavior:
+#   - Fires in bassclef AND adopter repos (no consumer-repo guard since bassclef#1275)
+#   - Silent on main branch (gate is per-feature-branch scope decision)
+#   - Silent when state/markers/roadmap-reconcile-gate/<branch-slug>.marker exists
+#   - Silent when SKIP_ROADMAP_RECONCILE_GATE=1 (logged via trace-helper)
+#   - Otherwise emits BLOCKED block naming the dispatch command + resolution path
+#
+# Resolution:
+#   1. Run /roadmap-reconcile --dry-run
+#   2. If diff shows no drift: touch the marker
+#         mkdir -p state/markers/roadmap-reconcile-gate/
+#         touch state/markers/roadmap-reconcile-gate/<branch-slug>.marker
+#   3. If diff shows drift: amend the canvas LR-N tables OR explicitly defer
+#      per .claude/rules/blocked-items.md ("skip roadmap-reconcile this session")
+#
+# Override (logged):
+#   SKIP_ROADMAP_RECONCILE_GATE=1 <command>
+
+# Override path — silent, log via trace-helper if present
+if [ "${SKIP_ROADMAP_RECONCILE_GATE:-0}" = "1" ]; then
+  if [ -x ".claude/hooks/trace-helper.sh" ]; then
+    bash .claude/hooks/trace-helper.sh "roadmap-reconcile-gate" "skipped via SKIP_ROADMAP_RECONCILE_GATE=1" 2>/dev/null || true
+  fi
+  return 0 2>/dev/null || exit 0
+fi
+
+# Branch guard: silent on main
+BRANCH=$(git symbolic-ref --short HEAD 2>/dev/null || echo "")
+if [ -z "$BRANCH" ] || [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+
+# Branch slug: slash → dash
+BRANCH_SLUG=$(echo "$BRANCH" | tr '/' '-')
+
+# Marker check
+MARKER_PATH="state/markers/roadmap-reconcile-gate/${BRANCH_SLUG}.marker"
+if [ -f "$MARKER_PATH" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+
+# Emit BLOCKED block
+echo ""
+echo "============================================"
+echo "🛑 BLOCKED: roadmap-reconcile-gate"
+echo "============================================"
+echo ""
+echo "Before /sprint or /longrun prep proposes work this session, run /roadmap-reconcile --dry-run."
+echo ""
+echo "Why: canvases hold LR-N tables that drift from shipping reality across long sessions."
+echo "Agents proposing work against stale canvas state pick the wrong scope. The dry-run diff"
+echo "names the drift (status mismatch, sequencing mismatch, reference rot) before scope-commit."
+echo ""
+echo "Resolve:"
+echo "  1. Dispatch:  /roadmap-reconcile --dry-run"
+echo "  2. If diff shows NO drift, mark this branch oriented:"
+echo "        mkdir -p state/markers/roadmap-reconcile-gate/"
+echo "        touch ${MARKER_PATH}"
+echo "  3. If diff shows drift, either:"
+echo "        - Amend the canvas LR-N tables to match reality, then mark"
+echo "        - OR explicitly defer per .claude/rules/blocked-items.md:"
+echo "            \"skip roadmap-reconcile this session\""
+echo ""
+echo "Silence is not deferral. Default is run the dry-run."
+echo ""
+echo "Override (logged): SKIP_ROADMAP_RECONCILE_GATE=1"
+echo "Per bassclef#1183 + bassclef#504 + bassclef#1275."
+echo ""
+
+return 0 2>/dev/null || exit 0

package/dist/lite/.claude/hooks/session-reflection.d/60-deferred-actions.sh

@@ -0,0 +1,212 @@
+# tier: lite
+# Deferred-actions scan: enumerate docs/deferred-actions/*.md, detect current
+# modality capabilities, emit BLOCKED: for capability matches (this session
+# can resolve), INFORM: for capability misses (visible, not actionable).
+#
+# Schema: standards/deferred-actions-schema.md
+# Rule:   .claude/rules/deferred-actions.md
+#
+# Migration note (Phase A WS-3 + spine v0 WU-6): this hook reads
+# docs/deferred-actions/ entries via lib/deferred-actions.sh (typed
+# accessor; pre-spine, still load-bearing for capability-routed scanning).
+# Capability detection stays inline because it is session-environment-
+# specific, not artifact-specific. Falls back to inline scanning if lib
+# unavailable (consumer repos pre-distribution).
+#
+# Spine v0 (WU-6) integration: lib/state.sh provides
+# state_deferred_action_pending [requires-capability...] and
+# state_deferred_action_list [pending|completed|all] as the unified
+# accessor surface. This hook continues using lib/deferred-actions.sh
+# for now because (a) capability-routed filtering is more deeply wired
+# into the existing accessor + (b) full migration would risk regressing
+# capability-detection logic that's uniquely tested here. Future
+# unification (consolidate into lib/state.sh) is tracked as a /promote.
+
+DEFERRED_DIR="docs/deferred-actions"
+
+# No dir → nothing to scan.
+if [ ! -d "$DEFERRED_DIR" ]; then
+  return 0 2>/dev/null || true
+fi
+
+# Source typed accessor when available. Probe bundled path first
+# (dist/lite/ ship path per #1631 goal 2026-09-14b), then $BASSCLEF_DIR
+# fallback for synced adopters. Pattern matches session-reflection.sh:13.
+# Graceful fallback to inline scanning if lib not present.
+_sd="$(dirname "${BASH_SOURCE[0]:-$0}")"
+DA_LIB=""
+for _c in "${_sd}/../../../lib/deferred-actions.sh" \
+          "${BASSCLEF_DIR:-}/lib/deferred-actions.sh"; do
+  [ -f "$_c" ] && DA_LIB="$_c" && break
+done
+USE_LIB=0
+if [ -n "$DA_LIB" ]; then
+  # shellcheck source=/dev/null
+  source "$DA_LIB"
+  # Point lib at consumer-local docs/deferred-actions, not bassclef's
+  DEFERRED_ACTIONS_DIR="$DEFERRED_DIR"
+  export DEFERRED_ACTIONS_DIR
+  USE_LIB=1
+fi
+
+# === Modality detection — synthesize current capability set ===
+#
+# Detection order matches .claude/rules/mobile-ephemeral-session.md:
+# primary signal $CLAUDE_EPHEMERAL, then heuristics. Capabilities are
+# additive — start empty, set flags for each positive check.
+
+CAP_GCLOUD=0
+CAP_GDOCS=0
+CAP_GH_AUTH=0
+CAP_GIT_PUSH=0
+CAP_GIT_TAG=0
+CAP_NETWORK=0
+CAP_MEMORY_WRITE=0
+CAP_NPM_INSTALL=0
+CAP_PLAYWRIGHT_MCP=0
+
+# gcloud-auth + google-docs-write: presence of SA key
+if [ -f "$HOME/.config/gcloud/sunjay-google-ops.json" ]; then
+  CAP_GCLOUD=1
+fi
+
+# gh-auth: CLI installed AND authenticated
+if command -v gh &>/dev/null && gh auth status &>/dev/null 2>&1; then
+  CAP_GH_AUTH=1
+fi
+
+# git-push: in a git repo with a remote configured
+if git remote get-url origin &>/dev/null 2>&1; then
+  CAP_GIT_PUSH=1
+fi
+
+# git-tag: superset of git-push (same creds); set if git-push set
+if [ "$CAP_GIT_PUSH" = "1" ]; then
+  CAP_GIT_TAG=1
+fi
+
+# network: reachable via curl with short timeout (heuristic — some
+# ephemeral sandboxes block outbound but claim no $CLAUDE_EPHEMERAL).
+# Skip the check in known-no-network envs to avoid flakiness.
+if [ "${CLAUDE_EPHEMERAL:-}" = "1" ]; then
+  CAP_NETWORK=1
+else
+  CAP_NETWORK=1
+fi
+
+# memory-write: path exists + writable. Only desktop has this.
+MEMORY_DIR="$HOME/.claude/projects"
+if [ -d "$MEMORY_DIR" ] && [ -w "$MEMORY_DIR" ] && [ "${CLAUDE_EPHEMERAL:-}" != "1" ]; then
+  CAP_MEMORY_WRITE=1
+fi
+
+# npm-install: npm on PATH + network
+if command -v npm &>/dev/null && [ "$CAP_NETWORK" = "1" ]; then
+  CAP_NPM_INSTALL=1
+fi
+
+# playwright-mcp: settings.json mentions mcp__playwright, or env hint
+if [ -f "$HOME/.claude/settings.json" ] && grep -q "playwright" "$HOME/.claude/settings.json" 2>/dev/null; then
+  CAP_PLAYWRIGHT_MCP=1
+fi
+
+# google-docs-write composite: gcloud-auth + network
+if [ "$CAP_GCLOUD" = "1" ] && [ "$CAP_NETWORK" = "1" ]; then
+  CAP_GDOCS=1
+fi
+
+# === Helper: does current session satisfy a required-capability list? ===
+capability_match() {
+  local reqs="$1"
+  local cap
+  reqs=$(echo "$reqs" | tr -d '[]"' | tr ',' ' ')
+  for cap in $reqs; do
+    cap=$(echo "$cap" | xargs)
+    [ -z "$cap" ] && continue
+    case "$cap" in
+      gcloud-auth)       [ "$CAP_GCLOUD" = "1" ] || return 1 ;;
+      google-docs-write) [ "$CAP_GDOCS" = "1" ] || return 1 ;;
+      gh-auth)           [ "$CAP_GH_AUTH" = "1" ] || return 1 ;;
+      git-push)          [ "$CAP_GIT_PUSH" = "1" ] || return 1 ;;
+      git-tag)           [ "$CAP_GIT_TAG" = "1" ] || return 1 ;;
+      network)           [ "$CAP_NETWORK" = "1" ] || return 1 ;;
+      memory-write)      [ "$CAP_MEMORY_WRITE" = "1" ] || return 1 ;;
+      npm-install)       [ "$CAP_NPM_INSTALL" = "1" ] || return 1 ;;
+      playwright-mcp)    [ "$CAP_PLAYWRIGHT_MCP" = "1" ] || return 1 ;;
+      *)
+        return 1
+        ;;
+    esac
+  done
+  return 0
+}
+
+# === Scan entries ===
+
+BLOCKED_ENTRIES=""
+INFORM_ENTRIES=""
+MALFORMED_COUNT=0
+
+# Lib-backed enumeration when available; fall back to direct glob.
+if [ "$USE_LIB" = "1" ]; then
+  ENTRIES="$(da_list_open)"
+else
+  ENTRIES=""
+  for entry in "$DEFERRED_DIR"/*.md; do
+    [ -f "$entry" ] || continue
+    [ "$(basename "$entry")" = "README.md" ] && continue
+    [ "$(basename "$entry")" = "template.md" ] && continue
+    ENTRIES="$ENTRIES $entry"
+  done
+fi
+
+for entry in $ENTRIES; do
+  [ -f "$entry" ] || continue
+  # Lib-backed field reads when available; fall back to inline awk.
+  if [ "$USE_LIB" = "1" ]; then
+    ID="$(da_get_field "$entry" id 2>/dev/null)"
+    ACTION="$(da_get_field "$entry" pending_action 2>/dev/null)"
+    REQS="$(da_get_field "$entry" requires_capability 2>/dev/null)"
+    PRIORITY="$(da_get_field "$entry" priority 2>/dev/null)"
+  else
+    ID=$(awk '/^id:/ {print $2; exit}' "$entry" 2>/dev/null)
+    ACTION=$(awk '/^pending_action:/ {sub(/^pending_action: */, ""); print; exit}' "$entry" 2>/dev/null)
+    REQS=$(awk '/^requires_capability:/ {sub(/^requires_capability: */, ""); print; exit}' "$entry" 2>/dev/null)
+    PRIORITY=$(awk '/^priority:/ {print $2; exit}' "$entry" 2>/dev/null)
+  fi
+
+  if [ -z "$ID" ] || [ -z "$ACTION" ] || [ -z "$REQS" ]; then
+    MALFORMED_COUNT=$((MALFORMED_COUNT + 1))
+    continue
+  fi
+
+  SUMMARY_LINE="${PRIORITY:-medium}: ${ID} — ${ACTION} (requires: ${REQS})"
+
+  if capability_match "$REQS"; then
+    BLOCKED_ENTRIES="${BLOCKED_ENTRIES}\n  - ${SUMMARY_LINE}"
+  else
+    INFORM_ENTRIES="${INFORM_ENTRIES}\n  - ${SUMMARY_LINE}"
+  fi
+done
+
+# === Surface findings ===
+
+if [ -n "$BLOCKED_ENTRIES" ]; then
+  MSG="deferred-actions — $(echo -e "$BLOCKED_ENTRIES" | grep -c '^  - ') entry(ies) resolvable in this session:$(echo -e "$BLOCKED_ENTRIES")\nResolve each per .claude/rules/deferred-actions.md, or explicitly defer."
+  blocked_banner "$MSG"
+fi
+
+if [ -n "$INFORM_ENTRIES" ]; then
+  echo "### DEFERRED ACTIONS — INFORM (not resolvable this session)"
+  echo ""
+  echo -e "The following deferred-action entries require capabilities"
+  echo "this session doesn't have. They wait for a capable session."
+  echo -e "$INFORM_ENTRIES"
+  echo ""
+  echo "Do NOT attempt to resolve them here. See .claude/rules/deferred-actions.md."
+  echo ""
+fi
+
+if [ "$MALFORMED_COUNT" -gt 0 ]; then
+  blocked_banner "deferred-actions — ${MALFORMED_COUNT} malformed entry(ies) in $DEFERRED_DIR/. Missing required frontmatter (id / pending_action / requires_capability). See standards/deferred-actions-schema.md."
+fi

package/dist/lite/.claude/hooks/session-reflection.d/70-recent-strategic-artifacts.sh

@@ -0,0 +1,101 @@
+# tier: lite
+# Recent Strategic Artifacts — session-start branch of artifact-ingestion gate.
+#
+# Surfaces canvases / specs / ADRs / iteration-bets / decompositions / roadmaps
+# authored OR modified within the last N days (default 7) so the agent reads
+# them before substantive work this session.
+#
+# Closes the gap that PreToolUse `artifact-ingestion-gate.sh` cannot cover:
+# that hook fires on Write/Edit (production-time); this module fires on
+# SessionStart (orientation-time). Failure mode covered:
+# "agent does substantive work without reading recent strategic artifacts"
+# — explicitly named in canvas v3 §"Failure modes spine does NOT prevent".
+#
+# Inherits from session-reflection.sh: blocked_banner, $BASSCLEF_DIR, trace_log.
+#
+# Env overrides (logged via trace_log when used):
+#   SKIP_RECENT_ARTIFACTS=1   — disable for this session
+#   RECENT_STRATEGIC_DAYS=N   — window size in days (default 7); 0 disables
+#
+# Issue: bassclef#308
+
+# Skip if env override
+if [ "${SKIP_RECENT_ARTIFACTS:-0}" = "1" ]; then
+  type trace_log >/dev/null 2>&1 && trace_log "70-recent-strategic-artifacts" "SKIP via SKIP_RECENT_ARTIFACTS=1"
+  return 0 2>/dev/null || exit 0
+fi
+
+DAYS="${RECENT_STRATEGIC_DAYS:-7}"
+
+# Zero-day window = disabled this session
+if [ "$DAYS" = "0" ]; then
+  type trace_log >/dev/null 2>&1 && trace_log "70-recent-strategic-artifacts" "DISABLED via RECENT_STRATEGIC_DAYS=0"
+  return 0 2>/dev/null || exit 0
+fi
+
+# Bail if not in a git repo (defensive — most consumer repos are git, but mobile
+# / fresh-clone edges may not be when this fires).
+if ! git rev-parse --git-dir >/dev/null 2>&1; then
+  return 0 2>/dev/null || exit 0
+fi
+
+# Strategic artifact path matcher — mirrors artifact-ingestion-gate.sh's set
+# minus prototypes (those have their own approval workflow per
+# prototype-workflow.md), plus roadmaps (added per canvas v3 §Failure modes).
+STRATEGIC_PATHS=(
+  'strategy/canvases/*.md'
+  'docs/specs/*.md'
+  'docs/iteration-bets/*.md'
+  'architecture/decisions/ADR-*.md'
+  'docs/decompositions/*.md'
+  'docs/roadmaps/*.md'
+)
+
+# git log --since=N days ago, A=added M=modified, restricted to strategic paths.
+# Output: <ISO-date>\t<path> per line, deduplicated, most recent commit per path.
+RECENT=$(git log \
+  --since="${DAYS} days ago" \
+  --diff-filter=AM \
+  --name-only \
+  --pretty=format:'%nCOMMIT %ai' \
+  -- "${STRATEGIC_PATHS[@]}" 2>/dev/null \
+  | awk '
+    /^COMMIT / { date=$2; next }
+    NF && !seen[$0]++ { print date "\t" $0 }
+  ' \
+  | sort -u
+)
+
+if [ -z "$RECENT" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+
+# Build the block message.
+COUNT=$(echo "$RECENT" | wc -l | tr -d ' ')
+MSG="RECENT STRATEGIC ARTIFACTS ($COUNT in last ${DAYS} days) — Read before substantive work this session"
+MSG="${MSG}"$'\n'
+while IFS=$'\t' read -r DATE PATHNAME; do
+  [ -z "$PATHNAME" ] && continue
+  MSG="${MSG}  - ${PATHNAME} (${DATE})"$'\n'
+done <<< "$RECENT"
+MSG="${MSG}"
+MSG="${MSG}Per .claude/rules/artifact-ingestion.md §Session-start branch:"$'\n'
+MSG="${MSG}  Strategic artifacts authored or modified within the last ${DAYS} days"$'\n'
+MSG="${MSG}  MUST be Read before substantive work. Resolve via Read; defer via"$'\n'
+MSG="${MSG}  explicit operator statement (\"skip recent-artifacts this session\")."$'\n'
+MSG="${MSG}  Override: SKIP_RECENT_ARTIFACTS=1 <command> (logged)."
+
+# Emit via inherited blocked_banner (defined in session-reflection.sh)
+if type blocked_banner >/dev/null 2>&1; then
+  blocked_banner "$MSG"
+else
+  # Defensive fallback if module is invoked outside the coordinator
+  echo ""
+  echo "🛑🛑🛑 BLOCKED 🛑🛑🛑"
+  echo "$MSG"
+  echo ""
+fi
+
+type trace_log >/dev/null 2>&1 && trace_log "70-recent-strategic-artifacts" "BLOCK count=$COUNT days=$DAYS"
+
+return 0 2>/dev/null || exit 0