Tooling — Global vs. Project Decision Matrix

Every development/AI tool SenseBridge uses, where it lives, and how to run it. The standing rule: global by default; project-level only when the repo needs a pinned, portable, or shareable config. Fewer, higher-quality tools beat more tools.

This file is current state. The decision history behind every row — why a tool was chosen or refused, what broke, what superseded what — lives in docs/archive/TOOLING-DECISIONS.md, split out 2026-08-01 when this file had reached 92 KB (~23k tokens to read) and had become session-by-session archaeology rather than a reference. Look a tool up by name there before changing anything about it; the reasoning is usually load-bearing.

SenseBridge is a Swift/SwiftUI iOS app with no Node or Python stack in the app itself — that fact still decides most rows below. The repo also has a small, deliberately separate Node/web stack under website/ (the marketing site). It changes nothing about the app: no Node, Python, backend, container, or orchestration platform touches app/.

Project-level (in this repository)

Claude Code hooks in detail

Each subsection below is self-contained: an agent looking for one of these answers can stop reading after it.

Read-token discipline

cap-large-read.sh, warn-duplicate-read.sh, and prefer-serena.sh shape what a read costs. Measured effect of the read pair (2026-08-01): mean cost per Read fell 911 → 826 tokens, about 9%, and reads over 8k stayed flat at ~1.2%. Modest because most reads were already small — keep them, but do not expect them to be the lever.

cap-large-read.sh treats TODO.md and COMPLETED.todo as queue files: a Read with no offset and no limit is clamped to 120 lines and pointed at Grep for the ### section heading, because TODO.md was the most expensive file in the whole transcript corpus (264k tokens over 182 reads) and nobody ever needs it sequentially. An explicit offset or limit falls through to the ordinary 500-line rule.

limit-agent-fanout.sh caps subagent fanout, and prefer-rtk-shape.mjs auto-rewrites the command shapes RTK’s own hook skips — pipes, redirects, loops, substitutions, subshells, eval.

Permission-rule path globs do not reach MCP tool arguments

