git:20260820.3125eb5 to git:20260820.c27c91c

# AGENTS.md — Working on ClaudeWatch

This is the build philosophy and key constraints document for ClaudeWatch.

The contract lives in [`SPEC.md`](SPEC.md); this document captures the *how to

think about it*. Every Claude Code session should read this before making

non-trivial changes.

## What ClaudeWatch is

A Claude Code plugin that wraps every shell invocation — `Bash` and `Monitor`,

which runs its command in the same shell — in a `PreToolUse` hook and applies

regex-based safety rules. The core safety advantage over Claude

Code's built-in deny rules is that patterns match **anywhere** in the command

string (`re.search()`), so compound commands (`git add . && git push --force`),

heredocs, and reordered flags are not bypassable by syntactic tricks.

## Core contracts (don't break these)

No clocks, no randomness, no network on the decision path. `cwd` and

`CLAUDE_PROJECT_DIR` enter the decision only as the deterministic per-invocation

inputs the `is_in_project_tree` predicate ([RL-15], [RL-16]) resolves `rm`

targets against — pure string work, no filesystem access. `CLAUDE_PROJECT_DIR`

[LOG-01]–[LOG-04]; `CLAUDEWATCH_LOG=off` opts out) is a side channel: it

stamps a timestamp and writes a file *after* the decision is computed, never

feeding back into it. Keep it that way — the clock stays in `_log_event`, not

in `evaluate_rules`.

2. **Exit code is always 0.** A non-zero exit blocks the host (Claude Code)

from getting a useful decision. All errors are surfaced as `deny` decisions

with explanatory messages.

3. **Single coalesced decision per invocation.** Multiple matching rules

across multiple rule sets aggregate into one `deny` (preferred) or one

`ask`. Never emit more than one decision.

4. **The engine ships self-contained.** `scripts/watchdog.py` and everything on

the decision path use only the Python standard library (with a minimal

built-in YAML parser), so the plugin installs cleanly and evaluates rules

fast in any environment Claude Code runs in — no pip step on the hot path.

Build- and release-time tooling that never runs on the decision path (e.g.

`scripts/gen-plugin-json.py`) may use PyYAML; it runs only in dev and CI.

5. **Allow-by-default.** When no rule matches, the engine produces no stdout

output. Silence is allow.

## Build philosophy

- **The engine is generic; the rules are domain-specific.** Treat

`scripts/watchdog.py` as a stable library. New safety domains are new YAML

files in `watches/`, not new code.

- **`unless_condition` predicates are the one exception, so keep them thin.**

A predicate answers something a regex cannot — "does this path resolve inside

the tree" — so it is domain logic living in the engine, and adding one *is* an

engine change with a spec requirement behind it. Push everything that isn't

the domain judgment down into a shared helper: `_command_operands` parses

POSIX utility syntax and takes the program as an argument, so a predicate for

a different destructive tool reuses it rather than writing a second tokenizer

that drifts from its guards. A predicate that has grown its own parsing is

the signal that something belongs in the shared layer.

- **Make adding a rule set frictionless.** Drop a `watch-*.yml` file, add a

test file, regenerate docs. No registration, no manifest, no engine change.

- **Rules are documentation.** Every rule has a `reason` and (almost always) a

`ref` URL. The canonical message is `<rule>: <reason> — <ref>`, used verbatim

in the prompt and the log alike; the rule-set name is omitted since the `ref`

URL supplies it. If you can't articulate why a rule exists, don't add it.

- **Block is for "no recovery"; ask is for "permanent but recoverable".**

`git push --force` blocks (overwrites remote history). `git commit` asks

(you can amend or reset). When in doubt, prefer `ask` — block rules are

un-bypassable.

- **`except` is a noise filter, not a security exception.** `except` only

applies to ask rules; block rules ignore it with a stderr warning. Use

`except` to skip prompts on demonstrably-safe variants (`rm -rf /tmp/...`),

not to make a block rule "softer."

- **Allow-by-default (deny-list) vs ask-by-default (allow-list).** Most sets

are deny-lists: allow-by-default, enumerate the dangerous ops as block/ask —

you don't want to prompt on every `git status`. Flip to an allow-list — one

broad catch-all `ask` plus an `except` for the safe subset — only when the

tool surface is huge and mostly consequential (a cloud control plane), the

safe subset is small and cleanly identifiable (AWS `get-`/`list-`/`describe-`/

`head-` verbs), and an un-prompted action is costly (spend, data loss, prod

change). Litmus test: enumerate the small side. `watch-aws` is the allow-list

example; `watch-git` is the deny-list example.

## Repo conventions

- One Python file (`scripts/watchdog.py`), one YAML format, one hook config

(`hooks/hooks.json`). Resist refactoring into modules until there's a

concrete reason — the simplicity is a feature.

