wrapper-guard: name the marker every forge API shares, not one dialect's

The scope gate asked for a scheme URL, a `/api/v[0-9]` path, or a provider-CLI `api` subcommand. `/api/v[0-9]` is Gitea's spelling. GitHub's API carries no version segment at all -- `api.github.com/repos/a/b/issues` -- so the schemeless Gitea write was in scope and the schemeless GitHub one was not: curl -X POST -d x api.github.com/repos/a/b/issues rc 0 curl -X POST -d x api.github.com/repos/a/b/issues/1/comments rc 0 host=api.github.com; curl -X POST -d x ${host}/repos/a/b/issues rc 0 A gate calibrated to one provider's spelling rather than to what identifies a provider API. `/repos/` is the marker both dialects share -- every forge API addresses a repository through it -- so the gate now names both. This is SPAN a third time, and the third layer it has appeared on. Round 8: a block message named a wrapper that could not make the call. Round 9: a map claimed a span its wrapper did not cover. Round 10: a control claimed a surface it did not measure. Here the scope gate itself claimed a class of API and recognised one member of it. Same question each time -- does this thing SPAN what it claims -- and it has now been the answer four rounds running, which is the argument for asking it of every arm rather than of the reported one. Widening a scope gate can only make the guard stricter. Downstream a block still requires a body flag AND either a mapped endpoint or an unreadable one, so this widens what is CONSIDERED, not what is refused. The three fixtures asserting that -- a schemeless GitHub read, an unwrapped GitHub endpoint, and a read past `--` -- exist to hold that claim to account rather than state it. Also: the provider-CLI arm's option scanner required a letter after the dashes, so `gh api -X POST -- ${p}${q} -f title=x` walked its endpoint straight past. The end-of-options marker is the one option not spelled like one, and a scanner that skips options had to be told so. Because the new endpoints are READABLE, each blocked fixture asserts the wrapper its message must name. A rc-only fixture here would have passed on the unreadable arm and proved nothing -- which is the failure mode this suite caught in itself last round. Evidence: 110/110 fixtures (was 101) locally and in ci-base. Negative-controlled per change, not in aggregate: dropping `/repos/` from the gate fails exactly the five GitHub fixtures; dropping the `--` alternative fails exactly one; neither disturbs a pre-existing fixture. 18-command sweep unchanged (same three round-6 flips, nothing new); 12-command ordinary-work sweep 0 blocked. shellcheck clean at warning+. CI 2374 on the previous head was green across all nine steps. Residual, stated rather than implied: a caller who splits `/repos/` itself in a schemeless GitHub URL leaves no literal marker anywhere and is out of scope -- the same boundary as splitting the hostname, and no longer a mistake anyone makes by accident. Round 11, addressing rev0 review 154.
wrapper-guard: fail closed on an unreadable endpoint in every shape the scope gate admits
2026-08-12 19:07:44 -05:00 · 2026-08-12 18:53:25 -05:00 · 2026-08-12 18:36:23 -05:00 · 2026-08-12 18:25:13 -05:00 · 2026-08-12 18:10:19 -05:00 · 2026-08-12 17:59:14 -05:00
8 changed files with 1499 additions and 8 deletions
@@ -46,10 +46,21 @@ steps:
      # [0] of the pnpm chain, so severing that chain would silence it together
      # with everything it guards; this direct line keeps one instrument running.
      - bash packages/mosaic/framework/tools/quality/scripts/check-test-enumeration.sh
      # Tool-index gate: a shipped wrapper that appears in no resident index doc
      # is undiscoverable from inside a session, and an agent that cannot learn a
      # wrapper exists reaches for raw curl instead — which is how a Gitea review
      # got filed PENDING three times. Ships-and-documented is one commit, or red.
      - bash packages/mosaic/framework/tools/quality/scripts/check-tools-index.sh --self-test
      - bash packages/mosaic/framework/tools/quality/scripts/check-tools-index.sh
      # Hermetic regression for issue-close.sh (#1081): mocks tea/curl onto PATH
      # and sandboxes a throwaway git repo, so it resolves no real credentials and
      # joins CI directly rather than the exclusions file.
      - bash packages/mosaic/framework/tools/git/test-issue-close-fail-closed.sh
      # Hermetic behavioural regression for the PreToolUse wrapper guard: proves
      # it still blocks the three mistakes AND still lets reads, unwrapped
      # endpoints and ordinary commands through. Both directions are asserted —
      # a guard that over-blocks gets routed around, which fails just as hard.
      - bash packages/mosaic/framework/tools/git/test-wrapper-guard.sh
  # Blocking gate (#791): a framework upgrade must never write or delete an
  # operator-owned path. The HARD GATE proves an unanticipated operator sentinel
@@ -52,6 +52,52 @@ If a repo does not expose these scripts, run equivalent local workflow commands
 - Do not auto-resolve data conflicts in shared state files.
 - Keep commits scoped to a single logical change set.
 ## Model Tiering
 Model choice is a standard, not a preference. Delegating a mechanical grep to a
 frontier reasoning model wastes budget; sending a security review to a cheap tier
 produces a review that passes and proves nothing. Both are defects.
 Tiers are named by **capability class**, so the standard survives a model
 generation. An operator binds each class to a concrete model id.
 | Class         | Use for                                                                                   |
 | ------------- | ----------------------------------------------------------------------------------------- |
 | `search`      | grep/glob, file location, status and health checks, one-line mechanical edits             |
 | `build`       | feature implementation, test writing, bugfixes, routine refactors                         |
 | `judge`       | code review, planning, API/compat-sensitive changes                                       |
 | `adversarial` | security review, ambiguous architecture, anything where a wrong "looks fine" is expensive |
 Rules:
 1. **Start at the cheapest class that can do the task; escalate on evidence, not
   on nerves.** Omitting a tier is not neutral — it inherits the caller's model,
   which is usually the most expensive one.
 2. **Compat-sensitive work escalates one class.** A change that must interoperate
   with an existing contract is judged, not just built.
 3. **A tier assignment is benchmarked, not asserted.** Move a task class to a
   cheaper tier only against a blind A/B on real work from this codebase, ranked
   by someone other than the author. "It seemed fine" is not evidence.
 4. **Reviewer independence beats reviewer size.** An `adversarial` verdict from
   the model that wrote the code is not a second opinion (see Constitution gate 16).
 ### Where the binding lives
 The class→model map is operator configuration, never framework source: model
 availability, cost, and quotas differ per operator and per host.
 Resolution order, first hit wins:
 1. the config service (DB-backed, surfaced and editable in the Mosaic webUI)
 2. a local operator file (`STANDARDS.local.md`, or `policy/` where the runtime
   injects it)
 3. the framework default — the class names above, with no binding
 Only layer 1 is auditable across a fleet, so it is the target end state; layers 2
 and 3 exist so a host with no config service still runs. A local override that
 silently disagrees with the config service is drift — the same failure class the
 tool-index gate exists to catch, and it belongs in `mosaic doctor`.
 ## Prompting Contract
 All runtime adapters should inject:
@@ -11,22 +11,105 @@ All tool suites are located at `~/.config/mosaic/tools/`.
 Mosaic wrappers at `~/.config/mosaic/tools/git/*.sh` handle platform detection and edge cases. Always use these before raw CLI commands.
 This index is complete and is kept complete mechanically: `tools/quality/scripts/check-tools-index.sh`
 fails CI when a wrapper ships without an entry here, or when an entry here names a wrapper that no
 longer exists. A wrapper missing from this list is, from inside an agent session, indistinguishable
 from a wrapper that was never written — which is how the APPROVE/APPROVED incident below happened.
 Every command takes `--help`. All of them accept `--login <account>` to pin the acting identity;
 supply it explicitly on any host where the provider CLI's default account is an admin.
 | Issues             |                                   |
 | ------------------ | --------------------------------- |
 | `issue-create.sh`  | Create an issue (Gitea or GitHub) |
 | `issue-view.sh`    | Show one issue                    |
 | `issue-list.sh`    | List issues                       |
 | `issue-edit.sh`    | Edit title/body/labels/milestone  |
 | `issue-comment.sh` | Add a comment                     |
 | `issue-assign.sh`  | Assign or unassign                |
 | `issue-close.sh`   | Close an issue                    |
 | `issue-reopen.sh`  | Reopen a closed issue             |
 | Pull requests    |                                                           |
 | ---------------- | --------------------------------------------------------- |
 | `pr-create.sh`   | Open a pull request                                       |
 | `pr-view.sh`     | Show one PR                                               |
 | `pr-list.sh`     | List PRs                                                  |
 | `pr-diff.sh`     | Fetch a PR's diff                                         |
 | `pr-metadata.sh` | PR metadata as JSON (head SHA, base, state, mergeability) |
 | `pr-review.sh`   | **Place a review verdict — see the dialect note below**   |
 | `pr-ci-wait.sh`  | Block until the PR's CI reaches a terminal state          |
 | `pr-merge.sh`    | Merge a PR                                                |
 | `pr-close.sh`    | Close a PR without merging                                |
 | Milestones            |                    |
 | --------------------- | ------------------ |
 | `milestone-create.sh` | Create a milestone |
 | `milestone-list.sh`   | List milestones    |
 | `milestone-close.sh`  | Close a milestone  |
 | Gates and guards        |                                                                                                           |
 | ----------------------- | --------------------------------------------------------------------------------------------------------- |
 | `ci-queue-wait.sh`      | CI queue guard — required before push/merge (see below)                                                   |
 | `push-guard.sh`         | Refuse verifications that pass for the wrong reason (e.g. green against an unpushed tree)                 |
 | `mutate-push-guard.sh`  | Regenerate the guard's mutation-coverage table from measurement, so the table cannot drift from the guard |
 | `verify-clean-clone.sh` | Prove the **committed** artifact runs, from a clean clone — not the working tree                          |
 | Context              |                                                                                          |
 | -------------------- | ---------------------------------------------------------------------------------------- |
 | `detect-platform.sh` | Resolve the provider (Gitea vs GitHub) for the current repo; every other wrapper uses it |
 | `lane-brief.sh`      | Live dispatch brief for a repo "lane" (milestone/label) straight from the provider       |
 | Workspace            |                                                                          |
 | -------------------- | ------------------------------------------------------------------------ |
 | `mosaic-worktree.sh` | Create/list/remove git worktrees — **the only supported way**; see below |
 | `wrapper-guard.sh`   | PreToolUse hook that enforces the two rules above; not called by hand    |
 **Workspace placement is derived, not chosen.** `mosaic-worktree.sh new <branch>` takes a branch
 name and nothing else. Every path comes out of `git worktree list --porcelain` — main worktree,
 repo name, parent dir, then `<parent>/<repo>-worktrees/<branch-slug>`. There is no placement flag
 because a decision an agent has to make is a decision that drifts: the rule "big work goes on a work
 filesystem" already existed in prose and 255 GB accumulated in `$HOME` across 842 directories
 anyway, under five simultaneous conventions on a single host.
 ```bash
-# Issues
+~/.config/mosaic/tools/git/mosaic-worktree.sh new <branch> [--from <base>]
-~/.config/mosaic/tools/git/issue-create.sh
+~/.config/mosaic/tools/git/mosaic-worktree.sh path <branch>   # derived path, no side effect
-~/.config/mosaic/tools/git/issue-close.sh
+~/.config/mosaic/tools/git/mosaic-worktree.sh list            # this repo's worktrees + state
 ~/.config/mosaic/tools/git/mosaic-worktree.sh rm <branch>     # removal is part of the task
 ~/.config/mosaic/tools/git/mosaic-worktree.sh gc [--apply]    # reclaim clean + fully-pushed ones
 ```
-# PRs
+Worktrees rather than clones, because `git worktree list` makes every checkout enumerable — a bare
-~/.config/mosaic/tools/git/pr-create.sh
+clone dropped somewhere on disk can never be safely reclaimed, so it is never reclaimed. `rm` and
-~/.config/mosaic/tools/git/pr-merge.sh
+`gc` decide by **evidence, never by size or age**: a worktree is reclaimable only when
 `git status --porcelain` is empty _and_ `git rev-list --count HEAD --not --remotes` is 0. Anything
 else is preserved and reported. `--force` exists and is yours to type deliberately.
