axel-setup 0.2.0

package/docs/superpowers/plans/2026-06-12-setup-hardening-roadmap.md

@@ -0,0 +1,61 @@
+# AXEL Setup Hardening Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make AXEL publishable and safer for third-party installation by hardening bootstrap behavior, tests, release automation, and public roadmap hygiene.
+
+**Architecture:** Keep `bootstrap.sh` as the installer entrypoint, but move validation coverage into shell-based integration tests under `tests/`. Extend `bin/axel-setup.js` with subcommands that do not change installation semantics unless explicitly requested.
+
+**Tech Stack:** Bash, Node.js built-ins, jq, GitHub Actions, npm.
+
+---
+
+### Task 1: Bootstrap Safety And Assets
+
+**Files:**
+- Modify: `bootstrap.sh`
+- Test: `tests/bootstrap-behavior.sh`
+
+- [ ] Write tests that prove `--dry-run` does not create `~/.claude`, recursive skill assets install, and skip flags prevent plugin, GSD, and launchd side effects.
+- [ ] Run `bash tests/bootstrap-behavior.sh` and verify the new assertions fail.
+- [ ] Update `bootstrap.sh` so dry-run wraps all filesystem writes, skill directories copy recursively, and `--skip-plugins`, `--skip-gsd`, `--no-launchd`, and `--profile` are parsed.
+- [ ] Re-run `bash tests/bootstrap-behavior.sh` and verify it passes.
+
+### Task 2: Profiles, Manifest, And Doctor
+
+**Files:**
+- Modify: `bootstrap.sh`
+- Modify: `bin/axel-setup.js`
+- Add: `axel-manifest.json`
+- Test: `tests/cli-doctor.sh`
+
+- [ ] Write tests that prove `axel-setup doctor --home <tmp>` detects installed files and missing files without mutating state.
+- [ ] Run `bash tests/cli-doctor.sh` and verify it fails before implementation.
+- [ ] Add manifest metadata for installable components and make bootstrap install the manifest into `~/.claude/axel-manifest.json`.
+- [ ] Extend `bin/axel-setup.js` with `doctor`, `--help`, and bootstrap passthrough behavior.
+- [ ] Re-run `bash tests/cli-doctor.sh` and verify it passes.
+
+### Task 3: CI, Release, And Docs
+
+**Files:**
+- Modify: `scripts/ci/check.sh`
+- Modify: `.github/workflows/ci.yml`
+- Add: `.github/workflows/release.yml`
+- Modify: `README.md`
+- Modify: `CHANGELOG.md`
+
+- [ ] Add checks for shfmt and shellcheck when available, without making local machines fail if the tools are absent.
+- [ ] Add GitHub Actions installation for shellcheck and shfmt.
+- [ ] Add npm provenance release workflow triggered by `v*` tags.
+- [ ] Update README to make `npx axel-setup` the primary path after npm publish and document profiles and skip flags.
+- [ ] Run `npm run check` and `npm run publish:dry-run`.
+
+### Task 4: GitHub Roadmap Hygiene
+
+**Files:**
+- No repo file changes required.
+
+- [ ] Create labels for roadmap phases and feature classes.
+- [ ] Create milestone `v0.2.0 Setup Hardening`.
+- [ ] Open public issues for release automation, installer one-liner, OSS core separation, harness tests, upgrade workflow, and metrics.
+- [ ] Push branch and open PR.

