@reddb-io/red-skills 4.4.0 → 4.5.0

package/runtime/plugins/dev/skills/misc/branch-lock/scripts/branch-lock-hook.sh

@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+# branch-lock-hook.sh — PreToolUse(Bash) hook that blocks the agent from
+# switching away from the locked branch. Self-contained: composes the three
+# pure modules (lock-store, scope-resolver, git-command-classifier) into one
+# allow/block verdict, with no dependency on the git-guardrails skill.
+#
+# Reads the Claude Code PreToolUse payload on stdin, extracts the Bash command,
+# and:
+#   1. resolves the project root (CLAUDE_PROJECT_DIR, else the git toplevel);
+#   2. exits 0 (allow) when the checkout is an /afk worktree — scope exemption;
+#   3. exits 0 (allow) when no lock file is present — unlocked is the default;
+#   4. classifies the command; on "block" prints a clear message to stderr and
+#      exits 2 (the Claude Code convention for "deny this tool call").
+#
+# Any verdict other than block is a silent exit 0, so the hook never adds noise
+# to allowed commands.
+
+set -uo pipefail
+
+allow() {
+  printf '{}'
+  exit 0
+}
+
+deny() {
+  local reason="$1"
+  printf '%s\n' "$reason" >&2
+  jq -nc --arg reason "$reason" '{
+    decision: "block",
+    reason: $reason,
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: $reason
+    }
+  }'
+  exit 0
+}
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/lock-store.sh
+source "$HERE/lib/lock-store.sh"
+# shellcheck source=lib/scope-resolver.sh
+source "$HERE/lib/scope-resolver.sh"
+# shellcheck source=lib/git-command-classifier.sh
+source "$HERE/lib/git-command-classifier.sh"
+# shellcheck source=lib/dev-config.sh
+source "$HERE/lib/dev-config.sh"
+
+INPUT="$(timeout "${RED_SKILLS_HOOK_STDIN_TIMEOUT_S:-5s}" cat 2>/dev/null || true)"
+COMMAND="$(jq -r '.tool_input.command // empty' <<<"$INPUT" 2>/dev/null)"
+[[ -z "$COMMAND" ]] && allow
+
+# Project root: prefer the harness-provided dir, fall back to the git toplevel.
+ROOT="${CLAUDE_PROJECT_DIR:-}"
+if [[ -z "$ROOT" ]]; then
+  ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+fi
+[[ -z "$ROOT" ]] && allow
+
+# Per-directory plugin gate (ADR 0067): the dev plugin's hooks are installed
+# globally but must stay fully inert in any repo that did not opt in. Exit before
+# any lock/scope work unless `plugins.dev.enabled: true` is set here.
+dev_plugin_enabled "$ROOT/.red/config.yaml" || allow
+
+# Scope: /afk worktrees are exempt even when a lock is active.
+scope_should_enforce "$ROOT" || allow
+
+# Untouchable primary (ADR 0083 §2): an agent may never move the primary
+# checkout's branch. This block is unconditional — it no longer arms with the
+# `dev.lock.primary-branch` toggle (which stays readable for backward
+# compatibility but can no longer *enable* switching; /red-doctor may flag it as
+# redundant). Human terminals are unaffected: this is an agent-only pre-tool hook
+# (ADR 0006).
+if [[ "$(classify_primary_branch_switch_guard "$COMMAND")" == "block" ]]; then
+  deny "$(cat <<EOF
+BLOCKED by the untouchable-primary rule (ADR 0083): an agent can never switch
+the primary checkout's branch or destroy work in it, regardless of
+configuration or lock state. The command '$COMMAND' would move the agent's
+primary checkout to another branch or destroy work in it (branch switch,
+'git reset' in any form, 'git stash', or 'git rebase --autostash'). Parallel
+human WIP lives in this primary checkout, and these commands have destroyed
+in-progress work before.
+
+Do branch work in an isolated worktree under .red/tmp/worktrees/manual/<slug> instead
+('git worktree add .red/tmp/worktrees/manual/<slug> -b <branch> origin/main'). If the local
+trunk diverged from origin, leave it alone and base on the fresh remote ref
+(ADR 0083) — never reset or stash the primary to reconcile it.
+
+Allowed in the primary checkout: git commit, git worktree add, read-only git,
+and other non-destructive commands. To change the primary branch, ask the user.
+EOF
+  )"
+fi
+
+LOCKFILE="$ROOT/.red/tmp/branch-lock.yaml"
+LOCK_BRANCH="$(lock_store_read "$LOCKFILE")" || allow   # absent => unlocked
+
+if [[ "$(classify_git_command "$LOCK_BRANCH" "$COMMAND")" == "block" ]]; then
+  deny "$(cat <<EOF
+BLOCKED by branch lock: this session is locked to '$LOCK_BRANCH'.
+The command '$COMMAND' would switch the agent away from the locked branch or
+discard working-tree changes (stash, clean -f, reset --hard, whole-tree restore).
+
+Allowed while locked: switching back to '$LOCK_BRANCH', targeted file restore
+('git checkout -- <path>', 'git restore <path>'), read-only stash, dry-run clean,
+soft/mixed reset, and 'git worktree add'. To change or release the lock, ask the
+user — they drive it with '/branch-lock <branch>' or '/branch-lock clear'.
+EOF
+  )"
+fi
+
+allow

