claude-code-arcane 2.13.0 → 2.15.0

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+# [2.15.0](https://github.com/SebastianLuser/claude-code-arcane/compare/v2.14.0...v2.15.0) (2026-10-16)
+
+
+### Features
+
+* **hooks:** watch the session for loops, scope and unchecked edits ([84d7c3e](https://github.com/SebastianLuser/claude-code-arcane/commit/84d7c3eccc33380f27d7f8901affedb090ee21d5))
+* **installer:** wire the session watch and feed it the real context window ([615d212](https://github.com/SebastianLuser/claude-code-arcane/commit/615d212d96744c180fe9f84f7670382ec58d2772))
+
+# [2.14.0](https://github.com/SebastianLuser/claude-code-arcane/compare/v2.13.0...v2.14.0) (2026-10-16)
+
+
+### Features
+
+* **hooks:** leave finished worktrees and tell a session where it is ([df0531f](https://github.com/SebastianLuser/claude-code-arcane/commit/df0531feef6801649682f8f21dfcf36de006851b))
+* **session:** keep the progress file in .claude/session-state ([0615ce5](https://github.com/SebastianLuser/claude-code-arcane/commit/0615ce5289751044a749a034b1ef99bcbfd7e058))
+
 # [2.13.0](https://github.com/SebastianLuser/claude-code-arcane/compare/v2.12.0...v2.13.0) (2026-10-16)
 
 

package/README.md

@@ -1,6 +1,6 @@
 # Claude Code Arcane
 
-> **437 skills, 115 agents, 16 hooks and 36 rules for Claude Code — selective deploy by profile.**
+> **437 skills, 115 agents, 18 hooks and 36 rules for Claude Code — selective deploy by profile.**
 
 A configuration harness installable via `npx`. Pick a **profile** that matches your stack and only the relevant tools get installed into your project's `.claude/` directory.
 

package/agents/visualnovel/vn-producer.md

@@ -81,7 +81,7 @@ Know who to call for what:
 
 #### Progress Tracking
 
-Maintain `production/session-state/active.md` with:
+Maintain `.claude/session-state/active.md` with:
 
 ```markdown
 ## VN Production State
@@ -122,7 +122,7 @@ Maintain `production/session-state/active.md` with:
 | Audio asset gaps | Medium | Medium | Placeholder tracks, generate late |
 
 ### File Ownership
-- `production/session-state/active.md` — session state
+- `.claude/session-state/active.md` — session state
 - `production/milestones/` — milestone definitions and status
 - `design/assets/asset-manifest.md` — asset pipeline tracking (shared with vn-asset-pipeline)
 

package/dist/cli.js

@@ -880,16 +880,19 @@ var FILE_TOOLS_MATCHER = "Write|Edit|MultiEdit|NotebookEdit";
 var LEGACY_COMMAND = /^bash \.claude\/hooks\/([\w.-]+\.sh)$/;
 var ARCANE_COMMAND = /^bash "?(?:\$CLAUDE_PROJECT_DIR\/|[^"]*\/)?\.claude\/hooks\/([\w.-]+\.sh)"?$/;
 var RETIRED_SCRIPTS = /* @__PURE__ */ new Set(["validate-push.sh", "validate-secrets.sh"]);
-function hookCommand(target, script) {
+function hookCommand(target, script, args = "") {
+  const suffix = args ? ` ${args}` : "";
   if (path8.resolve(target) === path8.resolve(os2.homedir())) {
     const absolute = path8.join(target, ".claude", "hooks", script).replace(/\\/g, "/");
-    return `bash "${absolute}"`;
+    return `bash "${absolute}"${suffix}`;
   }
-  return `bash "$CLAUDE_PROJECT_DIR/.claude/hooks/${script}"`;
+  return `bash "$CLAUDE_PROJECT_DIR/.claude/hooks/${script}"${suffix}`;
 }
-function hook(target, script, timeout) {
-  return { type: "command", command: hookCommand(target, script), timeout };
+function hook(target, script, timeout, args = "") {
+  return { type: "command", command: hookCommand(target, script, args), timeout };
 }
+var WATCH_POST_TOOL = ["run-py.sh", "session_watch.py post-tool"];
+var WATCH_STOP = ["run-py.sh", "session_watch.py stop"];
 function defaultHooks(target) {
   const one = (script, timeout) => [
     { matcher: "", hooks: [hook(target, script, timeout)] }
@@ -921,12 +924,22 @@ function defaultHooks(target) {
       {
         matcher: "Write|Edit",
         hooks: [hook(target, "validate-assets.sh", 10), hook(target, "validate-skill-change.sh", 5)]
-      }
+      },
+      { matcher: "", hooks: [hook(target, WATCH_POST_TOOL[0], 10, WATCH_POST_TOOL[1])] }
     ],
     Notification: one("notify.sh", 10),
     PreCompact: one("pre-compact.sh", 10),
     PostCompact: one("post-compact.sh", 10),
-    Stop: one("session-stop.sh", 10),
+    Stop: [
+      {
+        matcher: "",
+        hooks: [
+          hook(target, "session-stop.sh", 10),
+          hook(target, "worktree-stop.sh", 10),
+          hook(target, WATCH_STOP[0], 120, WATCH_STOP[1])
+        ]
+      }
+    ],
     SubagentStart: one("log-agent.sh", 5),
     SubagentStop: one("log-agent-stop.sh", 5)
   };
@@ -973,8 +986,21 @@ function healHooks(hooks, target) {
     pre.push({ matcher: FILE_TOOLS_MATCHER, hooks: [hook(target, "guard.sh", 10)] });
     changes.push("guard for file edits");
   }
+  ensureHook(hooks, "Stop", hook(target, "worktree-stop.sh", 10), "worktree exit on stop", changes);
+  ensureHook(hooks, "Stop", hook(target, WATCH_STOP[0], 120, WATCH_STOP[1]), "format and type check on stop", changes);
+  ensureHook(hooks, "PostToolUse", hook(target, WATCH_POST_TOOL[0], 10, WATCH_POST_TOOL[1]), "session watch", changes);
   return changes;
 }
+function ensureHook(hooks, event, entry, label, changes) {
+  const signature = entry.command.replace(/^bash "[^"]*\/hooks\//, "");
+  const groups = hooks[event] ??= [];
+  const present = groups.some((g) => g.hooks?.some((h) => h.command?.endsWith(signature)));
+  if (present) return;
+  const group = groups.find((g) => !g.matcher);
+  if (group) group.hooks = [...group.hooks ?? [], entry];
+  else groups.push({ matcher: "", hooks: [entry] });
+  changes.push(label);
+}
 
 // src/installer.ts
 var SETTINGS_TEMPLATE = {

package/docs/USER-GUIDE.md

@@ -2,7 +2,7 @@
 
 ## What is Arcane?
 
-Arcane is a configuration harness for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). It provides a curated library of **437 skills**, **115 agents**, **16 hooks**, and **36 rules** that you selectively deploy into any project. Instead of shipping everything to every project (wasting tokens and degrading performance), you pick a **profile** that matches your stack and only the relevant tools get installed.
+Arcane is a configuration harness for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). It provides a curated library of **437 skills**, **115 agents**, **18 hooks**, and **36 rules** that you selectively deploy into any project. Instead of shipping everything to every project (wasting tokens and degrading performance), you pick a **profile** that matches your stack and only the relevant tools get installed.
 
 ## Table of Contents
 
@@ -239,7 +239,7 @@ Every installation automatically loads `core.yaml` first:
 |----------|----------|
 | **Skills (21)** | commit, create-pr, changelog, check, code-review, context-prime, help, start, fix-issue, hotfix, brainstorm, scope-check, reverse-document, skill-improve, skill-test, tech-debt, arcane-status, arcane-list, arcane-add, arcane-remove, arcane-clean |
 | **Rules (8)** | data-files, prototype-code, test-standards, implementation-workflow, code-comments, verification, agent-delegation, git-worktrees |
-| **Hooks (15)** | session-start, detect-division, detect-unreal, detect-gaps, check-update, guard, validate-commit, validate-assets, validate-skill-change, notify, pre-compact, post-compact, session-stop, log-agent, log-agent-stop |
+| **Hooks (17)** | session-start, detect-division, detect-unreal, detect-gaps, check-update, guard, validate-commit, validate-assets, validate-skill-change, notify, pre-compact, post-compact, session-stop, worktree-stop, run-py (session_watch), log-agent, log-agent-stop |
 | **Agents (1 dir)** | quality |
 | **Permissions** | 15 allow (git, ls, gh pr/issue/run and read-only gh, curl) + 13 deny (force push, reset --hard, clean -f, sudo, .env, etc.) |
 

package/docs/collaborative-design.md

@@ -311,7 +311,7 @@ Para documentos largos (ADRs, PRDs, GDDs, RFCs) escribí sección por sección a
    - Review con el usuario
    - Iterar hasta aprobación
    - Escribir ESA sección al archivo
-   - Update production/session-state/active.md
+   - Update .claude/session-state/active.md
    - La conversación de esa sección puede compactarse — la decisión ya está en disco
 
 3. Si la sesión crashea mid-document:

package/docs/context-management.md

@@ -16,7 +16,7 @@ Claude Code tiene una ventana de contexto limitada. Sesiones largas llegan al l
 
 ### Session State File
 
-Mantené `production/session-state/active.md` como checkpoint vivo. Update después de cada milestone significativo:
+Mantené `.claude/session-state/active.md` como checkpoint vivo. Update después de cada milestone significativo:
 
 - Sección de diseño / ADR aprobada y escrita
 - Decisión arquitectónica tomada
@@ -25,23 +25,6 @@ Mantené `production/session-state/active.md` como checkpoint vivo. Update despu
 
 El state file debe contener: tarea actual, checklist de progreso, decisiones clave tomadas, archivos en trabajo, preguntas abiertas.
 
-### Status Line Block (opcional, para proyectos activos)
-
-Para proyectos en fase de ejecución, incluir en `active.md` un bloque estructurado que el status line script puede parsear:
-
-```markdown
-<!-- STATUS -->
-Epic: Auth refactor
-Feature: JWT rotation
-Task: Implementar refresh endpoint
-<!-- /STATUS -->
-```
-
-- Los tres campos (Epic, Feature, Task) son opcionales — incluí solo lo aplicable
-- Update cuando cambiás de foco
-- El status line lo muestra como breadcrumb: `Auth refactor > JWT rotation > Refresh endpoint`
-- Remove o vaciá cuando no hay work focus activo
-
 Después de cualquier disrupción (compaction, crash, `/clear`), leé el state file primero.
 
 ---
@@ -65,14 +48,15 @@ Esto mantiene el context window con ~3-5k tokens (solo la sección actual) en ve
 ## Proactive Compaction
 
 - **Compactá proactivamente** a ~60-70% de uso, no reactivamente al límite
+- **Aviso automático:** con el profile `statusline`, `session_watch.py` avisa a Claude al 70% y al 85% de la ventana real (la statusline anota el tamaño que reporta Claude Code en `.claude/session-state/context.json`). Sin statusline no avisa: adivinar la ventana haría saltar el aviso demasiado temprano en sesiones de 1M
 - **Usá `/clear`** entre tareas no relacionadas, o después de 2+ intentos de corrección fallidos
 - **Puntos naturales de compaction:** después de escribir una sección al archivo, después de un commit, después de completar una tarea, antes de empezar un tema nuevo
 - **Focused compaction:** `/compact Focus on [tarea actual] — secciones 1-3 ya escritas al archivo, working on sección 4`
 
 ### Compaction Hooks
 
-- `pre-compact.sh`: Guarda summary del estado antes de compaction
-- `post-compact.sh`: Carga summary después de compaction
+- `pre-compact.sh` y `post-compact.sh` solo anotan la hora en `.claude/session-state/sessions.log`. No guardan ni cargan estado.
+- Lo que sobrevive a la compactación es el archivo: `session-start.sh` corre también después de cada compactación (SessionStart con matcher vacío) y muestra el inicio de `active.md`. Por eso `active.md` tiene que estar al día **antes** de compactar.
 
 ---
 
@@ -111,7 +95,7 @@ Los subagents no heredan historia de conversación — dales contexto completo e
 
 Cuando el contexto se compacta, preservá en el summary:
 
-- Referencia a `production/session-state/active.md` (leer para recover state)
+- Referencia a `.claude/session-state/active.md` (leer para recover state)
 - Lista de archivos modificados en la sesión y su propósito
 - Decisiones arquitectónicas hechas y su rationale
 - Tasks activas del sprint y estado actual
@@ -163,7 +147,7 @@ Cuando el status line muestra >= 70%:
 ```
 Tarea: "Implementá auth JWT completo"
 
-1. Crear production/session-state/active.md con:
+1. Crear .claude/session-state/active.md con:
    - Feature: JWT auth
    - Files to create: src/auth/{tokens.ts, middleware.ts, login.ts}
    - Tests: tests/auth.test.ts

package/docs/coordination-rules.md

@@ -71,7 +71,7 @@ Ningún agente hace commits sin instrucción explícita del user. Ni siquiera el
 
 ## Regla #9 — Session State
 
-Actualizar `production/session-state/active.md` cuando:
+Actualizar `.claude/session-state/active.md` cuando:
 - Se completa un section/phase
 - Se toma una decisión significativa
 - Se cambia de división/agente

package/docs/directory-structure.md

@@ -97,9 +97,9 @@ claude-code-arcane/
 │   ├── statusline.sh                  # Solo con el profile statusline
 │   ├── output-styles/                 # Solo si algún profile declara output_styles
 │   ├── docs/                          # Copia de docs/; arcane update la mantiene al día
+│   ├── session-state/                 # active.md y logs de sesión; se ignora solo (.gitignore con *)
 │   └── .arcane-trash/                 # Lo que arcane update saca; nunca se borra con rm
-├── .claude.bak/                       # Backup de .claude/ antes de instalar
-└── production/session-state/          # Estado de sesión que escriben los hooks
+└── .claude.bak/                       # Backup de .claude/ antes de instalar
 ```
 
 Fuera del proyecto, `~/.arcane/` guarda el registro de instalaciones (`installations.json`) y el contenido descargado de GitHub (`cache/<version>/`). `ARCANE_HOME` lo desvía.
@@ -125,9 +125,10 @@ Los eventos los define `src/installer.ts` al generar `settings.json`, no los pro
 | PreToolUse (`Bash`) | `guard.sh` → `validate-commit.sh` |
 | PreToolUse (`Write\|Edit\|MultiEdit\|NotebookEdit`) | `guard.sh` |
 | PostToolUse (`Write\|Edit`) | `validate-assets.sh`, `validate-skill-change.sh` |
+| PostToolUse (todas) | `run-py.sh session_watch.py post-tool` (ediciones, loops, alcance, aviso de compactación) |
 | Notification | `notify.sh` |
 | PreCompact / PostCompact | `pre-compact.sh` / `post-compact.sh` |
-| Stop | `session-stop.sh` |
+| Stop | `session-stop.sh`, `worktree-stop.sh`, `run-py.sh session_watch.py stop` (format + type check de lo editado) |
 | SubagentStart / SubagentStop | `log-agent.sh` / `log-agent-stop.sh` |
 
 Cada comando es `bash "$CLAUDE_PROJECT_DIR/.claude/hooks/<script>"`: dentro de un worktree los hooks corren parados en el worktree, que puede no tener `.claude/hooks/` commiteado, y la variable siempre apunta al proyecto donde arrancó la sesión. `arcane update` migra las instalaciones que tenían la ruta relativa.

package/docs/gates/README.md

@@ -123,8 +123,8 @@ Después de que un gate resuelve, registrar el verdict en el header de status de
 ```
 
 Para phase gates, registrar en:
-- Software: `docs/architecture/architecture.md` o `production/session-state/active.md`
-- Gamedev: `docs/architecture/architecture.md` o `production/session-state/active.md`
+- Software: `docs/architecture/architecture.md` o `.claude/session-state/active.md`
+- Gamedev: `docs/architecture/architecture.md` o `.claude/session-state/active.md`
 
 ---
 

package/hooks/detect-division.sh

@@ -22,7 +22,7 @@ main() {
     DIVISION="engineering (Python)"
   fi
 
-  [[ -d "production/session-state" ]] && echo "Division: $DIVISION" > production/session-state/division.txt
+  [[ -d ".claude/session-state" ]] && echo "Division: $DIVISION" > .claude/session-state/division.txt
 }
 main 2>/dev/null
 exit 0

package/hooks/log-agent-stop.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 set +e
 main() {
-  [[ -d production/session-state ]] && echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] subagent_stop" >> production/session-state/agents.log
+  [[ -d .claude/session-state ]] && echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] subagent_stop" >> .claude/session-state/agents.log
 }
 main 2>/dev/null
 exit 0

package/hooks/log-agent.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 set +e
 main() {
-  [[ -d production/session-state ]] && echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] subagent_start" >> production/session-state/agents.log
+  [[ -d .claude/session-state ]] && echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] subagent_start" >> .claude/session-state/agents.log
 }
 main 2>/dev/null
 exit 0

package/hooks/notify.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 set +e
 main() {
-  [[ -d production/session-state ]] && echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] notification" >> production/session-state/notifications.log
+  [[ -d .claude/session-state ]] && echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] notification" >> .claude/session-state/notifications.log
 }
 main 2>/dev/null
 exit 0

package/hooks/post-compact.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 set +e
 main() {
-  [[ -d production/session-state ]] && echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] post-compact" >> production/session-state/sessions.log
+  [[ -d .claude/session-state ]] && echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] post-compact" >> .claude/session-state/sessions.log
 }
 main 2>/dev/null
 exit 0