package/hooks/desktop-notify.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+# Desktop notification ONLY when Claude Code CLI finishes a main response
+# Ignores: subagents, Cursor, other AI tools
+
+# Guard: only notify from Claude Code CLI — skip Cursor, VS Code, and any non-CLI entrypoint
+if [ "$CLAUDE_CODE_ENTRYPOINT" != "cli" ]; then
+  exit 0
+fi
+
+# Guard: skip if this is a subagent (spawned by Agent tool)
+# Subagents have CLAUDE_AGENT_ID or run in /tmp worktrees
+if [ -n "$CLAUDE_AGENT_ID" ]; then
+  exit 0
+fi
+if echo "$(pwd)" | grep -qE '/tmp/claude|\.worktrees/'; then
+  exit 0
+fi
+
+# Only notify if terminal is NOT the active app
+ACTIVE_APP=$(osascript -e 'tell application "System Events" to get name of first application process whose frontmost is true' 2>/dev/null)
+
+if [[ "$ACTIVE_APP" != "Terminal" ]] && [[ "$ACTIVE_APP" != "iTerm2" ]] && [[ "$ACTIVE_APP" != "Ghostty" ]] && [[ "$ACTIVE_APP" != "WezTerm" ]] && [[ "$ACTIVE_APP" != "kitty" ]] && [[ "$ACTIVE_APP" != "Alacritty" ]]; then
+  osascript -e 'display notification "Claude terminó de responder" with title "Claude Code" sound name "Glass"' 2>/dev/null
+fi
+
+exit 0

package/hooks/enforce-agent-model.jq

@@ -0,0 +1,14 @@
+# PreToolUse hook filter (matcher: Agent). Blocks Agent calls without an explicit model param.
+# Companion to ~/.claude/skills/model-routing/SKILL.md: without model, subagents inherit the
+# expensive session model (Fable). Emits a deny decision so the model retries with model set.
+if (.tool_input.model // "") == "" then
+  {
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: "Agent call blocked: missing required model param (subagents inherit the expensive session model otherwise). Retry the SAME Agent call adding model per the model-routing skill: sonnet (exploration, research, bounded implementation), haiku (mechanical reduction, log/test triage, inventories), opus (risky implementation, code review, adversarial verification). Use fable only if judgment itself must run in a subagent."
+    }
+  }
+else
+  empty
+end

