@paths.design/caws-cli 11.1.6 → 11.1.8

package/templates/hook-packs/claude-code/shortcut-language-check.sh

@@ -0,0 +1,147 @@
+#!/bin/bash
+# CAWS-MANAGED-HOOK
+# hook_pack: claude-code
+# hook_pack_version: 11
+# caws_min_major: 11
+# lineage_refs: 29
+# do_not_edit_directly: update via `caws init --agent-surface claude-code`
+#
+# CAWS Shortcut-Language Progressive Check (QG-HOOKS-EXTRACT-001)
+#
+# PostToolUse hook firing on Write/Edit. Flags "shortcut" / incomplete-work
+# language in committed-bound source — the edit-time analogue of the
+# quality-gates `todo_detection` gate
+# (packages/quality-gates/todo-analyzer.mjs + check-placeholders.mjs). It
+# re-implements the practical intent in self-contained bash: catch the agent
+# leaving a TODO/FIXME/placeholder/"not implemented" stub in a NON-test source
+# file.
+#
+# Unlike the other three advisory hooks, this one escalates via the existing
+# progressive-strike mechanism (guard-strikes.sh):
+#   strike 1 -> warn (allow)
+#   strike 2 -> ask  (permission prompt)
+#   strike 3 -> block
+# Rationale: TODO/placeholder language in committed code is the CLAUDE.md
+# "No fake implementations" rule; repeated offenses in a session warrant
+# escalation, matching how scope-guard treats repeated scope violations.
+#
+# Test files (*.test.* / *.spec.*) are NOT strike-eligible: TODO/placeholder
+# language in tests is routine (describing pending cases, fixture stubs).
+#
+# Patterns (case-insensitive) — only the high-signal subset of the
+# todo-analyzer engine, kept to single-file grep for hook-time speed:
+#   \bTODO\b \bFIXME\b \bXXX\b \bHACK\b \bTBD\b
+#   "not implemented" "implement later" "coming soon" "placeholder"
+#   stub-return shapes: return null;? // TODO ; throw new Error("not implemented")
+#
+# env: none (strike count fixed at 3 via guard-strikes.sh).
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/parse-input.sh
+source "$SCRIPT_DIR/lib/parse-input.sh" 2>/dev/null || exit 0
+parse_hook_input || exit 0
+# shellcheck source=guard-strikes.sh
+source "$SCRIPT_DIR/guard-strikes.sh" 2>/dev/null || exit 0
+
+FILE_PATH="$HOOK_FILE_PATH"
+TOOL_NAME="$HOOK_TOOL_NAME"
+
+case "$TOOL_NAME" in
+  Write | Edit) ;;
+  *) exit 0 ;;
+esac
+
+[[ -z "$FILE_PATH" ]] && exit 0
+
+# Skip generated / vendored / build output.
+case "$FILE_PATH" in
+  */node_modules/* | */dist/* | */build/* | */coverage/* | */.next/* | */out/* | */vendor/*)
+    exit 0
+    ;;
+esac
+
+# Skip non-source artifacts: markdown/docs and lockfiles routinely contain
+# the word "placeholder"/"TODO" as prose. The hook targets code.
+case "$(basename "$FILE_PATH")" in
+  *.md | *.markdown | *.txt | *.lock | *-lock.json | package-lock.json | *.min.js | *.bundle.js | *.map)
+    exit 0
+    ;;
+esac
+
+# Test files are exempt from strikes (TODO/placeholder is routine in specs).
+case "$FILE_PATH" in
+  *.test.* | *.spec.* | */tests/* | */__tests__/* | */test/* | */fixtures/*)
+    exit 0
+    ;;
+esac
+
+# The content to scan: prefer the tool payload (works on untracked files and
+# is exactly what the agent just wrote). Write -> .content; Edit -> .new_string.
+CONTENT=""
+if [[ -n "${HOOK_TOOL_INPUT_JSON:-}" ]] && command -v jq >/dev/null 2>&1; then
+  CONTENT=$(printf '%s' "$HOOK_TOOL_INPUT_JSON" | jq -r '.content // .new_string // empty' 2>/dev/null || printf '')
+fi
+# Fallback: read the file from disk if the payload had no content field.
+if [[ -z "$CONTENT" ]] && [[ -f "$FILE_PATH" ]]; then
+  CONTENT=$(cat "$FILE_PATH" 2>/dev/null || printf '')
+fi
+[[ -z "$CONTENT" ]] && exit 0
+
+# Match the high-signal patterns. grep -nE on the content via a here-string;
+# -i case-insensitive. Word-boundary keywords first, then phrases, then
+# stub-return shapes.
+MATCH=""
+PATTERN_DESC=""
+
+# 1. Keyword markers (word-boundary).
+if hit=$(printf '%s' "$CONTENT" | grep -nE '\b(TODO|FIXME|XXX|HACK|TBD)\b' 2>/dev/null | head -1); then
+  if [[ -n "$hit" ]]; then
+    MATCH="$hit"
+    PATTERN_DESC="incomplete-work marker (TODO/FIXME/XXX/HACK/TBD)"
+  fi
+fi
+
+# 2. Placeholder / not-implemented phrases.
+if [[ -z "$MATCH" ]]; then
+  if hit=$(printf '%s' "$CONTENT" | grep -niE 'not implemented|implement later|coming soon|placeholder' 2>/dev/null | head -1); then
+    if [[ -n "$hit" ]]; then
+      MATCH="$hit"
+      PATTERN_DESC="placeholder / not-implemented language"
+    fi
+  fi
+fi
+
+# 3. Stub-return shapes (throw new Error("not implemented") is caught above;
+#    catch the bare "return null; // TODO" combo and an explicit stub throw).
+if [[ -z "$MATCH" ]]; then
+  if hit=$(printf '%s' "$CONTENT" | grep -niE 'throw new Error\(["'"'"']not implemented' 2>/dev/null | head -1); then
+    if [[ -n "$hit" ]]; then
+      MATCH="$hit"
+      PATTERN_DESC="explicit not-implemented stub throw"
+    fi
+  fi
+fi
+
+[[ -z "$MATCH" ]] && exit 0
+
+# Trim the matched line for the message (strip leading whitespace, cap length).
+LINE_TEXT=$(printf '%s' "$MATCH" | sed 's/^[0-9]*://; s/^[[:space:]]*//' | cut -c1-120)
+
+BASE="Shortcut-language advisory in ${FILE_PATH}: ${PATTERN_DESC} — \"${LINE_TEXT}\". CAWS doctrine (\"No fake implementations\") asks for complete code in committed source, not TODO/placeholder stubs."
+MSG1="${BASE} (strike 1 of 3 — advisory.)"
+MSG2="${BASE} (strike 2 of 3 — please resolve before continuing.)"
+MSG3="${BASE} (strike 3 — blocked. Replace the placeholder/stub with a real implementation, or move the work to a tracked spec.)"
+
+guard_enforce_progressive_strikes \
+  "${HOOK_SESSION_ID:-unknown}" \
+  "shortcut_language" \
+  "${HOOK_CWD:-}" \
+  "$MSG1" "$MSG2" "$MSG3"
+
+# guard_enforce_progressive_strikes emits the decision JSON. For strikes 1/2
+# it is an allow/ask (exit 0). For strike 3 it emits a block decision; exit 0
+# is correct for PostToolUse (the tool already ran) — the block decision in
+# the JSON is what Claude Code honors.
+exit 0

