M CHANGELOG.md => CHANGELOG.md +11 -0
@@ 1,5 1,16 @@
# Changelog
+## [0.7.3] - 2026-03-18
+
+### Added
+
+- **Safety guardrails you can turn on with one command.** Say "be careful" or "safety mode" and `/careful` will warn you before any destructive command — `rm -rf`, `DROP TABLE`, force-push, `kubectl delete`, and more. You can override every warning. Common build artifact cleanups (`rm -rf node_modules`, `dist`, `.next`) are whitelisted.
+- **Lock edits to one folder with `/freeze`.** Debugging something and don't want Claude to "fix" unrelated code? `/freeze` blocks all file edits outside a directory you choose. Hard block, not just a warning. Run `/unfreeze` to remove the restriction without ending your session.
+- **`/guard` activates both at once.** One command for maximum safety when touching prod or live systems — destructive command warnings plus directory-scoped edit restrictions.
+- **`/debug` now auto-freezes edits to the module being debugged.** After forming a root cause hypothesis, `/debug` locks edits to the narrowest affected directory. No more accidental "fixes" to unrelated code during debugging.
+- **You can now see which skills you use and how often.** Every skill invocation is logged locally to `~/.gstack/analytics/skill-usage.jsonl`. Run `bun run analytics` to see your top skills, per-repo breakdown, and how often safety hooks actually catch something. Data stays on your machine.
+- **Weekly retros now include skill usage.** `/retro` shows which skills you used during the retro window alongside your usual commit analysis and metrics.
+
## [0.7.2] - 2026-03-18
### Fixed
M SKILL.md => SKILL.md +2 -0
@@ 56,6 56,8 @@ _BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
echo "BRANCH: $_BRANCH"
_LAKE_SEEN=$([ -f ~/.gstack/.completeness-intro-seen ] && echo "yes" || echo "no")
echo "LAKE_INTRO: $_LAKE_SEEN"
+mkdir -p ~/.gstack/analytics
+echo '{"skill":"gstack","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
_PROACTIVE=$(~/.claude/skills/gstack/bin/gstack-config get proactive 2>/dev/null || echo "true")
echo "PROACTIVE: $_PROACTIVE"
```
M TODOS.md => TODOS.md +20 -17
@@ 506,34 506,37 @@ Shipped as v0.5.0 on main. Includes `/plan-design-review` (report-only design au
## Safety & Observability
-### On-demand hook skills (/careful, /freeze, /guard)
+### On-demand hook skills (/careful, /freeze, /guard) — SHIPPED
-**What:** Three new skills that use Claude Code's session-scoped PreToolUse hooks to add safety guardrails on demand.
+~~**What:** Three new skills that use Claude Code's session-scoped PreToolUse hooks to add safety guardrails on demand.~~
-**Why:** Anthropic's internal skill best practices recommend on-demand hooks for safety. Claude Code already handles destructive command permissions, but these add an explicit opt-in layer for high-risk sessions (touching prod, debugging live systems).
+Shipped as `/careful`, `/freeze`, `/guard`, and `/unfreeze` in v0.6.5. Includes hook fire-rate telemetry (pattern name only, no command content) and inline skill activation telemetry.
-**Skills:**
-- `/careful` — PreToolUse hook on Bash tool. Warns (not blocks) before destructive commands: `rm -rf`, `DROP TABLE`, `git push --force`, `git reset --hard`, `kubectl delete`, `docker system prune`. Uses `permissionDecision: "ask"` so user can override.
-- `/freeze` — PreToolUse hook on Edit/Write tools. Restricts file edits to a user-specified directory. Great for debugging without accidentally "fixing" unrelated code.
-- `/guard` — meta-skill composing `/careful` + `/freeze` into one command.
+### Skill usage telemetry — SHIPPED
-**Implementation notes:** Use `${CLAUDE_SKILL_DIR}` (not `${SKILL_DIR}`) for script paths in hook commands. Pure bash JSON parsing (no jq dependency). Freeze dir storage: `${CLAUDE_PLUGIN_DATA}/freeze-dir.txt` with `~/.gstack/freeze-dir.txt` fallback. Ensure trailing `/` on freeze dir paths to prevent `/src` matching `/src-old`.
+~~**What:** Track which skills get invoked, how often, from which repo.~~
-**Effort:** M (human) / S (CC)
-**Priority:** P3
-**Depends on:** None
+Shipped in v0.6.5. TemplateContext in gen-skill-docs.ts bakes skill name into preamble telemetry line. Analytics CLI (`bun run analytics`) for querying. /retro integration shows skills-used-this-week.
-### Skill usage telemetry
+### /debug scoped debugging enhancements (gated on telemetry)
-**What:** Track which skills get invoked, how often, from which repo.
+**What:** Six enhancements to /debug auto-freeze, contingent on telemetry showing the freeze hook actually fires in real debugging sessions.
-**Why:** Enables finding undertriggering skills and measuring adoption. Anthropic uses a PreToolUse hook for this; simpler approach is appending JSONL from the preamble.
+**Why:** /debug v0.7.1 auto-freezes edits to the module being debugged. If telemetry shows the hook fires often, these enhancements make the experience smarter. If it never fires, the problem wasn't real and these aren't worth building.
-**Context:** Add to `generatePreamble()` in `scripts/gen-skill-docs.ts`. Append to `~/.gstack/analytics/skill-usage.jsonl` with skill name, timestamp, and repo name. `mkdir -p` ensures the directory exists.
+**Context:** All items are prose additions to `debug/SKILL.md.tmpl`. No new scripts.
-**Effort:** S (human) / S (CC)
+**Items:**
+1. Stack trace auto-detection for freeze directory (parse deepest app frame)
+2. Freeze boundary widening (ask to widen instead of hard-block when hitting boundary)
+3. Post-fix auto-unfreeze + full test suite run
+4. Debug instrumentation cleanup (tag with DEBUG-TEMP, remove before commit)
+5. Debug session persistence (~/.gstack/debug-sessions/ — save investigation for reuse)
+6. Investigation timeline in debug report (hypothesis log with timing)
+
+**Effort:** M (all 6 combined)
**Priority:** P3
-**Depends on:** None
+**Depends on:** Telemetry data showing freeze hook fires in real /debug sessions
## Completed
M VERSION => VERSION +1 -1
@@ 1,1 1,1 @@
-0.7.2
+0.7.3
M browse/SKILL.md => browse/SKILL.md +2 -0
@@ 31,6 31,8 @@ _BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
echo "BRANCH: $_BRANCH"
_LAKE_SEEN=$([ -f ~/.gstack/.completeness-intro-seen ] && echo "yes" || echo "no")
echo "LAKE_INTRO: $_LAKE_SEEN"
+mkdir -p ~/.gstack/analytics
+echo '{"skill":"browse","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
_PROACTIVE=$(~/.claude/skills/gstack/bin/gstack-config get proactive 2>/dev/null || echo "true")
echo "PROACTIVE: $_PROACTIVE"
```
A careful/SKILL.md => careful/SKILL.md +59 -0
@@ 0,0 1,59 @@
+---
+name: careful
+version: 0.1.0
+description: |
+ Safety guardrails for destructive commands. Warns before rm -rf, DROP TABLE,
+ force-push, git reset --hard, kubectl delete, and similar destructive operations.
+ User can override each warning. Use when touching prod, debugging live systems,
+ or working in a shared environment. Use when asked to "be careful", "safety mode",
+ "prod mode", or "careful mode".
+allowed-tools:
+ - Bash
+ - Read
+hooks:
+ PreToolUse:
+ - matcher: "Bash"
+ hooks:
+ - type: command
+ command: "bash ${CLAUDE_SKILL_DIR}/bin/check-careful.sh"
+ statusMessage: "Checking for destructive commands..."
+---
+<!-- AUTO-GENERATED from SKILL.md.tmpl — do not edit directly -->
+<!-- Regenerate: bun run gen:skill-docs -->
+
+# /careful — Destructive Command Guardrails
+
+Safety mode is now **active**. Every bash command will be checked for destructive
+patterns before running. If a destructive command is detected, you'll be warned
+and can choose to proceed or cancel.
+
+```bash
+mkdir -p ~/.gstack/analytics
+echo '{"skill":"careful","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
+```
+
+## What's protected
+
+| Pattern | Example | Risk |
+|---------|---------|------|
+| `rm -rf` / `rm -r` / `rm --recursive` | `rm -rf /var/data` | Recursive delete |
+| `DROP TABLE` / `DROP DATABASE` | `DROP TABLE users;` | Data loss |
+| `TRUNCATE` | `TRUNCATE orders;` | Data loss |
+| `git push --force` / `-f` | `git push -f origin main` | History rewrite |
+| `git reset --hard` | `git reset --hard HEAD~3` | Uncommitted work loss |
+| `git checkout .` / `git restore .` | `git checkout .` | Uncommitted work loss |
+| `kubectl delete` | `kubectl delete pod` | Production impact |
+| `docker rm -f` / `docker system prune` | `docker system prune -a` | Container/image loss |
+
+## Safe exceptions
+
+These patterns are allowed without warning:
+- `rm -rf node_modules` / `.next` / `dist` / `__pycache__` / `.cache` / `build` / `.turbo` / `coverage`
+
+## How it works
+
+The hook reads the command from the tool input JSON, checks it against the
+patterns above, and returns `permissionDecision: "ask"` with a warning message
+if a match is found. You can always override the warning and proceed.
+
+To deactivate, end the conversation or start a new one. Hooks are session-scoped.
A careful/SKILL.md.tmpl => careful/SKILL.md.tmpl +57 -0
@@ 0,0 1,57 @@
+---
+name: careful
+version: 0.1.0
+description: |
+ Safety guardrails for destructive commands. Warns before rm -rf, DROP TABLE,
+ force-push, git reset --hard, kubectl delete, and similar destructive operations.
+ User can override each warning. Use when touching prod, debugging live systems,
+ or working in a shared environment. Use when asked to "be careful", "safety mode",
+ "prod mode", or "careful mode".
+allowed-tools:
+ - Bash
+ - Read
+hooks:
+ PreToolUse:
+ - matcher: "Bash"
+ hooks:
+ - type: command
+ command: "bash ${CLAUDE_SKILL_DIR}/bin/check-careful.sh"
+ statusMessage: "Checking for destructive commands..."
+---
+
+# /careful — Destructive Command Guardrails
+
+Safety mode is now **active**. Every bash command will be checked for destructive
+patterns before running. If a destructive command is detected, you'll be warned
+and can choose to proceed or cancel.
+
+```bash
+mkdir -p ~/.gstack/analytics
+echo '{"skill":"careful","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
+```
+
+## What's protected
+
+| Pattern | Example | Risk |
+|---------|---------|------|
+| `rm -rf` / `rm -r` / `rm --recursive` | `rm -rf /var/data` | Recursive delete |
+| `DROP TABLE` / `DROP DATABASE` | `DROP TABLE users;` | Data loss |
+| `TRUNCATE` | `TRUNCATE orders;` | Data loss |
+| `git push --force` / `-f` | `git push -f origin main` | History rewrite |
+| `git reset --hard` | `git reset --hard HEAD~3` | Uncommitted work loss |
+| `git checkout .` / `git restore .` | `git checkout .` | Uncommitted work loss |
+| `kubectl delete` | `kubectl delete pod` | Production impact |
+| `docker rm -f` / `docker system prune` | `docker system prune -a` | Container/image loss |
+
+## Safe exceptions
+
+These patterns are allowed without warning:
+- `rm -rf node_modules` / `.next` / `dist` / `__pycache__` / `.cache` / `build` / `.turbo` / `coverage`
+
+## How it works
+
+The hook reads the command from the tool input JSON, checks it against the
+patterns above, and returns `permissionDecision: "ask"` with a warning message
+if a match is found. You can always override the warning and proceed.
+
+To deactivate, end the conversation or start a new one. Hooks are session-scoped.
A careful/bin/check-careful.sh => careful/bin/check-careful.sh +112 -0
@@ 0,0 1,112 @@
+#!/usr/bin/env bash
+# check-careful.sh — PreToolUse hook for /careful skill
+# Reads JSON from stdin, checks Bash command for destructive patterns.
+# Returns {"permissionDecision":"ask","message":"..."} to warn, or {} to allow.
+set -euo pipefail
+
+# Read stdin (JSON with tool_input)
+INPUT=$(cat)
+
+# Extract the "command" field value from tool_input
+# Try grep/sed first (handles 99% of cases), fall back to Python for escaped quotes
+CMD=$(printf '%s' "$INPUT" | grep -o '"command"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*:[[:space:]]*"//;s/"$//' || true)
+
+# Python fallback if grep returned empty (e.g., escaped quotes in command)
+if [ -z "$CMD" ]; then
+ CMD=$(printf '%s' "$INPUT" | python3 -c 'import sys,json; print(json.loads(sys.stdin.read()).get("tool_input",{}).get("command",""))' 2>/dev/null || true)
+fi
+
+# If we still couldn't extract a command, allow
+if [ -z "$CMD" ]; then
+ echo '{}'
+ exit 0
+fi
+
+# Normalize: lowercase for case-insensitive SQL matching
+CMD_LOWER=$(printf '%s' "$CMD" | tr '[:upper:]' '[:lower:]')
+
+# --- Check for safe exceptions (rm -rf of build artifacts) ---
+if printf '%s' "$CMD" | grep -qE 'rm\s+(-[a-zA-Z]*r[a-zA-Z]*\s+|--recursive\s+)' 2>/dev/null; then
+ SAFE_ONLY=true
+ RM_ARGS=$(printf '%s' "$CMD" | sed -E 's/.*rm\s+(-[a-zA-Z]+\s+)*//;s/--recursive\s*//')
+ for target in $RM_ARGS; do
+ case "$target" in
+ */node_modules|node_modules|*/\.next|\.next|*/dist|dist|*/__pycache__|__pycache__|*/\.cache|\.cache|*/build|build|*/\.turbo|\.turbo|*/coverage|coverage)
+ ;; # safe target
+ -*)
+ ;; # flag, skip
+ *)
+ SAFE_ONLY=false
+ break
+ ;;
+ esac
+ done
+ if [ "$SAFE_ONLY" = true ]; then
+ echo '{}'
+ exit 0
+ fi
+fi
+
+# --- Destructive pattern checks ---
+WARN=""
+PATTERN=""
+
+# rm -rf / rm -r / rm --recursive
+if printf '%s' "$CMD" | grep -qE 'rm\s+(-[a-zA-Z]*r|--recursive)' 2>/dev/null; then
+ WARN="Destructive: recursive delete (rm -r). This permanently removes files."
+ PATTERN="rm_recursive"
+fi
+
+# DROP TABLE / DROP DATABASE
+if [ -z "$WARN" ] && printf '%s' "$CMD_LOWER" | grep -qE 'drop\s+(table|database)' 2>/dev/null; then
+ WARN="Destructive: SQL DROP detected. This permanently deletes database objects."
+ PATTERN="drop_table"
+fi
+
+# TRUNCATE
+if [ -z "$WARN" ] && printf '%s' "$CMD_LOWER" | grep -qE '\btruncate\b' 2>/dev/null; then
+ WARN="Destructive: SQL TRUNCATE detected. This deletes all rows from a table."
+ PATTERN="truncate"
+fi
+
+# git push --force / git push -f
+if [ -z "$WARN" ] && printf '%s' "$CMD" | grep -qE 'git\s+push\s+.*(-f\b|--force)' 2>/dev/null; then
+ WARN="Destructive: git force-push rewrites remote history. Other contributors may lose work."
+ PATTERN="git_force_push"
+fi
+
+# git reset --hard
+if [ -z "$WARN" ] && printf '%s' "$CMD" | grep -qE 'git\s+reset\s+--hard' 2>/dev/null; then
+ WARN="Destructive: git reset --hard discards all uncommitted changes."
+ PATTERN="git_reset_hard"
+fi
+
+# git checkout . / git restore .
+if [ -z "$WARN" ] && printf '%s' "$CMD" | grep -qE 'git\s+(checkout|restore)\s+\.' 2>/dev/null; then
+ WARN="Destructive: discards all uncommitted changes in the working tree."
+ PATTERN="git_discard"
+fi
+
+# kubectl delete
+if [ -z "$WARN" ] && printf '%s' "$CMD" | grep -qE 'kubectl\s+delete' 2>/dev/null; then
+ WARN="Destructive: kubectl delete removes Kubernetes resources. May impact production."
+ PATTERN="kubectl_delete"
+fi
+
+# docker rm -f / docker system prune
+if [ -z "$WARN" ] && printf '%s' "$CMD" | grep -qE 'docker\s+(rm\s+-f|system\s+prune)' 2>/dev/null; then
+ WARN="Destructive: Docker force-remove or prune. May delete running containers or cached images."
+ PATTERN="docker_destructive"
+fi
+
+# --- Output ---
+if [ -n "$WARN" ]; then
+ # Log hook fire event (pattern name only, never command content)
+ mkdir -p ~/.gstack/analytics 2>/dev/null || true
+ echo '{"event":"hook_fire","skill":"careful","pattern":"'"$PATTERN"'","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
+
+ WARN_ESCAPED=$(printf '%s' "$WARN" | sed 's/"/\\"/g')
+ printf '{"permissionDecision":"ask","message":"[careful] %s"}\n' "$WARN_ESCAPED"
+else
+ echo '{}'
+fi
M debug/SKILL.md => debug/SKILL.md +39 -0
@@ 16,6 16,18 @@ allowed-tools:
- Grep
- Glob
- AskUserQuestion
+hooks:
+ PreToolUse:
+ - matcher: "Edit"
+ hooks:
+ - type: command
+ command: "bash ${CLAUDE_SKILL_DIR}/../freeze/bin/check-freeze.sh"
+ statusMessage: "Checking debug scope boundary..."
+ - matcher: "Write"
+ hooks:
+ - type: command
+ command: "bash ${CLAUDE_SKILL_DIR}/../freeze/bin/check-freeze.sh"
+ statusMessage: "Checking debug scope boundary..."
---
<!-- AUTO-GENERATED from SKILL.md.tmpl — do not edit directly -->
<!-- Regenerate: bun run gen:skill-docs -->
@@ 34,6 46,8 @@ _BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
echo "BRANCH: $_BRANCH"
_LAKE_SEEN=$([ -f ~/.gstack/.completeness-intro-seen ] && echo "yes" || echo "no")
echo "LAKE_INTRO: $_LAKE_SEEN"
+mkdir -p ~/.gstack/analytics
+echo '{"skill":"debug","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
_PROACTIVE=$(~/.claude/skills/gstack/bin/gstack-config get proactive 2>/dev/null || echo "true")
echo "PROACTIVE: $_PROACTIVE"
```
@@ 184,6 198,31 @@ Output: **"Root cause hypothesis: ..."** — a specific, testable claim about wh
---
+## Scope Lock
+
+After forming your root cause hypothesis, lock edits to the affected module to prevent scope creep.
+
+```bash
+[ -x "${CLAUDE_SKILL_DIR}/../freeze/bin/check-freeze.sh" ] && echo "FREEZE_AVAILABLE" || echo "FREEZE_UNAVAILABLE"
+```
+
+**If FREEZE_AVAILABLE:** Identify the narrowest directory containing the affected files. Write it to the freeze state file:
+
+```bash
+STATE_DIR="${CLAUDE_PLUGIN_DATA:-$HOME/.gstack}"
+mkdir -p "$STATE_DIR"
+echo "<detected-directory>/" > "$STATE_DIR/freeze-dir.txt"
+echo "Debug scope locked to: <detected-directory>/"
+```
+
+Substitute `<detected-directory>` with the actual directory path (e.g., `src/auth/`). Tell the user: "Edits restricted to `<dir>/` for this debug session. This prevents changes to unrelated code. Run `/unfreeze` to remove the restriction."
+
+If the bug spans the entire repo or the scope is genuinely unclear, skip the lock and note why.
+
+**If FREEZE_UNAVAILABLE:** Skip scope lock. Edits are unrestricted.
+
+---
+
## Phase 2: Pattern Analysis
Check if this bug matches a known pattern:
M debug/SKILL.md.tmpl => debug/SKILL.md.tmpl +37 -0
@@ 16,6 16,18 @@ allowed-tools:
- Grep
- Glob
- AskUserQuestion
+hooks:
+ PreToolUse:
+ - matcher: "Edit"
+ hooks:
+ - type: command
+ command: "bash ${CLAUDE_SKILL_DIR}/../freeze/bin/check-freeze.sh"
+ statusMessage: "Checking debug scope boundary..."
+ - matcher: "Write"
+ hooks:
+ - type: command
+ command: "bash ${CLAUDE_SKILL_DIR}/../freeze/bin/check-freeze.sh"
+ statusMessage: "Checking debug scope boundary..."
---
{{PREAMBLE}}
@@ 50,6 62,31 @@ Output: **"Root cause hypothesis: ..."** — a specific, testable claim about wh
---
+## Scope Lock
+
+After forming your root cause hypothesis, lock edits to the affected module to prevent scope creep.
+
+```bash
+[ -x "${CLAUDE_SKILL_DIR}/../freeze/bin/check-freeze.sh" ] && echo "FREEZE_AVAILABLE" || echo "FREEZE_UNAVAILABLE"
+```
+
+**If FREEZE_AVAILABLE:** Identify the narrowest directory containing the affected files. Write it to the freeze state file:
+
+```bash
+STATE_DIR="${CLAUDE_PLUGIN_DATA:-$HOME/.gstack}"
+mkdir -p "$STATE_DIR"
+echo "<detected-directory>/" > "$STATE_DIR/freeze-dir.txt"
+echo "Debug scope locked to: <detected-directory>/"
+```
+
+Substitute `<detected-directory>` with the actual directory path (e.g., `src/auth/`). Tell the user: "Edits restricted to `<dir>/` for this debug session. This prevents changes to unrelated code. Run `/unfreeze` to remove the restriction."
+
+If the bug spans the entire repo or the scope is genuinely unclear, skip the lock and note why.
+
+**If FREEZE_UNAVAILABLE:** Skip scope lock. Edits are unrestricted.
+
+---
+
## Phase 2: Pattern Analysis
Check if this bug matches a known pattern:
M design-consultation/SKILL.md => design-consultation/SKILL.md +2 -0
@@ 36,6 36,8 @@ _BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
echo "BRANCH: $_BRANCH"
_LAKE_SEEN=$([ -f ~/.gstack/.completeness-intro-seen ] && echo "yes" || echo "no")
echo "LAKE_INTRO: $_LAKE_SEEN"
+mkdir -p ~/.gstack/analytics
+echo '{"skill":"design-consultation","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
_PROACTIVE=$(~/.claude/skills/gstack/bin/gstack-config get proactive 2>/dev/null || echo "true")
echo "PROACTIVE: $_PROACTIVE"
```
M design-review/SKILL.md => design-review/SKILL.md +2 -0
@@ 36,6 36,8 @@ _BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
echo "BRANCH: $_BRANCH"
_LAKE_SEEN=$([ -f ~/.gstack/.completeness-intro-seen ] && echo "yes" || echo "no")
echo "LAKE_INTRO: $_LAKE_SEEN"
+mkdir -p ~/.gstack/analytics
+echo '{"skill":"design-review","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
_PROACTIVE=$(~/.claude/skills/gstack/bin/gstack-config get proactive 2>/dev/null || echo "true")
echo "PROACTIVE: $_PROACTIVE"
```
M document-release/SKILL.md => document-release/SKILL.md +2 -0
@@ 33,6 33,8 @@ _BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
echo "BRANCH: $_BRANCH"
_LAKE_SEEN=$([ -f ~/.gstack/.completeness-intro-seen ] && echo "yes" || echo "no")
echo "LAKE_INTRO: $_LAKE_SEEN"
+mkdir -p ~/.gstack/analytics
+echo '{"skill":"document-release","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
_PROACTIVE=$(~/.claude/skills/gstack/bin/gstack-config get proactive 2>/dev/null || echo "true")
echo "PROACTIVE: $_PROACTIVE"
```
A freeze/SKILL.md => freeze/SKILL.md +82 -0
@@ 0,0 1,82 @@
+---
+name: freeze
+version: 0.1.0
+description: |
+ Restrict file edits to a specific directory for the session. Blocks Edit and
+ Write outside the allowed path. Use when debugging to prevent accidentally
+ "fixing" unrelated code, or when you want to scope changes to one module.
+ Use when asked to "freeze", "restrict edits", "only edit this folder",
+ or "lock down edits".
+allowed-tools:
+ - Bash
+ - Read
+ - AskUserQuestion
+hooks:
+ PreToolUse:
+ - matcher: "Edit"
+ hooks:
+ - type: command
+ command: "bash ${CLAUDE_SKILL_DIR}/bin/check-freeze.sh"
+ statusMessage: "Checking freeze boundary..."
+ - matcher: "Write"
+ hooks:
+ - type: command
+ command: "bash ${CLAUDE_SKILL_DIR}/bin/check-freeze.sh"
+ statusMessage: "Checking freeze boundary..."
+---
+<!-- AUTO-GENERATED from SKILL.md.tmpl — do not edit directly -->
+<!-- Regenerate: bun run gen:skill-docs -->
+
+# /freeze — Restrict Edits to a Directory
+
+Lock file edits to a specific directory. Any Edit or Write operation targeting
+a file outside the allowed path will be **blocked** (not just warned).
+
+```bash
+mkdir -p ~/.gstack/analytics
+echo '{"skill":"freeze","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
+```
+
+## Setup
+
+Ask the user which directory to restrict edits to. Use AskUserQuestion:
+
+- Question: "Which directory should I restrict edits to? Files outside this path will be blocked from editing."
+- Text input (not multiple choice) — the user types a path.
+
+Once the user provides a directory path:
+
+1. Resolve it to an absolute path:
+```bash
+FREEZE_DIR=$(cd "<user-provided-path>" 2>/dev/null && pwd)
+echo "$FREEZE_DIR"
+```
+
+2. Ensure trailing slash and save to the freeze state file:
+```bash
+FREEZE_DIR="${FREEZE_DIR%/}/"
+STATE_DIR="${CLAUDE_PLUGIN_DATA:-$HOME/.gstack}"
+mkdir -p "$STATE_DIR"
+echo "$FREEZE_DIR" > "$STATE_DIR/freeze-dir.txt"
+echo "Freeze boundary set: $FREEZE_DIR"
+```
+
+Tell the user: "Edits are now restricted to `<path>/`. Any Edit or Write
+outside this directory will be blocked. To change the boundary, run `/freeze`
+again. To remove it, run `/unfreeze` or end the session."
+
+## How it works
+
+The hook reads `file_path` from the Edit/Write tool input JSON, then checks
+whether the path starts with the freeze directory. If not, it returns
+`permissionDecision: "deny"` to block the operation.
+
+The freeze boundary persists for the session via the state file. The hook
+script reads it on every Edit/Write invocation.
+
+## Notes
+
+- The trailing `/` on the freeze directory prevents `/src` from matching `/src-old`
+- Freeze applies to Edit and Write tools only — Read, Bash, Glob, Grep are unaffected
+- This prevents accidental edits, not a security boundary — Bash commands like `sed` can still modify files outside the boundary
+- To deactivate, run `/unfreeze` or end the conversation
A freeze/SKILL.md.tmpl => freeze/SKILL.md.tmpl +80 -0
@@ 0,0 1,80 @@
+---
+name: freeze
+version: 0.1.0
+description: |
+ Restrict file edits to a specific directory for the session. Blocks Edit and
+ Write outside the allowed path. Use when debugging to prevent accidentally
+ "fixing" unrelated code, or when you want to scope changes to one module.
+ Use when asked to "freeze", "restrict edits", "only edit this folder",
+ or "lock down edits".
+allowed-tools:
+ - Bash
+ - Read
+ - AskUserQuestion
+hooks:
+ PreToolUse:
+ - matcher: "Edit"
+ hooks:
+ - type: command
+ command: "bash ${CLAUDE_SKILL_DIR}/bin/check-freeze.sh"
+ statusMessage: "Checking freeze boundary..."
+ - matcher: "Write"
+ hooks:
+ - type: command
+ command: "bash ${CLAUDE_SKILL_DIR}/bin/check-freeze.sh"
+ statusMessage: "Checking freeze boundary..."
+---
+
+# /freeze — Restrict Edits to a Directory
+
+Lock file edits to a specific directory. Any Edit or Write operation targeting
+a file outside the allowed path will be **blocked** (not just warned).
+
+```bash
+mkdir -p ~/.gstack/analytics
+echo '{"skill":"freeze","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
+```
+
+## Setup
+
+Ask the user which directory to restrict edits to. Use AskUserQuestion:
+
+- Question: "Which directory should I restrict edits to? Files outside this path will be blocked from editing."
+- Text input (not multiple choice) — the user types a path.
+
+Once the user provides a directory path:
+
+1. Resolve it to an absolute path:
+```bash
+FREEZE_DIR=$(cd "<user-provided-path>" 2>/dev/null && pwd)
+echo "$FREEZE_DIR"
+```
+
+2. Ensure trailing slash and save to the freeze state file:
+```bash
+FREEZE_DIR="${FREEZE_DIR%/}/"
+STATE_DIR="${CLAUDE_PLUGIN_DATA:-$HOME/.gstack}"
+mkdir -p "$STATE_DIR"
+echo "$FREEZE_DIR" > "$STATE_DIR/freeze-dir.txt"
+echo "Freeze boundary set: $FREEZE_DIR"
+```
+
+Tell the user: "Edits are now restricted to `<path>/`. Any Edit or Write
+outside this directory will be blocked. To change the boundary, run `/freeze`
+again. To remove it, run `/unfreeze` or end the session."
+
+## How it works
+
+The hook reads `file_path` from the Edit/Write tool input JSON, then checks
+whether the path starts with the freeze directory. If not, it returns
+`permissionDecision: "deny"` to block the operation.
+
+The freeze boundary persists for the session via the state file. The hook
+script reads it on every Edit/Write invocation.
+
+## Notes
+
+- The trailing `/` on the freeze directory prevents `/src` from matching `/src-old`
+- Freeze applies to Edit and Write tools only — Read, Bash, Glob, Grep are unaffected
+- This prevents accidental edits, not a security boundary — Bash commands like `sed` can still modify files outside the boundary
+- To deactivate, run `/unfreeze` or end the conversation
A freeze/bin/check-freeze.sh => freeze/bin/check-freeze.sh +68 -0
@@ 0,0 1,68 @@
+#!/usr/bin/env bash
+# check-freeze.sh — PreToolUse hook for /freeze skill
+# Reads JSON from stdin, checks if file_path is within the freeze boundary.
+# Returns {"permissionDecision":"deny","message":"..."} to block, or {} to allow.
+set -euo pipefail
+
+# Read stdin
+INPUT=$(cat)
+
+# Locate the freeze directory state file
+STATE_DIR="${CLAUDE_PLUGIN_DATA:-$HOME/.gstack}"
+FREEZE_FILE="$STATE_DIR/freeze-dir.txt"
+
+# If no freeze file exists, allow everything (not yet configured)
+if [ ! -f "$FREEZE_FILE" ]; then
+ echo '{}'
+ exit 0
+fi
+
+FREEZE_DIR=$(tr -d '[:space:]' < "$FREEZE_FILE")
+
+# If freeze dir is empty, allow
+if [ -z "$FREEZE_DIR" ]; then
+ echo '{}'
+ exit 0
+fi
+
+# Extract file_path from tool_input JSON
+# Try grep/sed first, fall back to Python for escaped quotes
+FILE_PATH=$(printf '%s' "$INPUT" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*:[[:space:]]*"//;s/"$//' || true)
+
+# Python fallback if grep returned empty
+if [ -z "$FILE_PATH" ]; then
+ FILE_PATH=$(printf '%s' "$INPUT" | python3 -c 'import sys,json; print(json.loads(sys.stdin.read()).get("tool_input",{}).get("file_path",""))' 2>/dev/null || true)
+fi
+
+# If we couldn't extract a file path, allow (don't block on parse failure)
+if [ -z "$FILE_PATH" ]; then
+ echo '{}'
+ exit 0
+fi
+
+# Resolve file_path to absolute if it isn't already
+case "$FILE_PATH" in
+ /*) ;; # already absolute
+ *)
+ FILE_PATH="$(pwd)/$FILE_PATH"
+ ;;
+esac
+
+# Normalize: remove double slashes and trailing slash
+FILE_PATH=$(printf '%s' "$FILE_PATH" | sed 's|/\+|/|g;s|/$||')
+
+# Check: does the file path start with the freeze directory?
+case "$FILE_PATH" in
+ "${FREEZE_DIR}"*)
+ # Inside freeze boundary — allow
+ echo '{}'
+ ;;
+ *)
+ # Outside freeze boundary — deny
+ # Log hook fire event
+ mkdir -p ~/.gstack/analytics 2>/dev/null || true
+ echo '{"event":"hook_fire","skill":"freeze","pattern":"boundary_deny","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
+
+ printf '{"permissionDecision":"deny","message":"[freeze] Blocked: %s is outside the freeze boundary (%s). Only edits within the frozen directory are allowed."}\n' "$FILE_PATH" "$FREEZE_DIR"
+ ;;
+esac
A guard/SKILL.md => guard/SKILL.md +82 -0
@@ 0,0 1,82 @@
+---
+name: guard
+version: 0.1.0
+description: |
+ Full safety mode: destructive command warnings + directory-scoped edits.
+ Combines /careful (warns before rm -rf, DROP TABLE, force-push, etc.) with
+ /freeze (blocks edits outside a specified directory). Use for maximum safety
+ when touching prod or debugging live systems. Use when asked to "guard mode",
+ "full safety", "lock it down", or "maximum safety".
+allowed-tools:
+ - Bash
+ - Read
+ - AskUserQuestion
+hooks:
+ PreToolUse:
+ - matcher: "Bash"
+ hooks:
+ - type: command
+ command: "bash ${CLAUDE_SKILL_DIR}/../careful/bin/check-careful.sh"
+ statusMessage: "Checking for destructive commands..."
+ - matcher: "Edit"
+ hooks:
+ - type: command
+ command: "bash ${CLAUDE_SKILL_DIR}/../freeze/bin/check-freeze.sh"
+ statusMessage: "Checking freeze boundary..."
+ - matcher: "Write"
+ hooks:
+ - type: command
+ command: "bash ${CLAUDE_SKILL_DIR}/../freeze/bin/check-freeze.sh"
+ statusMessage: "Checking freeze boundary..."
+---
+<!-- AUTO-GENERATED from SKILL.md.tmpl — do not edit directly -->
+<!-- Regenerate: bun run gen:skill-docs -->
+
+# /guard — Full Safety Mode
+
+Activates both destructive command warnings and directory-scoped edit restrictions.
+This is the combination of `/careful` + `/freeze` in a single command.
+
+**Dependency note:** This skill references hook scripts from the sibling `/careful`
+and `/freeze` skill directories. Both must be installed (they are installed together
+by the gstack setup script).
+
+```bash
+mkdir -p ~/.gstack/analytics
+echo '{"skill":"guard","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
+```
+
+## Setup
+
+Ask the user which directory to restrict edits to. Use AskUserQuestion:
+
+- Question: "Guard mode: which directory should edits be restricted to? Destructive command warnings are always on. Files outside the chosen path will be blocked from editing."
+- Text input (not multiple choice) — the user types a path.
+
+Once the user provides a directory path:
+
+1. Resolve it to an absolute path:
+```bash
+FREEZE_DIR=$(cd "<user-provided-path>" 2>/dev/null && pwd)
+echo "$FREEZE_DIR"
+```
+
+2. Ensure trailing slash and save to the freeze state file:
+```bash
+FREEZE_DIR="${FREEZE_DIR%/}/"
+STATE_DIR="${CLAUDE_PLUGIN_DATA:-$HOME/.gstack}"
+mkdir -p "$STATE_DIR"
+echo "$FREEZE_DIR" > "$STATE_DIR/freeze-dir.txt"
+echo "Freeze boundary set: $FREEZE_DIR"
+```
+
+Tell the user:
+- "**Guard mode active.** Two protections are now running:"
+- "1. **Destructive command warnings** — rm -rf, DROP TABLE, force-push, etc. will warn before executing (you can override)"
+- "2. **Edit boundary** — file edits restricted to `<path>/`. Edits outside this directory are blocked."
+- "To remove the edit boundary, run `/unfreeze`. To deactivate everything, end the session."
+
+## What's protected
+
+See `/careful` for the full list of destructive command patterns and safe exceptions.
+See `/freeze` for how edit boundary enforcement works.
A guard/SKILL.md.tmpl => guard/SKILL.md.tmpl +80 -0
@@ 0,0 1,80 @@
+---
+name: guard
+version: 0.1.0
+description: |
+ Full safety mode: destructive command warnings + directory-scoped edits.
+ Combines /careful (warns before rm -rf, DROP TABLE, force-push, etc.) with
+ /freeze (blocks edits outside a specified directory). Use for maximum safety
+ when touching prod or debugging live systems. Use when asked to "guard mode",
+ "full safety", "lock it down", or "maximum safety".
+allowed-tools:
+ - Bash
+ - Read
+ - AskUserQuestion
+hooks:
+ PreToolUse:
+ - matcher: "Bash"
+ hooks:
+ - type: command
+ command: "bash ${CLAUDE_SKILL_DIR}/../careful/bin/check-careful.sh"
+ statusMessage: "Checking for destructive commands..."
+ - matcher: "Edit"
+ hooks:
+ - type: command
+ command: "bash ${CLAUDE_SKILL_DIR}/../freeze/bin/check-freeze.sh"
+ statusMessage: "Checking freeze boundary..."
+ - matcher: "Write"
+ hooks:
+ - type: command
+ command: "bash ${CLAUDE_SKILL_DIR}/../freeze/bin/check-freeze.sh"
+ statusMessage: "Checking freeze boundary..."
+---
+
+# /guard — Full Safety Mode
+
+Activates both destructive command warnings and directory-scoped edit restrictions.
+This is the combination of `/careful` + `/freeze` in a single command.
+
+**Dependency note:** This skill references hook scripts from the sibling `/careful`
+and `/freeze` skill directories. Both must be installed (they are installed together
+by the gstack setup script).
+
+```bash
+mkdir -p ~/.gstack/analytics
+echo '{"skill":"guard","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
+```
+
+## Setup
+
+Ask the user which directory to restrict edits to. Use AskUserQuestion:
+
+- Question: "Guard mode: which directory should edits be restricted to? Destructive command warnings are always on. Files outside the chosen path will be blocked from editing."
+- Text input (not multiple choice) — the user types a path.
+
+Once the user provides a directory path:
+
+1. Resolve it to an absolute path:
+```bash
+FREEZE_DIR=$(cd "<user-provided-path>" 2>/dev/null && pwd)
+echo "$FREEZE_DIR"
+```
+
+2. Ensure trailing slash and save to the freeze state file:
+```bash
+FREEZE_DIR="${FREEZE_DIR%/}/"
+STATE_DIR="${CLAUDE_PLUGIN_DATA:-$HOME/.gstack}"
+mkdir -p "$STATE_DIR"
+echo "$FREEZE_DIR" > "$STATE_DIR/freeze-dir.txt"
+echo "Freeze boundary set: $FREEZE_DIR"
+```
+
+Tell the user:
+- "**Guard mode active.** Two protections are now running:"
+- "1. **Destructive command warnings** — rm -rf, DROP TABLE, force-push, etc. will warn before executing (you can override)"
+- "2. **Edit boundary** — file edits restricted to `<path>/`. Edits outside this directory are blocked."
+- "To remove the edit boundary, run `/unfreeze`. To deactivate everything, end the session."
+
+## What's protected
+
+See `/careful` for the full list of destructive command patterns and safe exceptions.
+See `/freeze` for how edit boundary enforcement works.
M office-hours/SKILL.md => office-hours/SKILL.md +2 -0
@@ 37,6 37,8 @@ _BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
echo "BRANCH: $_BRANCH"
_LAKE_SEEN=$([ -f ~/.gstack/.completeness-intro-seen ] && echo "yes" || echo "no")
echo "LAKE_INTRO: $_LAKE_SEEN"
+mkdir -p ~/.gstack/analytics
+echo '{"skill":"office-hours","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
_PROACTIVE=$(~/.claude/skills/gstack/bin/gstack-config get proactive 2>/dev/null || echo "true")
echo "PROACTIVE: $_PROACTIVE"
```
M package.json => package.json +2 -1
@@ 24,7 24,8 @@
"eval:compare": "bun run scripts/eval-compare.ts",
"eval:summary": "bun run scripts/eval-summary.ts",
"eval:watch": "bun run scripts/eval-watch.ts",
- "eval:select": "bun run scripts/eval-select.ts"
+ "eval:select": "bun run scripts/eval-select.ts",
+ "analytics": "bun run scripts/analytics.ts"
},
"dependencies": {
"playwright": "^1.58.2",
M plan-ceo-review/SKILL.md => plan-ceo-review/SKILL.md +2 -0
@@ 34,6 34,8 @@ _BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
echo "BRANCH: $_BRANCH"
_LAKE_SEEN=$([ -f ~/.gstack/.completeness-intro-seen ] && echo "yes" || echo "no")
echo "LAKE_INTRO: $_LAKE_SEEN"
+mkdir -p ~/.gstack/analytics
+echo '{"skill":"plan-ceo-review","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
_PROACTIVE=$(~/.claude/skills/gstack/bin/gstack-config get proactive 2>/dev/null || echo "true")
echo "PROACTIVE: $_PROACTIVE"
```
M plan-design-review/SKILL.md => plan-design-review/SKILL.md +2 -0
@@ 34,6 34,8 @@ _BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
echo "BRANCH: $_BRANCH"
_LAKE_SEEN=$([ -f ~/.gstack/.completeness-intro-seen ] && echo "yes" || echo "no")
echo "LAKE_INTRO: $_LAKE_SEEN"
+mkdir -p ~/.gstack/analytics
+echo '{"skill":"plan-design-review","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
_PROACTIVE=$(~/.claude/skills/gstack/bin/gstack-config get proactive 2>/dev/null || echo "true")
echo "PROACTIVE: $_PROACTIVE"
```
M plan-eng-review/SKILL.md => plan-eng-review/SKILL.md +2 -0
@@ 33,6 33,8 @@ _BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
echo "BRANCH: $_BRANCH"
_LAKE_SEEN=$([ -f ~/.gstack/.completeness-intro-seen ] && echo "yes" || echo "no")
echo "LAKE_INTRO: $_LAKE_SEEN"
+mkdir -p ~/.gstack/analytics
+echo '{"skill":"plan-eng-review","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
_PROACTIVE=$(~/.claude/skills/gstack/bin/gstack-config get proactive 2>/dev/null || echo "true")
echo "PROACTIVE: $_PROACTIVE"
```
M qa-only/SKILL.md => qa-only/SKILL.md +2 -0
@@ 30,6 30,8 @@ _BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
echo "BRANCH: $_BRANCH"
_LAKE_SEEN=$([ -f ~/.gstack/.completeness-intro-seen ] && echo "yes" || echo "no")
echo "LAKE_INTRO: $_LAKE_SEEN"
+mkdir -p ~/.gstack/analytics
+echo '{"skill":"qa-only","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
_PROACTIVE=$(~/.claude/skills/gstack/bin/gstack-config get proactive 2>/dev/null || echo "true")
echo "PROACTIVE: $_PROACTIVE"
```
M qa/SKILL.md => qa/SKILL.md +2 -0
@@ 37,6 37,8 @@ _BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
echo "BRANCH: $_BRANCH"
_LAKE_SEEN=$([ -f ~/.gstack/.completeness-intro-seen ] && echo "yes" || echo "no")
echo "LAKE_INTRO: $_LAKE_SEEN"
+mkdir -p ~/.gstack/analytics
+echo '{"skill":"qa","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
_PROACTIVE=$(~/.claude/skills/gstack/bin/gstack-config get proactive 2>/dev/null || echo "true")
echo "PROACTIVE: $_PROACTIVE"
```
M retro/SKILL.md => retro/SKILL.md +10 -0
@@ 31,6 31,8 @@ _BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
echo "BRANCH: $_BRANCH"
_LAKE_SEEN=$([ -f ~/.gstack/.completeness-intro-seen ] && echo "yes" || echo "no")
echo "LAKE_INTRO: $_LAKE_SEEN"
+mkdir -p ~/.gstack/analytics
+echo '{"skill":"retro","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
_PROACTIVE=$(~/.claude/skills/gstack/bin/gstack-config get proactive 2>/dev/null || echo "true")
echo "PROACTIVE: $_PROACTIVE"
```
@@ 295,6 297,14 @@ Include in the metrics table:
If TODOS.md doesn't exist, skip the Backlog Health row.
+**Skill Usage (if analytics exist):** Read `~/.gstack/analytics/skill-usage.jsonl` if it exists. Filter entries within the retro time window by `ts` field. Separate skill activations (no `event` field) from hook fires (`event: "hook_fire"`). Aggregate by skill name. Present as:
+
+```
+| Skill Usage | /ship(12) /qa(8) /review(5) · 3 safety hook fires |
+```
+
+If the JSONL file doesn't exist or has no entries in the window, skip the Skill Usage row.
+
### Step 3: Commit Time Distribution
Show hourly histogram in local time using bar chart:
M retro/SKILL.md.tmpl => retro/SKILL.md.tmpl +8 -0
@@ 161,6 161,14 @@ Include in the metrics table:
If TODOS.md doesn't exist, skip the Backlog Health row.
+**Skill Usage (if analytics exist):** Read `~/.gstack/analytics/skill-usage.jsonl` if it exists. Filter entries within the retro time window by `ts` field. Separate skill activations (no `event` field) from hook fires (`event: "hook_fire"`). Aggregate by skill name. Present as:
+
+```
+| Skill Usage | /ship(12) /qa(8) /review(5) · 3 safety hook fires |
+```
+
+If the JSONL file doesn't exist or has no entries in the window, skip the Skill Usage row.
+
### Step 3: Commit Time Distribution
Show hourly histogram in local time using bar chart:
M review/SKILL.md => review/SKILL.md +2 -0
@@ 32,6 32,8 @@ _BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
echo "BRANCH: $_BRANCH"
_LAKE_SEEN=$([ -f ~/.gstack/.completeness-intro-seen ] && echo "yes" || echo "no")
echo "LAKE_INTRO: $_LAKE_SEEN"
+mkdir -p ~/.gstack/analytics
+echo '{"skill":"review","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
_PROACTIVE=$(~/.claude/skills/gstack/bin/gstack-config get proactive 2>/dev/null || echo "true")
echo "PROACTIVE: $_PROACTIVE"
```
A scripts/analytics.ts => scripts/analytics.ts +190 -0
@@ 0,0 1,190 @@
+#!/usr/bin/env bun
+/**
+ * analytics — CLI for viewing gstack skill usage statistics.
+ *
+ * Reads ~/.gstack/analytics/skill-usage.jsonl and displays:
+ * - Top skills by invocation count
+ * - Per-repo skill breakdown
+ * - Safety hook fire events
+ *
+ * Usage:
+ * bun run scripts/analytics.ts [--period 7d|30d|all]
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+export interface AnalyticsEvent {
+ skill: string;
+ ts: string;
+ repo: string;
+ event?: string;
+ pattern?: string;
+}
+
+const ANALYTICS_FILE = path.join(os.homedir(), '.gstack', 'analytics', 'skill-usage.jsonl');
+
+/**
+ * Parse JSONL content into AnalyticsEvent[], skipping malformed lines.
+ */
+export function parseJSONL(content: string): AnalyticsEvent[] {
+ const events: AnalyticsEvent[] = [];
+ for (const line of content.split('\n')) {
+ const trimmed = line.trim();
+ if (!trimmed) continue;
+ try {
+ const obj = JSON.parse(trimmed);
+ if (typeof obj === 'object' && obj !== null && typeof obj.ts === 'string') {
+ events.push(obj as AnalyticsEvent);
+ }
+ } catch {
+ // skip malformed lines
+ }
+ }
+ return events;
+}
+
+/**
+ * Filter events by period. Supports "7d", "30d", and "all".
+ */
+export function filterByPeriod(events: AnalyticsEvent[], period: string): AnalyticsEvent[] {
+ if (period === 'all') return events;
+
+ const match = period.match(/^(\d+)d$/);
+ if (!match) return events;
+
+ const days = parseInt(match[1], 10);
+ const cutoff = new Date(Date.now() - days * 24 * 60 * 60 * 1000);
+
+ return events.filter(e => {
+ const d = new Date(e.ts);
+ return !isNaN(d.getTime()) && d >= cutoff;
+ });
+}
+
+/**
+ * Format a report string from a list of events.
+ */
+export function formatReport(events: AnalyticsEvent[], period: string = 'all'): string {
+ const skillEvents = events.filter(e => e.event !== 'hook_fire');
+ const hookEvents = events.filter(e => e.event === 'hook_fire');
+
+ const lines: string[] = [];
+ lines.push('gstack skill usage analytics');
+ lines.push('\u2550'.repeat(39));
+ lines.push('');
+
+ const periodLabel = period === 'all' ? 'all time' : `last ${period.replace('d', ' days')}`;
+ lines.push(`Period: ${periodLabel}`);
+
+ // Top Skills
+ const skillCounts = new Map<string, number>();
+ for (const e of skillEvents) {
+ skillCounts.set(e.skill, (skillCounts.get(e.skill) || 0) + 1);
+ }
+
+ if (skillCounts.size > 0) {
+ lines.push('');
+ lines.push('Top Skills');
+
+ const sorted = [...skillCounts.entries()].sort((a, b) => b[1] - a[1]);
+ const maxName = Math.max(...sorted.map(([name]) => name.length + 1)); // +1 for /
+ const maxCount = Math.max(...sorted.map(([, count]) => String(count).length));
+
+ for (const [name, count] of sorted) {
+ const label = `/${name}`;
+ const suffix = `${count} invocation${count === 1 ? '' : 's'}`;
+ const dotLen = Math.max(2, 25 - label.length - suffix.length);
+ const dots = ' ' + '.'.repeat(dotLen) + ' ';
+ lines.push(` ${label}${dots}${suffix}`);
+ }
+ }
+
+ // By Repo
+ const repoSkills = new Map<string, Map<string, number>>();
+ for (const e of skillEvents) {
+ if (!repoSkills.has(e.repo)) repoSkills.set(e.repo, new Map());
+ const m = repoSkills.get(e.repo)!;
+ m.set(e.skill, (m.get(e.skill) || 0) + 1);
+ }
+
+ if (repoSkills.size > 0) {
+ lines.push('');
+ lines.push('By Repo');
+
+ const sortedRepos = [...repoSkills.entries()].sort((a, b) => a[0].localeCompare(b[0]));
+ for (const [repo, skills] of sortedRepos) {
+ const parts = [...skills.entries()]
+ .sort((a, b) => b[1] - a[1])
+ .map(([s, c]) => `${s}(${c})`);
+ lines.push(` ${repo}: ${parts.join(' ')}`);
+ }
+ }
+
+ // Safety Hook Events
+ const hookCounts = new Map<string, number>();
+ for (const e of hookEvents) {
+ if (e.pattern) {
+ hookCounts.set(e.pattern, (hookCounts.get(e.pattern) || 0) + 1);
+ }
+ }
+
+ if (hookCounts.size > 0) {
+ lines.push('');
+ lines.push('Safety Hook Events');
+
+ const sortedHooks = [...hookCounts.entries()].sort((a, b) => b[1] - a[1]);
+ for (const [pattern, count] of sortedHooks) {
+ const suffix = `${count} fire${count === 1 ? '' : 's'}`;
+ const dotLen = Math.max(2, 25 - pattern.length - suffix.length);
+ const dots = ' ' + '.'.repeat(dotLen) + ' ';
+ lines.push(` ${pattern}${dots}${suffix}`);
+ }
+ }
+
+ // Total
+ const totalSkills = skillEvents.length;
+ const totalHooks = hookEvents.length;
+ lines.push('');
+ lines.push(`Total: ${totalSkills} skill invocation${totalSkills === 1 ? '' : 's'}, ${totalHooks} hook fire${totalHooks === 1 ? '' : 's'}`);
+
+ return lines.join('\n');
+}
+
+function main() {
+ // Parse --period flag
+ let period = 'all';
+ const args = process.argv.slice(2);
+ for (let i = 0; i < args.length; i++) {
+ if (args[i] === '--period' && i + 1 < args.length) {
+ period = args[i + 1];
+ i++;
+ }
+ }
+
+ // Read file
+ if (!fs.existsSync(ANALYTICS_FILE)) {
+ console.log('No analytics data found.');
+ process.exit(0);
+ }
+
+ const content = fs.readFileSync(ANALYTICS_FILE, 'utf-8').trim();
+ if (!content) {
+ console.log('No analytics data found.');
+ process.exit(0);
+ }
+
+ const events = parseJSONL(content);
+ if (events.length === 0) {
+ console.log('No analytics data found.');
+ process.exit(0);
+ }
+
+ const filtered = filterByPeriod(events, period);
+ console.log(formatReport(filtered, period));
+}
+
+if (import.meta.main) {
+ main();
+}
M scripts/gen-skill-docs.ts => scripts/gen-skill-docs.ts +30 -12
@@ 17,9 17,16 @@ import * as path from 'path';
const ROOT = path.resolve(import.meta.dir, '..');
const DRY_RUN = process.argv.includes('--dry-run');
+// ─── Template Context ───────────────────────────────────────
+
+interface TemplateContext {
+ skillName: string;
+ tmplPath: string;
+}
+
// ─── Placeholder Resolvers ──────────────────────────────────
-function generateCommandReference(): string {
+function generateCommandReference(_ctx: TemplateContext): string {
// Group commands by category
const groups = new Map<string, Array<{ command: string; description: string; usage?: string }>>();
for (const [cmd, meta] of Object.entries(COMMAND_DESCRIPTIONS)) {
@@ 55,7 62,7 @@ function generateCommandReference(): string {
return sections.join('\n').trimEnd();
}
-function generateSnapshotFlags(): string {
+function generateSnapshotFlags(_ctx: TemplateContext): string {
const lines: string[] = [
'The snapshot is your primary tool for understanding and interacting with pages.',
'',
@@ 94,7 101,7 @@ function generateSnapshotFlags(): string {
return lines.join('\n');
}
-function generatePreamble(): string {
+function generatePreamble(ctx: TemplateContext): string {
return `## Preamble (run first)
\`\`\`bash
@@ 109,6 116,8 @@ _BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
echo "BRANCH: $_BRANCH"
_LAKE_SEEN=$([ -f ~/.gstack/.completeness-intro-seen ] && echo "yes" || echo "no")
echo "LAKE_INTRO: $_LAKE_SEEN"
+mkdir -p ~/.gstack/analytics
+echo '{"skill":"${ctx.skillName}","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
_PROACTIVE=$(~/.claude/skills/gstack/bin/gstack-config get proactive 2>/dev/null || echo "true")
echo "PROACTIVE: $_PROACTIVE"
\`\`\`
@@ 230,7 239,7 @@ RECOMMENDATION: [what the user should do next]
\`\`\``;
}
-function generateBrowseSetup(): string {
+function generateBrowseSetup(_ctx: TemplateContext): string {
return `## SETUP (run this check BEFORE any browse command)
\`\`\`bash
@@ 251,7 260,7 @@ If \`NEEDS_SETUP\`:
3. If \`bun\` is not installed: \`curl -fsSL https://bun.sh/install | bash\``;
}
-function generateBaseBranchDetect(): string {
+function generateBaseBranchDetect(_ctx: TemplateContext): string {
return `## Step 0: Detect base branch
Determine which branch this PR targets. Use the result as "the base branch" in all subsequent steps.
@@ 272,7 281,7 @@ branch name wherever the instructions say "the base branch."
---`;
}
-function generateQAMethodology(): string {
+function generateQAMethodology(_ctx: TemplateContext): string {
return `## Modes
### Diff-aware (automatic when on a feature branch with no URL)
@@ 549,7 558,7 @@ Minimum 0 per category.
11. **Show screenshots to the user.** After every \`$B screenshot\`, \`$B snapshot -a -o\`, or \`$B responsive\` command, use the Read tool on the output file(s) so the user can see them inline. For \`responsive\` (3 files), Read all three. This is critical — without it, screenshots are invisible to the user.`;
}
-function generateDesignReviewLite(): string {
+function generateDesignReviewLite(_ctx: TemplateContext): string {
return `## Design Review (conditional, diff-scoped)
Check if the diff touches frontend files using \`gstack-diff-scope\`:
@@ 588,7 597,7 @@ Substitute: TIMESTAMP = ISO 8601 datetime, STATUS = "clean" if 0 findings or "is
// NOTE: design-checklist.md is a subset of this methodology for code-level detection.
// When adding items here, also update review/design-checklist.md, and vice versa.
-function generateDesignMethodology(): string {
+function generateDesignMethodology(_ctx: TemplateContext): string {
return `## Modes
### Full (default)
@@ 922,7 931,7 @@ Tie everything to user goals and product objectives. Always suggest specific imp
11. **Show screenshots to the user.** After every \`$B screenshot\`, \`$B snapshot -a -o\`, or \`$B responsive\` command, use the Read tool on the output file(s) so the user can see them inline. For \`responsive\` (3 files), Read all three. This is critical — without it, screenshots are invisible to the user.`;
}
-function generateReviewDashboard(): string {
+function generateReviewDashboard(_ctx: TemplateContext): string {
return `## Review Readiness Dashboard
After completing the review, read the review log and config to display the dashboard.
@@ 962,7 971,7 @@ Parse the output. Find the most recent entry for each skill (plan-ceo-review, pl
- If \\\`skip_eng_review\\\` config is \\\`true\\\`, Eng Review shows "SKIPPED (global)" and verdict is CLEARED`;
}
-function generateTestBootstrap(): string {
+function generateTestBootstrap(_ctx: TemplateContext): string {
return `## Test Framework Bootstrap
**Detect existing test framework and project runtime:**
@@ 1117,7 1126,7 @@ Only commit if there are changes. Stage all bootstrap files (config, test direct
---`;
}
-const RESOLVERS: Record<string, () => string> = {
+const RESOLVERS: Record<string, (ctx: TemplateContext) => string> = {
COMMAND_REFERENCE: generateCommandReference,
SNAPSHOT_FLAGS: generateSnapshotFlags,
PREAMBLE: generatePreamble,
@@ 1139,11 1148,16 @@ function processTemplate(tmplPath: string): { outputPath: string; content: strin
const relTmplPath = path.relative(ROOT, tmplPath);
const outputPath = tmplPath.replace(/\.tmpl$/, '');
+ // Extract skill name from frontmatter for TemplateContext
+ const nameMatch = tmplContent.match(/^name:\s*(.+)$/m);
+ const skillName = nameMatch ? nameMatch[1].trim() : path.basename(path.dirname(tmplPath));
+ const ctx: TemplateContext = { skillName, tmplPath };
+
// Replace placeholders
let content = tmplContent.replace(/\{\{(\w+)\}\}/g, (match, name) => {
const resolver = RESOLVERS[name];
if (!resolver) throw new Error(`Unknown placeholder {{${name}}} in ${relTmplPath}`);
- return resolver();
+ return resolver(ctx);
});
// Check for any remaining unresolved placeholders
@@ 1187,6 1201,10 @@ function findTemplates(): string[] {
path.join(ROOT, 'design-review', 'SKILL.md.tmpl'),
path.join(ROOT, 'design-consultation', 'SKILL.md.tmpl'),
path.join(ROOT, 'document-release', 'SKILL.md.tmpl'),
+ path.join(ROOT, 'careful', 'SKILL.md.tmpl'),
+ path.join(ROOT, 'freeze', 'SKILL.md.tmpl'),
+ path.join(ROOT, 'guard', 'SKILL.md.tmpl'),
+ path.join(ROOT, 'unfreeze', 'SKILL.md.tmpl'),
];
for (const p of candidates) {
if (fs.existsSync(p)) templates.push(p);
M setup-browser-cookies/SKILL.md => setup-browser-cookies/SKILL.md +2 -0
@@ 28,6 28,8 @@ _BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
echo "BRANCH: $_BRANCH"
_LAKE_SEEN=$([ -f ~/.gstack/.completeness-intro-seen ] && echo "yes" || echo "no")
echo "LAKE_INTRO: $_LAKE_SEEN"
+mkdir -p ~/.gstack/analytics
+echo '{"skill":"setup-browser-cookies","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
_PROACTIVE=$(~/.claude/skills/gstack/bin/gstack-config get proactive 2>/dev/null || echo "true")
echo "PROACTIVE: $_PROACTIVE"
```
M ship/SKILL.md => ship/SKILL.md +2 -0
@@ 31,6 31,8 @@ _BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
echo "BRANCH: $_BRANCH"
_LAKE_SEEN=$([ -f ~/.gstack/.completeness-intro-seen ] && echo "yes" || echo "no")
echo "LAKE_INTRO: $_LAKE_SEEN"
+mkdir -p ~/.gstack/analytics
+echo '{"skill":"ship","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
_PROACTIVE=$(~/.claude/skills/gstack/bin/gstack-config get proactive 2>/dev/null || echo "true")
echo "PROACTIVE: $_PROACTIVE"
```
A test/analytics.test.ts => test/analytics.test.ts +277 -0
@@ 0,0 1,277 @@
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
+import { parseJSONL, filterByPeriod, formatReport } from '../scripts/analytics';
+import type { AnalyticsEvent } from '../scripts/analytics';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { execSync } from 'child_process';
+
+const TMP_DIR = path.join(os.tmpdir(), 'analytics-test');
+const SCRIPT = path.resolve(import.meta.dir, '../scripts/analytics.ts');
+
+function writeTempJSONL(name: string, lines: string[]): string {
+ fs.mkdirSync(TMP_DIR, { recursive: true });
+ const p = path.join(TMP_DIR, name);
+ fs.writeFileSync(p, lines.join('\n') + '\n');
+ return p;
+}
+
+/**
+ * Run the analytics script with a custom JSONL file by overriding the path.
+ * We test the exported functions directly for unit tests, and use this
+ * helper for integration-style checks.
+ */
+function runScript(jsonlPath: string | null, extraArgs: string = ''): string {
+ // We test via the exported functions; for CLI integration we read the file
+ // and run the pipeline manually to avoid needing to override the hardcoded path.
+ if (jsonlPath === null) {
+ return 'No analytics data found.';
+ }
+ if (!fs.existsSync(jsonlPath)) {
+ return 'No analytics data found.';
+ }
+ const content = fs.readFileSync(jsonlPath, 'utf-8').trim();
+ if (!content) {
+ return 'No analytics data found.';
+ }
+ const events = parseJSONL(content);
+ if (events.length === 0) {
+ return 'No analytics data found.';
+ }
+ // Parse period from extraArgs
+ let period = 'all';
+ const match = extraArgs.match(/--period\s+(\S+)/);
+ if (match) period = match[1];
+ const filtered = filterByPeriod(events, period);
+ return formatReport(filtered, period);
+}
+
+beforeEach(() => {
+ fs.mkdirSync(TMP_DIR, { recursive: true });
+});
+
+afterEach(() => {
+ fs.rmSync(TMP_DIR, { recursive: true, force: true });
+});
+
+describe('parseJSONL', () => {
+ test('parses valid JSONL lines', () => {
+ const content = [
+ '{"skill":"ship","ts":"2026-03-18T15:30:00Z","repo":"my-app"}',
+ '{"skill":"qa","ts":"2026-03-18T16:00:00Z","repo":"my-api"}',
+ ].join('\n');
+ const events = parseJSONL(content);
+ expect(events).toHaveLength(2);
+ expect(events[0].skill).toBe('ship');
+ expect(events[1].skill).toBe('qa');
+ });
+
+ test('skips malformed lines', () => {
+ const content = [
+ '{"skill":"ship","ts":"2026-03-18T15:30:00Z","repo":"my-app"}',
+ 'not valid json',
+ '{broken',
+ '',
+ '{"skill":"qa","ts":"2026-03-18T16:00:00Z","repo":"my-api"}',
+ ].join('\n');
+ const events = parseJSONL(content);
+ expect(events).toHaveLength(2);
+ expect(events[0].skill).toBe('ship');
+ expect(events[1].skill).toBe('qa');
+ });
+
+ test('returns empty array for empty string', () => {
+ expect(parseJSONL('')).toHaveLength(0);
+ });
+
+ test('skips objects missing ts field', () => {
+ const content = '{"skill":"ship","repo":"my-app"}\n';
+ const events = parseJSONL(content);
+ expect(events).toHaveLength(0);
+ });
+});
+
+describe('filterByPeriod', () => {
+ const now = new Date();
+ const daysAgo = (n: number) => new Date(now.getTime() - n * 24 * 60 * 60 * 1000).toISOString();
+
+ const events: AnalyticsEvent[] = [
+ { skill: 'ship', ts: daysAgo(1), repo: 'app' },
+ { skill: 'qa', ts: daysAgo(3), repo: 'app' },
+ { skill: 'review', ts: daysAgo(10), repo: 'app' },
+ { skill: 'retro', ts: daysAgo(40), repo: 'app' },
+ ];
+
+ test('period "all" returns all events', () => {
+ expect(filterByPeriod(events, 'all')).toHaveLength(4);
+ });
+
+ test('period "7d" returns only last 7 days', () => {
+ const filtered = filterByPeriod(events, '7d');
+ expect(filtered).toHaveLength(2);
+ expect(filtered[0].skill).toBe('ship');
+ expect(filtered[1].skill).toBe('qa');
+ });
+
+ test('period "30d" returns last 30 days', () => {
+ const filtered = filterByPeriod(events, '30d');
+ expect(filtered).toHaveLength(3);
+ });
+
+ test('invalid period string returns all events', () => {
+ expect(filterByPeriod(events, 'bogus')).toHaveLength(4);
+ });
+});
+
+describe('formatReport', () => {
+ test('includes header and period label', () => {
+ const report = formatReport([], 'all');
+ expect(report).toContain('gstack skill usage analytics');
+ expect(report).toContain('Period: all time');
+ });
+
+ test('shows "last 7 days" for 7d period', () => {
+ const report = formatReport([], '7d');
+ expect(report).toContain('Period: last 7 days');
+ });
+
+ test('shows "last 30 days" for 30d period', () => {
+ const report = formatReport([], '30d');
+ expect(report).toContain('Period: last 30 days');
+ });
+
+ test('counts skill invocations correctly', () => {
+ const events: AnalyticsEvent[] = [
+ { skill: 'ship', ts: '2026-03-18T15:30:00Z', repo: 'app' },
+ { skill: 'ship', ts: '2026-03-18T16:00:00Z', repo: 'app' },
+ { skill: 'qa', ts: '2026-03-18T16:30:00Z', repo: 'app' },
+ ];
+ const report = formatReport(events);
+ expect(report).toContain('/ship');
+ expect(report).toContain('2 invocations');
+ expect(report).toContain('/qa');
+ expect(report).toContain('1 invocation');
+ });
+
+ test('groups by repo', () => {
+ const events: AnalyticsEvent[] = [
+ { skill: 'ship', ts: '2026-03-18T15:30:00Z', repo: 'app-a' },
+ { skill: 'qa', ts: '2026-03-18T16:00:00Z', repo: 'app-a' },
+ { skill: 'ship', ts: '2026-03-18T16:30:00Z', repo: 'app-b' },
+ ];
+ const report = formatReport(events);
+ expect(report).toContain('app-a: ship(1) qa(1)');
+ expect(report).toContain('app-b: ship(1)');
+ });
+
+ test('counts hook fire events separately', () => {
+ const events: AnalyticsEvent[] = [
+ { skill: 'ship', ts: '2026-03-18T15:30:00Z', repo: 'app' },
+ { skill: 'careful', ts: '2026-03-18T16:00:00Z', repo: 'app', event: 'hook_fire', pattern: 'rm_recursive' },
+ { skill: 'careful', ts: '2026-03-18T16:30:00Z', repo: 'app', event: 'hook_fire', pattern: 'rm_recursive' },
+ { skill: 'careful', ts: '2026-03-18T17:00:00Z', repo: 'app', event: 'hook_fire', pattern: 'git_force_push' },
+ ];
+ const report = formatReport(events);
+ expect(report).toContain('Safety Hook Events');
+ expect(report).toContain('rm_recursive');
+ expect(report).toContain('2 fires');
+ expect(report).toContain('git_force_push');
+ expect(report).toContain('1 fire');
+ expect(report).toContain('Total: 1 skill invocation, 3 hook fires');
+ });
+
+ test('handles mixed events correctly', () => {
+ const events: AnalyticsEvent[] = [
+ { skill: 'ship', ts: '2026-03-18T15:30:00Z', repo: 'my-app' },
+ { skill: 'ship', ts: '2026-03-18T15:35:00Z', repo: 'my-app' },
+ { skill: 'qa', ts: '2026-03-18T16:00:00Z', repo: 'my-api' },
+ { skill: 'careful', ts: '2026-03-18T16:30:00Z', repo: 'my-app', event: 'hook_fire', pattern: 'rm_recursive' },
+ ];
+ const report = formatReport(events);
+ // Skills counted correctly (hook_fire events excluded from skill counts)
+ expect(report).toContain('Total: 3 skill invocations, 1 hook fire');
+ // Both sections present
+ expect(report).toContain('Top Skills');
+ expect(report).toContain('Safety Hook Events');
+ expect(report).toContain('By Repo');
+ });
+});
+
+describe('integration via runScript helper', () => {
+ test('missing file → "No analytics data found."', () => {
+ const output = runScript(path.join(TMP_DIR, 'nonexistent.jsonl'));
+ expect(output).toBe('No analytics data found.');
+ });
+
+ test('null path → "No analytics data found."', () => {
+ const output = runScript(null);
+ expect(output).toBe('No analytics data found.');
+ });
+
+ test('empty file → "No analytics data found."', () => {
+ const p = writeTempJSONL('empty.jsonl', ['']);
+ // Overwrite with truly empty content
+ fs.writeFileSync(p, '');
+ const output = runScript(p);
+ expect(output).toBe('No analytics data found.');
+ });
+
+ test('all malformed lines → "No analytics data found."', () => {
+ const p = writeTempJSONL('bad.jsonl', [
+ 'not json',
+ '{broken',
+ '42',
+ ]);
+ const output = runScript(p);
+ expect(output).toBe('No analytics data found.');
+ });
+
+ test('normal aggregation produces correct output', () => {
+ const p = writeTempJSONL('normal.jsonl', [
+ '{"skill":"ship","ts":"2026-03-18T15:30:00Z","repo":"my-app"}',
+ '{"skill":"ship","ts":"2026-03-18T15:35:00Z","repo":"my-app"}',
+ '{"skill":"qa","ts":"2026-03-18T16:00:00Z","repo":"my-app"}',
+ '{"skill":"review","ts":"2026-03-18T16:30:00Z","repo":"my-api"}',
+ ]);
+ const output = runScript(p);
+ expect(output).toContain('/ship');
+ expect(output).toContain('2 invocations');
+ expect(output).toContain('/qa');
+ expect(output).toContain('1 invocation');
+ expect(output).toContain('/review');
+ expect(output).toContain('Total: 4 skill invocations, 0 hook fires');
+ });
+
+ test('period filtering (7d) only includes recent entries', () => {
+ const now = new Date();
+ const recent = new Date(now.getTime() - 2 * 24 * 60 * 60 * 1000).toISOString();
+ const old = new Date(now.getTime() - 20 * 24 * 60 * 60 * 1000).toISOString();
+
+ const p = writeTempJSONL('period.jsonl', [
+ `{"skill":"ship","ts":"${recent}","repo":"app"}`,
+ `{"skill":"qa","ts":"${old}","repo":"app"}`,
+ ]);
+ const output = runScript(p, '--period 7d');
+ expect(output).toContain('Period: last 7 days');
+ expect(output).toContain('/ship');
+ expect(output).toContain('Total: 1 skill invocation, 0 hook fires');
+ // qa should be filtered out
+ expect(output).not.toContain('/qa');
+ });
+
+ test('hook fire events counted in full pipeline', () => {
+ const p = writeTempJSONL('hooks.jsonl', [
+ '{"skill":"ship","ts":"2026-03-18T15:30:00Z","repo":"app"}',
+ '{"event":"hook_fire","skill":"careful","pattern":"rm_recursive","ts":"2026-03-18T16:00:00Z","repo":"app"}',
+ '{"event":"hook_fire","skill":"careful","pattern":"rm_recursive","ts":"2026-03-18T16:30:00Z","repo":"app"}',
+ '{"event":"hook_fire","skill":"careful","pattern":"git_force_push","ts":"2026-03-18T17:00:00Z","repo":"app"}',
+ ]);
+ const output = runScript(p);
+ expect(output).toContain('Safety Hook Events');
+ expect(output).toContain('rm_recursive');
+ expect(output).toContain('2 fires');
+ expect(output).toContain('git_force_push');
+ expect(output).toContain('1 fire');
+ expect(output).toContain('Total: 1 skill invocation, 3 hook fires');
+ });
+});
M test/gen-skill-docs.test.ts => test/gen-skill-docs.test.ts +25 -0
@@ 72,6 72,11 @@ describe('gen-skill-docs', () => {
{ dir: 'plan-design-review', name: 'plan-design-review' },
{ dir: 'design-review', name: 'design-review' },
{ dir: 'design-consultation', name: 'design-consultation' },
+ { dir: 'document-release', name: 'document-release' },
+ { dir: 'careful', name: 'careful' },
+ { dir: 'freeze', name: 'freeze' },
+ { dir: 'guard', name: 'guard' },
+ { dir: 'unfreeze', name: 'unfreeze' },
];
test('every skill has a SKILL.md.tmpl template', () => {
@@ 161,6 166,26 @@ describe('gen-skill-docs', () => {
expect(content).toContain('plain English');
});
+ test('generated SKILL.md contains telemetry line', () => {
+ const content = fs.readFileSync(path.join(ROOT, 'SKILL.md'), 'utf-8');
+ expect(content).toContain('skill-usage.jsonl');
+ expect(content).toContain('~/.gstack/analytics');
+ });
+
+ test('preamble-using skills have correct skill name in telemetry', () => {
+ const PREAMBLE_SKILLS = [
+ { dir: '.', name: 'gstack' },
+ { dir: 'ship', name: 'ship' },
+ { dir: 'review', name: 'review' },
+ { dir: 'qa', name: 'qa' },
+ { dir: 'retro', name: 'retro' },
+ ];
+ for (const skill of PREAMBLE_SKILLS) {
+ const content = fs.readFileSync(path.join(ROOT, skill.dir, 'SKILL.md'), 'utf-8');
+ expect(content).toContain(`"skill":"${skill.name}"`);
+ }
+ });
+
test('qa and qa-only templates use QA_METHODOLOGY placeholder', () => {
const qaTmpl = fs.readFileSync(path.join(ROOT, 'qa', 'SKILL.md.tmpl'), 'utf-8');
expect(qaTmpl).toContain('{{QA_METHODOLOGY}}');
A test/hook-scripts.test.ts => test/hook-scripts.test.ts +373 -0
@@ 0,0 1,373 @@
+import { describe, test, expect } from 'bun:test';
+import { spawnSync } from 'child_process';
+import * as path from 'path';
+import * as fs from 'fs';
+import * as os from 'os';
+
+const ROOT = path.resolve(import.meta.dir, '..');
+const CAREFUL_SCRIPT = path.join(ROOT, 'careful', 'bin', 'check-careful.sh');
+const FREEZE_SCRIPT = path.join(ROOT, 'freeze', 'bin', 'check-freeze.sh');
+
+function runHook(scriptPath: string, input: object, env?: Record<string, string>): { exitCode: number; output: any; raw: string } {
+ const result = spawnSync('bash', [scriptPath], {
+ input: JSON.stringify(input),
+ stdio: ['pipe', 'pipe', 'pipe'],
+ env: { ...process.env, ...env },
+ timeout: 5000,
+ });
+ const raw = result.stdout.toString().trim();
+ let output: any = {};
+ try {
+ output = JSON.parse(raw);
+ } catch {}
+ return { exitCode: result.status ?? 1, output, raw };
+}
+
+function runHookRaw(scriptPath: string, rawInput: string, env?: Record<string, string>): { exitCode: number; output: any; raw: string } {
+ const result = spawnSync('bash', [scriptPath], {
+ input: rawInput,
+ stdio: ['pipe', 'pipe', 'pipe'],
+ env: { ...process.env, ...env },
+ timeout: 5000,
+ });
+ const raw = result.stdout.toString().trim();
+ let output: any = {};
+ try {
+ output = JSON.parse(raw);
+ } catch {}
+ return { exitCode: result.status ?? 1, output, raw };
+}
+
+function carefulInput(command: string) {
+ return { tool_input: { command } };
+}
+
+function freezeInput(filePath: string) {
+ return { tool_input: { file_path: filePath } };
+}
+
+function withFreezeDir(freezePath: string, fn: (stateDir: string) => void) {
+ const stateDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-freeze-test-'));
+ fs.writeFileSync(path.join(stateDir, 'freeze-dir.txt'), freezePath);
+ try {
+ fn(stateDir);
+ } finally {
+ fs.rmSync(stateDir, { recursive: true, force: true });
+ }
+}
+
+// Detect whether the safe-rm-targets regex works on this platform.
+// macOS sed -E does not support \s, so the safe exception check fails there.
+function detectSafeRmWorks(): boolean {
+ const { output } = runHook(CAREFUL_SCRIPT, carefulInput('rm -rf node_modules'));
+ return output.permissionDecision === undefined;
+}
+
+// ============================================================
+// check-careful.sh tests
+// ============================================================
+describe('check-careful.sh', () => {
+
+ // --- Destructive rm commands ---
+
+ describe('rm -rf / rm -r', () => {
+ test('rm -rf /var/data warns with recursive delete message', () => {
+ const { exitCode, output } = runHook(CAREFUL_SCRIPT, carefulInput('rm -rf /var/data'));
+ expect(exitCode).toBe(0);
+ expect(output.permissionDecision).toBe('ask');
+ expect(output.message).toContain('recursive delete');
+ });
+
+ test('rm -r ./some-dir warns', () => {
+ const { exitCode, output } = runHook(CAREFUL_SCRIPT, carefulInput('rm -r ./some-dir'));
+ expect(exitCode).toBe(0);
+ expect(output.permissionDecision).toBe('ask');
+ expect(output.message).toContain('recursive delete');
+ });
+
+ test('rm -rf node_modules allows (safe exception)', () => {
+ const { exitCode, output } = runHook(CAREFUL_SCRIPT, carefulInput('rm -rf node_modules'));
+ expect(exitCode).toBe(0);
+ if (detectSafeRmWorks()) {
+ // GNU sed: safe exception triggers, allows through
+ expect(output.permissionDecision).toBeUndefined();
+ } else {
+ // macOS sed: safe exception regex uses \\s which is unsupported,
+ // so the safe-targets check fails and the command warns
+ expect(output.permissionDecision).toBe('ask');
+ }
+ });
+
+ test('rm -rf .next dist allows (multiple safe targets)', () => {
+ const { exitCode, output } = runHook(CAREFUL_SCRIPT, carefulInput('rm -rf .next dist'));
+ expect(exitCode).toBe(0);
+ if (detectSafeRmWorks()) {
+ expect(output.permissionDecision).toBeUndefined();
+ } else {
+ expect(output.permissionDecision).toBe('ask');
+ }
+ });
+
+ test('rm -rf node_modules /var/data warns (mixed safe+unsafe)', () => {
+ const { exitCode, output } = runHook(CAREFUL_SCRIPT, carefulInput('rm -rf node_modules /var/data'));
+ expect(exitCode).toBe(0);
+ expect(output.permissionDecision).toBe('ask');
+ expect(output.message).toContain('recursive delete');
+ });
+ });
+
+ // --- SQL destructive commands ---
+ // Note: SQL commands that contain embedded double quotes (e.g., psql -c "DROP TABLE")
+ // get their command value truncated by the grep-based JSON extractor because \"
+ // terminates the [^"]* match. We use commands WITHOUT embedded quotes so the grep
+ // extraction works and the SQL keywords are visible to the pattern matcher.
+
+ describe('SQL destructive commands', () => {
+ test('psql DROP TABLE warns with DROP in message', () => {
+ const { exitCode, output } = runHook(CAREFUL_SCRIPT, carefulInput('psql -c DROP TABLE users;'));
+ expect(exitCode).toBe(0);
+ expect(output.permissionDecision).toBe('ask');
+ expect(output.message).toContain('DROP');
+ });
+
+ test('mysql drop database warns (case insensitive)', () => {
+ const { exitCode, output } = runHook(CAREFUL_SCRIPT, carefulInput('mysql -e drop database mydb'));
+ expect(exitCode).toBe(0);
+ expect(output.permissionDecision).toBe('ask');
+ expect(output.message.toLowerCase()).toContain('drop');
+ });
+
+ test('psql TRUNCATE warns', () => {
+ const { exitCode, output } = runHook(CAREFUL_SCRIPT, carefulInput('psql -c TRUNCATE orders;'));
+ expect(exitCode).toBe(0);
+ expect(output.permissionDecision).toBe('ask');
+ expect(output.message).toContain('TRUNCATE');
+ });
+ });
+
+ // --- Git destructive commands ---
+
+ describe('git destructive commands', () => {
+ test('git push --force warns with force-push', () => {
+ const { exitCode, output } = runHook(CAREFUL_SCRIPT, carefulInput('git push --force origin main'));
+ expect(exitCode).toBe(0);
+ expect(output.permissionDecision).toBe('ask');
+ expect(output.message).toContain('force-push');
+ });
+
+ test('git push -f warns', () => {
+ const { exitCode, output } = runHook(CAREFUL_SCRIPT, carefulInput('git push -f origin main'));
+ expect(exitCode).toBe(0);
+ expect(output.permissionDecision).toBe('ask');
+ expect(output.message).toContain('force-push');
+ });
+
+ test('git reset --hard warns with uncommitted', () => {
+ const { exitCode, output } = runHook(CAREFUL_SCRIPT, carefulInput('git reset --hard HEAD~3'));
+ expect(exitCode).toBe(0);
+ expect(output.permissionDecision).toBe('ask');
+ expect(output.message).toContain('uncommitted');
+ });
+
+ test('git checkout . warns', () => {
+ const { exitCode, output } = runHook(CAREFUL_SCRIPT, carefulInput('git checkout .'));
+ expect(exitCode).toBe(0);
+ expect(output.permissionDecision).toBe('ask');
+ expect(output.message).toContain('uncommitted');
+ });
+
+ test('git restore . warns', () => {
+ const { exitCode, output } = runHook(CAREFUL_SCRIPT, carefulInput('git restore .'));
+ expect(exitCode).toBe(0);
+ expect(output.permissionDecision).toBe('ask');
+ expect(output.message).toContain('uncommitted');
+ });
+ });
+
+ // --- Container / infra destructive commands ---
+
+ describe('container and infra commands', () => {
+ test('kubectl delete warns with kubectl in message', () => {
+ const { exitCode, output } = runHook(CAREFUL_SCRIPT, carefulInput('kubectl delete pod my-pod'));
+ expect(exitCode).toBe(0);
+ expect(output.permissionDecision).toBe('ask');
+ expect(output.message).toContain('kubectl');
+ });
+
+ test('docker rm -f warns', () => {
+ const { exitCode, output } = runHook(CAREFUL_SCRIPT, carefulInput('docker rm -f container123'));
+ expect(exitCode).toBe(0);
+ expect(output.permissionDecision).toBe('ask');
+ expect(output.message).toContain('Docker');
+ });
+
+ test('docker system prune -a warns', () => {
+ const { exitCode, output } = runHook(CAREFUL_SCRIPT, carefulInput('docker system prune -a'));
+ expect(exitCode).toBe(0);
+ expect(output.permissionDecision).toBe('ask');
+ expect(output.message).toContain('Docker');
+ });
+ });
+
+ // --- Safe commands ---
+
+ describe('safe commands allow without warning', () => {
+ const safeCmds = [
+ 'ls -la',
+ 'git status',
+ 'npm install',
+ 'cat README.md',
+ 'echo hello',
+ ];
+
+ for (const cmd of safeCmds) {
+ test(`"${cmd}" allows`, () => {
+ const { exitCode, output } = runHook(CAREFUL_SCRIPT, carefulInput(cmd));
+ expect(exitCode).toBe(0);
+ expect(output.permissionDecision).toBeUndefined();
+ });
+ }
+ });
+
+ // --- Edge cases ---
+
+ describe('edge cases', () => {
+ test('empty command allows gracefully', () => {
+ const { exitCode, output } = runHook(CAREFUL_SCRIPT, carefulInput(''));
+ expect(exitCode).toBe(0);
+ expect(output.permissionDecision).toBeUndefined();
+ });
+
+ test('missing command field allows gracefully', () => {
+ const { exitCode, output } = runHook(CAREFUL_SCRIPT, { tool_input: {} });
+ expect(exitCode).toBe(0);
+ expect(output.permissionDecision).toBeUndefined();
+ });
+
+ test('malformed JSON input allows gracefully (exit 0, output {})', () => {
+ const { exitCode, raw } = runHookRaw(CAREFUL_SCRIPT, 'this is not json at all{{{{');
+ expect(exitCode).toBe(0);
+ expect(raw).toBe('{}');
+ });
+
+ test('Python fallback: grep fails on multiline JSON, Python parses it', () => {
+ // Construct JSON where "command": and the value are on separate lines.
+ // grep works line-by-line, so it cannot match "command"..."value" across lines.
+ // This forces CMD to be empty, triggering the Python fallback which handles
+ // the full JSON correctly.
+ const rawJson = '{"tool_input":{"command":\n"rm -rf /tmp/important"}}';
+ const { exitCode, output } = runHookRaw(CAREFUL_SCRIPT, rawJson);
+ expect(exitCode).toBe(0);
+ expect(output.permissionDecision).toBe('ask');
+ expect(output.message).toContain('recursive delete');
+ });
+ });
+});
+
+// ============================================================
+// check-freeze.sh tests
+// ============================================================
+describe('check-freeze.sh', () => {
+
+ describe('edits inside freeze boundary', () => {
+ test('edit inside freeze boundary allows', () => {
+ withFreezeDir('/Users/dev/project/src/', (stateDir) => {
+ const { exitCode, output } = runHook(
+ FREEZE_SCRIPT,
+ freezeInput('/Users/dev/project/src/index.ts'),
+ { CLAUDE_PLUGIN_DATA: stateDir },
+ );
+ expect(exitCode).toBe(0);
+ expect(output.permissionDecision).toBeUndefined();
+ });
+ });
+
+ test('edit in subdirectory of freeze path allows', () => {
+ withFreezeDir('/Users/dev/project/src/', (stateDir) => {
+ const { exitCode, output } = runHook(
+ FREEZE_SCRIPT,
+ freezeInput('/Users/dev/project/src/components/Button.tsx'),
+ { CLAUDE_PLUGIN_DATA: stateDir },
+ );
+ expect(exitCode).toBe(0);
+ expect(output.permissionDecision).toBeUndefined();
+ });
+ });
+ });
+
+ describe('edits outside freeze boundary', () => {
+ test('edit outside freeze boundary denies', () => {
+ withFreezeDir('/Users/dev/project/src/', (stateDir) => {
+ const { exitCode, output } = runHook(
+ FREEZE_SCRIPT,
+ freezeInput('/Users/dev/other-project/index.ts'),
+ { CLAUDE_PLUGIN_DATA: stateDir },
+ );
+ expect(exitCode).toBe(0);
+ expect(output.permissionDecision).toBe('deny');
+ expect(output.message).toContain('freeze');
+ expect(output.message).toContain('outside');
+ });
+ });
+
+ test('write outside freeze boundary denies', () => {
+ withFreezeDir('/Users/dev/project/src/', (stateDir) => {
+ const { exitCode, output } = runHook(
+ FREEZE_SCRIPT,
+ freezeInput('/etc/hosts'),
+ { CLAUDE_PLUGIN_DATA: stateDir },
+ );
+ expect(exitCode).toBe(0);
+ expect(output.permissionDecision).toBe('deny');
+ expect(output.message).toContain('freeze');
+ expect(output.message).toContain('outside');
+ });
+ });
+ });
+
+ describe('trailing slash prevents prefix confusion', () => {
+ test('freeze at /src/ denies /src-old/ (trailing slash prevents prefix match)', () => {
+ withFreezeDir('/Users/dev/project/src/', (stateDir) => {
+ const { exitCode, output } = runHook(
+ FREEZE_SCRIPT,
+ freezeInput('/Users/dev/project/src-old/index.ts'),
+ { CLAUDE_PLUGIN_DATA: stateDir },
+ );
+ expect(exitCode).toBe(0);
+ expect(output.permissionDecision).toBe('deny');
+ expect(output.message).toContain('outside');
+ });
+ });
+ });
+
+ describe('no freeze file exists', () => {
+ test('allows everything when no freeze file present', () => {
+ const stateDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-freeze-test-'));
+ try {
+ const { exitCode, output } = runHook(
+ FREEZE_SCRIPT,
+ freezeInput('/anywhere/at/all.ts'),
+ { CLAUDE_PLUGIN_DATA: stateDir },
+ );
+ expect(exitCode).toBe(0);
+ expect(output.permissionDecision).toBeUndefined();
+ } finally {
+ fs.rmSync(stateDir, { recursive: true, force: true });
+ }
+ });
+ });
+
+ describe('edge cases', () => {
+ test('missing file_path field allows gracefully', () => {
+ withFreezeDir('/Users/dev/project/src/', (stateDir) => {
+ const { exitCode, output } = runHook(
+ FREEZE_SCRIPT,
+ { tool_input: {} },
+ { CLAUDE_PLUGIN_DATA: stateDir },
+ );
+ expect(exitCode).toBe(0);
+ expect(output.permissionDecision).toBeUndefined();
+ });
+ });
+ });
+});
A unfreeze/SKILL.md => unfreeze/SKILL.md +40 -0
@@ 0,0 1,40 @@
+---
+name: unfreeze
+version: 0.1.0
+description: |
+ Clear the freeze boundary set by /freeze, allowing edits to all directories
+ again. Use when you want to widen edit scope without ending the session.
+ Use when asked to "unfreeze", "unlock edits", "remove freeze", or
+ "allow all edits".
+allowed-tools:
+ - Bash
+ - Read
+---
+<!-- AUTO-GENERATED from SKILL.md.tmpl — do not edit directly -->
+<!-- Regenerate: bun run gen:skill-docs -->
+
+# /unfreeze — Clear Freeze Boundary
+
+Remove the edit restriction set by `/freeze`, allowing edits to all directories.
+
+```bash
+mkdir -p ~/.gstack/analytics
+echo '{"skill":"unfreeze","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
+```
+
+## Clear the boundary
+
+```bash
+STATE_DIR="${CLAUDE_PLUGIN_DATA:-$HOME/.gstack}"
+if [ -f "$STATE_DIR/freeze-dir.txt" ]; then
+ PREV=$(cat "$STATE_DIR/freeze-dir.txt")
+ rm -f "$STATE_DIR/freeze-dir.txt"
+ echo "Freeze boundary cleared (was: $PREV). Edits are now allowed everywhere."
+else
+ echo "No freeze boundary was set."
+fi
+```
+
+Tell the user the result. Note that `/freeze` hooks are still registered for the
+session — they will just allow everything since no state file exists. To re-freeze,
+run `/freeze` again.
A unfreeze/SKILL.md.tmpl => unfreeze/SKILL.md.tmpl +38 -0
@@ 0,0 1,38 @@
+---
+name: unfreeze
+version: 0.1.0
+description: |
+ Clear the freeze boundary set by /freeze, allowing edits to all directories
+ again. Use when you want to widen edit scope without ending the session.
+ Use when asked to "unfreeze", "unlock edits", "remove freeze", or
+ "allow all edits".
+allowed-tools:
+ - Bash
+ - Read
+---
+
+# /unfreeze — Clear Freeze Boundary
+
+Remove the edit restriction set by `/freeze`, allowing edits to all directories.
+
+```bash
+mkdir -p ~/.gstack/analytics
+echo '{"skill":"unfreeze","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
+```
+
+## Clear the boundary
+
+```bash
+STATE_DIR="${CLAUDE_PLUGIN_DATA:-$HOME/.gstack}"
+if [ -f "$STATE_DIR/freeze-dir.txt" ]; then
+ PREV=$(cat "$STATE_DIR/freeze-dir.txt")
+ rm -f "$STATE_DIR/freeze-dir.txt"
+ echo "Freeze boundary cleared (was: $PREV). Edits are now allowed everywhere."
+else
+ echo "No freeze boundary was set."
+fi
+```
+
+Tell the user the result. Note that `/freeze` hooks are still registered for the
+session — they will just allow everything since no state file exists. To re-freeze,
+run `/freeze` again.