package/hooks/pre-compact.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 set +e
 main() {
-  [[ -d production/session-state ]] && echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] pre-compact" >> production/session-state/sessions.log
+  [[ -d .claude/session-state ]] && echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] pre-compact" >> .claude/session-state/sessions.log
 }
 main 2>/dev/null
 exit 0

package/hooks/run-py.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Runs a Python hook from this folder: run-py.sh <script.py> [args...]
+#
+# Uses the first Python that actually starts (on Windows `python3` can be the
+# Microsoft Store stub, which exits non-zero instead of running). With no working
+# Python the hook does nothing.
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SCRIPT="$1"
+shift
+[ -f "$DIR/$SCRIPT" ] || exit 0
+INPUT=$(cat)
+
+for PY in python3 python py; do
+  command -v "$PY" >/dev/null 2>&1 || continue
+  if OUT=$(printf '%s' "$INPUT" | "$PY" "$DIR/$SCRIPT" "$@" 2>/dev/null); then
+    printf '%s' "$OUT"
+    exit 0
+  fi
+done
+exit 0

package/hooks/session-start.sh

@@ -3,13 +3,49 @@
 # Graceful: wraps in main(), never blocks session
 set +e
 
-main() {
-  mkdir -p production/session-state 2>/dev/null
+STATE_DIR=".claude/session-state"
+LEGACY_STATE_DIR="production/session-state"
+
+# The folder holds session notes, never project files: a .gitignore with `*` keeps it
+# out of every commit without touching the project's own .gitignore.
+ensure_state_dir() {
+  mkdir -p "$STATE_DIR" 2>/dev/null
+  [ -f "$STATE_DIR/.gitignore" ] || echo '*' > "$STATE_DIR/.gitignore" 2>/dev/null
+}
+
+# active.md used to live in production/session-state/. Move it once, so a task left
+# half done before the update still shows up here.
+migrate_legacy_state() {
+  [ -f "$LEGACY_STATE_DIR/active.md" ] || return 0
+  [ -f "$STATE_DIR/active.md" ] && return 0
+  ensure_state_dir
+  mv "$LEGACY_STATE_DIR/active.md" "$STATE_DIR/active.md" 2>/dev/null &&
+    echo "Moved $LEGACY_STATE_DIR/active.md to $STATE_DIR/active.md"
+}
 
-  SESSION_LOG="production/session-state/sessions.log"
-  echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] Session started" >> "$SESSION_LOG" 2>/dev/null
+# A session started inside a worktree should know it, and where the main checkout is.
+worktree_notice() {
+  local DIRS GIT_DIR COMMON_DIR TOP BRANCH MAIN MAIN_BRANCH
+  DIRS=$(git rev-parse --path-format=absolute --git-dir --git-common-dir 2>/dev/null) || return 0
+  GIT_DIR=$(echo "$DIRS" | sed -n 1p)
+  COMMON_DIR=$(echo "$DIRS" | sed -n 2p)
+  [ -z "$COMMON_DIR" ] || [ "$GIT_DIR" = "$COMMON_DIR" ] && return 0
+  TOP=$(git rev-parse --show-toplevel 2>/dev/null)
+  BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
+  MAIN=$(dirname "$COMMON_DIR")
+  MAIN_BRANCH=$(git -C "$MAIN" rev-parse --abbrev-ref HEAD 2>/dev/null)
+  echo "Worktree: you are in $TOP on branch $BRANCH."
+  echo "Main checkout: $MAIN on branch $MAIN_BRANCH. See the git-worktrees rule before pulling or switching branches."
+  echo ""
+}
+
+main() {
+  migrate_legacy_state
+  [ -d "$STATE_DIR" ] && ensure_state_dir
+  [ -d "$STATE_DIR" ] && echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] Session started" >> "$STATE_DIR/sessions.log" 2>/dev/null
 
   echo "=== Claude Code Arcane — Session Context ==="