package/templates/hook-packs/claude-code/worktree-guard.sh

@@ -1,9 +1,9 @@
 #!/bin/bash
 # CAWS-MANAGED-HOOK
 # hook_pack: claude-code
-# hook_pack_version: 2
+# hook_pack_version: 11
 # caws_min_major: 11
-# lineage_refs: 4,6,11
+# lineage_refs: 4,6,11,19
 # do_not_edit_directly: update via `caws init --agent-surface claude-code`
 #
 # CAWS Worktree Safety Guard for Claude Code (v11-shape).
@@ -50,11 +50,137 @@ if echo "$COMMAND" | grep -qE 'caws\s+(worktree\s+create|parallel\s+setup).*--sc
 fi
 
 if echo "$COMMAND" | grep -qE '(^|;|&&|\|)\s*git\s+sparse-checkout'; then
-  echo "BLOCKED: git sparse-checkout is not allowed in this project." >&2
-  echo "Use full worktrees without sparse-checkout." >&2
+  # WORKTREE-SPEC-CANONICAL-ACCESS-GUARD-001 A3: blanket refusal stays.
+  # Agent-issued git sparse-checkout commands are refused regardless of
+  # subcommand (disable / set / init / reapply / list / add). Recovery
+  # of the canonical-spec-materialization invariant in a linked CAWS
+  # worktree is a CAWS worktree-repair concern routed through the CLI,
+  # not an agent-Bash git operation.
+  echo "BLOCKED: agent-issued git sparse-checkout is refused in CAWS projects." >&2
+  echo "" >&2
+  echo "Sparse-checkout in a CAWS linked worktree carries the mechanical guard" >&2
+  echo "against the v10.2 split-brain authority class: .caws/specs/ is excluded" >&2
+  echo "from the worktree by design, so canonical spec authority cannot be" >&2
+  echo "materialized inside the worktree as a divergent private copy. Disabling" >&2
+  echo "sparse-checkout (or any sparse-checkout reconfiguration via agent Bash)" >&2
+  echo "would re-open that class. Linked worktrees must not use worktree-local" >&2
+  echo ".caws/specs/ files as authority; CAWS resolves spec reads through the" >&2
+  echo "canonical control plane regardless of cwd." >&2
+  echo "" >&2
+  echo "To read a spec from any cwd (including this worktree), use:" >&2
+  echo "  caws specs show <id>" >&2
+  echo "" >&2
+  echo "To check scope from any cwd, use:" >&2
+  echo "  caws scope show <path>" >&2
+  echo "  caws scope check <path>" >&2
+  echo "" >&2
+  echo "To restore the sparse-checkout invariant on a linked worktree (e.g.," >&2
+  echo "after a human-authorized sparse-checkout reconfiguration left the tree" >&2
+  echo "with materialized .caws/specs/ files), run from the canonical checkout:" >&2
+  echo "  caws worktree repair-sparse <name>" >&2
+  echo "" >&2
+  echo "The repair command is non-destructive: it refuses dirty .caws/specs/" >&2
+  echo "rather than stashing, cleaning, or deleting work." >&2
   exit 2
 fi
 