-# Milestones
+`wrapper-guard.sh` is registered as a Claude Code `PreToolUse` hook on `Bash` (see
-~/.config/mosaic/tools/git/milestone-create.sh
+`runtime/claude/settings.json`). It blocks exactly three things and lets everything else through:
 a `git clone`/`git worktree add` targeting `$HOME`; a raw provider-API **write** to an endpoint that
 already has a wrapper above (reads are untouched — they are how you gather evidence); and the
 literal `"event": "APPROVE"`. For a genuine gap no wrapper can express, prefix
 `MOSAIC_WRAPPER_OVERRIDE=1`. Reaching for the override twice for the same call means the wrapper has
 a missing flag — extend the wrapper.
 ```bash
 ~/.config/mosaic/tools/git/issue-create.sh --help
 ~/.config/mosaic/tools/git/pr-review.sh --pr 42 --event APPROVED --body "..."
 # CI queue guard (required before push/merge; defaults to the checked-out branch)
 ~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge
 ```
 **Review dialect — the reason `pr-review.sh` is not optional.** Gitea's approve event is
 `APPROVED`; GitHub's is `APPROVE`. Send GitHub's spelling to a Gitea host and it answers **HTTP
 200**, files the review as PENDING, and then rejects the submit with `422 review stay pending` — the
 verdict looks placed and is not. (`REQUEST_CHANGES` is spelled identically on both, so only the
 approve path carries the trap.) `pr-review.sh` sends the correct token for the detected provider.
 Whatever you use, re-read `GET /pulls/{n}/reviews` and assert the state before reporting a verdict
 placed.
 The guard exits nonzero for any provider-asserted non-green, missing, or malformed CI state. If credentials or the provider are unavailable, it emits `CANNOT_ASSERT` and writes a JSONL audit record. Push degrades to exit 0 so recovery work is not bricked; merge holds with retryable exit 75 until the provider recovers, then self-clears without manual reset. Neither outcome is evidence that CI was clear. `pr-merge.sh` automatically inspects the exact PR head repository and full commit SHA rather than its `main` base; this also handles fork PRs without branch-name ambiguity. Pass `--expect-head <approved-full-sha>` to bind a commit-specific review or merge-gate verdict; Gitea uses atomic `head_commit_id` and GitHub uses `--match-head-commit`.
 ### Code Review (Codex)
