wip-branch-guard

name	wip-branch-guard
description	PreToolUse hook that enforces branch discipline, blocks destructive commands, requires repo onboarding before first write, tracks blocked-file retries, and gates PR creation against external repos. Read when: a tool call was denied by the guard, or you're about to make the first write in a new repo, or an agent is setting up a new Claude Code / OpenClaw install.

wip-branch-guard

Runtime enforcement of the WIP Computer development workflow. Installed as a PreToolUse hook for Claude Code and as an OpenClaw plugin. Same rules, same deny messages on both harnesses.

Layer 1 ... write gate

Context	Writes (Write/Edit/NotebookEdit/Bash-write)
On main branch of a git repo	Denied
On a feature branch, NOT in a linked worktree	Denied
On a feature branch, IN a linked worktree	Allowed
Shared-state paths (see below)	Always allowed
Not in any git repo	Allowed

Shared-state paths (always allowed): ~/.claude/plans/, ~/.claude/projects/*/memory/, ~/.claude/rules/, ~/.openclaw/workspace/, ~/.openclaw/extensions/, ~/.ldm/shared/, ~/.ldm/messages/, ~/.ldm/templates/, ~/.ldm/extensions/, ~/.ldm/logs/, ~/.ldm/agents/*/memory/daily/*.md, ~/.ldm/memory/shared-log.jsonl, ~/.ldm/memory/daily/*.md, workspace/SHARED-CONTEXT.md, workspace/TOOLS.md, workspace/MEMORY.md, workspace/IDENTITY.md, workspace/SOUL.md, workspace/WHERE-TO-WRITE.md, workspace/HEARTBEAT.md, workspace/memory/*.md, CLAUDE.md.

Worktree convention: .worktrees/<repo>--<branch>/. Bootstrap compound (git worktree add .worktrees/... && mkdir -p .../ai/... && cp src dest) is explicitly allowed.

Layer 2 ... destructive-command block (any branch)

Always denied regardless of branch:

• git clean -f* (deletes untracked)
• git checkout -- <path> (reverts files)
• git checkout . (reverts everything)
• git stash drop / pop / clear (destroys stashed work)
• git reset --hard (nukes uncommitted changes)
• git restore <path> (reverts files; --staged is safe and allowed)
• python -c "open().write()" / node -e "writeFile()" (scripting-language write bypass)
• --no-verify (skips git hooks)
• git push --force without --force-with-lease

Quoted content is stripped before matching so gh issue create --body 'use git checkout -- to fix' is allowed.

Layer 3 ... session-level gates (new in 1.9.77)

1. Onboarding-before-first-write

Before the first write to any git repo in a session, the guard requires the agent to have Read specific onboarding docs at the repo root. The check auto-populates from Read tool calls on the hook matcher (Read|Glob|Write|Edit|NotebookEdit|Bash).

Required reads: README.md, CLAUDE.md, and anything matching *RUNBOOK*.md, *LANDMINES*.md, WORKFLOW*.md at repo root.

TTL: 2 hours of activity once onboarded. Fresh session or inactivity expires the cache.

Expected ritual for any repo new to your session:

1. git rev-parse --show-toplevel   # confirm the repo
2. Read README.md                  # via Read tool, not cat
3. Read CLAUDE.md                  # if present
4. Read RUNBOOK / LANDMINES / WORKFLOW  # if present at root
5. Proceed with Write/Edit

No override. Pre-v1.9.82 an LDM_GUARD_SKIP_ONBOARDING env var could bypass this gate. It was removed in v1.9.82 along with the cross-session state-file bug that made it necessary. Actually reading the docs is the only path through.

2. Recently-blocked-file tracking

Every time the guard denies a write to a specific file, it records {ts, path, tool, command_stripped} to the session's recent-denials tail (last 20 entries, 1-hour window). If a subsequent file-writing tool call targets the same path, the guard denies again with prior-block context.

This catches the pattern: Edit X → denied → agent retries with cat > X via Bash. The second attempt is caught as "equivalent-action bypass" even if the Bash command itself would otherwise be allowed.

No override. Pre-v1.9.82 an LDM_GUARD_ACK_BLOCKED_FILE env var could acknowledge-and-continue on a blocked-file retry. Removed in v1.9.82. If the original block was wrong, fix the underlying cause (not the block).

3. External-PR create guard (new in 1.9.80)

Denied:

• gh pr create --repo <non-wipcomputer>/<repo>
• gh pr create --repo <non-wipcomputer>/<repo> --head <fork>:<branch> (cross-fork)
• gh pr create [--web] when the cwd's git origin is <non-wipcomputer>/<repo>
• gh api repos/<non-wipcomputer>/<repo>/pulls ... -X POST

Allowed:

• Same commands when owner is wipcomputer/
• gh pr view, gh pr list, gh pr merge, gh pr edit against any repo (read/interact, not create)
• gh api repos/<owner>/<repo>/issues ... -X POST (issues, not pulls)

Triggered by the 2026-04-18 PR #89 incident where an agent opened a PR directly against steipete/imsg without approval.

Override: LDM_GUARD_UPSTREAM_PR_APPROVED=<owner>/<repo> (target-specific) or =1 (blanket for the current process).

Override env vars

Overrides are routed through the inlined approval backend. Every use is recorded in the bypass audit log.

Env var	Applies to	Value shape
LDM_GUARD_UPSTREAM_PR_APPROVED	External-PR guard	<owner>/<repo> or 1
LDM_GUARD_APPROVAL_BACKEND	Backend selector	env (default). Future: bridge, kaleidoscope-biometric.
LDM_GUARD_STATE_DIR	State file redirect	dir path. Tests only.

Removed in v1.9.82: LDM_GUARD_SKIP_ONBOARDING and LDM_GUARD_ACK_BLOCKED_FILE. Both existed as escape hatches for a cross-session state-collision bug that v1.9.82 fixes at the root. With the bug gone, the escape hatches just train agents to route around the guard instead of fixing its misbehavior. If either env var is set now, the guard ignores it.

Default stance: don't bypass. The block message tells you exactly what to do. The one remaining override (LDM_GUARD_UPSTREAM_PR_APPROVED) exists for scope-specific operator authorization of a specific external PR, not routine workaround.

Bypass audit log

~/.ldm/state/bypass-audit.jsonl, append-only JSON Lines:

{"kind":"deny","ts":1776780123456,"session_id":"...","tool":"Edit","path":"/abs/path","command_stripped":"...","reason":"BLOCKED: ..."}
{"kind":"skip-onboarding-approved","ts":...,"session_id":"...","path":"<repo>","via":"env","reason":"LDM_GUARD_SKIP_ONBOARDING set"}
{"kind":"external-pr-create-approved","ts":...,"session_id":"...","target":"owner/repo","via":"env","reason":"..."}

Rotates to bypass-audit.jsonl.YYYY-MM-DD at 50 MB. Keep last 10 archives.

Session state

Per-session file (v1.9.82+): ~/.ldm/state/guard-session-<session_id>.json. One file per CC session. Pruned after 24 hours of inactivity.

{
  "session_id": "...",
  "started_at": 1776700000000,
  "last_touch_ts": 1776700500000,
  "read_files": ["/abs/path/README.md", "/abs/path/CLAUDE.md"],
  "onboarded_repos": {
    "/abs/repo/path": { "onboarded_at_ts": ..., "last_touch_ts": ... }
  },
  "recent_denials": [
    { "ts": ..., "path": "...", "tool": "Edit", "command_stripped": "..." }
  ]
}

Each session's state is independent of every other session's. Writes are serialized within a session via a lockfile (guard-session-<sid>.json.lock) to prevent parallel tool calls from clobbering each other. Atomic tmp-file + rename. Never edit directly; the guard owns this file.

Pre-v1.9.82 legacy: the guard used a single global ~/.ldm/state/guard-session.json. Every CC session wrote to it with its own session_id, triggering a full state reset on every session switch. That file is ignored by v1.9.82+ and can be deleted safely.

SessionStart warning

Separate hook event. When a session starts in the main working tree of a protected repo, the guard injects a warning into boot context listing available worktrees + the stash escape-hatch. Non-blocking; just informational.

When the guard errors on import (fail-open)

If guard.mjs fails to load (missing module, syntax error), Claude Code treats the hook as fail-open ... tools proceed unguarded. This is a safety failure mode and should be caught by:

1. The matcher-containing static test (bash test.sh).
2. Smoke-tests after every ldm install.

If you suspect fail-open, probe directly:

echo '{"tool_name":"Bash","tool_input":{"command":"echo test"}}' | node ~/.ldm/extensions/wip-branch-guard/guard.mjs

Empty output = allow (fine). Any error = broken guard (file an issue + roll back to a prior version via ldm install /tmp/toolbox-at-old-tag).

Recovery: installer-as-escape-hatch

The guard can cliff-block its own fix. When that happens, roll back via the installer:

git -C <wip-ai-devops-toolbox-private> worktree add /tmp/toolbox-old <pre-problematic-tag>
ldm install /tmp/toolbox-old --yes

The installer writes a pre-fix guard to ~/.ldm/extensions/. Source edits are then unblocked. Fix the underlying issue, ship the new version, reinstall.

Version history (today)

• 1.9.76: worktree-bootstrap allowlist
• 1.9.77: Layer 3 core (shipped with a dead-code bug; the Read handler never fired because the matcher omitted Read)
• 1.9.78: hotfix, inlined lib/*.mjs into guard.mjs after an installer bug dropped the lib/ subdir
• 1.9.79: added Read|Glob to the matcher so the Read handler actually runs
• 1.9.80: external-PR create guard
• 1.9.81: canonical repo key (onboarding shared across worktrees)
• 1.9.82: per-session state files (fix cross-session state wipe), lockfile-based atomic writes, removed LDM_GUARD_SKIP_ONBOARDING + LDM_GUARD_ACK_BLOCKED_FILE env-var bypasses

Related

• Plan: wip-ldm-os-private/ai/product/bugs/guard/2026-04-20--cc-mini--guard-implementation-plan.md
• Spec (onboarding): wip-ldm-os-private/ai/product/bugs/guard/2026-04-19--cc-mini--guard-onboarding-and-blocked-file-tracking.md
• Spec (external-PR): wip-ldm-os-private/ai/product/bugs/guard/2026-04-19--cc-mini--external-pr-guard.md
• Triggering incident: wip-ldm-os-private/ai/product/bugs/code/lesa/2026-04-19--cc-mini--pr-89-process-violation-postmortem.md