Read(**/*.pem) and Edit(legal/**) scope by path for built-in tools only, because MCP rules match on tool name alone. Confirmed by probe on 2026-08-01, not inferred: with the built-in Read of a scratch .pem denied, mcp__filesystem__read_text_file returned that same file’s contents and mcp__filesystem__write_file wrote to it.

guard-serena-legal.sh had already patched one case (legal/, Serena’s six mutating tools); guard-mcp-sensitive-paths.mjs closes the rest, denying the whole mcp__filesystem__* family plus Serena’s mutators on credential material and legal/. It imports its taxonomy from tools/check-sensitive-files.mjs rather than restating it, so the run-time guard and the commit-time gate cannot drift apart, and it is the one hook here that fails closed — an unparseable payload means the path is unknown, which is exactly what malformed input produces.

The same bypass shape existed on the token-discipline side: cap-large-read.sh and warn-duplicate-read.sh only recognized file_path (native Read’s field), so mcp__serena__read_file (relative_path) and mcp__filesystem__read_text_file (path) skipped both the size cap and the duplicate-read nudge entirely. Fixed 2026-08-03: both now check file_path // path // relative_path, wired to those two MCP tools via their own PreToolUse matcher group — kept separate from prefer-serena.sh, which would otherwise misfire advising “use Serena” on a call that already is one. The limit-field rewrite stays Read-only: Serena’s read_file (start_line/end_line) and the filesystem MCP’s read_text_file (no pagination field) have nothing this hook can safely rewrite, so those two get an advisory additionalContext with no attempted clamp.

Bash arguments are not path-scoped either

guard-bash-secret-read.mjs mirrors the same rules for the shell — same imported taxonomy, third enforcement point. It is best-effort and bypassable by design, and must never be cited as a boundary: Bash is a general-purpose interpreter, so python3 -c 'open(".env").read()', a here-doc, a base64 round trip, or a path assembled from variables all sail past. Demonstrated, not assumed (2026-08-01).

What it buys is the accident: cat .env on autopilot, a grep -r wandering into a key file, a cp of signing material to a scratch dir. It peels rtk/sudo/env wrappers (a guard blind to the rtk prefix would be blind on this repo’s normal path) and judges each &&, ;, and pipe segment independently, so a readme read chained to a discard of a stale key stays allowed. Unlike its MCP sibling it fails open — it sits on the Bash path, so failing closed on a parse error would take the session down to defend a boundary it already admits it cannot hold. Validated against 20 real commands replayed from the session that built it: zero false positives.

guard-main-commit.sh and guard-destructive-git.sh are each registered three times — for Bash(git *), Bash(rtk git *), and Bash(rtk proxy git *) — so neither RTK’s transparent rewrite nor its byte-exact passthrough can slip a destructive command past a guard. The if conditions mean at most one variant spawns per command.

A guard that fires on prose is a defect, not caution

guard-main-commit.sh used to deny any command whose text contained git commit, blocking test fixtures and docs that merely quoted it — which teaches agents to route around the guard. Quoted string literals are now blanked before classification, with commands that execute a string (eval, sh -c) opting out so their contents stay visible.

guard-protected-delete.sh had the same defect and got the same treatment on 2026-08-01, after it denied two commands whose here-doc data merely mentioned a discard verb near a protected path: its sed 's/<<.*//' ran line by line, so it truncated the cat <<EOF line and left the body it was meant to cut. The blanking could not simply be copied, though — this guard matches on an argument, and arguments are routinely quoted, so blanking quoted text wholesale would have let rm -rf "sessions/x" through. It instead walks the command once, quote-aware, keeping two views per segment: quoted runs collapsed for verb detection, quote characters dropped but contents kept for path detection. Splitting is quote-aware for the same reason, so a ; inside a string does not start a new command.

Self-checks and registration gates

Self-checks live in .claude/hooks/tests/ (12 suites) and .claude/hooks/global/tests/ (4 suites), both run by npm run check:hook-tests. The runner globs *.test.sh and *.test.mjs, so a new suite is picked up without wiring.

npm run check:hooks verifies every registered hook script still exists and is executable — a renamed or deleted hook otherwise fails silently, since Claude Code logs the spawn error and carries on, leaving the config claiming a guarantee that is gone. It also cross-checks .mcp.json against the guard-mcp-sensitive-paths.mjs matcher: every project-scoped MCP server inherits the name-only-matching bypass, and the guard itself needs no change when one is added — only its matcher does, which nothing else would notice. Adding a server now fails the gate until it is either covered by the matcher or recorded in MCP_SERVERS_WITHOUT_PATH_ARGS with the reason it takes no filesystem path.

That gate sees project-scoped servers only. User-scope servers (claude mcp add -s user, e.g. filesystem) live in the owner’s global config, which a tracked repo gate cannot read. The user-global ~/.claude/hooks/away-guard.sh carries the same fix and its own suite at ~/.claude/hooks/tests/away-guard.test.sh — deliberately not run by this repo’s CI, since gating a repo on a user-global file would break every other clone.

Global (installed on this machine, nothing to add to the repo)

Claude skills and plugins

Installed globally (user scope) from source-verified marketplaces, plus the project-scoped skills under .agents/skills/ and .claude/skills/. The full install log — what was added when, from which marketplace, and which candidates were evaluated and refused — is in the archive.

Two rules below are live constraints, not history, and are linked from CLAUDE.md:

Impeccable project root — always the repo root

Impeccable keys its state directory (.impeccable/) to its resolved project root. Absent a monorepo marker — and this repo has none (no root package.json workspaces, no pnpm-workspace.yaml/turbo.json/nx.json/ lerna.json; the root .git halts its upward search) — that resolver falls back to whatever directory it was invoked from. cd docs && node …/context.mjs roots .impeccable/ in docs/.

Repo root is the only supported root, and this is not merely a convention: the editor hook (hook-lib.mjs → resolveCacheCwd) hard-keys to the repo root because .git is one of its project-root markers, so the hook writes the root .impeccable/ no matter which file was edited. A second .impeccable/ elsewhere is therefore always a stray, never a second valid project — it silently misses the real ignore rules and cache in the root one.

Three defenses, all in place:

1. CI runs from the root. website-ci.yml’s design-qa job deliberately omits the working-directory: website that its lint job uses, and passes website as a target argument instead (npx impeccable detect website). This was the one automated path that created a stray.
2. .gitignore ignores impeccable local state at any depth (**/.impeccable/…). The patterns contain a slash, so without **/ they would anchor to the repo root only and a stray’s session/cache files would land in git status as untracked noise.
3. Manual invocations: keep cwd at the repo root, as SKILL.md’s setup step already instructs, and scope work with --target <path>.

Impeccable design context — .agents/context/, not website/

Impeccable’s context resolver looks for PRODUCT.md/DESIGN.md at the project root, then .agents/context/, then docs/ (first match wins; there is no config key for this, and IMPECCABLE_CONTEXT_DIR is consulted only when those find nothing). Since the project root is necessarily the repo root, the site’s design context lives in .agents/context/PRODUCT.md and .agents/context/DESIGN.md — the one location that resolves deterministically without misrepresenting the repo.

Two files named PRODUCT.md, deliberately, with different scopes:

They complement rather than contradict: the app doc owns product strategy and the context doc cites it for the positioning wedge. Each states its own scope up top so neither can be mistaken for the other.

This was a real defect until 2026-07-16, not a theoretical one: the context files had been written to website/, so impeccable — resolving from the repo root — fell through to docs/PRODUCT.md and loaded the app’s strategy doc as the design context for the website, with designPath: null (no design system at all). Every critique/audit/polish ran mis-primed. Verify the fix with:

node -e "import('./.agents/skills/impeccable/scripts/context.mjs').then(m=>{
  const c=m.loadContext(process.cwd());
  console.log(c.productPath, c.designPath);
})"
# expect: .agents/context/PRODUCT.md .agents/context/DESIGN.md