- Tests are bash scripts that pipe JSON to the engine and assert decisions.

Keep them readable and self-contained — `tests/test-watch-<name>.sh` mirrors

`watches/watch-<name>.yml`.

- Docs are generated from rules YAML by `build/gen-rules-doc.py`. Don't

hand-edit `docs/_site` content for rule references; edit the YAML and run

`just docs`.

## When making changes

- **Rule edits** — Use `/ClaudeWatch:rules` for interactive edits; it

validates and previews. Manual edits to YAML are fine for bulk changes,

but run `just test` before committing.

- **Engine changes** — Update `scripts/watchdog.py` and `tests/test-engine.sh`

in the same change. The engine has a small surface; every behavior should

be exercised by a test.

- **New or changed rule set** — Add/edit `watches/watch-<name>.yml` and

`tests/test-watch-<name>.sh`. No `hooks.json` change needed (auto-discovery).

A rule set is described in hand-maintained indexes that drift

independently — update whichever the change affects:

1. `README.md` — rule-sets table (one row per set)

2. `SPEC.md` `[SH-01]` — enumeration with block/ask coverage prose

The `docs/_site` reference is generated, not hand-maintained — run `just docs`.

A dev-time PostToolUse hook (`.claude/settings.json` →

`.claude/hooks/remind-rules-index.py`) emits this same checklist after any

`watches/watch-*.yml` Write/Edit so it isn't forgotten; it is not part of the

shipped plugin.

- **Spec changes** — Update `SPEC.md` first. If a code change reveals a spec

problem (ambiguity, missing requirement), **note it** and resolve via the

Gap Resolution Protocol (see the spec-driven recipe), don't silently change

the implementation.

## plugin.yml is canonical

`plugin.yml` (repo root) is the single source of truth for the plugin's

descriptor. `.claude-plugin/plugin.json` is **generated** from it by

[`scripts/gen-plugin-json.py`](scripts/gen-plugin-json.py) (`just plugin-json`) — don't hand-edit

`plugin.json`. The `suite:` block also feeds the bridge.ai marketplace SPA.

Run `just generate` after editing `plugin.yml` to refresh the projection, and

`just check` to confirm the committed artifacts still match their source.

**Nothing blocks a stale `plugin.json` from landing on `main`.** The Preview

workflow (`.github/workflows/preview.yml`) runs `shipyard generate --dry-run` on

every pull request, but that command prints the pending projection as a diff and

exits 0 — it reports drift, it does not fail on it. Read that step's output when

a change touches `plugin.yml`, `skills/`, `rules/`, or `hooks/`; a diff there

means someone skipped `just generate`.

What is guaranteed is the *shipped* descriptor: `release.yml` regenerates

`plugin.json` from `plugin.yml` when it cuts a release, so no release can ship a

descriptor that disagrees with its source. The window is `main` between

releases.

## Releasing

A release is cut by **creating a GitHub Release** with tag `v<version>` and the

release notes in the body — that's the only manual step. The next release is

`current + 1` (minor bump for features, patch for fixes).

Publishing the Release triggers `.github/workflows/release.yml`, which:

1. derives the version from the tag (`v0.13.3` → `0.13.3`),

2. runs the test suite — a red gate stops the release before anything lands,

3. writes the version into `plugin.yml`, regenerates `plugin.json`, and

proxies the release notes into a new `CHANGELOG.md` section,

4. commits and pushes that to `main`, and

5. notifies the bridge.ai marketplace to rebuild its catalog via

`repository_dispatch`.

`main` is always the latest released state, and `version` in `plugin.yml`

stays the source of truth — but it's now *written by* the release from the tag

rather than hand-edited. The chris-peterson marketplace tracks ClaudeWatch as

an unpinned git source (default-branch HEAD), so step 4's push to `main` is the

moment consumers see the update; the tag and the marketplace notify are not

what `claude plugin update` reads.

## Known constraints (do not paper over)

- **macOS-style absolute paths** appear in shipped rules (`~/.ssh/...`,

`~/.aws/credentials`). These are user-home patterns, not platform-specific

per se — but the documentation references unix conventions. If

cross-platform support becomes a goal, that's a spec change, not a quick

fix.

- **YAML parser is minimal.** It handles the format ClaudeWatch ships and

nothing more. Multi-line strings, anchors, and `!!tag` constructs are not

supported. If you need them, that's a spec discussion, not a copy-paste of

PyYAML.

## Reading order for new contributors

1. `README.md` — the elevator pitch and install path

2. `SPEC.md` — the contract

3. `scripts/watchdog.py` — the engine (under 250 lines)

4. `watches/watch-git.yml` — the canonical rule-set example

5. `SCHEMA.md` — the YAML rule format reference (for rule authors)

6. `tests/test-watch-git.sh` — the test pattern

7. This file — for "how to think about adding things"