ghostrules 0.1.1__tar.gz → 0.2.1__tar.gz

ghostrules-0.2.1/.ghostrules.lock

@@ -0,0 +1,31 @@
+{
+  "agents": {
+    "claude-code": [
+      {
+        "conditions": [],
+        "lines": "2a3d3f1fb26381e9 e3b0c44298fc1c14 ddabff43c0a4efe5 6aa552cc1598dcb7 be186e6b970ab643 fb78540ec32b52f9 e3b0c44298fc1c14 d393a517d5cbec9f e3b0c44298fc1c14 85b7ae55df076ab0 2f6995b0ecd75c8d e3b0c44298fc1c14 5f2235a1b010f82c 56a4406ad70b7f0a ba2cd86d7e76eff5 a7b723b74ee03fc8 e3b0c44298fc1c14 782729a560418c17 36a8e590ff4c085c e3b0c44298fc1c14 9f4e3cc48918efc0 efeeec23855e4659 2f23b1dcff8841e8 c3abd357eb574eb6 76881ea91e0040bd e3b0c44298fc1c14 36cd3f2bb454f575 ad332335cfaa348c a58865feac87f52b 052081156966d443 5654f9fffd4a2a7a bd0710fd0315ecbb e4d8cec4158bb770 f1b901847390b0ed e3b0c44298fc1c14 966a8946115b377a 5b59b2f749ffabac 9bf96d3c4c385073 43d8bbb16372109c 5226bbb3f5f9e13d add6d744d3ac0c02 3dafca094d79548b 21a3cd5236dfd642 79e12b3b50117933 9cb81024d1184666 f1e7b346d65f35c5 e3b0c44298fc1c14 60ab6be4219694a0 3a1c5dcc5281208a e256f3fb8239bf8c 10d8918d097bebb5 ff85c33a894fab39 10f274c7d25257d2 6216cf539fa87bd8 e3b0c44298fc1c14 7136000e494604c0 aa8d4cf82644ac63 f75f6ee8f0d942eb 1f59b655e6071114 da29957f3e8be475",
+        "load": "always",
+        "path": "CLAUDE.md",
+        "raw_sha256": "c21de91b03da043818a3d8a83418a2e4ce449e58e1e6a5906e7d7c2212ddfca5",
+        "seen_sha256": "c21de91b03da043818a3d8a83418a2e4ce449e58e1e6a5906e7d7c2212ddfca5",
+        "via": []
+      }
+    ],
+    "copilot-cli": [
+      {
+        "conditions": [],
+        "lines": "2a3d3f1fb26381e9 e3b0c44298fc1c14 ddabff43c0a4efe5 6aa552cc1598dcb7 be186e6b970ab643 fb78540ec32b52f9 e3b0c44298fc1c14 d393a517d5cbec9f e3b0c44298fc1c14 85b7ae55df076ab0 2f6995b0ecd75c8d e3b0c44298fc1c14 5f2235a1b010f82c 56a4406ad70b7f0a ba2cd86d7e76eff5 a7b723b74ee03fc8 e3b0c44298fc1c14 782729a560418c17 36a8e590ff4c085c e3b0c44298fc1c14 9f4e3cc48918efc0 efeeec23855e4659 2f23b1dcff8841e8 c3abd357eb574eb6 76881ea91e0040bd e3b0c44298fc1c14 36cd3f2bb454f575 ad332335cfaa348c a58865feac87f52b 052081156966d443 5654f9fffd4a2a7a bd0710fd0315ecbb e4d8cec4158bb770 f1b901847390b0ed e3b0c44298fc1c14 966a8946115b377a 5b59b2f749ffabac 9bf96d3c4c385073 43d8bbb16372109c 5226bbb3f5f9e13d add6d744d3ac0c02 3dafca094d79548b 21a3cd5236dfd642 79e12b3b50117933 9cb81024d1184666 f1e7b346d65f35c5 e3b0c44298fc1c14 60ab6be4219694a0 3a1c5dcc5281208a e256f3fb8239bf8c 10d8918d097bebb5 ff85c33a894fab39 10f274c7d25257d2 6216cf539fa87bd8 e3b0c44298fc1c14 7136000e494604c0 aa8d4cf82644ac63 f75f6ee8f0d942eb 1f59b655e6071114 da29957f3e8be475",
+        "load": "always",
+        "path": "CLAUDE.md",
+        "raw_sha256": "c21de91b03da043818a3d8a83418a2e4ce449e58e1e6a5906e7d7c2212ddfca5",
+        "seen_sha256": "c21de91b03da043818a3d8a83418a2e4ce449e58e1e6a5906e7d7c2212ddfca5",
+        "via": []
+      }
+    ],
+    "cursor": [],
+    "generic": []
+  },
+  "configs": [],
+  "generator": "ghostrules 0.2.1",
+  "lock_version": 1
+}