package/runtime/plugins/dev/skills/misc/branch-lock/scripts/branch-lock-session-start.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# branch-lock-session-start.sh — SessionStart hook that offers, once at session
+# start, to lock the agent to the current branch. Self-contained: reuses the
+# same two pure modules as the PreToolUse hook (lock-store, scope-resolver) so
+# the prompt obeys the exact same scope rule as enforcement.
+#
+# On SessionStart it:
+#   1. resolves the project root (CLAUDE_PROJECT_DIR, else the git toplevel);
+#   2. stays silent (exit 0, no output) inside an /afk worktree — the lock
+#      protects the interactive primary checkout, never the autonomous loop;
+#   3. stays silent when a lock is already present — nothing to offer;
+#   4. stays silent on a detached HEAD — there is no branch to lock;
+#   5. otherwise emits a SessionStart additionalContext block instructing the
+#      agent to ask the user whether to lock to the current branch before doing
+#      anything else.
+#
+# The hook never writes the lock itself: it only injects the instruction. The
+# agent runs `branch-lock.sh set <branch>` (or the user's /branch-lock command)
+# on a "yes", and leaves the repo unlocked on a "no".
+
+set -uo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/lock-store.sh
+source "$HERE/lib/lock-store.sh"
+# shellcheck source=lib/scope-resolver.sh
+source "$HERE/lib/scope-resolver.sh"
+
+# session_start_should_prompt <root> <lockfile> <branch>
+#   Returns 0 (prompt) only in the primary checkout, while unlocked, with a real
+#   branch checked out. Returns 1 (stay silent) otherwise. No output.
+session_start_should_prompt() {
+  local _root="$1" _lockfile="$2" _branch="$3"
+  scope_should_enforce "$_root" || return 1          # worktree => exempt
+  lock_store_is_locked "$_lockfile" && return 1      # already locked => nothing to offer
+  [[ -z "$_branch" || "$_branch" == "HEAD" ]] && return 1   # detached / no branch
+  return 0
+}
+
+# session_start_prompt_text <branch>
+#   The instruction injected into the agent's context.
+session_start_prompt_text() {
+  local _branch="$1"
+  cat <<EOF
+branch-lock: this session is on branch '$_branch' in the primary checkout, and the branch is not locked. Before doing anything else, ask the user whether to lock the agent to '$_branch' for this session, showing the branch name. If they say yes, lock it with the /branch-lock command (or run scripts/branch-lock.sh set '$_branch'). If they say no, leave the repo unlocked and proceed. Do not lock without an explicit yes.
+EOF
+}
+
+main() {
+  # Drain stdin (SessionStart sends a JSON payload we don't need to inspect).
+  cat >/dev/null 2>&1 || true
+
+  local root="${CLAUDE_PROJECT_DIR:-}"
+  if [[ -z "$root" ]]; then
+    root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+  fi
+  [[ -z "$root" ]] && exit 0
+
+  local lockfile="$root/.red/tmp/branch-lock.yaml"
+  local branch
+  branch="$(git -C "$root" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
+
+  session_start_should_prompt "$root" "$lockfile" "$branch" || exit 0
+
+  local text
+  text="$(session_start_prompt_text "$branch")"
+
+  if command -v jq >/dev/null 2>&1; then
+    jq -nc --arg ctx "$text" \
+      '{hookSpecificOutput: {hookEventName: "SessionStart", additionalContext: $ctx}}'
+  else
+    # Fallback: bare stdout is added to the session context too.
+    printf '%s\n' "$text"
+  fi
+  exit 0
+}
+
+# Run main only when executed directly, not when sourced by tests.
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+  main "$@"
+fi

