From ec5d68a5a1f64f5e78c7705840c1ce675c697a78 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Tue, 18 Aug 2026 09:48:22 -0700 Subject: [PATCH] docs: update project documentation for v1.68.1.0 README: document canonical-only hook registration + the prune-stale self-heal in the setup hooks section; expand the manual-uninstall note to cover every gstack hook identity, not just timeline-stop-hook. CONTRIBUTING: record PT_EXPLICIT provenance (Conductor auto-opt-in fires only on the true silent fall-through) and the heal-first repair exception in the dev-setup paragraph. Co-Authored-By: Claude Fable 5 --- CONTRIBUTING.md | 2 +- README.md | 18 +++++++++++++++--- 2 files changed, 16 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d69b538fc..a85deba64 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -430,7 +430,7 @@ If you're using [Conductor](https://conductor.build) to run multiple Claude Code When Conductor creates a new workspace, `bin/dev-setup` runs automatically. It detects the main worktree (via `git worktree list`), copies your `.env` so API keys carry over, and sets up dev mode — no manual steps needed. -`bin/dev-setup` runs `./setup` fully non-interactively (it passes `--plan-tune-hooks=prompt` and closes stdin), so a forwarded Conductor TTY can never hang on a hidden setup prompt. It also never installs the plan-tune Claude Code hooks, which means a throwaway workspace can't rewrite your global `~/.claude/settings.json` to point at an ephemeral worktree path. To install the plan-tune hooks deliberately, run `./setup --plan-tune-hooks` outside dev-setup (or `gstack-config set plan_tune_hooks yes`). +`bin/dev-setup` runs `./setup` fully non-interactively (it passes `--plan-tune-hooks=prompt` and closes stdin), so a forwarded Conductor TTY can never hang on a hidden setup prompt. It also never installs the plan-tune Claude Code hooks, which means a throwaway workspace can't rewrite your global `~/.claude/settings.json` to point at an ephemeral worktree path. To install the plan-tune hooks deliberately, run `./setup --plan-tune-hooks` outside dev-setup (or `gstack-config set plan_tune_hooks yes`). The explicit flag counts as an explicit decision: setup's Conductor auto-opt-in for AskUserQuestion hooks fires only on the true silent fall-through (no flag, no `GSTACK_PLAN_TUNE_HOOKS` env var, no `plan_tune_hooks` key literally present in config, checked via `gstack-config has`), so it can never override dev-setup into installing hooks. One stated repair exception: setup's heal-first pass (`gstack-settings-hook prune-stale --repoint`) may prune dead gstack hook entries and re-point existing ones at the stable `~/.claude/skills/gstack` install. That is strictly convergent repair, never a new registration, and registration itself is canonical-only, so an ephemeral tree path can never be baked into settings.json. **First-time setup:** Put your `ANTHROPIC_API_KEY` in `.env` in the main repo (see `.env.example`). Every Conductor workspace inherits it automatically. diff --git a/README.md b/README.md index f1534590f..ca39f7ab6 100644 --- a/README.md +++ b/README.md @@ -261,6 +261,14 @@ a session). Skip it with `./setup --no-team`, remove it with `gstack-settings-hook remove-source --source gstack-timeline-stop`; `gstack-uninstall` removes it too. +Hook registration is canonical-only: every hook command points at the stable +`~/.claude/skills/gstack` install, never the tree setup ran from, so deleting +a worktree or Conductor workspace can't leave dead hooks erroring in your +sessions. Every `./setup` run also heals first: `gstack-settings-hook +prune-stale --repoint` removes dead gstack hook entries, re-points stale ones +at the stable install, and collapses duplicates, printing one line (and +writing a backup beside the file) only when it changed something. + ### Continuous checkpoint mode (opt-in, local by default) Set `gstack-config set checkpoint_mode continuous` and skills auto-commit your work as you go with a `WIP:` prefix plus a structured `[gstack-context]` body (decisions, remaining work, failed approaches). Survives crashes and context switches. `/context-restore` reads those commits to reconstruct session state. `/ship` filter-squashes WIP commits before the PR (preserving non-WIP commits) so bisect stays clean. Push is opt-in via `checkpoint_push=true` — default is local-only so you don't trigger CI on every WIP commit. @@ -388,9 +396,13 @@ rm -rf .gstack .gstack-worktrees .claude/skills/gstack 2>/dev/null rm -rf .agents/skills/gstack* .factory/skills/gstack* 2>/dev/null ``` -Manual removal leaves the gstack Stop hook entry behind in `~/.claude/settings.json` -(the uninstall script removes it for you). Edit that file and delete the hook whose -command path ends in `hosts/claude/hooks/timeline-stop-hook`. +Manual removal leaves gstack's hook entries behind in `~/.claude/settings.json` +(the uninstall script removes all of them for you, including entries whose +`_gstack_source` tag was stripped). Edit that file and delete every hook whose +command path points into `.claude/skills/gstack/`: the SessionStart auto-update +hook, the AskUserQuestion PreToolUse/PostToolUse hooks, and the Stop hooks +(session timeline, plus verify-gate if you opted in). Left in place, they error +on every matching event once the install directory is gone. ### Clean up CLAUDE.md