Wip Branch Guard

Enforces branch discipline by blocking disallowed writes and destructive commands, requires onboarding docs read before first write, tracks retry attempts, a...

Security Scan

The skill's code, documentation, and runtime instructions are internally consistent with its stated purpose (a local pre-tool-use hook that enforces branch/write rules and records a local audit); it does not request unrelated credentials or download remote code.

Purpose & Capability

Name/description (branch/write guard) match the included files and SKILL.md: guard.mjs implements PreToolUse + SessionStart policies, test.sh exercises them, and docs describe installing the script as a local hook. There are no unrelated required binaries, env secrets, or external services declared.

Instruction Scope

Runtime instructions expect the guard to be invoked as a PreToolUse/SessionStart hook and describe reading repo onboarding files, parsing tool commands, denying writes, and maintaining per-session state and an append-only bypass-audit file under ~/.ldm/state/. Those actions are appropriate for a local guard, but they do involve reading repo files and writing state/audit files in the user's home directory — review/accept that behavior before installing.

Install Mechanism

No automated install spec or remote downloads are present. INSTALL.md instructs a local copy into ~/.ldm/extensions and an edit to ~/.claude/settings.json to register the hook. This is low-risk compared with arbitrary network installs; the code runs locally when the hook is invoked.

Credentials

The package declares no required env vars or credentials. SKILL.md documents optional operator env toggles (LDM_GUARD_UPSTREAM_PR_APPROVED, LDM_GUARD_APPROVAL_BACKEND, LDM_GUARD_STATE_DIR) used for overrides or testing. None are secret API keys; their presence is proportional to the described override/audit features.

Persistence & Privilege

Installation requires placing guard.mjs under ~/.ldm/extensions and registering it in ~/.claude/settings.json so it runs on PreToolUse and SessionStart. The guard will therefore run frequently and will create/read per-session state and an audit log under ~/.ldm/state/. This persistence and hook-level access are expected for its purpose but give it the ability to intercept tool calls and write local state — review and consent to that placement.

Assessment

This skill appears to do exactly what it says: a local hook that blocks destructive git/file writes and records an audit. Before installing: (1) inspect guard.mjs yourself (it runs locally and will be executed by your hook), (2) be aware it will be registered in your ~/.claude/settings.json and will write/read files under ~/.ldm/state/ and may emit boot-time advisories, (3) run the included test.sh in a safe sandbox if you can, and (4) note the operator override envs (especially LDM_GUARD_UPSTREAM_PR_APPROVED) — those can be used to bypass targeted PR-create blocks and should be set only by a trusted operator. If you don't want a hook with persistent state and hook privileges, do not copy it into your extensions/hooks.

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