+  worktree_notice
 
   BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
   if [ -n "$BRANCH" ]; then
@@ -55,7 +91,7 @@ main() {
     fi
   fi
 
-  STATE_FILE="production/session-state/active.md"
+  STATE_FILE="$STATE_DIR/active.md"
   if [ -f "$STATE_FILE" ]; then
     echo ""
     echo "=== ACTIVE SESSION STATE DETECTED ==="

package/hooks/session-stop.sh

@@ -1,7 +1,11 @@
 #!/usr/bin/env bash
 set +e
 main() {
-  [[ -d production/session-state ]] && echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] Session stopped" >> production/session-state/sessions.log
+  [[ -d .claude/session-state ]] || return 0
+  # Claude creates the folder the first time it writes active.md; keep it out of
+  # commits from that same turn on.
+  [[ -f .claude/session-state/.gitignore ]] || echo '*' > .claude/session-state/.gitignore
+  echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] Session stopped" >> .claude/session-state/sessions.log
 }
 main 2>/dev/null
 exit 0

package/hooks/session_watch.py

@@ -0,0 +1,278 @@
+#!/usr/bin/env python3
+"""Session watch: cheap, deterministic signals the model should not have to remember.
+
+`session_watch.py post-tool` (PostToolUse, every tool):
+  - records each file Claude edits, for the Stop check below;
+  - warns when the same tool runs with the same input 5 times in a row (a loop);
+  - warns once when a session has edited 15 files (scope drift);
+  - warns when the context passes 70% and 85% of the real window, so active.md is
+    brought up to date before a compaction. The window size comes from the status
+    line (statusline.sh caches what Claude Code reports); without it, no warning,
+    since guessing the window would warn far too early on 1M-token sessions.
+
+`session_watch.py stop` (Stop): formats the files edited this turn and type-checks
+them with the project's own tools (Prettier or Biome + tsc, gofmt + go vet,
+dotnet format). Only errors in files edited this turn block the stop, once, so
+errors the project already had never trap a session.
+
+State lives in .claude/session-state/watch-<session>.json, which ignores itself.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+
+LOOP_LENGTH = 5
+SCOPE_FILES = 15
+CONTEXT_WARNINGS = (70, 85)
+FILE_TOOLS = {"Write", "Edit", "MultiEdit", "NotebookEdit"}
+IGNORED_INPUT_KEYS = {"description", "timeout"}
+CHECK_TIMEOUT = 90
+MAX_REPORT_LINES = 25
+
+
+# --- state -------------------------------------------------------------------
+
+def state_dir(project: str) -> str:
+    path = os.path.join(project, ".claude", "session-state")
+    os.makedirs(path, exist_ok=True)
+    ignore = os.path.join(path, ".gitignore")
+    if not os.path.exists(ignore):
+        with open(ignore, "w", encoding="utf-8") as f:
+            f.write("*\n")
+    return path
+
+
+def load_state(project: str, session: str) -> dict:
+    path = os.path.join(state_dir(project), f"watch-{safe(session)}.json")
+    try:
+        with open(path, encoding="utf-8") as f:
+            return json.load(f)
+    except (OSError, ValueError):
+        return {}
+
+
+def save_state(project: str, session: str, state: dict) -> None:
+    path = os.path.join(state_dir(project), f"watch-{safe(session)}.json")
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(state, f)
+
+
+def safe(session: str) -> str:
+    return re.sub(r"[^A-Za-z0-9_-]", "", session or "default")[:64] or "default"
+
+
+# --- post-tool -----------------------------------------------------------------
+
+def post_tool(payload: dict, project: str) -> list[str]:
+    """Update the session state and return the warnings to show Claude."""
+    session = payload.get("session_id", "")
+    state = load_state(project, session)
+    warnings: list[str] = []
+    tool = payload.get("tool_name", "")
+    tool_input = payload.get("tool_input") or {}
+
+    if tool in FILE_TOOLS:
+        path = tool_input.get("file_path") or tool_input.get("notebook_path")
+        if path:
+            absolute = os.path.abspath(os.path.join(project, path))
+            pending = state.setdefault("pending", [])
+            if absolute not in pending:
+                pending.append(absolute)
+            edited = state.setdefault("edited", [])
+            if absolute not in edited:
+                edited.append(absolute)
+            if len(edited) >= SCOPE_FILES and not state.get("scope_warned"):
+                state["scope_warned"] = True
+                warnings.append(f"This session has edited {len(edited)} files. Check the change is still "
+                                "within the task's scope before going further.")
+
+    # The description is Claude's label for the call ("call 2 of 6"), not what runs.
+    action = {k: v for k, v in tool_input.items() if k not in IGNORED_INPUT_KEYS}
+    digest = hashlib.sha1(json.dumps([tool, action], sort_keys=True).encode()).hexdigest()
+    recent = (state.get("recent", []) + [digest])[-LOOP_LENGTH:]
+    state["recent"] = recent
+    if len(recent) == LOOP_LENGTH and len(set(recent)) == 1 and state.get("loop_warned") != digest:
+        state["loop_warned"] = digest
+        warnings.append(f"{tool} ran {LOOP_LENGTH} times in a row with the same input. Stop repeating it: "
+                        "name the assumption that may be wrong, or ask the user one diagnostic question.")
+
+    used = context_used(project, session)
+    if used is not None:
+        for level in CONTEXT_WARNINGS:
+            if used >= level and state.get("context_warned", 0) < level:
+                state["context_warned"] = level
+                warnings.append(f"Context is at {used:.0f}% of the window. At the next logical point "
+                                "(a commit, a finished step), update .claude/session-state/active.md if this "
+                                "task has one, then suggest the user run /compact.")
+                break
+
+    save_state(project, session, state)
+    return warnings
+
+
+def context_used(project: str, session: str) -> float | None:
+    """Percent of the real context window in use, as the status line last saw it."""
+    path = os.path.join(project, ".claude", "session-state", "context.json")
+    try:
+        with open(path, encoding="utf-8") as f:
+            data = json.load(f)
+    except (OSError, ValueError):
+        return None
+    if data.get("session_id") != session:
+        return None
+    try:
+        return float(data["used_percentage"])
+    except (KeyError, TypeError, ValueError):
+        return None
+
+
+# --- stop ----------------------------------------------------------------------
+
+def find_up(start: str, names: tuple[str, ...], stop_at: str) -> str | None:
+    """Nearest ancestor of `start` (up to `stop_at`) containing one of `names`."""
+    current = os.path.dirname(start)
+    stop_at = os.path.abspath(stop_at)
+    while True:
+        if any(os.path.exists(os.path.join(current, n)) for n in names):
+            return current
+        if os.path.abspath(current) == stop_at or os.path.dirname(current) == current:
+            return None
+        current = os.path.dirname(current)
+
+
+def local_bin(root: str, name: str) -> str | None:
+    """A tool installed in the project; never one npx would download."""
+    for folder in (root, os.path.dirname(root)):
+        base = os.path.join(folder, "node_modules", ".bin", name)
+        for candidate in ((base + ".cmd", base) if os.name == "nt" else (base,)):
+            if os.path.exists(candidate):
+                return candidate
+    return None
+
+
+def plan_checks(files: list[str], project: str) -> list[dict]:
+    """Group edited files by project root and pick the format and check commands."""
+    plans: dict[tuple, dict] = {}
+
+    def add(key: tuple, cwd: str, fmt: list | None, check: list | None, file: str) -> None:
+        plan = plans.setdefault(key, {"cwd": cwd, "format": fmt, "check": check, "files": []})
+        plan["files"].append(file)
+
+    for file in files:
+        if not os.path.exists(file):
+            continue
+        ext = os.path.splitext(file)[1].lower()
+        if ext in (".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".json", ".css", ".scss", ".md"):
+            root = find_up(file, ("package.json",), project)
+            if not root:
+                continue
+            fmt = None
+            biome = local_bin(root, "biome")
+            prettier = local_bin(root, "prettier")
+            if biome and any(os.path.exists(os.path.join(root, n)) for n in ("biome.json", "biome.jsonc")):
+                fmt = [biome, "format", "--write"]
+            elif prettier:
+                fmt = [prettier, "--write", "--log-level", "warn"]
+            check = None
+            if ext in (".ts", ".tsx"):
+                tsconfig = find_up(file, ("tsconfig.json",), project)
+                tsc = local_bin(root, "tsc")
+                if tsconfig and tsc:
+                    check = [tsc, "--noEmit", "--pretty", "false", "-p", os.path.join(tsconfig, "tsconfig.json")]
+            add(("node", root, tuple(check or ())), root, fmt, check, file)
+        elif ext == ".go" and shutil.which("gofmt"):
+            root = find_up(file, ("go.mod",), project)
+            if root:
+                rel = "./" + os.path.relpath(os.path.dirname(file), root).replace("\\", "/")
+                check = ["go", "vet", rel] if shutil.which("go") else None
+                add(("go", root, rel), root, ["gofmt", "-w"], check, file)
+        elif ext == ".cs" and shutil.which("dotnet"):
+            root = find_up(file, (".editorconfig",), project) or project
+            add(("dotnet", root), root, ["dotnet", "format", "whitespace", ".", "--folder", "--include"], None, file)
+    return list(plans.values())
+
+
+def run(command: list[str], cwd: str) -> tuple[int, str]:
+    try:
+        result = subprocess.run(command, cwd=cwd, capture_output=True, text=True,
+                                timeout=CHECK_TIMEOUT, encoding="utf-8", errors="replace")
+        return result.returncode, (result.stdout or "") + (result.stderr or "")
+    except (OSError, subprocess.TimeoutExpired) as error:
+        return 0, f"skipped: {error}"
+
+
+def errors_in(output: str, files: list[str], cwd: str) -> list[str]:
+    """Error lines that name one of `files`; errors elsewhere predate this turn."""
+    wanted = {os.path.normcase(os.path.abspath(f)) for f in files}
+    lines = []
+    for line in output.splitlines():
+        match = re.match(r"^(.+?)(?:\(\d+,\d+\)|:\d+:\d+)", line.strip())
+        if not match:
+            continue
+        candidate = os.path.normcase(os.path.abspath(os.path.join(cwd, match.group(1).strip())))
+        if candidate in wanted:
+            lines.append(line.strip())
+    return lines
+
+
+def stop(payload: dict, project: str) -> dict | None:
+    session = payload.get("session_id", "")
+    state = load_state(project, session)
+    files = state.pop("pending", [])
+    save_state(project, session, state)
+    if not files or payload.get("stop_hook_active"):
+        return None
+
+    problems: list[str] = []
+    for plan in plan_checks(files, project):
+        if plan["format"]:
+            run(plan["format"] + plan["files"], plan["cwd"])
+        if plan["check"]:
+            code, output = run(plan["check"], plan["cwd"])
+            if code != 0:
+                problems.extend(errors_in(output, plan["files"], plan["cwd"]))
+    if not problems:
+        return None
+    shown = problems[:MAX_REPORT_LINES]
+    more = f"\n... and {len(problems) - len(shown)} more" if len(problems) > len(shown) else ""
+    return {
+        "decision": "block",
+        "reason": "The type check found errors in files you edited this turn. Fix them before finishing:\n"
+                  + "\n".join(shown) + more,
+    }
+
+
+# --- entry point ---------------------------------------------------------------
+
+def main() -> int:
+    mode = sys.argv[1] if len(sys.argv) > 1 else ""
+    try:
+        payload = json.loads(sys.stdin.read() or "{}")
+    except ValueError:
+        return 0
+    project = os.environ.get("CLAUDE_PROJECT_DIR") or payload.get("cwd") or os.getcwd()
+    if mode == "post-tool":
+        warnings = post_tool(payload, project)
+        if warnings:
+            print(json.dumps({"hookSpecificOutput": {
+                "hookEventName": "PostToolUse",
+                "additionalContext": "Arcane session watch: " + " ".join(warnings),
+            }}))
+    elif mode == "stop":
+        decision = stop(payload, project)
+        if decision:
+            print(json.dumps(decision))
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except Exception:  # a watch bug must never break the session
+        sys.exit(0)

package/hooks/statusline.sh

@@ -75,6 +75,21 @@ if isinstance(cw, dict) and cw:
             pct = float(up)
         except Exception:
             pct = None
+    # Hooks never see the window size; session_watch.py reads it from here to warn
+    # before a compaction at a share of the real window instead of a guessed one.
+    project_dir = (data.get("workspace") or {}).get("project_dir") or data.get("cwd") or ""
+    if pct is not None and project_dir and os.path.isdir(os.path.join(project_dir, ".claude")):
+        try:
+            state = os.path.join(project_dir, ".claude", "session-state")
+            os.makedirs(state, exist_ok=True)
+            ignore = os.path.join(state, ".gitignore")
+            if not os.path.exists(ignore):
+                open(ignore, "w").write("*\n")
+            with open(os.path.join(state, "context.json"), "w") as f:
+                json.dump({"session_id": data.get("session_id"), "used_percentage": pct,
+                           "context_window_size": limit}, f)
+        except Exception:
+            pass
 
 # Fallback (older Claude Code without context_window): scan transcript usage.
 if total is None:

package/hooks/worktree-stop.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# Hook: worktree-stop.sh — Stop
+#
+# A session that enters a worktree with EnterWorktree tends to stay there after the
+# task is done, and the next pull or branch switch fails inside it. When the turn
+# ends inside such a worktree with everything committed, block the stop once and ask
+# Claude to leave with ExitWorktree (keep), or to say the task continues.
+#
+# Fires once per commit: a new commit means new progress, so it may ask again.
+# Never fires when the session itself started inside the worktree (ExitWorktree
+# could not leave it) or while there are uncommitted changes (work in progress).
+set +e
+
+main() {
+  local INPUT PROJECT TOP BRANCH HEAD MARKER_DIR MARKER REASON
+  INPUT=$(cat 2>/dev/null)
+  # Second stop of the same turn: Claude already answered the block.
+  echo "$INPUT" | grep -qE '"stop_hook_active"[[:space:]]*:[[:space:]]*true' && return 0
+
+  PROJECT="${CLAUDE_PROJECT_DIR:-}"
+  [ -n "$PROJECT" ] || return 0
+  TOP=$(git rev-parse --show-toplevel 2>/dev/null) || return 0
+
+  # Only worktrees EnterWorktree creates: under the project the session started in.
+  case "$TOP" in
+    "$PROJECT"/.claude/worktrees/*) ;;
+    *) return 0 ;;
+  esac
+
+  [ -z "$(git status --porcelain 2>/dev/null)" ] || return 0
+
+  BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
+  HEAD=$(git rev-parse HEAD 2>/dev/null)
+  MARKER_DIR="$PROJECT/.claude/session-state"
+  MARKER="$MARKER_DIR/.worktree-stop"
+  [ "$(cat "$MARKER" 2>/dev/null)" = "$TOP $HEAD" ] && return 0
+  mkdir -p "$MARKER_DIR" 2>/dev/null
+  [ -f "$MARKER_DIR/.gitignore" ] || echo '*' > "$MARKER_DIR/.gitignore"
+  echo "$TOP $HEAD" > "$MARKER"
+
+  REASON="You are still inside the worktree $TOP (branch $BRANCH) and its changes are committed. If the task is finished, push the branch if the task included pushing, then leave with ExitWorktree (action: keep) and tell the user the worktree path and branch. If the task continues, say so in one line and stop."
+  REASON=${REASON//\\/\/}
+  REASON=${REASON//\"/\'}
+  printf '{"decision": "block", "reason": "%s"}\n' "$REASON"
+}
+
+main
+exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-arcane",
-  "version": "2.13.0",
+  "version": "2.15.0",
   "description": "Skills, agents, hooks and rules for Claude Code — installable via npx claude-code-arcane",
   "type": "module",
   "bin": {

package/profiles/core.yaml

@@ -57,6 +57,8 @@ hooks:
   - pre-compact.sh
   - post-compact.sh
   - session-stop.sh
+  - worktree-stop.sh
+  - run-py.sh
   - log-agent.sh
   - log-agent-stop.sh
 

package/rules/implementation-workflow.md

@@ -39,6 +39,30 @@ Use AskUserQuestion exactly like this:
 - **Goal-driven:** Help the user define a verifiable goal statement and 2-4 checkpoints, create tasks, implement toward each checkpoint. No formal plan.
 - **Directo:** Proceed immediately without ceremony.
 
+## Progress file
+
+In **Plan + Goal** and **Goal-driven** mode, keep `.claude/session-state/active.md` up to date. A compaction or a new session loses the conversation, not this file: `session-start.sh` shows its first lines when a session starts and after every compaction.
+
+- **Create it** when the goal is set. If `.claude/session-state/` does not exist yet, create it with a `.gitignore` containing `*`, so the file never lands in a commit.
+- **Update it** at every checkpoint, and always before a compaction.
+- **Close it** when the task ends: set `Status: closed` and record the final verification result.
+- Keep it under 30 lines:
+
+```markdown
+# <task>
+Status: in progress | closed
+Goal: <verifiable outcome>
+Criteria: <how we know it is done>
+Plan:
+- [x] <step done>
+- [ ] <step pending>
+Decisions: <decision> — <why>
+Next: <the next concrete step>
+Not verified: <what has not been checked yet>
+```
+
+Directo and Action Plan tasks do not need it.
+
 ## Before writing new code
 
 In every mode, search in this order and take the first option that fully works:

package/skills/help/SKILL.md

@@ -14,7 +14,7 @@ model: haiku
 
 - Stage: !`cat production/stage.txt 2>/dev/null | tr -d '[:space:]' || echo 'not set'`
 - Latest sprint: !`ls -t production/sprints/*.md 2>/dev/null | head -1 || echo 'none'`
-- Session state: !`head -5 production/session-state/active.md 2>/dev/null || echo 'none'`
+- Session state: !`head -5 .claude/session-state/active.md 2>/dev/null || echo 'none'`
 
 Read-only skill — reports findings, writes no files. Lightweight orientation; for a formal readiness check use `/gate-check`.
 
@@ -29,7 +29,7 @@ Read `.claude/docs/workflow-catalog.yaml` (authoritative phases/steps). Glob `.c
 
 ## Step 3: Read Session Context
 
-Read `production/session-state/active.md` — what was most recently worked on, in-progress tasks, open questions.
+Read `.claude/session-state/active.md` — what was most recently worked on, in-progress tasks, open questions.
 
 ## Step 4: Check Step Completion
 

package/skills/start/SKILL.md

@@ -12,7 +12,7 @@ Entry point para sesiones nuevas. Detecta contexto, hace preguntas clave, rutea
 
 ## Paso 1: Detectar contexto
 
-Escanear en paralelo: Unity (`ProjectSettings/ProjectVersion.txt`), Unreal (`*.uproject`), Web/Node (`package.json`), Go (`go.mod`), Python (`pyproject.toml`/`requirements.txt`), Flutter (`pubspec.yaml`), Rust (`Cargo.toml`), docs (`README.md`, `CLAUDE.md`, `design/`, `docs/`), session state (`production/session-state/active.md`).
+Escanear en paralelo: Unity (`ProjectSettings/ProjectVersion.txt`), Unreal (`*.uproject`), Web/Node (`package.json`), Go (`go.mod`), Python (`pyproject.toml`/`requirements.txt`), Flutter (`pubspec.yaml`), Rust (`Cargo.toml`), docs (`README.md`, `CLAUDE.md`, `design/`, `docs/`), session state (`.claude/session-state/active.md`).
 
 ## Paso 2: Determinar etapa
 
@@ -45,7 +45,7 @@ AskUserQuestion multi-tab:
 
 ## Paso 5: Set session state
 
-Crear `production/session-state/active.md`: project name, division, stage, user role, next action, stack detected, existing artifacts, recommended flow (3 commands).
+Crear `.claude/session-state/active.md`: project name, division, stage, user role, next action, stack detected, existing artifacts, recommended flow (3 commands).
 
 ## Paso 6: First action
 

package/skills/story-done/SKILL.md

@@ -12,7 +12,7 @@ Closes loop between design and implementation. Verifies acceptance criteria, che
 
 ## Phase 1: Find Story
 
-Resolve review mode: `--review` arg → `production/review-mode.txt` → default `lean`. Story source: arg path → `production/session-state/active.md` → most recent sprint file (IN PROGRESS stories) → AskUserQuestion.
+Resolve review mode: `--review` arg → `production/review-mode.txt` → default `lean`. Story source: arg path → `.claude/session-state/active.md` → most recent sprint file (IN PROGRESS stories) → AskUserQuestion.
 
 ## Phase 2: Read Story
 
@@ -55,7 +55,7 @@ BLOCKED → do not proceed, list fixes, offer help.
 
 ## Phase 7: Update Story
 
-Ask approval → edit story: `Status: Complete` + `## Completion Notes` (date, criteria, deviations, test evidence, code review status). Advisory deviations → offer to log in `docs/tech-debt-register.md`. Update `production/sprint-status.yaml` if exists. Append to `production/session-state/active.md`.
+Ask approval → edit story: `Status: Complete` + `## Completion Notes` (date, criteria, deviations, test evidence, code review status). Advisory deviations → offer to log in `docs/tech-debt-register.md`. Update `production/sprint-status.yaml` if exists. Append to `.claude/session-state/active.md`.
 
 ## Phase 8: Surface Next Story
 

package/skills/ux-design/SKILL.md

@@ -38,7 +38,7 @@ If output file exists → read it, show section status table (Complete/Empty/Pla
 
 ## Skeleton Creation
 
-Create output file with `[To be designed]` placeholders for all sections. Update `production/session-state/active.md`.
+Create output file with `[To be designed]` placeholders for all sections. Update `.claude/session-state/active.md`.
 
 > → Read references/spec-sections.md for [section inventories for UX spec, HUD, pattern library, and key section guidance]