package/hooks/gsd-context-monitor.js

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+// gsd-hook-version: 1.30.0
+// Context Monitor - PostToolUse/AfterTool hook (Gemini uses AfterTool)
+// Reads context metrics from the statusline bridge file and injects
+// warnings when context usage is high. This makes the AGENT aware of
+// context limits (the statusline only shows the user).
+//
+// How it works:
+// 1. The statusline hook writes metrics to /tmp/claude-ctx-{session_id}.json
+// 2. This hook reads those metrics after each tool use
+// 3. When remaining context drops below thresholds, it injects a warning
+//    as additionalContext, which the agent sees in its conversation
+//
+// Thresholds:
+//   WARNING  (remaining <= 35%): Agent should wrap up current task
+//   CRITICAL (remaining <= 25%): Agent should stop immediately and save state
+//
+// Debounce: 5 tool uses between warnings to avoid spam
+// Severity escalation bypasses debounce (WARNING -> CRITICAL fires immediately)
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const WARNING_THRESHOLD = 15;  // remaining_percentage <= 15% (lowered for 1M context)
+const CRITICAL_THRESHOLD = 8;  // remaining_percentage <= 8%
+const STALE_SECONDS = 60;      // ignore metrics older than 60s
+const DEBOUNCE_CALLS = 10;     // min tool uses between warnings
+
+let input = '';
+// Timeout guard: if stdin doesn't close within 10s (e.g. pipe issues on
+// Windows/Git Bash, or slow Claude Code piping during large outputs),
+// exit silently instead of hanging until Claude Code kills the process
+// and reports "hook error". See #775, #1162.
+const stdinTimeout = setTimeout(() => process.exit(0), 10000);
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
+  try {
+    const data = JSON.parse(input);
+    const sessionId = data.session_id;
+
+    if (!sessionId) {
+      process.exit(0);
+    }
+
+    // Check if context warnings are disabled via config
+    const cwd = data.cwd || process.cwd();
+    const configPath = path.join(cwd, '.planning', 'config.json');
+    if (fs.existsSync(configPath)) {
+      try {
+        const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        if (config.hooks?.context_warnings === false) {
+          process.exit(0);
+        }
+      } catch (e) {
+        // Ignore config parse errors
+      }
+    }
+
+    const tmpDir = os.tmpdir();
+    const metricsPath = path.join(tmpDir, `claude-ctx-${sessionId}.json`);
+
+    // If no metrics file, this is a subagent or fresh session -- exit silently
+    if (!fs.existsSync(metricsPath)) {
+      process.exit(0);
+    }
+
+    const metrics = JSON.parse(fs.readFileSync(metricsPath, 'utf8'));
+    const now = Math.floor(Date.now() / 1000);
+
+    // Ignore stale metrics
+    if (metrics.timestamp && (now - metrics.timestamp) > STALE_SECONDS) {
+      process.exit(0);
+    }
+
+    const remaining = metrics.remaining_percentage;
+    const usedPct = metrics.used_pct;
+
+    // No warning needed
+    if (remaining > WARNING_THRESHOLD) {
+      process.exit(0);
+    }
+
+    // Debounce: check if we warned recently
+    const warnPath = path.join(tmpDir, `claude-ctx-${sessionId}-warned.json`);
+    let warnData = { callsSinceWarn: 0, lastLevel: null };
+    let firstWarn = true;
+
+    if (fs.existsSync(warnPath)) {
+      try {
+        warnData = JSON.parse(fs.readFileSync(warnPath, 'utf8'));
+        firstWarn = false;
+      } catch (e) {
+        // Corrupted file, reset
+      }
+    }
+
+    warnData.callsSinceWarn = (warnData.callsSinceWarn || 0) + 1;
+
+    const isCritical = remaining <= CRITICAL_THRESHOLD;
+    const currentLevel = isCritical ? 'critical' : 'warning';
+
+    // Emit immediately on first warning, then debounce subsequent ones
+    // Severity escalation (WARNING -> CRITICAL) bypasses debounce
+    const severityEscalated = currentLevel === 'critical' && warnData.lastLevel === 'warning';
+    if (!firstWarn && warnData.callsSinceWarn < DEBOUNCE_CALLS && !severityEscalated) {
+      // Update counter and exit without warning
+      fs.writeFileSync(warnPath, JSON.stringify(warnData));
+      process.exit(0);
+    }
+
+    // Reset debounce counter
+    warnData.callsSinceWarn = 0;
+    warnData.lastLevel = currentLevel;
+    fs.writeFileSync(warnPath, JSON.stringify(warnData));
+
+    // Detect if GSD is active (has .planning/STATE.md in working directory)
+    const isGsdActive = fs.existsSync(path.join(cwd, '.planning', 'STATE.md'));
+
+    // Build advisory warning message (never use imperative commands that
+    // override user preferences — see #884)
+    let message;
+    if (isCritical) {
+      message = isGsdActive
+        ? `CONTEXT CRITICAL: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+          'Context is nearly exhausted. Do NOT start new complex work or write handoff files — ' +
+          'GSD state is already tracked in STATE.md. Inform the user so they can run ' +
+          '/gsd:pause-work at the next natural stopping point.'
+        : `CONTEXT CRITICAL: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+          'Context is nearly exhausted. Inform the user that context is low and ask how they ' +
+          'want to proceed. Do NOT autonomously save state or write handoff files unless the user asks.';
+    } else {
+      message = isGsdActive
+        ? `CONTEXT WARNING: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+          'Context is getting limited. Avoid starting new complex work. If not between ' +
+          'defined plan steps, inform the user so they can prepare to pause.'
+        : `CONTEXT WARNING: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+          'Be aware that context is getting limited. Avoid unnecessary exploration or ' +
+          'starting new complex work.';
+    }
+
+    const output = {
+      hookSpecificOutput: {
+        hookEventName: process.env.GEMINI_API_KEY ? "AfterTool" : "PostToolUse",
+        additionalContext: message
+      }
+    };
+
+    process.stdout.write(JSON.stringify(output));
+  } catch (e) {
+    // Silent fail -- never block tool execution
+    process.exit(0);
+  }
+});

package/hooks/linear-lifecycle-sync.sh