@@ -52,6 +52,16 @@
            "timeout": 10
          }
        ]
      },
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.config/mosaic/tools/git/wrapper-guard.sh",
            "timeout": 10
          }
        ]
      }
    ],
    "PostToolUse": [
@@ -0,0 +1,289 @@
 #!/usr/bin/env bash
 # mosaic-worktree.sh — the only supported way to create and dispose of a git
 # worktree on a fleet host.
 #
 # Why this exists as a helper and not as a rule: the rule already existed, in
 # the framework's own words ("Big work → /var/tmp"), and 255 GB accumulated in
 # $HOME across 842 directories anyway. Five placement conventions were live on
 # one fleet host simultaneously. Every one was a decision an agent had to make,
 # and a decision an agent has to make is a decision that drifts.
 #
 # So this script makes NO placement decision available. The caller supplies a
 # branch name. Every path is DERIVED:
 #
 #   main worktree   <- git worktree list --porcelain (never cwd, which may
 #                      itself already be a worktree)
 #   REPO_NAME       <- basename of the main worktree
 #   REPO_PARENT     <- dirname  of the main worktree
 #   WT_ROOT         <- $REPO_PARENT/$REPO_NAME-worktrees
 #   SLUG            <- branch with '/' replaced by '-'
 #   WT_PATH         <- $WT_ROOT/$SLUG
 #
 # The derivation puts the worktree on the same filesystem as the object store
 # it shares, as a sibling of the repo, under one root per repo. Those are the
 # properties that make the checkout cheap and — via `git worktree list` —
 # enumerable, which is the only reason automated cleanup can ever be safe.
 #
 # Usage:
 #   mosaic-worktree.sh new <branch> [--from <base>]   create (branch may exist)
 #   mosaic-worktree.sh path <branch>                  print derived path, no side effect
 #   mosaic-worktree.sh list                           this repo's worktrees + state
 #   mosaic-worktree.sh rm <branch> [--force]          remove; refuses to lose work
 #   mosaic-worktree.sh gc [--apply]                   report/remove clean+pushed worktrees
 #
 # `rm` and `gc` refuse to delete a worktree with uncommitted changes, with
 # commits absent from every remote, or holding ignored files that are not of the
 # well-known regenerable kind (a `.env` is ignored so it is never committed,
 # which is also why nothing else holds a copy). That check is by EVIDENCE, never
 # by size or age. --force overrides it and is yours to type deliberately.
 #
 # Run from anywhere inside the repo, or pass --repo <path>.
 set -euo pipefail
 die() { printf 'mosaic-worktree: %s\n' "$*" >&2; exit 1; }
 REPO_HINT=""
 ARGS=()
 while [ $# -gt 0 ]; do
  case "$1" in
    --repo) REPO_HINT="${2:-}"; shift 2 ;;
    *) ARGS+=("$1"); shift ;;
  esac
 done
 set -- "${ARGS[@]+"${ARGS[@]}"}"
 CMD="${1:-}"
 [ -n "$CMD" ] || die "no command. Try: new | path | list | rm | gc"
 shift || true
 # ---- mechanical derivation -------------------------------------------------
 # The FIRST entry of `git worktree list --porcelain` is always the main
 # worktree, regardless of which worktree we are standing in. Deriving from cwd
 # would nest worktrees inside worktrees.
 resolve_repo() {
  local start="${REPO_HINT:-$PWD}"
  git -C "$start" rev-parse --git-dir >/dev/null 2>&1 \
    || die "not inside a git repository: $start"
  MAIN_WT="$(git -C "$start" worktree list --porcelain | awk '/^worktree /{print substr($0,10); exit}')"
  [ -n "$MAIN_WT" ] || die "could not resolve the main worktree"
  REPO_NAME="$(basename -- "$MAIN_WT")"
  REPO_PARENT="$(dirname -- "$MAIN_WT")"
  WT_ROOT="$REPO_PARENT/$REPO_NAME-worktrees"
 }
 slugify() { printf '%s' "$1" | tr '/' '-'; }
 derive_path() {
  local branch="$1"
  [ -n "$branch" ] || die "branch name required"
  printf '%s/%s' "$WT_ROOT" "$(slugify "$branch")"
 }
 # A worktree root under $HOME defeats the entire point: wrong filesystem, and
 # $HOME is for configuration and state, not work products. Refuse rather than
 # silently produce the layout we are trying to eliminate.
 assert_not_home() {
  local p="$1" home_real repo_real
  home_real="$(cd "$HOME" && pwd -P)"
  repo_real="$(cd "$(dirname -- "$p")" 2>/dev/null && pwd -P || dirname -- "$p")"
  case "$repo_real/" in
    "$home_real"/*)
      die "refusing: derived path is under \$HOME ($p).
 The repo itself lives under \$HOME, so its worktrees would too. Move the repo
 to a work filesystem (e.g. /src/$REPO_NAME) and re-run. \$HOME holds
 configuration, credentials, state and caches — not checkouts." ;;
  esac
 }
 # ---- work-loss evidence ----------------------------------------------------
 # Two independent questions, both answered from git, neither from size or age:
 #   dirty    — anything uncommitted in the tree
 #   unpushed — commits reachable from HEAD that no remote ref contains
 #   precious — IGNORED files git will not mention and will not miss
 #
 # The third question is not obvious and was missed on the first pass. An
 # independent reviewer demonstrated it in four commands: a pushed, clean
 # worktree whose .gitignore covers `*.secret`, holding one `local.secret`.
 # `git status --porcelain` is empty, `rev-list --count HEAD --not --remotes` is
 # 0 — the evidence reads SAFE — and `git worktree remove` deletes the file. The
 # same shape covers `.env`, credentials, scratch notes, downloaded fixtures:
 # precisely the files that are ignored BECAUSE they must not be committed, which
 # is also why nothing else is holding a copy.
 #
 # So ignored files count as work unless they are the well-known regenerable
 # kind. Getting that set wrong is asymmetric: an over-broad list preserves a
 # worktree that could have been reclaimed (cheap, visible, fixable by --force),
 # an over-narrow one deletes the only copy of a secret (silent, permanent).
 # The list stays short and conservative for that reason.
 DISPOSABLE_RE='(^|/)(node_modules|\.venv|venv|__pycache__|\.mypy_cache|\.pytest_cache|\.ruff_cache|\.turbo|\.cache|\.parcel-cache|\.gradle|dist|build|out|target|coverage|\.next|\.nuxt|\.svelte-kit)(/|$)|\.(pyc|pyo|o|class)$'
 # These three run under `set -euo pipefail` inside command substitution, which
 # makes any nonzero exit ANYWHERE in the pipeline abort the calling function
 # silently. Two ways that bites, one of which shipped:
 #
 #   * `grep -v` exits 1 when it filters everything out. A worktree whose only
 #     ignored entry is `node_modules/` is exactly the SAFE case, and it made
 #     `rm` exit 1 with no message and no removal — found by review.
 #   * `head -200` closes the pipe, SIGPIPEs the producer, and turns a worktree
 #     with 201 dirty files into the same silent abort. Not reported; it is the
 #     same defect one step upstream, so the cap is gone. Counting is cheap;
 #     the cap only ever protected output that is now never printed.
 #
 # Every one of them therefore ends in a total, and every stage that can
 # legitimately exit nonzero says so explicitly.
 wt_dirty() {
  local out
  out="$(git -C "$1" status --porcelain 2>/dev/null || true)"
  if [ -n "$out" ]; then printf '%s\n' "$out" | wc -l; else printf '0'; fi
 }
 wt_unpushed() { git -C "$1" rev-list --count HEAD --not --remotes 2>/dev/null || printf '?'; }
 # Default --ignored (not =matching) so a 40k-file node_modules collapses to one
 # directory entry instead of being enumerated and then discarded.
 wt_precious() {
  local ignored
  ignored="$(git -C "$1" status --porcelain --ignored 2>/dev/null \
             | awk '/^!! /{print substr($0,4)}' || true)"
  [ -n "$ignored" ] || { printf '0'; return 0; }
  printf '%s\n' "$ignored" | grep -Ecv "$DISPOSABLE_RE" || true
 }
 wt_state() {
  local wt="$1" d u p
  d="$(wt_dirty "$wt")"; u="$(wt_unpushed "$wt")"; p="$(wt_precious "$wt")"
  if [ "$d" -eq 0 ] && [ "$u" = "0" ] && [ "$p" -eq 0 ]; then
    printf 'SAFE\tclean; 0 unpushed; no ignored files worth keeping'
  else
    printf 'PRESERVE\t%s uncommitted; %s unpushed; %s ignored-but-not-disposable' "$d" "$u" "$p"
  fi
 }
 # ---- commands --------------------------------------------------------------
 cmd_path() { resolve_repo; derive_path "${1:-}"; echo; }
 cmd_new() {
  local branch="${1:-}" base=""
  shift || true
  while [ $# -gt 0 ]; do
    case "$1" in --from) base="${2:-}"; shift 2 ;; *) die "unknown flag: $1" ;; esac
  done
  [ -n "$branch" ] || die "usage: mosaic-worktree.sh new <branch> [--from <base>]"
  resolve_repo
  local path; path="$(derive_path "$branch")"
  assert_not_home "$path"
  if [ -e "$path" ]; then
    echo "exists: $path"
    echo "(already checked out — reuse it, or 'rm' it first)"
    return 0
  fi
  mkdir -p "$WT_ROOT"
  # Existing branch -> check it out. New branch -> create from base (default:
  # the remote's default branch if resolvable, else current HEAD).
  if git -C "$MAIN_WT" show-ref --verify --quiet "refs/heads/$branch" \
     || git -C "$MAIN_WT" show-ref --verify --quiet "refs/remotes/origin/$branch"; then
    git -C "$MAIN_WT" worktree add "$path" "$branch"
  else
    if [ -z "$base" ]; then
      base="$(git -C "$MAIN_WT" symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null || true)"
      [ -n "$base" ] || base="HEAD"
    fi
    git -C "$MAIN_WT" worktree add -b "$branch" "$path" "$base"
  fi
  cat <<EOF
 worktree: $path
 branch:   $branch
 Removal is part of this task, not a later chore. When the work is pushed:
  mosaic-worktree.sh rm $branch
 EOF
 }
 cmd_list() {
  resolve_repo
  printf 'repo: %s\nroot: %s\n\n' "$MAIN_WT" "$WT_ROOT"
  git -C "$MAIN_WT" worktree list --porcelain \
    | awk '/^worktree /{print substr($0,10)}' \
    | while read -r wt; do
        [ "$wt" = "$MAIN_WT" ] && { printf '%-10s %s (main)\n' "-" "$wt"; continue; }
        printf '%-10s %s\t%s\n' "$(wt_state "$wt" | cut -f1)" "$wt" "$(wt_state "$wt" | cut -f2)"
      done
 }
 cmd_rm() {
  local branch="${1:-}" force=0
  shift || true
  while [ $# -gt 0 ]; do
    case "$1" in --force) force=1; shift ;; *) die "unknown flag: $1" ;; esac
  done
  [ -n "$branch" ] || die "usage: mosaic-worktree.sh rm <branch> [--force]"
  resolve_repo
  local path; path="$(derive_path "$branch")"
  [ -d "$path" ] || die "no worktree at $path"
  local d u p
  d="$(wt_dirty "$path")"; u="$(wt_unpushed "$path")"; p="$(wt_precious "$path")"
  if [ "$force" -eq 0 ] && { [ "$d" -ne 0 ] || [ "$u" != "0" ] || [ "$p" -ne 0 ]; }; then
    die "refusing to remove $path
  uncommitted files:            $d
  unpushed commits:             $u
  ignored, not disposable:      $p
 Commit and push first — that is the contract. Ignored files are counted because
 git will neither report them nor miss them: a .env or a *.secret is ignored
 precisely so it is never committed, which is also why nothing else holds a copy.
 List them with:  git -C $path status --porcelain --ignored | grep '^!!'
 If this work is genuinely disposable, re-run with --force."
  fi
  # NB: ${force:+--force} would expand for force=0 too ("0" is non-empty).
  if [ "$force" -eq 1 ]; then
    git -C "$MAIN_WT" worktree remove --force "$path"
  else
    git -C "$MAIN_WT" worktree remove "$path"
  fi
  git -C "$MAIN_WT" worktree prune
  echo "removed: $path"
  rmdir "$WT_ROOT" 2>/dev/null || true
 }
 cmd_gc() {
  local apply=0
  [ "${1:-}" = "--apply" ] && apply=1
  resolve_repo
  git -C "$MAIN_WT" worktree prune
  git -C "$MAIN_WT" worktree list --porcelain \
    | awk '/^worktree /{print substr($0,10)}' \
    | while read -r wt; do
        [ "$wt" = "$MAIN_WT" ] && continue
        local_state="$(wt_state "$wt")"
        case "$local_state" in
          SAFE*)
            if [ "$apply" -eq 1 ]; then
              git -C "$MAIN_WT" worktree remove "$wt" && echo "removed: $wt"
            else
              echo "reclaimable (clean + fully pushed): $wt"
            fi ;;
          *) echo "preserved: $wt  [$(printf '%s' "$local_state" | cut -f2)]" ;;
        esac
      done
  git -C "$MAIN_WT" worktree prune
  [ "$apply" -eq 1 ] || echo $'\n(report only — re-run with --apply to remove the reclaimable ones)'
 }
 case "$CMD" in
  new)  cmd_new  "$@" ;;
  path) cmd_path "$@" ;;
  list) cmd_list "$@" ;;
  rm)   cmd_rm   "$@" ;;
  gc)   cmd_gc   "$@" ;;
  -h|--help|help) sed -n '2,40p' "$0" | sed 's/^# \{0,1\}//' ;;
  *) die "unknown command: $CMD (new | path | list | rm | gc)" ;;
 esac
@@ -0,0 +1,275 @@
 #!/usr/bin/env bash
 # test-wrapper-guard.sh — hermetic behavioural regression for wrapper-guard.sh.
 #
 # Resolves no credentials, touches no network, and creates no repository: the
 # guard reads a hook payload on stdin and answers with an exit code, so the whole
 # contract is testable from fixtures.
 #
 # The fixtures are written to a temp file rather than passed inline, and this is
 # not stylistic. The guard inspects the literal text of the Bash command it is
 # handed. A test that embeds `git clone ... $HOME` inside its own command line
 # trips the guard on the harness instead of on the fixture — which is exactly
 # what happened the first time this was checked by hand. Substring matching over
 # whole command text is the guard's deliberate fail-closed posture; a test that
 # does not account for it silently measures the wrong thing.
 #
 # Exit: 0 = every fixture behaved as specified · 1 = at least one did not
 set -uo pipefail
 HERE="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
 GUARD="${1:-$HERE/wrapper-guard.sh}"
 [ -x "$GUARD" ] || { printf 'test-wrapper-guard: not executable: %s\n' "$GUARD" >&2; exit 2; }
 TMP="$(mktemp -d)"; trap 'rm -rf "$TMP"' EXIT
 FIXTURES="$TMP/fixtures.tsv"
 # Each line: <expected-exit> TAB <hook payload> TAB <what it proves>
 #            [ TAB <substring the block message must contain> ]
 # 0 = allowed, 2 = blocked. The optional fourth field is how the remediation
 # itself gets checked; without it a block is only asserted to have happened,
 # not to have been useful.
 {
  printf '2\t{"tool_input":{"command":"git clone https://example.invalid/x ~/wt"}}\tcheckout into $HOME is refused\n'
  printf '2\t{"tool_input":{"command":"git worktree add ~/wt topic"}}\tworktree into $HOME is refused\n'
  printf '0\t{"tool_input":{"command":"git clone https://example.invalid/x /src/wt"}}\tcheckout onto a work filesystem is fine\n'
  printf '0\t{"tool_input":{"command":"curl -s -X GET https://git.example.invalid/api/v1/repos/a/b/pulls/1"}}\treads are never blocked\n'
  printf '2\t{"tool_input":{"command":"curl -X POST -d @b https://git.example.invalid/api/v1/repos/a/b/pulls/1/reviews"}}\treview write has a wrapper\n'
  printf '2\t{"tool_input":{"command":"curl -X POST -d @b https://git.example.invalid/api/v1/repos/a/b/pulls/1/merge"}}\tmerge write has a wrapper\n'
  printf '2\t{"tool_input":{"command":"curl -X POST -d @b https://api.github.com/repos/a/b/issues"}}\tGitHub host is covered too\n'
  printf '0\t{"tool_input":{"command":"curl -X POST -d @b https://git.example.invalid/api/v1/repos/a/b/releases"}}\tan endpoint with no wrapper passes\n'
  printf '2\t{"tool_input":{"command":"curl -X POST -d {\\"event\\":\\"APPROVE\\"} https://example.invalid/x"}}\tthe APPROVE token is caught anywhere\n'
  printf '0\t{"tool_input":{"command":"ls -la /src"}}\tordinary commands are untouched\n'
  printf '0\t{"tool_input":{"command":"MOSAIC_WRAPPER_OVERRIDE=1 curl -X POST -d @b https://git.example.invalid/api/v1/repos/a/b/pulls"}}\tbreak-glass works\n'
  printf '0\t{"tool_input":{}}\tan empty payload does not block the session\n'
  # --- bypasses an independent reviewer demonstrated against the first version.
  # Each of these returned 0 (allowed) and each is a real write. They are pinned
  # as fixtures rather than fixed-and-forgotten because the class is recurring:
  # the guard reads text, so every spelling it does not know is a hole.
  printf '2\t{"tool_input":{"command":"curl -d@b https://git.example.invalid/api/v1/repos/a/b/pulls/1/reviews"}}\t-d@body with no space is still a body\n'
  printf '2\t{"tool_input":{"command":"curl --request=POST -d@b https://git.example.invalid/api/v1/repos/a/b/pulls/1/reviews"}}\t--request=POST equals-form is still a method\n'
  printf '2\t{"tool_input":{"command":"p=/api/v1/repo; q=s/a/b/pulls/1/reviews; curl -d@b https://git.example.invalid${p}${q}"}}\ta path split across variables is still that path\n'
  printf '2\t{"tool_input":{"command":"curl --data-binary @b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments"}}\t--data-binary is a body\n'
  printf '2\t{"tool_input":{"command":"curl -F f=@b https://git.example.invalid/api/v1/repos/a/b/issues"}}\t-F multipart is a body\n'
  # Reads must survive every one of those broadenings, or the guard gets disabled.
  printf '0\t{"tool_input":{"command":"curl -s https://git.example.invalid/api/v1/repos/a/b/pulls/1/reviews"}}\tno body and no verb is a read\n'
  printf '0\t{"tool_input":{"command":"grep -rn /pulls/ src/ | head -20"}}\ta path fragment in a grep is not an API call\n'
  printf '0\t{"tool_input":{"command":"curl -X POST -d @b https://registry.example.invalid/v2/x/manifests/latest"}}\tan unwrapped API is not this guard'"'"'s business\n'
  # --- round two of the same review. Splitting the ENDPOINT TOKEN defeats any
  # amount of fragment matching, because the endpoint does not exist until the
  # shell expands it. The guard now refuses to clear a write whose URL it cannot
  # read, rather than pretending it read one.
  printf '2\t{"tool_input":{"command":"a=/api/v1/repos/a/b/iss; b=ues/1/comments; curl -d@body https://git.example.invalid${a}${b}"}}\tan endpoint token split across variables is unreadable, not absent\n'
  printf '2\t{"tool_input":{"command":"a=/api/v1/repos/a/b/pu; b=lls/1/reviews; curl -d@body https://git.example.invalid${a}${b}"}}\tsame split, review endpoint\n'
  printf '0\t{"tool_input":{"command":"curl -X POST -d @payload https://hooks.example.invalid/services/${WEBHOOK_ID}"}}\tan opaque URL that is not forge-shaped stays allowed\n'
  # --- round six changed the contract in this direction, and these fixtures are
  # where it shows. They used to assert that discussing a call is not making one.
  # Five rounds proved there is no textual way to tell a quoted example from a
  # quoted command, so the guard stopped trying: it judges the payload, and a
  # payload inside quotes is still a payload. Quoting one of these on a Bash
  # command line is now refused, and the way to write the example is a
  # file-writing tool. This is the deliberate cost of the mechanism change.
  printf '2\t{"tool_input":{"command":"grep -R \\"curl -d https://git.example.invalid/api/v1/repos/a/b/issues\\" docs/"}}\tquoting a wrapped write is refused even in a grep\n'
  printf '2\t{"tool_input":{"command":"echo \\"curl -d https://git.example.invalid/api/v1/repos/a/b/pulls\\" > note.txt"}}\t...and when written into a file\n'
  printf '2\t{"tool_input":{"command":"python3 -c '"'"'print(\\"curl -d https://git.example.invalid/api/v1/repos/a/b/issues\\")'"'"'"}}\t...and when printed from another language\n'
  # The boundary that keeps this from being "block everything": what is refused
  # is a WRITE to a WRAPPED endpoint. Mentioning either alone still passes, and
  # these are asserted as hard as the blocks above.
  printf '0\t{"tool_input":{"command":"grep -R \\"curl -s https://git.example.invalid/api/v1/repos/a/b/issues/1/comments\\" docs/"}}\tquoting a READ example is untouched\n'
  printf '0\t{"tool_input":{"command":"echo \\"the wrapped endpoint is https://git.example.invalid/api/v1/repos/a/b/issues/1/comments\\" >> notes.md"}}\tnaming the endpoint without a body flag is untouched\n'
  printf '0\t{"tool_input":{"command":"grep -R \\"curl -d@b https://git.example.invalid/api/v1/repos/a/b/releases\\" docs/"}}\tquoting a write to an UNWRAPPED endpoint is untouched\n'
  printf '0\t{"tool_input":{"command":"issue-comment.sh --repo a/b --issue 1 --body @msg.md"}}\tthe wrapper itself carries a body flag and must never trip its own guard\n'
  # Command position must still catch the real thing behind operators and env.
  printf '2\t{"tool_input":{"command":"cd /tmp && GITEA_TOKEN=$T curl -d@b https://git.example.invalid/api/v1/repos/a/b/pulls/1/merge"}}\ta real call behind && and an assignment is still a call\n'
  # --- the case the AUTHOR hit twice while chasing the above: sending a message
  # that QUOTED one of these fixtures. Under the old contract that was a defect
  # to be parsed away; under this one it is the documented cost, and the message
  # gets composed with a file-writing tool instead.
  printf '2\t{"tool_input":{"command":"send.sh -m \\"repro was: cd /tmp && curl -d@b https://git.example.invalid/api/v1/repos/a/b/pulls/1/merge\\""}}\tquoting the repro in a message is refused too\n'
  printf '2\t{"tool_input":{"command":"cat >> notes.md <<EOF\\nwe ran: curl -d@b https://git.example.invalid/api/v1/repos/a/b/issues\\nEOF"}}\ta heredoc body carrying the payload is refused with it\n'
  # ...but quotes stop being data the moment something executes them.
  printf '2\t{"tool_input":{"command":"bash -c \\"curl -d@b https://git.example.invalid/api/v1/repos/a/b/pulls/1/merge\\""}}\tbash -c makes the quoted text code again\n'
  # --- round three. Each of these four is a real write that a bare-name match
  # for the client could not see, because an ordinary word sat in front of it.
  # They are kept as fixtures after the mechanism change even though the guard no
  # longer looks for a client at all: they are the evidence for WHY it stopped,
  # and a future re-narrowing that reintroduced position would fail here first.
  printf '2\t{"tool_input":{"command":"env GITEA_TOKEN=$T curl -d@b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments"}}\tenv VAR=... in front of the client is still the client\n'
  printf '2\t{"tool_input":{"command":"command curl -d@b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments"}}\tcommand in front of the client is still the client\n'
  printf '2\t{"tool_input":{"command":"timeout 10 curl -d@b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments"}}\ttimeout N in front of the client is still the client\n'
  printf '2\t{"tool_input":{"command":"/usr/bin/curl -d@b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments"}}\tan absolute path to the client is still the client\n'
  printf '2\t{"tool_input":{"command":"echo timeout 10 curl -d@b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments >> notes.md"}}\tnaming the call after echo carries the payload, so it is refused\n'
  # A shell standing between quoted data and execution makes that data code,
  # and the pipe is the form agents actually use. Filing it as data allowed the
  # call to vanish from the skeleton while still running.
  printf '2\t{"tool_input":{"command":"printf '"'"'%%s\\\\n'"'"' '"'"'curl -d@b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments'"'"' | sh"}}\tquoted code piped to a shell is code\n'
  printf '2\t{"tool_input":{"command":"cat <<EOF | sh\\ncurl -d@b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments\\nEOF"}}\ta heredoc piped to a shell is code\n'
  printf '2\t{"tool_input":{"command":"sh -s <<EOF\\ncurl -d@b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments\\nEOF"}}\tsh -s reads its script from the heredoc\n'
  # ...and the questions that used to follow — is the pipe target a shell, does a
  # shell on one line execute a string on another — no longer have to be answered
  # at all. Both of these carry the payload, both are refused, and neither
  # outcome depends on parsing what the pipe or the other line does.
  printf '2\t{"tool_input":{"command":"grep -R \\"curl -d@b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments\\" docs/ | wc -l"}}\tpiping the payload to wc is refused without asking what wc is\n'
  printf '2\t{"tool_input":{"command":"docker run --rm alpine sh -c '"'"'echo hi'"'"'\\necho \\"example: curl -d@b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments\\" >> notes.md"}}\tan unrelated shell on another line no longer changes the answer either way\n'
  # --- round four. The guard was still reading the command as typed rather than
  # as the shell will run it: a backslash before a newline is removed before
  # anything else happens, so the endpoint token can be split across the join.
  printf '2\t{"tool_input":{"command":"curl -d@b https://git.example.invalid/api/v1/repos/a/b/iss\\\\\\nues/1/comments"}}\ta line continuation inside the endpoint token is still that endpoint\n'
  printf '2\t{"tool_input":{"command":"curl -d@b https://git.example.invalid/api/v1/repos/a/b/pu\\\\\\nlls/1/reviews"}}\tsame join, review endpoint\n'
  printf '2\t{"tool_input":{"command":"cat >> notes.md <<EOF\\nwe ran: curl -d@b https://git.example.invalid/api/v1/repos/a/b/iss\\\\\\nues/1/comments\\nEOF"}}\tthe join still runs first, and the joined payload is refused in a document too\n'
  # Transparent prefixes take option VALUES, and the value was a word the list
  # did not know — so the client went missing again behind an ordinary `sudo -u`.
  printf '2\t{"tool_input":{"command":"sudo -u root curl -d@b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments"}}\tan option value after a prefix does not hide the client\n'
  printf '2\t{"tool_input":{"command":"timeout --signal TERM 10 curl -d@b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments"}}\tan option pair plus a duration does not hide the client\n'
  printf '2\t{"tool_input":{"command":"xargs echo curl -d@b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments"}}\tthe payload behind xargs echo is refused rather than adjudicated\n'
  printf '0\t{"tool_input":{"command":"sudo apt-get install curl"}}\tinstalling the client is not calling it\n'
  # Execution through another command needed its own case under the old design.
  printf '2\t{"tool_input":{"command":"find . -maxdepth 0 -exec curl -d@b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments ;"}}\tfind -exec runs the client\n'
  # --- round five, and the finding that ended the parser. Command substitution
  # inside a double-quoted span EXECUTES, while the skeleton was discarding that
  # span as inert prose. The unquoted and process-substitution forms already
  # blocked, which is what made it a classification defect rather than a spelling
  # one: the same call was refused or allowed depending on a quote character.
  printf '2\t{"tool_input":{"command":"echo \\"$(curl -d@b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments)\\""}}\tcommand substitution inside double quotes executes\n'
  printf '2\t{"tool_input":{"command":"echo \\"`curl -d@b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments`\\""}}\tso does the backtick form\n'
  printf '2\t{"tool_input":{"command":"msg=\\"$(curl -d@b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments)\\""}}\tand an assignment RHS is not data either\n'
  printf '2\t{"tool_input":{"command":"echo $(curl -d@b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments)"}}\tthe unquoted form, which blocked before and must keep blocking\n'
  printf '2\t{"tool_input":{"command":"cat <(curl -d@b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments)"}}\tprocess substitution, same\n'
  printf '2\t{"tool_input":{"command":"bash --command \\"curl -d@b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments\\""}}\tthe long-option spelling of bash -c needs no entry in any list now\n'
  # A client the guard was never taught is the point of dropping client
  # detection: neither of these names curl at all.
  printf '2\t{"tool_input":{"command":"python3 -c '"'"'import requests; requests.post(\\"https://git.example.invalid/api/v1/repos/a/b/issues/1/comments\\", json={})'"'"'"}}\ta library call is a write with no flag and no curl\n'
  printf '2\t{"tool_input":{"command":"wget --post-data=x https://git.example.invalid/api/v1/repos/a/b/issues/1/comments"}}\twget spells its body differently and is still a write\n'
  # Round six scoped the guard on `https?://`, and review found the absence shape
  # had simply moved to that new boundary: a raw provider CLI carries no scheme,
  # so the guard never reached the write question. These are the reported repros.
  printf '2\t{"tool_input":{"command":"gh api -X POST repos/a/b/issues -f title=x -f body=y"}}\tgh api is a raw write with no URL scheme at all\n'
  printf '2\t{"tool_input":{"command":"gh api -X POST repos/a/b/pulls/1/reviews -f event=APPROVE"}}\tand it reaches the endpoint the review wrapper owns\n'
  printf '2\t{"tool_input":{"command":"tea api -X POST repos/a/b/issues/1/comments -f body=x"}}\ttea api, same shape, different CLI\n'
  printf '2\t{"tool_input":{"command":"curl -X POST -d x git.example.invalid/api/v1/repos/a/b/issues"}}\ta scheme-less host path is still an API write\n'
  printf '2\t{"tool_input":{"command":"gh api repos/a/b/issues -f title=x"}}\tgh POSTs implicitly when handed a field, exactly as curl does with -d\n'
  # ...and the boundary that stops a broader scope gate becoming block-everything.
  printf '0\t{"tool_input":{"command":"gh api repos/a/b/pulls/1"}}\treading through a provider CLI stays untouched\n'
  printf '0\t{"tool_input":{"command":"gh api -X POST repos/a/b/releases -f tag_name=v1"}}\tno wrapper owns releases, whoever calls it\n'
  printf '0\t{"tool_input":{"command":"tea pulls create --title x --repo a/b"}}\tprovider PORCELAIN is out of scope by decision, not by accident\n'
  printf '0\t{"tool_input":{"command":"rm -f /var/tmp/api/v1-issues-notes.txt"}}\t-f is only a body when it carries key=value\n'
  printf '0\t{"tool_input":{"command":"grep -f patterns.txt /src/api/v1/repos/a/b/issues.log"}}\tsame, on the flag agents actually collide with\n'
  # Wrong remediation is its own defect: /issues/1/labels used to block with
  # "use issue-create.sh", which is not the wrapper for that call. Round seven
  # answered that by letting EVERY path under a numbered issue or PR through,
  # and review showed the reasoning ("no wrapper owns these") was false in this
  # tree. These are the reported repros, all rc 0 before round eight, and each
  # asserts the wrapper the advice must name — not merely that a block happened.
  printf '2\t{"tool_input":{"command":"gh api -X PATCH repos/a/b/issues/1 -f title=x"}}\tan issue edit is issue-edit.sh, not a wrapper gap\tissue-edit.sh\n'
  printf '2\t{"tool_input":{"command":"curl -X PATCH -d @b https://git.example.invalid/api/v1/repos/a/b/issues/1"}}\tsame call through curl, same wrapper\tissue-edit.sh\n'
  printf '2\t{"tool_input":{"command":"gh api -X PATCH repos/a/b/issues/1/labels -f labels[]=bug"}}\tlabels are wrapped, and the advice says by which\tissue-edit.sh\n'
  printf '2\t{"tool_input":{"command":"gh api -X POST repos/a/b/issues/1/assignees -f assignees[]=u"}}\tassignees are issue-assign.sh\tissue-assign.sh\n'
  printf '2\t{"tool_input":{"command":"gh api repos/a/b/issues/1/assignees -f assignees[]=u"}}\tthe array field spelling is a body with no -X at all\tissue-assign.sh\n'
  printf '2\t{"tool_input":{"command":"curl -X PATCH -d @b https://git.example.invalid/api/v1/repos/a/b/pulls/1/labels"}}\ta PR is an issue where labels live, so the issue wrapper owns them\tissue-edit.sh\n'
  printf '2\t{"tool_input":{"command":"curl -X PATCH -d @b https://git.example.invalid/api/v1/repos/a/b/pulls/1"}}\tPR state is pr-close.sh, and the gap in that arm is stated\tpr-close.sh\n'
  printf '2\t{"tool_input":{"command":"curl -X PATCH -d @b https://git.example.invalid/api/v1/repos/a/b/milestones/4"}}\ta milestone state change is milestone-close.sh, not the create wrapper\tmilestone-close.sh\n'
  # SPAN. A wrapper that owns a slice of an endpoint must not be advertised as
  # owning the endpoint. milestone-close.sh takes only -t <title> and sends
  # state=closed, so a title/description/due-date edit is a gap and the message
  # has to say so — round eight named the wrapper and stopped there.
  printf '2\t{"tool_input":{"command":"curl -X PATCH -d @b https://git.example.invalid/api/v1/repos/a/b/milestones/1"}}\ta milestone edit blocks, but the advice states the close-only span\towns the CLOSE only\n'
  printf '2\t{"tool_input":{"command":"gh api -X PATCH repos/a/b/issues/1 -f assignee=u"}}\tissue-edit.sh cannot set an assignee, so the message names the one that can\tissue-assign.sh owns the assignee\n'
  # The residue: still genuinely owned by nothing, and still flowing through.
  # Requesting a reviewer is not submitting one; pr-review.sh files verdicts and
  # nothing in the tree adds a requested reviewer.
  printf '0\t{"tool_input":{"command":"gh api -X POST repos/a/b/pulls/1/requested_reviewers -f reviewers[]=u"}}\tno wrapper requests a reviewer, so it is not refused with pr-review.sh\n'
  # SPAN, applied to the guard's OWN fail-closed rule rather than to a wrapper.
  # The scope gate admits three shapes; the unreadable-endpoint rule asked only
  # for `https?://`, so a split endpoint in the other two was in scope to block,
  # produced no readable endpoint, and fell through to allow. Same defect class
  # as the milestone arm, one layer up. Each shape gets its own fixture, because
  # a single one would have passed on the arm that already worked.
  printf '2\t{"tool_input":{"command":"p=repos/a/b/iss; q=ues; gh api -X POST ${p}${q} -f title=x"}}\ta split endpoint in a provider-CLI api call is unreadable, not absent\n'
  printf '2\t{"tool_input":{"command":"p=repos/a/b/issues/1/comm; q=ents; gh api -X POST ${p}${q} -f body=x"}}\tsame, comments\n'
  printf '2\t{"tool_input":{"command":"p=repos/a/b/pulls/1/rev; q=iews; gh api -X POST ${p}${q} -f event=APPROVED"}}\tsame, and a verdict is the costliest one to lose\n'
  printf '2\t{"tool_input":{"command":"p=repos/a/b/iss; q=ues; tea api -X POST ${p}${q} -f title=x"}}\tevery CLI the scope gate admits, not just gh\n'
  printf '2\t{"tool_input":{"command":"p=/api/v1/repos/a/b/iss; q=ues; curl -X POST -d x git.example.invalid${p}${q}"}}\ta schemeless forge host with a split path is unreadable too\n'
  printf '2\t{"tool_input":{"command":"h=git.example.invalid; q=ues; curl -X POST -d x ${h}/api/v1/repos/a/b/iss${q}"}}\tthe expansion may come first; the token is what matters\n'
  # And the reason this is not "any variable blocks a write": a payload in a
  # variable is the SAFE way to pass one and leaves the endpoint fully legible.
  printf '0\t{"tool_input":{"command":"gh api repos/a/b/git/refs -f sha=$SHA"}}\tan expansion in a body value leaves the endpoint readable\n'
  printf '0\t{"tool_input":{"command":"curl -X POST -d \\"$BODY\\" https://git.example.invalid/api/v1/repos/a/b/git/refs"}}\tsame for a quoted body on an unwrapped endpoint\n'
  printf '0\t{"tool_input":{"command":"gh api repos/${OWNER}/${REPO}/git/refs"}}\ta read with a split endpoint is still a read\n'
  printf '0\t{"tool_input":{"command":"curl -X PATCH -d @b https://git.example.invalid/api/v1/repos/a/b/issues/comments/5"}}\tediting a comment has no wrapper; only creating one does\n'
  printf '0\t{"tool_input":{"command":"curl -X POST -d @b https://git.example.invalid/api/v1/repos/a/b/issues/1/stopwatch/start"}}\tno wrapper owns a stopwatch, and none is invented for it\n'
  printf '0\t{"tool_input":{"command":"gh api -X POST repos/a/b/issues/1/times -f time=60"}}\tnor time tracking\n'
  printf '0\t{"tool_input":{"command":"gh api -X POST repos/a/b/issues/1/reactions -f content=+1"}}\tnor reactions\n'
  # ...and the residue must be decided by the SEGMENT, never by a stray slash.
  printf '2\t{"tool_input":{"command":"gh api -X PATCH repos/a/b/issues/1 -f body=see-/docs/x"}}\ta slash inside the body is not a subresource\tissue-edit.sh\n'
  # The arms above the numbered ones must keep blocking, with their own wrappers.
  printf '2\t{"tool_input":{"command":"curl -X POST -d @b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments"}}\tthe wrapped subresource must not fall through\tissue-comment.sh\n'
  printf '2\t{"tool_input":{"command":"curl -X POST -d @b https://git.example.invalid/api/v1/repos/a/b/issues"}}\tnor may issue creation\tissue-create.sh\n'
  printf '2\t{"tool_input":{"command":"curl -X POST -d @b https://git.example.invalid/api/v1/repos/a/b/pulls"}}\tPR creation is wrapped and must not fall through with them\tpr-create.sh\n'
  printf '2\t{"tool_input":{"command":"curl -X POST -d @b https://git.example.invalid/api/v1/repos/a/b/pulls/1/reviews"}}\tand a review still names the review wrapper\tpr-review.sh\n'
  # SPAN a third time, now in the scope gate itself: it asked for `/api/v[0-9]`,
  # which is Gitea's spelling. GitHub's API carries no version segment at all
  # (`api.github.com/repos/...`), so the schemeless Gitea write was in scope and
  # the schemeless GitHub one was not — a gate calibrated to one dialect rather
  # than to what identifies a provider API. `/repos/` is the marker both share.
  # These endpoints are READABLE, so each asserts the wrapper it must name; a
  # rc-only fixture here would pass on the unreadable arm and prove nothing.
  printf '2\t{"tool_input":{"command":"curl -X POST -d x api.github.com/repos/a/b/issues"}}\ta schemeless GitHub host is a provider API even with no version segment\tissue-create.sh\n'
  printf '2\t{"tool_input":{"command":"curl -X POST -d x api.github.com/repos/a/b/issues/1/comments"}}\tsame, and the subresource still names its own wrapper\tissue-comment.sh\n'
  printf '2\t{"tool_input":{"command":"host=api.github.com; curl -X POST -d x ${host}/repos/a/b/issues"}}\tthe host may be a variable; the path is what the guard reads\tissue-create.sh\n'
  printf '2\t{"tool_input":{"command":"curl -X POST -d x api.github.com/repos/a/b/pulls/1/reviews"}}\ta verdict is the costliest call to lose to a spelling\tpr-review.sh\n'
  printf '2\t{"tool_input":{"command":"p=/repos/a/b/iss; q=ues; curl -X POST -d x api.github.com${p}${q}"}}\tand the split form of it is unreadable, not absent\n'
  # The end-of-options marker, which is the one option not spelled like one.
  printf '2\t{"tool_input":{"command":"p=repos/a/b/iss; q=ues; gh api -X POST -- ${p}${q} -f title=x"}}\ta bare -- must not walk the endpoint past the scanner\n'
  # Widening a scope gate may not create a block. Reads and unwrapped endpoints
  # in the newly admitted shape have to stay allowed, or this is a regression
  # wearing a fix'"'"'s clothes.
  printf '0\t{"tool_input":{"command":"curl api.github.com/repos/a/b/issues"}}\tadmitting a shape to the gate does not make a read a write\n'
  printf '0\t{"tool_input":{"command":"curl -X POST -d x api.github.com/repos/a/b/git/refs"}}\tno wrapper owns git refs, on GitHub'"'"'s spelling either\n'
  printf '0\t{"tool_input":{"command":"gh api -- repos/a/b/issues"}}\tthe marker in a read is still a read\n'
  # The APPROVE trap, in the spelling a provider CLI uses, and the value that
  # must never trip it.
  printf '0\t{"tool_input":{"command":"curl -X POST -d {\\"event\\":\\"APPROVED\\"} https://git.example.invalid/api/v1/repos/a/b/releases"}}\tAPPROVED is the correct value and is never the trap\n'
  # Documented over-block, pinned so it is a known boundary and not a surprise.
  printf '2\t{"tool_input":{"command":"python3 -c '"'"'print(\\"https://git.example.invalid/api/v1/repos/a/b/issues/1/comments .post(\\")'"'"'"}}\tprose carrying .post( near a wrapped URL is refused, by the same payload rule\n'
 } > "$FIXTURES"
 fail=0 n=0
 while IFS=$'\t' read -r want payload why remedy; do
  [ -n "${want:-}" ] || continue
  n=$((n + 1))
  out="$(printf '%s' "$payload" | "$GUARD" 2>&1)"
  got=$?
  if [ "$got" != "$want" ]; then
    printf 'FAIL  %s (want exit %s, got %s)\n' "$why" "$want" "$got"
    fail=1
    continue
  fi
  # A block that names the wrong wrapper is a defect in its own right, and until
  # now it was invisible here: the harness read the exit code and nothing else,
  # so /issues/1/labels blocking with "use issue-create.sh" passed every run for
  # six rounds. Where a fixture states the remediation it expects, assert it.
  if [ -n "${remedy:-}" ] && ! printf '%s' "$out" | grep -Fq -- "$remedy"; then
    printf 'FAIL  %s (blocked, but the advice does not name %s)\n' "$why" "$remedy"
    fail=1
    continue
  fi
  printf 'ok    %s\n' "$why"
 done < "$FIXTURES"
 printf '\n'
 if [ "$fail" -eq 0 ]; then
  printf 'wrapper-guard: %d/%d fixtures behaved as specified.\n' "$n" "$n"
 else
  cat <<'EOF'
 wrapper-guard drifted from its contract.
 A guard that blocks too much gets routed around, and a guard that blocks too
 little is decoration. Both directions are failures here, which is why the
 allowed cases are asserted as hard as the blocked ones.
 EOF
 fi
 exit "$fail"
@@ -0,0 +1,484 @@
 #!/usr/bin/env bash
 # wrapper-guard.sh — PreToolUse hook on Bash.
 #
 # Blocks three specific, mechanically-detectable mistakes that prose has
 # repeatedly failed to prevent:
 #
 #   1. A checkout (git clone / git worktree add) targeting $HOME.
 #      Root cause of a fleet host's /home filling to 100% — 255 GB, 842 dirs.
 #
 #   2. A raw provider API WRITE against an endpoint that already has a Mosaic
 #      wrapper. Constitution gate 7 requires the wrapper; the wrapper knows
 #      provider dialect, identity, and queue-guard ordering that raw curl does
 #      not. Reads are untouched — they are how you gather evidence.
 #
 #   3. The literal review event "APPROVE". Gitea's vocabulary is APPROVED;
 #      it accepts APPROVE with HTTP 200, silently files the review PENDING,
 #      and then 422s on submit. This one is unconditionally wrong on Gitea and
 #      is what a verdict silently failing to land looks like.
 #
 # Design constraint: this hook must not become something agents route around.
 # It blocks WRITES to endpoints with a known wrapper, and nothing else. Raw
 # curl for reads, for registry/manifest calls, and for endpoints with no
 # wrapper (there are many) all pass untouched.
 #
 # One consequence is worth knowing before it surprises you: it judges the
 # payload, not the caller, so a command that merely QUOTES such a write is
 # refused as well. See the long note at section 2 for why that trade was made.
 #
 # Break-glass, for a genuine gap where no wrapper can express the call:
 #   MOSAIC_WRAPPER_OVERRIDE=1 <command>
 # Using it means "no wrapper covers this" — if that is wrong, the fix is to
 # extend the wrapper, not to keep typing the override.
 #
 # Exit codes (Claude Code PreToolUse): 0 = allow, 2 = block with message.
 set -euo pipefail
 INPUT="$(cat)"
 CMD="$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null || true)"
 [ -z "$CMD" ] && exit 0
 # Read the command the SHELL will run, not the text as typed. A backslash before
 # a newline is removed before anything else happens, so
 #   curl -d@b https://host/api/v1/repos/a/b/iss\
 #   ues/1/comments
 # executes the comments endpoint while the literal token `issues` never appears
 # in the text. Every check below — position, URL, body, endpoint — reads the
 # joined form, because that is the command.
 CMD="$(printf '%s' "$CMD" | sed -e ':a' -e 'N' -e '$!ba' -e 's/\\\n//g')"
 # Honour the override only when it is set in the command itself or the env.
 case "$CMD" in *MOSAIC_WRAPPER_OVERRIDE=1*) exit 0 ;; esac
 [ "${MOSAIC_WRAPPER_OVERRIDE:-0}" = "1" ] && exit 0
 # The wrappers this guard points at are its own siblings. Resolving relative to
 # this file — rather than to a hardcoded $HOME/.config/mosaic — means the guard
 # names the wrappers from the same install it was launched from, and that it
 # still works from a repo checkout with no installed mosaic home (which is how it
 # is exercised in CI). $HOME remains the fallback for a guard invoked by an
 # absolute path from somewhere unusual.
 W="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
 [ -x "$W/pr-review.sh" ] || W="$HOME/.config/mosaic/tools/git"
 # ---- 1. checkout into $HOME ------------------------------------------------
 if printf '%s' "$CMD" | grep -Eq 'git[^|;&]*(clone|worktree[[:space:]]+add)'; then
  # Any argument that resolves under $HOME and is not under a work filesystem.
  if printf '%s' "$CMD" | grep -Eq "(^|[[:space:]=\"'])(~|\\\$HOME|$HOME)/"; then
    cat <<EOF
 BLOCKED: this checks a repository out under \$HOME.
 \$HOME holds configuration, credentials, state and caches. It does not hold
 checkouts, worktrees, scratch files, or build output. One fleet host's /home hit
 100% (394 G) with 255 GB of agent workspaces accumulated exactly this way.
 Use the helper, which derives the path so you do not have to choose one:
  ~/.config/mosaic/tools/git/mosaic-worktree.sh new <branch>     # /src/<repo>-worktrees/<slug>
  ~/.config/mosaic/tools/git/mosaic-worktree.sh path <branch>    # show where it would go
  ~/.config/mosaic/tools/git/mosaic-worktree.sh rm <branch>      # removal is part of the task
 Worktrees, not clones: they share the object store, and \`git worktree list\`
 makes every one of them enumerable — which is the only reason cleanup can
 ever be safe.
 EOF
    exit 2
  fi
 fi
 # ---- 2/3. provider API writes ---------------------------------------------
 # A raw provider write this guard cares about is two things: a WRITE, and a URL
 # naming an endpoint a Mosaic wrapper already owns. Reads are untouched — they
 # are how you gather evidence — and the many endpoints with no wrapper flow
 # through.
 #
 # It deliberately does NOT ask which program makes the call, or whether that
 # program sits at shell command position. It used to, and that is the whole
 # history of this file. Answering "is this code or is this data" from the text
 # of a shell command required a skeleton with quoted spans and heredoc bodies
 # removed, an invoker list for the forms where a shell executes quoted text, a
 # prefix list for `env`/`sudo`/`timeout`, option-value skipping, and
 # backslash-newline joining. Five rounds of adversarial review put nineteen
 # writes straight through it, and every one had the same shape: the client was
 # ABSENT from the skeleton, so the guard allowed. Variables, line continuations,
 # command prefixes, option values, pipes into a shell, and finally command
 # substitution inside the very quotes the skeleton was discarding:
 #   echo "$(curl -d@b .../issues/1/comments)"
 #   msg="$(curl -d@b .../issues/1/comments)"
 # Classifying code against data in shell text with sed and awk is not a hard
 # problem, it is the wrong problem. It was not even portable: under CI's busybox
 # awk the quote-stripping silently failed, the skeleton kept every quoted span,
 # and the guard started refusing ordinary prose instead — which is the other way
 # a control like this dies.
 #
 # So the client detection is gone, and with it that entire failure class: what
 # is left cannot fail open by hiding the caller, because it never looks for one.
 # It looks for the payload. Something that names a wrapped endpoint and carries
 # a body is refused however it is spelled — curl, wget, `python -c`, or a form
 # nobody has thought of yet.
 #
 # The cost is real and belongs in the open, because over-blocking is how a hook
 # gets switched off: QUOTING one of these calls on a Bash command line now
 # blocks too. `grep -R "curl -d .../issues" docs/` is refused, and so is echoing
 # an example into a file. There is no textual way to tell a quoted example from
 # a quoted command — that is exactly the finding above — so the rule is the one
 # an agent can hold in mind without a parser:
 #
 #   do not put a raw write to a wrapped forge endpoint on a Bash command line,
 #   not even inside quotes.
 #
 # Write the example with a file-writing tool, or leave the body flag out of it.
 # That is a deliberate narrowing of scope, not an oversight. This hook stops
 # mistakes; it is not a sandbox, and pretending otherwise is how you get a
 # control nobody can trust the boundaries of.
 #
 # Scoped to commands that are provider-API-shaped, so nothing else is even
 # considered. The first version of this scope gate asked only for `https?://`,
 # and review found the absence shape had simply moved to the new boundary:
 #   gh api -X POST repos/a/b/pulls/1/reviews -f event=APPROVE
 #   tea api -X POST repos/a/b/issues/1/comments -f body=x
 #   curl -X POST -d x git.example.invalid/api/v1/repos/a/b/issues
 # all carry a real write to a wrapped endpoint and none carries a scheme, so the
 # guard never asked the write question at all. Gate 7 covers raw provider CLIs,
 # so these are in scope and the gate now names the shapes they come in.
 #
 # Then review found the same absence at the same boundary a second time, in the
 # one provider whose paths carry no version marker at all:
 #   curl -X POST -d x api.github.com/repos/a/b/issues
 # GitHub's API is `api.github.com/repos/...`; Gitea's is `/api/v1/repos/...`.
 # Asking for `/api/v[0-9]` therefore admitted the schemeless Gitea write and
 # excluded the schemeless GitHub one — a gate calibrated to one dialect's
 # spelling rather than to what identifies a provider API. So the gate names both
 # markers: a version segment, and the `/repos/` path that every forge API uses
 # to address a repository.
 #
 # Adding alternatives to a scope gate can only make it stricter — it cannot
 # create a new allow — which is why this is a list of triggers rather than a
 # model of any one caller. Downstream, a block still requires a body flag AND
 # either a mapped endpoint or an unreadable one, so widening the gate widens
 # what is CONSIDERED, not what is refused.
 #
 # Residual, stated rather than implied: a caller who splits `/repos/` itself in
 # a schemeless GitHub URL (`h=api.github.com/rep; q=os/a/b/issues`) leaves no
 # literal marker anywhere and is out of scope. That is the same boundary as
 # splitting the hostname — no longer a mistake anyone makes by accident.
 #
 # Boundary, deliberate and worth stating: this covers the `api` subcommand,
 # which is a raw API call wearing a CLI. Provider PORCELAIN (`tea pulls create`,
 # `gh pr merge`) is NOT covered — catching that means modelling every CLI's verb
 # grammar, which is the parser mistake again in a new costume. Porcelain is a
 # gate-7 gap for prose and review to hold, not this hook.
 API_SHAPED='https?://|/api/v[0-9]|/repos/'
 API_SHAPED="$API_SHAPED"'|(^|[[:space:]|;&(])(gh|tea|glab|hub)[[:space:]]+api([[:space:]]|$)'
 if printf '%s' "$CMD" | grep -Eq "$API_SHAPED"; then
  # Write detection, now client-agnostic. Every spelling curl accepts, because
  # the guard is defeated by the one spelling it does not know: `-d@body` (no
  # space) and `--request=POST` (equals form) both slipped past the first
  # version. Plus wget's forms and a library call, which a client-shaped test
  # could not have seen at all.
  #
  # A body flag is read as a body flag wherever it appears. `ls -d */ && curl -s
  # .../issues/1/comments` is therefore refused, which is a read wearing a
  # write's flag. That direction is the acceptable one: it costs an override on
  # a rare command, where the reverse costs a silent raw write.
  is_write=0
  printf '%s' "$CMD" | grep -Eq -- \
    '-X[[:space:]]*(POST|PATCH|PUT|DELETE)|--(request|method)[[:space:]=]*(POST|PATCH|PUT|DELETE)' && is_write=1
  # curl sends POST implicitly when handed a body, in any of these forms.
  printf '%s' "$CMD" | grep -Eq -- \
    '(^|[[:space:]])(-d|-F|-T)|--data([-a-z]*)?[[:space:]=]|--json[[:space:]=]|--form|--upload-file|--post-(data|file)[[:space:]=]' && is_write=1
  # The provider CLIs POST implicitly the same way curl does, when handed a
  # field. Matched only in `-f key=value` shape, so the far more common `rm -f`
  # and `grep -f` cannot be read as a body. The trailing `[]` is the array
  # spelling the provider CLIs use for repeated fields (`-f labels[]=bug`), and
  # without it the key class stopped at the bracket and the field was not seen
  # as a body at all — found while pinning the labels/assignees repros, both of
  # which carry it.
  printf '%s' "$CMD" | grep -Eq -- \
    '(^|[[:space:]])(-f|--field|--raw-field)[[:space:]]+[A-Za-z_][A-Za-z0-9_.-]*(\[\])?=|--input[[:space:]=]' && is_write=1
  # ...and a library call is a write without any flag at all.
  #
  # Second documented over-block, and broader than the body flags because it
  # needs no flag: any text carrying `.post(` near a wrapped URL is refused,
  # including prose that merely quotes it. That follows from the same rule as
  # the quoted-curl cost above — the payload is judged, not the caller — and it
  # is stated here so it is a known boundary rather than a surprise.
  printf '%s' "$CMD" | grep -Eq -- \
    '\.(post|put|patch|delete)\(' && is_write=1
  if [ "$is_write" -eq 1 ]; then
    # The endpoint map, and the rule that keeps it honest: an arm exists here
    # ONLY because a wrapper in this directory owns that call. It is an
    # inventory, not a model — read off `ls tools/git/*.sh` and the flags each
    # script accepts, so it can be re-derived and checked rather than believed.
    # Second column is what the wrapper SPANS; a partial span must be stated in
    # the block message, never rounded up to ownership of the whole endpoint.
    #
    #   /pulls/{n}/reviews          pr-review.sh          full
    #   /pulls/{n}/merge            pr-merge.sh           full (-m method, -d)
    #   /issues/{n}/comments        issue-comment.sh      create only (POST)
    #   /issues|pulls/{n}/assignees issue-assign.sh       full (-a, -r)
    #   /issues|pulls/{n}/labels    issue-edit.sh         sets the whole list;
    #                               issue-assign.sh -l    same
    #   /milestones/{n}             milestone-close.sh    CLOSE ONLY — title,
    #                                                     description, due date
    #                                                     are a wrapper gap
    #   /issues/{n}                 issue-edit.sh         title/body/labels/
    #                                                     milestone; close/reopen
    #                                                     for state; assignee is
    #                                                     issue-assign.sh
    #   /pulls/{n}                  pr-close.sh           state only — title and
    #                                                     body are a wrapper gap
    #   /pulls, /issues,            the create wrappers   full
    #   /milestones
    #
    # Owned by nothing, so they flow through: /issues/comments/{id} (a comment
    # EDIT), /pulls/{n}/requested_reviewers, and the residue caught by
    # subtraction below.
    #
    # Round seven had a single arm allowing EVERY path under a numbered issue or
    # PR, on the reasoning that no wrapper owned any of them. Review showed that
    # was false in this tree — issue-edit.sh takes --title/--body/--labels/
    # --milestone and issue-assign.sh takes assignee/labels/milestone — so the
    # guard was answering "allow" because wrapper ownership had been ASSUMED
    # absent instead of looked up. That is the same absence-driven allow the
    # whole file exists to remove, committed inside the fix for it. The lesson
    # is not "block more"; it is that ownership is an inventory question and an
    # inventory has to be read.
    #
    # Wrong advice remains its own defect — a block an agent cannot comply with
    # teaches that the hook is broken and the override is routine, and a routine
    # override is a guard that is off. So the fix is precision in BOTH
    # directions: every arm names the wrapper that actually owns the call, and
    # anything genuinely unowned still flows through (below).
    #
    # Round eight got the inventory right and the SPAN wrong, which review caught
    # on /milestones/{n}: milestone-close.sh takes only -t <title> and hardcodes
    # state=closed, so it cannot express a title, description or due-date edit,
    # and naming it there told an agent to use a wrapper that cannot make the
    # call. "Which wrapper touches this endpoint" is the wrong question; "does
    # the wrapper SPAN this endpoint" is the right one. Where a wrapper owns only
    # a slice, `alsoown` must say which slice and name the rest as a gap — the
    # treatment /pulls/{n} already had, and that two other arms did not, so this
    # was a consistency failure rather than a missing idea. Auditing every arm
    # for span (not just the reported one) is what found requested_reviewers.
    endpoint=""; wrapper=""; alsoown=""
    case "$CMD" in
      # Requesting a reviewer is not submitting one. pr-review.sh takes
      # -a <action> -c <comment> and files a verdict; nothing in the tree adds a
      # requested reviewer. Unowned, so it flows through — placed above the
      # reviews arm so it cannot be refused with "use pr-review.sh".
      *"/pulls/"*"/requested_reviewers"*) : ;;
      *"/pulls/"*"/reviews"*) endpoint="pull-request review"; wrapper="pr-review.sh" ;;
      *"/pulls/"*"/merge"*)   endpoint="pull-request merge";  wrapper="pr-merge.sh"  ;;
      # A comment EDIT/DELETE lives at /issues/comments/{id} — a sibling of the
      # numbered issue, not a child of it. issue-comment.sh only creates, so
      # nothing owns this one. Placed above the create arm so it cannot be
      # refused with "use issue-comment.sh", which would be the wrong call.
      *"/issues/comments/"*)  : ;;
      *"/issues/"*"/comments"*) endpoint="issue comment";     wrapper="issue-comment.sh" ;;
      *"/issues/"*"/assignees"*|*"/pulls/"*"/assignees"*)
                              endpoint="issue assignee";      wrapper="issue-assign.sh" ;;
      *"/issues/"*"/labels"*|*"/pulls/"*"/labels"*)
                              endpoint="issue label";         wrapper="issue-edit.sh"
                              alsoown="issue-assign.sh -l sets labels too (and the milestone)." ;;
      *"/milestones/"[0-9]*)  endpoint="milestone";            wrapper="milestone-close.sh"
                              alsoown="milestone-close.sh owns the CLOSE only — it takes -t <title>
 and sends state=closed. A milestone's title, description or due date is a real
 wrapper gap: no tool in this tree edits them, and the override exists for it." ;;
      # The numbered object itself. These two arms are the fuzzy ones — they
      # match a number and then anything — so they are refined immediately
      # below rather than trusted as written.
      *"/issues/"[0-9]*)      endpoint="issue edit";          wrapper="issue-edit.sh"
                              alsoown="issue-close.sh and issue-reopen.sh own the state change, and
 issue-assign.sh owns the assignee, labels and milestone fields at this same
 number — issue-edit.sh does not set an assignee." ;;
      *"/pulls/"[0-9]*)       endpoint="pull-request edit";   wrapper="pr-close.sh"
                              alsoown="pr-close.sh owns state=closed. A PR's labels, assignee and
 milestone are the ISSUE object on both providers, so issue-edit.sh and
 issue-assign.sh own those at the same number. Nothing wraps a PR title/body
 edit — that one is a real wrapper gap, and the override exists for it." ;;
      *"/pulls"*)             endpoint="pull request";        wrapper="pr-create.sh" ;;
      *"/issues"*)            endpoint="issue";               wrapper="issue-create.sh" ;;
      *"/milestones"*)        endpoint="milestone";           wrapper="milestone-create.sh" ;;
    esac
    # Refine the two fuzzy arms, and note WHY this is a regex and not another
    # case arm: `case` globs cannot express a path SEGMENT, so an allow arm
    # written as *"/issues/"[0-9]*"/"* would clear
    #   gh api -X PATCH repos/a/b/issues/1 -f body="see /docs"
    # on the strength of a slash inside the body. An allow decided by a glob
    # over the whole command is exactly the fail-open shape this file keeps
    # finding; the regex pins the segment to the number.
    #
    # The residue is defined by SUBTRACTION rather than by listing provider API
    # surface: every subresource a wrapper owns was consumed by an arm above, so
    # whatever still carries /issues|pulls/{n}/<segment> here is owned by
    # nothing — times, stopwatch, reactions, subscriptions, dependencies, a PR's
    # files or commits. Listing them instead would rot the moment a provider
    # adds one, and rot in the blocking direction with wrong advice.
    case "$endpoint" in
      "issue edit"|"pull-request edit")
        if printf '%s' "$CMD" | grep -Eq '/(issues|pulls)/[0-9]+/[A-Za-z_]'; then
          endpoint=""; wrapper=""; alsoown=""
        fi ;;
    esac
    # An endpoint the guard cannot READ is an endpoint the guard must not CLEAR.
    #
    # Round one fixed one spelling of this and review immediately produced the
    # general form: split the endpoint token itself across two variables —
    #   a=/api/v1/repos/o/r/iss; b=ues/1/comments
    #   curl -d@body "https://host${a}${b}"
    # — and no fragment above ever appears contiguously. Chasing that with more
    # fragments is unwinnable: the endpoint does not exist until the shell
    # expands it, and this hook runs before that.
    #
    # So stop pretending to read it. If a write's endpoint contains an expansion,
    # the guard has no endpoint to judge, and "no endpoint" must not mean
    # "allowed" — that is the same absence-driven allow as the missing-wrapper
    # case, wearing different clothes.
    #
    # SPAN, and the defect review found here: a fail-closed rule must cover the
    # same surface as the block it guards. This test asked only for `https?://`
    # while the scope gate above had already been widened to three shapes, so
    #   p=repos/a/b/iss; q=ues; gh api -X POST ${p}${q} -f title=x
    #   p=/api/v1/repos/a/b/iss; q=ues; curl -X POST -d x git.example.invalid${p}${q}
    # were in scope to be blocked, produced no readable endpoint, and then fell
    # through to ALLOW — while the identical split behind a literal `https://`
    # blocked. Same shape as the milestone arm one round earlier: the correct
    # treatment already existed and was applied to one of the surfaces it
    # covered. A control is only as wide as its narrowest arm.
    #
    # Three arms, one per shape the scope gate admits:
    #   A  a scheme-bearing URL token carrying an expansion
    #   B  a schemeless token carrying BOTH a forge fragment and an expansion
    #   C  the endpoint argument of a provider-CLI `api` call carrying one
    #
    # Stated limits, because a control may not claim more than it measures. B
    # requires the fragment and the expansion in the SAME shell token, so a
    # caller who splits the hostname and `/api/` as well gets through. C reads
    # the endpoint positionally — the first bare token after `api` and its option
    # run — so an endpoint pushed past an option whose value itself contains
    # whitespace is not seen. Both are deliberate: this hook stops mistakes, it
    # is not a sandbox, and pretending otherwise is how you get a control nobody
    # can trust the boundaries of.
    #
    # C's option run also accepts the bare `--` end-of-options marker, because
    # review found that `gh api -X POST -- ${p}${q} -f title=x` walked straight
    # past an option class that required a letter after the dashes. The marker is
    # the one "option" that is not spelled like one, and a scanner that skips
    # options had to be told that.
    #
    # Note what is NOT unreadable: an expansion in a BODY (`-d "$BODY"`,
    # `-f sha=$SHA`) leaves the endpoint perfectly legible, and blocking it would
    # punish the safest way to pass a payload. Only the endpoint region counts.
    URLTOK='[^[:space:]"'"'"'|;&)]*'
    FORGE='(/api/v[0-9]|/repos/|git\.|gitea|github\.com|gitlab|forgejo)'
    unreadable=0
    if printf '%s' "$CMD" | grep -Eq "https?://$URLTOK"'[$`]' \
       && printf '%s' "$CMD" | grep -Eq "$FORGE"; then unreadable=1; fi
    printf '%s' "$CMD" | grep -Eq \
      "$URLTOK($FORGE$URLTOK"'[$`]'"|"'[$`]'"$URLTOK$FORGE)" && unreadable=1
    printf '%s' "$CMD" | grep -Eq \
      '(^|[[:space:]|;&(])(gh|tea|glab|hub)[[:space:]]+api([[:space:]]+(--|--?[A-Za-z][A-Za-z-]*)([[:space:]]+[^-[:space:]][^[:space:]]*)?)*[[:space:]]+[^-[:space:]][^[:space:]]*[$`]' \
      && unreadable=1
    if [ -z "$endpoint" ] && [ "$unreadable" -eq 1 ]; then
      cat <<EOF
 BLOCKED: raw provider API write whose endpoint this guard cannot read.
 The endpoint is assembled from shell expansions, so the path it names does not
 exist until the shell builds it — after this check runs. The guard cannot tell
 whether it is a wrapped endpoint, and an unreadable endpoint is not a cleared
 one.
  $W/  <- the wrappers; use the one for the endpoint you are calling
 If you are calling a wrapped endpoint (reviews, merges, comments, pulls,
 issues, milestones), use the wrapper — it also resolves identity explicitly,
 which matters on a host whose default provider login is an admin account.
 If this is genuinely not a provider endpoint, either write the endpoint
 literally so the guard can see what it is, or prefix MOSAIC_WRAPPER_OVERRIDE=1.
 A variable in the BODY is fine and does not trigger this; only the endpoint
 itself has to be legible.
 EOF
      exit 2
    fi
    # Block on the ENDPOINT, never on whether the wrapper file happens to exist.
    # The previous version required `[ -x "$W/$wrapper" ]`, which meant a host
    # with a broken or absent install allowed exactly the raw writes the guard
    # exists to stop — an absence-driven allow, and the second one found in this
    # file. A missing wrapper is a broken install; it is not a licence to bypass
    # gate 7. Say so, and say which is which.
    if [ -n "$endpoint" ]; then
      if [ -x "$W/$wrapper" ]; then
        remedy="Use the wrapper the Constitution (gate 7) requires:
  $W/$wrapper
 Run \`$wrapper --help\` for the flags."
        # Several wrappers can own one endpoint (labels are settable from both
        # issue-edit.sh and issue-assign.sh; state has its own pair). Naming
        # only one of them is how a correct block still ends up reading as
        # wrong advice, so say which wrapper owns which part of the call.
        [ -n "$alsoown" ] && remedy="$remedy
 $alsoown"
      else
        remedy="The wrapper that covers this endpoint is \`$wrapper\`, and it is NOT
 present or not executable at:
  $W/$wrapper
 That is a broken or incomplete install, not permission to send the call raw.
 Repair the install (\`mosaic doctor\`) and use the wrapper."
        [ -n "$alsoown" ] && remedy="$remedy
 $alsoown"
      fi
      cat <<EOF
 BLOCKED: raw provider API write to the $endpoint endpoint.
 $remedy
 The wrappers are not a formality. They carry provider-dialect differences that
 raw curl silently gets wrong — Gitea's review event is APPROVED, GitHub's is
 APPROVE, and Gitea accepts the wrong one with HTTP 200 while filing the review
 as PENDING. They also resolve identity explicitly, which matters on a host
 where the default login is an admin account.
 If no wrapper flag can express this call, that is a wrapper gap: extend the
 wrapper. To proceed anyway for a genuine gap, prefix MOSAIC_WRAPPER_OVERRIDE=1.
 EOF
      exit 2
    fi
  fi
 fi
 # ---- 3. the APPROVE/APPROVED trap, wherever it appears ---------------------
 # Both spellings the trap arrives in: the JSON body `"event": "APPROVE"` and the
 # provider-CLI field `-f event=APPROVE`. The trailing [^A-Z] is what keeps the
 # correct value out of it — APPROVED must never match.
 if printf '%s' "$CMD" | grep -Eq 'event"?[[:space:]]*[=:][[:space:]]*"?APPROVE([^A-Z]|$)'; then
  cat <<EOF
 BLOCKED: review event "APPROVE" is not valid on Gitea.
 Gitea's vocabulary is "APPROVED". It accepts "APPROVE" with HTTP 200, silently
 files the review as PENDING, and then fails the submit endpoint with
 422 "review stay pending" — so the verdict looks placed and is not.
 ("REQUEST_CHANGES" is spelled identically on both providers; only the approve
 path carries this trap.)
 Use $W/pr-review.sh, which sends the correct token for the detected provider.
 Whatever you use, re-read GET /pulls/{n}/reviews and assert state==APPROVED
 before reporting a verdict placed.
 EOF
  exit 2
 fi
 exit 0
@@ -0,0 +1,293 @@
 #!/usr/bin/env bash
 # check-tools-index.sh — assert every shipped tool is discoverable from the
 # resident documentation an agent actually has in context.
 #
 # WHY THIS GATE EXISTS
 # --------------------
 # The framework ships 26 git wrappers. Before this gate, 20 of them were named
 # in neither `defaults/TOOLS.md` nor `guides/TOOLS-REFERENCE.md`. One of the
 # undocumented ones was `pr-review.sh` — the wrapper that carries the
 # APPROVED/APPROVE provider-dialect split.
 #
 # The observable consequence, on a live fleet host: an agent needing to place a
 # review verdict reached for raw `curl`, sent GitHub's `APPROVE` to a Gitea
 # host, and got HTTP 200 with the review silently filed PENDING — three times,
 # because nothing about the failure pointed at the wrapper that already handled
 # it correctly. The agent was not ignoring Constitution gate 7. It was obeying
 # an index that said the tool did not exist.
 #
 # That is not a discipline problem and no amount of prose fixes it. A wrapper
 # that is not in the resident index is, from inside a session, indistinguishable
 # from a wrapper that was never written. So the invariant is mechanical:
 #
 #     shipping a tool and documenting it are the same commit, or CI fails.
 #
 # WHAT IT CHECKS
 # --------------
 #   forward  every non-excluded tool in an ENFORCED suite is named in at least
 #            one index document (missing tool -> undiscoverable -> FAIL)
 #   reverse  every `<name>.sh` an index document attributes to an enforced
 #            suite exists on disk (stale reference -> agent runs a ghost -> FAIL)
 #
 # Suites outside the enforced set are reported with a coverage percentage but do
 # not fail the build, so the ratchet can be tightened one suite per PR instead of
 # landing as one unreviewable sweep. `--strict` fails on those too.
 #
 # WHY THE ENFORCED LIST LIVES HERE AND NOT IN A MARKER INSIDE THE DOC
 # -------------------------------------------------------------------
 # `TOOLS.md` is operator-owned (see framework-manifest.txt). A marker inside it
 # would let an operator silence this gate by editing their own copy — the gate
 # would then be strongest exactly where it is least needed and absent where it
 # is needed most. The list is framework-owned and changes only through a
 # reviewed PR.
 #
 # Usage:
 #   check-tools-index.sh [--tools-dir DIR] [--doc FILE]... [--strict] [--self-test]
 #
 # Exit: 0 = every enforced suite fully discoverable · 1 = drift · 2 = bad usage
 set -euo pipefail
 # Suites whose coverage is a HARD requirement. Add a suite here only together
 # with the doc changes that make it pass.
 #
 # `git` is first because it is the suite Constitution gates 6-8 make mandatory:
 # an undiscoverable git wrapper converts a hard gate into a coin flip.
 ENFORCED_SUITES=(git)
 # Files that are not agent-callable tools and must not be required in an index.
 EXCLUDE_GLOBS=(
  'test-*'        # hermetic regression scripts, invoked by CI not by agents
  '_*'            # private helpers (_lib, _scripts internals)
  '*.bak'         # editor/installer debris
  '*.pre-*'       # pre-change backups (e.g. ci-queue-wait.sh.pre-404fix-bak)
  'README.md'
 )
 STRICT=0
 SELF_TEST=0
 TOOLS_DIR=""
 DOCS=()
 die() { printf 'check-tools-index: %s\n' "$*" >&2; exit 2; }
 while [ $# -gt 0 ]; do
  case "$1" in
    --tools-dir) TOOLS_DIR="${2:-}"; shift 2 ;;
    --doc)       DOCS+=("${2:-}");   shift 2 ;;
    --strict)    STRICT=1; shift ;;
    --self-test) SELF_TEST=1; shift ;;
    -h|--help)   sed -n '2,48p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
    *)           die "unknown argument: $1" ;;
  esac
 done
 # ---- location resolution ---------------------------------------------------
 # Runs from two places with different layouts, and must not silently check the
 # wrong tree: a CI checkout (repo-relative) and an installed host ($MOSAIC_HOME).
 resolve_locations() {
  local here framework
  here="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
  # .../framework/tools/quality/scripts -> .../framework
  framework="$(cd -- "$here/../../.." && pwd)"
  if [ -z "$TOOLS_DIR" ]; then
    if [ -d "$framework/tools" ]; then
      TOOLS_DIR="$framework/tools"
    else
      TOOLS_DIR="${MOSAIC_HOME:-$HOME/.config/mosaic}/tools"
    fi
  fi
  if [ ${#DOCS[@]} -eq 0 ]; then
    # The two layouts are mutually exclusive on purpose. Unioning them would let
    # a well-maintained operator TOOLS.md on the developer's own machine mask a
    # gap in the shipped defaults — the check would pass locally and the defect
    # would still install on every other host. Repo layout wins when present.
    if [ -f "$framework/defaults/TOOLS.md" ]; then
      DOCS+=("$framework/defaults/TOOLS.md")
      [ -f "$framework/guides/TOOLS-REFERENCE.md" ] && DOCS+=("$framework/guides/TOOLS-REFERENCE.md")
    else
      local mosaic_home="${MOSAIC_HOME:-$HOME/.config/mosaic}"
      [ -f "$mosaic_home/TOOLS.md" ]                  && DOCS+=("$mosaic_home/TOOLS.md")
      [ -f "$mosaic_home/guides/TOOLS-REFERENCE.md" ] && DOCS+=("$mosaic_home/guides/TOOLS-REFERENCE.md")
    fi
  fi
  [ -d "$TOOLS_DIR" ] || die "tools dir not found: $TOOLS_DIR"
  [ ${#DOCS[@]} -gt 0 ] || die "no index documents found (pass --doc FILE)"
 }
 is_excluded() {
  local name="$1" glob
  for glob in "${EXCLUDE_GLOBS[@]}"; do
    # shellcheck disable=SC2254  # glob is intentionally a pattern
    case "$name" in $glob) return 0 ;; esac
  done
  return 1
 }
 # A tool counts as documented when its basename appears anywhere in the corpus.
 # Deliberately permissive about *form* (table cell, code fence, prose) and strict
 # about *presence*: the gate's job is "an agent can find it", not house style.
 documented() { grep -qF -- "$1" "$CORPUS"; }
 # ---- the check -------------------------------------------------------------
 run_check() {
  local rc=0 suite dir tool base enforced
  CORPUS="$(mktemp)"; trap 'rm -f "$CORPUS"' RETURN
  cat "${DOCS[@]}" > "$CORPUS"
  printf 'tools:  %s\n' "$TOOLS_DIR"
  for d in "${DOCS[@]}"; do printf 'index:  %s\n' "$d"; done
  printf '\n'
  for dir in "$TOOLS_DIR"/*/; do
    [ -d "$dir" ] || continue
    suite="$(basename -- "$dir")"
    case " ${ENFORCED_SUITES[*]} " in *" $suite "*) enforced=1 ;; *) enforced=0 ;; esac
    [ "$STRICT" -eq 1 ] && enforced=1
    case "$suite" in _*) continue ;; esac
    local total=0 found=0
    local -a suite_missing=() suite_noexec=()
    for tool in "$dir"*.sh; do
      [ -e "$tool" ] || continue
      base="$(basename -- "$tool")"
      is_excluded "$base" && continue
      total=$((total + 1))
      if documented "$base"; then
        found=$((found + 1))
        # Documented AND present is not enough. The index presents these as
        # commands to run, and every caller — the wrapper guard included —
        # decides "is this tool here?" with `[ -x ]`. A 0644 wrapper is
        # documented, present, and dead: it reads as absent to every check that
        # matters while scoring 100% here. That is a false green, which is worse
        # than a red, so it fails rather than warns.
        [ -x "$tool" ] || suite_noexec+=("$base")
      else
        suite_missing+=("$base")
      fi
    done
    [ "$total" -eq 0 ] && continue
    local pct=$(( found * 100 / total ))
    if [ "$enforced" -eq 1 ] && [ ${#suite_noexec[@]} -gt 0 ]; then
      printf 'FAIL  %-12s %3d%% (%d/%d)  documented but not executable: %s\n' \
        "$suite" "$pct" "$found" "$total" "${suite_noexec[*]}"
      rc=1
    fi
    if [ "$enforced" -eq 1 ] && [ ${#suite_missing[@]} -gt 0 ]; then
      printf 'FAIL  %-12s %3d%% (%d/%d)  undocumented: %s\n' \
        "$suite" "$pct" "$found" "$total" "${suite_missing[*]}"
      rc=1
    elif [ "$enforced" -eq 1 ] && [ ${#suite_noexec[@]} -eq 0 ]; then
      printf 'ok    %-12s %3d%% (%d/%d)  [enforced]\n' "$suite" "$pct" "$found" "$total"
    else
      printf 'info  %-12s %3d%% (%d/%d)  not yet enforced\n' "$suite" "$pct" "$found" "$total"
    fi
    # Reverse: an index that names a tool this suite does not have sends agents
    # after something that cannot run. Only checked for enforced suites, where
    # the naming is unambiguous enough to attribute.
    if [ "$enforced" -eq 1 ]; then
      local -a stale=()
      local ref
      while read -r ref; do
        [ -n "$ref" ] || continue
        is_excluded "$ref" && continue
        [ -e "$dir$ref" ] || stale+=("$ref")
      done < <(grep -oE "$suite/[a-z0-9][a-z0-9._-]*\.sh" "$CORPUS" \
                 | sed "s|^$suite/||" | sort -u)
      if [ ${#stale[@]} -gt 0 ]; then
        printf 'FAIL  %-12s stale index references (no such file): %s\n' \
          "$suite" "${stale[*]}"
        rc=1
      fi
    fi
  done
  printf '\n'
  if [ "$rc" -ne 0 ]; then
    cat <<EOF
 Undocumented tools are undiscoverable. An agent cannot obey a hard gate that
 tells it to use a wrapper it has no way to learn exists — it will reach for raw
 curl/gh/tea instead, and the wrapper's provider-dialect handling will be lost.
 Fix by naming each tool above in one of the index documents listed at the top,
 in the same commit that ships it.
 EOF
  else
    printf 'every enforced suite is fully discoverable.\n'
  fi
  return "$rc"
 }
 # ---- self-test -------------------------------------------------------------
 # Proves the gate can actually fail. A checker that only ever passes is
 # indistinguishable from one that is not running, which is the failure mode this
 # whole file exists to prevent — so it must demonstrate a red on demand.
 self_test() {
  local tmp rc
  tmp="$(mktemp -d)"; trap 'rm -rf "$tmp"' RETURN
  mkdir -p "$tmp/tools/git"
  printf '#!/bin/sh\n' > "$tmp/tools/git/documented-tool.sh"
  printf '#!/bin/sh\n' > "$tmp/tools/git/test-ignored.sh"
  chmod +x "$tmp/tools/git/documented-tool.sh" "$tmp/tools/git/test-ignored.sh"
  # run_check reads the TOOLS_DIR / DOCS globals; an array cannot ride in a
  # command-prefix assignment, so point the globals at the fixture directly.
  TOOLS_DIR="$tmp/tools"
  DOCS=("$tmp/doc.md")
  # Case 1: fully documented -> pass.
  printf 'see tools/git/documented-tool.sh for details\n' > "$tmp/doc.md"
  if run_check >/dev/null; then
    printf 'self-test 1/4 ok  (complete index passes)\n'
  else
    printf 'self-test 1/4 FAIL (complete index should pass)\n'; return 1
  fi
  # Case 2: an undocumented tool -> fail.
  printf '#!/bin/sh\n' > "$tmp/tools/git/undocumented-tool.sh"
  rc=0; run_check >/dev/null || rc=$?
  if [ "$rc" -eq 1 ]; then
    printf 'self-test 2/4 ok  (undocumented tool fails the gate)\n'
  else
    printf 'self-test 2/4 FAIL (undocumented tool should fail, got rc=%s)\n' "$rc"; return 1
  fi
  # Case 3: a stale index reference -> fail.
  rm "$tmp/tools/git/undocumented-tool.sh"
  printf 'also tools/git/deleted-tool.sh\n' >> "$tmp/doc.md"
  rc=0; run_check >/dev/null || rc=$?
  if [ "$rc" -eq 1 ]; then
    printf 'self-test 3/4 ok  (stale index reference fails the gate)\n'
  else
    printf 'self-test 3/4 FAIL (stale reference should fail, got rc=%s)\n' "$rc"; return 1
  fi
  # Case 4: documented, present, and NOT executable -> fail. Found by an
  # independent reviewer: a 0644 wrapper scored 100% here while reading as
  # absent to every `[ -x ]` in the fleet, including the wrapper guard's.
  sed -i '/deleted-tool/d' "$tmp/doc.md"
  printf '#!/bin/sh\n' > "$tmp/tools/git/noexec-tool.sh"
  chmod 0644 "$tmp/tools/git/noexec-tool.sh"
  printf 'and tools/git/noexec-tool.sh\n' >> "$tmp/doc.md"
  rc=0; run_check >/dev/null || rc=$?
  if [ "$rc" -eq 1 ]; then
    printf 'self-test 4/4 ok  (documented but non-executable tool fails the gate)\n'
  else
    printf 'self-test 4/4 FAIL (non-executable tool should fail, got rc=%s)\n' "$rc"; return 1
  fi
  printf '\nself-test passed: the gate demonstrably reds on every drift direction.\n'
 }
 if [ "$SELF_TEST" -eq 1 ]; then
  self_test
 else
  resolve_locations
  run_check
 fi