+# ─── CANONICAL-CHECKOUT-WORKTREE-GUARD-001 (Entry 19) ────────────────
+# Block mutating git commands from the canonical checkout while at
+# least one active CAWS worktree exists. Hook-layer enforcement only:
+# authority remains in worktrees.json + specs. The guard's refusal
+# predicate is conjunctive: canonical + worktrees-active + mutating
+# command. Any one false MUST allow.
+#
+# Leases (.caws/leases/*.json) are NOT consulted by this decision —
+# stale-lease-is-evidence-never-authority. The block decision uses
+# worktrees.json's active entries only.
+canonical_guard_emit_block() {
+  local action="$1"
+  local first_active="$2"
+  echo "BLOCKED: $action from the canonical checkout while CAWS worktrees are active." >&2
+  echo "Active worktree(s) detected (e.g. '$first_active' in .caws/worktrees.json)." >&2
+  echo "Switch into your worktree before mutating: cd .caws/worktrees/$first_active" >&2
+  echo "Or destroy any worktree that is genuinely abandoned: caws worktree destroy <name>" >&2
+}
+
+# Determine whether the session's cwd is the canonical checkout.
+# git_dir == git_common_dir indicates canonical; a linked worktree has
+# git_dir under git_common_dir/worktrees/<name>/.
+CANONICAL_GUARD_CHECK_CWD="${HOOK_CWD:-$PROJECT_DIR}"
+if command -v git >/dev/null 2>&1 && [[ -d "$CANONICAL_GUARD_CHECK_CWD" ]]; then
+  GIT_DIR_RESOLVED=$(cd "$CANONICAL_GUARD_CHECK_CWD" && git rev-parse --git-dir 2>/dev/null | head -1 || echo "")
+  GIT_COMMON_RESOLVED=$(cd "$CANONICAL_GUARD_CHECK_CWD" && git rev-parse --git-common-dir 2>/dev/null | head -1 || echo "")
+  if [[ -n "$GIT_DIR_RESOLVED" ]] && [[ -n "$GIT_COMMON_RESOLVED" ]]; then
+    # Normalize to absolute paths so equality is structural, not textual.
+    GIT_DIR_ABS=$(cd "$CANONICAL_GUARD_CHECK_CWD" && cd "$GIT_DIR_RESOLVED" 2>/dev/null && pwd || echo "$GIT_DIR_RESOLVED")
+    GIT_COMMON_ABS=$(cd "$CANONICAL_GUARD_CHECK_CWD" && cd "$GIT_COMMON_RESOLVED" 2>/dev/null && pwd || echo "$GIT_COMMON_RESOLVED")
+    if [[ "$GIT_DIR_ABS" == "$GIT_COMMON_ABS" ]]; then
+      # We are in the canonical checkout. Now check for active worktrees.
+      WORKTREES_JSON="$PROJECT_DIR/.caws/worktrees.json"
+      if [[ -f "$WORKTREES_JSON" ]] && command -v node >/dev/null 2>&1; then
+        FIRST_ACTIVE_WT=$(node -e "
+          try {
+            var reg = JSON.parse(require('fs').readFileSync('$WORKTREES_JSON', 'utf8'));
+            function entriesOf(r) {
+              if (!r || typeof r !== 'object') return [];
+              if (r.worktrees && typeof r.worktrees === 'object') {
+                return Object.entries(r.worktrees);
+              }
+              var out = [];
+              for (var k in r) {
+                if (Object.prototype.hasOwnProperty.call(r, k)) {
+                  var v = r[k];
+                  if (v && typeof v === 'object') out.push([k, v]);
+                }
+              }
+              return out;
+            }
+            var entries = entriesOf(reg);
+            // 'active' is the documented status; entries without an
+            // explicit status (legacy/in-flight registry shapes) are
+            // also treated as active because the CLI's createWorktree
+            // does not always emit a status field.
+            var active = entries.filter(function(e) {
+              var s = e[1] && e[1].status;
+              return s === 'active' || s === undefined || s === null || s === '';
+            });
+            if (active.length > 0) console.log(active[0][0]);
+            else console.log('');
+          } catch(e) { console.log(''); }
+        " 2>/dev/null || echo "")
+        if [[ -n "$FIRST_ACTIVE_WT" ]]; then
+          # Predicate (a) canonical + (b) at least one active worktree
+          # is satisfied. Now check (c) mutation command keywords.
+          # Read-only commands (status, log, diff, show, fetch w/o --prune,
+          # rev-parse, ls-files, branch -v, stash list) are NOT in this
+          # set; they fall through to the existing guard rules.
+          if echo "$COMMAND" | grep -qE '(^|[[:space:];&|])git\s+checkout\s+[^[:space:]-]'; then
+            canonical_guard_emit_block "git checkout (branch switch)" "$FIRST_ACTIVE_WT"
+            exit 2
+          fi
+          if echo "$COMMAND" | grep -qE '(^|[[:space:];&|])git\s+switch\s+[^[:space:]-]'; then
+            canonical_guard_emit_block "git switch (branch switch)" "$FIRST_ACTIVE_WT"
+            exit 2
+          fi
+          if echo "$COMMAND" | grep -qE '(^|[[:space:];&|])git\s+branch\s+(-f|--force)'; then
+            canonical_guard_emit_block "git branch -f (force branch update)" "$FIRST_ACTIVE_WT"
+            exit 2
+          fi
+          # git reset variants other than --hard (already covered later in
+          # this file) — --keep, --merge, --soft, --mixed, or with no
+          # mode flag — mutate the canonical's working tree/HEAD.
+          if echo "$COMMAND" | grep -qE '(^|[[:space:];&|])git\s+reset\b' \
+             && ! echo "$COMMAND" | grep -qE 'git\s+reset\s+--hard'; then
+            canonical_guard_emit_block "git reset (HEAD mutation)" "$FIRST_ACTIVE_WT"
+            exit 2
+          fi
+        fi
+      fi
+    fi
+  fi
+fi
+# ─── /CANONICAL-CHECKOUT-WORKTREE-GUARD-001 ──────────────────────────
+
 # Block cross-boundary file copies (worktree → main).
 WORKTREE_BASE="$PROJECT_DIR/.caws/worktrees"
 if [[ -d "$WORKTREE_BASE" ]]; then

package/templates/hook-packs/claude-code/worktree-write-guard.sh

@@ -1,21 +1,37 @@
 #!/bin/bash
 # CAWS-MANAGED-HOOK
 # hook_pack: claude-code
-# hook_pack_version: 2
+# hook_pack_version: 11
 # caws_min_major: 11
 # lineage_refs: 4,8,13
 # do_not_edit_directly: update via `caws init --agent-surface claude-code`
 #
-# CAWS Worktree Write Guard for Claude Code (v11-shape, intentionally
-# fail-open for v11.1).
+# CAWS Worktree Write Guard for Claude Code.
 #
-# This hook fires on Write/Edit and currently allows all writes from the
-# main checkout. Worktree-first enforcement returns when worktree lifecycle
-# is restored in CLI-WORKTREE-001 (Slice 6). Until then, this hook serves
-# as the managed-install seat for the worktree-write enforcement surface
-# and asserts the always-allowed allowlist so .caws/, .claude/, docs/,
-# scripts/, tmp/, and tests/ writes are never inadvertently blocked by a
-# future enforcement pass that forgets the allowlist.
+# Two responsibilities:
+#
+#   1. Canonical-spec-materialization refusal
+#      (WORKTREE-SPEC-CANONICAL-ACCESS-GUARD-001 A1/A2).
+#      From inside a linked worktree (git rev-parse --git-common-dir !=
+#      git rev-parse --git-dir, after realpath normalization), refuse
+#      Read/Write/Edit tool calls whose file_path resolves under
+#      <linked-worktree>/.caws/specs/*. Such files would be private
+#      materialized copies of canonical spec authority, divergent from
+#      the canonical .caws/specs bytes, silently consulted by anything
+#      that walks cwd upward. The refusal MUST fire BEFORE the broad
+#      .caws/* allowlist below, otherwise the allowlist would exit 0
+#      first and the slice would appear implemented while the target
+#      path still bypassed the guard. The canonical checkout itself
+#      (git_common_dir == git_dir) IS spec authority and is allowed
+#      through this predicate; this refusal targets the linked-worktree
+#      materialization class only.
+#
+#   2. Base-branch write enforcement (intentionally fail-open for
+#      v11.1, restored in CLI-WORKTREE-001). The hook serves as the
+#      managed-install seat for the worktree-write enforcement surface
+#      and asserts the always-allowed allowlist so .caws/, .claude/,
+#      docs/, scripts/, tmp/, and tests/ writes are never inadvertently
+#      blocked by a future enforcement pass that forgets the allowlist.
 #
 # Worktree-active enforcement (when restored) must read the worktrees
 # registry under both shapes:
@@ -34,23 +50,122 @@ TOOL_NAME="$HOOK_TOOL_NAME"
 FILE_PATH="$HOOK_FILE_PATH"
 
 case "$TOOL_NAME" in
-  Write|Edit) ;;
+  Read|Write|Edit) ;;
   *) exit 0 ;;
 esac
 
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
-PROJECT_DIR="$(cd "$PROJECT_DIR" 2>/dev/null && pwd || printf '%s\n' "$PROJECT_DIR")"
+# WORKTREE_ROOT: where the agent is operating from. This is the cwd
+# whose .caws/specs/* path is the refusal target. Kept distinct from
+# CANONICAL_ROOT below — these MUST NOT be conflated for the spec-path
+# predicate.
+WORKTREE_ROOT="${CLAUDE_PROJECT_DIR:-.}"
+WORKTREE_ROOT="$(cd "$WORKTREE_ROOT" 2>/dev/null && pwd -P || printf '%s\n' "$WORKTREE_ROOT")"
 