@@ -0,0 +1,112 @@
+#!/bin/bash
+# linear-lifecycle-sync.sh
+# Auto-syncs Linear card state based on git/gh actions.
+# Runs as PostToolUse Bash hook (async).
+#
+# Requirements:
+#   - Linear MCP server connected (linear-server)
+#   - claude CLI available (for the haiku sub-call)
+#   - Tickets in commit messages follow the pattern: KEY-123
+#     (configure TICKET_PATTERN below to match your team's prefix)
+#
+# Behavior:
+#   git commit (KEY-123) → In Progress  (if currently Todo/Backlog)
+#   gh pr create          → In Review
+#   gh pr merge           → Done
+#
+# Bootstrap substitution: set REPO_PATH_FILTER to a regex matching your
+# repo paths so the hook only fires in those directories.
+# Example: '/home/user/projects/mycompany/'
+# Leave empty ("") to run in all directories.
+REPO_PATH_FILTER="{{REPO_PATH_FILTER}}"
+case "$REPO_PATH_FILTER" in "{{"*"}}"|"") REPO_PATH_FILTER="" ;; esac
+
+TICKET_PATTERN="{{TICKET_PATTERN}}"
+case "$TICKET_PATTERN" in "{{"*"}}"|"") TICKET_PATTERN="[A-Z]+-[0-9]+" ;; esac
+
+LINEAR_TEAM="{{LINEAR_TEAM}}"
+case "$LINEAR_TEAM" in "{{"*"}}"|"") LINEAR_TEAM="your team" ;; esac
+
+# Guard against recursive invocation (this script spawns claude -p)
+if [ -n "$CLAUDE_LINEAR_SYNC" ]; then exit 0; fi
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+CWD=$(echo "$INPUT" | jq -r '.cwd // empty' 2>/dev/null)
+
+# Only run in configured repos (skip if filter is empty — runs everywhere)
+if [ -n "$REPO_PATH_FILTER" ] && ! echo "$CWD" | grep -qE "$REPO_PATH_FILTER"; then exit 0; fi
+
+# --- Detect action type ---
+ACTION=""
+TICKETS=""
+
+if echo "$COMMAND" | grep -qE '(^|[[:space:]&;|(])git[[:space:]]+commit([[:space:]]|$)'; then
+  ACTION="in_progress"
+  TICKETS=$(echo "$COMMAND" | grep -oE "$TICKET_PATTERN" | sort -u | tr '\n' ' ' | sed 's/ $//')
+
+elif echo "$COMMAND" | grep -qE '(^|[[:space:]&;|(])gh[[:space:]]+pr[[:space:]]+create'; then
+  ACTION="in_review"
+  TICKETS=$(echo "$COMMAND" | grep -oE "$TICKET_PATTERN" | sort -u | tr '\n' ' ' | sed 's/ $//')
+  if [ -z "$TICKETS" ]; then
+    TICKETS=$(git -C "$CWD" log --not --remotes --pretty=format:"%s %b" 2>/dev/null \
+      | grep -oE "$TICKET_PATTERN" | sort -u | tr '\n' ' ' | sed 's/ $//')
+  fi
+
+elif echo "$COMMAND" | grep -qE '(^|[[:space:]&;|(])gh[[:space:]]+pr[[:space:]]+merge'; then
+  ACTION="done"
+  TICKETS=$(echo "$COMMAND" | grep -oE "$TICKET_PATTERN" | sort -u | tr '\n' ' ' | sed 's/ $//')
+  if [ -z "$TICKETS" ]; then
+    TICKETS=$(git -C "$CWD" log --not --remotes --pretty=format:"%s %b" 2>/dev/null \
+      | grep -oE "$TICKET_PATTERN" | sort -u | tr '\n' ' ' | sed 's/ $//')
+  fi
+fi
+
+[ -z "$ACTION" ] && exit 0
+[ -z "$TICKETS" ] && exit 0
+
+# --- Rate limit: 90s debounce per action type ---
+RATE_FILE="$HOME/.claude/.linear_sync_${ACTION}"
+if [ -f "$RATE_FILE" ]; then
+  LAST=$(stat -f %m "$RATE_FILE" 2>/dev/null || stat -c %Y "$RATE_FILE" 2>/dev/null)
+  NOW=$(date +%s)
+  if [ -n "$LAST" ] && [ $((NOW - LAST)) -lt 90 ]; then exit 0; fi
+fi
+touch "$RATE_FILE"
+
+# --- Determine target state label ---
+case "$ACTION" in
+  in_progress) TARGET="In Progress" ;;
+  in_review)   TARGET="In Review" ;;
+  done)        TARGET="Done" ;;
+  *) exit 0 ;;
+esac
+
+PROMPT="You are a Linear lifecycle sync agent. Update card states silently and efficiently. No explanations, no headers — just one line per ticket.
+
+Tickets to process: $TICKETS
+Target state: $TARGET
+Team: $LINEAR_TEAM
+
+Instructions:
+1. Call list_issue_statuses to find the state ID for '$TARGET' in the $LINEAR_TEAM team.
+2. For each ticket, call get_issue to check its current state name.
+3. Skip rules:
+   - If target is 'In Progress' and current state is already In Progress, In Review, or Done → skip.
+   - If target is 'In Review' and current state is already In Review or Done → skip.
+   - If target is 'Done' and current state is already Done → skip.
+4. For tickets that need updating, call save_issue with the new stateId.
+5. Output format (one line per ticket):
+   KEY-123 → In Progress
+   KEY-456: already In Review, skipped"
+
+HOOK_TMP=$(mktemp -d 2>/dev/null)
+REAL_TMP=$(cd "$HOOK_TMP" 2>/dev/null && pwd -P)
+RESULT=$(cd "$HOOK_TMP" 2>/dev/null && printf '%s' "$PROMPT" | CLAUDE_LINEAR_SYNC=1 claude -p --model haiku 2>/dev/null)
+GHOST_SLUG=$(echo "$REAL_TMP" | sed 's|[^a-zA-Z0-9]|-|g')
+rm -rf "$HOOK_TMP" "$HOME/.claude/projects/${GHOST_SLUG}" 2>/dev/null
+
+mkdir -p "$HOME/.claude/logs"
+echo "[$(date '+%Y-%m-%d %H:%M:%S')] [$ACTION] $TICKETS → $RESULT" >> "$HOME/.claude/logs/linear-sync.log"
+
+exit 0

