@reddb-io/red-skills-dev 2.75.2

package/skills/misc/branch-lock/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: branch-lock
+description: Lock the agent to a branch and block it from switching away. Sets up self-contained pre-tool hooks that block the agent's git checkout/switch to any other branch while a lock is active, and gives you a /branch-lock command to set, change, and clear the lock. Use when you want the agent pinned to one branch for a session.
+disable-model-invocation: true
+---
+
+# Branch Lock
+
+Pin the agent to one branch in the primary checkout and block it from switching away.
+
+<what-to-do>
+
+**Never hand-edit `branch-lock.yaml` — route every lock change through `scripts/branch-lock.sh` so the lock-store stays single-writer.**
+
+## Parse the request
+
+The user invokes `/branch-lock <branch>` or `/branch-lock clear` (or just asks
+to lock/unlock). Map it to one CLI action and run the bundled CLI:
+
+- `/branch-lock <branch>` → `scripts/branch-lock.sh set <branch>`
+- `/branch-lock` (no arg) → `scripts/branch-lock.sh set` (lock to the current branch)
+- `/branch-lock clear` → `scripts/branch-lock.sh clear`
+- "what's locked?" → `scripts/branch-lock.sh status`
+
+The CLI does the **atomic relock-then-switch**: it rewrites the lock target
+first, so the switch to that branch is itself "return to the lock target" and
+the hook never blocks the very change the user asked for.
+
+## Install the hooks (first time only)
+
+If the hooks are not yet wired in this repo, install them before relying on the lock:
+
+### Codex
+
+The `dev` plugin ships Codex wiring in
+`plugins/dev/.codex-plugin/plugin.json` (`"hooks": "./hooks/codex.hooks.json"`).
+That manifest calls `plugins/dev/hooks/branch-lock-codex.sh`, which reads Codex
+`PreToolUse` payloads and reuses the same `lock-store`, `scope-resolver`, and
+`git-command-classifier` modules as the Claude hook.
+
+Codex must load the updated `dev` plugin, and plugin hooks must be enabled.
+Current Codex builds list `plugin_hooks` as stable/enabled; older builds may
+need `[features].plugin_hooks = true` in `~/.codex/config.toml`. Once that is
+true, no per-repo `.codex/` copy is needed: set the lock with
+`scripts/branch-lock.sh set` or the `/branch-lock` skill command and the Codex
+hook enforces it for shell-command tool calls. If Codex has plugin hooks
+disabled, the lock file may exist but Codex will not enforce it.
+
+### Claude Code
+
+The `dev` plugin ships Claude wiring in
+`plugins/dev/.claude-plugin/plugin.json` (`"hooks": "./hooks/claude.hooks.json"`).
+That manifest registers `branch-lock-hook.sh` under `PreToolUse`/matcher `Bash`
+at the plugin level, so no per-repo `.claude/settings.json` copy is needed for
+the primary-branch guard. The hook reads `.red/config.yaml` at runtime; once
+`plugins.dev.enabled: true` it enforces the untouchable-primary rule and, when a
+branch-lock file is present, the work-loss family too.
+
+Manual per-repo installation is only needed for older/pluginless Claude setups:
+copy [scripts/branch-lock-hook.sh](scripts/branch-lock-hook.sh),
+[scripts/branch-lock-session-start.sh](scripts/branch-lock-session-start.sh),
+and `scripts/lib/` together into `.claude/hooks/branch-lock/`, make the scripts
+executable, and register `branch-lock-hook.sh` under `PreToolUse`/matcher `Bash`.
+The optional SessionStart hook only injects an instruction asking whether to
+lock; it never writes the lock itself.
+
+## DOs / DON'Ts
+
+- ✅ Always route lock changes through `scripts/branch-lock.sh`.
+- ✅ Confirm the resulting `status` to the user after `set`/`clear`.
+- ❌ Never hand-edit `branch-lock.yaml` — route via CLI so the lock-store stays single-writer.
+- ❌ Don't try to make the lock block the human terminal — out of scope by design (ADR 0006).
+
+</what-to-do>
+
+<supporting-info>
+
+## Why the lock exists
+
+The lock is a local fact — `.red/state/branch-lock.yaml` whose content is the
+branch name — under the gitignored state tier, so every checkout and machine
+locks independently and nothing is committed. Legacy readers may still recognize
+the old `.red/tmp/branch-lock.yaml` path during migration, but the canonical home
+is the durable state tier. Absence of the file means unlocked: the branch-lock
+layer is strictly opt-in.
+
+Layered under it, the dev plugin ships an **unconditional** primary-checkout
+branch guard (ADR 0083 §2, untouchable primary). Once the dev plugin is enabled
+(`plugins.dev.enabled: true`), the pre-tool hook blocks the agent from changing
+the primary checkout's branch — always, with no lock file and no config toggle.
+The answer to "may an agent switch the primary checkout's branch" is not
+configurable: it is always **no**. The historical `dev.lock.primary-branch` key
+stays **readable** for backward compatibility but can no longer enable or disable
+switching; the guard fires regardless of its value, and `/red-doctor` may note it as
+redundant.
+
+```yaml
+dev: { lock: { primary-branch: true } }  # retained for backward compatibility only — no longer toggles the guard
+```
+
+The same unconditional guard also blocks the work-destroying commands the
+standing maintainer rules forbid in the primary checkout, because parallel human
+WIP lives there and these have destroyed in-progress work before (issue #1024).
+The refusal points to the sanctioned alternative — do branch work in an isolated
+worktree under `.red/tmp/worktrees/manual/<slug>`, and if the local trunk
+diverged from origin, leave it alone and base on the fresh remote ref (ADR 0083).
+Inside isolated worktrees these commands remain allowed — the guard is about the
+primary checkout only, and `/afk` and `/go` worktrees under their registered
+`.red/tmp/` lanes are always exempt.
+
+Enforcement is **agent-only**, via runner pre-tool hooks — Claude Code
+`PreToolUse(Bash)` and Codex plugin `PreToolUse` — that intercept the agent's own
+tool calls, not the human's terminal (ADR 0006, unaffected). See
+[ADR 0006](../../../../../.red/adr/0006-branch-lock-agent-only-enforcement.md).
+The hook logic is self-contained: it depends on neither the
+`git-guardrails-claude-code` skill nor anything else, and the two stack
+harmlessly if both are installed.
+
+## Layout
+
+```
+branch-lock/
+├── SKILL.md
+├── ../../../hooks/
+│   ├── codex.hooks.json          ← Codex plugin hook manifest
+│   └── branch-lock-codex.sh      ← Codex PreToolUse hook
+└── scripts/
+    ├── branch-lock.sh            ← /branch-lock CLI (set | clear | status)
+    ├── branch-lock-hook.sh       ← Claude PreToolUse(Bash) hook
+    ├── branch-lock-session-start.sh ← SessionStart hook (offers to lock at start)
+    ├── lib/
+    │   ├── dev-config.sh          ← read dev.lock.primary-branch from .red/config.yaml
+    │   ├── lock-store.sh          ← read/write/clear branch-lock.yaml
+    │   ├── scope-resolver.sh      ← primary enforces, registered .red/tmp worktrees exempt
+    │   └── git-command-classifier.sh ← branch-switch + work-loss family = block
+    └── tests/
+        ├── lock-store.test.sh
+        ├── scope-resolver.test.sh
+        ├── git-command-classifier.test.sh
+        ├── dev-config.test.sh
+        ├── session-start.test.sh
+        ├── claude-plugin-hook.test.sh
+        ├── codex-hook.test.sh
+        └── branch-lock-cli.test.sh    ← /branch-lock set: atomic relock-then-switch
+```
+
+## What the hook blocks vs allows
+
+In the primary checkout, once `plugins.dev.enabled: true`, the hook blocks (the
+first three are the unconditional untouchable-primary rule; the rest are the
+work-loss family, blocked only while a branch-lock file is present):
+
+- `git checkout <any>` / `git switch <any>` — switching to any branch, including
+  the lock target (untouchable primary — the agent can never move the primary)
+- `git checkout -b <new>` / `git switch -c <new>` — leaving via a new branch
+- `git switch -` — switching to the previous branch
+- `git stash` / `git stash push` / `git stash save` — shelving away the working tree
+- `git clean -f` (any force flag: `-fd`, `-xfd`, `--force`) — deleting untracked files
+- `git reset --hard` — discarding the working tree
+- `git checkout .` / `git checkout -- .` / `git restore .` — whole-tree restore
+
+It allows (exit 0, silent):
+
+- `git checkout -- <path>` / `git restore <path>` — targeted file-level restore
+- `git stash list` / `git stash show` — read-only stash
+- `git clean -n` / `--dry-run` — non-destructive clean
+- `git reset --soft` / mixed reset, `git restore --staged <path>` — no working-tree loss
+- `git worktree add .red/tmp/worktrees/manual/<slug>` — manual worktrees stay in the registered lane
+- `git commit`, `git status` / read-only git, and any other command
+
+The dev command proxy has a stricter host-wide invariant when
+`plugins.dev.enabled: true`: any agent-created `git worktree add` destination
+must resolve under a registered lane in the repo's `.red/tmp/`. Branch-lock
+allows the command class; the dev proxy decides whether the destination path is
+inside the repo-owned runtime area.
+
+## Tests
+
+Pure-module unit tests, run directly with bash:
+
+```bash
+for t in scripts/tests/*.test.sh; do bash "$t"; done
+```
+
+Each prints `summary: N passed, 0 failed` and exits non-zero on any failure.
+
+</supporting-info>

package/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/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/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/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"
+}