package/runtime/plugins/dev/skills/misc/branch-lock/scripts/branch-lock.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# branch-lock.sh — the CLI behind the /branch-lock command. Sets, clears, and
+# reports the branch lock, keeping lib/lock-store.sh the single writer of the
+# lock file. The lock always lives at <root>/.red/tmp/branch-lock.yaml, where
+# <root> is CLAUDE_PROJECT_DIR (set by the harness) or the git toplevel.
+#
+# Usage:
+#   branch-lock.sh set [branch]   lock to <branch> (default: current branch),
+#                                 atomic relock-then-switch — rewrite the lock
+#                                 target first so the move "back to the lock
+#                                 target" is itself allowed by the hook, then
+#                                 switch the working tree if not already there.
+#   branch-lock.sh clear          release the lock.
+#   branch-lock.sh status         print the locked branch, or "unlocked".
+
+set -uo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/lock-store.sh
+source "$HERE/lib/lock-store.sh"
+
+resolve_root() {
+  local root="${CLAUDE_PROJECT_DIR:-}"
+  [[ -z "$root" ]] && root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+  [[ -z "$root" ]] && { echo "branch-lock: not inside a git repo and CLAUDE_PROJECT_DIR unset" >&2; return 1; }
+  printf '%s' "$root"
+}
+
+main() {
+  local action="${1:-status}"
+  local root lockfile
+  root="$(resolve_root)" || return 1
+  lockfile="$root/.red/tmp/branch-lock.yaml"
+
+  case "$action" in
+    set)
+      local branch="${2:-}"
+      [[ -z "$branch" ]] && branch="$(git rev-parse --abbrev-ref HEAD 2>/dev/null)"
+      [[ -z "$branch" ]] && { echo "branch-lock: no branch given and HEAD is detached" >&2; return 1; }
+      # Atomic relock-then-switch: rewrite the target before moving, so the
+      # subsequent switch is "return to the lock target" and the hook allows it.
+      lock_store_write "$lockfile" "$branch" || return 1
+      local current; current="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
+      if [[ -n "$current" && "$current" != "$branch" ]]; then
+        git switch "$branch" || { echo "branch-lock: locked to '$branch' but switch failed (resolve manually)" >&2; return 1; }
+      fi
+      echo "branch-lock: locked to '$branch'"
+      ;;
+    clear)
+      lock_store_clear "$lockfile"
+      echo "branch-lock: cleared (unlocked)"
+      ;;
+    status)
+      local b
+      if b="$(lock_store_read "$lockfile")"; then
+        echo "branch-lock: locked to '$b'"
+      else
+        echo "branch-lock: unlocked"
+      fi
+      ;;
+    *)
+      echo "usage: branch-lock.sh <set [branch]|clear|status>" >&2
+      return 2
+      ;;
+  esac
+}
+
+main "$@"

package/runtime/plugins/dev/skills/misc/branch-lock/scripts/lib/dev-config.sh