{ghostrules-0.1.1 → ghostrules-0.2.1}/.github/workflows/ci.yml

@@ -38,3 +38,4 @@ jobs:
         run: |
           ghostrules scan . --no-color
           ghostrules scan . --all-files --no-color
+          ghostrules lock --check --no-color

ghostrules-0.2.1/.github/workflows/self-test.yml

@@ -0,0 +1,153 @@
+name: Self-test
+
+# Runs the action from this very checkout against the demo repositories.
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  action:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Poisoned demo with fail-on none (must pass, must report findings)
+        id: poisoned
+        uses: ./
+        with:
+          path: examples/poisoned-repo
+          fail-on: none
+          upload-sarif: "false"
+
+      - name: SARIF must contain results, led by the hidden instruction
+        run: |
+          python - <<'PY'
+          import json
+          run = json.load(open("ghostrules.sarif"))["runs"][0]
+          results = run["results"]
+          assert len(results) > 10, f"expected many results, got {len(results)}"
+          ids = {r["ruleId"] for r in results}
+          assert {"GR001", "GR012", "GR101"} <= ids, ids
+          assert results[0]["ruleId"] == "GR001", results[0]["ruleId"]
+          assert run["tool"]["driver"]["rules"], "rules missing"
+          print(f"ok: {len(results)} results")
+          PY
+
+      - name: The exit-code output is 0
+        env:
+          EXIT_CODE: ${{ steps.poisoned.outputs.exit-code }}
+        run: test "$EXIT_CODE" = "0"
+
+      - name: Poisoned demo with the default fail-on (must fail the step)
+        id: gate
+        uses: ./
+        continue-on-error: true
+        with:
+          path: examples/poisoned-repo
+          upload-sarif: "false"
+
+      - name: The gate must have failed
+        env:
+          OUTCOME: ${{ steps.gate.outcome }}
+          EXIT_CODE: ${{ steps.gate.outputs.exit-code }}
+        run: |
+          test "$OUTCOME" = "failure"
+          test "$EXIT_CODE" = "1"
+
+      - name: Clean demo (must pass with no results)
+        uses: ./
+        with:
+          path: examples/clean-repo
+          upload-sarif: "false"
+
+      - name: SARIF must be empty
+        run: |
+          python - <<'PY'
+          import json
+          results = json.load(open("ghostrules.sarif"))["runs"][0]["results"]
+          assert results == [], results
+          PY
+
+  import-chain:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Import-chain demo, following imports (default)
+        uses: ./
+        with:
+          path: examples/import-chain-repo
+          fail-on: none
+          upload-sarif: "false"
+
+      - name: SARIF must carry the hidden payload with the import chain that reaches it
+        run: |
+          python - <<'PY'
+          import json
+          results = json.load(open("ghostrules.sarif"))["runs"][0]["results"]
+          ids = {r["ruleId"] for r in results}
+          assert {"GR001", "GR020", "GR021"} <= ids, ids
+          hidden = next(r for r in results if r["ruleId"] == "GR001")
+          chain = [l["physicalLocation"]["artifactLocation"]["uri"] for l in hidden["relatedLocations"]]
+          assert chain == ["CLAUDE.md", "docs/style.md"], chain
+          assert hidden["locations"][0]["physicalLocation"]["artifactLocation"]["uri"] == "shared/team-rules.md"
+          assert "reached-via-import" in hidden["properties"]["tags"]
+          print(f"ok: {len(results)} results")
+          PY
+
+      - name: Import-chain demo with follow-imports off (a 0.1-style scan finds nothing)
+        uses: ./
+        with:
+          path: examples/import-chain-repo
+          follow-imports: "false"
+          upload-sarif: "false"
+
+      - name: SARIF must be empty
+        run: |
+          python - <<'PY'
+          import json
+          results = json.load(open("ghostrules.sarif"))["runs"][0]["results"]
+          assert results == [], results
+          PY
+
+      - name: Lock a copy of the demo, then make a pull-request-like change to another copy
+        run: |
+          python scripts/make_demo.py --lock-scenario "$RUNNER_TEMP/acme"
+          ghostrules lock --root "$RUNNER_TEMP/acme/base"
+          cp "$RUNNER_TEMP/acme/base/.ghostrules.lock" "$RUNNER_TEMP/acme/pr/"
+
+      - name: Lock check on the unchanged repository (must pass)
+        id: unchanged
+        uses: ./
+        with:
+          path: ${{ runner.temp }}/acme/base
+          fail-on: none
+          lock-check: "true"
+          upload-sarif: "false"
+
+      - name: The unchanged lock exit code is 0
+        env:
+          LOCK_EXIT_CODE: ${{ steps.unchanged.outputs.lock-exit-code }}
+        run: test "$LOCK_EXIT_CODE" = "0"
+
+      - name: Lock check after the pull request (must fail the step)
+        id: changed
+        uses: ./
+        continue-on-error: true
+        with:
+          path: ${{ runner.temp }}/acme/pr
+          fail-on: none
+          lock-check: "true"
+          upload-sarif: "false"
+
+      - name: The changed lock must have failed with exit code 1
+        env:
+          OUTCOME: ${{ steps.changed.outcome }}
+          LOCK_EXIT_CODE: ${{ steps.changed.outputs.lock-exit-code }}
+        run: |
+          test "$OUTCOME" = "failure"
+          test "$LOCK_EXIT_CODE" = "1"