+# _realpath: best-effort realpath. macOS lacks `readlink -f` by default;
+# python3 is available on every supported runner (CI matrix verified).
+# Falls back to the original path if realpath cannot resolve.
+_realpath() {
+  local p="$1"
+  if [[ -z "$p" ]]; then
+    printf '%s\n' ""
+    return 0
+  fi
+  if command -v python3 >/dev/null 2>&1; then
+    python3 -c "import os, sys; print(os.path.realpath(sys.argv[1]))" "$p" 2>/dev/null || printf '%s\n' "$p"
+  else
+    printf '%s\n' "$p"
+  fi
+}
+
+# Linked-worktree detection via git as primary signal. CAWS registry
+# (.caws/worktrees.json) is consulted ONLY for diagnostic enrichment;
+# a registry desync MUST NOT suppress the refusal (I3).
+IS_LINKED_WORKTREE=0
+CANONICAL_ROOT=""
 if command -v git >/dev/null 2>&1; then
-  GIT_COMMON_DIR=$(cd "$PROJECT_DIR" && git rev-parse --git-common-dir 2>/dev/null || echo "")
-  if [[ -n "$GIT_COMMON_DIR" ]] && [[ "$GIT_COMMON_DIR" != ".git" ]]; then
-    CANDIDATE=$(cd "$PROJECT_DIR" && cd "$GIT_COMMON_DIR/.." 2>/dev/null && pwd || echo "")
-    if [[ -n "$CANDIDATE" ]] && [[ -d "$CANDIDATE/.caws" ]]; then
-      PROJECT_DIR="$CANDIDATE"
+  GIT_COMMON_DIR_RAW="$(cd "$WORKTREE_ROOT" 2>/dev/null && git rev-parse --git-common-dir 2>/dev/null || printf '')"
+  GIT_DIR_RAW="$(cd "$WORKTREE_ROOT" 2>/dev/null && git rev-parse --git-dir 2>/dev/null || printf '')"
+  if [[ -n "$GIT_COMMON_DIR_RAW" ]] && [[ -n "$GIT_DIR_RAW" ]]; then
+    # Resolve relative paths against WORKTREE_ROOT before realpath.
+    case "$GIT_COMMON_DIR_RAW" in
+      /*) GIT_COMMON_DIR_ABS="$GIT_COMMON_DIR_RAW" ;;
+      *)  GIT_COMMON_DIR_ABS="$WORKTREE_ROOT/$GIT_COMMON_DIR_RAW" ;;
+    esac
+    case "$GIT_DIR_RAW" in
+      /*) GIT_DIR_ABS="$GIT_DIR_RAW" ;;
+      *)  GIT_DIR_ABS="$WORKTREE_ROOT/$GIT_DIR_RAW" ;;
+    esac
+    GIT_COMMON_DIR="$(_realpath "$GIT_COMMON_DIR_ABS")"
+    GIT_DIR="$(_realpath "$GIT_DIR_ABS")"
+    if [[ -n "$GIT_COMMON_DIR" ]] && [[ "$GIT_COMMON_DIR" != "$GIT_DIR" ]]; then
+      IS_LINKED_WORKTREE=1
+      # CANONICAL_ROOT = parent of GIT_COMMON_DIR. Used for allowlist
+      # rewriting only; NOT used for the spec-path refusal predicate.
+      CANONICAL_CANDIDATE="$(_realpath "$GIT_COMMON_DIR/..")"
+      if [[ -n "$CANONICAL_CANDIDATE" ]] && [[ -d "$CANONICAL_CANDIDATE/.caws" ]]; then
+        CANONICAL_ROOT="$CANONICAL_CANDIDATE"
+      fi
     fi
   fi
 fi
 
+# Canonical-spec-materialization refusal (I1: BEFORE the allowlist).
+#
+# Predicate: tool_name in {Read,Write,Edit} (already gated above)
+#            AND is_linked_worktree (via git signal)
+#            AND FILE_PATH resolves under <WORKTREE_ROOT>/.caws/specs/.
+#
+# WORKTREE_ROOT is the cwd-as-resolved-via-CLAUDE_PROJECT_DIR. NOT
+# CANONICAL_ROOT, NOT a PROJECT_DIR that has been rewritten upward. The
+# refused path lives under the LINKED worktree's tree.
+if [[ "$IS_LINKED_WORKTREE" == "1" ]] && [[ -n "$FILE_PATH" ]]; then
+  # WORKTREE_ROOT is already realpath-normalized (pwd -P above), so
+  # SPEC_ROOT inherits that normalization. We MUST also normalize
+  # FILE_PATH_ABS through _realpath so the comparison is symlink-
+  # immune. On macOS, /tmp -> /private/tmp; without normalization, an
+  # agent-supplied /tmp/.../.caws/specs/X.yaml would NOT prefix-match
+  # SPEC_ROOT=/private/tmp/.../.caws/specs because the literal strings
+  # diverge. python3 os.path.realpath resolves the existing prefix
+  # even when the leaf does not exist (Write tool case).
+  SPEC_ROOT="$WORKTREE_ROOT/.caws/specs"
+  case "$FILE_PATH" in
+    /*) FILE_PATH_ABS="$FILE_PATH" ;;
+    *)  FILE_PATH_ABS="$WORKTREE_ROOT/$FILE_PATH" ;;
+  esac
+  FILE_PATH_ABS="$(_realpath "$FILE_PATH_ABS")"
+  case "$FILE_PATH_ABS" in
+    "$SPEC_ROOT"/*|"$SPEC_ROOT")
+      echo "[worktree-write-guard.sh] BLOCKED: $FILE_PATH" >&2
+      echo "[worktree-write-guard.sh] Refusing $TOOL_NAME against a linked-worktree .caws/specs/ path." >&2
+      echo "[worktree-write-guard.sh]" >&2
+      echo "[worktree-write-guard.sh] Linked worktrees must not use worktree-local .caws/specs/ files as authority." >&2
+      echo "[worktree-write-guard.sh] That path would be a private materialized copy, not canonical spec authority." >&2
+      echo "[worktree-write-guard.sh] CAWS resolves spec reads through the canonical control plane regardless of cwd." >&2
+      echo "[worktree-write-guard.sh]" >&2
+      echo "[worktree-write-guard.sh] To read a spec from any cwd (including this worktree), use:" >&2
+      echo "[worktree-write-guard.sh]   caws specs show <id>" >&2
+      echo "[worktree-write-guard.sh]" >&2
+      echo "[worktree-write-guard.sh] To check scope from any cwd, use:" >&2
+      echo "[worktree-write-guard.sh]   caws scope show <path>" >&2
+      echo "[worktree-write-guard.sh]   caws scope check <path>" >&2
+      echo "[worktree-write-guard.sh]" >&2
+      echo "[worktree-write-guard.sh] If sparse-checkout was disabled in this worktree and you need to restore" >&2
+      echo "[worktree-write-guard.sh] the canonical-only invariant, run from the canonical checkout:" >&2
+      echo "[worktree-write-guard.sh]   caws worktree repair-sparse <name>" >&2
+      exit 2
+      ;;
+  esac
+fi
+
+# Legacy allowlist preserved from v11.1 fail-open base-branch enforcement.
+# For the allowlist, use PROJECT_DIR rewritten toward the canonical checkout
+# (the historical behavior) so that .caws/ etc. paths under canonical also
+# match when the agent is operating from inside a linked worktree.
+PROJECT_DIR="$WORKTREE_ROOT"
+if [[ -n "$CANONICAL_ROOT" ]]; then
+  PROJECT_DIR="$CANONICAL_ROOT"
+fi
+
 # Always-allowed paths bypass any future enforcement.
 # User-global Claude state lives outside the repo; .caws/, .claude/, docs/,
 # scripts/, tmp/, .archive/, and .githooks/ are coordination/governance