@@ -0,0 +1,126 @@
+#!/usr/bin/env bash
+# lib/dev-config.sh — tiny runtime reader for `.red/config.yaml` dev flags.
+#
+# The hook must be dormant by default: missing config file or missing key means
+# disabled. This parser intentionally mirrors the constrained YAML shape used by
+# the dev runtime: nested 2-space mappings with scalar leaves. It exposes the
+# few boolean flags the dev hooks need (ADR 0043 lock guard, ADR 0067 gate).
+
+# _dev_config_scalar_true <config.yaml> <dotted-key...>
+# Returns 0 when ANY of the given dotted keys is the exact scalar `true`, 1
+# otherwise (including a missing file). Shared parser for the public readers.
+_dev_config_scalar_true() {
+  local _file="$1"
+  shift
+  local -a _keys=("$@")
+  [[ -f "$_file" ]] || return 1
+
+  local -a _stack=()
+  local -a _indents=()
+  local _raw _line _indent_str _indent _rest _key _value _full _i
+  local _inner _before_close _close_len _tail
+
+  while IFS= read -r _raw || [[ -n "$_raw" ]]; do
+    _raw="${_raw%$'\r'}"
+    _line="$_raw"
+
+    if [[ "$_line" != *\"* && "$_line" != *\'* ]]; then
+      _line="${_line%%#*}"
+    fi
+    _line="${_line%"${_line##*[![:space:]]}"}"
+    [[ -z "${_line//[[:space:]]/}" ]] && continue
+
+    _indent_str="${_line%%[![:space:]]*}"
+    _indent=${#_indent_str}
+    (( _indent % 2 == 0 )) || return 1
+    _rest="${_line:$_indent}"
+
+    # Skip block-sequence items (`- value`) — they never contain dev flags.
+    # A top-level sequence (empty stack) mirrors the TS parser: malformed → bail.
+    if [[ "$_rest" =~ ^-([[:space:]]|$) ]]; then
+      (( ${#_stack[@]} == 0 )) && return 1
+      continue
+    fi
+
+    [[ "$_rest" =~ ^[A-Za-z_][A-Za-z0-9_-]*: ]] || return 1
+    _key="${_rest%%:*}"
+    _value="${_rest#*:}"
+    _value="${_value#"${_value%%[![:space:]]*}"}"
+
+    while ((${#_indents[@]} > 0 && _indents[${#_indents[@]} - 1] >= _indent)); do
+      local _last_stack=$(( ${#_stack[@]} - 1 ))
+      local _last_indent=$(( ${#_indents[@]} - 1 ))
+      unset "_stack[$_last_stack]"
+      unset "_indents[$_last_indent]"
+    done
+
+    _full=""
+    for ((_i = 0; _i < ${#_stack[@]}; _i++)); do
+      [[ -n "$_full" ]] && _full+="."
+      _full+="${_stack[$_i]}"
+    done
+    [[ -n "$_full" ]] && _full+="."
+    _full+="$_key"
+
+    if [[ -z "$_value" ]]; then
+      _stack+=("$_key")
+      _indents+=("$_indent")
+      continue
+    fi
+
+    # Strip an inline comment that follows a closing quote (e.g. `key: "v" # note`).
+    if [[ "${_value:0:1}" == '"' ]]; then
+      _inner="${_value:1}"
+      _before_close="${_inner%%\"*}"
+      if [[ "$_inner" == *'"'* ]]; then
+        _close_len=$(( 1 + ${#_before_close} + 1 ))
+        _tail="${_value:$_close_len}"
+        if [[ "$_tail" =~ ^[[:space:]]*(#.*)?$ ]]; then
+          _value="${_value:0:$_close_len}"
+        fi
+      fi
+    elif [[ "${_value:0:1}" == "'" ]]; then
+      _inner="${_value:1}"
+      _before_close="${_inner%%\'*}"
+      if [[ "$_inner" == *"'"* ]]; then
+        _close_len=$(( 1 + ${#_before_close} + 1 ))
+        _tail="${_value:$_close_len}"
+        if [[ "$_tail" =~ ^[[:space:]]*(#.*)?$ ]]; then
+          _value="${_value:0:$_close_len}"
+        fi
+      fi
+    fi
+
+    if [[ "$_value" == \"*\" && "$_value" == *\" ]]; then
+      _value="${_value:1:${#_value}-2}"
+    elif [[ "$_value" == \'*\' && "$_value" == *\' ]]; then
+      _value="${_value:1:${#_value}-2}"
+    fi
+
+    local _k
+    for _k in "${_keys[@]}"; do
+      if [[ "$_full" == "$_k" ]]; then
+        [[ "$_value" == "true" ]] && return 0
+      fi
+    done
+  done < "$_file"
+
+  return 1
+}
+
+# dev_config_lock_primary_branch_enabled <config.yaml>
+# Returns 0 when the primary-branch lock is on, 1 otherwise. The flag lives at
+# `dev.lock.primary-branch` (top-level) or `plugins.dev.lock.primary-branch`
+# (namespaced); either set to exactly `true` enables the guard.
+dev_config_lock_primary_branch_enabled() {
+  _dev_config_scalar_true "$1" "dev.lock.primary-branch" "plugins.dev.lock.primary-branch"
+}
+
+# dev_plugin_enabled <config.yaml>
+# The per-directory plugin activation gate (ADR 0067): returns 0 only when
+# `plugins.dev.enabled` is the exact scalar `true`. A missing file or missing
+# flag → 1 (dormant). Every dev shell hook must early-exit on a non-zero return
+# so it stays fully inert in repos that did not opt into the dev plugin.
+dev_plugin_enabled() {
+  _dev_config_scalar_true "$1" "plugins.dev.enabled"
+}

package/runtime/plugins/dev/skills/misc/branch-lock/scripts/lib/git-command-classifier.sh

@@ -0,0 +1,198 @@
+#!/usr/bin/env bash
+# lib/git-command-classifier.sh — the Git Command Classifier: given the locked
+# branch and a shell command string, decides whether the command would lose the
+# agent's work while a lock is active and must be blocked. Pure / explicit-args,
+# like the sibling lib/ modules. Self-contained: it carries its own small
+# command matcher so the branch-lock hook needs no dependency on the
+# git-guardrails skill.
+#
+# It blocks two families of command:
+#   1. Branch-leaving `git checkout <branch>` / `git switch <branch>` (the
+#      original slice) — unless the target is the lock branch itself.
+#   2. The work-loss family (issue #61): commands that throw away the working
+#      tree or the stash —
+#        - `git stash` / `git stash push` / `git stash save`  (bare stash defaults to push)
+#        - `git clean` with any force flag (`-f`, `-fd`, `-xfd`, `--force`)
+#        - `git reset --hard`
+#        - whole-tree restore: `git checkout .`, `git checkout -- .`, `git restore .`
+#
+# Everything else is allowed — switching back to the lock branch, targeted
+# single-file restore (`git checkout -- <path>`, `git restore <path>`), a bare
+# `git checkout`, read-only stash (`list`/`show`), a dry-run clean (`-n`), a
+# soft/mixed reset, an unstage (`git restore --staged`), `git worktree add`
+# (worktrees are how /afk works and are exempt by scope), and any other command.
+#
+# Recognition is intentionally conservative: it scans the token stream for a
+# `git` token, skips any global options between `git` and the subcommand
+# (`git -C <path> checkout x`, `git --git-dir=… switch y`, `git -c k=v …`), and
+# classifies the recognised subcommand, so a compound command
+# (`cd x && git reset --hard`) and a global-option form are both classified.
+#
+# Public surface:
+#   classify_git_command <lock_branch> <command>
+#     Echoes exactly "block" or "allow" and returns 0.
+#
+#   classify_primary_branch_switch_guard <command>
+#     Echoes exactly "block" for commands that would move or destroy work in the
+#     primary checkout, and "allow" otherwise. This is the config-flag guard
+#     from ADR 0043 (unlike classify_git_command it has no lock branch). It
+#     blocks: branch movement (switch/create/checkout to a branch); `git reset`
+#     in ANY form; every `git stash` subcommand; and `git rebase --autostash`
+#     (issue #1024). Parallel human WIP lives in the primary checkout and these
+#     commands have destroyed in-progress work before; do branch work in an
+#     isolated worktree under .red/tmp/ instead. Worktrees are exempt by scope,
+#     so this classifier only ever runs against the primary checkout.
+
+# _git_subcommand_index <toks-name> <git-index>
+# Given the name of the token array and the index of a `git` token, echoes the
+# index of the git subcommand, skipping any leading global options. Global
+# options that take a separate argument (`-C <path>`, `-c <name=value>`,
+# `--git-dir <path>`, `--work-tree <path>`, `--namespace <name>`,
+# `--exec-path <path>`, `--super-prefix <path>`) consume the following token;
+# the `--opt=value` form is self-contained, and bare flags (`-p`, `--no-pager`,
+# `--bare`, …) consume only themselves. Echoes the array length when no
+# subcommand follows.
+_git_subcommand_index() {
+  local -n _t="$1"
+  local k=$(( $2 + 1 ))
+  local len=${#_t[@]}
+  while (( k < len )); do
+    local tok="${_t[k]}"
+    case "$tok" in
+      -C|-c|--git-dir|--work-tree|--namespace|--exec-path|--super-prefix)
+        k=$(( k + 2 )); continue ;;   # option + its separate argument
+      --*=*|-*)
+        k=$(( k + 1 )); continue ;;   # `--opt=value` or a bare flag
+      *)
+        break ;;                      # the subcommand token
+    esac
+  done
+  echo "$k"
+}
+
+# classify_git_command <lock_branch> <command>
+classify_git_command() {
+  local _lock="$1" _cmd="$2"
+  local -a toks
+  read -ra toks <<<"$_cmd"
+  local n=${#toks[@]} i j
+
+  for ((i = 0; i < n; i++)); do
+    [[ "${toks[i]}" == "git" ]] || continue
+    local s; s="$(_git_subcommand_index toks "$i")"   # subcommand index, past global options
+    local sub="${toks[s]:-}"
+    case "$sub" in
+      worktree)
+        echo "allow"; return 0
+        ;;
+      stash)
+        # bare `git stash` defaults to push; push/save discard the working tree.
+        local op="${toks[s + 1]:-}"
+        if [[ -z "$op" || "$op" == "push" || "$op" == "save" ]]; then
+          echo "block"; return 0
+        fi
+        echo "allow"; return 0   # list / show / pop / apply / drop …
+        ;;
+      clean)
+        # any force flag makes clean destructive; -n/--dry-run is safe.
+        for ((j = s + 1; j < n; j++)); do
+          local t="${toks[j]}"
+          [[ "$t" == "--force" ]] && { echo "block"; return 0; }
+          # short flag bundle containing 'f' (-f, -fd, -xfd, …) but not -n.
+          if [[ "$t" == -[^-]* && "$t" == *f* ]]; then echo "block"; return 0; fi
+        done
+        echo "allow"; return 0
+        ;;
+      reset)
+        for ((j = s + 1; j < n; j++)); do
+          [[ "${toks[j]}" == "--hard" ]] && { echo "block"; return 0; }
+        done
+        echo "allow"; return 0
+        ;;
+      restore)
+        # whole-tree restore (`git restore .`) loses work; a targeted path or an
+        # unstage (`--staged <path>`) is allowed, mirroring `checkout -- <path>`.
+        for ((j = s + 1; j < n; j++)); do
+          local t="${toks[j]}"
+          [[ "$t" == -* ]] && continue   # skip flags (--staged, --source=…, …)
+          if [[ "$t" == "." ]]; then echo "block"; return 0; fi
+          break                          # a named path: allowed
+        done
+        echo "allow"; return 0
+        ;;
+      checkout|switch)
+        local target="" sawdoubledash=0
+        for ((j = s + 1; j < n; j++)); do
+          local t="${toks[j]}"
+          if [[ "$t" == "--" ]]; then sawdoubledash=1; continue; fi
+          if [[ "$t" == "-" ]]; then target="-"; break; fi  # `switch -` = previous branch
+          [[ "$t" == -* ]] && continue   # skip flags (-b, -c, -q, --track, …)
+          target="$t"; break
+        done
+        # whole-tree restore via checkout (`git checkout .`, `git checkout -- .`).
+        if [[ "$target" == "." ]]; then echo "block"; return 0; fi
+        if (( sawdoubledash )); then echo "allow"; return 0; fi   # file restore
+        if [[ -z "$target" ]]; then echo "allow"; return 0; fi    # bare checkout
+        if [[ "$target" == "$_lock" ]]; then echo "allow"; return 0; fi # back to lock
+        echo "block"; return 0
+        ;;
+    esac
+  done
+
+  echo "allow"; return 0
+}
+
+# classify_primary_branch_switch_guard <command>
+classify_primary_branch_switch_guard() {
+  local _cmd="$1"
+  local -a toks
+  read -ra toks <<<"$_cmd"
+  local n=${#toks[@]} i j
+
+  for ((i = 0; i < n; i++)); do
+    [[ "${toks[i]}" == "git" ]] || continue
+    local s; s="$(_git_subcommand_index toks "$i")"   # subcommand index, past global options
+    local sub="${toks[s]:-}"
+    case "$sub" in
+      worktree)
+        echo "allow"; return 0
+        ;;
+      reset)
+        # `git reset` in ANY form (--hard/--soft/--mixed, with or without a
+        # pathspec) can throw away parallel human WIP in the primary checkout
+        # (issue #1024). All forms blocked; use a worktree for branch work.
+        echo "block"; return 0
+        ;;
+      stash)
+        # `git stash` and every subcommand (push/save/pop/apply/list/show/…)
+        # blocked in the primary checkout (issue #1024) — the whole family
+        # touches or hides the primary's working tree.
+        echo "block"; return 0
+        ;;
+      rebase)
+        # `git rebase --autostash` silently stashes/pops the primary's WIP
+        # around the rebase (issue #1024); a plain rebase is not this vector.
+        for ((j = s + 1; j < n; j++)); do
+          [[ "${toks[j]}" == "--autostash" ]] && { echo "block"; return 0; }
+        done
+        echo "allow"; return 0
+        ;;
+      checkout|switch)
+        local target="" sawdoubledash=0
+        for ((j = s + 1; j < n; j++)); do
+          local t="${toks[j]}"
+          if [[ "$t" == "--" ]]; then sawdoubledash=1; continue; fi
+          if [[ "$t" == "-" ]]; then target="-"; break; fi
+          [[ "$t" == -* ]] && continue
+          target="$t"; break
+        done
+        if (( sawdoubledash )); then echo "allow"; return 0; fi
+        if [[ -z "$target" ]]; then echo "allow"; return 0; fi
+        if [[ "$target" == "." ]]; then echo "allow"; return 0; fi
+        echo "block"; return 0
+        ;;
+    esac
+  done
+
+  echo "allow"; return 0
+}

package/runtime/plugins/dev/skills/misc/branch-lock/scripts/lib/lock-store.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# lib/lock-store.sh — the Lock Store: owns the branch-lock.yaml file end to end,
+# following the pure / explicit-args contract of the afk lib/ modules.
+#
+# The lock file records the single branch the agent is pinned to in the primary
+# checkout. Its presence means "locked"; its absence means "unlocked". Content
+# is the branch name on one line (a bare YAML scalar — valid YAML, trivially
+# inspectable). It lives under the gitignored .red/tmp/ so every checkout and
+# machine locks independently and nothing is ever committed.
+#
+# Reads no globals. The lock-file path is a parameter on every call, so the
+# Module stays unit-testable by sourcing it directly. Writes are atomic
+# (temp-in-same-dir then mv) so a concurrent reader never sees a half-written
+# file and a relock can never leave the target empty.
+#
+# Public surface:
+#   lock_store_write <lockfile> <branch>
+#     Atomically writes <branch> as the lock target. Creates the parent dir if
+#     missing. Returns 2 on missing arguments.
+#
+#   lock_store_read <lockfile>
+#     Echoes the locked branch name (trailing whitespace stripped) and returns
+#     0 when locked. Prints nothing and returns 1 when the file is absent
+#     (= unlocked), so absence is strictly opt-out.
+#
+#   lock_store_clear <lockfile>
+#     Removes the lock file. Idempotent — returns 0 whether or not it existed.
+#
+#   lock_store_is_locked <lockfile>
+#     Returns 0 when a non-empty lock file is present, 1 otherwise. No output.
+
+# lock_store_write <lockfile> <branch>
+lock_store_write() {
+  local _path="$1" _branch="$2"
+  [[ -z "$_path" || -z "$_branch" ]] && { printf '[lock-store] lock_store_write: need <lockfile> <branch>\n' >&2; return 2; }
+  mkdir -p "$(dirname "$_path")"
+  local tmp
+  tmp="$(mktemp "$(dirname "$_path")/.branch-lock.XXXXXX")"
+  printf '%s\n' "$_branch" > "$tmp"
+  mv -f "$tmp" "$_path"
+}
+
+# lock_store_read <lockfile>
+lock_store_read() {
+  local _path="$1"
+  [[ -s "$_path" ]] || return 1
+  local branch
+  # strip trailing whitespace/newlines; keep the first line only
+  IFS= read -r branch < "$_path"
+  branch="${branch%"${branch##*[![:space:]]}"}"
+  [[ -n "$branch" ]] || return 1
+  printf '%s' "$branch"
+}
+
+# lock_store_clear <lockfile>
+lock_store_clear() {
+  local _path="$1"
+  [[ -z "$_path" ]] && { printf '[lock-store] lock_store_clear: need <lockfile>\n' >&2; return 2; }
+  rm -f "$_path"
+  return 0
+}
+
+# lock_store_is_locked <lockfile>
+lock_store_is_locked() {
+  local _path="$1"
+  lock_store_read "$_path" >/dev/null 2>&1
+}