Do not “helpfully” move these back next to the site they describe — that is what caused the bug. If a future app/ surface ever needs its own impeccable context, .agents/context/ holds one project’s context, so that needs a real decision (impeccable’s own init.md prescribes a per-app PRODUCT.md plus a root one for the primary surface — which requires the workspace markers this repo deliberately does not have).

Not needed (and why)

MCP inventory

Verified against ~/.claude.json and .mcp.json on 2026-08-01. Seven servers (dune, github, gitnexus, glyph, granola, memory, sequential-thinking) were removed from the user-scope config on 2026-07-31 after 30 days with zero calls; headroom was removed when its routing was disabled. codegraph, graphify, and glyph still work as CLIs from Bash; gitnexus was uninstalled entirely on 2026-08-24. Their original entries are in the archive.

Adding an MCP server to this repo requires: local-first, least privilege, a row in this table, and — if it could ever see user-surroundings data — a privacy-doc update per docs/PRIVACY.md.

.claude/settings.global.json — the shareable global config

CLAUDE.template.md publishes the engineering standard as prose; .claude/settings.global.json publishes the harness settings that enforce the mechanical half of it, and .claude/hooks/global/ ships the four guard scripts it registers. Copy both into your own user-global config:

# macOS/Linux — merge the JSON by hand if you already have one; it is not a patch.
cp .claude/hooks/global/*.sh .claude/hooks/global/*.mjs ~/.claude/hooks/
cp .claude/hooks/global/tests/* ~/.claude/hooks/tests/
chmod +x ~/.claude/hooks/*.sh
cp .claude/settings.global.json ~/.claude/settings.json

Install the scripts and the settings together or neither. A registration whose script is missing fails to spawn silently — Claude Code notes it in its own log and the transcript looks exactly like a guard that passed.

RTK.template.md is a separate, optional companion — copy it to ~/.claude/RTK.md only if you install the RTK token-compaction proxy CLAUDE.template.md’s Tools section references. It has no drift check (unlike the guards above): it is prose, not load-bearing config, so a stale copy degrades to a documentation-freshness issue rather than a hook that silently stops firing.

What it contains. Credential and build-artifact deny rules for Read, Grep, and Edit (the §10 secrets rule, enforced rather than trusted); read-only allow entries for RTK, Serena, and Docker so routine inspection does not prompt; deny on the destructive Docker prunes and the Docker MCP’s config-mutating tools; ask on the escape hatches (rtk run, rtk pipe, docker run/exec, mcp-exec, Serena’s two destructive tools); the tmp/handoff.md loader from §5; RTK’s Bash rewrite hook; the four project-agnostic guards described below; and effortLevel: high, which the standard names as the default tier.

Rules that only restrict are shipped even when they name a tool you may not have installed — a deny for an absent MCP server is an inert no-op, whereas shipping the permissive half of a pair without its restrictive half would make this template quietly looser than the config it came from.

What it deliberately omits.

• Personal preferences — model, theme, tui, editorMode, verbose, notification channels, enabledPlugins, extraKnownMarketplaces. These are taste, not standard.
• Machine-specific hooks — anything calling a script under ~/.claude/hooks/ or ~/bin/ that this repo does not ship (wake-lock management, away-mode guards, time tracking, graph indexing, disk-space checks). A registration whose script is absent fails to spawn silently, which is worse than no registration at all. The four guards are registered precisely because .claude/hooks/global/ ships them; that is the whole distinction.

The four project-agnostic guards — guard-attribution.sh, guard-commit-shape.sh, guard-long-running-server.sh, and require-doc-comments.mjs — are addressed by $HOME/.claude/hooks/… rather than ${CLAUDE_PROJECT_DIR}, because a user-scoped hook has no project directory to anchor to. They are not registered in this repo’s own .claude/settings.json: they enforce rules that hold in every repository, so they live in one place, and a second registration here would fire each guard twice. Rows in the map below marked (user-global) are the ones this covers.

Prerequisites. The RTK hook needs rtk on PATH; the Serena allow entries need the Serena MCP server configured. Both are no-ops otherwise, beyond a spawn error per Bash call if rtk is missing — drop that hook entry if you do not use RTK.

tools/check-settings-hooks.mjs fails the build if this file stops being valid JSON, gains an absolute home path / machine-specific helper name / private service name / personal-preference key, registers a $HOME script that .claude/hooks/global/ does not ship, or drifts from an installed copy at ~/.claude/hooks/. The check exists because every one of those failures is invisible: the JSON stays valid and the harness loads it, and the only symptom is a setting that silently does nothing for whoever copied it.

Rules enforced mechanically — the CLAUDE.md ↔ hook map

CLAUDE.md states each rule once, in one line, and points here for the mechanism. That split only stays honest if the mapping is written down: a rule whose hook is renamed, unregistered, or quietly deleted would otherwise revert to nothing at all, with the short line in CLAUDE.md still implying it is covered. tools/check-settings-hooks.mjs guards the registration side (every hook exists, is executable, and is registered exactly once); this table is the human-readable side.

Every hook carries its own self-check under .claude/hooks/tests/, and the user-global four under .claude/hooks/global/tests/. npm run check:hook-tests runs both sets. Run the lot before touching any of them.

Rows marked (user-global) enforce project-agnostic rules from the global CLAUDE.md rather than SenseBridge rules, so they run from ~/.claude/hooks/, registered once in the owner’s ~/.claude/settings.json — registering them here as well would fire each guard twice per command. The canonical scripts are tracked at .claude/hooks/global/ and ~/.claude/hooks/ holds installed copies; npm run check:hooks fails on drift between the two, so the reviewed copy is always the running one. A clone that has not run the install step from that README does not inherit these guards — checking out the repo is not sufficient.

What is deliberately not mechanized, and so stays as prose in CLAUDE.md and AGENTS.md: the awareness-not-safety doctrine, the zero-unlabeled-elements gate, protocol-seam and main-thread invariants, model-license clearance, and every judgment rule about scope, simplicity, and architecture. A hook can check a string; it cannot decide whether a spoken phrase claims unearned certainty.

Guardrails required for every tool, MCP server, script, hook, or utility

This is a blocking requirement, not a suggestion — apply it before adding anything under scripts/, tools/, .githooks/, .claude/hooks/, an MCP server config, or any other executable automation in this repo:

• Fail closed, fail loud. Shell: set -euo pipefail. Node/other: non-zero exit and a clear stderr message on error, never a silent no-op on an unexpected condition.
• Validate and quote everything. Allowlist input (e.g. tools/new-audit.sh’s type enum), quote every variable expansion, and prefer argv-array process spawning (execFileSync(cmd, [args])) over shell string interpolation — never build a shell command by concatenating untrusted input.
• Bound the blast radius. No destructive action (delete, force-push, overwrite, main-branch push) without an explicit opt-in flag or an already-documented exception; time out or cap anything that could run away (see .claude/hooks/limit-agent-fanout.sh’s session cap, .githooks/post-checkout’s rebuild timeout).
• Least privilege. Local-first; no network call, no credential, no broader filesystem access than the task needs. A new MCP server follows the row above; a new script or hook follows the same principle.
• Advisory vs. blocking, stated explicitly. Say in a comment whether a missing dependency or failed check blocks (exits non-zero) or just warns (see scripts/setup.sh’s required-vs-advisory split) — never leave it ambiguous.
• No secrets, ever. Nothing that reads, logs, or embeds a credential — see tools/check-sensitive-files.mjs and docs/ENVIRONMENT.md.

Existing scripts/hooks in this repo (audited 2026-07-17) already follow this; use them as reference implementations rather than reinventing the pattern.

Need help? See SUPPORT.md.