package/hooks/memory-dedup.sh

@@ -0,0 +1,122 @@
+#!/bin/zsh
+# Memory dedup check — hash-based duplicate detection + orphan cleanup
+# Inspired by Claw Code's hash-based instruction file dedup.
+# Uses zsh for associative array support on macOS.
+#
+# Run standalone: zsh memory-dedup.sh
+# Exit codes: 0 = clean/fixed
+
+MEMORY_DIR="${MEMORY_DIR:-$HOME/.claude/memory}"
+MEMORY_INDEX="$MEMORY_DIR/MEMORY.md"
+LOG_FILE="$HOME/.claude/logs/memory-dedup.log"
+QUIET="${QUIET:-false}"
+
+mkdir -p "$(dirname "$LOG_FILE")"
+
+log() { echo "[$(date +%H:%M:%S)] $1" >> "$LOG_FILE"; [[ "$QUIET" == "true" ]] || echo "$1"; }
+
+found_issues=0
+
+# --- 1. Content-based duplicate detection ---
+typeset -A hash_map
+
+for f in "$MEMORY_DIR"/*.md(N); do
+  [[ ! -f "$f" ]] && continue
+  local BASENAME="${f:t}"
+  [[ "$BASENAME" == "MEMORY.md" ]] && continue
+
+  local BODY=$(awk 'BEGIN{c=0} /^---$/{c++; next} c>=2{print}' "$f")
+  [[ -z "$BODY" ]] && continue
+  local HASH=$(echo "$BODY" | md5 -q)
+
+  if [[ -n "${hash_map[$HASH]}" ]]; then
+    local EXISTING="${hash_map[$HASH]}"
+    log "DUPLICATE: $BASENAME has identical content to $EXISTING"
+
+    if grep -qF "$EXISTING" "$MEMORY_INDEX" 2>/dev/null; then
+      log "  -> Removing $BASENAME (keeping indexed $EXISTING)"
+      rm "$f"
+      found_issues=1
+    elif grep -qF "$BASENAME" "$MEMORY_INDEX" 2>/dev/null; then
+      log "  -> Removing $EXISTING (keeping indexed $BASENAME)"
+      rm "$MEMORY_DIR/$EXISTING"
+      hash_map[$HASH]="$BASENAME"
+      found_issues=1
+    else
+      if [[ "$f" -nt "$MEMORY_DIR/$EXISTING" ]]; then
+        log "  -> Removing $EXISTING (keeping newer $BASENAME)"
+        rm "$MEMORY_DIR/$EXISTING"
+        hash_map[$HASH]="$BASENAME"
+      else
+        log "  -> Removing $BASENAME (keeping newer $EXISTING)"
+        rm "$f"
+      fi
+      found_issues=1
+    fi
+  else
+    hash_map[$HASH]="$BASENAME"
+  fi
+done
+
+# --- 2. Semantic duplicate detection (same frontmatter name) ---
+typeset -A name_map
+
+for f in "$MEMORY_DIR"/*.md(N); do
+  [[ ! -f "$f" ]] && continue
+  local BASENAME="${f:t}"
+  [[ "$BASENAME" == "MEMORY.md" ]] && continue
+
+  local NAME=$(awk '/^name:/{sub(/^name: */, ""); print; exit}' "$f")
+  [[ -z "$NAME" ]] && continue
+  local NAME_LOWER="${NAME:l}"
+
+  if [[ -n "${name_map[$NAME_LOWER]}" ]]; then
+    local EXISTING="${name_map[$NAME_LOWER]}"
+    [[ "$BASENAME" == "$EXISTING" ]] && continue
+    log "SAME NAME: $BASENAME and $EXISTING share name \"$NAME\""
+    log "  -> Manual review recommended (content may differ)"
+    found_issues=1
+  else
+    name_map[$NAME_LOWER]="$BASENAME"
+  fi
+done
+
+# --- 3. Orphan detection (files not in MEMORY.md index) ---
+if [[ -f "$MEMORY_INDEX" ]]; then
+  for f in "$MEMORY_DIR"/*.md(N); do
+    [[ ! -f "$f" ]] && continue
+    local BASENAME="${f:t}"
+    [[ "$BASENAME" == "MEMORY.md" ]] && continue
+
+    if ! grep -qF "$BASENAME" "$MEMORY_INDEX"; then
+      log "ORPHAN: $BASENAME not in MEMORY.md index"
+
+      local NAME=$(awk '/^name:/{sub(/^name: */, ""); print; exit}' "$f")
+      local DESC=$(awk '/^description:/{sub(/^description: */, ""); print; exit}' "$f")
+      if [[ -n "$NAME" ]] && [[ -n "$DESC" ]]; then
+        local INDEX_LINE="- [$NAME]($BASENAME) — $DESC"
+        echo "$INDEX_LINE" >> "$MEMORY_INDEX"
+        log "  -> Auto-indexed: $INDEX_LINE"
+      else
+        log "  -> Cannot auto-index (missing name/description frontmatter)"
+      fi
+      found_issues=1
+    fi
+  done
+fi
+
+# --- 4. Dead link detection ---
+if [[ -f "$MEMORY_INDEX" ]]; then
+  grep -oE '\([^)]+\.md\)' "$MEMORY_INDEX" | tr -d '()' | while read -r fname; do
+    if [[ ! -f "$MEMORY_DIR/$fname" ]]; then
+      log "DEAD LINK: $fname referenced in MEMORY.md but file missing"
+      sed -i '' "/${fname//\//\\/}/d" "$MEMORY_INDEX" 2>/dev/null
+      log "  -> Removed dead link from MEMORY.md"
+      found_issues=1
+    fi
+  done
+fi
+
+[[ $found_issues -eq 0 ]] && log "Memory check: all clean ($(ls "$MEMORY_DIR"/*.md 2>/dev/null | grep -v MEMORY.md | wc -l | tr -d ' ') files)"
+
+exit 0