ghostrules-0.2.1/CHANGELOG.md

@@ -0,0 +1,150 @@
+# Changelog
+
+All notable changes to this project are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.2.1] - 2026-10-28
+
+Precision release. A scan of 12 popular public repositories with 0.2.0 found no critical issue,
+but every `high` finding was a false positive, and `context` was wrong for the most common real
+setup. On those repositories 0.2.0 reported 9 high, 18 medium and 8 low findings; 0.2.1 reports
+2 medium and 2 low, with no high, no critical and no GR025.
+
+### Added
+- `ghostrules context --format json` entries carry `alias_of` (and `link_problem`) when a symlink is
+  involved; lock entries carry `link` for an alias. Both keys are omitted otherwise.
+- `ghostrules.rules.directive.classify`: the helper that tells directive, descriptive and example
+  text apart (used by GR011, GR014 and GR016).
+
+### Fixed
+- A symbolic link whose final target is a regular file inside the repository is now an **alias**:
+  `CLAUDE.md -> AGENTS.md` (the setup Claude Code documents) is loaded under the link's name,
+  `context` shows `CLAUDE.md → AGENTS.md (symlink)` and the `AGENTS.md` entry as already read, the
+  content is scanned once (findings say `via CLAUDE.md (symlink)`), and `lock` records the link and
+  its target. Chains of up to 8 links and in-repository directory links work the same way. Nothing
+  is opened before the resolved path is known to be inside the repository.
+  GR025 now fires only for links that leave the repository (`high`) or are broken, cyclic or too
+  long (`low`), instead of one `medium` per link, and adds an `info` note for a link checked out as
+  a text file (Windows with `core.symlinks=false`).
+- GR022 no longer reports npm scopes and mentions (`@n8n/design-system`, `@cline/llms`, `@types/node`)
+  as imports that do not load. It reports a token only if it has a file extension, starts with `./`,
+  `../`, `~/` or `/`, or its first directory exists next to the importing file.
+- GR011, GR014 and GR016 tell instructions from descriptions and examples. A match in prose that
+  describes something ("The scripts read `~/.npmrc`", "The harness runs Claude with
+  `bypassPermissions`") is at most `medium`; in a fenced block, in quotes or after "e.g.", "such
+  as", "a skill that ..." it is at most `low`; imperative text and decoded hidden text keep their
+  severity. A lowered finding says why.
+  - GR011: "do not tell the user to/which/what/how ..." is no longer concealment.
+  - GR014: the verb must govern the path (same clause, six words at most) and template files
+    (`.env.example`, `*.example`, `.env.ai-surfaces.example`) never fire.
+- GR012: `curl ... | python -c`, `| python -m`, `| python script.py`, `| sh -c '...'` use stdin as
+  data and are no longer reported; `| python`, `| python -` and `| sh` still are. The Claude Code
+  installer (`https://claude.ai/install.sh`) is a known installer. GR105 and GR107 share these
+  patterns and follow.
+
+### Changed
+- README: the new tagline is the only one (the old one opens the first paragraph), the import-chain
+  GIF comes first and the hidden-Unicode GIF sits further down, both by absolute URL.
+- The original `SPEC.md`, `PLAN.md` and the per-version design documents moved to `docs/design/`
+  (design history, not kept up to date). `RULES.md`, `AGENT_MODELS.md` and `DECISIONS.md` stay in
+  `docs/`.
+
+## [0.2.0] - 2026-10-28
+
+Know exactly what your agent reads: `ghostrules` now models how each agent loads its instructions,
+scans exactly that, shows it, and pins it.
+
+### Added
+- GitHub Action inputs `follow-imports` (default `true`) and `lock-check` (default `false`). With
+  `lock-check` the action runs `ghostrules lock --check`, puts the differences in the job summary
+  under "What your agents read changed in this PR" and fails the job if there are any; new output
+  `lock-exit-code`.
+- Config keys `follow_imports`, `agents` and `lockfile`.
+- `python scripts/make_demo.py --lock-scenario DEST` and the tapes `demo/imports.tape` and
+  `demo/lock.tape` for the 0.2 GIFs.
+- `ghostrules lock`: writes `.ghostrules.lock`, a deterministic record (sorted keys, no timestamps,
+  CRLF-normalised hashes) of every file in each modelled agent's context, how it is reached, and
+  the text the agent actually receives, plus a hash of every MCP and agent settings file.
+  `lock --check` recomputes it and shows what changed (added, changed, removed, and changes that
+  only touch text an agent strips), with invisible characters revealed; exit 0 up to date, 1
+  changed, 2 error. `--format text|markdown|json`, `--update`, `--lockfile`; config key `lockfile`.
+- `ghostrules context [TARGET]`: shows what an agent reads when it works on a file (the files it
+  loads at session start, the rules its `paths`/`globs` select, the directories that load on
+  demand, the imports it follows and the files it skips, with the reason) and scans exactly that.
+  Output as a tree, JSON or Markdown; `--agent`, `--cwd`, `--root`, `--show-text`, `--no-scan`,
+  `--home`, `--fail-on`.
+- `examples/import-chain-repo`: a CLAUDE.md that looks clean and reaches a hidden payload through two
+  imports, plus a `.env` import and one outside the repository.
+- `scan` follows `@path` imports by default: files an instruction file imports are scanned as
+  instructions, and their findings carry the import chain (`via`), the agents that load them and the
+  tag `reached-via-import`. `--no-follow-imports` (or `follow_imports = false`) turns it off.
+- Rules GR020 (external import), GR021 (sensitive file imported), GR022 (import that silently does
+  not load), GR023 (import cycle), GR024 (tag for payloads reached through an import) and GR025
+  (symlinked instruction source).
+- The files each modelled agent loads (including `.claude/rules/**`) are scanned even when the
+  discovery globs do not list them. New config keys `follow_imports` and `agents`.
+- JSON findings gain optional `via`, `agents` and `tags`; SARIF results gain `relatedLocations` for
+  the chain and `properties.agents`/`tags`; the table and Markdown reports show the chain.
+
+- `docs/AGENT_MODELS.md`: how each agent loads its instructions, with the documentation it is based on
+  and what is still unverified; `CONTRIBUTING.md` explains how to add a model.
+- `ghostrules` locks its own `CLAUDE.md` (`.ghostrules.lock`), checked in CI.
+
+### Changed
+- GR005 is agent-aware: it says which agents see a hidden comment. Claude Code strips block-level
+  comments from CLAUDE.md files, so the finding is info when no configured agent sees the comment.
+
+## [0.1.1] - 2026-10-27
+
+### Changed
+- GR012 (remote code execution pattern) now sets its severity from context instead of reporting
+  every `curl ... | sh` as critical. A well-known installer in a code block is low, in prose
+  medium; an unknown domain is high in a code block and critical in prose. Plain `http://`, IP
+  literals, non-default ports, collector domains, opaque payloads (`base64 -d | sh`,
+  `powershell -enc`) and text hidden by invisible characters stay critical. This stops the default
+  `--fail-on high` from failing on real repositories that document `uv` or `rustup`.
+  GR105 and GR107 (MCP server commands and hooks) are unchanged.
+
+### Added
+- Built-in list of well-known installers (uv/ruff, rustup, Bun, Deno, pnpm, Poetry, Homebrew, nvm,
+  SDKMAN, Docker, Ollama, Volta), matched on the exact host and optional path prefix, and
+  `ghostrules rules --installers` to print it.
+- `trust_known_installers` option (default `true`); `false` restores the 0.1.0 behaviour.
+- Inline code span awareness for GR012 (`ScanTarget.code_span_at`).
+
+## [0.1.0] - 2026-10-27
+
+First release.
+
+### Added
+- Scanner for the files AI coding agents read and obey (`AGENTS.md`, `CLAUDE.md`, `.cursorrules`,
+  Copilot instructions, skills, MCP configs, agent settings and more), with `--home` for
+  user-level configs and `--all-files` for hidden Unicode anywhere in a tree.
+- 21 rules. Hidden content: Unicode tag characters (GR001), bidirectional controls (GR002),
+  zero-width characters (GR003), variation-selector steganography (GR004), hidden HTML comments
+  (GR005), mixed-script homoglyphs (GR006). Malicious instructions, English and Spanish: instruction
+  override (GR010), concealment (GR011), remote code execution (GR012), data exfiltration (GR013),
+  sensitive file access (GR014), encoded payloads (GR015), safety bypass (GR016). Configuration:
+  hardcoded secrets (GR101), unpinned packages (GR102), insecure transport (GR103), broad
+  filesystem scope (GR104), shell wrappers (GR105), dangerous Docker options (GR106),
+  over-permissive agent settings (GR107), auto-trusted MCP servers (GR108).
+- Hidden text decoded by GR001, GR004 and GR015 is re-scanned by GR010-GR016 and reported with
+  one more level of severity.
+- CLI: `scan` (the default command), `reveal`, `clean`, `rules`, `version`. Reports as a table
+  grouped by file with the decoded hidden text highlighted, JSON, SARIF 2.1.0 (validated against the
+  official schema) and Markdown. Exit codes: 0 clean, 1 findings at or above `--fail-on`, 2 error.
+- Configuration through `.ghostrules.toml` or `[tool.ghostrules]`, and inline `ghostrules-ignore`
+  suppressions (never for GR001, GR002 or text found inside hidden characters).
+- GitHub Action (SARIF upload to code scanning, job summary, `fail-on` gate), pre-commit hook, CI
+  with a smoke test and a self-scan, and a tag-triggered release workflow using PyPI Trusted
+  Publishing.
+- Demo repositories `examples/poisoned-repo` (every rule fires) and `examples/clean-repo` (no
+  findings), and `demo/demo.tape` to record the README GIF.
+
+### Security
+- Read-only: nothing found in a scanned file is executed, imported, downloaded or sent anywhere,
+  and the tool makes no network requests. Symbolic links are not followed.
+- Secrets are never printed: every finding, warning and error passes through one masking step
+  (`ghp_****…a1b2`), and a test fails if a secret appears in any report format.

{ghostrules-0.1.1 → ghostrules-0.2.1}/CLAUDE.md

@@ -11,9 +11,9 @@ It is a **defensive** security tool. It only reads files and reports findings. I
 anything it finds, never makes network requests, and never phones home.
 
 ## Source-of-truth documents (read before coding)
-- `docs/SPEC.md` — features, CLI, file targets, output formats, config. **The contract.**
+- `docs/design/SPEC.md` — features, CLI, file targets, output formats, config. **The contract.**
 - `docs/RULES.md` — every detection rule: ID, severity, logic, true/false positive examples.
-- `docs/PLAN.md` — build order, phase by phase, with acceptance criteria.
+- `docs/design/PLAN.md` — build order, phase by phase, with acceptance criteria.
 
 If something in the code disagrees with these docs, the docs win unless the user says otherwise.
 If a doc is ambiguous, pick the simplest reasonable option and note it in `docs/DECISIONS.md`.
@@ -54,7 +54,7 @@ ghostrules scan examples/clean-repo      # must report zero findings
 - Never add code that executes, downloads or evaluates scanned content.
 
 ## Workflow
-- Work phase by phase following `docs/PLAN.md`. After each phase: run tests + ruff, then
+- Work phase by phase following `docs/design/PLAN.md`. After each phase: run tests + ruff, then
   stop and summarize what was done and what is next.
 - Commit after each phase with a conventional commit message (`feat:`, `test:`, `docs:`…).
 - Keep the README in English and keep it updated when CLI flags change.

{ghostrules-0.1.1 → ghostrules-0.2.1}/CONTRIBUTING.md

@@ -17,9 +17,12 @@ ghostrules scan examples/poisoned-repo   # must find issues, exit code 1
 ghostrules scan examples/clean-repo      # must report nothing, exit code 0
 ```
 
-The documents in `docs/` are the contract: `SPEC.md` (features), `RULES.md` (every rule) and
-`DECISIONS.md` (choices made where they were ambiguous). If code and docs disagree, fix one of
-them in the same pull request.
+The documents in `docs/` are the contract: `RULES.md` (every rule), `AGENT_MODELS.md` (how each
+agent loads its instructions, with sources) and `DECISIONS.md` (choices made where they were
+ambiguous). `docs/design/` is the **design history**: the original `SPEC.md` and `PLAN.md` and the
+per-version design documents (`v0.1.1/`, `v0.2/`). They explain why things are the way they are and
+are not kept up to date. If code and the contract documents disagree, fix one of them in the same
+pull request.
 
 ## Add a rule in three steps
 
@@ -46,7 +49,8 @@ them in the same pull request.
 
 2. **Test it.** Add at least one positive and one negative test (see `tests/test_rules_*.py`). Add
    a case to `scripts/make_demo.py` so `examples/poisoned-repo` triggers the rule (a test fails
-   if any rule does not fire there) and make sure `examples/clean-repo` still reports nothing.
+   if a `GR00x`, `GR01x` or `GR1xx` rule does not fire there; the import rules `GR02x` are tested
+   in `tests/test_scan_imports.py`) and make sure `examples/clean-repo` still reports nothing.
    Fixtures with invisible characters are generated by `scripts/make_fixtures.py`.
 
 3. **Document it.** Describe the rule in `docs/RULES.md` (ID, severity, logic, true and false
@@ -58,6 +62,32 @@ them in the same pull request.
    python scripts/gen_rules_table.py --write
    ```
 
+## Add an agent model
+
+`ghostrules context` and `ghostrules lock` need to know how an agent loads its instructions. A
+model is one module, one section of `docs/AGENT_MODELS.md` and its tests:
+
+1. **Write down what the agent's documentation says** in a new section of `docs/AGENT_MODELS.md`:
+   which files it reads and in what order, which are conditional or loaded on demand, whether it
+   follows `@` imports (relative to what, how deep), what it strips before the model sees the text,
+   and the page and date you checked. Anything the documentation does not state is marked
+   **UNVERIFIED** and modelled conservatively (a file the agent might read is included). Model only
+   what is written there.
+2. **Implement it** in `src/ghostrules/agents/<name>.py` with a `build(repo, *, cwd, target, home)`
+   method that returns a `ContextGraph`. Use the `Builder` in `agents/base.py`: it reads files
+   safely (never through a symlink), applies your text transforms (`render_*`), follows imports
+   with the `ImportPolicy` you pass, hashes the result and records the edges. Register the model in
+   `agents/__init__.py` (`AGENT_NAMES`, `get_model`) and in `config.AGENT_NAMES`. Use
+   `globs.matches_any` for `paths`/`globs`/`applyTo` and `markdown_utils.parse_frontmatter` for
+   front matter.
+3. **Test it with a fake repository** built in `tmp_path` (see `tests/test_agents_claude.py`):
+   given the tree, the working directory and the target, the ordered entries, their `load`
+   states, `matches` and `unverified` flags must be what the documentation implies. Add the
+   precedence and depth cases that apply to the agent.
+4. **Say what you could not model** (user-level or organisation settings, environment variables)
+   in `ContextGraph.notes`, and add a line to `CHANGELOG.md` and a decision to
+   `docs/DECISIONS.md` for every judgement call.
+
 ## Rules of the repository
 
 - **Defanged only.** Fixtures, demos and tests use `attacker.example`, `exfil.example`,
@@ -77,4 +107,6 @@ them in the same pull request.
 - [ ] positive and negative tests for every new or changed detection
 - [ ] `examples/poisoned-repo` still triggers every rule; `examples/clean-repo` is still clean
 - [ ] `docs/RULES.md`, `docs/DECISIONS.md`, `CHANGELOG.md` and the README table are updated
+- [ ] for an agent model: `docs/AGENT_MODELS.md` cites the documentation and the date, and the
+      unverified parts are marked
 - [ ] nothing real in the fixtures: no secrets, domains or payloads that work