feat(plugin): a directory says which project it belongs to, git repo or not (#4085)

All six hooks scoped their requests one way: `git remote get-url origin`,
resolved server-side through the repo bindings. That key does not exist
outside a git repo, so a session in a plain directory was unscoped in every
hook at once — no project context, no prior-art scoping, no project rules —
and silently, because a missing remote is indistinguishable from a remote
nobody bound.

A `.scribe` file is the second key, read by the shared scribe_scope_query so a
directory scopes the same way everywhere:

    {"instance": "https://scribe.example.com", "project_id": 2, "project": "…"}

`instance` is why the file is not just a number: an id is a different project
on every Scribe, so a marker that travels — a copied directory, a shared
machine, a repo someone else clones — would otherwise scope the session to the
wrong project without a word. Compared host-only, and a mismatch drops the id:
no project beats the wrong project. A bare integer is accepted too, since it
is what a person writes by hand. The marker beats a git remote — someone put
the file there on purpose — which is also how a directory overrides its
binding.

Two things it found on the way:

  * An explicit project_id that did not resolve rendered NO message at all —
    the branch hung off `if project_id` as an `elif`, so a caller holding a
    pointer it believed in got a context that silently omitted the project it
    had asked for. Now reported.
  * The refusal reason was a global set inside a function every caller reads
    through `$( )`. The assignment died with the subshell, leaving the caller
    to read an unset variable under `set -u` — which aborts the hook and costs
    the whole session's SessionStart context, to fetch a warning about a file.
    It comes back through stdout with the id instead, and a test pins it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy

plugin/hooks/scribe_defs.sh

@@ -19,6 +19,11 @@
 #   scribe_rules_live FILE     live rule ids from the exclusion ledger,
 #                              comma-joined; entries age out (#3751)
 #   scribe_rules_append FILE   stdin ids -> the ledger, timestamped
+#   scribe_scope_query DIR     `project_id=N` or `repo=<enc>` for DIR — the
+#                              project-scope key EVERY hook sends (#4085).
+#                              Helpers: scribe_marker_file, scribe_url_host,
+#                              scribe_marker_read (id<TAB>why-not),
+#                              scribe_marker_project (the id alone)
 #
 # Sourced, not executed: `. "$(dirname "${BASH_SOURCE[0]}")/scribe_defs.sh"`.
 
@@ -283,3 +288,124 @@ scribe_rules_append() {
   now=$(date +%s 2>/dev/null) || now=0
   awk -v ts="$now" 'NF { print $1 "\t" ts }' >> "$f" 2>/dev/null || true
 }
+
+# ---------------------------------------------------------------------------
+# WHICH PROJECT IS THIS DIRECTORY'S? (#4085)
+#
+# Every hook here scopes its request to a project, and until this existed all
+# six did it the same single way: `git remote get-url origin`, resolved
+# server-side through the repo bindings. That works well inside a bound repo
+# and not at all outside one — a session in a plain directory got no project
+# scope from ANY hook, silently, because the one key the whole chain turns on
+# only exists in a git repo.
+#
+# The second key is a `.scribe` file in the directory (or above it, the way
+# git finds its root), naming the project the work belongs to. It is a
+# POINTER, not a copy: an id and enough to check the id means what it says.
+# Nothing Scribe should be holding goes in it.
+#
+#   {"instance": "https://scribe.example.com", "project_id": 2,
+#    "project": "FabledScribe"}
+#
+#   instance    WHICH Scribe the id belongs to, and the reason this file is
+#               not just a number. A project id means nothing on its own: id 2
+#               is a different project on every instance, so a marker that
+#               travels — a copied directory, a shared machine, a repo someone
+#               else clones — would silently scope a session to the wrong
+#               project. Compared HOST-ONLY against the configured endpoint, so
+#               http/https and a trailing slash don't cause a false mismatch.
+#               A mismatch drops the id: no project beats the wrong project.
+#   project_id  the pointer itself. Required.
+#   project     a human label. NOTHING READS IT. It is there so the file
+#               answers "what is this?" when opened, and so a stale one is
+#               visible rather than inert.
+#
+# A bare integer is also accepted (`echo 2 > .scribe`), because it is what a
+# person writes by hand and it parses as JSON already. It skips the instance
+# check by having nothing to check — deliberate, and the reason the written
+# form carries `instance`.
+#
+# THE MARKER WINS over a git remote. Someone put the file there on purpose;
+# a remote is just where the code happens to be pushed. That also makes the
+# marker the way to override a binding for one directory.
+
+# Nearest `.scribe` at or above DIR. Walks up to the filesystem root, capped so
+# a pathological path cannot spin.
+scribe_marker_file() {
+  local dir="$1" depth=0
+  [ -n "$dir" ] || return 0
+  while [ "$depth" -lt 40 ]; do
+    [ -f "$dir/.scribe" ] && { printf '%s' "$dir/.scribe"; return 0; }
+    case "$dir" in ""|"/") return 0 ;; esac
+    dir=$(dirname -- "$dir" 2>/dev/null) || return 0
+    depth=$((depth + 1))
+  done
+  return 0
+}
+
+# Host of a URL, lowercased, port kept. "" for empty input.
+scribe_url_host() {
+  printf '%s' "${1:-}" \
+    | sed -e 's#^[A-Za-z][A-Za-z0-9+.-]*://##' -e 's#^[^/@]*@##' -e 's#[/?].*$##' \
+    | tr 'A-Z' 'a-z'
+}
+
+# Read a marker file: prints "ID<TAB>REASON", at most one of them non-empty.
+#
+#   "7\t"            use project 7
+#   "\tnames no …"   a file is there and deliberately NOT used; say why
+#   "\t"             no marker file at all — the ordinary case, say nothing
+#
+# One line rather than an id plus a global, because every caller reads this
+# through `$( )` and a global set inside a command substitution dies with the
+# subshell. The caller would then read an unset variable, which under the
+# `set -u` these hooks all run with aborts the hook and costs the whole
+# session's context — a failure far larger than the message it was fetching.
+scribe_marker_read() {
+  local f="$1" id inst want
+  [ -n "$f" ] && [ -f "$f" ] || { printf '\t'; return 0; }
+  command -v jq >/dev/null 2>&1 || { printf '\t'; return 0; }
+  # A bare integer is valid JSON, so one filter reads both forms.
+  id=$(jq -r 'if type=="number" then (.|floor|tostring)
+              elif type=="object" then (.project_id // empty | tostring)
+              else empty end' "$f" 2>/dev/null) || id=""
+  case "$id" in ''|*[!0-9]*) id="" ;; esac
+  if [ -z "$id" ] || [ "$id" = "0" ]; then
+    printf '\tnames no project_id'
+    return 0
+  fi
+  inst=$(jq -r 'if type=="object" then (.instance // empty) else empty end' "$f" 2>/dev/null) || inst=""
+  if [ -n "$inst" ]; then
+    want=$(scribe_url_host "${url:-}")
+    inst=$(scribe_url_host "$inst")
+    if [ -n "$want" ] && [ "$inst" != "$want" ]; then
+      printf '\tpoints at %s, but this session is configured for %s' "$inst" "$want"
+      return 0
+    fi
+  fi
+  printf '%s\t' "$id"
+}
+
+# Just the id a marker names, or "" — the half scribe_scope_query needs.
+scribe_marker_project() {
+  scribe_marker_read "$1" | cut -f1
+}
+
+# The query args identifying DIR's project — `project_id=N` or `repo=<enc>` —
+# with NO leading `?` or `&`, so each caller keeps its own separator. Empty
+# when neither key is available. Requires `url` to be set (scribe_config) for
+# the marker's instance check; without it a marker is still honoured, since an
+# unconfigured hook is not going to send the request anyway.
+scribe_scope_query() {
+  local dir="$1" id repo enc
+  id=$(scribe_marker_project "$(scribe_marker_file "$dir")")
+  if [ -n "$id" ]; then
+    printf 'project_id=%s' "$id"
+    return 0
+  fi
+  repo=$(git -C "$dir" remote get-url origin 2>/dev/null || true)
+  [ -n "$repo" ] || return 0
+  command -v jq >/dev/null 2>&1 || return 0
+  enc=$(printf '%s' "$repo" | jq -sRr '@uri' 2>/dev/null) || enc=""
+  [ -n "$enc" ] && printf 'repo=%s' "$enc"
+}